@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/commands/test.js

@@ -9,12 +9,13 @@ import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
 import { assertMarionettePortAvailable, ensureLaunchableBrowserNotRunning, ensureMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
 import { ensureMochitestServerPortAvailable } from '../core/mochitest-server-port.js';
-import { closeActiveRunLog, openRunLog, setActiveRunLog } from '../core/run-log.js';
+import { closeActiveRunLog, openRunLog, setActiveRunLog, writeToActiveRunLog, } from '../core/run-log.js';
 import { createPostRebuildFailureContext } from '../core/test-harness-output.js';
 import { analyzeTestPathScopes, formatScopeNotice, } from '../core/test-path-scope.js';
 import { assertObjdirMatchesTreeMarker } from '../core/tree-store.js';
-import { GeneralError } from '../errors/base.js';
+import { FireForgeError, GeneralError, PreflightRefusalError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, notice, outro, verbose } from '../utils/logger.js';
 import { stripEnginePrefix } from '../utils/paths.js';
@@ -41,7 +42,7 @@ async function assertTestPathsExist(engineDir, testPaths) {
  * auto-routes to the suite-specific command (`mach xpcshell-test` /
  * `mach mochitest`), which degrades a broken host resource monitor to a
  * warning instead of crashing generic `mach test` at startup. Mixed runs are
- * rejected before this point; a path-less "run all" or an explicit
+ * rejected before this point. A path-less "run all" or an explicit
  * `--generic-mach-test` opt-out stays on the generic command.
  */
 function resolveTestSuite(classification, forceGeneric) {
@@ -101,14 +102,14 @@ function logTestSelection(scopes) {
 }
 /**
  * Runs the `--doctor` marionette handshake probe. With no test paths the
- * probe is the entire command (returns `'stop'` after reporting); with
- * paths it gates the mach invocation — a FAIL throws before mach runs.
+ * probe is the entire command (returns `'stop'` after reporting). With
+ * paths it gates the mach invocation, where a FAIL throws before mach runs.
  */
 async function runDoctorPreflight(args) {
     const { engineDir, effectivePort, hasTestPaths, objDir, binaryName, launchablePath } = args;
     // Non-TTY captures need the banner even if clack's renderer defers output
-    // in pipe mode; TTY users need the clack framing. Gated rather than
-    // written twice — the unconditional pair printed the same line twice on a
+    // in pipe mode. TTY users need the clack framing. Gated rather than
+    // written twice: the unconditional pair printed the same line twice on a
     // terminal.
     if (process.stdout.isTTY) {
         info('Running marionette preflight...');
@@ -124,7 +125,7 @@ async function runDoctorPreflight(args) {
     // can drop the summary under non-TTY capture.
     //
     // Gated on non-TTY: unconditional, it stacks with the two clack renderings
-    // below and the same line appears THREE times on a terminal. Captured
+    // below and the same line appears three times on a terminal. Captured
     // streams are exactly where this branch still fires.
     const directLine = formatMarionettePreflightLine(preflight);
     if (!process.stdout.isTTY) {
@@ -138,7 +139,7 @@ async function runDoctorPreflight(args) {
             throw new GeneralError('Marionette preflight reported FAIL — see output above.');
         }
         // Doctor-only runs end here, so they carry their own verdict line
-        // (reason=preflight on failure); with test paths the verdict comes
+        // (reason=preflight on failure). With test paths the verdict comes
         // from the actual harness run downstream.
         emitPassVerdict();
         outro('Test completed');
@@ -160,12 +161,12 @@ async function runDoctorPreflight(args) {
 function appendMarionetteForwardingArgs(extraArgs, options, forwardedPort, xpcshellOnly = false) {
     // Auto-forward the Marionette port to mach when `--marionette-port` is set.
     // `--setpref=marionette.port=<n>` configures where the browser listener
-    // binds; `--marionette=127.0.0.1:<n>` tells the mochitest harness client to
+    // binds. `--marionette=127.0.0.1:<n>` tells the mochitest harness client to
     // connect there (default client is 127.0.0.1:2828). xpcshell ignores both
     // for browser Marionette.
     //
     // Skip setpref forwarding when the operator already supplied an equivalent
-    // arg via `--mach-arg` — duplicates would confuse without changing
+    // arg via `--mach-arg`: duplicates would confuse without changing
     // semantics. Skip when mach args explicitly request `--flavor=xpcshell` (or
     // `xpcshell-tests`): the preflight still honours `--marionette-port`, but
     // mach does not use the marionette.port pref on that harness. Any other arg
@@ -177,7 +178,7 @@ function appendMarionetteForwardingArgs(extraArgs, options, forwardedPort, xpcsh
     if (options.marionettePort === undefined)
         return;
     if (xpcshellOnly) {
-        // Manifest classification says every requested path is xpcshell —
+        // Manifest classification says every requested path is xpcshell.
         // xpcshell ignores the browser Marionette path entirely, and forwarding
         // the mochitest client flags here makes mach reject the dispatch.
         info(`--marionette-port=${options.marionettePort} applied to the preflight probe only: the requested paths are xpcshell-only, and xpcshell ignores the browser Marionette port. Not forwarding --setpref=marionette.port or --marionette to mach.`);
@@ -271,9 +272,9 @@ const TEST_BUILD_PREFLIGHT = {
  *
  * Owns the run's exactly-one-`FIREFORGE-VERDICT:`-line guarantee: the sink
  * is re-armed at entry, and any failure that reaches this boundary without
- * an inner writer having emitted — the preflight ladder (missing engine or
- * build, config errors, stale-build and port gates, missing paths), and a
- * harness process that failed to start — emits `FAIL reason=preflight`,
+ * an inner writer having emitted (the preflight ladder: missing engine or
+ * build, config errors, stale-build and port gates, missing paths, and a
+ * harness process that failed to start) emits `FAIL reason=preflight`,
  * since no harness classification exists for such a run. Writers closer to
  * the harness (doctor, canary, single, sharded, the engine-generation
  * guard) emit first and win.
@@ -284,7 +285,7 @@ const TEST_BUILD_PREFLIGHT = {
 export async function testCommand(projectRoot, testPaths, options = {}) {
     intro('FireForge Test');
     resetVerdictEmission();
-    // Opened before ANY work so a preflight refusal is logged too — those are
+    // Opened before any work so a preflight refusal is logged too. Those are
     // exactly the runs whose only output a `tail` throws away. Closed in
     // `finally`, after the verdict line has already read the path.
     setActiveRunLog(await openRunLog(projectRoot, 'test'));
@@ -292,19 +293,55 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         await runTestCommandBody(projectRoot, testPaths, options);
     }
     catch (error) {
-        if (!verdictEmitted())
-            emitFailVerdict('preflight');
+        if (!verdictEmitted()) {
+            renderPreflightRefusal(error);
+            emitFailVerdict('preflight', refusalNote(error));
+        }
         throw error;
     }
     finally {
         await closeActiveRunLog();
     }
 }
+/** The refusal class a preflight gate named, when it named one. */
+function refusalNote(error) {
+    return error instanceof PreflightRefusalError ? error.note : undefined;
+}
+/**
+ * Puts a preflight refusal's own text on the operator's channel before the
+ * verdict line, and into the run log.
+ *
+ * Both halves matter, and neither happened before:
+ *
+ *  - `withErrorHandling` renders `error.userMessage` back in `cli.ts`, but
+ *    by then `emitFailVerdict` has called `setStdoutSealed(true)`, the seal
+ *    that keeps the verdict the last stdout write, so `logError` routes to
+ *    stderr. A run captured with `> file` therefore kept the verdict and
+ *    dropped the reason.
+ *  - That same rendering happens after this function's caller returns, and
+ *    the `finally` below has already closed the run log. So the artifact the
+ *    verdict's own `log=` key points at did not contain the refusal either,
+ *    which is what left `.fireforge/logs/test-*.log` holding only the
+ *    pre-test build.
+ *
+ * Writing here, before the seal, fixes both without trading away the
+ * contract: the refusal lands on stdout and in the log, and the verdict
+ * line still comes last.
+ */
+function renderPreflightRefusal(error) {
+    const text = error instanceof FireForgeError ? error.userMessage : toError(error).message;
+    const block = `Preflight refused:\n${text}\n`;
+    // Raw stdout rather than the clack logger: this must land on the captured
+    // stream verbatim, and clack's renderer can drop output under non-TTY
+    // capture, the same reason the verdict line is written this way.
+    process.stdout.write(block);
+    writeToActiveRunLog(block);
+}
 /**
  * Verifies `engine/` did not change under the run before any PASS verdict
- * may print. On failure the run's verdict is `FAIL reason=inconclusive` —
- * the harness result exists but cannot be trusted (`preflight` would
- * misdescribe a run whose harness already executed) — emitted here so the
+ * may print. On failure the run's verdict is `FAIL reason=inconclusive`,
+ * because the harness result exists but cannot be trusted (`preflight` would
+ * misdescribe a run whose harness already executed). It is emitted here so the
  * guard's throw can never leave a stale or missing verdict line behind.
  */
 async function verifyEngineGenerationOrEmitInconclusive(engineDir, before) {
@@ -324,7 +361,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     const buildCheck = await hasBuildArtifacts(paths.engine);
     assertBuildArtifacts(paths.engine, buildCheck, TEST_BUILD_PREFLIGHT);
     // Inside a verification tree, only the objdir the marker records was
-    // proven rewritten-and-reconfigured to the tree; refuse any other.
+    // proven rewritten-and-reconfigured to the tree. Refuse any other.
     await assertObjdirMatchesTreeMarker(projectRoot, buildCheck.objDir);
     // Load the project config once so both the build and the port
     // probe have access to `binaryName` (the port probe uses it to
@@ -332,11 +369,11 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     const projectConfig = await loadConfig(projectRoot);
     const canaryPath = resolveCanaryPath(options, projectConfig);
     assertTestModeCombinations(testPaths, options, canaryPath);
-    // `hasBuildArtifacts` only confirms `obj-*/dist/` exists; a partial build
+    // `hasBuildArtifacts` only confirms `obj-*/dist/` exists. A partial build
     // (linker failed, packaging step interrupted) can satisfy that check
     // without ever writing the launchable binary the marionette preflight
     // needs to spawn. `fireforge run` already uses `hasRunnableBundle` to fail
-    // fast with a precise message; mirroring it here makes `test --doctor`
+    // fast with a precise message. Mirroring it here makes `test --doctor`
     // against an incomplete build surface the missing-bundle path instead of a
     // cryptic `Browser process exited during spawn (exit code 1, signal none).
     // stderr tail: (empty)`.
@@ -345,8 +382,8 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     // Normalized engine-relative request paths, hoisted above the build/stale
     // gate: the pre-test build records them as the packaging-coverage claim,
     // and the --allow-stale-build path checks the request against the
-    // recorded coverage. (Existence is still asserted later, after the gate —
-    // stale/coverage refusals keep precedence over missing-path errors.)
+    // recorded coverage. (Existence is still asserted later, after the gate,
+    // so stale/coverage refusals keep precedence over missing-path errors.)
     const requestedPaths = canaryPath !== undefined ? [canaryPath] : testPaths;
     const normalizedPaths = requestedPaths.map((p) => stripEnginePrefix(p).trim());
     const { classification, xpcshellOnly } = await classifyBeforeDispatch(paths.engine, normalizedPaths, { allowMixed: options.buildOnly === true });
@@ -392,26 +429,26 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
         extraArgs.push('--auto');
     }
     if (canaryPath !== undefined) {
-        extraArgs.push(`--timeout=${String(canaryTimeoutSeconds(projectConfig))}`);
+        extraArgs.push(`--timeout=${canaryTimeoutSeconds(projectConfig)}`);
     }
     // --mach-arg is a verbatim passthrough for upstream mach/xpcshell/mochitest
     // flags FireForge does not model directly (see the xpcshell appdir hint
-    // above for why). Appended AFTER --headless so mach sees
+    // above for why). Appended after --headless so mach sees
     // the FireForge-managed flags first and the escape-valve ones last, which
     // keeps the override precedence predictable.
     if (forwardedMachArgs.length > 0) {
         extraArgs.push(...forwardedMachArgs);
     }
     appendMarionetteForwardingArgs(extraArgs, options, forwardedPort, xpcshellOnly);
-    // Directory arguments mean EXACTLY that directory: mozbuild's test
+    // Directory arguments mean exactly that directory: mozbuild's test
     // resolver matches paths by string prefix, so a bare directory arg
-    // silently sweeps in prefix-named siblings — `…/test/hominis` also running
-    // `…/test/hominis-tiles`, with no indication the scope widened. Each
+    // silently sweeps in prefix-named siblings, with `…/test/hominis` also
+    // running `…/test/hominis-tiles`, with no indication the scope widened. Each
     // directory argument therefore dispatches as its enumerated explicit
-    // test-file list, which cannot prefix-match a sibling; a trailing-`/`
+    // test-file list, which cannot prefix-match a sibling. A trailing-`/`
     // normalization does not work, as mach still sweeps the sibling in. Any
     // prefix-siblings are echoed so the narrowed scope is visible.
-    // Classification above intentionally used the raw argument forms; only the
+    // Classification above intentionally used the raw argument forms. Only the
     // mach dispatch needs the exact-match shape.
     const scopes = await analyzeTestPathScopes(paths.engine, normalizedPaths);
     const dispatchGroups = scopes.map((scope) => ({
@@ -445,10 +482,10 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
         : undefined;
     // Multi-argument requests shard into sequential harness runs by default:
     // one shared mochitest profile across files bleeds pref/media-query state
-    // into later files. Sharding is per path ARGUMENT — a directory argument
+    // into later files. Sharding is per path argument: a directory argument
     // keeps its enumerated files together in one invocation, preserving the
     // one-browser-instance semantics of a directory run. `--no-shard` restores
-    // the combined invocation. The default must not be SILENT: a cross-file
+    // the combined invocation. The default must not be silent: a cross-file
     // pollution repro otherwise "passes" because the comparison run was
     // sharded without saying so, misattributing a suite-context bug upstream.
     // Hence the one-line notice stating what sharding does and does not
@@ -463,7 +500,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
             summary = await runShardedTests(runCtx, dispatchGroups, (outcome, label) => diagnoseShardOutcome(outcome, label, projectConfig.binaryName, postRebuildContext));
         }
         finally {
-            // Runs BEFORE the aggregate verdict below: a mutated engine/ emits
+            // Runs before the aggregate verdict below: a mutated engine/ emits
             // `FAIL reason=inconclusive` and throws, so an invalidated run can
             // never print `PASS shards=N/N` first. (A throw here masks an
             // in-flight shard error, as the plain assert always did.)

package/dist/src/commands/token-coverage.js

@@ -34,11 +34,11 @@ export async function tokenCoverageCommand(projectRoot) {
         .map((f) => f.file);
     // Also scan CSS files deployed by Furnace custom components. Deployed
     // files can be committed (and therefore absent from `git status`) while
-    // still being the primary surface where token adoption matters; looking
+    // still being the primary surface where token adoption matters. Looking
     // only at modified files silently undercounts projects where Furnace
     // writes many component-CSS files into the engine.
     const furnaceCssFiles = await collectFurnaceCustomCssFiles(projectRoot, paths.engine, tokensCssPath);
-    // De-dupe so a file that is both a custom deploy target AND modified is
+    // De-dupe so a file that is both a custom deploy target and modified is
     // scanned exactly once.
     const cssFiles = [...new Set([...statusCssFiles, ...furnaceCssFiles])];
     const tokenSourceFiles = [...new Set(statusTokenCssFiles)];
@@ -129,7 +129,7 @@ async function validateTokenSourceFiles(engineDir, tokenSourceFiles, tokenPrefix
 /**
  * Returns engine-relative `.css` paths deployed by every Furnace custom
  * component registered in `furnace.json`. Only files that actually exist
- * on disk are included — a component whose deploy target is missing (e.g.
+ * on disk are included. A component whose deploy target is missing (e.g.
  * `furnace apply` has not run yet) is skipped silently so a fresh
  * `furnace init` followed immediately by `token coverage` does not error.
  *

package/dist/src/commands/token-list.d.ts

@@ -0,0 +1,26 @@
+/** Options accepted by {@link tokenListCommand}. */
+export interface TokenListOptions {
+    /** Restrict the report to one category. */
+    category?: string;
+    /** Emit the machine-readable envelope instead of the human report. */
+    json?: boolean;
+}
+/**
+ * Lists the categories declared in the tokens CSS with their token names,
+ * in file order.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param options - Filter and output-mode options
+ */
+export declare function tokenListCommand(projectRoot: string, options?: TokenListOptions): Promise<void>;
+/**
+ * Reports one token: the category that owns it and the value it takes in
+ * every block that declares it.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param tokenName - Custom-property name, with or without the leading `--`
+ * @param options - Output-mode options
+ */
+export declare function tokenShowCommand(projectRoot: string, tokenName: string, options?: {
+    json?: boolean;
+}): Promise<void>;

package/dist/src/commands/token-list.js

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `token list` and `token show`: the read half of design-token management.
+ *
+ * `token add` requires `--category` and refuses an unknown one, but nothing
+ * reported the categories a project has, so naming one meant hand-parsing a
+ * neighbouring `= Category =` banner out of the tokens CSS. Both commands
+ * read through `token-inventory.ts`, which is built on the same banner and
+ * `:root`-bounds primitives `token add` and `token coverage` use, because
+ * a second tokens-CSS parser would let the report and the writer disagree about
+ * which section a token lives in.
+ *
+ * Helper module: no registrar, called from `token.ts`.
+ */
+import { join } from 'node:path';
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { collectTokenBlockValues, collectTokenInventory, } from '../core/token-inventory.js';
+import { getTokensCssPath } from '../core/token-manager.js';
+import { GeneralError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { pathExists, readText } from '../utils/fs.js';
+import { info, intro, outro, setMachineOutputMode, setStdoutSealed } from '../utils/logger.js';
+import { emitMachineError, MACHINE_OUTPUT_SCHEMA_VERSION } from '../utils/machine-output.js';
+/** Reads the project's tokens CSS as lines, refusing when it is absent. */
+async function readTokensCssLines(projectRoot) {
+    const paths = getProjectPaths(projectRoot);
+    const config = await loadConfig(projectRoot);
+    const tokensCssPath = getTokensCssPath(config.binaryName);
+    const filePath = join(paths.engine, tokensCssPath);
+    if (!(await pathExists(filePath))) {
+        throw new GeneralError(`Token CSS file not found: ${tokensCssPath}. Run "fireforge furnace init" to seed it.`);
+    }
+    return { lines: (await readText(filePath)).split('\n'), tokensCssPath };
+}
+/** Applies the `--category` filter, refusing a name the file does not carry. */
+function filterByCategory(groups, category, tokensCssPath) {
+    const matched = groups.filter((group) => group.category === category);
+    if (matched.length > 0)
+        return matched;
+    // Same "name the alternatives" contract `token add` gives for an unknown
+    // category: a filter that silently prints nothing reads as "this
+    // category is empty", which is a different fact.
+    const available = groups
+        .map((group) => group.category)
+        .filter((name) => name !== null);
+    const suffix = available.length > 0
+        ? `Available categories: ${available.map((name) => `"${name}"`).join(', ')}.`
+        : 'The file declares no category banners.';
+    throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}.\n\n${suffix}`);
+}
+/**
+ * Lists the categories declared in the tokens CSS with their token names,
+ * in file order.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param options - Filter and output-mode options
+ */
+export async function tokenListCommand(projectRoot, options = {}) {
+    if (options.json === true) {
+        // stdout belongs exclusively to the payload from here on. A later
+        // diagnostic (including withErrorHandling's) routes to stderr.
+        setMachineOutputMode(true);
+        try {
+            const { lines, tokensCssPath } = await readTokensCssLines(projectRoot);
+            const all = collectTokenInventory(lines);
+            const groups = options.category === undefined
+                ? all
+                : filterByCategory(all, options.category, tokensCssPath);
+            process.stdout.write(`${JSON.stringify({
+                schemaVersion: MACHINE_OUTPUT_SCHEMA_VERSION,
+                tokensCssPath,
+                categories: groups.map((group) => ({
+                    category: group.category,
+                    tokens: group.tokens.map((token) => ({
+                        name: token.name,
+                        line: token.line,
+                        value: token.value,
+                    })),
+                })),
+            }, null, 2)}\n`);
+            setStdoutSealed(true);
+        }
+        catch (error) {
+            emitMachineError('token-list-failed', toError(error).message);
+        }
+        finally {
+            setMachineOutputMode(false);
+        }
+        return;
+    }
+    const { lines, tokensCssPath } = await readTokensCssLines(projectRoot);
+    const all = collectTokenInventory(lines);
+    const groups = options.category === undefined ? all : filterByCategory(all, options.category, tokensCssPath);
+    intro('Design Tokens');
+    info(tokensCssPath);
+    if (groups.length === 0) {
+        outro('No token declarations found in the :root block');
+        return;
+    }
+    let total = 0;
+    for (const group of groups) {
+        info(`  ${group.category ?? '(no category)'} — ${String(group.tokens.length)} token(s)`);
+        for (const token of group.tokens) {
+            info(`    ${token.name}`);
+        }
+        total += group.tokens.length;
+    }
+    outro(`${String(groups.length)} category/categories, ${String(total)} token(s)`);
+}
+/**
+ * Reports one token: the category that owns it and the value it takes in
+ * every block that declares it.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param tokenName - Custom-property name, with or without the leading `--`
+ * @param options - Output-mode options
+ */
+export async function tokenShowCommand(projectRoot, tokenName, options = {}) {
+    const emit = async () => {
+        const { lines, tokensCssPath } = await readTokensCssLines(projectRoot);
+        const name = tokenName.startsWith('--') ? tokenName : `--${tokenName}`;
+        const declarations = collectTokenBlockValues(lines, name);
+        if (declarations.length === 0) {
+            throw new GeneralError(`Token "${name}" is not declared in ${tokensCssPath}. ` +
+                'Run "fireforge token list" to see the declared tokens.');
+        }
+        const owning = collectTokenInventory(lines).find((group) => group.tokens.some((token) => token.name === name));
+        return { tokensCssPath, name, category: owning?.category ?? null, declarations };
+    };
+    if (options.json === true) {
+        setMachineOutputMode(true);
+        try {
+            const report = await emit();
+            process.stdout.write(`${JSON.stringify({ schemaVersion: MACHINE_OUTPUT_SCHEMA_VERSION, ...report }, null, 2)}\n`);
+            setStdoutSealed(true);
+        }
+        catch (error) {
+            emitMachineError('token-show-failed', toError(error).message);
+        }
+        finally {
+            setMachineOutputMode(false);
+        }
+        return;
+    }
+    const report = await emit();
+    intro('Design Token');
+    info(`${report.name} — category: ${report.category ?? '(no category)'}`);
+    info(report.tokensCssPath);
+    for (const declaration of report.declarations) {
+        info(`  ${declaration.block}: ${declaration.value}  (line ${String(declaration.line)})`);
+    }
+    outro(`${String(report.declarations.length)} declaration(s)`);
+}

package/dist/src/commands/token.js

@@ -10,6 +10,7 @@ import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { normalizeTokenName } from '../utils/validation.js';
 import { tokenCoverageCommand } from './token-coverage.js';
+import { tokenListCommand, tokenShowCommand } from './token-list.js';
 async function normalizeTokenNameForProject(projectRoot, rawTokenName) {
     if (rawTokenName.startsWith('--')) {
         return normalizeTokenName(rawTokenName);
@@ -20,7 +21,7 @@ async function normalizeTokenNameForProject(projectRoot, rawTokenName) {
             const strippedPrefix = furnaceConfig.tokenPrefix.replace(/^--/, '').replace(/-$/, '');
             const strippedName = rawTokenName.replace(/^--/, '');
             // A bare name that already starts with the configured prefix text is
-            // treated as fully qualified — blindly prepending would silently
+            // treated as fully qualified. Blindly prepending would silently
             // produce a double-prefixed token (e.g. "--hominis-hominis-shadow-low").
             if (strippedName === strippedPrefix || strippedName.startsWith(`${strippedPrefix}-`)) {
                 info(`Token name "${rawTokenName}" already starts with the configured prefix ` +
@@ -36,12 +37,12 @@ async function normalizeTokenNameForProject(projectRoot, rawTokenName) {
     return normalizeTokenName(rawTokenName);
 }
 /**
- * Reports a no-op add, naming WHERE the existing declaration lives.
+ * Reports a no-op add, naming where the existing declaration lives.
  *
- * A variant skip has no category to name — the declaration lives in a
- * `:root<selector>` block — so the location reads as that block. The
+ * A variant skip has no category to name, because the declaration lives in
+ * a `:root<selector>` block, so the location reads as that block. The
  * variant path used to report no location at all, so a re-run meant to
- * CHANGE a value exited 0 having silently changed nothing.
+ * change a value exited 0 having silently changed nothing.
  *
  * @param tokenName - Full token name including prefix
  * @param result - Result carrying the skip location, when known
@@ -52,7 +53,7 @@ function reportSkippedToken(tokenName, result, options) {
         ? `:root${options.variant}`
         : `category "${result.skippedExisting?.category ?? options.category ?? ''}"`;
     const where = result.skippedExisting
-        ? ` in ${scope} (line ${String(result.skippedExisting.line)}), unchanged`
+        ? ` in ${scope} (line ${result.skippedExisting.line}), unchanged`
         : '';
     info(`Token ${tokenName} already exists${where} (skipped)`);
 }
@@ -68,8 +69,8 @@ export async function tokenAddCommand(projectRoot, tokenName, value, options) {
     intro('Token Add');
     // A fresh project without furnace.json otherwise fails deep inside the
     // token-manager's `assertTokenCategoryExists` with "Token CSS file not
-    // found: browser/themes/shared/<binary>-tokens.css" — technically correct,
-    // but the operator's actual next step is to initialize Furnace, which
+    // found: browser/themes/shared/<binary>-tokens.css", which is technically
+    // correct, but the operator's actual next step is to initialize Furnace, which
     // scaffolds the tokens CSS file. Catching the uninitialized case here
     // gives the right guidance before the generic "file not found" error.
     if (!(await furnaceConfigExists(projectRoot))) {
@@ -170,9 +171,9 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
     // Commander's argument parsing.
     // Description ends with `(required)` because Commander's
     // `makeOptionMandatory` does not render a required marker in `--help`
-    // output — only `.requiredOption` does that, and switching to
+    // output. Only `.requiredOption` does that, and switching to
     // `.requiredOption` would lose the `.choices()` enforcement. The
-    // explicit suffix keeps the runtime validation AND surfaces required
+    // explicit suffix keeps the runtime validation and surfaces required
     // status in help alongside the other options that use `.requiredOption`.
     new Option('--mode <mode>', 'Dark mode behavior (required)')
         .choices(['auto', 'static', 'override'])
@@ -201,6 +202,21 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
             }),
         });
     }));
+    token
+        .command('list')
+        .description('List the design-token categories declared in the tokens CSS with their token names, in file order')
+        .option('--category <name>', 'Restrict the report to one category')
+        .option('--json', 'Emit the machine-readable envelope on stdout (see docs/machine-output.md)')
+        .action(withErrorHandling(async (options) => {
+        await tokenListCommand(getProjectRoot(), pickDefined({ category: options.category, json: options.json }));
+    }));
+    token
+        .command('show <token-name>')
+        .description('Show one token: its category, the value it takes in every declaring block, and where it is defined. The leading `--` is optional; with it, use the `--` separator first (e.g. `fireforge token show -- --my-token`).')
+        .option('--json', 'Emit the machine-readable envelope on stdout (see docs/machine-output.md)')
+        .action(withErrorHandling(async (tokenName, options) => {
+        await tokenShowCommand(getProjectRoot(), tokenName, pickDefined({ json: options.json }));
+    }));
     token
         .command('coverage')
         .description('Measure design token usage across modified CSS files')