An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): align swizzle.copy and Suggestion contract shapes with emitted data (#4273)
Joeyef8314c80645
diff --git a/.changeset/cli-type-integrity.md b/.changeset/cli-type-integrity.mdnew file mode 100644index 0000000000..5e62bee86c--- /dev/null+++ b/.changeset/cli-type-integrity.md@@ -0,0 +1,12 @@+---+'@astryxdesign/cli': patch+---++[fix] Align two `--json` contract shapes with what the CLI actually emits++- `swizzle.copy` payloads always include `package` and `usesStyleX` (both covered by tests), but `SwizzleCopyResponse.data` didn't declare them — the call site cast the payload to `Record<string, unknown>` to sidestep the mismatch. Added both fields to the type and dropped the loose cast so the payload is type-checked.+- The error `suggestions` shape was declared as `{name, reason}` (reason required) in the JSON envelope / API error contract, but some call sites emit bare `{name}` (e.g. candidate component names on swizzle). Introduced a single canonical `Suggestion` type (`reason?` optional) and referenced it everywhere so the contract matches the emitted data.++No runtime change.++@josephfarinadiff --git a/packages/cli/src/api/error.mjs b/packages/cli/src/api/error.mjsindex 359b852728..f079f1f9a8 100644--- a/packages/cli/src/api/error.mjs+++ b/packages/cli/src/api/error.mjs@@ -14,7 +14,7 @@import {ERROR_CODES} from '../lib/error-codes.mjs';export class AstryxError extends Error {- /** @type {Array<{name: string, reason: string}> | undefined} */+ /** @type {import('../types/base').Suggestion[] | undefined} */suggestions;/**@@ -26,7 +26,7 @@ export class AstryxError extends Error {/*** @param {string} message- * @param {Array<{name: string, reason: string}>} [suggestions]+ * @param {import('../types/base').Suggestion[]} [suggestions]* @param {string} [code] - Stable error code. Defaults to ERR_UNKNOWN.*/constructor(message, suggestions, code) {diff --git a/packages/cli/src/commands/swizzle.mjs b/packages/cli/src/commands/swizzle.mjsindex c0aa6ff326..96fea435e9 100644--- a/packages/cli/src/commands/swizzle.mjs+++ b/packages/cli/src/commands/swizzle.mjs@@ -358,7 +358,7 @@ export function registerSwizzle(program) {const feedback = buildFeedback(dirName, owner.issuesUrl);if (json) {- /** @type {Record<string, unknown>} */+ /** @type {import('../types/swizzle').SwizzleCopyResponse['data']} */const payload = {component: dirName,package: owner.package,diff --git a/packages/cli/src/lib/cli-error.mjs b/packages/cli/src/lib/cli-error.mjsindex d46f7f9158..9894e04840 100644--- a/packages/cli/src/lib/cli-error.mjs+++ b/packages/cli/src/lib/cli-error.mjs@@ -55,8 +55,8 @@ import {ERROR_CODES} from './error-codes.mjs';/*** Suggestion object — matches the shape used by API errors and the JSON- * envelope's `suggestions` field.- * @typedef {{name: string, reason?: string}} Suggestion+ * envelope's `suggestions` field. Canonical definition lives in types/base.+ * @typedef {import('../types/base').Suggestion} Suggestion*//**diff --git a/packages/cli/src/lib/json-shim.mjs b/packages/cli/src/lib/json-shim.mjsindex 717d5c70d8..e35fc0cada 100644--- a/packages/cli/src/lib/json-shim.mjs+++ b/packages/cli/src/lib/json-shim.mjs@@ -102,7 +102,7 @@ export function buildHelpEnvelope(cmd) {* for both success and error).** @param {string} message- * @param {Array<{name: string, reason: string}>} [suggestions]+ * @param {import('../types/base').Suggestion[]} [suggestions]* @param {string} [code] - Stable machine-readable error code (error-codes.mjs).*/function emitJsonError(message, suggestions, code) {diff --git a/packages/cli/src/lib/json.mjs b/packages/cli/src/lib/json.mjsindex d610c9a50d..a1f5acc04c 100644--- a/packages/cli/src/lib/json.mjs+++ b/packages/cli/src/lib/json.mjs@@ -112,10 +112,10 @@ export function jsonOut(type, data, meta) {* consumers can branch on it unconditionally.** @param {unknown} err- * @param {Array<{name: string, reason: string}>} [suggestions]+ * @param {import('../types/base').Suggestion[]} [suggestions]* @param {string} [code] - Explicit stable error code. Overrides any code* carried on a thrown Error.- * @returns {{apiVersion: number, error: string, code: string, suggestions?: Array<{name: string, reason: string}>}}+ * @returns {{apiVersion: number, error: string, code: string, suggestions?: import('../types/base').Suggestion[]}}*/export function toErrorEnvelope(err, suggestions, code) {const message =@@ -136,7 +136,7 @@ export function toErrorEnvelope(err, suggestions, code) {/*** Output a structured JSON error and exit.* @param {string} message- * @param {Array<{name: string, reason: string}>} [suggestions]+ * @param {import('../types/base').Suggestion[]} [suggestions]* @param {string} [code] - Stable machine-readable error code (error-codes.mjs).*/export function jsonError(message, suggestions, code) {diff --git a/packages/cli/src/types/api.d.ts b/packages/cli/src/types/api.d.tsindex e4b04cfb26..2ccca60360 100644--- a/packages/cli/src/types/api.d.ts+++ b/packages/cli/src/types/api.d.ts@@ -44,17 +44,14 @@ import type {import type {SearchResponse, SearchDomain} from './search';import type {ErrorCode} from './error-codes';import type {DoctorResponse} from './doctor';+import type {Suggestion} from './base';/** Structured API error with a stable machine-readable code. */export declare class AstryxError extends Error {/** Stable error code; consumers branch on this, never the message. */code: ErrorCode;- suggestions?: Array<{name: string; reason: string}>;- constructor(- message: string,- suggestions?: Array<{name: string; reason: string}>,- code?: ErrorCode,- );+ suggestions?: Suggestion[];+ constructor(message: string, suggestions?: Suggestion[], code?: ErrorCode);}// ── Component ────────────────────────────────────────────────────────@@ -100,9 +97,7 @@ export interface DocsOptions {}type DocsResult =- | DocsListResponse- | DocsDetailResponse- | DocsDetailSectionResponse;+ DocsListResponse | DocsDetailResponse | DocsDetailSectionResponse;export declare function docs(topic?: string,diff --git a/packages/cli/src/types/base.d.ts b/packages/cli/src/types/base.d.tsindex 799d0c6bfc..5728066f18 100644--- a/packages/cli/src/types/base.d.ts+++ b/packages/cli/src/types/base.d.ts@@ -56,6 +56,16 @@ import type {ManifestResponse} from './manifest';import type {DoctorResponse} from './doctor';import type {ValidateIntegrationResponse} from './validate-integration';+/**+ * A "did you mean…" suggestion attached to an error. `reason` is optional:+ * some call sites emit bare `{name}` (e.g. a list of candidate component names)+ * with no per-item explanation.+ */+export interface Suggestion {+ name: string;+ reason?: string;+}+/*** Structured error. Check `'error' in result` to discriminate.*@@ -65,7 +75,7 @@ import type {ValidateIntegrationResponse} from './validate-integration';export interface CLIError {error: string;code: ErrorCode;- suggestions?: Array<{name: string; reason: string}>;+ suggestions?: Suggestion[];}/** Returned by the fallback hook for commands without --json support. */@@ -140,7 +150,7 @@ export function jsonOut<T extends CLIResponseType>(*/export function jsonError(message: string,- suggestions?: Array<{name: string; reason: string}>,+ suggestions?: Suggestion[],code?: ErrorCode,): never;diff --git a/packages/cli/src/types/swizzle.d.ts b/packages/cli/src/types/swizzle.d.tsindex 172605ef8f..1ed7e921d8 100644--- a/packages/cli/src/types/swizzle.d.ts+++ b/packages/cli/src/types/swizzle.d.ts@@ -29,9 +29,13 @@ export interface SwizzleCopyResponse {type: 'swizzle.copy';data: {component: string;+ /** Owner package the component source was copied from. */+ package: string;outputDir: string;filesCopied: number;files: string[];+ /** Whether any copied file uses StyleX (requires build-time setup). */+ usesStyleX: boolean;feedback?: SwizzleFeedback;};}