Console Laravel Package

Technical Evaluation

What the release is. 0.5.0 is the console-layer consolidation wave for IndexNow Kit: the artisan commands that the Laravel adapter used to hand-roll (submit, submit-model/subjects, explain, check, config, key:generate) now ship as framework-agnostic classes in Console\Command\*, registered by the adapter rather than reimplemented. For a Laravel team the practical meaning is: the Laravel adapter (0.15.0) stops carrying its own command classes and registers this package's Symfony-console commands through Illuminate\Console\Application::resolve(). This is structural de-duplication, not new end-user capability.

Architecture fit. Good for a standard Laravel app. Commands are constructor-injected (runner, Vocabulary, Check\SampleOptions), so artisan registration is a container/registration concern rather than a subclassing exercise. Laravel-specific affordances are preserved: SubmitSubjectsCommand/ExplainCommand take string $classArgument = 'class', and the Laravel adapter passes 'model', so Artisan::call('indexnow:submit-model', ['model' => Post::class]) and existing tests keep working. That is the single most important compatibility fact in this release.

Integration feasibility. Low-to-moderate. Additive classes plus two bug-fix clusters; the only removal is CommandDefinition::laravelSignature(), whose sole in-tree consumer was the Laravel adapter's own command classes — now deleted. A stock app that only calls artisan commands and Artisan::call() should upgrade with a composer bump and a smoke test. Effort concentrates in (a) coordinated version pinning and (b) auditing any self-written commands.

Technical risk.

• Breaking, narrow: laravelSignature() removal. Impact only if the team wrote custom commands and used Definitions::check()->applyTo($this) or a $signature renderer. Migration is copy a 32-line renderer from 0.4, or register through $this->commands([...]) with the new classes. Pre-1.0 and documented — acceptable, not silent.
• Lock-step release: versioned 0.5.0 rather than 0.4.2 specifically because sitemap and history pin ^0.5. Partial upgrades across the family are the likely failure mode; the package family must move in one PR.
• Constraint bump: requires indexnowkit/core ^0.13. Confirm the Laravel adapter 0.15.0 and the optional packages agree on core ^0.13 before resolving, or composer will strand you on a half-upgraded set.
• Security-relevant fixes, not just bugs: (1) indexnow:config previously failed to mask adapter-only keys, so history.pdo.dsn — with its database password — was printed in the table, in --json, and inside the "configuration does not build" JSON the command invites users to paste into a bug report. Treat any historical indexnow:config --json output in tickets, CI artifacts, or chat as a disclosure event and rotate the implicated DB credentials. (2) --write-env created .env under umask (typically 0644) before narrowing to 0600; existing files are not narrowed, only warned about. (3) Key rotation corrupted keys containing $ or \ via unescaped preg_replace() replacement.
• Operational sharp edge on 0600: if artisan indexnow:key:generate --write-env runs as root or a build user in a container/CI step, a 0600 .env can become unreadable to php-fpm's user. Verify deploy ownership after the upgrade; this fix can convert a leak into an outage if the deploy model is naive.

Key questions.

1. Is Laravel adapter 0.15.0 (and sitemap/history at ^0.5) released and pinned in the same composer change?
2. Do we have any custom artisan command using laravelSignature() or Definitions::…->applyTo($this)? Grep before upgrading.
3. Has indexnow:config --json (or the build-failure JSON) ever been pasted into a ticket, PR, or CI artifact in the last two releases? If yes, rotate the exposed DB password.
4. What user writes .env in every environment, and can it read a 0600 file after the deploy step?
5. Do we rely on "Command not found" text from scheduler/CI wrappers for the optional sitemap/history commands? Those now resolve and exit 1 with one sentence.

Integration Approach

Stack fit. Native. One composer family (indexnowkit/* core + this console package + laravel adapter + optional sitemap/history), artisan as the only entry point for operators, Illuminate\Console\Application::resolve() handling registration so no $signature strings exist to drift. Config flows through Console\ConfigSourceInterface (raw(), build(), packages()) supplied by the adapter — meaning indexnow:check and indexnow:config validate the same strict build the app boots with.

Migration path.

1. Grep the codebase for laravelSignature, Definitions::, applyTo(, and any $this->commands([...]) registration of IndexNow commands. Enumerate custom commands; only those need the 32-line renderer copied from 0.4, or re-registration.
2. Bump indexnowkit/core to ^0.13, this package to ^0.5, Laravel adapter to 0.15.0, and sitemap/history to ^0.5 in one commit. Reject any partial resolution.
3. Run composer update --with-dependencies in a scratch branch; confirm a single core version in composer.lock and no conflict/replace surprises.
4. Exercise every command in staging: indexnow:submit, indexnow:submit-model (both Artisan::call and CLI positional forms), indexnow:explain, indexnow:check, indexnow:config (table and --json), indexnow:key:generate.
5. Verify masked output now covers adapter-only keys, including history.pdo.dsn when indexnowkit/history is absent.
6. Verify .env mode and readability post---write-env in each environment; confirm the pre-existing-file warning path fires where applicable.

Compatibility. Public API for app developers is unchanged apart from the laravelSignature() removal. The 'model' argument name is explicitly preserved for Laravel, keeping Artisan::call('indexnow:submit-model', ['model' => Post::class]) and existing feature tests green. ConfigSourceInterface and AbstractSubjectLoader are marked "Implement" tier — no method additions without a major version (pre-1.0: a minor listed under Changed) — which is the stability guarantee that matters if we ever write a custom adapter or a bespoke ORM loader; a normal app team touches neither.

Sequencing. Do the security fixes first and in isolation if scheduling allows: upgrade, then rotate the history PDO password that was leaking into indexnow:config --json. Then run the custom-command audit as a separate, low-risk PR. Defer the optional sitemap/history ^0.5 bump only if those packages are uninstalled — and if they are, install the not-installed stubs knowingly, since the scheduler will now exit 1 instead of erroring. Finally, land the DEFAULT_LIMIT = 1000 and DEFAULT_LENGTH = 32 constants as documentation-only changes; no behavior change unless we were duplicating those literals, in which case swap them out.

Operational Impact

Maintenance. Net negative maintenance — in the good way. Roughly 900 lines of eleven near-identical adapter commands, four 38-line SubjectSampler copies, and four ORM-loader skeletons collapse into shared classes; the Laravel adapter's contribution shrinks to registration plus the 'model' argument name. Future command behavior changes land once instead of once per adapter. The cost is that we now depend on the console package's release cadence rather than owning the command bodies, and sitemap/history pinning ^0.5 means those three move as a unit forever.

Support. Support surface narrows: fewer Laravel-only code paths to explain, one vocabulary for command names (Vocabulary::$submitSubjects), consistent exit codes. Two support-relevant behavior changes to brief the team on: optional-package commands now produce one explanatory sentence and exit 1 instead of "command not found" (better for humans, marginally different for log greppers), and key:generate --write-env may emit a permissions warning on pre-existing .env files — that warning is intentional and should not be suppressed.

Scaling. Submission batching is now centrally tunable: SubmitSubjectsOptions::DEFAULT_LIMIT = 1000 is the documented --limit fallback adapters should use for non-numeric input, so oversized single-request submissions become a one-line change rather than a per-adapter inconsistency. Sampling for --sample-class is capped at PER_CLASS = 3, keeping spot-check runs bounded on large catalogs. Key generation defaults to 32 characters per KeyGenerateCommand::DEFAULT_LENGTH. None of this changes throughput characteristics; it removes drift between adapters, which is where scaling surprises usually hide.

Failure modes.

• Upgrade-time: partial composer resolution across the ^0.5/^0.13 family — symptom is a confusing conflict or an old core retained; detect in composer.lock review, not at runtime.
• Deploy-time: .env written as 0600 by a build user, unreadable by the web user; symptom is a boot-time config failure immediately after a key rotation. Add an explicit post-deploy assertion on .env ownership and mode.
• Scheduler: jobs invoking indexnow:sitemap/indexnow:history without the optional package now fail with exit 1 and a sentence rather than a command-not-found error. Ensure alerting keys on non-zero exit, not on message text.
• Custom commands: any internal command built on laravelSignature() throws a class-not-found at registration — caught immediately in artisan list, which is why the smoke test should list commands before deploying.
• Residual disclosure: the history.pdo.dsn password printed by prior versions persists in whatever was pasted where. The code fix does not remediate the disclosure; credential rotation does.

Ramp-up. Hours for a Laravel developer, not days. Reading load is the ConfigSourceInterface/AbstractSubjectLoader contracts only if someone writes an adapter or custom loader — otherwise the working knowledge is "commands are registered by the adapter; the model argument is still model; run indexnow:check after config changes." The one piece of institutional knowledge worth writing down: the .env permissions and ownership expectation per environment, and the fact that indexnow:config --json is now safe to attach to tickets — with a note that it was not safe before 0.5.0.