@hominis/fireforge 0.44.1 → 0.44.3

package/dist/src/core/token-manager.js

@@ -11,7 +11,7 @@ import { loadFurnaceConfig } from './furnace-config.js';
 import { assertTokenCategoryExists, categoryHeaderExists, declareCategoryBanner, findCategorySection, findTokenDeclarationInRoot, } from './token-category.js';
 import { findDarkMediaCloseIndex, findDarkRootInsertionIndex } from './token-dark-mode.js';
 import { addTokenToDocs } from './token-docs.js';
-import { insertVariantDeclaration, validateVariantSelector, variantBlockExists, variantBlockHasToken, } from './token-variant.js';
+import { findVariantBlockDeclaration, insertVariantDeclaration, validateVariantSelector, variantBlockExists, variantBlockHasToken, variantBlockQualifier, } from './token-variant.js';
 /**
  * Dark mode behaviour for a token.
  *
@@ -95,7 +95,9 @@ function normalizeVariantOption(options) {
     }
     if (options.createCategory === true) {
         throw new InvalidArgumentError('--create-category cannot be combined with --variant; variant declarations are routed ' +
-            'into a :root<selector> block, not a category section.', 'variant');
+            'into a :root<selector> block, not a category section. Add the BASE token first ' +
+            '(with --create-category) to author the category, then add each variant with ' +
+            '--variant.', 'variant');
     }
     const result = validateVariantSelector(options.variant);
     if (!result.ok) {
@@ -103,6 +105,30 @@ function normalizeVariantOption(options) {
     }
     return result.value;
 }
+/**
+ * Narrows {@link AddTokenOptions.category} for the base-declaration path,
+ * which cannot proceed without one.
+ *
+ * `--category` used to be unconditionally required, INCLUDING under
+ * `--variant`, where the declaration is routed into a `:root<selector>`
+ * block and the category names nothing about where the token lands. The
+ * requirement existed so the argument would not be silently discarded —
+ * a fair goal that produced a mandatory argument describing nothing. Under
+ * a variant it is now optional; everywhere else this states the reason
+ * rather than leaving commander to print a bare "required option not
+ * specified".
+ *
+ * @param options - Token options
+ * @returns The category
+ */
+function requireCategory(options) {
+    if (options.category === undefined || options.category.trim() === '') {
+        throw new InvalidArgumentError('A base token declaration lands in a category section, so --category is required. ' +
+            'Pass --variant <selector> instead if this declaration belongs in a ' +
+            ':root<selector> block, where no category applies.', 'category');
+    }
+    return options.category;
+}
 /** Throws when the tokens CSS file is missing (variant mode skips category checks). */
 async function assertTokensCssExists(engineDir, tokensCssPath) {
     if (!(await pathExists(join(engineDir, tokensCssPath)))) {
@@ -112,15 +138,22 @@ async function assertTokensCssExists(engineDir, tokensCssPath) {
 /**
  * Routes a declaration into the top-level `:root<variant>` block — creating
  * the block after the base `:root` block if absent, or appending to it if
- * present. Idempotent within the block. Returns `{ added: false }` when the
- * token already lives in that block.
+ * present. Idempotent within the block.
+ *
+ * A skip carries the LOCATION of the existing declaration, mirroring
+ * {@link evaluateBaseTokenIdempotency}. The bare `{ added: false }` it used
+ * to return told the caller nothing, so a re-run intending to CHANGE a
+ * value exited 0 having changed nothing and said only "already exists" —
+ * while the base path had reported the category and line for the same
+ * situation all along.
  */
 async function addVariantTokenToCSS(engineDir, options, tokensCssPath, variant) {
     await assertTokensCssExists(engineDir, tokensCssPath);
     const filePath = join(engineDir, tokensCssPath);
     const lines = (await readText(filePath)).split('\n');
-    if (variantBlockHasToken(lines, variant, options.tokenName))
-        return { added: false };
+    const declared = findVariantBlockDeclaration(lines, variant, options.tokenName);
+    if (declared !== undefined)
+        return { added: false, existing: declared };
     const annotation = getModeAnnotation(options.mode, options.value);
     insertVariantDeclaration(lines, variant, `  ${options.tokenName}: ${options.value}; /* ${annotation} */`);
     await writeText(filePath, lines.join('\n'));
@@ -158,14 +191,17 @@ export async function validateTokenAdd(root, options) {
     validateTokenNameSyntax(options.tokenName);
     await validateTokenPrefix(root, options);
     validateDarkValue(options);
-    // Variant mode targets a `:root<attr>` block, not a category section —
-    // but the required --category must still name a REAL category rather
-    // than being silently discarded (bypass 2).
+    // Variant mode targets a `:root<attr>` block, not a category section, so
+    // no category is consulted — and none is required. When one IS passed it
+    // is still checked, so a typo'd category is not silently accepted just
+    // because the flag happens to be inert here.
     if (normalizeVariantOption(options) !== undefined) {
-        await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, false);
+        if (options.category !== undefined && options.category.trim() !== '') {
+            await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, false);
+        }
         return;
     }
-    await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, options.createCategory === true);
+    await assertTokenCategoryExists(engineDir, tokensCssPath, requireCategory(options), options.createCategory === true);
 }
 /**
  * Adds a design token to the CSS file and documentation.
@@ -209,16 +245,19 @@ export async function addToken(root, options) {
     // docs row). Done before the base-CSS path so an override of an existing
     // base token is not short-circuited by the global idempotency check.
     if (normalizedVariant !== undefined) {
-        // The required --category must name a real category even though the
-        // declaration routes into the variant block (bypass 2).
-        await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, false);
-        const { added } = await addVariantTokenToCSS(engineDir, options, tokensCssPath, normalizedVariant);
+        // A category is optional here and names nothing about where the
+        // declaration lands, but a category that was passed is still verified.
+        if (options.category !== undefined && options.category.trim() !== '') {
+            await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, false);
+        }
+        const { added, existing } = await addVariantTokenToCSS(engineDir, options, tokensCssPath, normalizedVariant);
         return {
             cssAdded: added,
             docsAdded: false,
             unmappedAdded: false,
             countUpdated: false,
             skipped: !added,
+            ...(existing !== undefined ? { skippedExisting: existing } : {}),
         };
     }
     // --- CSS file ---
@@ -234,7 +273,11 @@ export async function addToken(root, options) {
         };
     }
     // --- Documentation ---
-    const docsResult = await addTokenToDocs(engineDir, options, getModeAnnotation(options.mode, options.value));
+    // Only the base path reaches here (variant declarations returned above),
+    // so a category is guaranteed — `requireCategory` already ran inside
+    // `addTokenToCSS`. Re-narrowing rather than asserting keeps the docs
+    // input's required `category` honest.
+    const docsResult = await addTokenToDocs(engineDir, { ...options, category: requireCategory(options) }, getModeAnnotation(options.mode, options.value));
     return {
         cssAdded,
         docsAdded: docsResult.docsAdded,
@@ -274,6 +317,16 @@ function insertThemeAttributeOverrides(lines, options) {
         const value = pick === 'dark' ? options.darkValue : options.value;
         insertVariantDeclaration(lines, variant, `  ${options.tokenName}: ${value};`);
         written.push(`:root${variant}`);
+        // A qualified block is matched — skipping it is the worse failure, and
+        // the one that shipped — but the qualifier narrows where the token
+        // applies, so say which selector was written through rather than
+        // letting the operator meet the narrowing as a theme bug later.
+        const qualifier = variantBlockQualifier(lines, variant);
+        if (qualifier !== undefined && qualifier.length > 0) {
+            warn(`Wrote ${options.tokenName} into the qualified block ":root${variant}${qualifier}". ` +
+                `The "${qualifier}" qualifier narrows where this override applies; ` +
+                'add an unqualified block if it should apply to every case.');
+        }
     }
     return written;
 }
@@ -304,7 +357,8 @@ function insertDarkModeOverride(lines, options) {
  */
 async function addTokenToCSS(engineDir, options, tokensCssPath) {
     const filePath = join(engineDir, tokensCssPath);
-    await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, options.createCategory === true);
+    const category = requireCategory(options);
+    await assertTokenCategoryExists(engineDir, tokensCssPath, category, options.createCategory === true);
     const content = await readText(filePath);
     const lines = content.split('\n');
     // Per-category idempotency: a declaration in the TARGET
@@ -324,11 +378,11 @@ async function addTokenToCSS(engineDir, options, tokensCssPath) {
     // token insertion — the file is written exactly once, so a failure
     // between "banner declared" and "token inserted" cannot occur.
     let categoryCreated = false;
-    if (options.createCategory === true && !categoryHeaderExists(lines, options.category)) {
-        declareCategoryBanner(lines, options.category, tokensCssPath);
+    if (options.createCategory === true && !categoryHeaderExists(lines, category)) {
+        declareCategoryBanner(lines, category, tokensCssPath);
         categoryCreated = true;
     }
-    const { categoryLine, sectionEnd } = findCategorySection(lines, options.category, tokensCssPath);
+    const { categoryLine, sectionEnd } = findCategorySection(lines, category, tokensCssPath);
     // Build the insertion lines
     const insertLines = [];
     if (options.description) {

package/dist/src/core/token-variant.d.ts

@@ -9,6 +9,7 @@
  * `:root<variant>` block so `token-manager.ts` can splice a declaration into
  * it, keeping all token authoring in the CLI.
  */
+import type { TokenDeclarationLocation } from './token-category.js';
 /**
  * Outcome of {@link validateVariantSelector}. `ok: true` carries the
  * normalized (quoted) selector fragment; `ok: false` carries a
@@ -22,10 +23,20 @@ export type VariantValidation = {
     reason: string;
 };
 /**
- * Validates a `--variant` attribute selector fragment and normalizes any
- * `=value` form to the double-quoted `="value"` shape (Mozilla convention).
+ * Validates a `--variant` selector fragment and normalizes any `=value`
+ * form to the double-quoted `="value"` shape (Mozilla convention).
  * Boolean-attribute fragments are returned unchanged.
  *
+ * Structure is decided by {@link rootAttributeSelector} — the matcher's own
+ * parse — rather than by a second regex. That is the point: 0.44.2 widened
+ * the matcher to consume consecutive `[…]` groups and stop at a pseudo-class
+ * tail, and the validator did not move with it, so
+ * `:root[data-skin="humanist"]:not([data-private])` was a block the tool
+ * could FIND but would not let you NAME. Running both halves off one parse
+ * is what stops them drifting apart again. Character-level safety stays a
+ * separate, per-group check, because the matcher finds bracket boundaries
+ * and validates no characters at all.
+ *
  * @param raw - Raw `--variant` value from the CLI / programmatic caller.
  */
 export declare function validateVariantSelector(raw: unknown): VariantValidation;
@@ -36,8 +47,41 @@ export declare function validateVariantSelector(raw: unknown): VariantValidation
  * the block, which is only wanted for the explicit `--variant` flow.
  */
 export declare function variantBlockExists(lines: string[], variant: string): boolean;
+/**
+ * The pseudo-class qualifier on the matched `:root<variant>` block, or
+ * `undefined` when no block matched. `''` for an unqualified block.
+ *
+ * A qualifier such as `:not([data-private])` is semantically LOAD-BEARING:
+ * writing into that block scopes the declaration to the qualified case, and
+ * that may not be what the operator meant. Matching it is still the right
+ * call — silently skipping it is the worse failure, and the one that
+ * shipped — but the override path uses this to say out loud which selector
+ * it wrote through, so the narrowing is a visible decision rather than a
+ * theme bug discovered later.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param variant - Attribute selector fragment, e.g. `[data-theme="light"]`
+ * @returns The qualifier, or undefined when no block matched
+ */
+export declare function variantBlockQualifier(lines: string[], variant: string): string | undefined;
 /** True when the `:root<variant>` block already declares `tokenName`. */
 export declare function variantBlockHasToken(lines: string[], variant: string, tokenName: string): boolean;
+/**
+ * Locates an existing declaration of `tokenName` inside the
+ * `:root<variant>` block, or `undefined` when the block has none (or does
+ * not exist).
+ *
+ * The located form of {@link variantBlockHasToken}: the variant add path
+ * reports a skip the way the base path does — naming the block and the
+ * line — instead of returning a bare boolean that leaves a no-op re-run
+ * indistinguishable from a write.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param variant - Attribute selector fragment
+ * @param tokenName - Full token name including prefix
+ * @returns The declaration's 1-based line, or undefined
+ */
+export declare function findVariantBlockDeclaration(lines: string[], variant: string, tokenName: string): TokenDeclarationLocation | undefined;
 /**
  * Splices `declLine` into the `:root<variant>` block, creating the block
  * (after the base `:root` block) when absent or appending after the last

package/dist/src/core/token-variant.js

@@ -12,36 +12,113 @@
  */
 import { findBlockCloseIndex, stripBlockCommentsInLines } from './token-dark-mode.js';
 /**
- * Accepts a single attribute selector fragment: `[data-private]` (boolean
- * attribute) or `[data-skin=precision]` / `[data-skin="precision"]`
- * (attribute with value). The value half is restricted to identifier-safe
+ * ONE attribute selector fragment: `[data-private]` (boolean attribute) or
+ * `[data-skin=precision]` / `[data-skin="precision"]` (attribute with
+ * value). The name and value halves are restricted to identifier-safe
  * characters so the fragment can be spliced into CSS verbatim without
  * escaping concerns.
+ *
+ * A multi-fragment variant is checked one group at a time (see
+ * {@link splitAttributeGroups}) rather than by wrapping this in a `+`: the
+ * repeated form is the shape CodeQL flags as `js/polynomial-redos`, and the
+ * split the matcher already performs is available for free.
+ */
+const ATTRIBUTE_FRAGMENT_PATTERN = /^\[[a-zA-Z][a-zA-Z0-9_-]*(?:=(?:"[a-zA-Z0-9_-]+"|'[a-zA-Z0-9_-]+'|[a-zA-Z0-9_-]+))?\]$/;
+/**
+ * A pseudo-class tail: `:not(…)`, `:hover`, and friends. The parenthesised
+ * argument is captured rather than validated here — it is a fragment run of
+ * its own and goes through the same per-group check.
+ */
+const QUALIFIER_PATTERN = /^:[a-zA-Z][a-zA-Z0-9-]*(?:\(([^()]*)\))?$/;
+/**
+ * Splits a run of consecutive attribute fragments into its groups, or
+ * returns `null` when the run is not exactly that — a group that does not
+ * open with `[`, an unclosed group, an empty run, or a group whose name or
+ * value is not identifier-safe.
+ *
+ * @param run - The `[…][…]` text with no `:root` prefix
+ * @returns The individual fragments, or null when the run is not valid
  */
-const VARIANT_PATTERN = /^\[[a-zA-Z][a-zA-Z0-9_-]*(?:=(?:"[a-zA-Z0-9_-]+"|'[a-zA-Z0-9_-]+'|[a-zA-Z0-9_-]+))?\]$/;
+function splitAttributeGroups(run) {
+    const groups = [];
+    let cursor = 0;
+    while (cursor < run.length) {
+        if (run[cursor] !== '[')
+            return null;
+        const close = run.indexOf(']', cursor);
+        if (close === -1)
+            return null;
+        const group = run.slice(cursor, close + 1);
+        if (!ATTRIBUTE_FRAGMENT_PATTERN.test(group))
+            return null;
+        groups.push(group);
+        cursor = close + 1;
+    }
+    return groups.length > 0 ? groups : null;
+}
+/** Rewrites `=value` / `='value'` to the double-quoted Mozilla convention. */
+function normalizeAttributeFragment(group) {
+    return group
+        .replace(/='([a-zA-Z0-9_-]+)'\]$/, '="$1"]')
+        .replace(/=([a-zA-Z0-9_-]+)\]$/, '="$1"]');
+}
 /**
- * Validates a `--variant` attribute selector fragment and normalizes any
- * `=value` form to the double-quoted `="value"` shape (Mozilla convention).
+ * Validates a `--variant` selector fragment and normalizes any `=value`
+ * form to the double-quoted `="value"` shape (Mozilla convention).
  * Boolean-attribute fragments are returned unchanged.
  *
+ * Structure is decided by {@link rootAttributeSelector} — the matcher's own
+ * parse — rather than by a second regex. That is the point: 0.44.2 widened
+ * the matcher to consume consecutive `[…]` groups and stop at a pseudo-class
+ * tail, and the validator did not move with it, so
+ * `:root[data-skin="humanist"]:not([data-private])` was a block the tool
+ * could FIND but would not let you NAME. Running both halves off one parse
+ * is what stops them drifting apart again. Character-level safety stays a
+ * separate, per-group check, because the matcher finds bracket boundaries
+ * and validates no characters at all.
+ *
  * @param raw - Raw `--variant` value from the CLI / programmatic caller.
  */
 export function validateVariantSelector(raw) {
     if (typeof raw !== 'string') {
         return { ok: false, reason: 'must be a string when set' };
     }
+    const reject = {
+        ok: false,
+        reason: 'must be one or more attribute selectors like [data-private], [data-skin=precision] ' +
+            'or [data-skin=precision][data-theme=dark], optionally followed by a pseudo-class ' +
+            'such as :not([data-private]) (identifier-safe attribute names and values only)',
+    };
     const value = raw.trim();
-    if (!VARIANT_PATTERN.test(value)) {
-        return {
-            ok: false,
-            reason: 'must be a single attribute selector like [data-private] or [data-skin=precision] ' +
-                '(identifier-safe attribute name and value only)',
-        };
+    if (value === '')
+        return reject;
+    const parts = rootAttributeSelector(`:root${value} {`);
+    // The parse must have consumed the WHOLE fragment: anything it declined to
+    // read (a stray space, a trailing combinator) is text the matcher would
+    // not see either, so accepting it would author a block nothing can find.
+    if (parts === null || `${parts.attributes}${parts.qualifier}` !== `:root${value}`)
+        return reject;
+    const groups = splitAttributeGroups(parts.attributes.slice(':root'.length));
+    if (groups === null)
+        return reject;
+    let qualifier = '';
+    if (parts.qualifier !== '') {
+        const match = QUALIFIER_PATTERN.exec(parts.qualifier);
+        if (match === null)
+            return reject;
+        const inner = match[1];
+        if (inner === undefined) {
+            qualifier = parts.qualifier;
+        }
+        else {
+            const innerGroups = splitAttributeGroups(inner);
+            if (innerGroups === null)
+                return reject;
+            const name = parts.qualifier.slice(0, parts.qualifier.indexOf('('));
+            qualifier = `${name}(${innerGroups.map(normalizeAttributeFragment).join('')})`;
+        }
     }
-    const normalized = value
-        .replace(/='([a-zA-Z0-9_-]+)'\]$/, '="$1"]')
-        .replace(/=([a-zA-Z0-9_-]+)\]$/, '="$1"]');
-    return { ok: true, value: normalized };
+    return { ok: true, value: `${groups.map(normalizeAttributeFragment).join('')}${qualifier}` };
 }
 /**
  * Reduces a `:root<attr>` selector to a quote- and whitespace-insensitive
@@ -53,15 +130,27 @@ function canonicalSelector(selector) {
     return selector.replace(/\s+/g, '').replace(/["']/g, '');
 }
 /**
- * The `:root[…]` selector fragment on `line`, spanning to the LAST `]` that
- * precedes the block's opening brace, or `null` when the line carries none.
+ * Splits the `:root[…]` selector on `line` into its attribute run and any
+ * trailing qualifier, or `null` when the line carries none.
  *
  * Index arithmetic rather than `/:root\[[^{]*\]/`: `[^{]` also matches `]`,
  * so that pattern backtracks quadratically on a line repeating `:root[`
- * (CodeQL `js/polynomial-redos`). Taking the last `]` — not the first —
- * preserves the greedy regex's reach, so a multi-attribute selector still
- * compares as the whole fragment and does not collide with a single-attribute
- * variant that happens to be its prefix.
+ * (CodeQL `js/polynomial-redos`). This walk is linear and allocation-free
+ * per group.
+ *
+ * It consumes CONSECUTIVE `[…]` groups and stops at the first character that
+ * is not `[`. The previous implementation instead sliced to the LAST `]`
+ * before the brace, which kept multi-attribute selectors comparing as a
+ * whole — that property is preserved here, since consecutive groups are all
+ * consumed — but it also swallowed a pseudo-class tail. On
+ * `:root[data-theme="light"]:not([data-private]) {` the last `]` is the one
+ * inside `:not(…)`, so the computed fragment was
+ * `:root[data-theme="light"]:not([data-private]` and the canonical
+ * comparison could never match. The unqualified
+ * `:root[data-theme="dark"] { }` beside it matched fine, and that asymmetry
+ * WAS the bug: an override add mirrored itself into the dark block and
+ * silently skipped the light one, which is precisely the half-finished
+ * themed edit `THEME_ATTRIBUTE_VARIANTS` exists to prevent.
  */
 function rootAttributeSelector(line) {
     const start = line.indexOf(':root[');
@@ -69,10 +158,18 @@ function rootAttributeSelector(line) {
         return null;
     const brace = line.indexOf('{', start);
     const limit = brace === -1 ? line.length : brace;
-    const close = line.lastIndexOf(']', limit - 1);
-    if (close <= start + ':root['.length - 1)
+    let cursor = start + ':root'.length;
+    let end = cursor;
+    while (cursor < limit && line[cursor] === '[') {
+        const close = line.indexOf(']', cursor);
+        if (close === -1 || close >= limit)
+            break;
+        cursor = close + 1;
+        end = cursor;
+    }
+    if (end === start + ':root'.length)
         return null;
-    return line.slice(start, close + 1);
+    return { attributes: line.slice(start, end), qualifier: line.slice(end, limit).trim() };
 }
 /**
  * Finds the top-level `:root<variant>` block whose attribute selector
@@ -85,11 +182,23 @@ function rootAttributeSelector(line) {
  */
 function findVariantBlock(lines, variant) {
     const stripped = stripBlockCommentsInLines(lines);
-    const want = canonicalSelector(`:root${variant}`);
+    // The request goes through the same parse as the candidate lines, so a
+    // variant carrying its own `:not(…)` tail is compared tail-to-tail rather
+    // than being folded into the attribute run — where it would match nothing
+    // and every add would splice a fresh duplicate block.
+    const requested = rootAttributeSelector(`:root${variant} {`);
+    const want = canonicalSelector(requested?.attributes ?? `:root${variant}`);
+    const wantQualifier = canonicalSelector(requested?.qualifier ?? '');
     for (let i = 0; i < stripped.length; i++) {
         const line = stripped[i] ?? '';
         const selector = rootAttributeSelector(line);
-        if (selector === null || canonicalSelector(selector) !== want)
+        if (selector === null || canonicalSelector(selector.attributes) !== want)
+            continue;
+        // An UNqualified request still matches a qualified block: that is the
+        // 0.44.2 behaviour `variantBlockQualifier` exists to report, since
+        // silently skipping the block is the worse failure. A request that names
+        // a qualifier, though, means it — so it must match.
+        if (wantQualifier !== '' && canonicalSelector(selector.qualifier) !== wantQualifier)
             continue;
         let openLine = /\{/.test(line) ? i : -1;
         if (openLine === -1) {
@@ -108,7 +217,7 @@ function findVariantBlock(lines, variant) {
         const close = findBlockCloseIndex(stripped, openLine);
         if (close === -1)
             continue;
-        return { open: openLine, close };
+        return { open: openLine, close, qualifier: selector.qualifier };
     }
     return null;
 }
@@ -138,16 +247,64 @@ function findVariantBlockInsertionPoint(lines) {
 export function variantBlockExists(lines, variant) {
     return findVariantBlock(lines, variant) !== null;
 }
+/**
+ * The pseudo-class qualifier on the matched `:root<variant>` block, or
+ * `undefined` when no block matched. `''` for an unqualified block.
+ *
+ * A qualifier such as `:not([data-private])` is semantically LOAD-BEARING:
+ * writing into that block scopes the declaration to the qualified case, and
+ * that may not be what the operator meant. Matching it is still the right
+ * call — silently skipping it is the worse failure, and the one that
+ * shipped — but the override path uses this to say out loud which selector
+ * it wrote through, so the narrowing is a visible decision rather than a
+ * theme bug discovered later.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param variant - Attribute selector fragment, e.g. `[data-theme="light"]`
+ * @returns The qualifier, or undefined when no block matched
+ */
+export function variantBlockQualifier(lines, variant) {
+    return findVariantBlock(lines, variant)?.qualifier;
+}
 /** True when the `:root<variant>` block already declares `tokenName`. */
 export function variantBlockHasToken(lines, variant, tokenName) {
+    return findVariantBlockDeclaration(lines, variant, tokenName) !== undefined;
+}
+/**
+ * Locates an existing declaration of `tokenName` inside the
+ * `:root<variant>` block, or `undefined` when the block has none (or does
+ * not exist).
+ *
+ * The located form of {@link variantBlockHasToken}: the variant add path
+ * reports a skip the way the base path does — naming the block and the
+ * line — instead of returning a bare boolean that leaves a no-op re-run
+ * indistinguishable from a write.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param variant - Attribute selector fragment
+ * @param tokenName - Full token name including prefix
+ * @returns The declaration's 1-based line, or undefined
+ */
+export function findVariantBlockDeclaration(lines, variant, tokenName) {
     const block = findVariantBlock(lines, variant);
     if (!block)
-        return false;
-    const blockText = lines
-        .slice(block.open, block.close + 1)
+        return undefined;
+    // Comments are stripped across the WHOLE block before scanning, matching
+    // what the boolean form always did: a `/* … */` spanning several lines
+    // must not leave its tail looking like a declaration.
+    const blockLines = lines.slice(block.open, block.close + 1);
+    // Blank the comment's CHARACTERS rather than deleting it: removing a
+    // multi-line comment outright collapses its lines and shifts every line
+    // number after it, which is the one thing this function exists to report.
+    const stripped = blockLines
         .join('\n')
-        .replace(/\/\*[\s\S]*?\*\//g, '');
-    return blockText.includes(`${tokenName}:`);
+        .replace(/\/\*[\s\S]*?\*\//g, (match) => match.replace(/[^\n]/g, ' '))
+        .split('\n');
+    for (let i = 0; i < stripped.length; i++) {
+        if ((stripped[i] ?? '').includes(`${tokenName}:`))
+            return { line: block.open + i + 1 };
+    }
+    return undefined;
 }
 /**
  * Splices `declLine` into the `:root<variant>` block, creating the block

package/dist/src/types/commands/options.d.ts

@@ -539,6 +539,12 @@ export interface RunOptions {
 export interface TestOptions {
     /** Run tests in headless mode */
     headless?: boolean;
+    /**
+     * Pass mozbuild's full verbosity through for the TEST phase by unsetting
+     * the coding-agent markers it quiets output on. Off by default, because
+     * that quieting is worth keeping for builds.
+     */
+    fullOutput?: boolean;
     /** Run incremental UI build before testing */
     build?: boolean;
     /**
@@ -652,6 +658,12 @@ export interface FurnaceApplyOptions {
     force?: boolean;
     /** Watch component directories and re-apply on changes */
     watch?: boolean;
+    /**
+     * Resolved `--wait-lock` budget in seconds, or undefined for the default.
+     * Threaded to the furnace lock `runFurnaceMutation` takes INSIDE the
+     * engine session lock, so one flag governs both.
+     */
+    waitLockSeconds?: number;
 }
 /**
  * Options for the furnace preview command.
@@ -670,6 +682,12 @@ export interface FurnaceDeployOptions {
     force?: boolean;
     /** Skip the validation step (apply only, no accessibility/compatibility checks) */
     skipValidate?: boolean;
+    /**
+     * Resolved `--wait-lock` budget in seconds, or undefined for the default.
+     * Threaded to the furnace lock `runFurnaceMutation` takes INSIDE the
+     * engine session lock, so one flag governs both.
+     */
+    waitLockSeconds?: number;
 }
 /**
  * Options for the furnace refresh command.
@@ -692,6 +710,12 @@ export interface FurnaceSyncOptions {
     dryRun?: boolean;
     /** Conflict resolution strategy for three-way merge (ours = keep local, theirs = accept upstream) */
     strategy?: 'ours' | 'theirs';
+    /**
+     * Resolved `--wait-lock` budget in seconds, or undefined for the default.
+     * Threaded to the furnace lock `runFurnaceMutation` takes INSIDE the
+     * engine session lock, so one flag governs both.
+     */
+    waitLockSeconds?: number;
 }
 /**
  * Options for the furnace validate command.
@@ -965,7 +989,12 @@ export interface StatusOptions {
  * Options for the token add command.
  */
 export interface TokenAddOptions {
-    category: string;
+    /**
+     * Required for a base declaration; optional under
+     * {@link TokenAddOptions.variant}, which routes into a `:root<selector>`
+     * block where no category applies.
+     */
+    category?: string;
     mode: string;
     description?: string;
     darkValue?: string;

package/dist/src/utils/child-env.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Environment construction for spawned children.
+ *
+ * Its own module rather than a helper inside `process.ts` only because that
+ * file sits on a 500-line budget; the logic belongs to the exec layer.
+ */
+/** The `env` / `envUnset` slice of exec options this module needs. */
+export interface ChildEnvOptions {
+    /** Variables to add or overwrite on top of `process.env`. */
+    env?: Record<string, string> | undefined;
+    /** Variables to remove after the merge. */
+    envUnset?: readonly string[] | undefined;
+}
+/**
+ * The child's environment: `process.env`, with `env` merged over it, then
+ * every `envUnset` key removed.
+ *
+ * One helper rather than five inline spreads — the removal step is easy to
+ * add at four of the five spawn sites and forget at the fifth, which would
+ * make the option silently inert exactly where it was not tested.
+ *
+ * Removal is a real removal, not an assignment to `''`: mozbuild's
+ * `is_running_under_coding_agent()` reads `CLAUDECODE` for its PRESENCE, so
+ * an empty value would not unset it. `Reflect.deleteProperty` rather than
+ * `delete obj[key]` because the key is computed.
+ *
+ * @param options - Options carrying `env` / `envUnset`
+ * @returns The environment to hand `spawn`
+ */
+export declare function buildChildEnv(options: ChildEnvOptions): NodeJS.ProcessEnv;