@agent-scope/cli 1.6.0 → 1.7.0

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // src/program.ts
-import { readFileSync as readFileSync3 } from "fs";
+import { readFileSync as readFileSync4 } from "fs";
 import { generateTest, loadTrace } from "@agent-scope/playwright";
-import { Command as Command3 } from "commander";
+import { Command as Command4 } from "commander";
 
 // src/browser.ts
 import { writeFileSync } from "fs";
@@ -1499,9 +1499,363 @@ function buildStructuredReport(report) {
   };
 }
 
+// src/tokens/commands.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { resolve as resolve4 } from "path";
+import {
+  parseTokenFileSync,
+  TokenParseError,
+  TokenResolver,
+  TokenValidationError,
+  validateTokenFile
+} from "@agent-scope/tokens";
+import { Command as Command3 } from "commander";
+var DEFAULT_TOKEN_FILE = "reactscope.tokens.json";
+var CONFIG_FILE = "reactscope.config.json";
+function isTTY2() {
+  return process.stdout.isTTY === true;
+}
+function pad3(value, width) {
+  return value.length >= width ? value.slice(0, width) : value + " ".repeat(width - value.length);
+}
+function buildTable2(headers, rows) {
+  const colWidths = headers.map(
+    (h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length))
+  );
+  const divider = colWidths.map((w) => "-".repeat(w)).join("  ");
+  const headerRow = headers.map((h, i) => pad3(h, colWidths[i] ?? 0)).join("  ");
+  const dataRows = rows.map(
+    (row2) => row2.map((cell, i) => pad3(cell ?? "", colWidths[i] ?? 0)).join("  ")
+  );
+  return [headerRow, divider, ...dataRows].join("\n");
+}
+function resolveTokenFilePath(fileFlag) {
+  if (fileFlag !== void 0) {
+    return resolve4(process.cwd(), fileFlag);
+  }
+  const configPath = resolve4(process.cwd(), CONFIG_FILE);
+  if (existsSync3(configPath)) {
+    try {
+      const raw = readFileSync3(configPath, "utf-8");
+      const config = JSON.parse(raw);
+      if (typeof config === "object" && config !== null && "tokens" in config && typeof config.tokens === "object" && config.tokens !== null && typeof config.tokens?.file === "string") {
+        const file = config.tokens.file;
+        return resolve4(process.cwd(), file);
+      }
+    } catch {
+    }
+  }
+  return resolve4(process.cwd(), DEFAULT_TOKEN_FILE);
+}
+function loadTokens(absPath) {
+  if (!existsSync3(absPath)) {
+    throw new Error(
+      `Token file not found at ${absPath}.
+Create a reactscope.tokens.json file or use --file to specify a path.`
+    );
+  }
+  const raw = readFileSync3(absPath, "utf-8");
+  return parseTokenFileSync(raw);
+}
+function getRawValue(node, segments) {
+  const [head, ...rest] = segments;
+  if (head === void 0) return null;
+  const child = node[head];
+  if (child === void 0 || child === null) return null;
+  if (rest.length === 0) {
+    if (typeof child === "object" && !Array.isArray(child) && "value" in child) {
+      const v = child.value;
+      return typeof v === "string" || typeof v === "number" ? v : null;
+    }
+    return null;
+  }
+  if (typeof child === "object" && !Array.isArray(child)) {
+    return getRawValue(child, rest);
+  }
+  return null;
+}
+function buildResolutionChain(startPath, rawTokens) {
+  const chain = [];
+  const seen = /* @__PURE__ */ new Set();
+  let current = startPath;
+  while (!seen.has(current)) {
+    seen.add(current);
+    const rawValue = getRawValue(rawTokens, current.split("."));
+    if (rawValue === null) break;
+    chain.push({ path: current, rawValue: String(rawValue) });
+    const refMatch = /^\{([^}]+)\}$/.exec(String(rawValue));
+    if (refMatch === null) break;
+    current = refMatch[1] ?? "";
+  }
+  return chain;
+}
+function registerGet2(tokensCmd) {
+  tokensCmd.command("get <path>").description("Resolve a token path to its computed value").option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((tokenPath, opts) => {
+    try {
+      const filePath = resolveTokenFilePath(opts.file);
+      const { tokens } = loadTokens(filePath);
+      const resolver = new TokenResolver(tokens);
+      const resolvedValue = resolver.resolve(tokenPath);
+      const useJson = opts.format === "json" || opts.format !== "text" && !isTTY2();
+      if (useJson) {
+        const token = tokens.find((t) => t.path === tokenPath);
+        process.stdout.write(
+          `${JSON.stringify({ path: tokenPath, value: token?.value, resolvedValue, type: token?.type }, null, 2)}
+`
+        );
+      } else {
+        process.stdout.write(`${resolvedValue}
+`);
+      }
+    } catch (err) {
+      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.exit(1);
+    }
+  });
+}
+function registerList2(tokensCmd) {
+  tokensCmd.command("list [category]").description("List tokens, optionally filtered by category or type").option("--type <type>", "Filter by token type (color, dimension, fontFamily, etc.)").option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or table (default: auto-detect)").action(
+    (category, opts) => {
+      try {
+        const filePath = resolveTokenFilePath(opts.file);
+        const { tokens } = loadTokens(filePath);
+        const resolver = new TokenResolver(tokens);
+        const filtered = resolver.list(opts.type, category);
+        const useJson = opts.format === "json" || opts.format !== "table" && !isTTY2();
+        if (useJson) {
+          process.stdout.write(`${JSON.stringify(filtered, null, 2)}
+`);
+        } else {
+          if (filtered.length === 0) {
+            process.stdout.write("No tokens found.\n");
+            return;
+          }
+          const headers = ["PATH", "VALUE", "RESOLVED", "TYPE"];
+          const rows = filtered.map((t) => [t.path, String(t.value), t.resolvedValue, t.type]);
+          process.stdout.write(`${buildTable2(headers, rows)}
+`);
+        }
+      } catch (err) {
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+        process.exit(1);
+      }
+    }
+  );
+}
+function registerSearch(tokensCmd) {
+  tokensCmd.command("search <value>").description("Find which token(s) match a computed value (supports fuzzy color matching)").option("--type <type>", "Restrict search to a specific token type").option("--fuzzy", "Return nearest match even if no exact match exists", false).option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or table (default: auto-detect)").action(
+    (value, opts) => {
+      try {
+        const filePath = resolveTokenFilePath(opts.file);
+        const { tokens } = loadTokens(filePath);
+        const resolver = new TokenResolver(tokens);
+        const useJson = opts.format === "json" || opts.format !== "table" && !isTTY2();
+        const typesToSearch = opts.type ? [opts.type] : [
+          "color",
+          "dimension",
+          "fontFamily",
+          "fontWeight",
+          "number",
+          "shadow",
+          "duration",
+          "cubicBezier"
+        ];
+        const exactMatches = [];
+        const nearestMatches = [];
+        for (const type of typesToSearch) {
+          const exact = resolver.match(value, type);
+          if (exact !== null) {
+            exactMatches.push({
+              path: exact.token.path,
+              resolvedValue: exact.token.resolvedValue,
+              type: exact.token.type,
+              exact: true,
+              distance: 0
+            });
+          }
+        }
+        if (exactMatches.length === 0 && opts.fuzzy) {
+          for (const type of typesToSearch) {
+            const typeTokens = tokens.filter((t) => t.type === type);
+            if (typeTokens.length === 0) continue;
+            try {
+              const near = resolver.nearest(value, type);
+              nearestMatches.push({
+                path: near.token.path,
+                resolvedValue: near.token.resolvedValue,
+                type: near.token.type,
+                exact: near.exact,
+                distance: near.distance
+              });
+            } catch {
+            }
+          }
+          nearestMatches.sort((a, b) => a.distance - b.distance);
+          nearestMatches.splice(3);
+        }
+        const results = exactMatches.length > 0 ? exactMatches : nearestMatches;
+        if (useJson) {
+          process.stdout.write(`${JSON.stringify(results, null, 2)}
+`);
+        } else {
+          if (results.length === 0) {
+            process.stdout.write(
+              `No tokens found matching "${value}".
+Tip: use --fuzzy for nearest-match search.
+`
+            );
+            return;
+          }
+          const headers = ["PATH", "RESOLVED VALUE", "TYPE", "MATCH", "DISTANCE"];
+          const rows = results.map((r) => [
+            r.path,
+            r.resolvedValue,
+            r.type,
+            r.exact ? "exact" : "nearest",
+            r.exact ? "\u2014" : r.distance.toFixed(2)
+          ]);
+          process.stdout.write(`${buildTable2(headers, rows)}
+`);
+        }
+      } catch (err) {
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+        process.exit(1);
+      }
+    }
+  );
+}
+function registerResolve(tokensCmd) {
+  tokensCmd.command("resolve <path>").description("Show the full resolution chain for a token").option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((tokenPath, opts) => {
+    try {
+      const filePath = resolveTokenFilePath(opts.file);
+      const absFilePath = filePath;
+      const { tokens, rawFile } = loadTokens(absFilePath);
+      const resolver = new TokenResolver(tokens);
+      resolver.resolve(tokenPath);
+      const chain = buildResolutionChain(tokenPath, rawFile.tokens);
+      const useJson = opts.format === "json" || opts.format !== "text" && !isTTY2();
+      if (useJson) {
+        process.stdout.write(`${JSON.stringify({ path: tokenPath, chain }, null, 2)}
+`);
+      } else {
+        if (chain.length === 0) {
+          process.stdout.write(`Token "${tokenPath}" not found.
+`);
+          return;
+        }
+        const parts = chain.map((step, i) => {
+          if (i < chain.length - 1) {
+            return `${step.path} \u2192 ${step.rawValue}`;
+          }
+          return step.rawValue;
+        });
+        process.stdout.write(`${parts.join("\n  ")}
+`);
+      }
+    } catch (err) {
+      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.exit(1);
+    }
+  });
+}
+function registerValidate(tokensCmd) {
+  tokensCmd.command("validate").description(
+    "Validate the token file for errors (circular refs, missing refs, type mismatches)"
+  ).option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((opts) => {
+    try {
+      const filePath = resolveTokenFilePath(opts.file);
+      if (!existsSync3(filePath)) {
+        throw new Error(
+          `Token file not found at ${filePath}.
+Create a reactscope.tokens.json file or use --file to specify a path.`
+        );
+      }
+      const raw = readFileSync3(filePath, "utf-8");
+      const useJson = opts.format === "json" || opts.format !== "text" && !isTTY2();
+      const errors = [];
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch (err) {
+        errors.push({
+          code: "PARSE_ERROR",
+          message: `Failed to parse token file as JSON: ${String(err)}`
+        });
+        outputValidationResult(filePath, errors, useJson);
+        process.exit(1);
+      }
+      try {
+        validateTokenFile(parsed);
+      } catch (err) {
+        if (err instanceof TokenValidationError) {
+          for (const e of err.errors) {
+            errors.push({ code: e.code, path: e.path, message: e.message });
+          }
+          outputValidationResult(filePath, errors, useJson);
+          process.exit(1);
+        }
+        throw err;
+      }
+      try {
+        parseTokenFileSync(raw);
+      } catch (err) {
+        if (err instanceof TokenParseError) {
+          errors.push({ code: err.code, path: err.path, message: err.message });
+        } else {
+          errors.push({ code: "UNKNOWN", message: String(err) });
+        }
+        outputValidationResult(filePath, errors, useJson);
+        process.exit(1);
+      }
+      outputValidationResult(filePath, errors, useJson);
+    } catch (err) {
+      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.exit(1);
+    }
+  });
+}
+function outputValidationResult(filePath, errors, useJson) {
+  const valid = errors.length === 0;
+  if (useJson) {
+    process.stdout.write(`${JSON.stringify({ valid, file: filePath, errors }, null, 2)}
+`);
+  } else {
+    if (valid) {
+      process.stdout.write(`\u2713 Token file is valid: ${filePath}
+`);
+    } else {
+      process.stderr.write(`\u2717 Token file has ${errors.length} error(s): ${filePath}
+
+`);
+      for (const e of errors) {
+        const pathPrefix = e.path ? ` [${e.path}]` : "";
+        process.stderr.write(`  ${e.code}${pathPrefix}: ${e.message}
+`);
+      }
+      process.exit(1);
+    }
+  }
+}
+function createTokensCommand() {
+  const tokensCmd = new Command3("tokens").description(
+    "Query and validate design tokens from a reactscope.tokens.json file"
+  );
+  registerGet2(tokensCmd);
+  registerList2(tokensCmd);
+  registerSearch(tokensCmd);
+  registerResolve(tokensCmd);
+  registerValidate(tokensCmd);
+  return tokensCmd;
+}
+
 // src/program.ts
 function createProgram(options = {}) {
-  const program2 = new Command3("scope").version(options.version ?? "0.1.0").description("Scope \u2014 React instrumentation toolkit");
+  const program2 = new Command4("scope").version(options.version ?? "0.1.0").description("Scope \u2014 React instrumentation toolkit");
   program2.command("capture <url>").description("Capture a React component tree from a live URL and output as JSON").option("-o, --output <path>", "Write JSON to file instead of stdout").option("--pretty", "Pretty-print JSON output (default: minified)", false).option("--timeout <ms>", "Max wait time for React to mount (ms)", "10000").option("--wait <ms>", "Additional wait after page load before capture (ms)", "0").action(
     async (url, opts) => {
       try {
@@ -1574,7 +1928,7 @@ function createProgram(options = {}) {
     }
   );
   program2.command("generate").description("Generate a Playwright test from a Scope trace file").argument("<trace>", "Path to a serialized Scope trace (.json)").option("-o, --output <path>", "Output file path", "scope.spec.ts").option("-d, --description <text>", "Test description").action((tracePath, opts) => {
-    const raw = readFileSync3(tracePath, "utf-8");
+    const raw = readFileSync4(tracePath, "utf-8");
     const trace = loadTrace(raw);
     const source = generateTest(trace, {
       description: opts.description,
@@ -1585,6 +1939,7 @@ function createProgram(options = {}) {
   });
   program2.addCommand(createManifestCommand());
   program2.addCommand(createRenderCommand());
+  program2.addCommand(createTokensCommand());
   return program2;
 }