@reforma/project-tokens 0.0.1

package/README.md

@@ -0,0 +1,174 @@
+# @reforma/project-tokens
+
+Compile project DTCG JSON into CSS, Tailwind theme bindings, and mode metadata.
+The compiler runs locally on Node 24 or newer. It does not call a Reforma service.
+
+## CLI
+
+Install the package, then call the `reforma-tokens` binary from a script. The default
+entry is `.reforma/tokens/tokens.resolver.json`.
+
+```json
+{
+  "scripts": {
+    "dev": "reforma-tokens dev -- next dev",
+    "build": "reforma-tokens build && next build"
+  }
+}
+```
+
+`dev` compiles, then runs the command after `--`. That command starts the app and
+must not call `reforma-tokens` again. `check`, `build`, and `watch` take no child
+command.
+
+| Command              | Behavior                                                                               |
+| -------------------- | -------------------------------------------------------------------------------------- |
+| `check`              | Validate every permutation. Write nothing. Exit 1 on errors.                           |
+| `build`              | Compile and replace changed generated files. Exit 1 on errors.                         |
+| `watch`              | Build, then poll dependency hashes. Recover after invalid or missing files.            |
+| `dev -- command ...` | Build before starting the command. Watch sources. Forward signals and the exit status. |
+
+`--cwd directory` selects the workspace. `--entry path` selects its resolver.
+Repeat `--context axis=value` to supply contexts, including axes without defaults.
+Every permutation is validated. The selected or default input supplies `:root`.
+Names are case-sensitive. Compilation stops at 1000 permutations.
+
+Ignore `.reforma/tokens/.generated/` in Git. A build writes `tokens.css`,
+`tailwind.css`, and `modes.json` there, and may leave staging and lock files
+while it runs. Import the generated CSS before application styles, and import
+`tailwind.css` through the project's Tailwind entry.
+
+A failed rebuild leaves the last successful output unchanged. Watch and dev print
+one JSON diagnostic per line on stderr and `{ "status": "stale", "revision" }`
+when input is invalid. A successful rebuild prints `{ "status": "ready", "revision" }`
+on stdout. The app keeps running after a bad edit. An invalid first build does
+not start the dev command.
+
+## API
+
+```ts
+import { compileProjectTokens } from "@reforma/project-tokens";
+
+const result = await compileProjectTokens({ workspaceRoot: process.cwd() });
+if (result.ok) {
+  console.log(result.output?.tokensCss);
+  console.log(result.permutations);
+}
+```
+
+Compilation reads sources and returns diagnostics, dependency SHA-256 hashes,
+an input revision, resolved tokens per permutation, and generated strings.
+Each token keeps its canonical path, type, resolved value, CSS declarations, and
+winning source file and JSON Pointer. A missing dependency has a null hash.
+The API does not write files. Source extensions stay opaque.
+
+Local file references and same-document JSON Pointers resolve. Remote URLs,
+paths that leave the workspace, and symlinks that escape it are rejected.
+Resolver `$ref` siblings replace referenced fields shallowly. Ordered composition
+replaces whole tokens. Groups merge recursively. Aliases resolve after composition
+for each context. `$root` stays in token identity and aliases, and is omitted
+from CSS names.
+
+A `mode` modifier selects `html[data-theme="context"]`. Any other axis selects
+`html[data-token-AXIS="context"]`. Each selector constrains every active axis.
+`:root` receives the full default. Context selectors receive only the values
+that differ. CSS names join path segments with `-`, escape CSS characters, and
+reject collisions. Recognized Tailwind namespaces become `@theme inline` bindings.
+Other groups stay ordinary CSS variables. The namespace does not infer the type.
+
+### Authoring data
+
+The snapshot describes the sources an editor can show:
+
+| Field                                           | Meaning                                                                                                                                                                                 |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `editing`                                       | A supported layout with `defaultMode`, `baseFile`, and `modeFiles`, or why structured editing is unavailable. A null mode file is a sparse context.                                     |
+| `permutations[].groups`                         | Flat group hierarchy, including empty groups and the root at `""`. Each group has provenance, original metadata in `definition`, and effective `type`, `description`, and `deprecated`. |
+| `tokens[].authoring.definition`                 | Original token properties, including unresolved `$value` aliases, JSON Pointers, and vendor extensions. `value` stays resolved.                                                         |
+| `tokens[].description`, `deprecated`            | Effective metadata after composition and group inheritance. Description belongs to the node. Type and deprecation can be inherited.                                                     |
+| `tokens[].authoring.inheritance`                | `base`, `inherited`, or `override` in the supported mode layout, or null when ownership is ambiguous. An explicit override stays an override when its value equals the base.            |
+| `tokens[].authoring.canReset`, `readOnlyReason` | Whether reset is allowed, and why the simple value editor cannot change this token. Composite values and tokens supplied through `$extends` stay readable.                              |
+
+Group `definition` is metadata from the last contributing source, without children
+or `$root`. Effective fields describe the composed group. Do not write that object
+back as a document. Definitions and resolved values share the snapshot revision,
+including candidates from `planTokenMutation`.
+
+Eligibility describes source structure. A mutation still checks references,
+usages, the revision, and the full candidate. Missing authoring fields do not
+mean the token can be edited.
+
+## Structured editing
+
+`planTokenMutation` from `@reforma/project-tokens/mutations` plans source edits
+and compiles the candidate in memory. It returns the original revision, changed
+files with before and after text, and the candidate compilation. It writes nothing.
+
+Create a top-level scope with `{ kind: 'scope.create', path, type }` and one of
+the exported `DTCG_TOKEN_TYPES`. `group.create` adds an inherited subgroup inside
+an existing scope. `token.create` sets `$value` and metadata in the default mode
+and takes the type from that scope. `$type` is rejected on token create, ordinary
+updates, and sparse mode files.
+
+Token operations are update, delete, reset, and rename. Group operations are
+delete and rename. A rename is `{ kind, path, to }`. A token destination must
+share the scope type. Nested groups stay inside their scope. A scope can be
+renamed at the top level. Aliases, JSON Pointers, and mode overrides move with
+the node, and values keep their inherited type. A scope type cannot change.
+Deleting a nonempty group requires `tokens`, the exact list of descendant paths.
+
+Mode operations are create, delete, default, rename, and reset. Mode rename is
+`{ kind: 'mode.rename', mode, to }`. Mode reset drops that mode's overrides.
+The default mode cannot be reset.
+
+The managed profile is one base set, then a `mode` modifier, with separate local
+JSON files and an empty default context. Every top-level base group declares one
+standard `$type`. Nested groups inherit it. Base owns every token path. A token
+`$type`, a mode `$type`, a mode-only path, or a cross-type descendant fails with
+a path-specific `SCOPE_*` diagnostic, including `expectedType` and `actualType`
+on a mismatch. Invalid managed sources produce no output and block structured
+writes. The compiler does not infer types or migrate documents.
+
+A sparse context gets its own document on the first edit. Other resolver layouts
+remain ordinary DTCG input, and structured editing reports `AMBIGUOUS_SOURCE`.
+Changing the default preserves effective values and aliases. Detached mode
+documents stay on disk. An existing file is not reused because its name matches.
+
+Changing the default, including replacing a deleted default, does not yet keep
+group-inherited `$deprecated` metadata across modes. CSS and values are preserved.
+Deprecation metadata is not.
+
+`buildProjectTokens` and `withTokenCompilationLock` from
+`@reforma/project-tokens/generation` write the same output as the CLI.
+
+## Compatibility
+
+The target is [DTCG Format 2025.10](https://www.designtokens.org/tr/2025.10/format/)
+and Resolver 2025.10. Terrazzo's parser and CSS tools are pinned to `2.7.1`.
+The adapter covers tested upstream gaps: shallow resolver-reference overrides,
+set references inside contexts, escaped pointers, shared group inheritance,
+JSON Pointer `$extends`, explicit `$root`, composite array aliases, and provenance.
+Neutral parser IDs keep legal names such as `constructor` and `__proto__`.
+A value gate rejects Terrazzo-only types and dimension units. Unknown vendor
+extensions do not turn on Terrazzo's legacy modes. A modifier with one context
+produces a nonfatal `SINGLE_CONTEXT` diagnostic.
+
+CSS uses Terrazzo's web projection, including the `dashed` fallback for custom
+stroke patterns and separate custom properties for typography components. Colors
+and color-bearing composites are serialized with Color.js in their native space,
+which keeps alpha and avoids Terrazzo's wide-gamut fallback IDs.
+
+## Development
+
+From this package:
+
+```sh
+bun run test
+bun run build
+bun run verify:project
+```
+
+`verify:project` packs the built artifact, installs it in a temporary consumer,
+and checks the Node API, CLI, standard types, modes, provenance, and Tailwind
+output. It needs registry access. If `node` is older than 24, set
+`PROJECT_TOKENS_NODE` to a Node 24+ binary.

package/dist/authoring.d.ts

@@ -0,0 +1,42 @@
+import type { ProjectToken, TokenCompilationOptions, TokenSource } from './compilation/compiler.js';
+export declare const DTCG_TOKEN_TYPES: readonly ['color', 'dimension', 'fontFamily', 'fontWeight', 'duration', 'cubicBezier', 'number', 'strokeStyle', 'border', 'transition', 'shadow', 'gradient', 'typography'];
+export type DtcgTokenType = typeof DTCG_TOKEN_TYPES[number];
+interface TokenEditingIssue {
+    code: 'AMBIGUOUS_SOURCE' | 'COMPOSITE_TOKEN' | 'INVALID_SCOPE' | 'INVALID_SOURCE';
+    message: string;
+}
+export type TokenEditingProfile = {
+    supported: true;
+    defaultMode: string;
+    baseFile: string;
+    /** Null contexts inherit the base and receive a file on their first edit. */
+    modeFiles: Record<string, string | null>;
+} | {
+    supported: false;
+    reason: TokenEditingIssue;
+};
+export interface TokenAuthoring {
+    /** Original source properties, including unresolved aliases, pointers and vendor extensions. */
+    definition: Record<string, unknown>;
+    inheritance: 'base' | 'inherited' | 'override' | null;
+    canReset: boolean;
+    /** Eligibility for the simple value editor; mutations still validate the complete candidate. */
+    readOnlyReason: TokenEditingIssue | null;
+}
+export interface TokenGroup {
+    /** Empty path identifies the document root; other paths encode the group hierarchy. */
+    path: string;
+    source: TokenSource | null;
+    /** Metadata authored at source; effective inherited fields are reported separately. */
+    definition: Record<string, unknown>;
+    type?: DtcgTokenType;
+    description?: string;
+    deprecated: boolean | string;
+}
+/** The same structural editing boundary is used by authoring reads and mutations. */
+export declare function getTokenEditingProfile(options: TokenCompilationOptions, documents: ReadonlyMap<string, Record<string, any>>): TokenEditingProfile;
+export declare function readTokenDefinition({ file, pointer }: TokenSource, documents: ReadonlyMap<string, Record<string, any>>): Record<string, any>;
+/** Read source facts without converting an alias or a composite into its resolved value. */
+export declare function describeTokenAuthoring(token: ProjectToken, documents: ReadonlyMap<string, Record<string, any>>, mode: string | undefined, profile: TokenEditingProfile): TokenAuthoring;
+export {};
+//# sourceMappingURL=authoring.d.ts.map

package/dist/authoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring.d.ts","sourceRoot":"","sources":["../src/authoring.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAEpG,eAAO,MAAM,gBAAgB,YACzB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAC3E,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,CAC7E,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAE5D,UAAU,iBAAiB;IACvB,IAAI,EAAE,kBAAkB,GAAG,iBAAiB,GAAG,eAAe,GAAG,gBAAgB,CAAC;IAClF,OAAO,EAAE,MAAM,CAAC;CACnB;AAOD,MAAM,MAAM,mBAAmB,GAAG;IAC9B,SAAS,EAAE,IAAI,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CAC5C,GAAG;IACA,SAAS,EAAE,KAAK,CAAC;IACjB,MAAM,EAAE,iBAAiB,CAAC;CAC7B,CAAC;AAEF,MAAM,WAAW,cAAc;IAC3B,gGAAgG;IAChG,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,WAAW,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,IAAI,CAAC;IACtD,QAAQ,EAAE,OAAO,CAAC;IAClB,gGAAgG;IAChG,cAAc,EAAE,iBAAiB,GAAG,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,UAAU;IACvB,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,uFAAuF;IACvF,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,OAAO,GAAG,MAAM,CAAC;CAChC;AAcD,qFAAqF;AACrF,wBAAgB,sBAAsB,CAClC,OAAO,EAAE,uBAAuB,EAChC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GACpD,mBAAmB,CAyDrB;AAED,wBAAgB,mBAAmB,CAC/B,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,WAAW,EAC9B,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GACpD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAErB;AAED,4FAA4F;AAC5F,wBAAgB,sBAAsB,CAClC,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,EACnD,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,OAAO,EAAE,mBAAmB,GAC7B,cAAc,CAuBhB"}

package/dist/authoring.js

@@ -0,0 +1,161 @@
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { decodeJsonPointer, encodeJsonPointer, readJsonPointer } from './json-pointer.js';
+export const DTCG_TOKEN_TYPES = [
+    'color', 'dimension', 'fontFamily', 'fontWeight', 'duration', 'cubicBezier',
+    'number', 'strokeStyle', 'border', 'transition', 'shadow', 'gradient', 'typography',
+];
+const SIMPLE_EDITABLE_TYPES = new Set([
+    'color',
+    'cubicBezier',
+    'dimension',
+    'duration',
+    'fontFamily',
+    'fontWeight',
+    'number',
+]);
+const AMBIGUOUS_SOURCE_MESSAGE = 'Structured editing requires one base set followed by one mode modifier, with independent local documents and an empty default context. Edit this layout in JSON.';
+/** The same structural editing boundary is used by authoring reads and mutations. */
+export function getTokenEditingProfile(options, documents) {
+    const workspaceRoot = resolve(options.workspaceRoot);
+    const entryPath = resolve(workspaceRoot, options.entry ?? '.reforma/tokens/tokens.resolver.json');
+    const entryFile = relative(workspaceRoot, entryPath).split(sep).join('/');
+    const resolver = documents.get(entryFile);
+    if (!resolver || resolver.resolutionOrder?.length !== 2) {
+        return unsupportedEditingProfile();
+    }
+    const base = resolveResolverItem(resolver, resolver.resolutionOrder[0], 'sets');
+    const mode = resolveResolverItem(resolver, resolver.resolutionOrder[1], 'modifiers');
+    if (!isEditableModeItem(mode)) {
+        return unsupportedEditingProfile();
+    }
+    const readSourceFile = (sources) => readSingleLocalSource(sources, entryPath, workspaceRoot, documents);
+    const baseFile = readSourceFile(base.item?.sources);
+    if (baseFile === null) {
+        return unsupportedEditingProfile();
+    }
+    const modeFiles = Object.create(null);
+    for (const [name, sources] of Object.entries(mode.item.contexts)) {
+        if (!Array.isArray(sources)) {
+            return unsupportedEditingProfile();
+        }
+        const file = sources.length > 0 ? readSourceFile(sources) : null;
+        if (sources.length > 0 && file === null) {
+            return unsupportedEditingProfile();
+        }
+        modeFiles[name] = name === mode.item.default ? baseFile : file;
+    }
+    const sourceFiles = Object.values(modeFiles).filter(file => file !== null);
+    if (new Set(sourceFiles).size !== sourceFiles.length) {
+        return unsupportedEditingProfile();
+    }
+    return {
+        supported: true,
+        defaultMode: mode.item.default,
+        baseFile,
+        modeFiles,
+    };
+}
+export function readTokenDefinition({ file, pointer }, documents) {
+    return readJsonPointer(documents.get(file), decodeJsonPointer(pointer));
+}
+/** Read source facts without converting an alias or a composite into its resolved value. */
+export function describeTokenAuthoring(token, documents, mode, profile) {
+    const sourcePointer = encodeJsonPointer(token.path.split('.'));
+    let readOnlyReason = getSourceEditingIssue(token, sourcePointer, profile);
+    let inheritance = null;
+    if (profile.supported && readOnlyReason === null) {
+        inheritance = getInheritance(token, mode, profile);
+        readOnlyReason = getParentEditingIssue(token, mode, documents, profile);
+    }
+    if (readOnlyReason === null && !SIMPLE_EDITABLE_TYPES.has(token.type)) {
+        readOnlyReason = {
+            code: 'COMPOSITE_TOKEN',
+            message: 'Inspect this token here and edit its structured value in JSON.',
+        };
+    }
+    return {
+        definition: readTokenDefinition(token.source, documents),
+        inheritance,
+        canReset: readOnlyReason === null && inheritance === 'override',
+        readOnlyReason,
+    };
+}
+function unsupportedEditingProfile() {
+    return {
+        supported: false,
+        reason: {
+            code: 'AMBIGUOUS_SOURCE',
+            message: AMBIGUOUS_SOURCE_MESSAGE,
+        },
+    };
+}
+function resolveResolverItem(resolver, item, section) {
+    const sectionReference = `#/${section}/`;
+    const isDirectReference = typeof item?.$ref === 'string'
+        && Object.keys(item).length === 1
+        && item.$ref.startsWith(sectionReference);
+    if (!isDirectReference) {
+        return { item, name: item?.name };
+    }
+    const name = decodeJsonPointer(item.$ref)[1];
+    return { item: resolver[section]?.[name], name };
+}
+function isEditableModeItem(mode) {
+    return mode.name === 'mode'
+        && mode.item?.contexts
+        && typeof mode.item.default === 'string'
+        && mode.item.contexts[mode.item.default]?.length === 0;
+}
+function readSingleLocalSource(sources, entryPath, workspaceRoot, documents) {
+    if (!Array.isArray(sources)
+        || sources.length !== 1
+        || !sources[0]
+        || typeof sources[0] !== 'object'
+        || Object.keys(sources[0]).length !== 1
+        || typeof sources[0].$ref !== 'string') {
+        return null;
+    }
+    const sourceUrl = new URL(sources[0].$ref, pathToFileURL(entryPath));
+    if (sourceUrl.protocol !== 'file:' || sourceUrl.host || sourceUrl.hash || sourceUrl.search) {
+        return null;
+    }
+    const file = relative(workspaceRoot, fileURLToPath(sourceUrl)).split(sep).join('/');
+    if (isAbsolute(file) || file.startsWith('../') || !documents.has(file)) {
+        return null;
+    }
+    return file;
+}
+function getSourceEditingIssue(token, expectedPointer, profile) {
+    if (!profile.supported) {
+        return profile.reason;
+    }
+    const knownSource = Object.values(profile.modeFiles).includes(token.source.file);
+    if (token.source.pointer === expectedPointer && knownSource) {
+        return null;
+    }
+    return {
+        code: 'AMBIGUOUS_SOURCE',
+        message: 'This token is supplied through group inheritance or a shared source. Edit its definition in JSON.',
+    };
+}
+function getInheritance(token, mode, profile) {
+    if (mode === profile.defaultMode) {
+        return 'base';
+    }
+    return token.source.file === profile.baseFile ? 'inherited' : 'override';
+}
+function getParentEditingIssue(token, mode, documents, profile) {
+    const modeFile = mode ? profile.modeFiles[mode] : null;
+    let parent = modeFile ? documents.get(modeFile) : undefined;
+    for (const part of token.path.split('.').slice(0, -1)) {
+        parent = parent?.[part];
+        if (parent && ('$value' in parent || '$extends' in parent)) {
+            return {
+                code: 'AMBIGUOUS_SOURCE',
+                message: 'The mode source contains an inherited group at this path. Edit its definition in JSON.',
+            };
+        }
+    }
+    return null;
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { realpath } from 'node:fs/promises';
+import { constants } from 'node:os';
+import { resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { parseArgs } from 'node:util';
+import { compileProjectTokens } from './compilation/compiler.js';
+import { buildProjectTokens, readTokenDependency } from './generation.js';
+function report(result) {
+    for (const diagnostic of result.diagnostics)
+        process.stderr.write(`${JSON.stringify(diagnostic)}\n`);
+    if (result.ok)
+        process.stdout.write(`${JSON.stringify({ status: 'ready', revision: result.revision })}\n`);
+    else
+        process.stderr.write(`${JSON.stringify({ status: 'stale', revision: result.revision })}\n`);
+}
+async function watch(options, command) {
+    let stopped = false;
+    let exitCode = 0;
+    let child;
+    let childDone;
+    const signalChild = (signal) => {
+        if (!child?.pid)
+            return;
+        try {
+            if (process.platform === 'win32')
+                child.kill(signal);
+            else
+                process.kill(-child.pid, signal);
+        }
+        catch (error) {
+            if (error.code !== 'ESRCH')
+                throw error;
+        }
+    };
+    const stop = (signal) => {
+        stopped = true;
+        exitCode = 128 + constants.signals[signal];
+        signalChild(signal);
+    };
+    const onTerm = () => stop('SIGTERM');
+    const onInt = () => stop('SIGINT');
+    process.on('SIGTERM', onTerm);
+    process.on('SIGINT', onInt);
+    try {
+        let dependencies = new Map();
+        let dirty = true;
+        let first = true;
+        // One queue for initial compilation and edits; hash polling also catches atomic saves and checkout.
+        while (!stopped) {
+            if (dirty) {
+                const result = await buildProjectTokens(options);
+                report(result);
+                if (result.ok)
+                    dependencies.clear();
+                for (const file of result.dependencies)
+                    dependencies.set(file.path, file.hash);
+                if (first && command.length) {
+                    if (!result.ok) {
+                        exitCode = 1;
+                        break;
+                    }
+                    if (stopped)
+                        break;
+                    child = spawn(command[0], command.slice(1), { cwd: options.workspaceRoot, stdio: 'inherit', detached: process.platform !== 'win32' });
+                    childDone = new Promise((done) => {
+                        child.once('error', (error) => {
+                            process.stderr.write(`${JSON.stringify({ severity: 'error', code: 'DEV_COMMAND', message: error.message })}\n`);
+                            exitCode = 1;
+                            stopped = true;
+                            done();
+                        });
+                        child.once('exit', (code, signal) => {
+                            if (!stopped)
+                                exitCode = code ?? (signal ? 128 + constants.signals[signal] : 1);
+                            stopped = true;
+                            done();
+                        });
+                    });
+                }
+                first = false;
+                dirty = false;
+            }
+            await delay(150);
+            for (const [path, previous] of dependencies) {
+                const text = await readTokenDependency(options.workspaceRoot, path);
+                const current = text === null ? null : createHash('sha256').update(text).digest('hex');
+                if (current !== previous)
+                    dirty = true;
+            }
+        }
+    }
+    finally {
+        signalChild('SIGTERM');
+        if (childDone) {
+            const killTimer = setTimeout(() => signalChild('SIGKILL'), 2000);
+            await childDone;
+            clearTimeout(killTimer);
+            // A command can exit while leaving descendants in its process group.
+            signalChild('SIGKILL');
+        }
+        process.off('SIGTERM', onTerm);
+        process.off('SIGINT', onInt);
+    }
+    process.exitCode = exitCode;
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const separator = args.indexOf('--');
+    const childCommand = separator < 0 ? [] : args.slice(separator + 1);
+    const { values, positionals } = parseArgs({ args: separator < 0 ? args : args.slice(0, separator), allowPositionals: true, options: {
+            cwd: { type: 'string' }, entry: { type: 'string' }, context: { type: 'string', multiple: true }, help: { type: 'boolean' },
+        } });
+    const [command] = positionals;
+    if (values.help) {
+        process.stdout.write('reforma-tokens <build|check|watch|dev -- command...> [--cwd directory] [--entry resolver.json] [--context axis=value]\n');
+        return;
+    }
+    if (!['build', 'check', 'watch', 'dev'].includes(command ?? '') || positionals.length !== 1)
+        throw new Error('Expected build, check, watch or dev.');
+    if (command === 'dev' && !childCommand.length || command !== 'dev' && separator >= 0)
+        throw new Error('Use dev -- command arguments.');
+    const input = Object.create(null);
+    for (const context of values.context ?? []) {
+        const separator = context.indexOf('=');
+        if (separator < 0)
+            throw new Error('Expected --context axis=value.');
+        input[context.slice(0, separator)] = context.slice(separator + 1);
+    }
+    const options = { workspaceRoot: await realpath(resolve(values.cwd ?? process.cwd())), entry: values.entry, input };
+    if (command === 'watch' || command === 'dev')
+        return watch(options, childCommand);
+    const result = await (command === 'check' ? compileProjectTokens(options) : buildProjectTokens(options));
+    report(result);
+    process.exitCode = result.ok ? 0 : 1;
+}
+main().catch((error) => {
+    process.stderr.write(`${JSON.stringify({ severity: 'error', code: 'CLI_FAILED', message: error.message })}\n`);
+    process.exitCode = 1;
+});

package/dist/color-value.d.ts

@@ -0,0 +1,13 @@
+export type DtcgColorSpace = 'a98-rgb' | 'display-p3' | 'hsl' | 'hwb' | 'lab' | 'lch' | 'oklab' | 'oklch' | 'prophoto-rgb' | 'rec2020' | 'srgb' | 'srgb-linear' | 'xyz-d50' | 'xyz-d65';
+export type DtcgColorComponent = number | 'none';
+export interface DtcgColorValue {
+    colorSpace: DtcgColorSpace;
+    components: [DtcgColorComponent, DtcgColorComponent, DtcgColorComponent];
+    alpha?: number;
+    hex?: string;
+}
+/** Validate a complete structured color value from the final DTCG format. */
+export declare function isDtcgColorValue(value: unknown): value is DtcgColorValue;
+/** Validate a color-space identifier supported by the final DTCG format. */
+export declare function isDtcgColorSpace(value: unknown): value is DtcgColorSpace;
+//# sourceMappingURL=color-value.d.ts.map

package/dist/color-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-value.d.ts","sourceRoot":"","sources":["../src/color-value.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAClB,SAAS,GACT,YAAY,GACZ,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,OAAO,GACP,OAAO,GACP,cAAc,GACd,SAAS,GACT,MAAM,GACN,aAAa,GACb,SAAS,GACT,SAAS,CAAC;AAElB,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEjD,MAAM,WAAW,cAAc;IAC3B,UAAU,EAAE,cAAc,CAAC;IAC3B,UAAU,EAAE,CAAC,kBAAkB,EAAE,kBAAkB,EAAE,kBAAkB,CAAC,CAAC;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB;AA8BD,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAsBxE;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE"}

package/dist/color-value.js

@@ -0,0 +1,71 @@
+const COLOR_SPACES = new Set([
+    'a98-rgb',
+    'display-p3',
+    'hsl',
+    'hwb',
+    'lab',
+    'lch',
+    'oklab',
+    'oklch',
+    'prophoto-rgb',
+    'rec2020',
+    'srgb',
+    'srgb-linear',
+    'xyz-d50',
+    'xyz-d65',
+]);
+const UNIT_COLOR_SPACES = new Set([
+    'a98-rgb',
+    'display-p3',
+    'prophoto-rgb',
+    'rec2020',
+    'srgb',
+    'srgb-linear',
+    'xyz-d50',
+    'xyz-d65',
+]);
+/** Validate a complete structured color value from the final DTCG format. */
+export function isDtcgColorValue(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const color = value;
+    return Object.keys(color).every(key => ['colorSpace', 'components', 'alpha', 'hex'].includes(key))
+        && isDtcgColorSpace(color.colorSpace)
+        && Array.isArray(color.components)
+        && color.components.length === 3
+        && color.components.every((component, index) => (component === 'none'
+            || isFiniteNumber(component)
+                && isColorComponentInRange(color.colorSpace, component, index)))
+        && (color.alpha === undefined
+            || isFiniteNumber(color.alpha) && color.alpha >= 0 && color.alpha <= 1)
+        && (color.hex === undefined
+            || typeof color.hex === 'string' && /^#[\da-f]{6}$/i.test(color.hex));
+}
+/** Validate a color-space identifier supported by the final DTCG format. */
+export function isDtcgColorSpace(value) {
+    return typeof value === 'string' && COLOR_SPACES.has(value);
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function isColorComponentInRange(colorSpace, component, index) {
+    if (UNIT_COLOR_SPACES.has(colorSpace))
+        return component >= 0 && component <= 1;
+    if (colorSpace === 'hsl' || colorSpace === 'hwb') {
+        return index === 0 ? component >= 0 && component < 360 : component >= 0 && component <= 100;
+    }
+    if (colorSpace === 'lab') {
+        return index !== 0 || component >= 0 && component <= 100;
+    }
+    if (colorSpace === 'lch') {
+        return index === 0 ? component >= 0 && component <= 100
+            : index === 1 ? component >= 0
+                : component >= 0 && component < 360;
+    }
+    if (colorSpace === 'oklab') {
+        return index !== 0 || component >= 0 && component <= 1;
+    }
+    return index === 0 ? component >= 0 && component <= 1
+        : index === 1 ? component >= 0
+            : component >= 0 && component < 360;
+}