From 9130aa5a800d2e7e92198216bb1e72afe333f102 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 25 Aug 2026 11:07:49 +0000 Subject: [PATCH 1/2] =?UTF-8?q?docs(cli):=20fix=20two=20stale=20`os=20?= =?UTF-8?q?=E2=80=A6`=20invocations,=20docblock=20the=20two=20deliberate?= =?UTF-8?q?=20ones?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `os projects switch` (utils/api-client.ts) and `os packages install` (commands/environments/create.ts) name ids the CLI does not register: `projects` became `environments` in v5.0 with no aliases (ADR-0006), and the package topic is singular. Both corrected against the ids read from the built oclif `Config`. The other two documented invocations in this package that do not resolve are correct prose, not defects, so they are annotated rather than changed: `os publish` / `os rollback` in commands/package/publish.ts name commands that were deliberately removed, and `os datasource` in utils/response-envelope.ts names a real topic whose three subcommands are the runnable ids. Each now says so in place, so a future reader — or a future sweep author — does not "fix" accurate prose. Comment text only; no command id, flag, or behaviour changes. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01HbG3rGVLjZStHQxHDtzJdJ --- packages/cli/src/commands/environments/create.ts | 2 +- packages/cli/src/commands/package/publish.ts | 8 ++++++++ packages/cli/src/utils/api-client.ts | 2 +- packages/cli/src/utils/response-envelope.ts | 9 +++++++++ 4 files changed, 19 insertions(+), 2 deletions(-) diff --git a/packages/cli/src/commands/environments/create.ts b/packages/cli/src/commands/environments/create.ts index 3d1fe9bfe3..c0f166b88d 100644 --- a/packages/cli/src/commands/environments/create.ts +++ b/packages/cli/src/commands/environments/create.ts @@ -36,7 +36,7 @@ export default class EnvironmentsCreate extends Command { // the `blank`/`crm`/`todo` registry it named died with the `apps/server` // templates route. Removed in #3731: an accepted-and-dropped flag reports // success for work that never happened. Starter content is installed from - // the App Marketplace instead (`os packages install`, `sys_package` with + // the App Marketplace instead (`os package install`, `sys_package` with // `is_starter = true`). artifact: Flags.string({ description: 'Path to a locally-compiled objectstack.json artifact to bind into this project', diff --git a/packages/cli/src/commands/package/publish.ts b/packages/cli/src/commands/package/publish.ts index c1be9ba559..7741f82ef7 100644 --- a/packages/cli/src/commands/package/publish.ts +++ b/packages/cli/src/commands/package/publish.ts @@ -16,6 +16,14 @@ * way to publish. (The legacy direct-to-environment `os publish` / `os * rollback` commands, which wrote sys_environment_revision, have been * removed.) + * + * NOTE — `os publish` and `os rollback` above are RETIRED ids, named here on + * purpose: the sentence is *about* their removal, and neither resolves today. + * Measured against the built oclif `Config`: the registered `publish` ids are + * `package publish` and `plugin publish`, and no `rollback` id exists at all. + * A sweep for documented `os …` invocations that do not resolve will flag + * these two — leave them. Re-spelling either to a live id would make the + * sentence false, and deleting the sentence would drop accurate history. */ import { readFile } from 'node:fs/promises'; diff --git a/packages/cli/src/utils/api-client.ts b/packages/cli/src/utils/api-client.ts index 2025fb8c06..6213c0d7bf 100644 --- a/packages/cli/src/utils/api-client.ts +++ b/packages/cli/src/utils/api-client.ts @@ -17,7 +17,7 @@ export interface ApiClientOptions { token?: string; /** * Explicit project id. Overrides the stored `activeEnvironmentId` from - * `~/.objectstack/credentials.json` (written by `os projects switch`). + * `~/.objectstack/credentials.json` (written by `os environments switch`). */ environmentId?: string; /** diff --git a/packages/cli/src/utils/response-envelope.ts b/packages/cli/src/utils/response-envelope.ts index 16351e8557..d94f2f3518 100644 --- a/packages/cli/src/utils/response-envelope.ts +++ b/packages/cli/src/utils/response-envelope.ts @@ -23,6 +23,15 @@ * drifts three times, and the three commands are how a human learns the server * disagrees with them. * + * (`datasource` is a TOPIC, not a runnable command id: the three subcommands + * are `datasource introspect`, `datasource list-tables` and `datasource + * validate` — verified against the built oclif `Config`, where `datasource` + * appears among the topics and not among the commands. The prose above names + * the topic, and naming it is correct; a sweep for documented `os …` + * invocations that resolve to a registered id flags `os datasource`, and that + * flag is a false positive — do not rewrite the sentence around one + * subcommand, which would say something narrower and untrue.) + * * ## Why an unreadable body is an ERROR here, never an empty payload * * That is the same defect generalised. The severe half was never the crash on From 6fe142cecb686b5ff40178d75bafd847fc4feafe Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 25 Aug 2026 12:01:52 +0000 Subject: [PATCH 2/2] docs(cli): word the two notes so they do not plant new unresolved spans MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Re-running the sweep this card measures showed the notes had added three sweep hits of their own: each contained a literal backticked `os …` span, which the sweep reads as an invocation that resolves to nothing. A note whose purpose is to keep a future sweep honest should not inflate that sweep's own numbers, so both now describe the sweep without spelling a placeholder invocation. The retired ids they deliberately name are unchanged. Measured after: 583 invocations across 109 non-test sources, 5 unresolved — the two genuinely stale ones are gone, and every remaining hit is one of the retired/topic names these two notes exist to declare. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01HbG3rGVLjZStHQxHDtzJdJ --- packages/cli/src/commands/package/publish.ts | 4 ++-- packages/cli/src/utils/response-envelope.ts | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/cli/src/commands/package/publish.ts b/packages/cli/src/commands/package/publish.ts index 7741f82ef7..c171e26f41 100644 --- a/packages/cli/src/commands/package/publish.ts +++ b/packages/cli/src/commands/package/publish.ts @@ -21,8 +21,8 @@ * purpose: the sentence is *about* their removal, and neither resolves today. * Measured against the built oclif `Config`: the registered `publish` ids are * `package publish` and `plugin publish`, and no `rollback` id exists at all. - * A sweep for documented `os …` invocations that do not resolve will flag - * these two — leave them. Re-spelling either to a live id would make the + * A sweep over the documented CLI invocations in this package will flag both + * of them as unresolved — leave them. Re-spelling either to a live id would make the * sentence false, and deleting the sentence would drop accurate history. */ diff --git a/packages/cli/src/utils/response-envelope.ts b/packages/cli/src/utils/response-envelope.ts index d94f2f3518..1c4123c439 100644 --- a/packages/cli/src/utils/response-envelope.ts +++ b/packages/cli/src/utils/response-envelope.ts @@ -27,8 +27,8 @@ * are `datasource introspect`, `datasource list-tables` and `datasource * validate` — verified against the built oclif `Config`, where `datasource` * appears among the topics and not among the commands. The prose above names - * the topic, and naming it is correct; a sweep for documented `os …` - * invocations that resolve to a registered id flags `os datasource`, and that + * the topic, and naming it is correct; a sweep over the documented CLI + * invocations in this package flags `os datasource` as unresolved, and that * flag is a false positive — do not rewrite the sentence around one * subcommand, which would say something narrower and untrue.) *