@astryxdesign/cli 0.1.1 → 0.1.2-canary.043f3fd

package/src/types/component.d.ts

@@ -28,7 +28,18 @@ import type {ComponentDoc, PropDoc} from '../../../core/src/docs-types';
 /** xds --json component [--list] [--category X] [--detail brief] */
 export interface ComponentListResponse {
   type: 'component.list';
-  data: Record<string, string[]>;
+  data: Record<string, ComponentListEntry[]>;
+}
+
+/**
+ * A single entry in a `component.list` group. Pre-1.0 the list moved from bare
+ * strings to package-qualified objects so consumers can disambiguate ownership
+ * (core vs. an integration package).
+ */
+export interface ComponentListEntry {
+  name: string;
+  /** Owner package, e.g. '@astryxdesign/core' or '@acme/astryx-meta'. */
+  package: string;
 }
 
 /** xds --json component --list --detail compact */
@@ -52,7 +63,21 @@ export interface ComponentFullResponse {
 /** xds --json component <name> */
 export interface ComponentDetailResponse {
   type: 'component.detail';
-  data: ComponentDoc;
+  data: ComponentDoc & ComponentOwnership;
+}
+
+/**
+ * Ownership metadata attached to every `component.detail` payload. Exposes the
+ * owner package, the import specifier, and whether a swizzleable source file is
+ * available — the inputs the integration-component swizzle (a later PR) needs.
+ */
+export interface ComponentOwnership {
+  /** Owner package, e.g. '@astryxdesign/core' or an integration package name. */
+  package: string;
+  /** Import specifier for the component (e.g. '@astryxdesign/core/Button'). */
+  import: string;
+  /** Whether a component source file exists for `--source` / swizzle. */
+  sourceAvailable: boolean;
 }
 
 /** xds --json component <name> --props */

package/src/types/config.d.ts

@@ -0,0 +1,70 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * A command to run as part of a post-codemod hook. Returned by a hook's
+ * `buildCommand` and executed via `execFile` after codemods write files.
+ */
+export interface PostCodemodCommand {
+  command: string;
+  args?: string[];
+  options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeout?: number;
+  };
+}
+
+/**
+ * A post-codemod hook. `buildCommand` receives the package directory and the
+ * list of files changed by codemods, and returns the command to run (or a
+ * nullish value to skip).
+ */
+export type PostCodemodHook = {
+  name?: string;
+  buildCommand: (ctx: {
+    packageDir: string;
+    files: string[];
+  }) =>
+    | PostCodemodCommand
+    | null
+    | undefined
+    | Promise<PostCodemodCommand | null | undefined>;
+};
+
+/** A component XLE layout expressions can reference by name via `{hint}`. */
+export interface XleComponent {
+  /** Import specifier the component is imported from, e.g. '@/components/KpiCard'. */
+  from: string;
+  /** Optional human description shown in tooling. */
+  description?: string;
+  /** Import as the module's default export instead of a named export. Defaults to false. */
+  default?: boolean;
+}
+
+/** User config exported from astryx.config.{ts,mjs,js}. */
+export interface AstryxConfig {
+  /** Integration package names to load. */
+  integrations?: string[];
+  /** Where to file issues/feedback for this project. */
+  issuesUrl?: string;
+  /** Lifecycle hooks. */
+  hooks?: {
+    postCodemod?: PostCodemodHook[];
+  };
+  /**
+   * EXPERIMENTAL — shape may change and is not part of the stable config
+   * contract. Provisional home for features still being proven out.
+   */
+  experimental?: {
+    /** Experimental XLE (layout expression) configuration. */
+    xle?: {
+      /**
+       * Register app-local components so XLE layout expressions can
+       * reference them by name via {hint}. Keyed by component name.
+       */
+      components?: Record<string, XleComponent>;
+    };
+  };
+}
+
+export declare function createConfig<T extends AstryxConfig>(config: T): T;

package/src/types/error-codes.d.ts

@@ -25,6 +25,9 @@ export type ErrorCode =
   | 'ERR_UNKNOWN_SECTION'
   | 'ERR_UNKNOWN_CATEGORY'
   | 'ERR_UNKNOWN_TEMPLATE'
+  | 'ERR_AMBIGUOUS_TEMPLATE'
+  | 'ERR_AMBIGUOUS_COMPONENT'
+  | 'ERR_UNKNOWN_THEME'
   | 'ERR_UNKNOWN_PACKAGE'
   | 'ERR_UNKNOWN_AGENT'
   | 'ERR_UNKNOWN_FEATURE'
@@ -41,13 +44,12 @@ export type ErrorCode =
   | 'ERR_WRITE_FAILED'
   | 'ERR_THEME_INVALID'
   | 'ERR_THEME_LOAD'
-  | 'ERR_TEMPLATE_CONFIG'
-  | 'ERR_TEMPLATE_GET'
   | 'ERR_VERSION_DETECT'
   | 'ERR_INVALID_VERSION'
   | 'ERR_DEP_MISSING'
   | 'ERR_GH_CLI'
-  | 'ERR_GAP_REPORT_FAILED';
+  | 'ERR_LAYOUT_PARSE'
+  | 'ERR_LAYOUT_INVALID';
 
 /** The frozen runtime map of all error codes (keys === values). */
 export declare const ERROR_CODES: Readonly<Record<ErrorCode, ErrorCode>>;

package/src/types/index.d.ts

@@ -8,7 +8,6 @@ export * from './template';
 export * from './hook';
 export * from './swizzle';
 export * from './theme';
-export * from './gap-report';
 export * from './upgrade';
 export * from './search';
 export * from './error-codes';

package/src/types/integration.d.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Integration manifest exported from a conventional root manifest file
+ * (astryx.integration.{ts,mjs,js}) sibling to the integration package's
+ * package.json. Identity (name/version) comes from the package's
+ * package.json, not from the manifest.
+ */
+export interface AstryxIntegration {
+  /** Relative path to the components/docs root (resolved to absolute). */
+  components?: string;
+  /** Relative path to the templates root (resolved to absolute). */
+  templates?: string;
+  /** Relative path to the codemods root (resolved to absolute). */
+  codemods?: string;
+  /** Where to file issues/feedback for this integration. */
+  issuesUrl?: string;
+}
+
+/** An issue surfaced by an integration. */
+export interface AstryxIntegrationIssue {
+  code: string;
+  severity: 'warning' | 'error';
+  message: string;
+}
+
+export declare function createIntegration<T extends AstryxIntegration>(
+  integration: T,
+): T;

package/src/types/swizzle.d.ts

@@ -7,7 +7,6 @@
  * ------------------------------------------------------------------
  * xds --json swizzle [--list]               -> swizzle.list
  * xds --json swizzle <component>            -> swizzle.copy
- * xds --json swizzle <component> --gap "x"  -> swizzle.copy (with gapReport)
  * (not found)                               -> CLIError
  */
 
@@ -17,6 +16,14 @@ export interface SwizzleListResponse {
   data: string[];
 }
 
+/** Maintainer feedback note emitted after a successful swizzle. */
+export interface SwizzleFeedback {
+  /** Where to report the gap that led to swizzling. */
+  issuesUrl: string;
+  /** Ready-to-run `gh issue create` command, when `gh` is available. */
+  ghCommand?: string;
+}
+
 /** xds --json swizzle <component> */
 export interface SwizzleCopyResponse {
   type: 'swizzle.copy';
@@ -25,6 +32,6 @@ export interface SwizzleCopyResponse {
     outputDir: string;
     filesCopied: number;
     files: string[];
-    gapReport?: string | null;
+    feedback?: SwizzleFeedback;
   };
 }

package/src/types/template-api.d.ts

@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Authoring surface for Astryx static templates, exported from
+ * `@astryxdesign/cli/template`.
+ *
+ * A template doc lives in a `<id>.doc.{ts,mjs,js}` file with a required
+ * same-stem sibling source file (`<id>.tsx`). The doc's `type` (page or
+ * block) — injected by the create* helpers — decides how the template is
+ * scaffolded; there is no `/pages` vs `/blocks` directory requirement.
+ */
+
+/** Optional preview metadata for a template (used by docs surfaces). */
+export interface AstryxTemplatePreview {
+  /** Path or URL to a preview image. */
+  image?: string;
+  /** CSS aspect-ratio hint for the preview, e.g. "16 / 9". */
+  aspectRatio?: string;
+}
+
+/** Fields common to page and block template docs (without the `type` tag). */
+export interface AstryxTemplateInput {
+  /** Human-readable template name. Required. */
+  name: string;
+  /** One-line description of what the template provides. Required. */
+  description: string;
+  /** Optional grouping/category label. */
+  category?: string;
+  /** Component display names the template composes. */
+  componentsUsed?: string[];
+  /** Optional preview metadata. */
+  preview?: AstryxTemplatePreview;
+}
+
+/** Input accepted by {@link createPageTemplate} (no `type` field). */
+export type AstryxPageTemplateInput = AstryxTemplateInput;
+/** Input accepted by {@link createBlockTemplate} (no `type` field). */
+export type AstryxBlockTemplateInput = AstryxTemplateInput;
+
+/** A validated page template doc. */
+export type AstryxPageTemplate = AstryxTemplateInput & {type: 'page'};
+/** A validated block template doc. */
+export type AstryxBlockTemplate = AstryxTemplateInput & {type: 'block'};
+
+/** A validated template doc (page or block). */
+export type AstryxTemplate = AstryxPageTemplate | AstryxBlockTemplate;
+
+export declare function createPageTemplate<T extends AstryxPageTemplateInput>(
+  def: T,
+): T & {type: 'page'};
+
+export declare function createBlockTemplate<T extends AstryxBlockTemplateInput>(
+  def: T,
+): T & {type: 'block'};

package/src/types/template.d.ts

@@ -21,12 +21,21 @@ export interface TemplateListResponse {
 }
 
 export interface TemplateListEntry {
+  /** Stable template id (relative path under the templates root, minus the .doc.* suffix). */
+  id: string;
   name: string;
+  /** @deprecated Alias of `name`, retained for back-compat. */
   displayName: string;
   description: string;
+  type: 'page' | 'block';
+  /** Owning package; core (built-in) templates report '@astryxdesign/core'. */
+  package: string;
+  /** Optional grouping/category label. */
+  category?: string;
+  /** Component display names the template composes. */
+  componentsUsed?: string[];
   isReady: boolean;
   scaffold?: boolean;
-  type: 'page' | 'block';
 }
 
 /** xds --json template <name> */
@@ -62,9 +71,3 @@ export interface TemplateCopyResponse {
     filesCopied: number;
   };
 }
-
-/** xds --json template get --id <id> */
-export interface TemplateGetResponse {
-  type: 'template.get';
-  data: {id: string; source: string};
-}

package/src/types/upgrade.d.ts

@@ -7,6 +7,7 @@
  * ------------------------------------------------------------------
  * xds --json upgrade --list                 -> upgrade.list
  * xds --json upgrade [--apply]              -> upgrade.run
+ * xds --json upgrade (status short-circuit) -> upgrade.status
  * (version detection failure)               -> CLIError
  */
 
@@ -33,3 +34,31 @@ export interface UpgradeRunResponse {
     agentDocsRefreshed: boolean;
   };
 }
+
+/**
+ * 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}
+    | {status: 'no_codemods'; from: string; to: string}
+    | {
+        status: 'config_fixable';
+        from: string;
+        to: string;
+        configError: string;
+        configCodemods: string[];
+        suggestedCommand: string;
+        message: string;
+        note: string;
+      };
+}

package/src/types/validate-integration.d.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * validate-integration command JSON responses.
+ *
+ * Invocation                              -> type discriminator
+ * ------------------------------------------------------------
+ * astryx --json validate-integration       -> integration.validate
+ * astryx --json validate-integration <pkg> -> integration.validate
+ */
+
+import type {AstryxIntegrationIssue} from './integration';
+
+/** astryx --json validate-integration [package] */
+export interface ValidateIntegrationResponse {
+  type: 'integration.validate';
+  data: {
+    /** Integration package name, or null when no manifest was located. */
+    name: string | null;
+    /** Integration package version, or null when unavailable. */
+    version: string | null;
+    issues: AstryxIntegrationIssue[];
+  };
+}

package/src/utils/github.mjs

@@ -4,84 +4,9 @@
  * @file GitHub utilities for Astryx CLI
  *
  * Shared helpers for interacting with the GitHub CLI (`gh`).
- * Used by gap-report and swizzle commands.
- *
- * Gap reporting can be configured via astryx.config.mjs:
- *   gapReport: false                                — disable entirely
- *   gapReport: { command: './scripts/report-gap.sh' } — run custom script (receives JSON on stdin)
- *
- * Or via environment variable:
- *   ASTRYX_GAP_REPORT=off                              — disable entirely
- *   ASTRYX_GAP_REPORT=./scripts/report-gap.sh          — run custom script
  */
 
 import {execFileSync} from 'node:child_process';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-
-/** Default target repository for gap report issues. */
-const DEFAULT_REPO = 'facebookexperimental/xds';
-
-/** Gap report category options. */
-export const GAP_CATEGORIES = [
-  {value: 'missing_component', label: 'Missing component'},
-  {value: 'missing_variant', label: 'Missing variant or prop'},
-  {value: 'layout_gap', label: 'Layout gap'},
-  {value: 'styling_gap', label: 'Styling gap'},
-  {value: 'a11y_gap', label: 'Accessibility gap'},
-  {value: 'api_friction', label: 'API friction'},
-  {value: 'docs_gap', label: 'Documentation gap'},
-  {value: 'other', label: 'Other'},
-];
-
-/**
- * Load gap report configuration.
- *
- * Priority: env var > astryx.config.mjs > default (GitHub issue)
- *
- * Returns { enabled: boolean, command?: string }
- *   - enabled: false → gap reporting disabled
- *   - command: string → run this script instead of creating a GitHub issue
- *   - neither → default behavior (GitHub issue to facebookexperimental/xds)
- */
-export function loadGapReportConfig() {
-  // 1. Check environment variable
-  const envVar = process.env.ASTRYX_GAP_REPORT;
-  if (envVar) {
-    if (envVar === 'off' || envVar === 'false' || envVar === '0') {
-      return {enabled: false};
-    }
-    // Treat as custom command
-    return {enabled: true, command: envVar};
-  }
-
-  // 2. Check astryx.config.mjs
-  const configPath = path.join(process.cwd(), 'astryx.config.mjs');
-  if (fs.existsSync(configPath)) {
-    try {
-      const content = fs.readFileSync(configPath, 'utf-8');
-      const match = content.match(/gapReport\s*:\s*(.+?)[\s,}]/s);
-      if (match) {
-        const value = match[1].trim();
-        if (value === 'false') {
-          return {enabled: false};
-        }
-        // Look for command property in object literal
-        const cmdMatch = content.match(
-          /gapReport\s*:\s*\{[^}]*command\s*:\s*['"](.+?)['"]/s,
-        );
-        if (cmdMatch) {
-          return {enabled: true, command: cmdMatch[1]};
-        }
-      }
-    } catch {
-      // Config parse error — fall through to defaults
-    }
-  }
-
-  // 3. Default
-  return {enabled: true};
-}
 
 /**
  * Check if `gh` CLI is installed and authenticated.
@@ -95,180 +20,3 @@ export function checkGhCli() {
     return false;
   }
 }
-
-/**
- * Idempotently create the `gap-report` and `gap-analysis` labels.
- * Uses `--force` to avoid errors if labels already exist.
- */
-function ensureGapReportLabel() {
-  try {
-    execFileSync(
-      'gh',
-      [
-        'label',
-        'create',
-        'gap-report',
-        '--repo',
-        DEFAULT_REPO,
-        '--color',
-        'D4C5F9',
-        '--description',
-        'Auto-filed gap report from swizzle/gap-report CLI',
-        '--force',
-      ],
-      {stdio: 'ignore'},
-    );
-    execFileSync(
-      'gh',
-      [
-        'label',
-        'create',
-        'gap-analysis',
-        '--repo',
-        DEFAULT_REPO,
-        '--color',
-        '0E8A16',
-        '--description',
-        'Curated gap analysis summary',
-        '--force',
-      ],
-      {stdio: 'ignore'},
-    );
-  } catch {
-    // Best-effort — labels may already exist or user may lack permissions
-  }
-}
-
-/**
- * Run a custom gap report command, piping report data as JSON to stdin.
- *
- * @param {string} command  Script path to execute
- * @param {object} report   Report data (component, category, intention, detail, source)
- * @returns {string} stdout from the command
- */
-function runCustomCommand(command, report) {
-  const resolved = path.resolve(process.cwd(), command);
-  const json = JSON.stringify(report, null, 2);
-
-  const result = execFileSync(resolved, [], {
-    input: json,
-    encoding: 'utf-8',
-  });
-
-  return result.trim();
-}
-
-/**
- * Build the report payload + rendered title/body for a gap report.
- * Pure function — no side effects, never calls `gh` or external scripts.
- *
- * @returns {{
- *   enabled: boolean,
- *   mode: 'disabled' | 'custom' | 'github',
- *   command?: string,
- *   report: object,
- *   title: string,
- *   body: string,
- *   repo: string,
- * }}
- */
-export function buildGapReportPreview({
-  component,
-  category,
-  intention,
-  detail,
-  source = 'cli',
-}) {
-  const config = loadGapReportConfig();
-  const categoryLabel =
-    GAP_CATEGORIES.find(c => c.value === category)?.label ?? category;
-
-  const report = {
-    component,
-    category,
-    categoryLabel,
-    intention,
-    detail: detail || null,
-    source,
-    timestamp: new Date().toISOString(),
-  };
-
-  const title = `[gap] ${component}: ${intention.slice(0, 70)}`;
-  const body = [
-    '| Field | Value |',
-    '|-------|-------|',
-    `| **Component** | ${component} |`,
-    `| **Category** | ${categoryLabel} |`,
-    `| **Source** | ${source} |`,
-    `| **Timestamp** | ${report.timestamp} |`,
-    '',
-    '## User Intention',
-    '',
-    intention,
-    ...(detail ? ['', '## Additional Context', '', detail] : []),
-  ].join('\n');
-
-  let mode = 'github';
-  if (!config.enabled) mode = 'disabled';
-  else if (config.command) mode = 'custom';
-
-  return {
-    enabled: config.enabled,
-    mode,
-    command: config.command,
-    report,
-    title,
-    body,
-    repo: DEFAULT_REPO,
-  };
-}
-
-/**
- * Create a gap report — either via GitHub issue or custom command.
- *
- * SAFETY: This actually invokes `gh issue create` (or runs the custom command).
- * Callers MUST gate this behind explicit user confirmation or a `--commit`-style
- * flag in non-interactive contexts. Use `buildGapReportPreview` for dry-run.
- *
- * @param {object} opts
- * @param {string} opts.component  Component name (e.g. "Button")
- * @param {string} opts.category   One of GAP_CATEGORIES values
- * @param {string} opts.intention  What the user was trying to achieve
- * @param {string} [opts.detail]   Additional context
- * @param {string} [opts.source]   Who filed it: "interactive", "llm-auto", "cli"
- * @returns {string|null} URL of the created issue (or custom command output), null if disabled
- */
-export function createGapReport(opts) {
-  const preview = buildGapReportPreview(opts);
-
-  if (!preview.enabled) {
-    return null;
-  }
-
-  // Custom command mode — pipe JSON to the script
-  if (preview.mode === 'custom') {
-    return runCustomCommand(preview.command, preview.report);
-  }
-
-  // Default mode — create GitHub issue
-  ensureGapReportLabel();
-
-  const result = execFileSync(
-    'gh',
-    [
-      'issue',
-      'create',
-      '--repo',
-      preview.repo,
-      '--title',
-      preview.title,
-      '--body',
-      preview.body,
-      '--label',
-      'gap-report',
-    ],
-    {encoding: 'utf-8'},
-  );
-
-  return result.trim();
-}

package/src/utils/interactive.mjs

@@ -18,8 +18,8 @@
  *     fail fast (exit 1) with actionable, non-interactive guidance.
  *
  *   - `isInteractive()` — for commands with an OPTIONAL secondary prompt
- *     (e.g. swizzle's post-copy "report a gap?"). The primary work already
- *     succeeded; callers use this to skip the prompt gracefully.
+ *     that runs after the primary work has already succeeded; callers use
+ *     this to skip the prompt gracefully in non-interactive contexts.
  */
 
 /**

package/templates/blocks/components/Card/ClickableCardWithNestedButton.doc.mjs

@@ -5,7 +5,7 @@ export const doc = {
   type: 'block',
   exampleFor: 'ClickableCard',
   name: 'ClickableCardWithNestedButton',
-  displayName: 'Clickable Card With Nested Button',
+  displayName: 'Clickable Card — Nested Button',
   description:
     'A product card that navigates on click but has an independent "Add to cart" button inside.',
   isReady: true,

package/templates/blocks/components/Card/SelectableCardMulti.doc.mjs

@@ -5,7 +5,7 @@ export const doc = {
   type: 'block',
   exampleFor: 'SelectableCard',
   name: 'SelectableCardMulti',
-  displayName: 'Selectable Card Multi',
+  displayName: 'Selectable Card — Multi-select',
   description:
     'Multi-select tag picker using color variant selectable cards with color-matched selection borders.',
   isReady: true,

package/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerWithProgress.tsx

@@ -44,7 +44,7 @@ export default function ChatComposerDrawerWithProgress() {
         }
         headerContext={
           <Stack direction="horizontal" gap={2} vAlign="center">
-            <ProgressBar value={42} label="Context usage" isLabelHidden hasValueLabel />
+            <ProgressBar value={42} label="Context usage" isLabelHidden />
           </Stack>
         }
       />