@agent-scope/cli 1.8.0 → 1.9.0

package/dist/index.d.cts

@@ -1,6 +1,94 @@
 import { Command } from 'commander';
 import { ComplexityClass } from '@agent-scope/manifest';
 
+/**
+ * @agent-scope/cli — `scope init` command implementation
+ *
+ * Scaffolds a `reactscope.config.json` (and friends) in the current working
+ * directory.  Supports two modes:
+ *
+ *   - Interactive (default): prompts the user to confirm / override every
+ *     auto-detected value via Node's built-in `readline`.
+ *   - Non-interactive (`--yes`): accepts all auto-detected defaults without
+ *     prompting and prints a summary of created files.
+ *
+ * Safety rules (locked decisions):
+ *   - Config file format is JSON (`reactscope.config.json`).
+ *   - Output directory is `.reactscope/` — always added to `.gitignore`.
+ *   - Auto-detection is non-destructive; never overwrite existing config
+ *     without `--force`.
+ */
+interface ReactScopeConfig {
+    components: {
+        include: string[];
+        exclude: string[];
+        wrappers: {
+            providers: string[];
+            globalCSS: string[];
+        };
+    };
+    render: {
+        viewport: {
+            default: {
+                width: number;
+                height: number;
+            };
+        };
+        theme: "light" | "dark";
+        warmBrowser: boolean;
+    };
+    tokens: {
+        file: string;
+        compliance: {
+            threshold: number;
+        };
+    };
+    output: {
+        dir: string;
+        sprites: {
+            format: "png" | "webp";
+            cellPadding: number;
+            labelAxes: boolean;
+        };
+        json: {
+            pretty: boolean;
+        };
+    };
+    ci: {
+        complianceThreshold: number;
+        failOnA11yViolations: boolean;
+        failOnConsoleErrors: boolean;
+        baselinePath: string;
+    };
+}
+interface InitOptions {
+    /** Accept all defaults without prompting. */
+    yes: boolean;
+    /** Overwrite existing config without warning. */
+    force: boolean;
+    /** Root directory (defaults to `process.cwd()`). */
+    cwd?: string;
+}
+interface InitResult {
+    /** Whether the command succeeded. */
+    success: boolean;
+    /** Human-readable message summarising the outcome. */
+    message: string;
+    /** Paths of files that were created. */
+    created: string[];
+    /** Whether init was skipped (config already existed and --force was not set). */
+    skipped: boolean;
+}
+/**
+ * Execute `scope init` logic.
+ *
+ * Separated from the Commander action so it can be unit-tested without
+ * spawning a real subprocess.
+ */
+declare function runInit(options: InitOptions): Promise<InitResult>;
+
+declare function createInitCommand(): Command;
+
 /**
  * @agent-scope/cli — manifest sub-commands
  *
@@ -67,4 +155,4 @@ declare function createProgram(options?: ScopeCLIOptions): Command;
  */
 declare function createTokensCommand(): Command;
 
-export { type ListRow, type QueryRow, type ScopeCLIOptions, createManifestCommand, createProgram, createTokensCommand, isTTY, matchGlob };
+export { type InitOptions, type InitResult, type ListRow, type QueryRow, type ReactScopeConfig, type ScopeCLIOptions, createInitCommand, createManifestCommand, createProgram, createTokensCommand, isTTY, matchGlob, runInit };

package/dist/index.d.ts

@@ -1,6 +1,94 @@
 import { Command } from 'commander';
 import { ComplexityClass } from '@agent-scope/manifest';
 
+/**
+ * @agent-scope/cli — `scope init` command implementation
+ *
+ * Scaffolds a `reactscope.config.json` (and friends) in the current working
+ * directory.  Supports two modes:
+ *
+ *   - Interactive (default): prompts the user to confirm / override every
+ *     auto-detected value via Node's built-in `readline`.
+ *   - Non-interactive (`--yes`): accepts all auto-detected defaults without
+ *     prompting and prints a summary of created files.
+ *
+ * Safety rules (locked decisions):
+ *   - Config file format is JSON (`reactscope.config.json`).
+ *   - Output directory is `.reactscope/` — always added to `.gitignore`.
+ *   - Auto-detection is non-destructive; never overwrite existing config
+ *     without `--force`.
+ */
+interface ReactScopeConfig {
+    components: {
+        include: string[];
+        exclude: string[];
+        wrappers: {
+            providers: string[];
+            globalCSS: string[];
+        };
+    };
+    render: {
+        viewport: {
+            default: {
+                width: number;
+                height: number;
+            };
+        };
+        theme: "light" | "dark";
+        warmBrowser: boolean;
+    };
+    tokens: {
+        file: string;
+        compliance: {
+            threshold: number;
+        };
+    };
+    output: {
+        dir: string;
+        sprites: {
+            format: "png" | "webp";
+            cellPadding: number;
+            labelAxes: boolean;
+        };
+        json: {
+            pretty: boolean;
+        };
+    };
+    ci: {
+        complianceThreshold: number;
+        failOnA11yViolations: boolean;
+        failOnConsoleErrors: boolean;
+        baselinePath: string;
+    };
+}
+interface InitOptions {
+    /** Accept all defaults without prompting. */
+    yes: boolean;
+    /** Overwrite existing config without warning. */
+    force: boolean;
+    /** Root directory (defaults to `process.cwd()`). */
+    cwd?: string;
+}
+interface InitResult {
+    /** Whether the command succeeded. */
+    success: boolean;
+    /** Human-readable message summarising the outcome. */
+    message: string;
+    /** Paths of files that were created. */
+    created: string[];
+    /** Whether init was skipped (config already existed and --force was not set). */
+    skipped: boolean;
+}
+/**
+ * Execute `scope init` logic.
+ *
+ * Separated from the Commander action so it can be unit-tested without
+ * spawning a real subprocess.
+ */
+declare function runInit(options: InitOptions): Promise<InitResult>;
+
+declare function createInitCommand(): Command;
+
 /**
  * @agent-scope/cli — manifest sub-commands
  *
@@ -67,4 +155,4 @@ declare function createProgram(options?: ScopeCLIOptions): Command;
  */
 declare function createTokensCommand(): Command;
 
-export { type ListRow, type QueryRow, type ScopeCLIOptions, createManifestCommand, createProgram, createTokensCommand, isTTY, matchGlob };
+export { type InitOptions, type InitResult, type ListRow, type QueryRow, type ReactScopeConfig, type ScopeCLIOptions, createInitCommand, createManifestCommand, createProgram, createTokensCommand, isTTY, matchGlob, runInit };

package/dist/index.js

@@ -1,7 +1,8 @@
-import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'fs';
-import { resolve, dirname } from 'path';
-import { generateManifest } from '@agent-scope/manifest';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync, readdirSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import * as readline from 'readline';
 import { Command } from 'commander';
+import { generateManifest } from '@agent-scope/manifest';
 import { loadTrace, generateTest, getBrowserEntryScript } from '@agent-scope/playwright';
 import { chromium } from 'playwright';
 import { safeRender, ALL_CONTEXT_IDS, contextAxis, stressAxis, ALL_STRESS_IDS, RenderMatrix, SatoriRenderer, BrowserPool } from '@agent-scope/render';
@@ -9,7 +10,350 @@ import * as esbuild from 'esbuild';
 import { createRequire } from 'module';
 import { TokenResolver, validateTokenFile, TokenValidationError, parseTokenFileSync, TokenParseError } from '@agent-scope/tokens';
 
-// src/manifest-commands.ts
+// src/init/index.ts
+function hasConfigFile(dir, stem) {
+  if (!existsSync(dir)) return false;
+  try {
+    const entries = readdirSync(dir);
+    return entries.some((f) => f === stem || f.startsWith(`${stem}.`));
+  } catch {
+    return false;
+  }
+}
+function readSafe(path) {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function detectFramework(rootDir, packageDeps) {
+  if (hasConfigFile(rootDir, "next.config")) return "next";
+  if (hasConfigFile(rootDir, "vite.config")) return "vite";
+  if (hasConfigFile(rootDir, "remix.config")) return "remix";
+  if ("react-scripts" in packageDeps) return "cra";
+  return "unknown";
+}
+function detectPackageManager(rootDir) {
+  if (existsSync(join(rootDir, "bun.lock"))) return "bun";
+  if (existsSync(join(rootDir, "yarn.lock"))) return "yarn";
+  if (existsSync(join(rootDir, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(rootDir, "package-lock.json"))) return "npm";
+  return "npm";
+}
+function detectTypeScript(rootDir) {
+  const candidate = join(rootDir, "tsconfig.json");
+  if (existsSync(candidate)) {
+    return { typescript: true, tsconfigPath: candidate };
+  }
+  return { typescript: false, tsconfigPath: null };
+}
+var COMPONENT_DIRS = ["src/components", "src/app", "src/pages", "src/ui", "src/features", "src"];
+var COMPONENT_EXTS = [".tsx", ".jsx"];
+function detectComponentPatterns(rootDir, typescript) {
+  const patterns = [];
+  const ext = typescript ? "tsx" : "jsx";
+  const altExt = typescript ? "jsx" : "jsx";
+  for (const dir of COMPONENT_DIRS) {
+    const absDir = join(rootDir, dir);
+    if (!existsSync(absDir)) continue;
+    let hasComponents = false;
+    try {
+      const entries = readdirSync(absDir, { withFileTypes: true });
+      hasComponents = entries.some(
+        (e) => e.isFile() && COMPONENT_EXTS.some((x) => e.name.endsWith(x))
+      );
+      if (!hasComponents) {
+        hasComponents = entries.some(
+          (e) => e.isDirectory() && (() => {
+            try {
+              return readdirSync(join(absDir, e.name)).some(
+                (f) => COMPONENT_EXTS.some((x) => f.endsWith(x))
+              );
+            } catch {
+              return false;
+            }
+          })()
+        );
+      }
+    } catch {
+      continue;
+    }
+    if (hasComponents) {
+      patterns.push(`${dir}/**/*.${ext}`);
+      if (altExt !== ext) {
+        patterns.push(`${dir}/**/*.${altExt}`);
+      }
+    }
+  }
+  const unique = [...new Set(patterns)];
+  if (unique.length === 0) {
+    return [`**/*.${ext}`];
+  }
+  return unique;
+}
+var TAILWIND_STEMS = ["tailwind.config"];
+var CSS_EXTS = [".css", ".scss", ".sass", ".less"];
+var THEME_SUFFIXES = [".theme.ts", ".theme.js", ".theme.tsx"];
+var CSS_CUSTOM_PROPS_RE = /:root\s*\{[^}]*--[a-zA-Z]/;
+function detectTokenSources(rootDir) {
+  const sources = [];
+  for (const stem of TAILWIND_STEMS) {
+    if (hasConfigFile(rootDir, stem)) {
+      try {
+        const entries = readdirSync(rootDir);
+        const match = entries.find((f) => f === stem || f.startsWith(`${stem}.`));
+        if (match) {
+          sources.push({ kind: "tailwind-config", path: join(rootDir, match) });
+        }
+      } catch {
+      }
+    }
+  }
+  const srcDir = join(rootDir, "src");
+  const dirsToScan = existsSync(srcDir) ? [srcDir] : [];
+  for (const scanDir of dirsToScan) {
+    try {
+      const entries = readdirSync(scanDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isFile() && CSS_EXTS.some((x) => entry.name.endsWith(x))) {
+          const filePath = join(scanDir, entry.name);
+          const content = readSafe(filePath);
+          if (content !== null && CSS_CUSTOM_PROPS_RE.test(content)) {
+            sources.push({ kind: "css-custom-properties", path: filePath });
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  if (existsSync(srcDir)) {
+    try {
+      const entries = readdirSync(srcDir);
+      for (const entry of entries) {
+        if (THEME_SUFFIXES.some((s) => entry.endsWith(s))) {
+          sources.push({ kind: "theme-file", path: join(srcDir, entry) });
+        }
+      }
+    } catch {
+    }
+  }
+  return sources;
+}
+function detectProject(rootDir) {
+  const pkgPath = join(rootDir, "package.json");
+  let packageDeps = {};
+  const pkgContent = readSafe(pkgPath);
+  if (pkgContent !== null) {
+    try {
+      const pkg = JSON.parse(pkgContent);
+      packageDeps = {
+        ...pkg.dependencies,
+        ...pkg.devDependencies
+      };
+    } catch {
+    }
+  }
+  const framework = detectFramework(rootDir, packageDeps);
+  const { typescript, tsconfigPath } = detectTypeScript(rootDir);
+  const packageManager = detectPackageManager(rootDir);
+  const componentPatterns = detectComponentPatterns(rootDir, typescript);
+  const tokenSources = detectTokenSources(rootDir);
+  return {
+    framework,
+    typescript,
+    tsconfigPath,
+    componentPatterns,
+    tokenSources,
+    packageManager
+  };
+}
+function buildDefaultConfig(detected, tokenFile, outputDir) {
+  const include = detected.componentPatterns.length > 0 ? detected.componentPatterns : ["src/**/*.tsx"];
+  return {
+    components: {
+      include,
+      exclude: ["**/*.test.tsx", "**/*.stories.tsx"],
+      wrappers: { providers: [], globalCSS: [] }
+    },
+    render: {
+      viewport: { default: { width: 1280, height: 800 } },
+      theme: "light",
+      warmBrowser: true
+    },
+    tokens: {
+      file: tokenFile,
+      compliance: { threshold: 90 }
+    },
+    output: {
+      dir: outputDir,
+      sprites: { format: "png", cellPadding: 8, labelAxes: true },
+      json: { pretty: true }
+    },
+    ci: {
+      complianceThreshold: 90,
+      failOnA11yViolations: true,
+      failOnConsoleErrors: false,
+      baselinePath: `${outputDir}baseline/`
+    }
+  };
+}
+function createRL() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+}
+async function ask(rl, question) {
+  return new Promise((resolve6) => {
+    rl.question(question, (answer) => {
+      resolve6(answer.trim());
+    });
+  });
+}
+async function askWithDefault(rl, label, defaultValue) {
+  const answer = await ask(rl, `  ${label} [${defaultValue}]: `);
+  return answer.length > 0 ? answer : defaultValue;
+}
+function ensureGitignoreEntry(rootDir, entry) {
+  const gitignorePath = join(rootDir, ".gitignore");
+  if (existsSync(gitignorePath)) {
+    const content = readFileSync(gitignorePath, "utf-8");
+    const normalised = entry.replace(/\/$/, "");
+    const lines = content.split("\n").map((l) => l.trim());
+    if (lines.includes(entry) || lines.includes(normalised)) {
+      return;
+    }
+    const suffix = content.endsWith("\n") ? "" : "\n";
+    appendFileSync(gitignorePath, `${suffix}${entry}
+`);
+  } else {
+    writeFileSync(gitignorePath, `${entry}
+`);
+  }
+}
+function scaffoldConfig(rootDir, config) {
+  const path = join(rootDir, "reactscope.config.json");
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}
+`);
+  return path;
+}
+function scaffoldTokenFile(rootDir, tokenFile) {
+  const path = join(rootDir, tokenFile);
+  if (!existsSync(path)) {
+    const stub = {
+      $schema: "https://raw.githubusercontent.com/FlatFilers/Scope/main/packages/tokens/schema.json",
+      tokens: {}
+    };
+    writeFileSync(path, `${JSON.stringify(stub, null, 2)}
+`);
+  }
+  return path;
+}
+function scaffoldOutputDir(rootDir, outputDir) {
+  const dirPath = join(rootDir, outputDir);
+  mkdirSync(dirPath, { recursive: true });
+  const keepPath = join(dirPath, ".gitkeep");
+  if (!existsSync(keepPath)) {
+    writeFileSync(keepPath, "");
+  }
+  return dirPath;
+}
+async function runInit(options) {
+  const rootDir = options.cwd ?? process.cwd();
+  const configPath = join(rootDir, "reactscope.config.json");
+  const created = [];
+  if (existsSync(configPath) && !options.force) {
+    const msg = "reactscope.config.json already exists. Run with --force to overwrite.";
+    process.stderr.write(`\u26A0\uFE0F  ${msg}
+`);
+    return { success: false, message: msg, created: [], skipped: true };
+  }
+  const detected = detectProject(rootDir);
+  const defaultTokenFile = "reactscope.tokens.json";
+  const defaultOutputDir = ".reactscope/";
+  let config = buildDefaultConfig(detected, defaultTokenFile, defaultOutputDir);
+  if (options.yes) {
+    process.stdout.write("\n\u{1F50D}  Detected project settings:\n");
+    process.stdout.write(`   Framework      : ${detected.framework}
+`);
+    process.stdout.write(`   TypeScript     : ${detected.typescript}
+`);
+    process.stdout.write(`   Include globs  : ${config.components.include.join(", ")}
+`);
+    process.stdout.write(`   Token file     : ${config.tokens.file}
+`);
+    process.stdout.write(`   Output dir     : ${config.output.dir}
+
+`);
+  } else {
+    const rl = createRL();
+    process.stdout.write("\n\u{1F680}  scope init \u2014 project configuration\n");
+    process.stdout.write("   Press Enter to accept the detected value shown in brackets.\n\n");
+    try {
+      process.stdout.write(`   Detected framework: ${detected.framework}
+`);
+      const includeRaw = await askWithDefault(
+        rl,
+        "Component include patterns (comma-separated)",
+        config.components.include.join(", ")
+      );
+      config.components.include = includeRaw.split(",").map((s) => s.trim()).filter(Boolean);
+      const excludeRaw = await askWithDefault(
+        rl,
+        "Component exclude patterns (comma-separated)",
+        config.components.exclude.join(", ")
+      );
+      config.components.exclude = excludeRaw.split(",").map((s) => s.trim()).filter(Boolean);
+      const tokenFile = await askWithDefault(rl, "Token file location", config.tokens.file);
+      config.tokens.file = tokenFile;
+      config.ci.baselinePath = `${config.output.dir}baseline/`;
+      const outputDir = await askWithDefault(rl, "Output directory", config.output.dir);
+      config.output.dir = outputDir.endsWith("/") ? outputDir : `${outputDir}/`;
+      config.ci.baselinePath = `${config.output.dir}baseline/`;
+      config = buildDefaultConfig(detected, config.tokens.file, config.output.dir);
+      config.components.include = includeRaw.split(",").map((s) => s.trim()).filter(Boolean);
+      config.components.exclude = excludeRaw.split(",").map((s) => s.trim()).filter(Boolean);
+    } finally {
+      rl.close();
+    }
+    process.stdout.write("\n");
+  }
+  const cfgPath = scaffoldConfig(rootDir, config);
+  created.push(cfgPath);
+  const tokPath = scaffoldTokenFile(rootDir, config.tokens.file);
+  created.push(tokPath);
+  const outDirPath = scaffoldOutputDir(rootDir, config.output.dir);
+  created.push(outDirPath);
+  ensureGitignoreEntry(rootDir, config.output.dir);
+  process.stdout.write("\u2705  Scope project initialised!\n\n");
+  process.stdout.write("   Created files:\n");
+  for (const p of created) {
+    process.stdout.write(`     ${p}
+`);
+  }
+  process.stdout.write("\n   Next steps: run `scope manifest` to scan your components.\n\n");
+  return {
+    success: true,
+    message: "Project initialised successfully.",
+    created,
+    skipped: false
+  };
+}
+function createInitCommand() {
+  return new Command("init").description("Initialise a Scope project \u2014 scaffold reactscope.config.json and friends").option("-y, --yes", "Accept all detected defaults without prompting", false).option("--force", "Overwrite existing reactscope.config.json if present", false).action(async (opts) => {
+    try {
+      const result = await runInit({ yes: opts.yes, force: opts.force });
+      if (!result.success && !result.skipped) {
+        process.exit(1);
+      }
+    } catch (err) {
+      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.exit(1);
+    }
+  });
+}
 
 // src/manifest-formatter.ts
 function isTTY() {
@@ -2362,9 +2706,10 @@ function createProgram(options = {}) {
   program.addCommand(createRenderCommand());
   program.addCommand(createTokensCommand());
   program.addCommand(createInstrumentCommand());
+  program.addCommand(createInitCommand());
   return program;
 }
 
-export { createManifestCommand, createProgram, createTokensCommand, isTTY, matchGlob };
+export { createInitCommand, createManifestCommand, createProgram, createTokensCommand, isTTY, matchGlob, runInit };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map