@astryxdesign/cli 0.0.0-bootstrap.0 → 0.1.0-canary.0b5b49f

package/src/commands/swizzle-gap-safety.test.mjs

@@ -0,0 +1,273 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * End-to-end safety tests for `astryx swizzle --gap` and `xds gap-report`.
+ *
+ * Critical: these tests must NEVER actually invoke `gh issue create`. We
+ * defend in depth:
+ *
+ *   1. We spawn the CLI in a non-TTY pipe → triggers the dry-run gate.
+ *   2. We set ASTRYX_GAP_REPORT=off as an extra belt-and-suspenders for tests
+ *      that would otherwise risk filing.
+ *   3. We unset GH_TOKEN so that any unexpected `gh` invocation fails fast.
+ *   4. We put a sabotaged `gh` shim earlier on PATH that blocks real
+ *      `gh issue create` calls and writes a marker file. Any successful
+ *      "filing" path leaves a marker we can assert against — so a regression
+ *      is detected even if the gate silently breaks.
+ *
+ * Regression cases for issues #2370 and #2371: real gap-report issues filed
+ * unintentionally during a verification run because the non-interactive path
+ * called `gh issue create` with no confirmation.
+ */
+
+import {describe, it, expect, beforeAll, afterAll, beforeEach, afterEach} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const cliBin = path.resolve(__dirname, '../../bin/astryx.mjs');
+const repoRoot = path.resolve(__dirname, '../../../..');
+
+let shimDir;
+let markerFile;
+let baseEnv;
+
+beforeAll(() => {
+  shimDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-gh-shim-'));
+  markerFile = path.join(shimDir, 'gh-issue-create-was-called.marker');
+
+  // Sabotaged `gh` shim. Records ONLY `gh issue create` invocations to the
+  // marker file, since that's the only command we want to detect as a
+  // "would-have-filed" event. Other subcommands (auth status, label create)
+  // succeed silently so they don't break the gh availability check or the
+  // label-ensure path.
+  const shim = `#!/usr/bin/env node
+import * as fs from 'node:fs';
+const args = process.argv.slice(2);
+const isIssueCreate = args[0] === 'issue' && args[1] === 'create';
+if (isIssueCreate) {
+  fs.appendFileSync(${JSON.stringify(markerFile)}, JSON.stringify(args) + '\\n');
+  process.stderr.write('TEST GUARD: real gh issue create blocked\\n');
+  process.exit(1);
+}
+// Other commands (auth status, label create) succeed silently.
+process.exit(0);
+`;
+  fs.writeFileSync(path.join(shimDir, 'gh'), shim);
+  fs.chmodSync(path.join(shimDir, 'gh'), 0o755);
+
+  baseEnv = {
+    ...process.env,
+    PATH: `${shimDir}:${process.env.PATH}`,
+    // Belt-and-suspenders: even if a gate breaks, this disables the feature.
+    // For tests that need the feature on, individual cases override this.
+    GH_TOKEN: '',
+  };
+});
+
+afterAll(() => {
+  fs.rmSync(shimDir, {recursive: true, force: true});
+});
+
+function runXds(args, {env = {}, cwd = repoRoot} = {}) {
+  // Reset marker for each run.
+  if (fs.existsSync(markerFile)) fs.unlinkSync(markerFile);
+  const result = spawnSync('node', [cliBin, ...args], {
+    cwd,
+    env: {...baseEnv, ...env},
+    encoding: 'utf-8',
+  });
+  return {
+    ...result,
+    // True iff the CLI tried to call `gh issue create` — the actual filing
+    // operation. Other gh subcommands (auth status, label create) are
+    // ignored as benign.
+    ghWasCalled: fs.existsSync(markerFile),
+    ghCallArgs: fs.existsSync(markerFile)
+      ? fs.readFileSync(markerFile, 'utf-8')
+      : null,
+  };
+}
+
+describe('gap-report: dry-run by default in non-interactive mode', () => {
+  it('non-TTY pipe with all required flags → dry-run, exit 0, no gh call', () => {
+    const r = runXds([
+      'gap-report',
+      '--component',
+      'Button',
+      '--category',
+      'missing_variant',
+      '--reason',
+      'Test that we never file in non-interactive mode',
+    ]);
+    expect(r.status).toBe(0);
+    expect(r.ghWasCalled).toBe(false);
+    expect(r.stdout).toMatch(/dry-run/i);
+    expect(r.stdout).toMatch(/Re-run with --commit/i);
+    // Preview should include the title we'd file.
+    expect(r.stdout).toContain('Button');
+  });
+
+  it('--json mode in non-TTY → structured dry-run JSON, no gh call', () => {
+    const r = runXds([
+      '--json',
+      'gap-report',
+      '--component',
+      'Button',
+      '--category',
+      'missing_variant',
+      '--reason',
+      'JSON dry-run',
+    ]);
+    expect(r.status).toBe(0);
+    expect(r.ghWasCalled).toBe(false);
+    // jsonOut pretty-prints across multiple lines; parse the whole stdout
+    // as JSON (after stripping any trailing whitespace).
+    const parsed = JSON.parse(r.stdout.trim());
+    expect(parsed.type).toBe('gap-report.dryRun');
+    expect(parsed.data.dryRun).toBe(true);
+    expect(parsed.data.title).toContain('Button');
+    expect(parsed.data.wouldFile).toBe(true);
+  });
+
+  it('ASTRYX_GAP_REPORT=off → no gh call, even with --commit flag', () => {
+    const r = runXds(
+      [
+        'gap-report',
+        '--component',
+        'Button',
+        '--category',
+        'other',
+        '--reason',
+        'should be disabled',
+        '--commit',
+      ],
+      {env: {ASTRYX_GAP_REPORT: 'off'}},
+    );
+    // Should exit 0 with a "disabled" message; never calls gh.
+    expect(r.ghWasCalled).toBe(false);
+    expect(r.status).toBe(0);
+    expect(r.stdout + r.stderr).toMatch(/disabled/i);
+  });
+
+  it('--commit in non-TTY mode WOULD invoke gh (verified via shim)', () => {
+    // This proves --commit actually engages the file path. Our shim exits 1
+    // so the CLI will report failure, but the marker proves gh was invoked
+    // with the expected args.
+    const r = runXds(
+      [
+        'gap-report',
+        '--component',
+        'Button',
+        '--category',
+        'other',
+        '--reason',
+        'commit flag should engage filing',
+        '--commit',
+      ],
+      {env: {ASTRYX_GAP_REPORT: ''}}, // re-enable feature; shim will block real call
+    );
+    expect(r.ghWasCalled).toBe(true);
+    expect(r.ghCallArgs).toContain('issue');
+    expect(r.ghCallArgs).toContain('create');
+    expect(r.ghCallArgs).toContain('facebookexperimental/xds');
+  });
+});
+
+describe('swizzle --gap respects safety gates', () => {
+  // swizzle's --output is path-safety guarded: absolute paths and `..`
+  // traversal are rejected (see swizzle.path-safety.test.mjs). These gap
+  // tests only care about the gh-call / status gates, so they write into a
+  // *relative* output dir created under the repo root (a valid, in-root
+  // target) and clean it up afterward. The CLI still resolves @astryxdesign/core via
+  // findCoreDir walking up from the cwd.
+  let swizzleOutDir;
+  beforeEach(() => {
+    swizzleOutDir = fs.mkdtempSync(path.join(repoRoot, '.xds-swizzle-gap-test-'));
+  });
+  afterEach(() => {
+    if (swizzleOutDir) fs.rmSync(swizzleOutDir, {recursive: true, force: true});
+  });
+  // Relative path into the temp dir, so it passes the path-safety guard
+  // (cwd === repoRoot for runXds by default).
+  const relOut = () => path.relative(repoRoot, swizzleOutDir);
+
+  it('swizzle --gap in non-TTY → dry-run, no gh call', () => {
+    const r = runXds([
+      'swizzle',
+      'Button',
+      '--output',
+      relOut(),
+      '--gap',
+      'Need a compact variant',
+      '--gap-category',
+      'missing_variant',
+    ]);
+    expect(r.ghWasCalled).toBe(false);
+    expect(r.status).toBe(0);
+    expect(r.stdout).toMatch(/dry-run/i);
+  });
+
+  it('swizzle --gap --no-report → never engages gap reporting at all', () => {
+    const r = runXds([
+      'swizzle',
+      'Button',
+      '--output',
+      relOut(),
+      '--gap',
+      'Should be suppressed entirely',
+      '--gap-category',
+      'missing_variant',
+      '--no-report',
+    ]);
+    expect(r.ghWasCalled).toBe(false);
+    expect(r.status).toBe(0);
+    // Should not even show a dry-run preview — reporting is suppressed.
+    expect(r.stdout).toMatch(/suppressed/i);
+    expect(r.stdout).not.toMatch(/Would file GitHub issue/i);
+  });
+
+  it('swizzle --gap --no-report --commit → STILL no gh call (no-report wins)', () => {
+    // Critical regression test: --no-report must beat --commit for the
+    // --gap auto-file path. Otherwise CI scripts could file issues.
+    const r = runXds(
+      [
+        'swizzle',
+        'Button',
+        '--output',
+        relOut(),
+        '--gap',
+        'should never file',
+        '--gap-category',
+        'other',
+        '--no-report',
+        '--commit',
+      ],
+      {env: {ASTRYX_GAP_REPORT: ''}},
+    );
+    expect(r.ghWasCalled).toBe(false);
+    expect(r.status).toBe(0);
+  });
+
+  it('swizzle --gap with ASTRYX_GAP_REPORT=off → no gh call', () => {
+    const r = runXds(
+      [
+        'swizzle',
+        'Button',
+        '--output',
+        relOut(),
+        '--gap',
+        'should be disabled by env',
+        '--gap-category',
+        'other',
+        '--commit',
+      ],
+      {env: {ASTRYX_GAP_REPORT: 'off'}},
+    );
+    expect(r.ghWasCalled).toBe(false);
+    expect(r.status).toBe(0);
+  });
+});

package/src/commands/swizzle.mjs

@@ -0,0 +1,389 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file swizzle command — Copy component source for customization
+ *
+ * Resolves component source from packages/core/src/{Component}/,
+ * copies non-test files to the output directory, and rewrites
+ * relative imports to use '@astryxdesign/core' package paths.
+ *
+ * After swizzling, optionally prompts the user to file a gap report
+ * explaining why they needed to customize the component.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as p from '@clack/prompts';
+import {findCoreDir, listComponents} from '../utils/paths.mjs';
+import {assertWithin, PathSafetyError, isNonInteractive} from '../utils/path-safety.mjs';
+import {isInteractive} from '../utils/interactive.mjs';
+import {jsonOut, humanLog} from '../lib/json.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {ERROR_CODES} from '../lib/error-codes.mjs';
+import {
+  buildGapReportPreview,
+  checkGhCli,
+  createGapReport,
+  loadGapReportConfig,
+  GAP_CATEGORIES,
+} from '../utils/github.mjs';
+import {shouldActuallyFile, formatPreview} from './gap-report.mjs';
+
+/**
+ * Rewrite relative imports that point outside the component directory
+ * to use @astryxdesign/core package paths.
+ *
+ * e.g. '../theme/tokens.stylex' -> '@astryxdesign/core/theme'
+ *      '../utils/mergeProps'     -> '@astryxdesign/core/utils'
+ */
+export function rewriteImports(content) {
+  // Match import/export from statements with relative paths going up
+  return content.replace(
+    /(from\s+['"])(\.\.\/.+?)(['"])/g,
+    (match, prefix, importPath, suffix) => {
+      // Extract the top-level directory from the relative path
+      // e.g. '../theme/tokens.stylex' -> 'theme'
+      // e.g. '../utils/mergeProps' -> 'utils'
+      const parts = importPath.replace(/^\.\.\//, '').split('/');
+      const topDir = parts[0];
+
+      // Map to @astryxdesign/core subpath
+      return `${prefix}@astryxdesign/core/${topDir}${suffix}`;
+    },
+  );
+}
+
+function isCancel(value) {
+  if (p.isCancel(value)) {
+    p.cancel('Cancelled.');
+    process.exit(0);
+  }
+  return value;
+}
+
+export function registerSwizzle(program) {
+  program
+    .command('swizzle [component]')
+    .description('Copy component source for customization')
+    .option('--output <dir>', 'Output directory', './components/astryx')
+    .option('--list', 'List available components')
+    .option('--gap <reason>', 'File a gap report explaining why you swizzled')
+    .option('--gap-category <category>', 'Gap category (for --gap mode)')
+    .option(
+      '--no-report',
+      'Suppress all gap reporting (interactive prompt AND --gap auto-filing)',
+    )
+    .option(
+      '--dry-run',
+      'For --gap: print the issue that would be filed without contacting GitHub. Default in non-TTY / --json mode.',
+    )
+    .option(
+      '--commit',
+      'For --gap: actually file the issue. Required in non-interactive mode.',
+    )
+    .option('-f, --overwrite', 'Overwrite existing files without prompting')
+    .action(async (component, options) => {
+      const coreDir = findCoreDir(process.cwd());
+      const json = program.opts().json || false;
+
+      if (!coreDir) {
+        cliError(
+          'Could not find @astryxdesign/core package. Make sure you are inside the design system monorepo or have @astryxdesign/core installed.',
+          {code: ERROR_CODES.ERR_CORE_NOT_FOUND},
+        );
+        return;
+      }
+
+      const components = listComponents(coreDir);
+
+      if (options.list || !component) {
+        if (json) return jsonOut('swizzle.list', components);
+        humanLog('\nAvailable components:\n');
+        for (const name of components) {
+          humanLog(`  ${name}`);
+        }
+        humanLog(`\nUsage: astryx swizzle <component>\n`);
+        humanLog('Example: astryx swizzle Button');
+        humanLog('         astryx swizzle XDSButton  (XDS prefix also works)\n');
+        return;
+      }
+
+      const dirName = component.replace(/^XDS/, '');
+      const componentDir = path.join(coreDir, 'src', dirName);
+
+      if (!fs.existsSync(componentDir)) {
+        cliError(
+          `Component "${component}" not found.`,
+          {suggestions: components.slice(0, 10).map((n) => ({name: n})), code: ERROR_CODES.ERR_UNKNOWN_COMPONENT},
+        );
+        return;
+      }
+
+      // Path-safety: --output must resolve inside cwd. Reject absolute
+      // paths and `..` traversal up front, before any directory is created.
+      let outputBase;
+      try {
+        outputBase = assertWithin(options.output, process.cwd(), {
+          label: 'output directory',
+        });
+      } catch (err) {
+        if (err instanceof PathSafetyError) {
+          cliError(err.message, {code: ERROR_CODES.ERR_PATH_TRAVERSAL});
+          return;
+        }
+        throw err;
+      }
+      const outputDir = path.join(outputBase, dirName);
+
+      // Pre-flight overwrite check: collect files we'd write and detect
+      // collisions before mkdir/writeFile so we never half-clobber.
+      const sourceFiles = fs.readdirSync(componentDir).filter(file => {
+        if (file.includes('.test.') || file === 'README.md') return false;
+        const stat = fs.statSync(path.join(componentDir, file));
+        return stat.isFile();
+      });
+
+      const existingFiles = sourceFiles.filter(f =>
+        fs.existsSync(path.join(outputDir, f)),
+      );
+
+      if (existingFiles.length > 0 && !options.overwrite) {
+        const relOutputForMsg = path.relative(process.cwd(), outputDir) || '.';
+        if (json || isNonInteractive({json})) {
+          const msg =
+            `Refusing to overwrite ${existingFiles.length} existing file(s) in ${relOutputForMsg}/. ` +
+            `Re-run with --overwrite (or -f) to replace them.`;
+          cliError(msg, {code: ERROR_CODES.ERR_FILE_EXISTS});
+          return;
+        }
+        const confirmed = isCancel(
+          await p.confirm({
+            message:
+              `Overwrite ${existingFiles.length} existing file(s) in ${relOutputForMsg}/? ` +
+              `(${existingFiles.slice(0, 3).join(', ')}${existingFiles.length > 3 ? ', …' : ''})`,
+            initialValue: false,
+          }),
+        );
+        if (!confirmed) {
+          humanLog('Aborted. Re-run with --overwrite to replace files.');
+          return;
+        }
+      }
+
+      fs.mkdirSync(outputDir, {recursive: true});
+
+      // Copy all non-test, non-README files
+      const files = fs.readdirSync(componentDir);
+      let copied = 0;
+
+      for (const file of files) {
+        // Skip test files and README
+        if (file.includes('.test.') || file === 'README.md') continue;
+
+        const srcPath = path.join(componentDir, file);
+        const stat = fs.statSync(srcPath);
+        if (!stat.isFile()) continue;
+
+        let content = fs.readFileSync(srcPath, 'utf-8');
+
+        // Rewrite imports for .ts/.tsx files
+        if (file.endsWith('.ts') || file.endsWith('.tsx')) {
+          content = rewriteImports(content);
+        }
+
+        fs.writeFileSync(path.join(outputDir, file), content);
+        copied++;
+      }
+
+      const relOutput = path.relative(process.cwd(), outputDir);
+      const copiedFiles = files.filter(f => !f.includes('.test.') && f !== 'README.md' && fs.statSync(path.join(componentDir, f)).isFile());
+
+      // --- Gap reporting ---
+
+      const gapConfig = loadGapReportConfig();
+      let gapReportUrl = null;
+      let gapDryRunPreview = null;
+
+      // CRITICAL: --no-report must suppress BOTH the interactive prompt AND
+      // the --gap auto-file path. Previously --gap bypassed --no-report.
+      // commander sets options.report to false for `--no-report`.
+      const reportingSuppressed = options.report === false;
+
+      if (options.gap && !reportingSuppressed && gapConfig.enabled) {
+        const category = options.gapCategory || 'other';
+        const previewArgs = {
+          component: dirName,
+          category,
+          intention: options.gap,
+          source: 'llm-auto',
+        };
+
+        const willFile = shouldActuallyFile({
+          commit: options.commit,
+          dryRun: options.dryRun,
+          json,
+        });
+
+        const preview = buildGapReportPreview(previewArgs);
+
+        if (!willFile) {
+          // Dry-run: do NOT call gh. Surface what would have been filed.
+          gapDryRunPreview = {
+            dryRun: true,
+            wouldFile: preview.mode !== 'disabled',
+            mode: preview.mode,
+            title: preview.title,
+            body: preview.body,
+            repo: preview.repo,
+            command: preview.command || null,
+          };
+        } else if (gapConfig.command || checkGhCli()) {
+          try {
+            gapReportUrl = createGapReport(previewArgs);
+          } catch (err) {
+            if (!json)
+              console.error(`Warning: Could not file gap report: ${err.message}`);
+          }
+        }
+      }
+
+      if (options.gap) {
+        if (json)
+          return jsonOut('swizzle.copy', {
+            component: dirName,
+            outputDir: relOutput,
+            filesCopied: copied,
+            files: copiedFiles.map(f => f),
+            gapReport: gapReportUrl,
+            gapReportDryRun: gapDryRunPreview,
+            gapReportSuppressed: reportingSuppressed || !gapConfig.enabled,
+          });
+        humanLog(`\n✓ Copied ${copied} files to ${relOutput}/\n`);
+        humanLog('Relative imports have been rewritten to use @astryxdesign/core.');
+        humanLog('You can now customize the component source freely.\n');
+        if (gapReportUrl) {
+          humanLog(`✓ Gap report filed: ${gapReportUrl}\n`);
+        } else if (gapDryRunPreview) {
+          humanLog(formatPreview(buildGapReportPreview({
+            component: dirName,
+            category: options.gapCategory || 'other',
+            intention: options.gap,
+            source: 'llm-auto',
+          })));
+          humanLog(
+            '\n[dry-run] No gap report was filed. Re-run with --commit to file.',
+          );
+        } else if (reportingSuppressed) {
+          humanLog('Gap reporting suppressed by --no-report.');
+        } else if (!gapConfig.enabled) {
+          humanLog('Gap reporting is disabled via configuration.');
+        } else if (!gapConfig.command && !checkGhCli()) {
+          humanLog('Skipping gap report: gh CLI not available.');
+        }
+        return;
+      }
+
+      if (json) return jsonOut('swizzle.copy', {component: dirName, outputDir: relOutput, filesCopied: copied, files: copiedFiles.map(f => f)});
+
+      humanLog(`\n✓ Copied ${copied} files to ${relOutput}/\n`);
+      humanLog('Relative imports have been rewritten to use @astryxdesign/core.');
+      humanLog('You can now customize the component source freely.\n');
+
+      if (reportingSuppressed || !gapConfig.enabled) {
+        return;
+      }
+
+      // Interactive gap report prompt
+      //
+      // This prompt is OPTIONAL — the swizzle copy already succeeded above.
+      // In a non-interactive context (CI, piped I/O, no TTY) we must not
+      // block on it; skip gracefully rather than hang. Use --gap with
+      // explicit flags for non-interactive gap reporting.
+      if (!isInteractive()) {
+        return;
+      }
+
+      if (!gapConfig.command && !checkGhCli()) {
+        // Silently skip if gh isn't available and no custom command configured
+        return;
+      }
+
+      const shouldReport = isCancel(
+        await p.confirm({
+          message: 'Would you like to report why you swizzled this component?',
+          initialValue: false,
+        }),
+      );
+
+      if (!shouldReport) return;
+
+      const category = isCancel(
+        await p.select({
+          message: 'What kind of gap is this?',
+          options: GAP_CATEGORIES,
+        }),
+      );
+
+      const intention = isCancel(
+        await p.text({
+          message: 'What were you trying to achieve?',
+          placeholder:
+            'e.g. "Need a compact variant for use in dense data tables"',
+          validate: val => {
+            if (!val.trim()) return 'Please describe what you were trying to do';
+          },
+        }),
+      );
+
+      const detail = isCancel(
+        await p.text({
+          message: 'Any additional context? (optional)',
+          placeholder: 'Press Enter to skip',
+        }),
+      );
+
+      const previewArgs = {
+        component: dirName,
+        category,
+        intention: intention.trim(),
+        detail: detail?.trim() || undefined,
+        source: 'interactive',
+      };
+
+      const preview = buildGapReportPreview(previewArgs);
+
+      p.note(
+        `${preview.mode === 'github' ? `Repo: ${preview.repo}` : `Custom command: ${preview.command}`}\n\n` +
+          `Title:\n  ${preview.title}\n\n` +
+          `Body:\n${preview.body
+            .split('\n')
+            .map(l => `  ${l}`)
+            .join('\n')}`,
+        'Preview — this is exactly what will be filed',
+      );
+
+      const confirmFile = isCancel(
+        await p.confirm({
+          message: 'File this gap report now?',
+          initialValue: false,
+        }),
+      );
+
+      if (!confirmFile) {
+        humanLog('Cancelled — nothing was filed.');
+        return;
+      }
+
+      const s = p.spinner();
+      s.start('Filing gap report');
+
+      try {
+        const url = createGapReport(previewArgs);
+        s.stop('Gap report filed');
+        humanLog(`✓ ${url}\n`);
+      } catch (err) {
+        s.stop('Failed to file gap report');
+        console.error(`Warning: Could not file gap report: ${err.message}`);
+      }
+    });
+}