v3: mobile login, registration and verification on javaabu/auth v3

.gitattributes

@@ -1,11 +1,18 @@
 # Path-based git attributes
 # https://www.kernel.org/pub/software/scm/git/docs/gitattributes.html
 
-# Ignore all test and documentation with "export-ignore".
+# Left out of the Composer dist. docs/, llms.txt and resources/ ship: llms.txt and
+# the Boost skill point at docs/, and javaabu/manifest serves resources/js.
 /.gitattributes     export-ignore
 /.gitignore         export-ignore
-/.travis.yml        export-ignore
+/.editorconfig      export-ignore
+/.github            export-ignore
 /phpunit.xml.dist   export-ignore
-/.scrutinizer.yml   export-ignore
+/pint.json          export-ignore
 /tests              export-ignore
-/.editorconfig      export-ignore
+/AGENTS.md          export-ignore
+/CLAUDE.md          export-ignore
+/package.json       export-ignore
+/pnpm-lock.yaml     export-ignore
+/tsconfig.json      export-ignore
+/vitest.config.ts   export-ignore

.github/workflows/tests.yml

@@ -0,0 +1,178 @@
+name: tests
+
+on:
+    pull_request:
+    push:
+        branches:
+            - main
+            - next-gen
+    workflow_dispatch:
+
+# The unreleased javaabu/* dependencies come from VCS repositories; the job's own
+# token keeps Composer within GitHub's API limits
+env:
+    COMPOSER_AUTH: '{"github-oauth": {"github.com": "${{ github.token }}"}}'
+
+jobs:
+    pint:
+        runs-on: ubuntu-latest
+
+        name: Pint
+
+        steps:
+            -   name: Checkout code
+                uses: actions/checkout@v5
+
+            -   name: Setup PHP
+                uses: shivammathur/setup-php@v2
+                with:
+                    php-version: 8.4
+                    coverage: none
+
+            -   name: Install dependencies
+                run: composer update --prefer-dist --no-interaction --no-progress
+
+            -   name: Check code style
+                run: vendor/bin/pint --test
+
+    js:
+        runs-on: ubuntu-latest
+
+        name: React pages (typecheck, tests)
+
+        steps:
+            -   name: Checkout code
+                uses: actions/checkout@v5
+
+            # The pages import javaabu/auth's and javaabu/stencil's React code from vendor/
+            -   name: Setup PHP
+                uses: shivammathur/setup-php@v2
+                with:
+                    php-version: 8.4
+                    coverage: none
+
+            -   name: Install Composer dependencies
+                run: composer update --prefer-dist --no-interaction --no-progress
+
+            -   name: Setup pnpm
+                uses: pnpm/action-setup@v4
+
+            -   name: Setup Node
+                uses: actions/setup-node@v5
+                with:
+                    node-version: 22
+                    package-manager-cache: false
+
+            # The default store is inside a node_modules folder, which breaks the declaration
+            # build of @javaabu/forms (installed from git and built on install): Javaabu/react-forms#20
+            -   name: Install dependencies
+                run: pnpm install --frozen-lockfile --store-dir "$RUNNER_TEMP/pnpm-store"
+
+            -   name: Typecheck
+                run: pnpm typecheck
+
+            -   name: Test
+                run: pnpm test
+
+    dependencies:
+        runs-on: ubuntu-latest
+
+        name: No javaabu/helpers or javaabu/settings v1
+
+        steps:
+            -   name: Checkout code
+                uses: actions/checkout@v5
+
+            -   name: Setup PHP
+                uses: shivammathur/setup-php@v2
+                with:
+                    php-version: 8.4
+                    coverage: none
+
+            -   name: Install dependencies
+                run: composer update --prefer-dist --no-interaction --no-progress --no-dev
+
+            # javaabu/helpers pins javaabu/settings ^1, which breaks installs next to settings v2
+            -   name: Check the production dependency tree
+                run: |
+                    composer show --tree --no-dev > tree.txt
+                    if grep -E 'javaabu/helpers' tree.txt; then echo "javaabu/helpers is in the dependency tree"; exit 1; fi
+                    if grep -E 'javaabu/settings +\^?1' tree.txt; then echo "javaabu/settings v1 is in the dependency tree"; exit 1; fi
+                    if composer show --no-dev javaabu/settings 2>/dev/null | grep -E '^versions *: .*\b1\.'; then echo "javaabu/settings v1 is installed"; exit 1; fi
+                    echo "OK"
+
+    without-optional:
+        runs-on: ubuntu-latest
+
+        name: Without the optional packages
+
+        steps:
+            -   name: Checkout code
+                uses: actions/checkout@v5
+
+            -   name: Setup PHP
+                uses: shivammathur/setup-php@v2
+                with:
+                    php-version: 8.4
+                    extensions: curl, mbstring, zip, pdo, sqlite, pdo_sqlite
+                    coverage: none
+
+            -   name: Install dependencies without Inertia, Sanctum and Passport
+                run: |
+                    composer remove --dev inertiajs/inertia-laravel laravel/sanctum laravel/passport --no-interaction --no-update
+                    composer update --prefer-dist --no-interaction --no-progress
+
+            -   name: Execute tests
+                run: vendor/bin/phpunit --exclude-group optional
+
+    tests:
+        runs-on: ubuntu-latest
+
+        strategy:
+            fail-fast: false
+            matrix:
+                php: [ 8.4, 8.5 ]
+                laravel: [ 12.*, 13.* ]
+                stability: [ prefer-lowest, prefer-stable ]
+                include:
+                    -   laravel: 12.*
+                        testbench: 10.*
+                    -   laravel: 13.*
+                        testbench: 11.*
+
+        name: P${{ matrix.php }} - L${{ matrix.laravel }} - ${{ matrix.stability }}
+
+        env:
+            COVERAGE: ${{ matrix.php == '8.4' && matrix.laravel == '13.*' && matrix.stability == 'prefer-stable' }}
+
+        steps:
+            -   name: Checkout code
+                uses: actions/checkout@v5
+
+            -   name: Setup PHP
+                uses: shivammathur/setup-php@v2
+                with:
+                    php-version: ${{ matrix.php }}
+                    extensions: curl, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, iconv
+                    coverage: ${{ env.COVERAGE == 'true' && 'pcov' || 'none' }}
+
+            -   name: Install dependencies
+                run: |
+                    composer require "laravel/framework:${{ matrix.laravel }}" "orchestra/testbench:${{ matrix.testbench }}" --no-interaction --no-update
+                    composer update --${{ matrix.stability }} --prefer-dist --no-interaction --no-progress
+
+            -   name: Execute tests
+                if: env.COVERAGE != 'true'
+                run: vendor/bin/phpunit
+
+            -   name: Execute tests with coverage
+                if: env.COVERAGE == 'true'
+                run: vendor/bin/phpunit --coverage-clover build/coverage.xml
+
+            -   name: Upload coverage to Codecov
+                if: env.COVERAGE == 'true'
+                uses: codecov/codecov-action@v5
+                with:
+                    files: build/coverage.xml
+                    fail_ci_if_error: false
+                    token: ${{ secrets.CODECOV_TOKEN }}

.gitignore

@@ -3,6 +3,6 @@ composer.lock
 vendor
 coverage
 .phpunit.result.cache
-.php-cs-fixer.cache
 .idea
-clover.xml
+node_modules
+.phpunit.cache

AGENTS.md

@@ -0,0 +1,52 @@
+# mobile-verification: notes for AI coding agents
+
+`javaabu/mobile-verification` v3 adds mobile number login, registration and verification with SMS codes to javaabu/auth v3 user types. It plugs in through javaabu/auth's `LoginMethod` and `StartAuthenticatedSession`, so treat those (and `UserTypes`, `PageData`, `ApiTokens`, `AccountLayout`) as the contract with auth; if auth lacks something, open a `cross-package` issue on n4ff4h/auth instead of working around it.
+
+## Layout
+
+| Path | What |
+| --- | --- |
+| `src/MobileVerification.php` | Static helpers: config, normalizing, finding numbers per user type, `enableFor()` |
+| `src/Auth/MobileLoginMethod.php` | The javaabu/auth login method; registers the login and registration routes |
+| `src/Routing` | `Route::mobileNumberRoutes()`, `Route::mobileApiRoutes()`, `Route::mobileNumberActions()` |
+| `src/Http/Controllers` | `VerificationFlowController` (the shared send/verify/confirm/resend steps) and the login, registration and account flows; the API and admin actions controllers |
+| `src/Actions` | `SendVerificationCode`, `VerifyVerificationCode`, `AuthenticateMobileNumber` (API/Passport), `CreateUserFromMobileNumber` |
+| `src/Models/MobileNumber.php`, `src/Concerns/InteractsWithMobileNumbers.php` | The number (code, expiry, attempts, lock) and the user trait |
+| `src/Support` | `PendingVerification` (session state per type and purpose), `Strings` (React strings), the code generator, the number format validator |
+| `src/Passport/MobileGrant.php` | The optional `mobile` grant |
+| `src/Policies/MobileNumberPolicy.php` | Admin abilities and permission names |
+| `src/Stencil/MobileRegistrationForm.php` | The registration details form |
+| `src/Views/ViewRenderer.php` | Blade (`mobile-verification::login`) or Inertia (`mobile-verification::Login`) |
+| `resources/views`, `resources/js` | Blade pages (javaabu/forms v2) and React pages (`@javaabu/forms`, imports `@javaabu/auth` and `@javaabu/stencil` from vendor/) |
+| `lang/en.json`, `lang/dv.json` | English keys and Dhivehi |
+| `docs`, `llms.txt`, `resources/boost` | Docusaurus pages, the index for AI assistants, the Boost guideline and skill |
+| `tests` | Testbench tests with two types: `user` (`web`, no route prefix, registration on) and `admin` (`web_admin`, `/admin`, registration off). Inertia, Sanctum and Passport tests are in the `optional` group. Seconds are frozen in `TestCase`. `tests/js` are Vitest tests |
+
+## Rules
+
+- Follow Javaabu codestyle ([boost-javaabu-guidelines](https://github.com/Javaabu/boost-javaabu-guidelines)): snake_case variables and properties, camelCase methods, early returns, `#[Test]` with snake_case names. Pint enforces formatting.
+- Nothing may assume the `web` guard, `App\Models\User` or global route names. Resolve the type with `UserTypes::fromRequest()`, load users through `MobileVerification::userFor()` (the type's guard provider), and test both test types, including that one type's number doesn't log in another.
+- Codes are security-sensitive: keep them hashed, single-use, expiring, counted and locked, and test the failure cases (wrong, expired, superseded, locked, rate limited).
+- Inertia, Sanctum and Passport are optional: feature-detect them, never `use` their classes in code that always runs, keep CI's "Without the optional packages" job green.
+- Every page exists in Blade and React with the same props. Logical utilities only (a test rejects `ml-`, `text-left`, …); numbers and codes are `dir="ltr"`.
+- Every user-facing string goes through `__()` with an English key, a Dhivehi line in `lang/dv.json` and an English line in `lang/en.json` (`tests/Unit/TranslationsTest.php` checks). React strings go in `Support\Strings`; regenerate `tests/js/strings.dv.json` after changing them:
+
+  ```bash
+  php -r 'require "vendor/autoload.php"; $dv = json_decode(file_get_contents("lang/dv.json"), true); $auth = json_decode(file_get_contents("vendor/javaabu/auth/lang/dv.json"), true); $out = []; foreach (Javaabu\MobileVerification\Support\Strings::ALL as $k => $en) { $out[$k] = $dv[$en] ?? $auth[$en] ?? $en; } foreach (["account" => "Account", "profile" => "Profile", "security" => "Security", "log_out" => "Log out"] as $k => $en) { $out[$k] = $auth[$en] ?? $en; } ksort($out); file_put_contents("tests/js/strings.dv.json", json_encode($out, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) . "\n");'
+  ```
+
+- List uncertain Dhivehi in `docs/advanced-usage/translations.md`. Use Thaana in tests of user-facing behaviour.
+- Never depend on `javaabu/helpers` or `javaabu/settings` ^1 (CI checks the production tree).
+- Every change needs tests, docs (linked from `llms.txt`), the Boost skill if it changes how the package is used, and a line in `CHANGELOG.md`.
+- Work on the `next-gen` branch; don't commit to `main`.
+
+## Commands
+
+```bash
+composer install
+composer lint      # vendor/bin/pint --test
+composer format    # vendor/bin/pint
+composer test      # vendor/bin/phpunit
+pnpm install       # the React pages' dev tooling (after composer install)
+pnpm check         # typecheck and Vitest
+```