@smallpen/cli 0.1.0-alpha.2 → 0.1.0-alpha.5

package/bin/smallpen.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import {
   mkdir,
   readdir,
@@ -20,7 +20,7 @@ import {
   createCompareView,
   createInitializationState,
   diffDrafts,
-  designTokenWarningsForBatch,
+  designTokenAdviceForBatch,
   draftFromSnapshot,
   explainEffectiveToken,
   importTokens,
@@ -36,6 +36,7 @@ import {
   applyOperationBatch,
   createEvidence,
   defaultLibraryCacheRoot,
+  fontVariantName,
   importDraft,
   importFontVariant,
   importMedia,
@@ -52,11 +53,13 @@ import {
 } from "@smallpen/local-package";
 
 import { COMMAND_NAMES, printHelp } from "./help.mjs";
+import { schemaTopic } from "./schema.mjs";
 import { warningOutput } from "./warning-output.mjs";
 
 const FLAG_OPTIONS = new Set([
   "--apply",
   "--base64",
+  "--compact",
   "--confirm",
   "--confirm-unmatched",
   "--diff",
@@ -67,9 +70,22 @@ const FLAG_OPTIONS = new Set([
   "--json",
   "-h",
 ]);
+// Value options read with options(); every other value option is single.
+const REPEATABLE_OPTIONS = new Set(["--answer", "--context", "--select", "--selector"]);
 const COMMAND_OPTIONS = {
   version: ["--json"],
-  apply: ["--batch", "--confirm-unmatched", "--diff", "--dry-run", "--explain", "--json", "--warning-detail"],
+  schema: ["--json"],
+  apply: [
+    "--batch",
+    "--compact",
+    "--confirm-unmatched",
+    "--diff",
+    "--dry-run",
+    "--explain",
+    "--inverse-out",
+    "--json",
+    "--warning-detail",
+  ],
   catalog: ["--context", "--json"],
   component: ["--component-id", "--json"],
   compare: ["--json", "--selector"],
@@ -114,17 +130,52 @@ const COMMAND_OPTIONS = {
   ],
   "render-matrix": ["--contexts", "--json", "--output", "--scale"],
   impact: ["--json", "--package-id", "--path", "--token-id"],
-  flow: ["--batch-id", "--confirm-unmatched", "--diff", "--dry-run", "--explain", "--intent", "--json", "--warning-detail"],
-  page: ["--batch-id", "--confirm-unmatched", "--diff", "--dry-run", "--explain", "--intent", "--json", "--warning-detail"],
-  token: ["--batch-id", "--confirm-unmatched", "--diff", "--dry-run", "--explain", "--intent", "--json", "--warning-detail"],
+  flow: [
+    "--batch-id",
+    "--compact",
+    "--confirm-unmatched",
+    "--diff",
+    "--dry-run",
+    "--explain",
+    "--intent",
+    "--inverse-out",
+    "--json",
+    "--warning-detail",
+  ],
+  page: [
+    "--batch-id",
+    "--compact",
+    "--confirm-unmatched",
+    "--diff",
+    "--dry-run",
+    "--explain",
+    "--intent",
+    "--inverse-out",
+    "--json",
+    "--warning-detail",
+  ],
+  token: [
+    "--batch-id",
+    "--compact",
+    "--confirm-unmatched",
+    "--diff",
+    "--dry-run",
+    "--explain",
+    "--intent",
+    "--inverse-out",
+    "--json",
+    "--warning-detail",
+  ],
   "explain-token": ["--context", "--json", "--package-id", "--token-id"],
   init: ["--answer", "--answers", "--confirm", "--json", "--locale", "--state"],
   "import-draft": ["--input", "--json", "--kind", "--package-id"],
   "import-tokens": [
     "--apply",
     "--batch-id",
+    "--compact",
     "--dry-run",
     "--input",
+    "--inverse-out",
     "--json",
     "--select",
     "--set-name",
@@ -135,14 +186,13 @@ const COMMAND_OPTIONS = {
     "--file",
     "--font-id",
     "--json",
-    "--media-path",
     "--name",
     "--style",
     "--variant-id",
     "--weight",
   ],
   "import-media": ["--file", "--json", "--media-id", "--media-path", "--name"],
-  "library-refresh": ["--interval", "--json", "--library", "--max-events"],
+  "library-refresh": ["--json", "--library"],
   watch: ["--interval", "--json", "--max-events"],
   list: ["--json", "--kind", "--limit", "--offset"],
   read: ["--json"],
@@ -191,14 +241,51 @@ const COMMAND_OPTIONS = {
     "--type",
     "--value",
   ],
-  tokens: ["--context", "--json"],
+  tokens: ["--context", "--json", "--locale"],
   validate: ["--json"],
 };
 
+// Localized labels follow the environment unless --locale is given: any
+// zh* locale selects the Chinese labels, everything else English.
+function defaultLocale() {
+  const source =
+    process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || "";
+  return /^zh/i.test(source) ? "zh-TW" : "en";
+}
+
+function tokenLabels(locale) {
+  return /^zh/i.test(locale)
+    ? { context: "設計狀態", items: "有效設計變數" }
+    : { context: "Design Context", items: "Effective Tokens" };
+}
+
 function isRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
+// Locale-independent order for JSON output: localeCompare follows the host
+// LANG (Danish sorts "aa" after "ab"), which would reorder lists and pages.
+function compareText(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+// Caller-supplied input files fail with a typed error instead of a raw
+// filesystem internal_error.
+async function readInputFile(path, optionName, encoding) {
+  try {
+    return await readFile(path, encoding);
+  } catch (error) {
+    if (!["EACCES", "EISDIR", "ENOENT", "ENOTDIR", "EPERM"].includes(error?.code)) {
+      throw error;
+    }
+    throw new SmallPenError(
+      "unreadable_input_file",
+      `${optionName} file cannot be read: ${error.message}`,
+      { option: optionName, path: resolve(path), reason: error.code },
+    );
+  }
+}
+
 function option(args, name) {
   const index = args.indexOf(name);
   if (index === -1) return undefined;
@@ -240,6 +327,7 @@ function validateCommandArguments(command, args) {
     "--help",
     "-h",
   ]);
+  const seen = new Set();
   for (let index = 2; index < args.length; index += 1) {
     const value = args[index];
     if (!value.startsWith("-")) {
@@ -256,7 +344,18 @@ function validateCommandArguments(command, args) {
         validOptions: [...allowed].sort(),
       });
     }
-    if (!FLAG_OPTIONS.has(value)) index += 1;
+    if (FLAG_OPTIONS.has(value)) continue;
+    // option() reads only the first occurrence; a second value would be
+    // silently ignored.
+    if (seen.has(value) && !REPEATABLE_OPTIONS.has(value)) {
+      throw new SmallPenError(
+        "duplicate_option",
+        `${value} may be given only once`,
+        { command, option: value },
+      );
+    }
+    seen.add(value);
+    index += 1;
   }
 }
 
@@ -343,7 +442,7 @@ function printJson(value) {
         child instanceof Map
           ? Object.fromEntries(
               [...child.entries()].sort(([left], [right]) =>
-                String(left).localeCompare(String(right)),
+                compareText(String(left), String(right)),
               ),
             )
           : child,
@@ -381,7 +480,7 @@ function inspect(snapshot) {
           screenId,
         }),
       ),
-    ].sort((left, right) => left.id.localeCompare(right.id)),
+    ].sort((left, right) => compareText(left.id, right.id)),
     contexts: {
       axes: [...snapshot.domain.contextAxes.values()],
       profiles: [...snapshot.domain.contextProfiles.values()],
@@ -613,7 +712,42 @@ function explainBatch(before, prepared, batch) {
   return { diff, explain };
 }
 
+// The full reply carries the inverse batch twice (inverseBatch and
+// guidance.undo), which is most of its size. inverseBatch stays in the
+// default reply because undo relies on it; --inverse-out saves it to a file
+// and --compact drops it from the reply in favour of a short summary.
+async function writeReply(result, args) {
+  const inverseOut = option(args, "--inverse-out");
+  const inverseBatchPath =
+    inverseOut !== undefined && result.inverseBatch && !result.dryRun
+      ? await writeAtomic(inverseOut, `${JSON.stringify(result.inverseBatch, null, 2)}\n`)
+      : undefined;
+  if (!flag(args, "--compact")) {
+    return inverseBatchPath ? { ...result, inverseBatchPath } : result;
+  }
+  const { guidance: _guidance, inverseBatch, ...rest } = result;
+  const files = (result.changedFiles?.length ?? 0) + (result.deletedFiles?.length ?? 0);
+  const warnings = result.warningSummary?.total ?? result.warnings?.length ?? 0;
+  const verb = result.dryRun ? "Previewed" : result.alreadyApplied ? "Already applied" : "Applied";
+  return {
+    ...rest,
+    ...(inverseBatch ? { inverseOperationCount: inverseBatch.operations.length } : {}),
+    ...(inverseBatchPath ? { inverseBatchPath } : {}),
+    summary:
+      `${verb} ${result.batchId}: revision ${result.revision}, ` +
+      `${files} changed file(s), ${result.affectedIds?.length ?? 0} affected id(s), ` +
+      `${warnings} warning(s).` +
+      (inverseBatchPath || !inverseBatch || result.dryRun
+        ? ""
+        : " The inverse batch was not kept: rerun writes with --inverse-out FILE to save it for undo."),
+  };
+}
+
 async function applyBatch(packagePath, batch, args) {
+  return writeReply(await prepareAndApplyBatch(packagePath, batch, args), args);
+}
+
+async function prepareAndApplyBatch(packagePath, batch, args) {
   const detail = option(args, "--warning-detail") ?? "compact";
   if (!["compact", "full"].includes(detail)) {
     throw new SmallPenError("invalid_warning_detail", "--warning-detail must be compact or full", {
@@ -626,11 +760,27 @@ async function applyBatch(packagePath, batch, args) {
       "CLI Operation Batch JSON cannot contain binary blob writes",
     );
   }
+  // High-level commands rebuild their batch from the current revision, so a
+  // retry with the same --batch-id after success carries the recorded result
+  // as its base and may no longer prepare (its nodes already exist). Consult
+  // the ledger first; previews never write and skip it.
+  if (
+    args[0] !== "apply" &&
+    option(args, "--batch-id") !== undefined &&
+    !flag(args, "--dry-run") &&
+    !flag(args, "--explain") &&
+    !flag(args, "--diff")
+  ) {
+    const replayed = await replayRecordedBatch(packagePath, batch, { rebuilt: true });
+    if (replayed) return replayed;
+  }
   // 通用 apply 仍然能修复处于 Repair 的 Product；Token 建议不能变成写入门禁。
-  const { foundation, product } = await tokenAdviceWorkspace(packagePath);
+  const { foundation, libraries, product } = await tokenAdviceWorkspace(packagePath);
   let prepared;
   try {
-    prepared = await prepareOperationBatch(product, batch);
+    // Foundation and Library components let preparation check Instance
+    // override paths that target them.
+    prepared = await prepareOperationBatch(product, batch, { foundation, libraries });
   } catch (error) {
     if (error?.code === "stale_revision") {
       const replayed = await replayRecordedBatch(packagePath, batch);
@@ -638,13 +788,17 @@ async function applyBatch(packagePath, batch, args) {
     }
     throw error;
   }
-  const warnings = designTokenWarningsForBatch(prepared.snapshot, batch, {
+  const { suppressed, warnings } = designTokenAdviceForBatch(prepared.snapshot, batch, {
     foundation,
   });
   // Import warnings have their own schema and are not design-style advice.
   const advice = args[0] === "import-tokens"
     ? { warnings }
-    : warningOutput(warnings, detail, { confirmUnmatched: flag(args, "--confirm-unmatched") });
+    : warningOutput(warnings, detail, {
+        confirmUnmatched: flag(args, "--confirm-unmatched"),
+        suppressed,
+      });
+  const change = changeSummary(product, prepared, batch);
   if (flag(args, "--explain") || flag(args, "--diff")) {
     // explain/diff are read-only previews in any combination; neither flag
     // writes, with or without --dry-run (CLI-AI-TOPIC: "explain and diff
@@ -652,19 +806,37 @@ async function applyBatch(packagePath, batch, args) {
     return {
       ...prepared.result,
       ...explainBatch(product, prepared, batch),
+      ...change,
       dryRun: true,
       ...advice,
     };
   }
   if (flag(args, "--dry-run")) {
-    return { ...prepared.result, dryRun: true, ...advice };
+    return { ...prepared.result, ...change, dryRun: true, ...advice };
   }
   return {
     ...(await applyOperationBatch(packagePath, batch)),
+    ...change,
     ...advice,
   };
 }
 
+// A valid batch can still leave every byte as it was (for example a value
+// that is already set). Say so instead of reporting a silent success.
+function changeSummary(before, prepared, batch) {
+  if (prepared.snapshot.revision !== before.revision) return { changed: true };
+  return {
+    changed: false,
+    noChange: {
+      code: "no_change",
+      message:
+        `The batch is valid but changes nothing: the ${batch.operations.length} ` +
+        "operation(s) leave the Package at its current revision. Check the " +
+        "target ids and values (smallpen read-view PACKAGE --format semantic --json).",
+    },
+  };
+}
+
 function searchValue(args) {
   const color = option(args, "--color");
   const source = option(args, "--value");
@@ -799,17 +971,24 @@ async function initializeCommand(workspacePath, args) {
   const answersPath = option(args, "--answers");
   if (answersPath) {
     fileAnswers = parseJson(
-      await readFile(answersPath, "utf8"),
+      await readInputFile(answersPath, "--answers", "utf8"),
       "invalid_initialization_answers_json",
       { path: answersPath },
     );
+    if (!isRecord(fileAnswers)) {
+      throw new SmallPenError(
+        "invalid_initialization_answers_json",
+        "--answers must contain a JSON object keyed by question id",
+        { path: answersPath },
+      );
+    }
   }
   const answers = {
     ...(persisted.answers ?? {}),
     ...fileAnswers,
     ...answerArguments(args),
   };
-  const locale = option(args, "--locale") ?? "zh-TW";
+  const locale = option(args, "--locale") ?? defaultLocale();
   let state = createInitializationState(answers, {
     locale,
     statePath,
@@ -832,7 +1011,22 @@ async function initializeCommand(workspacePath, args) {
   if (state.status === "needs_input") {
     state.nextQuestion.continuation.args[1] = resolve(workspacePath);
     state.nextQuestion.continuation.args.push("--locale", locale);
-    return { ...state, statePath };
+    return {
+      ...state,
+      answersTemplate:
+        "smallpen schema init prints every question and a complete answers file for --answers",
+      // Without --state a call never reads earlier answers, so a chain of
+      // single --answer calls would keep only the last one.
+      ...(explicitStatePath
+        ? {}
+        : {
+            stateNotice:
+              "This call did not read earlier answers because --state was not given. " +
+              "Pass --state with the statePath below on every call (as continuation.args does) " +
+              "to collect answers one at a time, or answer everything at once with --answers FILE.",
+          }),
+      statePath,
+    };
   }
   const confirmation = {
     args: [
@@ -862,7 +1056,160 @@ async function initializeCommand(workspacePath, args) {
       status: "initialized",
     }),
   );
-  return { ...initialized, statePath };
+  return { ...initialized, ...(await initializedSummary(initialized)), statePath };
+}
+
+// The init reply names every id the first writes need (Packages, Screen,
+// root node, starter Tokens and Component Sets), so an Agent can start
+// without reading the new files.
+async function initializedSummary({ foundationPath, productPath }) {
+  const foundation = await openPackage(foundationPath);
+  const product = await openPackage(productPath);
+  const screenEntry = product.manifest.entries.screens.find(
+    (entry) => product.entries[entry].id === product.manifest.defaultScreenId,
+  );
+  const screen = product.entries[screenEntry];
+  const presentation = screen.presentations.find(
+    ({ id }) => id === screen.basePresentationId,
+  );
+  const root = presentation.nodes[presentation.rootId];
+  const packageSummary = (snapshot) => ({
+    packageId: snapshot.manifest.packageId,
+    path: snapshot.locator,
+    revision: snapshot.revision,
+  });
+  return {
+    packages: {
+      foundation: packageSummary(foundation),
+      product: packageSummary(product),
+    },
+    start: {
+      contextAxes: [...foundation.domain.contextAxes.values()].map(
+        ({ defaultValue, id, values }) => ({
+          defaultValue,
+          id,
+          values: values.map((value) => value.id),
+        }),
+      ),
+      presentationId: presentation.id,
+      rootNode: { height: root.height, id: root.id, width: root.width },
+      scenarioIds: [...product.domain.scenarios.keys()].sort(compareText),
+      screenId: screen.id,
+    },
+    seeded: {
+      componentSets: [...foundation.domain.componentSets.values()].map(
+        ({ axes, id, name, variants }) => ({
+          axes: axes.map((axis) => axis.id),
+          componentSetId: id,
+          name,
+          packageId: foundation.manifest.packageId,
+          variants: variants.map((variant) => ({
+            rootId: variant.rootId,
+            selection: variant.selection,
+            variantId: variant.id,
+          })),
+        }),
+      ),
+      note:
+        "Starter content. put-token or put-component-set with one of these ids replaces it " +
+        "whole (no merge). Write Tokens and Component Sets to packages.foundation.path; " +
+        "write Screens and nodes to packages.product.path.",
+      tokens: [...foundation.domain.tokens.values()].map(
+        ({ filePath, id, path, rawValue, type }) => ({
+          filePath,
+          packageId: foundation.manifest.packageId,
+          path,
+          tokenId: id,
+          type,
+          value: rawValue,
+        }),
+      ),
+    },
+  };
+}
+
+// The renderer reports one font_render_fallback per text node. Collapse them
+// to one diagnostic per missing family that names the fonts it can draw and
+// the import-font command that adds the missing one.
+async function renderEvidence(product, options) {
+  const bundle = await createEvidence(product, options);
+  const fallbacks = new Map();
+  const diagnostics = [];
+  for (const diagnostic of bundle.render.diagnostics) {
+    if (diagnostic.code !== "font_render_fallback") {
+      diagnostics.push(diagnostic);
+      continue;
+    }
+    const requestedFont =
+      diagnostic.details?.requestedFont ??
+      /substituted .+ for (.+)$/.exec(diagnostic.message)?.[1] ??
+      "<family>";
+    let collapsed = fallbacks.get(requestedFont);
+    if (!collapsed) {
+      collapsed = { diagnostic, nodeIds: [], paths: [], requestedFont };
+      fallbacks.set(requestedFont, collapsed);
+      diagnostics.push(collapsed);
+    }
+    if (diagnostic.nodeId !== undefined) collapsed.nodeIds.push(diagnostic.nodeId);
+    if (diagnostic.path !== undefined) collapsed.paths.push(diagnostic.path);
+  }
+  if (fallbacks.size === 0) return bundle;
+  const imported = [
+    ...new Set(
+      [options.foundation, ...(options.libraries ?? []), product]
+        .filter(Boolean)
+        .flatMap((snapshot) =>
+          snapshot.manifest.entries.assets.flatMap((entry) =>
+            (snapshot.entries[entry].fonts ?? []).map(({ family }) => family),
+          ),
+        ),
+    ),
+  ].sort(compareText);
+  const availableFonts = [
+    "Source Sans Pro (bundled)",
+    ...imported.map((family) => `${family} (imported)`),
+  ];
+  const collapsedEntries = new Set(fallbacks.values());
+  const explained = diagnostics.map((entry) => {
+    if (!collapsedEntries.has(entry)) return entry;
+    const { requestedFont } = entry;
+    return {
+      availableFonts,
+      code: entry.diagnostic.code,
+      details: {
+        ...entry.diagnostic.details,
+        requestedFont,
+        substituteFont: entry.diagnostic.details?.substituteFont ?? "Source Sans Pro",
+      },
+      message:
+        `${entry.diagnostic.message} on ${entry.nodeIds.length} text node(s): ` +
+        `${requestedFont} is neither bundled nor imported. Available fonts: ` +
+        `${availableFonts.join(", ")}. Import ${requestedFont} with smallpen import-font ` +
+        "(once per weight/style; see nextOperations), or use an available family.",
+      nextOperations: [
+        {
+          argv: [
+            "import-font",
+            product.locator,
+            "--file",
+            `<${requestedFont} .ttf|.otf|.woff file>`,
+            "--family",
+            requestedFont,
+            "--weight",
+            "<400|700|...>",
+            "--json",
+          ],
+          operation: "smallpen.import-font",
+        },
+      ],
+      nodeIds: entry.nodeIds,
+      paths: entry.paths,
+      requestedFont,
+    };
+  });
+  bundle.render.diagnostics = explained;
+  bundle.evidence.diagnostics = explained;
+  return bundle;
 }
 
 async function deliverImage(
@@ -900,7 +1247,7 @@ async function renderCommand(packagePath, args, evidenceOnly) {
   }
   const workspace = await tokenWorkspace(packagePath);
   const { foundation, libraries, product } = workspace;
-  const bundle = await createEvidence(product, {
+  const bundle = await renderEvidence(product, {
     foundation,
     libraries,
     scale: numberOption(args, "--scale", 1),
@@ -950,13 +1297,13 @@ async function inspectViewCommand(packagePath, args) {
   const semantic = readDesignView(product, {
     foundation,
     libraries,
-    locale: option(args, "--locale") ?? "zh-TW",
+    locale: option(args, "--locale") ?? defaultLocale(),
     selector: { ...selector, viewFormat: "semantic" },
   });
   const wireframe = readDesignView(product, {
     foundation,
     libraries,
-    locale: option(args, "--locale") ?? "zh-TW",
+    locale: option(args, "--locale") ?? defaultLocale(),
     selector: { ...selector, viewFormat: "wireframe" },
   });
   const context = semantic.selection.context;
@@ -971,7 +1318,7 @@ async function inspectViewCommand(packagePath, args) {
     wireframe: wireframe.result,
   };
   if (flag(args, "--include-image")) {
-    const bundle = await createEvidence(product, {
+    const bundle = await renderEvidence(product, {
       foundation,
       libraries,
       scale: numberOption(args, "--scale", 1),
@@ -996,7 +1343,7 @@ async function renderMatrixCommand(packagePath, args) {
     );
   }
   const contexts = parseJson(
-    await readFile(contextsPath, "utf8"),
+    await readInputFile(contextsPath, "--contexts", "utf8"),
     "invalid_render_contexts_json",
     { path: contextsPath },
   );
@@ -1025,7 +1372,7 @@ async function renderMatrixCommand(packagePath, args) {
         },
       );
     }
-    const bundle = await createEvidence(product, {
+    const bundle = await renderEvidence(product, {
       foundation,
       libraries,
       scale,
@@ -1096,7 +1443,7 @@ function tokenImpact(snapshot, tokenId, packageId) {
     }
   }
   return locations.sort((left, right) =>
-    JSON.stringify(left).localeCompare(JSON.stringify(right)),
+    compareText(JSON.stringify(left), JSON.stringify(right)),
   );
 }
 
@@ -1130,7 +1477,7 @@ function componentDetails(snapshot, componentId) {
           scenario.target.component.assetId === componentId,
       )
       .map(({ id, name, target }) => ({ id, name, target }))
-      .sort((left, right) => left.id.localeCompare(right.id)),
+      .sort((left, right) => compareText(left.id, right.id)),
   };
 }
 
@@ -1240,7 +1587,7 @@ async function repairOperations(resolution, conflict, action, args) {
       );
     }
     const asset = parseJson(
-      await readFile(assetPath, "utf8"),
+      await readInputFile(assetPath, "--asset", "utf8"),
       "invalid_recreated_asset_json",
       { path: assetPath },
     );
@@ -1315,7 +1662,11 @@ function insertionAdvice(owner, product, component) {
   const instanceNode = {
     children: [],
     height: dimensions.height,
-    id: `node_instance_${randomUUID().slice(0, 8)}`,
+    // Derived from the revision so a repeated read returns the same advice.
+    id: `node_instance_${createHash("sha256")
+      .update(`${product.revision}\0${component.packageId}\0${component.id}`)
+      .digest("hex")
+      .slice(0, 8)}`,
     instance: {
       component: { assetId: component.id, packageId: component.packageId },
       variant,
@@ -1532,6 +1883,25 @@ async function main(args) {
     else process.stdout.write(`${version}\n`);
     return;
   }
+  if (command === "schema") {
+    if (flag(args, "--help") || flag(args, "-h")) {
+      printHelp("schema");
+      return;
+    }
+    const positional = args.slice(1).filter((value) => !value.startsWith("-"));
+    validateCommandArguments("schema", ["schema", "", ...args.slice(1).filter(
+      (value) => value.startsWith("-"),
+    )]);
+    if (positional.length > 2) {
+      throw new SmallPenError(
+        "unexpected_argument",
+        `Unexpected positional argument: ${positional[2]}`,
+        { argument: positional[2], command },
+      );
+    }
+    printJson(schemaTopic(positional[0], positional[1]));
+    return;
+  }
   if (!COMMAND_NAMES.includes(command)) {
     throw new SmallPenError("unknown_command", `Unknown command: ${command}`, {
       validCommands: COMMAND_NAMES,
@@ -1566,7 +1936,7 @@ async function main(args) {
         "import-draft requires --input FILE",
       );
     }
-    const input = await readFile(inputPath);
+    const input = await readInputFile(inputPath, "--input");
     printJson(
       await importDraft({
         ...(kind === "figma"
@@ -1588,7 +1958,7 @@ async function main(args) {
       );
     }
     const document = parseJson(
-      await readFile(inputPath, "utf8"),
+      await readInputFile(inputPath, "--input", "utf8"),
       "invalid_import_json",
       { path: inputPath },
     );
@@ -1643,7 +2013,7 @@ async function main(args) {
       );
     }
     const selections = parseJson(
-      await readFile(selectionsPath, "utf8"),
+      await readInputFile(selectionsPath, "--selections", "utf8"),
       "invalid_draft_selections_json",
       { path: selectionsPath },
     );
@@ -1695,7 +2065,7 @@ async function main(args) {
     const offset = integerOption(args, "--offset", 0);
     const limit = integerOption(args, "--limit", 100, 100);
     const all = listDomain(snapshot, kind).sort((left, right) =>
-      String(left.item.id ?? "").localeCompare(String(right.item.id ?? "")),
+      compareText(String(left.item.id ?? ""), String(right.item.id ?? "")),
     );
     printJson({
       items: all.slice(offset, offset + limit),
@@ -1717,7 +2087,7 @@ async function main(args) {
     printJson({
       context,
       items: listEffectiveTokens(product, { context, foundation, libraries }),
-      labels: { context: "設計狀態", items: "有效設計變數" },
+      labels: tokenLabels(option(args, "--locale") ?? defaultLocale()),
       packageId: product.manifest.packageId,
       ...workspaceRevisions(product, foundation, libraries),
     });
@@ -1789,14 +2159,14 @@ async function main(args) {
       foundation,
       libraries,
       limit: integerOption(args, "--limit", 20, 100),
-      locale: option(args, "--locale") ?? "zh-TW",
+      locale: option(args, "--locale") ?? defaultLocale(),
       offset: integerOption(args, "--offset", 0),
       selector: designSelector(args),
     });
     if (command === "discover") {
       printJson(read.discovery);
     } else if (read.format === "screenshot") {
-      const bundle = await createEvidence(product, {
+      const bundle = await renderEvidence(product, {
         foundation,
         libraries,
         scale: 1,
@@ -2013,10 +2383,17 @@ async function main(args) {
       );
     }
     const batch = parseJson(
-      await readFile(batchPath, "utf8"),
+      await readInputFile(batchPath, "--batch", "utf8"),
       "invalid_batch_json",
       { path: batchPath },
     );
+    if (!isRecord(batch)) {
+      throw new SmallPenError(
+        "invalid_batch",
+        "Operation Batch must be a JSON object",
+        { path: batchPath },
+      );
+    }
     await checkExternalComponentConsumers(packagePath, batch.operations ?? []);
     printJson(await applyBatch(packagePath, batch, args));
     return;
@@ -2030,7 +2407,7 @@ async function main(args) {
       );
     }
     const intent = parseJson(
-      await readFile(intentPath, "utf8"),
+      await readInputFile(intentPath, "--intent", "utf8"),
       "invalid_flow_intent_json",
       { path: intentPath },
     );
@@ -2073,14 +2450,43 @@ async function main(args) {
     const parentId = intent.parentId === undefined
       ? presentation.rootId
       : intent.parentId;
-    const operations = intent.nodes.map((node, index) => ({
-      index: intent.index === undefined ? undefined : intent.index + index,
-      node,
-      parentId,
-      presentationId,
-      screenId: intent.screenId,
-      type: "add-presentation-node",
-    }));
+    // overrides on an INSTANCE intent node compile to set-instance-override
+    // operations after the node is added, in the same atomic batch, so batch
+    // preparation checks each override path and value against the component.
+    const overrideOperations = [];
+    const operations = intent.nodes.map((intentNode, index) => {
+      let node = intentNode;
+      if (isRecord(intentNode) && Object.hasOwn(intentNode, "overrides")) {
+        const { overrides, ...rest } = intentNode;
+        if (intentNode.type !== "INSTANCE" || !isRecord(overrides)) {
+          throw new SmallPenError(
+            "invalid_flow_intent",
+            'overrides is only allowed on INSTANCE intent nodes, as {"<sourceNodeId>:<field>": value}',
+            { nodeId: intentNode.id, nodeIndex: index },
+          );
+        }
+        node = rest;
+        for (const [overridePath, value] of Object.entries(overrides)) {
+          overrideOperations.push({
+            nodeId: intentNode.id,
+            overridePath,
+            presentationId,
+            screenId: intent.screenId,
+            type: "set-instance-override",
+            value,
+          });
+        }
+      }
+      return {
+        index: intent.index === undefined ? undefined : intent.index + index,
+        node,
+        parentId,
+        presentationId,
+        screenId: intent.screenId,
+        type: "add-presentation-node",
+      };
+    });
+    operations.push(...overrideOperations);
     printJson(
       await applyBatch(packagePath, {
         baseRevision: snapshot.revision,
@@ -2099,7 +2505,7 @@ async function main(args) {
       );
     }
     const intent = parseJson(
-      await readFile(intentPath, "utf8"),
+      await readInputFile(intentPath, "--intent", "utf8"),
       "invalid_token_intent_json",
       { path: intentPath },
     );
@@ -2120,14 +2526,14 @@ async function main(args) {
     return;
   }
   if (command === "import-media") {
-    const mediaPath = option(args, "--file") ?? args[1];
+    const mediaPath = option(args, "--file");
     if (!mediaPath) {
       throw new SmallPenError(
         "missing_media_file",
         "import-media requires --file MEDIA_FILE",
       );
     }
-    const bytes = new Uint8Array(await readFile(resolve(mediaPath)));
+    const bytes = new Uint8Array(await readInputFile(mediaPath, "--file"));
     const inspected = inspectMedia(bytes);
     const mediaId = option(args, "--media-id") ?? `media_${randomUUID()}`;
     const name = option(args, "--name") ?? mediaPath.split(/[\\/]/).pop();
@@ -2141,7 +2547,9 @@ async function main(args) {
       width: inspected.width,
     });
     printJson({
+      batchId: print.result.batchId,
       descriptor: print.descriptor,
+      inverseBatch: print.result.inverseBatch,
       revision: print.result.revision,
     });
     return;
@@ -2155,11 +2563,17 @@ async function main(args) {
       );
     }
     const result = await removeMedia(packagePath, mediaId);
-    printJson({ mediaId, removed: true, revision: result.revision });
+    printJson({
+      batchId: result.batchId,
+      inverseBatch: result.inverseBatch,
+      mediaId,
+      removed: true,
+      revision: result.revision,
+    });
     return;
   }
   if (command === "import-font") {
-    const fontPath = option(args, "--file") ?? args[1];
+    const fontPath = option(args, "--file");
     if (!fontPath) {
       throw new SmallPenError(
         "missing_font_file",
@@ -2173,7 +2587,7 @@ async function main(args) {
         "import-font requires --family NAME",
       );
     }
-    const bytes = new Uint8Array(await readFile(resolve(fontPath)));
+    const bytes = new Uint8Array(await readInputFile(fontPath, "--file"));
     const signatureTtf = bytes[0] === 0x00 && bytes[1] === 0x01;
     const signatureOtf = bytes[0] === 0x4f && bytes[1] === 0x54;
     const signatureWoff = bytes[0] === 0x77 && bytes[1] === 0x4f && bytes[2] === 0x46 && bytes[3] === 0x46;
@@ -2216,13 +2630,15 @@ async function main(args) {
       files,
       fontId,
       id: variantId,
-      name: option(args, "--name") ?? `${style}-${weight}`,
+      name: option(args, "--name") ?? fontVariantName(weight, style),
       style,
       weight,
     });
     printJson({
-      fontId,
+      batchId: result.batchId,
       files: variant.files,
+      fontId,
+      inverseBatch: result.inverseBatch,
       revision: result.revision,
       variantId: variant.id,
     });
@@ -2271,6 +2687,8 @@ async function main(args) {
         cache: refreshed.remote.cache,
         packageId: refreshed.manifest.packageId,
         revision: refreshed.revision,
+        // A failed fetch with a verified cache reports "stale": keep the reason.
+        warning: refreshed.remote.warning,
       },
       before: before
         ? { packageId: before.manifest.packageId, revision: before.revision }
@@ -2282,20 +2700,34 @@ async function main(args) {
     return;
   }
   if (command === "watch") {
-    const interval = Math.max(100, Number(option(args, "--interval") ?? 500));
+    // Validate before clamping: Number("abc") is NaN and would poll nonstop.
+    const interval = Math.max(
+      100,
+      integerOption(args, "--interval", 500, 3_600_000),
+    );
     // Default is unlimited: watch without --max-events must keep observing
     // (SP-041-A caught a fallback of 1 that exited after the first event).
     const maxEvents = integerOption(args, "--max-events", Number.POSITIVE_INFINITY, 10_000);
+    if (maxEvents === 0) {
+      throw new SmallPenError(
+        "invalid_integer_option",
+        "--max-events requires an integer from 1 through 10000",
+        { maximum: 10_000, name: "--max-events", value: "0" },
+      );
+    }
     const emit = (payload) =>
       process.stdout.write(`${JSON.stringify(payload)}\n`);
+    // The last emitted state: an unchanged invalid state is not repeated
+    // every poll, and recovery reports the revision again even when it is
+    // the one before the Package became invalid.
     let previous;
     let events = 0;
     process.on("SIGINT", () => process.exit(0));
     for (;;) {
       try {
         const snapshot = await openPackage(packagePath);
-        if (snapshot.revision !== previous) {
-          previous = snapshot.revision;
+        if (`revision:${snapshot.revision}` !== previous) {
+          previous = `revision:${snapshot.revision}`;
           events += 1;
           emit({
             event: "revision",
@@ -2305,13 +2737,17 @@ async function main(args) {
           if (maxEvents !== undefined && events >= maxEvents) return;
         }
       } catch (error) {
-        events += 1;
-        emit({
+        const invalid = {
           code: error instanceof SmallPenError ? error.code : "internal_error",
           event: "invalid",
           message: error instanceof Error ? error.message : String(error),
-        });
-        if (maxEvents !== undefined && events >= maxEvents) return;
+        };
+        if (`invalid:${invalid.code}:${invalid.message}` !== previous) {
+          previous = `invalid:${invalid.code}:${invalid.message}`;
+          events += 1;
+          emit(invalid);
+          if (maxEvents !== undefined && events >= maxEvents) return;
+        }
       }
       await delay(interval);
     }
@@ -2386,7 +2822,7 @@ function errorDetails(error, args) {
     }
     if (!replaced) retry.push("--answer", `${details.questionId}=<JSON>`);
     if (!retry.includes("--json")) retry.push("--json");
-    if (!retry.includes("--locale")) retry.push("--locale", "zh-TW");
+    if (!retry.includes("--locale")) retry.push("--locale", defaultLocale());
     return {
       ...details,
       nextOperations: [{ argv: retry, operation: "smallpen.init.answer" }],