@astryxdesign/cli 0.1.8-canary.4a7ce02 → 0.1.8-canary.4fe3df0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.8-canary.4a7ce02",
+  "version": "0.1.8-canary.4fe3df0",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -79,10 +79,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.1.8-canary.4a7ce02",
-    "@astryxdesign/core": "0.1.8-canary.4a7ce02",
-    "@astryxdesign/lab": "0.1.8-canary.4a7ce02",
-    "@astryxdesign/theme-neutral": "0.1.8-canary.4a7ce02",
+    "@astryxdesign/charts": "0.1.8-canary.4fe3df0",
+    "@astryxdesign/core": "0.1.8-canary.4fe3df0",
+    "@astryxdesign/lab": "0.1.8-canary.4fe3df0",
+    "@astryxdesign/theme-neutral": "0.1.8-canary.4fe3df0",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -100,10 +100,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.1.8-canary.4a7ce02",
-    "@astryxdesign/core": "0.1.8-canary.4a7ce02",
-    "@astryxdesign/lab": "0.1.8-canary.4a7ce02",
-    "@astryxdesign/theme-neutral": "0.1.8-canary.4a7ce02",
+    "@astryxdesign/charts": "0.1.8-canary.4fe3df0",
+    "@astryxdesign/core": "0.1.8-canary.4fe3df0",
+    "@astryxdesign/lab": "0.1.8-canary.4fe3df0",
+    "@astryxdesign/theme-neutral": "0.1.8-canary.4fe3df0",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {

package/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) {

package/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,

package/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
  */
 
 /**

package/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) {

package/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) {

package/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,

package/src/types/base.d.ts

@@ -11,10 +11,12 @@
 import type {
   ComponentListResponse,
   ComponentBriefResponse,
+  ComponentFullResponse,
   ComponentDetailResponse,
   ComponentDetailPropsResponse,
   ComponentDetailSourceResponse,
   ComponentDetailShowcaseResponse,
+  ComponentDetailBlocksResponse,
 } from './component';
 import type {
   DiscoverListResponse,
@@ -42,13 +44,28 @@ import type {
 } from './hook';
 import type {SwizzleListResponse, SwizzleCopyResponse} from './swizzle';
 import type {ThemeBuildResponse} from './theme';
-import type {UpgradeListResponse, UpgradeRunResponse} from './upgrade';
+import type {
+  UpgradeListResponse,
+  UpgradeRunResponse,
+  UpgradeStatusResponse,
+} from './upgrade';
 import type {SearchResponse} from './search';
+import type {BuildHelpResponse} from './build';
 import type {ErrorCode} from './error-codes';
 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.
  *
@@ -58,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. */
@@ -74,10 +91,12 @@ export type CLIResult<T> = T | CLIError | CLIUnsupportedError;
 export type CLIAnyResponse =
   | ComponentListResponse
   | ComponentBriefResponse
+  | ComponentFullResponse
   | ComponentDetailResponse
   | ComponentDetailPropsResponse
   | ComponentDetailSourceResponse
   | ComponentDetailShowcaseResponse
+  | ComponentDetailBlocksResponse
   | DiscoverListResponse
   | DiscoverDetailResponse
   | DiscoverDetailDocResponse
@@ -99,7 +118,9 @@ export type CLIAnyResponse =
   | ThemeBuildResponse
   | UpgradeListResponse
   | UpgradeRunResponse
+  | UpgradeStatusResponse
   | SearchResponse
+  | BuildHelpResponse
   | ManifestResponse
   | DoctorResponse
   | ValidateIntegrationResponse;
@@ -129,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;
 

package/src/types/build.d.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Build command JSON responses.
+ *
+ * `astryx build` is the "assemble a page" verb. With no query it emits the
+ * workflow playbook; with a query it delegates to the search pipeline and
+ * emits a `search` response (see search.d.ts).
+ *
+ * Invocation                    -> type discriminator
+ * ---------------------------------------------------
+ * xds --json build              -> build.help
+ * xds --json build "<idea>"     -> search
+ */
+
+/** xds --json build (no query) — the "how to build a page" playbook signal. */
+export interface BuildHelpResponse {
+  type: 'build.help';
+  data: {
+    /** Always true; marks this envelope as the playbook rather than a result set. */
+    playbook: true;
+  };
+}

package/src/types/index.d.ts

@@ -10,6 +10,7 @@ export * from './swizzle';
 export * from './theme';
 export * from './upgrade';
 export * from './search';
+export * from './build';
 export * from './error-codes';
 export * from './manifest';
 export * from './doctor';

package/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;
   };
 }

package/src/utils/package-manager.mjs

@@ -10,15 +10,41 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+/**
+ * A package manager we can install with and run binaries through.
+ * @typedef {'yarn' | 'pnpm' | 'bun' | 'npm'} PackageManager
+ */
+
+/**
+ * Result of package-manager detection. `'npx'` is the sentinel for "nothing
+ * detected" — no lockfile, no `packageManager` field, no runner user-agent —
+ * so callers fall back to npm/npx. It is a distinct value from {@link PackageManager}
+ * because it means "undetected", not "npm was chosen".
+ * @typedef {PackageManager | 'npx'} DetectedPackageManager
+ */
+
+/** @type {readonly PackageManager[]} */
+const KNOWN_PMS = ['yarn', 'pnpm', 'bun', 'npm'];
+
+/**
+ * Narrow an arbitrary string to a known {@link PackageManager}.
+ * @param {string} name
+ * @returns {name is PackageManager}
+ */
+function isKnownPackageManager(name) {
+  return /** @type {readonly string[]} */ (KNOWN_PMS).includes(name);
+}
+
 /**
  * Detect the package manager used in a project directory.
  * Walks up from targetDir looking for lockfiles.
  *
+ * Returns `'npx'` when nothing can be detected — see {@link DetectedPackageManager}.
+ *
  * @param {string} [targetDir=process.cwd()]
- * @returns {'yarn'|'pnpm'|'bun'|'npm'}
+ * @returns {DetectedPackageManager}
  */
 export function detectPackageManager(targetDir = process.cwd()) {
-  const KNOWN_PMS = new Set(['yarn', 'pnpm', 'bun', 'npm']);
   let dir = path.resolve(targetDir);
   const root = path.parse(dir).root;
 
@@ -36,7 +62,7 @@ export function detectPackageManager(targetDir = process.cwd()) {
         const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
         if (pkg.packageManager) {
           const name = pkg.packageManager.split('@')[0];
-          if (KNOWN_PMS.has(name)) return name;
+          if (isKnownPackageManager(name)) return name;
         }
       } catch {
         // Best-effort: unreadable/invalid package.json — keep walking up.
@@ -50,7 +76,7 @@ export function detectPackageManager(targetDir = process.cwd()) {
   const ua = process.env.npm_config_user_agent;
   if (ua) {
     const name = ua.split('/')[0];
-    if (KNOWN_PMS.has(name)) return name;
+    if (isKnownPackageManager(name)) return name;
   }
 
   return 'npx';

package/src/utils/update-check.mjs

@@ -18,9 +18,9 @@ import {getCliInvocation} from './package-manager.mjs';
 
 /**
  * Read the latest available version from local signals.
- * No network calls — purely filesystem and env var checks.
+ * No network calls — purely an env-var check ($ASTRYX_LATEST_VERSION),
+ * so it takes no arguments.
  *
- * @param {string} [cwd] - Project directory (default: process.cwd())
  * @returns {string|null} Latest version string, or null if unknown
  */
 export function getLatestVersion() {
@@ -64,7 +64,7 @@ export function getInstalledVersion(cwd = process.cwd()) {
  * @returns {string|null} FYI hint string, or null if up to date / unknown
  */
 export function checkForUpdate(cwd = process.cwd()) {
-  const latest = getLatestVersion(cwd);
+  const latest = getLatestVersion();
   if (!latest) return null;
 
   // Persist for subsequent commands in this shell session

package/src/utils/update-check.test.mjs

@@ -33,12 +33,12 @@ afterEach(() => {
 describe('getLatestVersion', () => {
   it('reads from ASTRYX_LATEST_VERSION env var', () => {
     process.env.ASTRYX_LATEST_VERSION = '0.0.8';
-    expect(getLatestVersion(tmpDir)).toBe('0.0.8');
+    expect(getLatestVersion()).toBe('0.0.8');
   });
 
   it('ignores invalid env var values', () => {
     process.env.ASTRYX_LATEST_VERSION = 'not-a-version';
-    expect(getLatestVersion(tmpDir)).toBeNull();
+    expect(getLatestVersion()).toBeNull();
   });
 
   it('returns null when no signals exist', () => {
@@ -46,7 +46,7 @@ describe('getLatestVersion', () => {
       path.join(tmpDir, 'package.json'),
       JSON.stringify({name: 'test'}),
     );
-    expect(getLatestVersion(tmpDir)).toBeNull();
+    expect(getLatestVersion()).toBeNull();
   });
 });