@hominis/fireforge 0.9.0

package/dist/src/commands/status.js

@@ -0,0 +1,268 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { isBrandingManagedPath } from '../core/branding.js';
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { getStatusWithCodes, isGitRepository } from '../core/git.js';
+import { getUntrackedFilesInDir } from '../core/git-status.js';
+import { isFileRegistered, matchesRegistrablePattern } from '../core/manifest-rules.js';
+import { computePatchedContent } from '../core/patch-apply.js';
+import { loadPatchesManifest } from '../core/patch-manifest.js';
+import { GeneralError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { pathExists, readText } from '../utils/fs.js';
+import { info, intro, outro, verbose, warn } from '../utils/logger.js';
+/**
+ * Status code descriptions for git status.
+ */
+const STATUS_DESCRIPTIONS = {
+    M: 'modified',
+    A: 'added',
+    D: 'deleted',
+    R: 'renamed',
+    C: 'copied',
+    U: 'unmerged',
+    '?': 'untracked',
+    '!': 'ignored',
+};
+/**
+ * Gets a human-readable description for a git status code.
+ */
+function getStatusDescription(code) {
+    return STATUS_DESCRIPTIONS[code] ?? 'changed';
+}
+function getPrimaryStatusCode(status) {
+    if (status.includes('?'))
+        return '?';
+    if (status.includes('!'))
+        return '!';
+    for (const code of status) {
+        if (code !== ' ') {
+            return code;
+        }
+    }
+    return status;
+}
+function isNewFileStatus(status) {
+    const code = getPrimaryStatusCode(status);
+    return code === '?' || code === 'A';
+}
+function groupFilesByStatus(files) {
+    const grouped = new Map();
+    for (const { status, file } of files) {
+        const code = getPrimaryStatusCode(status);
+        const existing = grouped.get(code) ?? [];
+        existing.push(file);
+        grouped.set(code, existing);
+    }
+    return grouped;
+}
+function printStatusGroups(files) {
+    const grouped = groupFilesByStatus(files);
+    for (const [status, fileList] of grouped) {
+        const description = getStatusDescription(status);
+        warn(`${description}:`);
+        for (const file of fileList) {
+            info(`  ${file}`);
+        }
+    }
+}
+async function printUnregisteredWarnings(files, projectRoot, binaryName) {
+    const newFiles = files.filter((f) => isNewFileStatus(f.status));
+    if (newFiles.length === 0)
+        return;
+    const registrableFiles = newFiles.filter((f) => matchesRegistrablePattern(f.file, binaryName));
+    const registrationChecks = await Promise.all(registrableFiles.map(async (f) => ({
+        file: f.file,
+        registered: await isFileRegistered(projectRoot, f.file),
+    })));
+    const unregistered = registrationChecks.filter((f) => !f.registered);
+    if (unregistered.length > 0) {
+        info('');
+        warn('Potentially unregistered files:');
+        for (const f of unregistered) {
+            info(`  ${f.file} — run 'fireforge register ${f.file}'`);
+        }
+    }
+}
+/**
+ * Renders raw worktree status as machine-parseable porcelain-style output.
+ * Each line is: STATUS<tab>FILE
+ */
+function renderRawStatus(files) {
+    for (const { status, file } of files) {
+        process.stdout.write(`${status.trim()}\t${file}\n`);
+    }
+}
+/**
+ * Expands collapsed untracked directory entries into individual file entries.
+ * Git status may report an entire untracked directory as a single entry (e.g. "?? dir/").
+ * This function expands those into individual file entries so each file can be classified.
+ */
+async function expandDirectoryEntries(files, engineDir) {
+    const expanded = [];
+    for (const entry of files) {
+        if (entry.file.endsWith('/') && entry.status.includes('?')) {
+            const individualFiles = await getUntrackedFilesInDir(engineDir, entry.file);
+            for (const f of individualFiles) {
+                expanded.push({ status: '??', file: f });
+            }
+        }
+        else {
+            expanded.push(entry);
+        }
+    }
+    return expanded;
+}
+/**
+ * Classifies files into patch-backed, unmanaged, or branding buckets.
+ */
+async function classifyFiles(files, engineDir, patchesDir, binaryName) {
+    const manifest = await loadPatchesManifest(patchesDir);
+    // Build set of all patch-claimed file paths
+    const patchClaimedFiles = new Set();
+    if (manifest) {
+        for (const patch of manifest.patches) {
+            for (const f of patch.filesAffected) {
+                patchClaimedFiles.add(f);
+            }
+        }
+    }
+    const results = [];
+    for (const entry of files) {
+        // Branding check first
+        if (isBrandingManagedPath(entry.file, binaryName)) {
+            results.push({ ...entry, classification: 'branding' });
+            continue;
+        }
+        // Not in any patch → unmanaged
+        if (!patchClaimedFiles.has(entry.file)) {
+            results.push({ ...entry, classification: 'unmanaged' });
+            continue;
+        }
+        // File is claimed by a patch — compare content
+        const primaryCode = getPrimaryStatusCode(entry.status);
+        if (primaryCode === 'D') {
+            // Deleted file: patch-backed only if patch expects deletion
+            const expected = await computePatchedContent(patchesDir, engineDir, entry.file);
+            results.push({
+                ...entry,
+                classification: expected === null ? 'patch-backed' : 'unmanaged',
+            });
+            continue;
+        }
+        // File exists on disk — compare actual vs expected
+        try {
+            const [expected, actual] = await Promise.all([
+                computePatchedContent(patchesDir, engineDir, entry.file),
+                readText(join(engineDir, entry.file)),
+            ]);
+            results.push({
+                ...entry,
+                classification: actual === expected ? 'patch-backed' : 'unmanaged',
+            });
+        }
+        catch (error) {
+            verbose(`Treating ${entry.file} as unmanaged because patch-backed classification failed: ${toError(error).message}`);
+            // If we can't read the file, treat as unmanaged
+            results.push({ ...entry, classification: 'unmanaged' });
+        }
+    }
+    return results;
+}
+/**
+ * Runs the status command to show modified files.
+ * @param projectRoot - Root directory of the project
+ * @param options - Status display options
+ */
+export async function statusCommand(projectRoot, options = {}) {
+    if (options.raw && options.unmanaged) {
+        throw new GeneralError('Cannot use --raw and --unmanaged together.');
+    }
+    if (!options.raw) {
+        intro('FireForge Status');
+    }
+    const paths = getProjectPaths(projectRoot);
+    const config = await loadConfig(projectRoot);
+    // Check if engine exists
+    if (!(await pathExists(paths.engine))) {
+        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
+    }
+    // Check if it's a git repository
+    if (!(await isGitRepository(paths.engine))) {
+        throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
+    }
+    const rawFiles = await getStatusWithCodes(paths.engine);
+    const files = await expandDirectoryEntries(rawFiles, paths.engine);
+    if (files.length === 0) {
+        info('No modified files');
+        outro('Working tree clean');
+        return;
+    }
+    // Raw mode: existing behavior
+    if (options.raw) {
+        renderRawStatus(files);
+        return;
+    }
+    // Patch-aware classification
+    const classified = await classifyFiles(files, paths.engine, paths.patches, config.binaryName);
+    const unmanagedFiles = classified.filter((f) => f.classification === 'unmanaged');
+    const patchBackedFiles = classified.filter((f) => f.classification === 'patch-backed');
+    const brandingFiles = classified.filter((f) => f.classification === 'branding');
+    // --unmanaged mode: only show unmanaged
+    if (options.unmanaged) {
+        info(`${unmanagedFiles.length} unmanaged file${unmanagedFiles.length === 1 ? '' : 's'} (${files.length} total modified):\n`);
+        if (unmanagedFiles.length > 0) {
+            printStatusGroups(unmanagedFiles);
+            await printUnregisteredWarnings(unmanagedFiles, projectRoot, config.binaryName);
+        }
+        else {
+            info('No unmanaged changes');
+        }
+        outro(unmanagedFiles.length === 0
+            ? 'No unmanaged changes'
+            : `${unmanagedFiles.length} unmanaged change${unmanagedFiles.length === 1 ? '' : 's'}`);
+        return;
+    }
+    // Default mode: three-bucket display
+    info(`${files.length} modified file${files.length === 1 ? '' : 's'}:\n`);
+    if (unmanagedFiles.length > 0) {
+        warn('Unmanaged changes:');
+        printStatusGroups(unmanagedFiles);
+        await printUnregisteredWarnings(unmanagedFiles, projectRoot, config.binaryName);
+    }
+    if (patchBackedFiles.length > 0) {
+        if (unmanagedFiles.length > 0)
+            info('');
+        warn('Patch-backed materialized changes:');
+        printStatusGroups(patchBackedFiles);
+    }
+    if (brandingFiles.length > 0) {
+        if (unmanagedFiles.length > 0 || patchBackedFiles.length > 0)
+            info('');
+        warn('Tool-managed branding changes:');
+        printStatusGroups(brandingFiles);
+    }
+    if (unmanagedFiles.length === 0 && patchBackedFiles.length === 0 && brandingFiles.length === 0) {
+        info('No changes');
+    }
+    const parts = [];
+    if (unmanagedFiles.length > 0)
+        parts.push(`${unmanagedFiles.length} unmanaged`);
+    if (patchBackedFiles.length > 0)
+        parts.push(`${patchBackedFiles.length} patch-backed`);
+    if (brandingFiles.length > 0)
+        parts.push(`${brandingFiles.length} branding`);
+    outro(parts.join(', '));
+}
+/** Registers the status command on the CLI program. */
+export function registerStatus(program, { getProjectRoot, withErrorHandling }) {
+    program
+        .command('status')
+        .description('Show modified files in engine/')
+        .option('--raw', 'Show raw worktree status without patch classification')
+        .option('--unmanaged', 'Show only unmanaged changes (not covered by patches or tools)')
+        .action(withErrorHandling(async (options) => {
+        await statusCommand(getProjectRoot(), options);
+    }));
+}
+//# sourceMappingURL=status.js.map

package/dist/src/commands/test.d.ts

@@ -0,0 +1,12 @@
+import { Command } from 'commander';
+import type { CommandContext } from '../types/cli.js';
+import type { TestOptions } from '../types/commands/index.js';
+/**
+ * Runs the test command to execute mach tests.
+ * @param projectRoot - Root directory of the project
+ * @param testPaths - Test file or directory paths
+ * @param options - Test options
+ */
+export declare function testCommand(projectRoot: string, testPaths: string[], options?: TestOptions): Promise<void>;
+/** Registers the test command on the CLI program. */
+export declare function registerTest(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/test.js

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { isBrandingSetup, setupBranding } from '../core/branding.js';
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { cleanStories } from '../core/furnace-stories.js';
+import { buildArtifactMismatchMessage, buildUI, generateMozconfig, hasBuildArtifacts, testWithOutput, } from '../core/mach.js';
+import { GeneralError } from '../errors/base.js';
+import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
+import { pathExists } from '../utils/fs.js';
+import { info, intro, spinner } from '../utils/logger.js';
+import { pickDefined } from '../utils/options.js';
+/**
+ * Strips the "engine/" prefix from a path if present.
+ * Users may specify paths like "engine/browser/modules/..." from the project
+ * root, but mach test expects paths relative to the engine directory.
+ * @param testPath - Path as provided by the user
+ * @returns Path relative to the engine directory
+ */
+function normalizeTestPath(testPath) {
+    if (testPath.startsWith('engine/')) {
+        return testPath.slice('engine/'.length);
+    }
+    if (testPath.startsWith('engine\\')) {
+        return testPath.slice('engine\\'.length);
+    }
+    return testPath;
+}
+async function assertTestPathsExist(engineDir, testPaths) {
+    const missingPaths = [];
+    for (const testPath of testPaths) {
+        if (!(await pathExists(join(engineDir, testPath)))) {
+            missingPaths.push(testPath);
+        }
+    }
+    if (missingPaths.length === 0) {
+        return;
+    }
+    throw new GeneralError(`Test path${missingPaths.length === 1 ? '' : 's'} not found under engine/: ${missingPaths.join(', ')}\n\n` +
+        'If you expected these files to come from your patch stack, run "fireforge import" first.');
+}
+function buildUnknownTestMessage(testPaths) {
+    return (`mach could not discover the requested test path${testPaths.length === 1 ? '' : 's'}: ${testPaths.join(', ')}\n\n` +
+        'The file may exist, but Firefox does not currently resolve it as a runnable test.\n\n' +
+        'Check the nearest test manifest (for example browser.toml or xpcshell.toml), confirm the file is listed under the correct test type, and make sure each parent moz.build registers that manifest before retrying.');
+}
+function buildStaleBuildMessage() {
+    return ('Firefox test runtime appears to be using stale build artifacts.\n\n' +
+        'The failing output referenced missing branding or distribution resources, which usually means the current obj-* build does not match recent engine or branding changes.\n\n' +
+        'Re-run "fireforge build --ui" or "fireforge test --build" and then retry.');
+}
+function hasStaleBuildArtifactsSignal(output) {
+    return (/chrome:\/\/branding\/locale\/brand\.properties/i.test(output) ||
+        /resource:\/\/\/modules\/distribution\.sys\.mjs/i.test(output) ||
+        /browser\/branding\/[^/\s]+\/moz\.build/i.test(output));
+}
+async function prepareIncrementalTestBuild(projectRoot) {
+    const config = await loadConfig(projectRoot);
+    const paths = getProjectPaths(projectRoot);
+    const brandingConfig = {
+        name: config.name,
+        vendor: config.vendor,
+        appId: config.appId,
+        binaryName: config.binaryName,
+    };
+    if (!(await isBrandingSetup(paths.engine, brandingConfig))) {
+        const brandingSpinner = spinner('Setting up branding...');
+        try {
+            await setupBranding(paths.engine, brandingConfig);
+            brandingSpinner.stop('Branding configured');
+        }
+        catch (error) {
+            brandingSpinner.error('Failed to set up branding');
+            throw error;
+        }
+    }
+    const mozconfigSpinner = spinner('Generating mozconfig...');
+    try {
+        await generateMozconfig(paths.configs, paths.engine, config);
+        mozconfigSpinner.stop('mozconfig generated');
+    }
+    catch (error) {
+        mozconfigSpinner.error('Failed to generate mozconfig');
+        throw error;
+    }
+    await cleanStories(paths.engine);
+    return { engineDir: paths.engine };
+}
+function handleNonZeroTestExit(result, normalizedPaths) {
+    if (result.exitCode === 0 || result.exitCode === 130)
+        return;
+    const combinedOutput = `${result.stdout}\n${result.stderr}`;
+    if (/UNKNOWN TEST\b/i.test(combinedOutput)) {
+        throw new GeneralError(buildUnknownTestMessage(normalizedPaths));
+    }
+    if (hasStaleBuildArtifactsSignal(combinedOutput)) {
+        throw new GeneralError(buildStaleBuildMessage());
+    }
+    if (/invalid filename/i.test(combinedOutput) ||
+        /chrome:\/\/mochitests.*not found/i.test(combinedOutput)) {
+        info('Hint: The test file may not be registered in browser.toml or jar.mn.');
+        info('Run "fireforge register <test-path>" to register it.');
+    }
+    throw new BuildError(`Tests failed with exit code ${result.exitCode}. Check the output above for details.`, 'mach test');
+}
+/**
+ * Runs the test command to execute mach tests.
+ * @param projectRoot - Root directory of the project
+ * @param testPaths - Test file or directory paths
+ * @param options - Test options
+ */
+export async function testCommand(projectRoot, testPaths, options = {}) {
+    intro('FireForge Test');
+    const paths = getProjectPaths(projectRoot);
+    // Check if engine exists
+    if (!(await pathExists(paths.engine))) {
+        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
+    }
+    // Check for build artifacts before running tests
+    const buildCheck = await hasBuildArtifacts(paths.engine);
+    if (buildCheck.ambiguous && buildCheck.objDirs && buildCheck.objDirs.length > 0) {
+        throw new AmbiguousBuildArtifactsError(buildCheck.objDirs);
+    }
+    const mismatchMessage = buildArtifactMismatchMessage(paths.engine, buildCheck, 'Tests');
+    if (mismatchMessage) {
+        throw new GeneralError(mismatchMessage);
+    }
+    if (!buildCheck.exists) {
+        const detail = buildCheck.objDir
+            ? `Build artifacts incomplete in ${buildCheck.objDir}/`
+            : 'No build artifacts found (obj-*/ directory missing)';
+        throw new GeneralError(`Tests require a completed build. ${detail}\n\n` +
+            "Run 'fireforge build' first, then run 'fireforge test'.");
+    }
+    // Run incremental build if requested
+    if (options.build) {
+        const { engineDir } = await prepareIncrementalTestBuild(projectRoot);
+        const s = spinner('Running incremental build...');
+        const buildExitCode = await buildUI(engineDir);
+        if (buildExitCode !== 0) {
+            s.error('Pre-test build failed');
+            throw new BuildError('Pre-test build failed', 'mach build faster');
+        }
+        s.stop('Build complete');
+        info('');
+    }
+    // Normalize test paths (strip engine/ prefix if present)
+    const normalizedPaths = testPaths.map(normalizeTestPath);
+    await assertTestPathsExist(paths.engine, normalizedPaths);
+    // Build extra args
+    const extraArgs = [];
+    if (options.headless) {
+        extraArgs.push('--headless');
+    }
+    // Log what we're doing
+    if (normalizedPaths.length > 0) {
+        info(`Running tests: ${normalizedPaths.join(', ')}`);
+    }
+    else {
+        info('Running all tests...');
+    }
+    info('');
+    let result;
+    try {
+        result = await testWithOutput(paths.engine, normalizedPaths, extraArgs);
+    }
+    catch (error) {
+        throw new BuildError('Test process failed to start', 'mach test', error instanceof Error ? error : undefined);
+    }
+    handleNonZeroTestExit(result, normalizedPaths);
+}
+/** Registers the test command on the CLI program. */
+export function registerTest(program, { getProjectRoot, withErrorHandling }) {
+    program
+        .command('test [paths...]')
+        .description('Run tests via mach test')
+        .option('--headless', 'Run tests in headless mode')
+        .option('--build', 'Run incremental UI build before testing')
+        .action(withErrorHandling(async (paths, options) => {
+        await testCommand(getProjectRoot(), paths, pickDefined(options));
+    }));
+}
+//# sourceMappingURL=test.js.map

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

@@ -0,0 +1,5 @@
+/**
+ * Measures design token coverage across modified CSS files.
+ * @param projectRoot - Root directory of the project
+ */
+export declare function tokenCoverageCommand(projectRoot: string): Promise<void>;

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

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { getStatusWithCodes, isGitRepository } from '../core/git.js';
+import { measureTokenCoverage } from '../core/token-coverage.js';
+import { getTokensCssPath } from '../core/token-manager.js';
+import { GeneralError } from '../errors/base.js';
+import { pathExists } from '../utils/fs.js';
+import { info, intro, outro, success, warn } from '../utils/logger.js';
+/**
+ * Measures design token coverage across modified CSS files.
+ * @param projectRoot - Root directory of the project
+ */
+export async function tokenCoverageCommand(projectRoot) {
+    intro('Token Coverage');
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.engine))) {
+        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
+    }
+    if (!(await isGitRepository(paths.engine))) {
+        throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
+    }
+    const config = await loadConfig(projectRoot);
+    const tokensCssPath = getTokensCssPath(config.binaryName);
+    const files = await getStatusWithCodes(paths.engine);
+    const cssFiles = files
+        .filter((f) => f.file.endsWith('.css') && f.file !== tokensCssPath)
+        .map((f) => f.file);
+    if (cssFiles.length === 0) {
+        info('No modified CSS files');
+        outro('Nothing to measure');
+        return;
+    }
+    const report = await measureTokenCoverage(paths.engine, cssFiles);
+    // Per-file breakdown
+    for (const entry of report.files) {
+        const parts = [
+            `tokens: ${entry.tokenUsages}`,
+            `allowlisted: ${entry.allowlisted}`,
+            `unknown: ${entry.unknownVars}`,
+            `raw colors: ${entry.rawColors}`,
+        ];
+        info(`${entry.file}  ${parts.join(' | ')}`);
+    }
+    // Coverage calculation
+    const denominator = report.tokenUsages + report.unknownVarUsages + report.rawColorCount;
+    const coverage = denominator > 0 ? Math.round((report.tokenUsages / denominator) * 100) : 100;
+    info('');
+    const summary = `Token coverage: ${coverage}% (${report.tokenUsages} tokens / ${denominator} total) — ${report.rawColorCount} raw colors, ${report.unknownVarUsages} unknown vars`;
+    if (coverage === 100 && report.rawColorCount === 0) {
+        success(summary);
+    }
+    else {
+        warn(summary);
+    }
+    outro(`${report.filesScanned} CSS file${report.filesScanned === 1 ? '' : 's'} scanned`);
+}
+//# sourceMappingURL=token-coverage.js.map

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

@@ -0,0 +1,14 @@
+import { Command } from 'commander';
+import type { CommandContext } from '../types/cli.js';
+import type { TokenAddOptions } from '../types/commands/index.js';
+/**
+ * Adds a design token to the CSS file and documentation.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param tokenName - Full token name including prefix
+ * @param value - CSS value
+ * @param options - Command options
+ */
+export declare function tokenAddCommand(projectRoot: string, tokenName: string, value: string, options: TokenAddOptions): Promise<void>;
+/** Registers token management commands on the CLI program. */
+export declare function registerToken(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/token.js

@@ -0,0 +1,121 @@
+import { loadConfig } from '../core/config.js';
+import { loadFurnaceConfig } from '../core/furnace-config.js';
+import { addToken, getTokensCssPath, validateTokenAdd, } from '../core/token-manager.js';
+import { InvalidArgumentError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+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';
+async function normalizeTokenNameForProject(projectRoot, rawTokenName) {
+    if (rawTokenName.startsWith('--')) {
+        return normalizeTokenName(rawTokenName);
+    }
+    try {
+        const furnaceConfig = await loadFurnaceConfig(projectRoot);
+        if (furnaceConfig.tokenPrefix) {
+            const strippedPrefix = furnaceConfig.tokenPrefix.replace(/^--/, '').replace(/-$/, '');
+            const strippedName = rawTokenName.replace(/^--/, '');
+            return `--${strippedPrefix}-${strippedName}`;
+        }
+    }
+    catch (error) {
+        warn(`Falling back to generic token normalization because furnace.json could not be loaded: ${toError(error).message}`);
+    }
+    return normalizeTokenName(rawTokenName);
+}
+/**
+ * Adds a design token to the CSS file and documentation.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param tokenName - Full token name including prefix
+ * @param value - CSS value
+ * @param options - Command options
+ */
+export async function tokenAddCommand(projectRoot, tokenName, value, options) {
+    intro('Token Add');
+    // Normalize token name using the configured Furnace token prefix when the
+    // user supplied a bare token name like "canvas-gap".
+    tokenName = await normalizeTokenNameForProject(projectRoot, tokenName);
+    // Validate mode
+    const validModes = ['auto', 'static', 'override'];
+    if (!validModes.includes(options.mode)) {
+        throw new InvalidArgumentError(`Invalid mode "${options.mode}". Must be one of: ${validModes.join(', ')}`, 'mode');
+    }
+    if (options.dryRun) {
+        await validateTokenAdd(projectRoot, {
+            tokenName,
+            value,
+            category: options.category,
+            mode: options.mode,
+            ...(options.description !== undefined ? { description: options.description } : {}),
+            ...(options.darkValue !== undefined ? { darkValue: options.darkValue } : {}),
+            dryRun: true,
+        });
+        info('[dry-run] Would add token:');
+        info(`  Name: ${tokenName}`);
+        info(`  Value: ${value}`);
+        info(`  Category: ${options.category}`);
+        info(`  Mode: ${options.mode}`);
+        if (options.description)
+            info(`  Description: ${options.description}`);
+        if (options.darkValue)
+            info(`  Dark value: ${options.darkValue}`);
+        outro('Dry run complete');
+        return;
+    }
+    const result = await addToken(projectRoot, {
+        tokenName,
+        value,
+        category: options.category,
+        mode: options.mode,
+        ...(options.description !== undefined ? { description: options.description } : {}),
+        ...(options.darkValue !== undefined ? { darkValue: options.darkValue } : {}),
+    });
+    if (result.skipped) {
+        info(`Token ${tokenName} already exists (skipped)`);
+    }
+    else {
+        const forgeConfig = await loadConfig(projectRoot);
+        const tokensCssFile = getTokensCssPath(forgeConfig.binaryName).split('/').pop();
+        if (result.cssAdded)
+            success(`Added ${tokenName} to ${tokensCssFile}`);
+        if (result.docsAdded)
+            success(`Added ${tokenName} to SRC_TOKENS.md`);
+        if (result.unmappedAdded)
+            info(`Added to unmapped tokens table (literal value)`);
+        if (result.countUpdated)
+            info(`Updated mode count in documentation`);
+    }
+    outro('Done');
+}
+/** Registers token management commands on the CLI program. */
+export function registerToken(program, { getProjectRoot, withErrorHandling }) {
+    const token = program.command('token').description('Design token management');
+    token
+        .command('add <token-name> <value>')
+        .description('Add a design token to CSS and documentation')
+        .requiredOption('--category <cat>', 'Token category (e.g., "Colors — Canvas", "Spacing")')
+        .requiredOption('--mode <mode>', 'Dark mode behavior: auto, static, or override')
+        .option('--description <desc>', 'Comment description for the CSS file')
+        .option('--dark-value <val>', 'Dark mode value (required if mode is "override")')
+        .option('--dry-run', 'Show what would be changed without writing')
+        .action(withErrorHandling(async (tokenName, value, options) => {
+        await tokenAddCommand(getProjectRoot(), tokenName, value, {
+            category: options.category,
+            mode: options.mode,
+            ...pickDefined({
+                description: options.description,
+                darkValue: options.darkValue,
+                dryRun: options.dryRun,
+            }),
+        });
+    }));
+    token
+        .command('coverage')
+        .description('Measure design token usage across modified CSS files')
+        .action(withErrorHandling(async () => {
+        await tokenCoverageCommand(getProjectRoot());
+    }));
+}
+//# sourceMappingURL=token.js.map

package/dist/src/commands/watch.d.ts

@@ -0,0 +1,9 @@
+import { Command } from 'commander';
+import type { CommandContext } from '../types/cli.js';
+/**
+ * Runs the watch command for auto-rebuilding.
+ * @param projectRoot - Root directory of the project
+ */
+export declare function watchCommand(projectRoot: string): Promise<void>;
+/** Registers the watch command on the CLI program. */
+export declare function registerWatch(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;