An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): declare apiVersion on the published envelope types (#6555)
Joey23be80d50596
diff --git a/.changeset/cli-spec-envelope-types-apiversion.md b/.changeset/cli-spec-envelope-types-apiversion.mdnew file mode 100644index 0000000000..87ea1e2908--- /dev/null+++ b/.changeset/cli-spec-envelope-types-apiversion.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] The `@astryxdesign/cli/json` types now declare `apiVersion` on `CLIError`, `CLIUnsupportedError`, and the success envelope that `parseResponse` and `assertResponse` return, matching what every `--json` envelope carries. Code that constructs a `CLIError` value by hand, for example in a test double, now has to include `apiVersion`.++@josephfarinadiff --git a/packages/cli/api/json/envelope-types.test.mjs b/packages/cli/api/json/envelope-types.test.mjsnew file mode 100644index 0000000000..8570bbf233--- /dev/null+++ b/packages/cli/api/json/envelope-types.test.mjs@@ -0,0 +1,76 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file The published `@astryxdesign/cli/json` envelope types carry+ * `apiVersion`, the field every `--json` envelope has. Type-checks a consumer+ * fixture that reads it from each envelope shape.+ */++import {describe, it, expect} from 'vitest';+import {spawnSync} from 'node:child_process';+import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';+import {createRequire} from 'node:module';+import {fileURLToPath} from 'node:url';++const INDEX = fileURLToPath(new URL('./index.ts', import.meta.url));+const TSC = createRequire(import.meta.url).resolve('typescript/bin/tsc');++const FIXTURE = `+import type {+ assertResponse,+ CLIError,+ CLIUnsupportedError,+ parseResponse,+} from ${JSON.stringify(INDEX)};++declare const error: CLIError;+declare const unsupported: CLIUnsupportedError;+declare const parsed: Exclude<ReturnType<typeof parseResponse>, CLIError | CLIUnsupportedError>;+declare const asserted: ReturnType<typeof assertResponse<'manifest'>>;++export const versions: number[] = [+ error.apiVersion,+ unsupported.apiVersion,+ parsed.apiVersion,+ asserted.apiVersion,+];+`;++describe('@astryxdesign/cli/json envelope types', () => {+ it('declare apiVersion on the success and error envelopes', () => {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-envelope-types-'));+ try {+ fs.writeFileSync(path.join(dir, 'fixture.ts'), FIXTURE);+ fs.writeFileSync(+ path.join(dir, 'tsconfig.json'),+ JSON.stringify({+ compilerOptions: {+ target: 'ES2022',+ module: 'ESNext',+ moduleResolution: 'bundler',+ strict: true,+ noEmit: true,+ skipLibCheck: true,+ allowImportingTsExtensions: true,+ // index.ts re-exports JSDoc types from .type.mjs files; read them+ // from source, as tsconfig.json-api.json does, not from generated+ // declarations that exist only after a build.+ allowJs: true,+ types: [],+ },+ files: ['fixture.ts'],+ }),+ );+ const res = spawnSync(process.execPath, [TSC, '-p', dir], {+ encoding: 'utf-8',+ timeout: 60_000,+ });+ expect(res.stdout + res.stderr).toBe('');+ expect(res.status).toBe(0);+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ }+ });+});diff --git a/packages/cli/api/json/parseResponse.doc.mjs b/packages/cli/api/json/parseResponse.doc.mjsindex 7fb50d1ee6..975007ec5e 100644--- a/packages/cli/api/json/parseResponse.doc.mjs+++ b/packages/cli/api/json/parseResponse.doc.mjs@@ -16,7 +16,7 @@ export const doc = {description:'The entry point for consuming the CLI as a subprocess. A JSON string is parsed; ' +'an already-parsed object is passed through unchanged, so it is safe to call on ' +- 'either. It returns the structural { type, data, meta? } envelope without narrowing: ' ++ 'either. It returns the structural { apiVersion, type, data, meta? } envelope without narrowing: ' +'`data` stays unknown until you discriminate on `type` (or use assertResponse).',importPath: '@astryxdesign/cli/json',signature: 'parseResponse(raw: unknown): any',@@ -34,7 +34,7 @@ export const doc = {{type: 'any',description:- 'The { type, data, meta? } envelope, or a CLIError envelope. The published signature is intentionally untyped; narrow it by casting to the matching *Response type exported from @astryxdesign/cli/json.',+ 'The { apiVersion, type, data, meta? } envelope, or a CLIError envelope ({ apiVersion, error, code, suggestions? }). The published signature is intentionally untyped; narrow it by casting to the matching *Response type exported from @astryxdesign/cli/json.',},],throws: [diff --git a/packages/cli/foundation/response/base.d.ts b/packages/cli/foundation/response/base.d.tsindex 1e55959dfe..9d26b40008 100644--- a/packages/cli/foundation/response/base.d.ts+++ b/packages/cli/foundation/response/base.d.ts@@ -29,6 +29,8 @@ export interface Suggestion {* human-readable `error` string, which changes freely.*/export interface CLIError {+ /** Version of the JSON envelope contract, as on the success envelope. */+ apiVersion: number;error: string;code: ErrorCode;suggestions?: Suggestion[];@@ -36,13 +38,15 @@ export interface CLIError {/** Returned by the fallback hook for commands without --json support. */export interface CLIUnsupportedError {+ apiVersion: number;error: `JSON output is not supported for the '${string}' command`;code: ErrorCode;}/**- * A success response envelope: a `type` discriminator, its `data` payload, and- * an optional `meta` sidecar (emitted as a sibling of `data`, never merged in).+ * A success response: a `type` discriminator, its `data` payload, and an+ * optional `meta` sidecar (emitted as a sibling of `data`, never merged in).+ * `--json` prints it with `apiVersion` added (see `parseResponse`).** Structural by design — there is no central union of every response `type`.* A specific command narrows `data` via its own return type.@@ -75,7 +79,7 @@ export function jsonError(/** Parse raw CLI output (string or object) into a typed result. */export function parseResponse(raw: unknown,-): CLIResponse | CLIError | CLIUnsupportedError;+): (CLIResponse & {apiVersion: number}) | CLIError | CLIUnsupportedError;/** Type guard: returns true if result is an error. */export function isError(@@ -90,7 +94,7 @@ export function isError(export function assertResponse<T extends string>(raw: unknown,type: T,-): CLIResponse & {type: T};+): CLIResponse & {apiVersion: number; type: T};declare global {namespace NodeJS {