@astryxdesign/cli 0.1.7 → 0.1.8-canary.07362a9

package/{src/types → types}/base.d.ts

@@ -11,10 +11,12 @@
 import type {
   ComponentListResponse,
   ComponentBriefResponse,
+  ComponentFullResponse,
   ComponentDetailResponse,
   ComponentDetailPropsResponse,
   ComponentDetailSourceResponse,
   ComponentDetailShowcaseResponse,
+  ComponentDetailBlocksResponse,
 } from './component';
 import type {
   DiscoverListResponse,
@@ -41,14 +43,38 @@ import type {
   HookDetailParamsResponse,
 } from './hook';
 import type {SwizzleListResponse, SwizzleCopyResponse} from './swizzle';
-import type {ThemeBuildResponse} from './theme';
-import type {UpgradeListResponse, UpgradeRunResponse} from './upgrade';
+import type {
+  ThemeBuildResponse,
+  ThemeListResponse,
+  ThemeAddResponse,
+} from './theme';
+import type {
+  UpgradeListResponse,
+  UpgradeRunResponse,
+  UpgradeStatusResponse,
+} from './upgrade';
 import type {SearchResponse} from './search';
+import type {
+  LayoutExpandResponse,
+  LayoutCheckResponse,
+  LayoutGrammarResponse,
+} from './layout';
+import type {BuildHelpResponse, BuildKitResponse} 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 +84,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 +100,12 @@ export type CLIResult<T> = T | CLIError | CLIUnsupportedError;
 export type CLIAnyResponse =
   | ComponentListResponse
   | ComponentBriefResponse
+  | ComponentFullResponse
   | ComponentDetailResponse
   | ComponentDetailPropsResponse
   | ComponentDetailSourceResponse
   | ComponentDetailShowcaseResponse
+  | ComponentDetailBlocksResponse
   | DiscoverListResponse
   | DiscoverDetailResponse
   | DiscoverDetailDocResponse
@@ -97,9 +125,17 @@ export type CLIAnyResponse =
   | SwizzleListResponse
   | SwizzleCopyResponse
   | ThemeBuildResponse
+  | ThemeListResponse
+  | ThemeAddResponse
   | UpgradeListResponse
   | UpgradeRunResponse
+  | UpgradeStatusResponse
   | SearchResponse
+  | LayoutExpandResponse
+  | LayoutCheckResponse
+  | LayoutGrammarResponse
+  | BuildHelpResponse
+  | BuildKitResponse
   | ManifestResponse
   | DoctorResponse
   | ValidateIntegrationResponse;
@@ -129,7 +165,7 @@ export function jsonOut<T extends CLIResponseType>(
  */
 export function jsonError(
   message: string,
-  suggestions?: Array<{name: string; reason: string}>,
+  suggestions?: Suggestion[],
   code?: ErrorCode,
 ): never;
 

package/types/build.d.ts

@@ -0,0 +1,53 @@
+// 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>"     -> build.kit
+ */
+
+import type {SearchResultEntry} from './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;
+  };
+}
+
+/**
+ * xds --json build "<idea>" — the composition kit for what you're building.
+ *
+ * Entries are raw `SearchResultEntry` objects (no package-manager-prefixed
+ * command strings — the CLI adds those); `frame`/`foundation` are static
+ * component-name arrays surfaced on every kit.
+ */
+export interface BuildKitResponse {
+  type: 'build.kit';
+  data: {
+    query: string;
+    /** False when search returned nothing (renderer shows "No matches"). */
+    hasResults: boolean;
+    /** True when the top page template is a confident direct match. */
+    directMatch: boolean;
+    /** Closest page templates (≤3). */
+    pages: SearchResultEntry[];
+    /** Drop-in block patterns covering parts of the idea (≤5). */
+    blocks: SearchResultEntry[];
+    /** Idea-specific components/hooks (≤6), excluding frame/foundation. */
+    domain: SearchResultEntry[];
+    /** Always-on page-shell component names. */
+    frame: string[];
+    /** Always-on layout/typography/action component names. */
+    foundation: string[];
+  };
+}

package/types/codemod.d.ts

@@ -0,0 +1,166 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Public type surface for the file-based codemod-authoring API exported from
+ * `@astryxdesign/cli/codemod`.
+ */
+
+/** A single source file presented to a codemod's transform. */
+export interface AstryxCodemodFile {
+  /** Absolute path to the file being transformed. */
+  path: string;
+  /** The current source contents of the file. */
+  source: string;
+}
+
+/** Helpers and context passed to a codemod's transform as the second argument. */
+export interface AstryxCodemodApi {
+  /** A jscodeshift instance configured with a parser for the file. */
+  jscodeshift: unknown;
+  /** Report a statistic (no-op-friendly; provided for jscodeshift parity). */
+  stats: (...args: unknown[]) => void;
+  /** Report progress (no-op-friendly; provided for jscodeshift parity). */
+  report: (...args: unknown[]) => void;
+}
+
+/**
+ * A codemod's transform. Return the new source to rewrite the file, or
+ * `null`/`undefined` to leave the file unchanged.
+ */
+export type AstryxCodemodTransform = (
+  file: AstryxCodemodFile,
+  api: AstryxCodemodApi,
+) => string | null | undefined;
+
+/** Definition accepted by {@link createCodemod}. */
+export interface AstryxCodemodDef {
+  /** Short, human-readable title shown in upgrade output. */
+  title: string;
+  /** Optional longer description. */
+  description?: string;
+  /** When true, the codemod runs only when explicitly requested. */
+  isOptional?: boolean;
+  /** File extensions this codemod applies to (e.g. ['.tsx', '.ts']). */
+  fileExtensions?: string[];
+  /** The transform function. */
+  transform: AstryxCodemodTransform;
+}
+
+/** Result of {@link createCodemod}. */
+export interface AstryxCodemod extends AstryxCodemodDef {
+  isOptional: boolean;
+  type: 'code';
+}
+
+/** Definition accepted by {@link createConfigCodemod}. */
+export interface AstryxConfigCodemodDef {
+  /** Short, human-readable title shown in upgrade output. */
+  title: string;
+  /** Optional longer description. */
+  description?: string;
+  /** When true, the codemod runs only when explicitly requested. */
+  isOptional?: boolean;
+  /** The transform function applied to the astryx.config.* file. */
+  transform: AstryxCodemodTransform;
+}
+
+/** Result of {@link createConfigCodemod}. */
+export interface AstryxConfigCodemod extends AstryxConfigCodemodDef {
+  isOptional: boolean;
+  type: 'config';
+}
+
+/** Define a file-transforming codemod. */
+export declare function createCodemod<T extends AstryxCodemodDef>(
+  def: T,
+): AstryxCodemod;
+
+/** Define a codemod that targets the consumer's astryx.config.* file. */
+export declare function createConfigCodemod<T extends AstryxConfigCodemodDef>(
+  def: T,
+): AstryxConfigCodemod;
+
+// ---------------------------------------------------------------------------
+// Internal types (used by the CLI codemod runner infrastructure & transforms).
+// These are not part of the public authoring surface but are shared across the
+// .mjs files under src/codemods/ so JSDoc annotations stay consistent.
+// ---------------------------------------------------------------------------
+
+/**
+ * jscodeshift transform signature. jscodeshift ships no type declarations, so
+ * the AST surface (`api.jscodeshift`, paths, node attributes) is untyped by
+ * design; transforms operate on it dynamically.
+ */
+export type CodemodTransform = (
+  file: AstryxCodemodFile,
+  api: CodemodTransformApi,
+) => string | null | undefined;
+
+/**
+ * The `api` argument as seen INSIDE a transform implementation. Identical to
+ * {@link AstryxCodemodApi} except `jscodeshift` is typed as the callable
+ * factory (jscodeshift ships no types, so the AST it returns is untyped). Used
+ * by the .mjs transforms so `const j = api.jscodeshift; j(file.source)` type-checks.
+ */
+export interface CodemodTransformApi {
+  jscodeshift: JscodeshiftFactory;
+  stats: (...args: unknown[]) => void;
+  report: (...args: unknown[]) => void;
+}
+
+/**
+ * A normalized codemod entry as produced by both the core registry runner and
+ * integration discovery. See the header of `run-codemod.mjs` for the contract.
+ */
+export interface CodemodEntry {
+  /** Unique id within its package/version (e.g. the transform module name). */
+  id: string;
+  /** Whether this is a source-file codemod or a config-file codemod. */
+  type: 'code' | 'config';
+  /** The codemod itself. */
+  codemod: {
+    title: string;
+    description?: string;
+    isOptional?: boolean;
+    fileExtensions?: string[];
+    transform: CodemodTransform;
+  };
+  /** Owning package name. */
+  package: string;
+  /** Owning package version. */
+  version?: string;
+}
+
+/** The result of running a single codemod over one or more files. */
+export interface CodemodRunResult {
+  filesChanged: number;
+  writtenFiles: string[];
+  errors: Array<{file: string; codemod: string; error: string}>;
+}
+
+/** The console-like log surface used across the codemod runners. */
+export interface CliLog {
+  step: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  success: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+  message?: (...args: unknown[]) => void;
+}
+
+/**
+ * The jscodeshift factory (the module's default export / `withParser` root).
+ * Callable and carries `withParser`; both return an untyped jscodeshift API.
+ *
+ * `any` is unavoidable here: jscodeshift ships no types and its AST/builder
+ * surface is fully dynamic (`j(src)`, `j.JSXElement`, `path.node`, …). `unknown`
+ * would break the callable + index access the transforms rely on.
+ */
+export interface JscodeshiftFactory {
+  /* eslint-disable @typescript-eslint/no-explicit-any */
+  (...args: any[]): any;
+  withParser: (parser: string) => any;
+  /** AST node types and builders (j.JSXElement, j.jsxAttribute, ...) are untyped. */
+  [key: string]: any;
+  /* eslint-enable @typescript-eslint/no-explicit-any */
+}

package/{src/types → types}/component.d.ts

@@ -23,7 +23,7 @@
  * (not found)                               -> CLIError
  */
 
-import type {ComponentDoc, PropDoc} from '../../../core/src/docs-types';
+import type {ComponentDoc, PropDoc} from '../../core/src/docs-types';
 
 /** xds --json component [--list] [--category X] [--detail brief] */
 export interface ComponentListResponse {

package/{src/types → types}/discover.d.ts

@@ -13,7 +13,7 @@
  * (not found)                                    -> CLIError
  */
 
-import type {ComponentDoc} from '../../../core/src/docs-types';
+import type {ComponentDoc} from '../../core/src/docs-types';
 
 /** xds --json discover */
 export interface DiscoverListResponse {

package/{src/types → types}/docs.d.ts

@@ -11,10 +11,7 @@
  * (unknown topic/section)                   -> CLIError
  */
 
-import type {
-  ReferenceDoc,
-  ReferenceSection,
-} from '../../../core/src/docs-types';
+import type {ReferenceDoc, ReferenceSection} from '../../core/src/docs-types';
 
 /** xds --json docs */
 export interface DocsListResponse {

package/{src/types → types}/hook.d.ts

@@ -20,7 +20,7 @@
  * (not found)                               -> CLIError
  */
 
-import type {HookDoc, HookParamDoc} from '../../../core/src/docs-types';
+import type {HookDoc, HookParamDoc} from '../../core/src/docs-types';
 
 /** xds --json hook [--list] [--category X] [--detail brief] */
 export interface HookListResponse {

package/{src/types → 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/types/jscodeshift.d.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Ambient declaration for `jscodeshift`, which ships no type declarations.
+ * The AST surface is intentionally untyped; codemod transforms operate on it
+ * dynamically. This keeps dynamic `import('jscodeshift')` from tripping TS7016
+ * under strict checkJs.
+ */
+declare module 'jscodeshift' {
+  interface JscodeshiftFactory {
+    /* eslint-disable @typescript-eslint/no-explicit-any */
+    (...args: any[]): any;
+    withParser: (parser: string) => any;
+    [key: string]: any;
+    /* eslint-enable @typescript-eslint/no-explicit-any */
+  }
+  const jscodeshift: JscodeshiftFactory;
+  export default jscodeshift;
+}

package/types/layout.d.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Layout command JSON responses.
+ *
+ * `astryx layout expand|check|grammar` turn compressed XLE/XLO expressions into
+ * validated XDS TSX (or echo canonical surfaces / a grammar cheatsheet).
+ *
+ * Invocation                                 -> type discriminator
+ * -----------------------------------------------------------------
+ * astryx --json layout expand "<expr>"       -> layout.expand
+ * astryx --json layout check "<expr>"        -> layout.check
+ * astryx --json layout grammar               -> layout.grammar
+ */
+
+/** The input surface an expression was parsed as. */
+export type LayoutForm = 'compact' | 'outline' | 'auto';
+
+/** A validation issue with its formatted, human-readable rendering. */
+export interface LayoutIssue {
+  line?: number;
+  col?: number;
+  message: string;
+  formatted: string;
+  suggestions?: string[];
+}
+
+/** A block referenced by a layout expression and how it was spliced in. */
+export interface LayoutBlockReference {
+  name: string;
+  mode: string;
+}
+
+/** astryx --json layout expand "<expr>" [path] */
+export interface LayoutExpandResponse {
+  type: 'layout.expand';
+  data: {
+    form: LayoutForm;
+    code: string;
+    componentsUsed: string[];
+    /** Number of useState hooks the expansion scaffolded. */
+    states: number;
+    todos: string[];
+    blocksReferenced: LayoutBlockReference[];
+    warnings: string[];
+    written: string | null;
+  };
+}
+
+/** astryx --json layout check "<expr>" */
+export interface LayoutCheckResponse {
+  type: 'layout.check';
+  data: {
+    valid: boolean;
+    form: LayoutForm;
+    errors: LayoutIssue[];
+    warnings: string[];
+    compact: string;
+    outline: string;
+  };
+}
+
+/** astryx --json layout grammar */
+export interface LayoutGrammarResponse {
+  type: 'layout.grammar';
+  data: {
+    text: string;
+    /** Alias table (short name -> canonical component), from the registry. */
+    aliases: Record<string, string>;
+  };
+}
+
+export type LayoutResponse =
+  LayoutExpandResponse | LayoutCheckResponse | LayoutGrammarResponse;

package/{src/types → 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/types → types}/template-api.d.ts

@@ -15,4 +15,7 @@ export type {
   AstryxTemplate,
 } from '@astryxdesign/core/authoring';
 
-export {createPageTemplate, createBlockTemplate} from '@astryxdesign/core/authoring';
+export {
+  createPageTemplate,
+  createBlockTemplate,
+} from '@astryxdesign/core/authoring';

package/types/theme.d.ts

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Theme build command JSON responses.
+ *
+ * Invocation                                 -> type discriminator
+ * ------------------------------------------------------------------
+ * xds --json theme build <file>             -> theme.build
+ * xds --json theme list                     -> theme.list
+ * xds --json theme add <slug>               -> theme.add
+ * (file not found / parse error)            -> CLIError
+ */
+
+/** xds --json theme build <file> */
+export interface ThemeBuildResponse {
+  type: 'theme.build';
+  data: {
+    name: string;
+    tokenCount: number;
+    componentCount: number;
+    sizeKB: number;
+    outputs: {css: string; js: string; dts: string; variantsDts?: string};
+    warnings: string[];
+  };
+}
+
+/** A single theme entry as surfaced by `theme list`. */
+export interface ThemeListEntry {
+  slug: string;
+  displayName: string;
+  description: string;
+  maintained: boolean;
+}
+
+/** xds --json theme list */
+export interface ThemeListResponse {
+  type: 'theme.list';
+  data: ThemeListEntry[];
+}
+
+/** xds --json theme add <slug> */
+export interface ThemeAddResponse {
+  type: 'theme.add';
+  data: {
+    slug: string;
+    displayName: string;
+    maintained: boolean;
+    outputDir: string;
+    entry: string;
+    exportName: string;
+    files: string[];
+  };
+}

package/types/upgrade.d.ts

@@ -0,0 +1,108 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Upgrade command JSON responses.
+ *
+ * Invocation                                 -> type discriminator
+ * ------------------------------------------------------------------
+ * xds --json upgrade --list                 -> upgrade.list
+ * xds --json upgrade [--apply]              -> upgrade.run
+ * xds --json upgrade (status short-circuit) -> upgrade.status
+ * (version detection failure)               -> CLIError
+ */
+
+/** xds --json upgrade --list */
+export interface UpgradeListResponse {
+  type: 'upgrade.list';
+  data: UpgradeListEntry[];
+}
+
+export interface UpgradeListEntry {
+  name: string;
+  title: string;
+  version: string;
+}
+
+/**
+ * State of the managed agent-docs block (`<!-- ASTRYX:START --> … END -->`)
+ * relative to the installed core version, plus what `upgrade` did about it.
+ * Present on every upgrade response (run, status, and the codemod/config error
+ * envelopes) because the block is refreshed independently of codemods.
+ *
+ * - `refreshed`     — a stale block was rewritten (`--apply` only).
+ * - `would-refresh` — a stale block was detected in dry-run; nothing written.
+ * - `nudge-init`    — no managed block exists; user should run `init`.
+ * - `error`         — refresh was attempted but writing failed.
+ * - `none`          — nothing to do (block already current).
+ */
+export interface AgentDocsSummary {
+  status: 'missing' | 'stale' | 'current';
+  /** Installed core version the block should reflect. */
+  installedVersion: string;
+  /** Distinct stale block versions found (the "from" side of the refresh). */
+  fromVersions: string[];
+  /** Files rewritten (apply) or that would be rewritten (dry-run). */
+  files: string[];
+  /** True only when a block was actually rewritten (apply mode). */
+  refreshed: boolean;
+  action: 'refreshed' | 'would-refresh' | 'nudge-init' | 'error' | 'none';
+}
+
+/** xds --json upgrade [--apply] */
+export interface UpgradeRunResponse {
+  type: 'upgrade.run';
+  data: {
+    from: string;
+    to: string;
+    codemods: number;
+    /** Integration packages processed in this upgrade (by name/spec). */
+    integrations: string[];
+    agentDocsRefreshed: boolean;
+    agentDocs: AgentDocsSummary;
+    /** Total files changed across core + integration codemods (apply mode). */
+    filesChanged?: number;
+    /** Total transforms that reported a change. */
+    transformsApplied?: number;
+    /** Per-codemod errors, when any codemod failed. */
+    errors?: Array<{file: string; codemod: string; error: string}>;
+  };
+}
+
+/**
+ * xds --json upgrade — short-circuit status results.
+ *
+ * - `up_to_date`: `--from` is >= installed target and `--force` was not passed.
+ * - `no_codemods`: no codemods (core or integration) apply to the range.
+ * - `config_fixable`: DRY-RUN ONLY. The consumer's astryx.config currently
+ *   fails strict validation, but a pending core CONFIG codemod (in the selected
+ *   range) would repair it. The dry run previews the fix without writing and
+ *   reports the exact command to apply it; integrations are skipped for the
+ *   preview (they will be processed on the `--apply` run).
+ */
+export interface UpgradeStatusResponse {
+  type: 'upgrade.status';
+  data:
+    | {
+        status: 'up_to_date';
+        from: string;
+        to: string;
+        agentDocs: AgentDocsSummary;
+      }
+    | {
+        status: 'no_codemods';
+        from: string;
+        to: string;
+        agentDocs: AgentDocsSummary;
+      }
+    | {
+        status: 'config_fixable';
+        from: string;
+        to: string;
+        configError: string;
+        configCodemods: string[];
+        suggestedCommand: string;
+        message: string;
+        note: string;
+        agentDocs: AgentDocsSummary;
+      };
+}