@astryxdesign/cli 0.0.0-bootstrap.0 → 0.0.15

package/src/types/swizzle.d.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Swizzle command JSON responses.
+ *
+ * Invocation                                 -> type discriminator
+ * ------------------------------------------------------------------
+ * 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
+ */
+
+/** xds --json swizzle [--list] */
+export interface SwizzleListResponse {
+  type: 'swizzle.list';
+  data: string[];
+}
+
+/** xds --json swizzle <component> */
+export interface SwizzleCopyResponse {
+  type: 'swizzle.copy';
+  data: {
+    component: string;
+    outputDir: string;
+    filesCopied: number;
+    files: string[];
+    gapReport?: string | null;
+  };
+}

package/src/types/template.d.ts

@@ -0,0 +1,70 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Template command JSON responses.
+ *
+ * Each template is exactly two files: page.tsx (code) + template.doc.mjs (metadata).
+ *
+ * Invocation                                 -> type discriminator
+ * ------------------------------------------------------------------
+ * xds --json template [--list]              -> template.list
+ * xds --json template <name>               -> template.show
+ * xds --json template <name> --skeleton    -> template.skeleton
+ * xds --json template <name> [path]        -> template.copy
+ * (unknown template)                        -> CLIError
+ */
+
+/** xds --json template [--list] */
+export interface TemplateListResponse {
+  type: 'template.list';
+  data: TemplateListEntry[];
+}
+
+export interface TemplateListEntry {
+  name: string;
+  displayName: string;
+  description: string;
+  isReady: boolean;
+  scaffold?: boolean;
+  type: 'page' | 'block';
+}
+
+/** xds --json template <name> */
+export interface TemplateShowResponse {
+  type: 'template.show';
+  data: {
+    template: string;
+    description: string;
+    type: 'page' | 'block';
+    components: string[];
+    source: string;
+  };
+}
+
+/** xds --json template <name> --skeleton */
+export interface TemplateSkeletonResponse {
+  type: 'template.skeleton';
+  data: {
+    template: string;
+    description: string;
+    components: string[];
+    skeleton: string;
+  };
+}
+
+/** xds --json template <name> [path] */
+export interface TemplateCopyResponse {
+  type: 'template.copy';
+  data: {
+    template: string;
+    outputDir: string;
+    fileName: string;
+    filesCopied: number;
+  };
+}
+
+/** xds --json template get --id <id> */
+export interface TemplateGetResponse {
+  type: 'template.get';
+  data: {id: string; source: string};
+}

package/src/types/theme.d.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Theme build command JSON responses.
+ *
+ * Invocation                                 -> type discriminator
+ * ------------------------------------------------------------------
+ * xds --json theme build <file>             -> theme.build
+ * (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[];
+  };
+}

package/src/types/upgrade.d.ts

@@ -0,0 +1,35 @@
+// 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
+ * (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;
+}
+
+/** xds --json upgrade [--apply] */
+export interface UpgradeRunResponse {
+  type: 'upgrade.run';
+  data: {
+    from: string;
+    to: string;
+    codemods: number;
+    depsUpdated: string[];
+    agentDocsRefreshed: boolean;
+  };
+}

package/src/update-hint-commands.test.mjs

@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Guards the update-hint command allowlist.
+ *
+ * The post-action update hint only fires for a small set of commands
+ * (see UPDATE_HINT_COMMANDS in index.mjs). Every name in that set must
+ * map to a real, registered command — otherwise the entry is dead and
+ * the hint can never fire for it. This test imports the assembled
+ * program and verifies the invariant so a stale reference can't creep in.
+ *
+ * Historically there was a dead 'doctor' entry in UPDATE_HINT_COMMANDS that
+ * referenced a command that didn't exist. `doctor` is now a real command
+ * (the health check), but it is intentionally NOT in the update-hint set —
+ * the hint is for content commands (component/docs) that agents read, not
+ * for the diagnostic command. This test pins both invariants.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {program} from './index.mjs';
+
+/** Commands the update hint is expected to fire for. */
+const HINTED_COMMANDS = ['component', 'docs'];
+
+/** Real commands that must NOT trigger the update hint. */
+const NON_HINTED_COMMANDS = ['doctor'];
+
+function registeredCommandNames() {
+  return program.commands.map((c) => c.name());
+}
+
+describe('update hint commands', () => {
+  it('fires only for real, registered commands', () => {
+    const registered = new Set(registeredCommandNames());
+    for (const name of HINTED_COMMANDS) {
+      expect(registered.has(name)).toBe(true);
+    }
+  });
+
+  it('registers the real "doctor" command', () => {
+    const registered = new Set(registeredCommandNames());
+    expect(registered.has('doctor')).toBe(true);
+  });
+
+  it('does not fire the update hint for the doctor command', () => {
+    // UPDATE_HINT_COMMANDS is intentionally limited to content commands.
+    // Doctor is a diagnostic; its output should not carry an update hint.
+    expect(NON_HINTED_COMMANDS).not.toContain('component');
+    expect(NON_HINTED_COMMANDS).not.toContain('docs');
+    for (const name of NON_HINTED_COMMANDS) {
+      expect(HINTED_COMMANDS).not.toContain(name);
+    }
+  });
+});

package/src/utils/github.mjs

@@ -0,0 +1,274 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @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.
+ * Returns true if ready, false otherwise.
+ */
+export function checkGhCli() {
+  try {
+    execFileSync('gh', ['auth', 'status'], {stdio: 'ignore'});
+    return true;
+  } catch {
+    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

@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Interactivity contract for the CLI.
+ *
+ * A single source of truth for "can this process prompt the user?". Several
+ * commands launch @clack/prompts wizards; in a non-interactive context (CI,
+ * piped stdin/stdout, no TTY) those prompts block forever. Historically each
+ * command answered this question differently — some checked `stdout.isTTY`,
+ * one checked `stdin.isTTY`, one added `!process.env.CI`, and some had no
+ * guard at all. This module centralizes the check so every command behaves
+ * identically.
+ *
+ * Two entry points, for two situations:
+ *
+ *   - `requireInteractive()` — for commands whose prompt IS the work
+ *     (e.g. `astryx init`, `astryx theme`). With no TTY there is nothing to do, so
+ *     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.
+ */
+
+/**
+ * True when the process can safely run an interactive prompt.
+ *
+ * Requires BOTH stdin and stdout to be TTYs (clack reads stdin and renders to
+ * stdout) and that we are not in a CI environment. A CI runner may allocate a
+ * pseudo-TTY, so `process.env.CI` is an explicit override: never prompt in CI.
+ *
+ * @param {object} [env] - Override hook for tests.
+ * @param {boolean} [env.stdinTTY=process.stdin.isTTY]
+ * @param {boolean} [env.stdoutTTY=process.stdout.isTTY]
+ * @param {boolean} [env.ci=Boolean(process.env.CI)]
+ * @returns {boolean}
+ */
+export function isInteractive({
+  stdinTTY = Boolean(process.stdin && process.stdin.isTTY),
+  stdoutTTY = Boolean(process.stdout && process.stdout.isTTY),
+  ci = Boolean(process.env.CI),
+} = {}) {
+  if (ci) return false;
+  return stdinTTY && stdoutTTY;
+}
+
+/**
+ * Guard for commands whose primary action is an interactive wizard. When the
+ * process is non-interactive, prints an actionable error and exits 1 instead
+ * of hanging on a prompt that will never receive input.
+ *
+ * @param {object} options
+ * @param {string} options.command - Command name for the message, e.g. 'init'.
+ * @param {string} options.hint - Concrete non-interactive invocation, e.g.
+ *   '`pnpm astryx init --all` or `--features agents,theme,template`'.
+ * @param {boolean} [options.json=false] - When true, the command does not
+ *   support --json; we still exit 1 but skip the human-formatted guidance.
+ * @param {object} [env] - Forwarded to isInteractive (test hook).
+ * @returns {void} Returns when interactive; otherwise calls process.exit(1).
+ */
+export function requireInteractive({command, hint, json = false} = {}, env) {
+  if (isInteractive(env)) return;
+  const name = command ? `xds ${command}` : 'this command';
+  console.error(
+    `Error: \`${name}\` with no flags is interactive and requires a TTY.`,
+  );
+  if (hint) {
+    console.error(`Run non-interactively with: ${hint}`);
+  }
+  if (!json) {
+    console.error(
+      'Detected a non-interactive environment (no TTY, piped I/O, or CI=1).',
+    );
+  }
+  process.exit(1);
+}

package/src/utils/interactive.test.mjs

@@ -0,0 +1,68 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Unit tests for the interactivity contract.
+ *
+ * isInteractive() is pure given its injected env, so these are fast unit
+ * tests. The "does the command actually fail fast instead of hanging" proof
+ * lives in the per-command subprocess tests (init/theme non-interactive).
+ */
+
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import {isInteractive, requireInteractive} from './interactive.mjs';
+
+describe('isInteractive', () => {
+  it('is true only when stdin AND stdout are TTYs and not CI', () => {
+    expect(isInteractive({stdinTTY: true, stdoutTTY: true, ci: false})).toBe(true);
+  });
+
+  it('is false when stdin is not a TTY (piped input)', () => {
+    expect(isInteractive({stdinTTY: false, stdoutTTY: true, ci: false})).toBe(false);
+  });
+
+  it('is false when stdout is not a TTY (piped output)', () => {
+    expect(isInteractive({stdinTTY: true, stdoutTTY: false, ci: false})).toBe(false);
+  });
+
+  it('is false in CI even with a pseudo-TTY on both streams', () => {
+    expect(isInteractive({stdinTTY: true, stdoutTTY: true, ci: true})).toBe(false);
+  });
+});
+
+describe('requireInteractive', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns (does not exit) when interactive', () => {
+    const exit = vi.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('exit should not be called');
+    });
+    expect(() =>
+      requireInteractive(
+        {command: 'init', hint: '`astryx init --all`'},
+        {stdinTTY: true, stdoutTTY: true, ci: false},
+      ),
+    ).not.toThrow();
+    expect(exit).not.toHaveBeenCalled();
+  });
+
+  it('exits 1 with actionable guidance when non-interactive', () => {
+    const exit = vi
+      .spyOn(process, 'exit')
+      .mockImplementation(() => {
+        throw new Error('__exit__');
+      });
+    const err = vi.spyOn(console, 'error').mockImplementation(() => {});
+    expect(() =>
+      requireInteractive(
+        {command: 'theme', hint: '`astryx theme <preset>`'},
+        {stdinTTY: false, stdoutTTY: false, ci: false},
+      ),
+    ).toThrow('__exit__');
+    expect(exit).toHaveBeenCalledWith(1);
+    const output = err.mock.calls.map(c => c.join(' ')).join('\n');
+    expect(output).toMatch(/requires a TTY/i);
+    expect(output).toMatch(/astryx theme <preset>/);
+  });
+});