From 14d22a44ba1c9b5f5f21408b234d7f7b229e039c Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 26 Aug 2026 02:15:29 +0000 Subject: [PATCH] fix(cli): name the entity an environment in every string the `os environments` family prints ADR-0006's v5.0 rename `project` -> `environment` has no aliases, and AGENTS.md states "Project now only means the npm/monorepo sense". #10967 (PR #11227) renamed the COMMAND across these same five files; the ENTITY NOUN inside the strings oclif prints was left behind, so `os environments switch ` answered `Active project: ...`. 25 user-visible string literals swap to the post-rename noun: 5 `static override description`, 7 flag/arg descriptions, 9 success-path console lines, 3 `examples` arg placeholders (`` -> ``) and the `switch` id-not-found error. No behaviour, flag/argument names, exit codes or `--format json`/`yaml` payloads change. `client.projects.*`, the `res.project`/`res.projects` response fields, the locals bound from them and the docblock comments are deliberately untouched: they are API surface in other packages, not CLI wording. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UjujZN219uFzBhSYfMykCd --- .changeset/cli-environments-entity-noun.md | 34 +++++++++++++++++++ .../cli/src/commands/environments/bind.ts | 16 ++++----- .../cli/src/commands/environments/create.ts | 12 +++---- .../cli/src/commands/environments/list.ts | 8 ++--- .../cli/src/commands/environments/show.ts | 6 ++-- .../cli/src/commands/environments/switch.ts | 8 ++--- 6 files changed, 59 insertions(+), 25 deletions(-) create mode 100644 .changeset/cli-environments-entity-noun.md diff --git a/.changeset/cli-environments-entity-noun.md b/.changeset/cli-environments-entity-noun.md new file mode 100644 index 0000000000..e9b24d5777 --- /dev/null +++ b/.changeset/cli-environments-entity-noun.md @@ -0,0 +1,34 @@ +--- +"@objectstack/cli": patch +--- + +fix(cli): the `os environments` family calls the entity an environment, not a project, in every string it prints (#12153) + +Per ADR-0006 the v5.0 rename `project` → `environment` has no aliases, and AGENTS.md +states "Project now only means the npm/monorepo sense". #10967 (PR #11227) renamed the +**command** (`os projects …` → `os environments …`) across these same five files; the +**entity noun** inside the strings oclif prints was left behind. A user ran +`os environments switch ` and the tool answered `✓ Active project: …`. + +25 user-visible string literals in `packages/cli/src/commands/environments/` are swapped +to the post-rename noun. No behaviour, no flag or argument names, no exit codes, and no +`--format json` / `--format yaml` payloads change — those are produced by +`formatOutput(res, …)` straight from the control-plane response and are untouched. + +| where | count | printed by | +| --- | --- | --- | +| `static override description` | 5 | `os environments --help` | +| flag / arg `description` | 7 | each command's own `--help` | +| success-path console output | 9 | `list` · `bind` · `create` · `show` · `switch` | +| `examples` arg placeholder (`` → ``) | 3 | `os environments bind --help` | +| the `switch` id-not-found error | 1 | `os environments switch` on a bad id | + +The five `static override description` strings now read as +`content/docs/deployment/cli.mdx`'s command table has described them since the rename +("List environments visible to the current session", "Provision a new environment", …), +so the shipped `--help` and the shipped docs agree for the first time. + +What is deliberately NOT renamed, because it is API surface in other packages rather than +CLI wording, and each needs its own decision: `client.projects.*` (the `@objectstack/client` +SDK method names), the `res.project` / `res.projects` response fields, the locals bound +directly from them, and the docblock comments in these files. diff --git a/packages/cli/src/commands/environments/bind.ts b/packages/cli/src/commands/environments/bind.ts index d8cb782abd..af2977cc13 100644 --- a/packages/cli/src/commands/environments/bind.ts +++ b/packages/cli/src/commands/environments/bind.ts @@ -21,17 +21,17 @@ import { formatOutput } from '../../utils/output-formatter.js'; * reflects the latest source. */ export default class EnvironmentsBind extends Command { - static override description = 'Bind a local objectstack artifact to an existing project'; + static override description = 'Bind a local objectstack artifact to an existing environment'; static override examples = [ - '$ os environments bind --artifact ./dist/objectstack.json', - '$ os environments bind --artifact ./dist/objectstack.json --build', - '$ os environments bind --reseed', + '$ os environments bind --artifact ./dist/objectstack.json', + '$ os environments bind --artifact ./dist/objectstack.json --build', + '$ os environments bind --reseed', ]; static override args = { environmentId: Args.string({ - description: 'Target project id (UUID)', + description: 'Target environment id (UUID)', required: true, }), }; @@ -111,7 +111,7 @@ export default class EnvironmentsBind extends Command { delete existingMeta.artifactBindError; existingMeta.artifact_path = artifactAbs; - printKV('Project', args.environmentId, '🎯'); + printKV('Environment', args.environmentId, '🎯'); printKV('Artifact', artifactAbs, '📦'); const res = await client.projects.update(args.environmentId, { @@ -139,9 +139,9 @@ export default class EnvironmentsBind extends Command { } else if (flags.format === 'yaml') { await formatOutput(res, 'yaml'); } else { - console.log(`\n✓ Project bound to artifact`); + console.log(`\n✓ Environment bound to artifact`); console.log(` ${args.environmentId} → ${artifactAbs}`); - console.log(` The next request to this project will load the new bundle.`); + console.log(` The next request to this environment will load the new bundle.`); console.log(''); } } catch (error: any) { diff --git a/packages/cli/src/commands/environments/create.ts b/packages/cli/src/commands/environments/create.ts index c0f166b88d..63b348089e 100644 --- a/packages/cli/src/commands/environments/create.ts +++ b/packages/cli/src/commands/environments/create.ts @@ -15,7 +15,7 @@ import { readAuthConfig, writeAuthConfig } from '../../utils/auth-config.js'; * (unless `--no-activate` is passed). */ export default class EnvironmentsCreate extends Command { - static override description = 'Provision a new project'; + static override description = 'Provision a new environment'; static override examples = [ '$ os environments create --org 00000000-0000-0000-0000-000000000000 --name Staging', @@ -39,11 +39,11 @@ export default class EnvironmentsCreate extends Command { // 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', + description: 'Path to a locally-compiled objectstack.json artifact to bind into this environment', }), - 'clone-from': Flags.string({ description: 'Clone schema from an existing project id' }), + 'clone-from': Flags.string({ description: 'Clone schema from an existing environment id' }), activate: Flags.boolean({ - description: 'Activate the new project for subsequent CLI calls', + description: 'Activate the new environment for subsequent CLI calls', default: true, allowNo: true, }), @@ -111,9 +111,9 @@ export default class EnvironmentsCreate extends Command { await formatOutput(res, 'yaml'); } else { const p = res?.project ?? {}; - console.log(`\n✓ Project created: ${p.display_name ?? p.id} (${p.id})`); + console.log(`\n✓ Environment created: ${p.display_name ?? p.id} (${p.id})`); if (flags.activate) { - console.log(` active project set to ${p.id}`); + console.log(` active environment set to ${p.id}`); } console.log(''); } diff --git a/packages/cli/src/commands/environments/list.ts b/packages/cli/src/commands/environments/list.ts index 892dd9f7af..b53e4998f5 100644 --- a/packages/cli/src/commands/environments/list.ts +++ b/packages/cli/src/commands/environments/list.ts @@ -13,7 +13,7 @@ import { formatOutput } from '../../utils/output-formatter.js'; * consistent DX. */ export default class EnvironmentsList extends Command { - static override description = 'List projects visible to the current session'; + static override description = 'List environments visible to the current session'; static override examples = [ '$ os environments list', @@ -25,7 +25,7 @@ export default class EnvironmentsList extends Command { url: Flags.string({ char: 'u', description: 'Server URL', env: 'OS_CLOUD_URL' }), token: Flags.string({ char: 't', description: 'Authentication token', env: 'OS_TOKEN' }), org: Flags.string({ description: 'Filter by organization id' }), - status: Flags.string({ description: 'Filter by project status (active|provisioning|failed|…)' }), + status: Flags.string({ description: 'Filter by environment status (active|provisioning|failed|…)' }), format: Flags.string({ char: 'f', description: 'Output format', @@ -57,9 +57,9 @@ export default class EnvironmentsList extends Command { } else if (flags.format === 'yaml') { await formatOutput(res, 'yaml'); } else { - console.log(`\nProjects (${projects.length}):\n`); + console.log(`\nEnvironments (${projects.length}):\n`); if (projects.length === 0) { - console.log(' (no projects)'); + console.log(' (no environments)'); } else { for (const p of projects) { const active = p.id === activeId ? ' ★' : ''; diff --git a/packages/cli/src/commands/environments/show.ts b/packages/cli/src/commands/environments/show.ts index 6c4b4f726b..92c4f46ab4 100644 --- a/packages/cli/src/commands/environments/show.ts +++ b/packages/cli/src/commands/environments/show.ts @@ -12,7 +12,7 @@ import { formatOutput } from '../../utils/output-formatter.js'; * membership row (same shape as `client.projects.get(id)`). */ export default class EnvironmentsShow extends Command { - static override description = 'Show detailed information for a project'; + static override description = 'Show detailed information for an environment'; static override examples = [ '$ os environments show 00000000-0000-0000-0000-000000000001', @@ -20,7 +20,7 @@ export default class EnvironmentsShow extends Command { ]; static override args = { - id: Args.string({ description: 'Project id', required: true }), + id: Args.string({ description: 'Environment id', required: true }), }; static override flags = { @@ -49,7 +49,7 @@ export default class EnvironmentsShow extends Command { await formatOutput(res, 'yaml'); } else { const p = res?.project ?? {}; - console.log(`\nProject: ${p.display_name ?? p.id}`); + console.log(`\nEnvironment: ${p.display_name ?? p.id}`); console.log('─'.repeat(60)); console.log(` id: ${p.id}`); console.log(` organization: ${p.organization_id ?? '—'}`); diff --git a/packages/cli/src/commands/environments/switch.ts b/packages/cli/src/commands/environments/switch.ts index dcbe0648f6..0750425157 100644 --- a/packages/cli/src/commands/environments/switch.ts +++ b/packages/cli/src/commands/environments/switch.ts @@ -15,7 +15,7 @@ import { readAuthConfig, writeAuthConfig } from '../../utils/auth-config.js'; * project. */ export default class EnvironmentsSwitch extends Command { - static override description = 'Activate a project for subsequent CLI calls'; + static override description = 'Activate an environment for subsequent CLI calls'; static override examples = [ '$ os environments switch 00000000-0000-0000-0000-000000000001', @@ -23,7 +23,7 @@ export default class EnvironmentsSwitch extends Command { ]; static override args = { - id: Args.string({ description: 'Project id to activate', required: true }), + id: Args.string({ description: 'Environment id to activate', required: true }), }; static override flags = { @@ -47,7 +47,7 @@ export default class EnvironmentsSwitch extends Command { const lookup = await client.projects.get(args.id); const project = lookup?.project; if (!project?.id) { - throw new Error(`Project ${args.id} not found`); + throw new Error(`Environment ${args.id} not found`); } if (flags.remote) { @@ -59,7 +59,7 @@ export default class EnvironmentsSwitch extends Command { cfg.lastUsedAt = new Date().toISOString(); await writeAuthConfig(cfg); - console.log(`\n✓ Active project: ${project.display_name ?? project.id}`); + console.log(`\n✓ Active environment: ${project.display_name ?? project.id}`); console.log(` id: ${project.id}`); if (!flags.remote) { console.log(' (local only — server session unchanged)');