Add the archetype command line

Archetype has only ever been reachable from PHP. This adds a command line
over the same engine — 26 operations, each an Artisan command under
`archetype:`, plus an `archetype` binary that finds the application and
forwards to it. Nothing here reimplements AST rewriting; every mutation
goes through the existing PHPFile/LaravelFile endpoints.

Three properties hold for every operation that writes, because a caller
that cannot rely on them has to read the file back and loses the point of
asking:

  - the file is re-rendered and compared, so a change that matched nothing
    exits non-zero instead of reporting a success that wrote nothing;
  - the answer carries a diff of what changed;
  - a change already applied reports SKIP, which makes them safe to repeat.

Every operation takes a single target — a path, a class name, or a
directory, where a directory means every class beneath it, narrowed with
--extends / --implements / --uses-trait / --matching. Every operation
takes --json; every mutation takes --dry-run and --no-diff.

Two operations exist because the PHP API cannot express them:
set-array-key edits the array a method returns, which is where rules(),
toArray() and casts() keep their contents, and set-casts writes to
whichever casting mechanism a model already uses rather than adding a
second one beside the first. add-relation covers all eleven Eloquent
relation types with pivot tables, explicit keys and withPivot.

Alongside, a few endpoints now reach constructs they previously matched
but silently ignored: className(), classConstant(), useTrait() and
property() work on any class-like, and implements() on classes and enums.
Before this, adding an interface to an enum reported success and wrote
nothing. The PSR-2 printer also prints `function name(): Type` rather
than `function name() : Type`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AjUMv5rFTVJMr6F1J7bx7x

Author: ajthinking

CHANGELOG.md

@@ -6,6 +6,57 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-08-29
+
+Adds a command line to Archetype. Every existing PHP API is untouched; a handful
+of endpoints now reach constructs they previously matched but silently ignored.
+
+### Added
+
+- **A command line.** 26 operations, each an Artisan command under `archetype:`,
+  plus an `archetype` binary that finds the application and forwards to it. Run
+  `archetype` with no arguments for the list, or see the
+  [reference](docs.md#command-line-reference).
+
+  Reading: `inspect`, `show`, `find`, `errors`.
+  Writing: `make`, `set-property`, `add-to-property`, `empty-property`,
+  `remove-property`, `set-casts`, `add-relation`, `set-array-key`, `add-use`,
+  `remove-use`, `add-trait`, `add-implements`, `set-extends`, `set-namespace`,
+  `rename-class`, `set-const`, `remove-const`, `add-case`, `add-method`,
+  `replace-method`, `remove-method`, `apply`.
+
+- Every operation takes a single target, which is a path, a class name, or a
+  directory — where a directory means every class beneath it, narrowed with
+  `--extends`, `--implements`, `--uses-trait` or `--matching`.
+- Every operation takes `--json`.
+- Every mutation re-renders the file and compares before reporting. One that
+  matched nothing exits non-zero rather than reporting a success that wrote
+  nothing; one whose change is already present reports `SKIP`, which makes the
+  operations safe to repeat.
+- Every mutation answers with a diff of what it changed, and takes `--dry-run`
+  to show that diff without writing.
+- `archetype apply` runs a script of operations in one invocation, reading a file
+  or standard input.
+- `set-casts` writes to whichever casting mechanism a model already uses — the
+  `casts()` method Laravel 11 generates, or the `$casts` property — instead of
+  adding a second one beside the first.
+- `set-array-key` edits the array a method returns, which is where `rules()`,
+  `toArray()`, `casts()` and `definition()` keep their contents.
+- `add-relation` covers all eleven Eloquent relation types, with pivot tables,
+  explicit keys, `withPivot`, `withTimestamps` and a custom pivot model.
+- `enum()` and `enumCase()` query methods on the `ASTQueryBuilder`.
+- `php artisan archetype:errors` takes `--json`.
+
+### Changed
+
+- `className()`, `classConstant()`, `useTrait()` and `property()` now match any
+  class-like declaration rather than only `class`, so they work on enums,
+  interfaces and traits. `implements()` matches classes and enums. Previously
+  these silently did nothing on anything but a class.
+- The PSR-2 pretty printer prints `function name(): Type` rather than
+  `function name() : Type`. Only newly printed declarations are affected;
+  untouched code keeps its own formatting.
+
 ## [2.0.1] - 2026-08-25
 
 Maintenance only. No API changes, and nothing here can break existing usage.
@@ -67,7 +118,8 @@ Last release of the 1.x line, which requires `nikic/php-parser` ^4.11.
 Pest 3 and newer. If Composer refuses to resolve `ajthinking/archetype`, upgrade
 to 2.x.
 
-[Unreleased]: https://github.com/ajthinking/archetype/compare/v2.0.1...HEAD
+[Unreleased]: https://github.com/ajthinking/archetype/compare/v2.1.0...HEAD
+[2.1.0]: https://github.com/ajthinking/archetype/compare/v2.0.1...v2.1.0
 [2.0.1]: https://github.com/ajthinking/archetype/compare/v2.0.0...v2.0.1
 [2.0.0]: https://github.com/ajthinking/archetype/compare/v1.1.5...v2.0.0
 [1.1.5]: https://github.com/ajthinking/archetype/releases/tag/v1.1.5

bin/archetype

@@ -0,0 +1,41 @@
+#!/usr/bin/env php
+<?php
+
+/**
+ * The `archetype` entry point.
+ *
+ * Everything of substance is an Artisan command under `archetype:*`; this walks
+ * up from the working directory to find the application's `artisan` file and
+ * forwards to it, so `archetype inspect app/Models/User.php` and
+ * `php artisan archetype:inspect app/Models/User.php` are the same call.
+ */
+
+$directory = getcwd();
+
+while (! is_file($directory.'/artisan')) {
+    $parent = dirname($directory);
+
+    if ($parent === $directory) {
+        fwrite(STDERR, 'ERR could not find a Laravel artisan file at or above '.getcwd().PHP_EOL);
+        exit(1);
+    }
+
+    $directory = $parent;
+}
+
+$arguments = array_slice($argv, 1);
+$operation = $arguments[0] ?? null;
+
+// A bare `archetype` lists the operations; anything else is `archetype:<op>`.
+if ($operation === null || str_starts_with($operation, '-')) {
+    array_unshift($arguments, 'archetype');
+} else {
+    $arguments[0] = str_starts_with($operation, 'archetype:') ? $operation : 'archetype:'.$operation;
+}
+
+passthru(
+    implode(' ', array_map('escapeshellarg', array_merge([PHP_BINARY, $directory.'/artisan'], $arguments))),
+    $status
+);
+
+exit($status);

composer.json

@@ -41,6 +41,9 @@
             ]
         }
     },
+    "bin": [
+        "bin/archetype"
+    ],
     "autoload": {
         "psr-4": {
             "Archetype\\": "src/"

docs.md

@@ -160,4 +160,257 @@ $file->add()->use([
 	Extra1::class,
 	Extra2::class,
 ])
-```
+```
+
+## Command line reference
+
+Every operation is an Artisan command named `archetype:<operation>`. The
+`archetype` binary walks up from the working directory to find your
+application's `artisan` file and forwards to it, so these are the same call:
+
+```bash
+./vendor/bin/archetype inspect app/Models/User.php
+php artisan archetype:inspect app/Models/User.php
+```
+
+### Targets
+
+Every operation but `make` and `apply` takes one target, which is any of:
+
+| Target | Means |
+|---|---|
+| `app/Models/User.php` | that file |
+| `App\Models\User` | that class, resolved to a path |
+| `app/Models` | every PHP class under that directory |
+
+A directory target can be narrowed:
+
+| Option | Keeps only classes |
+|---|---|
+| `--extends=Model` | extending that class |
+| `--implements=Auditable` | implementing that interface |
+| `--uses-trait=SoftDeletes` | using that trait |
+| `--matching=<regex>` | whose path matches |
+
+These options are rejected on a single-file target rather than ignored.
+
+### Options every operation takes
+
+| Option | Effect |
+|---|---|
+| `--json` | Emit JSON instead of the compact line format |
+
+### Options every mutation takes
+
+| Option | Effect |
+|---|---|
+| `--dry-run` | Show the diff without writing |
+| `--no-diff` | Suppress the diff |
+
+### Exit codes and statuses
+
+| Status | Meaning | Exit |
+|---|---|---|
+| `OK <file> <detail>` | Changed and saved | 0 |
+| `DRY <file> <detail>` | Would change; nothing written | 0 |
+| `SKIP <file> <detail>` | Already in the desired state | 0 |
+| `ERR <file> <detail>` | Could not do what was asked | 1 |
+
+A mutation that matches nothing reports `ERR`, never `OK`. That is what makes it
+safe not to read the file back.
+
+### Reading
+
+#### Summarise a file
+```bash
+archetype inspect app/Models/User.php
+```
+```
+app/Models/User.php
+class App\Models\User extends Authenticatable
+uses HasApiTokens, HasFactory, Notifiable
+import Illuminate\Foundation\Auth\User as Authenticatable
+prop protected $fillable = ["name","email","password"]
+prop protected $casts = {"email_verified_at":"datetime"}
+fn public posts() [4 lines]
+rel posts hasMany Post
+```
+
+Limit it to the sections you need — `meta`, `traits`, `uses`, `consts`, `cases`,
+`props`, `methods`, `relations`:
+
+```bash
+archetype inspect app/Models/User.php props relations
+```
+
+#### Print one method
+```bash
+archetype show app/Http/Requests/StoreTaskRequest.php rules
+```
+
+`inspect` deliberately leaves method bodies out; this is how you get one.
+
+#### Find files
+```bash
+archetype find app
+archetype find app --type=models
+archetype find --type=migrations
+archetype find app --extends=FormRequest
+archetype find app --matching='Http/Controllers'
+```
+
+`--type` is one of `all`, `models`, `controllers`, `providers`, `migrations`.
+The class types use reflection, so they only see classes the application can
+autoload; the other filters read the syntax tree and work on anything that
+parses.
+
+#### List files that do not parse
+```bash
+archetype errors
+```
+
+### Creating
+
+```bash
+archetype make 'App\Services\Billing'
+archetype make app/Services/Billing.php
+archetype make 'App\Models\Invoice' \
+    --extends='Illuminate\Database\Eloquent\Model' \
+    --implements='App\Contracts\Payable' \
+    --trait='Illuminate\Database\Eloquent\Factories\HasFactory'
+archetype make app/helpers.php --file
+```
+
+Refuses to overwrite an existing file unless given `--force`.
+
+### Properties
+
+```bash
+archetype set-property app/Models/User.php table gdpr_users
+archetype set-property app/Models/User.php with '["profile","posts"]'
+archetype set-property app/Models/User.php perPage 25 --visibility=public
+archetype set-property app/Models/User.php connection          # no default value
+
+archetype add-to-property app/Models/User.php fillable nickname avatar
+archetype empty-property app/Models/User.php fillable
+archetype remove-property app/Models/User.php hidden
+```
+
+Values are read as JSON when they are valid JSON, and as a plain string
+otherwise. Visibility is left as it is unless `--visibility` says otherwise.
+
+### Eloquent
+
+```bash
+archetype set-casts app/Models/User.php archived_at=datetime status=Status::class
+
+archetype add-relation app/Models/Project.php hasMany Task
+archetype add-relation app/Models/Project.php belongsTo User --name=owner --foreign-key=owner_id
+archetype add-relation app/Models/Project.php belongsToMany Label \
+    --table=label_project --with-pivot=sort,note --with-timestamps
+archetype add-relation app/Models/Project.php morphMany Comment --morph-name=commentable
+archetype add-relation app/Models/Project.php hasManyThrough Comment --through=Task
+```
+
+`set-casts` writes to whichever mechanism the model already uses — the `casts()`
+method Laravel 11 generates, or the `$casts` property — rather than adding a
+second one beside it.
+
+`add-relation` covers all eleven relation types: `hasOne`, `hasMany`,
+`belongsTo`, `belongsToMany`, `hasOneThrough`, `hasManyThrough`, `morphOne`,
+`morphMany`, `morphTo`, `morphToMany`, `morphedByMany`. The related class is
+imported when it needs to be.
+
+### Arrays returned from methods
+
+```bash
+archetype set-array-key app/Http/Requests/StoreTaskRequest.php rules due_at 'nullable|date'
+archetype set-array-key app/Http/Resources/TaskResource.php toArray budget '$this->budget_cents'
+archetype set-array-key app/Http/Requests/StoreTaskRequest.php rules tags "['array', 'max:5']"
+archetype set-array-key app/Http/Requests/StoreTaskRequest.php rules title --remove
+archetype set-array-key app/Providers/AppServiceProvider.php policies ignored Policy::class --append
+```
+
+This reaches `rules()`, `toArray()`, `casts()`, `definition()` and everything
+else of that shape — the array a method returns directly, never one returned
+from a closure nested inside it.
+
+A bare word is a string, so `nullable|date` is a validation rule rather than a
+bitwise or. Brackets, quotes, `$variables`, calls, `Class::constants`, numbers
+and booleans are read as PHP.
+
+### Structure
+
+```bash
+archetype add-use app/Models/User.php 'App\Contracts\Auditable' 'Illuminate\Support\Str'
+archetype remove-use app/Models/User.php 'Illuminate\Support\Str'
+archetype add-trait app/Models/User.php 'Illuminate\Database\Eloquent\SoftDeletes'
+archetype add-implements app/Models/User.php 'App\Contracts\Auditable'
+archetype set-extends app/Models/User.php 'Illuminate\Database\Eloquent\Model'
+archetype set-namespace app/Models/User.php 'App\Domain\Models'
+archetype rename-class app/Models/User.php Account
+```
+
+`add-trait`, `add-implements` and `set-extends` add the import too, since a name
+used without one is never valid PHP.
+
+`rename-class` renames the declaration only. It does not move the file or update
+references elsewhere.
+
+### Constants and enum cases
+
+```bash
+archetype set-const app/Models/User.php HOME /dashboard
+archetype remove-const app/Models/User.php HOME
+
+archetype add-case app/Enums/ProjectStatus.php OnHold on_hold
+archetype add-case app/Enums/Suit.php Spades          # pure enum, no backing value
+```
+
+Constants work on classes, interfaces, enums and traits. New enum cases are
+added after the ones already there.
+
+### Methods
+
+```bash
+archetype add-method app/Models/Project.php \
+    --code='public function scopeActive($query) { return $query->where("active", true); }'
+archetype replace-method app/Models/Project.php isActive \
+    --code='public function isActive(): bool { return $this->active; }'
+archetype remove-method app/Models/Project.php isActive
+```
+
+Methods can be added to a class, enum, interface or trait, and are appended
+after the methods already there.
+
+### Several operations in one call
+
+```bash
+archetype apply operations.txt
+archetype apply < operations.txt
+```
+
+One operation per line, `#` for comments, the `archetype:` prefix optional:
+
+```text
+# what this change needs
+add-to-property app/Models/Project.php fillable budget_cents
+set-casts app/Models/Project.php budget_cents=integer
+add-relation app/Models/Project.php hasMany Task
+```
+
+Each operation keeps its own verification, diff and exit status. `apply` exits
+non-zero if any of them failed, and `--stop-on-failure` stops at the first.
+
+### JSON
+
+Every operation takes `--json`:
+
+```bash
+archetype add-to-property app/Models/User.php fillable nickname --json
+```
+```json
+{"ok":true,"dryRun":false,"changed":1,"skipped":0,"failed":0,"results":[{"file":"app/Models/User.php","status":"changed","detail":"$fillable +1","diff":"@@ 24 @@\n+         'nickname',\n      ];"}]}
+```
+
+An error answers with `{"ok":false,"error":"..."}` and exit code 1.