@agent-scope/cli 1.5.0 → 1.7.0

package/dist/index.d.cts

@@ -62,4 +62,9 @@ interface ScopeCLIOptions {
 /** Build and return the Scope CLI program */
 declare function createProgram(options?: ScopeCLIOptions): Command;
 
-export { type ListRow, type QueryRow, type ScopeCLIOptions, createManifestCommand, createProgram, isTTY, matchGlob };
+/**
+ * Create and return the `tokens` command group.
+ */
+declare function createTokensCommand(): Command;
+
+export { type ListRow, type QueryRow, type ScopeCLIOptions, createManifestCommand, createProgram, createTokensCommand, isTTY, matchGlob };

package/dist/index.d.ts

@@ -62,4 +62,9 @@ interface ScopeCLIOptions {
 /** Build and return the Scope CLI program */
 declare function createProgram(options?: ScopeCLIOptions): Command;
 
-export { type ListRow, type QueryRow, type ScopeCLIOptions, createManifestCommand, createProgram, isTTY, matchGlob };
+/**
+ * Create and return the `tokens` command group.
+ */
+declare function createTokensCommand(): Command;
+
+export { type ListRow, type QueryRow, type ScopeCLIOptions, createManifestCommand, createProgram, createTokensCommand, isTTY, matchGlob };

package/dist/index.js

@@ -7,6 +7,7 @@ import { chromium } from 'playwright';
 import { safeRender, ALL_CONTEXT_IDS, contextAxis, stressAxis, ALL_STRESS_IDS, RenderMatrix, SatoriRenderer, BrowserPool } from '@agent-scope/render';
 import * as esbuild from 'esbuild';
 import { createRequire } from 'module';
+import { TokenResolver, validateTokenFile, TokenValidationError, parseTokenFileSync, TokenParseError } from '@agent-scope/tokens';
 
 // src/manifest-commands.ts
 
@@ -1465,6 +1466,348 @@ function buildStructuredReport(report) {
     route: report.route?.pattern ?? null
   };
 }
+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 resolve(process.cwd(), fileFlag);
+  }
+  const configPath = resolve(process.cwd(), CONFIG_FILE);
+  if (existsSync(configPath)) {
+    try {
+      const raw = readFileSync(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 resolve(process.cwd(), file);
+      }
+    } catch {
+    }
+  }
+  return resolve(process.cwd(), DEFAULT_TOKEN_FILE);
+}
+function loadTokens(absPath) {
+  if (!existsSync(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 = readFileSync(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 (!existsSync(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 = readFileSync(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 Command("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 = {}) {
@@ -1552,9 +1895,10 @@ function createProgram(options = {}) {
   });
   program.addCommand(createManifestCommand());
   program.addCommand(createRenderCommand());
+  program.addCommand(createTokensCommand());
   return program;
 }
 
-export { createManifestCommand, createProgram, isTTY, matchGlob };
+export { createManifestCommand, createProgram, createTokensCommand, isTTY, matchGlob };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map