feat(cli): carry the ADR-0112 code and httpStatus in --format json failure envelopes (#13510)

* feat(cli): carry the ADR-0112 code and httpStatus in --format json failure envelopes

Every machine-readable failure the CLI emits was `{ success: false, error:
error.message }` and nothing else — 48 sites under `packages/cli/src/commands/`.
The error reaching those `catch` blocks from `@objectstack/client` is not a bare
`Error`: the SDK's `fetch` wrapper attaches `err.code` (the semantic ADR-0112
string, normalized across both server dialects) and `err.httpStatus`. Both were
discarded at the CLI boundary, so a script had to substring-match an English
sentence that no contract pins.

One shared builder (`errorCodeFields` in `utils/format.ts`) plus 48 call-site
spreads. Additive: `success` and `error` keep their meaning and spelling, the
payload stays flat, and the two keys are ABSENT — not `undefined` — when the
thrown error did not carry them. No fallback code is invented for a
locally-thrown plain `Error`. Human `table` output is untouched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TvqBFLRzXdSPcbusDoED9k

* test(cli): give the #13347 envelope cases an explicit wall-clock budget

Each case drives a real `Command.run` against the real oclif root — ~0.8s per
case on an idle box, and measured TIMING OUT at vitest's 5s default when the
file ran inside `@objectstack/cli`'s full 220-file suite on a shared container.
Wall-clock only: no assertion moves. The neighbouring
`delete-reset-carriers.test.ts` reaches the same conclusion the same way.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TvqBFLRzXdSPcbusDoED9k

* docs(cli): declare errorCodeFields.code's real value space — pass-through, ADR-0112 for wire failures, Node errno for local I/O

Contract-review amendment on #13510: the field doc and changeset called
code 'the semantic ADR-0112 code', but the builder is a structural
pass-through and os validate/compile/lint throw errno-carrying fs errors
inside the same try, so ENOENT/ENOTDIR are genuinely publishable values.
Behaviour unchanged (the ruling's literal pass-through shape stands);
only the declaration now matches it. The vocabularies are disjoint
(errnos are E-prefixed OS names), so ADR-0112 branches cannot
false-match an errno.

---------

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

Author: os-trump

.changeset/cli-json-error-envelope-adr-0112-code.md

@@ -0,0 +1,81 @@
+---
+"@objectstack/cli": minor
+---
+
+feat(cli): `--format json` failure envelopes carry the ADR-0112 `code` and `httpStatus` (#13347)
+
+Every machine-readable failure this CLI emits was built the same way — 48 sites
+under `packages/cli/src/commands/`:
+
+```ts
+await emitJson({ success: false, error: error.message });
+```
+
+The payload carried the human sentence and nothing else. The error reaching
+those `catch` blocks from `@objectstack/client` is not a bare `Error`: the SDK's
+`fetch` wrapper attaches `err.code` (the semantic ADR-0112 string, normalized to
+the same spelling across the flat `@objectstack/rest` envelope and the wrapped
+runtime-dispatcher one) and `err.httpStatus`. Both were discarded at the CLI
+boundary, so the one outcome a script most needs to branch on — *someone else
+edited it, re-read and retry* vs *you are not allowed* vs *the server is down* —
+was separable only by substring-matching an English sentence that no contract
+pins.
+
+A stale-pin refusal from `os meta delete --if-match` used to read:
+
+```json
+{
+  "success": false,
+  "error": "[metadata_conflict] view/race_probe has been modified since you loaded it. …"
+}
+```
+
+and now reads:
+
+```json
+{
+  "success": false,
+  "error": "[metadata_conflict] view/race_probe has been modified since you loaded it. …",
+  "code": "METADATA_CONFLICT",
+  "httpStatus": 409
+}
+```
+
+Maintainer ruling 2026-08-30 (option **A** of three):
+
+- The payload stays **FLAT**. Nesting into `{ error: { code, message, httpStatus } }`
+  was considered and declined as breaking.
+- `success` and `error` keep their current meaning **and spelling**.
+- The two keys are emitted **only when the thrown error carries them**, and are
+  **absent** — not `undefined` — otherwise. No fallback code is invented for a
+  locally-thrown plain `Error`: this CLI's own input refusals get no code,
+  deliberately, because ADR-0112's ledger is the authority on who may mint one.
+
+One value-space note, stated so the declaration matches what ships: `code` is a
+**pass-through**, never minted or filtered. On wire failures it is the semantic
+ADR-0112 string the SDK attached; on local I/O failures inside the same `try`
+(`os validate` reading a `src/docs` that is a file, say) it is the Node errno
+(`ENOENT`, `ENOTDIR`, …). The two vocabularies are disjoint — errnos are
+`E`-prefixed OS names — so a consumer branching on ADR-0112 codes cannot
+false-match an errno, but not every emitted `code` is ledger-owned.
+
+Human (`table`) output is untouched.
+
+**Why `minor` and not `patch`.** Maintainer-set, and it overrides the obvious
+reading: this is a shape change to an **already-published error envelope**, and
+that makes it minor even though it is purely additive.
+
+**Migration.** Nothing is required — no key is removed, renamed or re-typed, and
+every payload this CLI emitted before is still emitted, byte-for-byte, minus the
+two new keys. Two things are worth knowing before you rely on the new ones:
+
+- **The envelope is polymorphic, by design.** `code` and `httpStatus` are absent
+  whenever the failure did not carry them, which a consumer cannot distinguish
+  from an older CLI. Branch on presence (`if (payload.code === 'METADATA_CONFLICT')`),
+  never on absence meaning "success" or "unsupported version". This cost was
+  weighed against breaking every existing consumer, and the non-breaking side won.
+- **Stop substring-matching the sentence.** `error` is prose and no contract pins
+  its wording; the bracketed `[metadata_conflict]` tag some messages carry today
+  is a property of one producer, not a contract, and a separate card argues for
+  removing it. Code that reads the sentence to classify a failure should move to
+  `code` (with `httpStatus` as the coarse fallback).

packages/cli/src/commands/cloud/login.ts

@@ -73,7 +73,7 @@ import * as readline from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import { Command, Flags } from '@oclif/core';
 import type { CliExitCode } from '../../utils/format.js';
-import { printHeader, printKV, printSuccess, printError, emitJson } from '../../utils/format.js';
+import { printHeader, printKV, printSuccess, printError, emitJson, errorCodeFields } from '../../utils/format.js';
 import { loginWithBrowser, loginWithPassword } from '../../utils/auth-flows.js';
 import { DEFAULT_CLOUD_URL, readCloudConfig, writeCloudConfig } from '../../utils/cloud-config.js';
 
@@ -246,7 +246,7 @@ export default class CloudLogin extends Command {
         // written (an expired code, a denied approval, a poll failure), so an
         // indented payload here would recreate a two-document stream on the
         // path a consumer is least able to recover from.
-        await emitRecord({ success: false, error: error.message });
+        await emitRecord({ success: false, error: error.message, ...errorCodeFields(error) });
         this.exit(1);
       }
       printError(error.message || String(error));

packages/cli/src/commands/cloud/logout.ts

@@ -8,7 +8,7 @@
 
 import { Command, Flags } from '@oclif/core';
 import { ObjectStackClient } from '@objectstack/client';
-import { printHeader, printSuccess, printError, emitJson } from '../../utils/format.js';
+import { printHeader, printSuccess, printError, emitJson, errorCodeFields } from '../../utils/format.js';
 import { deleteCloudConfig, tryReadCloudConfig } from '../../utils/cloud-config.js';
 
 export default class CloudLogout extends Command {
@@ -46,7 +46,7 @@ export default class CloudLogout extends Command {
       }
     } catch (error: any) {
       if (flags.json) {
-        await emitJson({ success: false, error: error.message });
+        await emitJson({ success: false, error: error.message, ...errorCodeFields(error) });
         this.exit(1);
       }
       printError(error.message || String(error));

packages/cli/src/commands/cloud/whoami.ts

@@ -7,7 +7,7 @@
  */
 
 import { Command, Flags } from '@oclif/core';
-import { printHeader, printKV, printSuccess, printError, emitJson, isExitSignal } from '../../utils/format.js';
+import { printHeader, printKV, printSuccess, printError, emitJson, isExitSignal, errorCodeFields } from '../../utils/format.js';
 import { tryReadCloudConfig } from '../../utils/cloud-config.js';
 
 export default class CloudWhoami extends Command {
@@ -72,7 +72,7 @@ export default class CloudWhoami extends Command {
     } catch (error: any) {
       if (isExitSignal(error)) throw error;
       if (flags.json) {
-        await emitJson({ success: false, error: error.message });
+        await emitJson({ success: false, error: error.message, ...errorCodeFields(error) });
         this.exit(1);
       }
       printError(error.message || String(error));

packages/cli/src/commands/compile.ts

@@ -39,6 +39,7 @@ import {
   printMetadataStats,
   emitJson,
   isExitSignal,
+  errorCodeFields,
 } from '../utils/format.js';
 import { checkSpecVersionGap } from '../utils/spec-version.js';
 
@@ -720,7 +721,7 @@ export default class Compile extends Command {
     } catch (error: any) {
       if (isExitSignal(error)) throw error;
       if (flags.json) {
-        await emitJson({ success: false, error: error.message, warnings: warningsSoFar(), conversions: conversionNotices }, 0, { compact: true });
+        await emitJson({ success: false, error: error.message, ...errorCodeFields(error), warnings: warningsSoFar(), conversions: conversionNotices }, 0, { compact: true });
         this.exit(1);
       }
       console.log('');

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

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { Args, Command, Flags } from '@oclif/core';
-import { printError, printSuccess, emitJson } from '../../utils/format.js';
+import { printError, printSuccess, emitJson, errorCodeFields } from '../../utils/format.js';
 import { createApiClient, requireAuth } from '../../utils/api-client.js';
 import { formatOutput } from '../../utils/output-formatter.js';
 
@@ -100,6 +100,7 @@ export default class DataCreate extends Command {
         await emitJson({
           success: false,
           error: error.message,
+          ...errorCodeFields(error),
         });
         this.exit(1);
       }

packages/cli/src/commands/data/delete.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { Args, Command, Flags } from '@oclif/core';
-import { printError, printSuccess, emitJson } from '../../utils/format.js';
+import { printError, printSuccess, emitJson, errorCodeFields } from '../../utils/format.js';
 import { createApiClient, requireAuth } from '../../utils/api-client.js';
 import { formatOutput } from '../../utils/output-formatter.js';
 
@@ -83,6 +83,7 @@ export default class DataDelete extends Command {
         await emitJson({
           success: false,
           error: error.message,
+          ...errorCodeFields(error),
         });
         this.exit(1);
       }

packages/cli/src/commands/data/get.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { Args, Command, Flags } from '@oclif/core';
-import { printError, emitJson } from '../../utils/format.js';
+import { printError, emitJson, errorCodeFields } from '../../utils/format.js';
 import { createApiClient, requireAuth } from '../../utils/api-client.js';
 import { formatOutput } from '../../utils/output-formatter.js';
 
@@ -74,6 +74,7 @@ export default class DataGet extends Command {
         await emitJson({
           success: false,
           error: error.message,
+          ...errorCodeFields(error),
         });
         this.exit(1);
       }

packages/cli/src/commands/data/query.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { Args, Command, Flags } from '@oclif/core';
-import { printError, emitJson } from '../../utils/format.js';
+import { printError, emitJson, errorCodeFields } from '../../utils/format.js';
 import { createApiClient, requireAuth } from '../../utils/api-client.js';
 import { formatOutput } from '../../utils/output-formatter.js';
 
@@ -117,6 +117,7 @@ export default class DataQuery extends Command {
         await emitJson({
           success: false,
           error: error.message,
+          ...errorCodeFields(error),
         });
         this.exit(1);
       }

packages/cli/src/commands/data/update.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { Args, Command, Flags } from '@oclif/core';
-import { printError, printSuccess, emitJson } from '../../utils/format.js';
+import { printError, printSuccess, emitJson, errorCodeFields } from '../../utils/format.js';
 import { createApiClient, requireAuth } from '../../utils/api-client.js';
 import { formatOutput } from '../../utils/output-formatter.js';
 
@@ -104,6 +104,7 @@ export default class DataUpdate extends Command {
         await emitJson({
           success: false,
           error: error.message,
+          ...errorCodeFields(error),
         });
         this.exit(1);
       }