cli: environments/*.ts command sources no longer spell os projects in --help (#11227)

* fix(cli): environments/*.ts command sources no longer spell os projects in live --help output

Fixes #10967

static override examples arrays, JSDoc headers, and exported class names
in packages/cli/src/commands/environments/{bind,create,list,show,switch}.ts
still spelled the pre-v5.0-rename `os projects <cmd>` — oclif prints
examples verbatim as part of --help, so a user copy-pasting straight from
`os environments bind --help` hit `Error: Command projects:bind not found.`

- examples arrays and JSDoc headers: os projects -> os environments (all
  five files, 21 occurrences).
- exported class names renamed to match their file-path-derived command id
  (ProjectsBind -> EnvironmentsBind, etc.) -- oclif's pattern-strategy
  loader derives a command's id purely from its file path, confirmed by
  reading processCommandIds() in @oclif/core and by building the CLI and
  running --help/a real invocation on all five commands after the rename.
- environments.test.ts's imports and describe title updated to match, and
  gains a pin: every examples entry on these five commands is checked
  against the CLI's actual file-tree-derived command-id set (not a grep for
  the literal string "os projects"), so a future topic rename that misses
  an examples string fails a test instead of shipping. Anti-vacuity and
  reverse-verification (both the pre-fix line as a specimen, and a live
  edit-run-restore cycle) are documented in the test file's own comment.

* fix(cli): widen #10967's examples-resolve pin to every command file

PM review on #11227: the pin's population was a hardcoded 5-file map --
exactly the set already correct -- so it could not catch this defect class
returning anywhere else, including in the register.ts/whoami.ts/logout.ts
files #11221 already tracks live.

Widen it to every command source under packages/cli/src/commands/**,
walked the same way registeredCommandIds() already walks the tree for the
id universe. examples are now read via TypeScript AST (extractExamples),
not by importing every command module, to avoid making this file's cost
and failure surface track the whole package's transitive import graph.
extractExamples/stripInvocationPrefix now handle every invocation shape
actually present in the package: plain '$ os ...', the oclif help-template
form '<%= config.bin %> ...', either prefixed by one or more ENV=value
assignments (including a double-quoted value containing spaces), and the
{ command, description } object form start.ts uses twice.

The three #11221-owned files are carved out via an EXCLUDED map (file ->
reason), matching the pattern in
packages/create-objectstack/src/starter-comments-self-contained.test.ts's
EXCLUDED: a filtered main assertion, plus a second it.each that re-runs the
same predicate over the excluded files and asserts it still finds an
unresolved entry -- so when #11221 lands, that assertion goes red and says
to delete the entry, instead of the exclusion silently living forever.

Verified: the widened pin passes (71 tests, up from 14). Reverse-verified
the exclusion is load-bearing, not decorative -- temporarily cleared
EXCLUDED and confirmed all three files fail by name for the expected
reason (their real, currently-unresolved os auth ... examples), then
restored. Re-verified the original bind.ts reverse-verification still
works under the new population (a reintroduced stale example fails only
that one file, all others still pass). Re-ran the full local gate battery
(18 gates) clean.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: Elon Musk

.changeset/environments-command-source-naming.md

@@ -0,0 +1,22 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `environments/*.ts` command sources no longer spell `os projects` in live `--help` output (#10967)
+
+`static override examples` is printed verbatim as part of oclif's `--help`, and all five
+commands under `packages/cli/src/commands/environments/` (`bind`, `create`, `list`, `show`,
+`switch`) still spelled the pre-v5.0-rename `os projects <cmd>` there — a user copy-pasting
+straight from `os environments bind --help` hit `Error: Command projects:bind not found.`
+(exit 2), the same dead command #10927 fixed in `packages/cli/README.md`, this time sourced
+from the CLI binary itself.
+
+`examples` arrays and JSDoc headers now say `os environments <cmd>`. The exported default
+class on each file is renamed to match its real, file-path-derived command id
+(`ProjectsBind` → `EnvironmentsBind`, etc.) — oclif's pattern-strategy loader derives a
+command's id purely from its file path, never from the class name, so this rename changes
+no runtime resolution; verified by building the CLI and running `--help` on all five
+commands, plus one real invocation, after the rename. `environments.test.ts`'s imports and
+`describe` title are updated to match, and gain a pin: every `examples` entry on these five
+commands is checked against the CLI's actual file-tree-derived command-id set, so a future
+topic rename that misses an `examples` string fails a test instead of shipping.

packages/cli/src/commands/environments/bind.ts

@@ -9,7 +9,7 @@ import { createApiClient, requireAuth } from '../../utils/api-client.js';
 import { formatOutput } from '../../utils/output-formatter.js';
 
 /**
- * `os projects bind` — bind a locally-compiled artifact to an existing
+ * `os environments bind` — bind a locally-compiled artifact to an existing
  * multi-environment server project.
  *
  * Equivalent to `PATCH /api/v1/cloud/environments/<id>` with
@@ -20,13 +20,13 @@ import { formatOutput } from '../../utils/output-formatter.js';
  * Use `--build` to compile `objectstack.config.ts` first so the artifact
  * reflects the latest source.
  */
-export default class ProjectsBind extends Command {
+export default class EnvironmentsBind extends Command {
   static override description = 'Bind a local objectstack artifact to an existing project';
 
   static override examples = [
-    '$ os projects bind <project-id> --artifact ./dist/objectstack.json',
-    '$ os projects bind <project-id> --artifact ./dist/objectstack.json --build',
-    '$ os projects bind <project-id> --reseed',
+    '$ os environments bind <project-id> --artifact ./dist/objectstack.json',
+    '$ os environments bind <project-id> --artifact ./dist/objectstack.json --build',
+    '$ os environments bind <project-id> --reseed',
   ];
 
   static override args = {
@@ -59,7 +59,7 @@ export default class ProjectsBind extends Command {
   };
 
   async run(): Promise<void> {
-    const { args, flags } = await this.parse(ProjectsBind);
+    const { args, flags } = await this.parse(EnvironmentsBind);
 
     try {
       const artifactRel = flags.artifact ?? './dist/objectstack.json';

packages/cli/src/commands/environments/create.ts

@@ -7,21 +7,21 @@ import { formatOutput } from '../../utils/output-formatter.js';
 import { readAuthConfig, writeAuthConfig } from '../../utils/auth-config.js';
 
 /**
- * `os projects create` — provision a new project.
+ * `os environments create` — provision a new project.
  *
  * Delegates to `ProjectProvisioningService.provisionProject` on the server.
  * On success, optionally activates the new project for the current session
  * and persists `activeEnvironmentId` into `~/.objectstack/credentials.json`
  * (unless `--no-activate` is passed).
  */
-export default class ProjectsCreate extends Command {
+export default class EnvironmentsCreate extends Command {
   static override description = 'Provision a new project';
 
   static override examples = [
-    '$ os projects create --org 00000000-0000-0000-0000-000000000000 --name Staging',
-    '$ os projects create --org $ORG --name Dev --plan free',
-    '$ os projects create --org $ORG --name "Clone" --clone-from <source-id> --no-activate',
-    '$ os projects create --org $ORG --name CRM --artifact ./examples/app-crm/dist/objectstack.json',
+    '$ os environments create --org 00000000-0000-0000-0000-000000000000 --name Staging',
+    '$ os environments create --org $ORG --name Dev --plan free',
+    '$ os environments create --org $ORG --name "Clone" --clone-from <source-id> --no-activate',
+    '$ os environments create --org $ORG --name CRM --artifact ./examples/app-crm/dist/objectstack.json',
   ];
 
   static override flags = {
@@ -56,7 +56,7 @@ export default class ProjectsCreate extends Command {
   };
 
   async run(): Promise<void> {
-    const { flags } = await this.parse(ProjectsCreate);
+    const { flags } = await this.parse(EnvironmentsCreate);
 
     try {
       const { client, token } = await createApiClient({ url: flags.url, token: flags.token });