Skip to content

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.md
new file mode 100644
index 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.
+
+@josephfarina
diff --git a/packages/cli/src/api/error.mjs b/packages/cli/src/api/error.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.ts
index 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.ts
index 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.ts
index 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;
};
}