Skip to content

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.md
new file mode 100644
index 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`.
+
+@josephfarina
diff --git a/packages/cli/api/json/envelope-types.test.mjs b/packages/cli/api/json/envelope-types.test.mjs
new file mode 100644
index 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.mjs
index 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.ts
index 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 {