diff --git a/.changeset/acidcat-cli-mcp.md b/.changeset/acidcat-cli-mcp.md new file mode 100644 index 0000000..3e3a548 --- /dev/null +++ b/.changeset/acidcat-cli-mcp.md @@ -0,0 +1,13 @@ +--- +"@hebilicious/cssforge": minor +--- + +Rewrite the CLI, and add an MCP server and typed calls from code. + +- Commands: `cssforge tokens build`, `cssforge tokens generate`, `cssforge config check`, `cssforge watch tokens.built` and `cssforge list`. Each command answers with JSON on stdout. +- `cssforge mcp` serves the same commands to an agent as MCP tools, through stdio. +- `@hebilicious/cssforge/capabilities` gives the same commands to code, with types: `createSession(cssforge, { target: "library", … })`. +- The catalog of the commands ships as `cssforge.acidcat.json`. +- Breaking: `cssforge [flags]` without a command no longer builds; run `cssforge tokens build [flags]`. `-w`, `-m` and `--prefix` are removed: use `cssforge watch tokens.built`, `--mode` and `--root`. `--color-formats` takes one format per flag or a JSON array, not a comma separated list. +- Breaking: the output is JSON. Build warnings are in the `diagnostics` of the result instead of `cssforge: warning:` lines on stderr. An invalid flag exits with `3` instead of `1`, and an interrupted watch exits with `130`. +- Breaking: `build()`, `watch()`, `parseColorFormats()`, `writeFileRecursive()` and the default export of `@hebilicious/cssforge/cli` are removed. Call `tokens.build` through `@hebilicious/cssforge/capabilities` instead. The `citty` dependency is removed. diff --git a/README.md b/README.md index e662943..656ee7c 100644 --- a/README.md +++ b/README.md @@ -50,8 +50,8 @@ pnpm add -D @hebilicious/cssforge The package installs a `cssforge` executable: ```bash -pnpm cssforge --mode all # pnpm -npx cssforge --mode all # npm +pnpm cssforge tokens build # pnpm +npx cssforge tokens build # npm ``` The rest of this document writes commands as `cssforge `. @@ -152,9 +152,9 @@ export default defineConfig({ 2. Run CSS Forge with the CLI : ```bash -cssforge # Basic usage -cssforge --help # To see all options -cssforge --watch # To watch for changes +cssforge tokens build # Basic usage +cssforge --help # To see all commands +cssforge watch tokens.built # To watch for changes ``` 3. Use the generated variables in your CSS: @@ -258,7 +258,7 @@ cssforge({ real file, or when a bundler has no CSS handling for virtual modules. The plugin calls the same `generateCSS` implementation as the CLI, so `virtual:cssforge.css` matches -`cssforge --mode css` output byte for byte. The served stylesheet is unlayered, and +`cssforge tokens build --mode css` output byte for byte. The served stylesheet is unlayered, and `@import "virtual:cssforge.css" layer(cssforge)` does not work because a CSS import resolves to a file; set `write` and import the written file with `layer(cssforge)` to keep the tokens in a layer. The CLI stays the integration path for everything else: JSR, Style Dictionary, CI steps, and tools @@ -316,7 +316,7 @@ A level with one child is collapsed, so `palette: { value: { coral: ... } }` bec The TypeScript output is a typed module. Put it in your source tree: ```bash -cssforge --mode ts --ts ./src/design-tokens.ts +cssforge tokens build --mode ts --ts ./src/design-tokens.ts ``` ```typescript @@ -348,7 +348,7 @@ the compiler options the Quick Start documents. The JSON output is the same tree without the `as const` wrapper: ```bash -cssforge --mode json --json ./src/design-tokens.json +cssforge tokens build --mode json --json ./src/design-tokens.json ``` ```javascript @@ -1984,29 +1984,74 @@ The pow representation of a step adds a `pow` segment, as in ## CLI Usage +Each command answers with JSON on stdout. + ```bash -# Basic usage -cssforge +# Write every output of ./cssforge.config.ts +cssforge tokens build -# Watch mode -cssforge --watch +# Watch mode: build now, then after each change of the config or a module it imports. +# Each build is one JSON line. +cssforge watch tokens.built # Custom paths and output -cssforge --config ./foo/bar/custom-path.ts --css ./dist/design-tokens.css --ts ./dist/design-tokens.ts --json ./dist/design-tokens.json --style-dictionary ./dist/design-tokens.sd.json --mode all +cssforge tokens build --config ./foo/bar/custom-path.ts --css ./dist/design-tokens.css --ts ./dist/design-tokens.ts --json ./dist/design-tokens.json --style-dictionary ./dist/design-tokens.sd.json --mode all + +# Resolve the relative paths against another directory +cssforge tokens build --root ./site # Style Dictionary JSON with final values (default) -cssforge --mode style-dictionary --style-dictionary ./dist/design-tokens.sd.json +cssforge tokens build --mode style-dictionary --style-dictionary ./dist/design-tokens.sd.json # Keep CSS variables as values for usage matching -cssforge --mode style-dictionary --style-dictionary ./dist/design-tokens.sd.json --style-dictionary-value-mode css-reference +cssforge tokens build --mode style-dictionary --style-dictionary ./dist/design-tokens.sd.json --style-dictionary-value-mode css-reference + +# Generate sRGB formats next to oklch for every palette color, added to the config's formats. +# Repeat the flag, or give a JSON array. +cssforge tokens build --color-formats hex --color-formats rgb + +# Print one output without writing a file +cssforge tokens generate --format css + +# Validate a config and list its warnings +cssforge config check -# Generate sRGB formats next to oklch for every palette color, added to the config's formats -cssforge --color-formats hex,rgb +# Every command, with its flags +cssforge list ``` -Build warnings, such as a fluid type step below the legibility floor, are printed to stderr -before the outputs are written, one line each as `cssforge: warning: `. They do not -fail the build: the outputs are still written and the exit code stays `0`. +| Command | Result on stdout | +| --- | --- | +| `tokens build` | `{ files, diagnostics, dependencies }`: the files written, the warnings and the files the config loaded | +| `tokens generate` | `{ format, content, diagnostics, dependencies }` | +| `config check` | `{ diagnostics, dependencies }` | +| `watch tokens.built` | One line per build: `{ data: { ok: true, files, … } }`, or `{ data: { ok: false, failure } }` | + +Build warnings, such as a fluid type step below the legibility floor, are the `diagnostics` of +the result. They do not fail the build: the outputs are still written and the exit code stays +`0`. A failure is a JSON object with a `_tag` and exit code `1`: `ConfigLoadFailed` (the +config is missing or cannot be evaluated), `InvalidConfig` (CSS Forge rejects a value) or +`WriteFailed`. An invalid flag exits with `3` and a message on stderr. An interrupted watch +exits with `130`. + +Code can make the same calls with types, through `@hebilicious/cssforge/capabilities`: + +```typescript +import { + createSession, + cssforge, + tokensBuild, + toJsonSchema, +} from "@hebilicious/cssforge/capabilities"; + +await using session = createSession(cssforge, { + target: "library", + context: { cwd: process.cwd() }, + toJsonSchema, +}); +const result = await session.call(tokensBuild, { mode: "css" }); +if (!result.ok) console.error(result.error._tag, result.error.message); +``` ## Programmatic Usage @@ -2060,7 +2105,7 @@ you already generate. Use `style-dictionary` mode to generate only the token file: ```bash -cssforge --mode style-dictionary --style-dictionary ./.cssforge/tokens.json +cssforge tokens build --mode style-dictionary --style-dictionary ./.cssforge/tokens.json ``` Use `--mode all` to generate it together with the CSS, TypeScript, and regular JSON outputs. @@ -2135,7 +2180,7 @@ Dictionary will transform the file. ```bash # Keep CSS variables as values for usage matching -cssforge --mode style-dictionary --style-dictionary ./.cssforge/tokens.json --style-dictionary-value-mode css-reference +cssforge tokens build --mode style-dictionary --style-dictionary ./.cssforge/tokens.json --style-dictionary-value-mode css-reference ``` ### Programmatic API @@ -2167,9 +2212,19 @@ lets Musea attribute a `var(--token)` written in an art file back to its token. ## Agentic usage -CSSForge is intentionally designed to be extremely simple and integrate well with various -agents, such as Github Copilot, Gemini, Claude Code ... While there's no documentation -yet, you can add the README file to the agent context directly. +Agents can run the `cssforge` CLI like any other command: each command answers with JSON, and +`cssforge list` describes every command and its flags. + +`cssforge mcp` serves the same commands as MCP tools, through standard input and output: +`tokens.build`, `tokens.generate` and `config.check`, and the event `tokens.built`. Paths +resolve against the directory where the agent starts the server, or against the `root` of a +call. To add it to Claude Code: + +```bash +claude mcp add cssforge -- npx cssforge mcp +``` + +You can also add the README file to the agent context directly. For most agents, this syntax works `@https://raw.githubusercontent.com/Hebilicious/cssforge/refs/heads/main/README.md`. diff --git a/example/tailwind-nextjs/moon.yml b/example/tailwind-nextjs/moon.yml index 05c05c5..d31b939 100644 --- a/example/tailwind-nextjs/moon.yml +++ b/example/tailwind-nextjs/moon.yml @@ -50,8 +50,8 @@ tasks: command: "node" args: - "../../packages/cssforge/dist/cli.js" - - "--prefix" - - "." + - "tokens" + - "build" - "--config" - "./cssforge.config.ts" - "--mode" diff --git a/example/tailwind-nuxt/moon.yml b/example/tailwind-nuxt/moon.yml index e405951..970ac67 100644 --- a/example/tailwind-nuxt/moon.yml +++ b/example/tailwind-nuxt/moon.yml @@ -63,8 +63,8 @@ tasks: command: "node" args: - "../../packages/cssforge/dist/cli.js" - - "--prefix" - - "." + - "tokens" + - "build" - "--config" - "./cssforge.config.ts" - "--mode" diff --git a/example/tailwind-solidstart/moon.yml b/example/tailwind-solidstart/moon.yml index 60a5f8f..f9aa982 100644 --- a/example/tailwind-solidstart/moon.yml +++ b/example/tailwind-solidstart/moon.yml @@ -45,8 +45,8 @@ tasks: command: "node" args: - "../../packages/cssforge/dist/cli.js" - - "--prefix" - - "." + - "tokens" + - "build" - "--config" - "./cssforge.config.ts" - "--mode" diff --git a/example/tailwind-sveltekit/moon.yml b/example/tailwind-sveltekit/moon.yml index 65b9d96..83aea40 100644 --- a/example/tailwind-sveltekit/moon.yml +++ b/example/tailwind-sveltekit/moon.yml @@ -68,8 +68,8 @@ tasks: command: "node" args: - "../../packages/cssforge/dist/cli.js" - - "--prefix" - - "." + - "tokens" + - "build" - "--config" - "./cssforge.config.ts" - "--mode" diff --git a/example/vanilla-solid-css/moon.yml b/example/vanilla-solid-css/moon.yml index f6d43d0..58de56d 100644 --- a/example/vanilla-solid-css/moon.yml +++ b/example/vanilla-solid-css/moon.yml @@ -43,8 +43,8 @@ tasks: command: "node" args: - "../../packages/cssforge/dist/cli.js" - - "--prefix" - - "." + - "tokens" + - "build" - "--config" - "./cssforge.config.ts" - "--mode" diff --git a/example/vanilla-svelte-css/moon.yml b/example/vanilla-svelte-css/moon.yml index af4b940..15e378a 100644 --- a/example/vanilla-svelte-css/moon.yml +++ b/example/vanilla-svelte-css/moon.yml @@ -48,8 +48,8 @@ tasks: command: "node" args: - "../../packages/cssforge/dist/cli.js" - - "--prefix" - - "." + - "tokens" + - "build" - "--config" - "./cssforge.config.ts" - "--mode" diff --git a/example/vanilla-vue-css/moon.yml b/example/vanilla-vue-css/moon.yml index bc00bf6..f1d4196 100644 --- a/example/vanilla-vue-css/moon.yml +++ b/example/vanilla-vue-css/moon.yml @@ -43,8 +43,8 @@ tasks: command: "node" args: - "../../packages/cssforge/dist/cli.js" - - "--prefix" - - "." + - "tokens" + - "build" - "--config" - "./cssforge.config.ts" - "--mode" diff --git a/packages/cssforge/README.md b/packages/cssforge/README.md index e662943..656ee7c 100644 --- a/packages/cssforge/README.md +++ b/packages/cssforge/README.md @@ -50,8 +50,8 @@ pnpm add -D @hebilicious/cssforge The package installs a `cssforge` executable: ```bash -pnpm cssforge --mode all # pnpm -npx cssforge --mode all # npm +pnpm cssforge tokens build # pnpm +npx cssforge tokens build # npm ``` The rest of this document writes commands as `cssforge `. @@ -152,9 +152,9 @@ export default defineConfig({ 2. Run CSS Forge with the CLI : ```bash -cssforge # Basic usage -cssforge --help # To see all options -cssforge --watch # To watch for changes +cssforge tokens build # Basic usage +cssforge --help # To see all commands +cssforge watch tokens.built # To watch for changes ``` 3. Use the generated variables in your CSS: @@ -258,7 +258,7 @@ cssforge({ real file, or when a bundler has no CSS handling for virtual modules. The plugin calls the same `generateCSS` implementation as the CLI, so `virtual:cssforge.css` matches -`cssforge --mode css` output byte for byte. The served stylesheet is unlayered, and +`cssforge tokens build --mode css` output byte for byte. The served stylesheet is unlayered, and `@import "virtual:cssforge.css" layer(cssforge)` does not work because a CSS import resolves to a file; set `write` and import the written file with `layer(cssforge)` to keep the tokens in a layer. The CLI stays the integration path for everything else: JSR, Style Dictionary, CI steps, and tools @@ -316,7 +316,7 @@ A level with one child is collapsed, so `palette: { value: { coral: ... } }` bec The TypeScript output is a typed module. Put it in your source tree: ```bash -cssforge --mode ts --ts ./src/design-tokens.ts +cssforge tokens build --mode ts --ts ./src/design-tokens.ts ``` ```typescript @@ -348,7 +348,7 @@ the compiler options the Quick Start documents. The JSON output is the same tree without the `as const` wrapper: ```bash -cssforge --mode json --json ./src/design-tokens.json +cssforge tokens build --mode json --json ./src/design-tokens.json ``` ```javascript @@ -1984,29 +1984,74 @@ The pow representation of a step adds a `pow` segment, as in ## CLI Usage +Each command answers with JSON on stdout. + ```bash -# Basic usage -cssforge +# Write every output of ./cssforge.config.ts +cssforge tokens build -# Watch mode -cssforge --watch +# Watch mode: build now, then after each change of the config or a module it imports. +# Each build is one JSON line. +cssforge watch tokens.built # Custom paths and output -cssforge --config ./foo/bar/custom-path.ts --css ./dist/design-tokens.css --ts ./dist/design-tokens.ts --json ./dist/design-tokens.json --style-dictionary ./dist/design-tokens.sd.json --mode all +cssforge tokens build --config ./foo/bar/custom-path.ts --css ./dist/design-tokens.css --ts ./dist/design-tokens.ts --json ./dist/design-tokens.json --style-dictionary ./dist/design-tokens.sd.json --mode all + +# Resolve the relative paths against another directory +cssforge tokens build --root ./site # Style Dictionary JSON with final values (default) -cssforge --mode style-dictionary --style-dictionary ./dist/design-tokens.sd.json +cssforge tokens build --mode style-dictionary --style-dictionary ./dist/design-tokens.sd.json # Keep CSS variables as values for usage matching -cssforge --mode style-dictionary --style-dictionary ./dist/design-tokens.sd.json --style-dictionary-value-mode css-reference +cssforge tokens build --mode style-dictionary --style-dictionary ./dist/design-tokens.sd.json --style-dictionary-value-mode css-reference + +# Generate sRGB formats next to oklch for every palette color, added to the config's formats. +# Repeat the flag, or give a JSON array. +cssforge tokens build --color-formats hex --color-formats rgb + +# Print one output without writing a file +cssforge tokens generate --format css + +# Validate a config and list its warnings +cssforge config check -# Generate sRGB formats next to oklch for every palette color, added to the config's formats -cssforge --color-formats hex,rgb +# Every command, with its flags +cssforge list ``` -Build warnings, such as a fluid type step below the legibility floor, are printed to stderr -before the outputs are written, one line each as `cssforge: warning: `. They do not -fail the build: the outputs are still written and the exit code stays `0`. +| Command | Result on stdout | +| --- | --- | +| `tokens build` | `{ files, diagnostics, dependencies }`: the files written, the warnings and the files the config loaded | +| `tokens generate` | `{ format, content, diagnostics, dependencies }` | +| `config check` | `{ diagnostics, dependencies }` | +| `watch tokens.built` | One line per build: `{ data: { ok: true, files, … } }`, or `{ data: { ok: false, failure } }` | + +Build warnings, such as a fluid type step below the legibility floor, are the `diagnostics` of +the result. They do not fail the build: the outputs are still written and the exit code stays +`0`. A failure is a JSON object with a `_tag` and exit code `1`: `ConfigLoadFailed` (the +config is missing or cannot be evaluated), `InvalidConfig` (CSS Forge rejects a value) or +`WriteFailed`. An invalid flag exits with `3` and a message on stderr. An interrupted watch +exits with `130`. + +Code can make the same calls with types, through `@hebilicious/cssforge/capabilities`: + +```typescript +import { + createSession, + cssforge, + tokensBuild, + toJsonSchema, +} from "@hebilicious/cssforge/capabilities"; + +await using session = createSession(cssforge, { + target: "library", + context: { cwd: process.cwd() }, + toJsonSchema, +}); +const result = await session.call(tokensBuild, { mode: "css" }); +if (!result.ok) console.error(result.error._tag, result.error.message); +``` ## Programmatic Usage @@ -2060,7 +2105,7 @@ you already generate. Use `style-dictionary` mode to generate only the token file: ```bash -cssforge --mode style-dictionary --style-dictionary ./.cssforge/tokens.json +cssforge tokens build --mode style-dictionary --style-dictionary ./.cssforge/tokens.json ``` Use `--mode all` to generate it together with the CSS, TypeScript, and regular JSON outputs. @@ -2135,7 +2180,7 @@ Dictionary will transform the file. ```bash # Keep CSS variables as values for usage matching -cssforge --mode style-dictionary --style-dictionary ./.cssforge/tokens.json --style-dictionary-value-mode css-reference +cssforge tokens build --mode style-dictionary --style-dictionary ./.cssforge/tokens.json --style-dictionary-value-mode css-reference ``` ### Programmatic API @@ -2167,9 +2212,19 @@ lets Musea attribute a `var(--token)` written in an art file back to its token. ## Agentic usage -CSSForge is intentionally designed to be extremely simple and integrate well with various -agents, such as Github Copilot, Gemini, Claude Code ... While there's no documentation -yet, you can add the README file to the agent context directly. +Agents can run the `cssforge` CLI like any other command: each command answers with JSON, and +`cssforge list` describes every command and its flags. + +`cssforge mcp` serves the same commands as MCP tools, through standard input and output: +`tokens.build`, `tokens.generate` and `config.check`, and the event `tokens.built`. Paths +resolve against the directory where the agent starts the server, or against the `root` of a +call. To add it to Claude Code: + +```bash +claude mcp add cssforge -- npx cssforge mcp +``` + +You can also add the README file to the agent context directly. For most agents, this syntax works `@https://raw.githubusercontent.com/Hebilicious/cssforge/refs/heads/main/README.md`. diff --git a/packages/cssforge/cssforge.acidcat.json b/packages/cssforge/cssforge.acidcat.json new file mode 100644 index 0000000..93f7fa7 --- /dev/null +++ b/packages/cssforge/cssforge.acidcat.json @@ -0,0 +1,752 @@ +{ + "acidcat": "0.1", + "title": "CSS Forge", + "description": "Generate CSS custom properties, JSON, TypeScript and Style Dictionary tokens from a CSS Forge configuration.", + "targets": { + "cli": { + "bindings": [ + "cli" + ], + "description": "The cssforge command line." + }, + "library": { + "bindings": [ + "typescript" + ], + "description": "Typed calls from code, through @hebilicious/cssforge/capabilities." + }, + "mcp": { + "bindings": [ + "mcp" + ], + "description": "The MCP server of `cssforge mcp`, for agents." + } + }, + "capabilities": { + "config.check": { + "description": "Load and validate a CSS Forge configuration, and give its warnings: values that generate, but likely not as intended. Writes no file.", + "audience": [ + "cli", + "mcp", + "library" + ], + "input": { + "additionalProperties": false, + "properties": { + "color-formats": { + "default": [], + "description": "Extra color formats generated beside oklch(), added to the formats that the configuration declares.", + "items": { + "enum": [ + "hex", + "rgb" + ], + "type": "string" + }, + "type": "array", + "uniqueItems": true + }, + "config": { + "default": "./cssforge.config.ts", + "description": "The path of the configuration file.", + "minLength": 1, + "type": "string" + }, + "root": { + "description": "The directory that the relative paths of the input resolve against. The default is the working directory of the tools.", + "minLength": 1, + "type": "string" + } + }, + "required": [], + "type": "object" + }, + "output": { + "additionalProperties": false, + "properties": { + "dependencies": { + "description": "The absolute paths of the configuration and the local modules it imports.", + "items": { + "type": "string" + }, + "type": "array" + }, + "diagnostics": { + "items": { + "additionalProperties": false, + "description": "A warning about a value that generates, but likely not as intended.", + "properties": { + "code": { + "description": "A stable identifier of the warning.", + "type": "string" + }, + "message": { + "description": "What is wrong, and how to fix it.", + "type": "string" + }, + "path": { + "description": "The configuration path of the value.", + "type": "string" + }, + "severity": { + "enum": [ + "warning" + ], + "type": "string" + } + }, + "required": [ + "code", + "severity", + "path", + "message" + ], + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "diagnostics", + "dependencies" + ], + "type": "object" + }, + "failures": { + "ConfigLoadFailed": { + "additionalProperties": false, + "properties": { + "_tag": { + "const": "ConfigLoadFailed", + "description": "The configuration file could not be found or evaluated, or it has no default export object." + }, + "message": { + "type": "string" + }, + "path": { + "description": "The file that the failure concerns.", + "type": "string" + } + }, + "required": [ + "_tag", + "message" + ], + "type": "object" + }, + "InvalidConfig": { + "additionalProperties": false, + "properties": { + "_tag": { + "const": "InvalidConfig", + "description": "The configuration loaded, but CSS Forge rejects a value in it." + }, + "message": { + "type": "string" + }, + "path": { + "description": "The file that the failure concerns.", + "type": "string" + } + }, + "required": [ + "_tag", + "message" + ], + "type": "object" + } + }, + "readOnly": true + }, + "tokens.build": { + "description": "Generate the outputs of a CSS Forge configuration and write them to files: CSS custom properties, JSON, TypeScript and Style Dictionary tokens. Every output is generated before the first file is written, so an invalid configuration leaves the previous files in place. The result lists the files written and the warnings of the configuration.", + "audience": [ + "cli", + "mcp", + "library" + ], + "input": { + "additionalProperties": false, + "properties": { + "color-formats": { + "default": [], + "description": "Extra color formats generated beside oklch(), added to the formats that the configuration declares.", + "items": { + "enum": [ + "hex", + "rgb" + ], + "type": "string" + }, + "type": "array", + "uniqueItems": true + }, + "config": { + "default": "./cssforge.config.ts", + "description": "The path of the configuration file.", + "minLength": 1, + "type": "string" + }, + "css": { + "default": "./.cssforge/output.css", + "description": "The path of the CSS file.", + "minLength": 1, + "type": "string" + }, + "json": { + "default": "./.cssforge/output.json", + "description": "The path of the JSON file.", + "minLength": 1, + "type": "string" + }, + "mode": { + "default": "all", + "description": "The output to write: one format, or all of them.", + "enum": [ + "css", + "json", + "ts", + "style-dictionary", + "all" + ], + "type": "string" + }, + "root": { + "description": "The directory that the relative paths of the input resolve against. The default is the working directory of the tools.", + "minLength": 1, + "type": "string" + }, + "style-dictionary": { + "default": "./.cssforge/tokens.sd.json", + "description": "The path of the Style Dictionary token JSON file.", + "minLength": 1, + "type": "string" + }, + "style-dictionary-value-mode": { + "default": "resolved", + "description": "How the Style Dictionary output writes values: css-reference for usage matching, resolved for previews and builds.", + "enum": [ + "css-reference", + "resolved" + ], + "type": "string" + }, + "ts": { + "default": "./.cssforge/output.ts", + "description": "The path of the TypeScript file.", + "minLength": 1, + "type": "string" + } + }, + "required": [], + "type": "object" + }, + "output": { + "additionalProperties": false, + "properties": { + "dependencies": { + "description": "The absolute paths of the configuration and the local modules it imports.", + "items": { + "type": "string" + }, + "type": "array" + }, + "diagnostics": { + "items": { + "additionalProperties": false, + "description": "A warning about a value that generates, but likely not as intended.", + "properties": { + "code": { + "description": "A stable identifier of the warning.", + "type": "string" + }, + "message": { + "description": "What is wrong, and how to fix it.", + "type": "string" + }, + "path": { + "description": "The configuration path of the value.", + "type": "string" + }, + "severity": { + "enum": [ + "warning" + ], + "type": "string" + } + }, + "required": [ + "code", + "severity", + "path", + "message" + ], + "type": "object" + }, + "type": "array" + }, + "files": { + "description": "The files written.", + "items": { + "additionalProperties": false, + "properties": { + "format": { + "enum": [ + "css", + "json", + "ts", + "style-dictionary" + ], + "type": "string" + }, + "path": { + "description": "The absolute path of the file.", + "type": "string" + } + }, + "required": [ + "format", + "path" + ], + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "files", + "diagnostics", + "dependencies" + ], + "type": "object" + }, + "failures": { + "ConfigLoadFailed": { + "additionalProperties": false, + "properties": { + "_tag": { + "const": "ConfigLoadFailed", + "description": "The configuration file could not be found or evaluated, or it has no default export object." + }, + "message": { + "type": "string" + }, + "path": { + "description": "The file that the failure concerns.", + "type": "string" + } + }, + "required": [ + "_tag", + "message" + ], + "type": "object" + }, + "InvalidConfig": { + "additionalProperties": false, + "properties": { + "_tag": { + "const": "InvalidConfig", + "description": "The configuration loaded, but CSS Forge rejects a value in it." + }, + "message": { + "type": "string" + }, + "path": { + "description": "The file that the failure concerns.", + "type": "string" + } + }, + "required": [ + "_tag", + "message" + ], + "type": "object" + }, + "WriteFailed": { + "additionalProperties": false, + "properties": { + "_tag": { + "const": "WriteFailed", + "description": "An output file could not be written." + }, + "message": { + "type": "string" + }, + "path": { + "description": "The file that the failure concerns.", + "type": "string" + } + }, + "required": [ + "_tag", + "message" + ], + "type": "object" + } + } + }, + "tokens.generate": { + "description": "Generate one output of a CSS Forge configuration and give it as text, with the warnings of the configuration. Writes no file.", + "audience": [ + "cli", + "mcp", + "library" + ], + "input": { + "additionalProperties": false, + "properties": { + "color-formats": { + "default": [], + "description": "Extra color formats generated beside oklch(), added to the formats that the configuration declares.", + "items": { + "enum": [ + "hex", + "rgb" + ], + "type": "string" + }, + "type": "array", + "uniqueItems": true + }, + "config": { + "default": "./cssforge.config.ts", + "description": "The path of the configuration file.", + "minLength": 1, + "type": "string" + }, + "format": { + "default": "css", + "description": "The output to generate.", + "enum": [ + "css", + "json", + "ts", + "style-dictionary" + ], + "type": "string" + }, + "root": { + "description": "The directory that the relative paths of the input resolve against. The default is the working directory of the tools.", + "minLength": 1, + "type": "string" + }, + "style-dictionary-value-mode": { + "default": "resolved", + "description": "How the Style Dictionary output writes values: css-reference for usage matching, resolved for previews and builds.", + "enum": [ + "css-reference", + "resolved" + ], + "type": "string" + } + }, + "required": [], + "type": "object" + }, + "output": { + "additionalProperties": false, + "properties": { + "content": { + "description": "The generated file content.", + "type": "string" + }, + "dependencies": { + "description": "The absolute paths of the configuration and the local modules it imports.", + "items": { + "type": "string" + }, + "type": "array" + }, + "diagnostics": { + "items": { + "additionalProperties": false, + "description": "A warning about a value that generates, but likely not as intended.", + "properties": { + "code": { + "description": "A stable identifier of the warning.", + "type": "string" + }, + "message": { + "description": "What is wrong, and how to fix it.", + "type": "string" + }, + "path": { + "description": "The configuration path of the value.", + "type": "string" + }, + "severity": { + "enum": [ + "warning" + ], + "type": "string" + } + }, + "required": [ + "code", + "severity", + "path", + "message" + ], + "type": "object" + }, + "type": "array" + }, + "format": { + "enum": [ + "css", + "json", + "ts", + "style-dictionary" + ], + "type": "string" + } + }, + "required": [ + "format", + "content", + "diagnostics", + "dependencies" + ], + "type": "object" + }, + "failures": { + "ConfigLoadFailed": { + "additionalProperties": false, + "properties": { + "_tag": { + "const": "ConfigLoadFailed", + "description": "The configuration file could not be found or evaluated, or it has no default export object." + }, + "message": { + "type": "string" + }, + "path": { + "description": "The file that the failure concerns.", + "type": "string" + } + }, + "required": [ + "_tag", + "message" + ], + "type": "object" + }, + "InvalidConfig": { + "additionalProperties": false, + "properties": { + "_tag": { + "const": "InvalidConfig", + "description": "The configuration loaded, but CSS Forge rejects a value in it." + }, + "message": { + "type": "string" + }, + "path": { + "description": "The file that the failure concerns.", + "type": "string" + } + }, + "required": [ + "_tag", + "message" + ], + "type": "object" + } + }, + "readOnly": true + } + }, + "events": { + "tokens.built": { + "description": "Build the outputs of a CSS Forge configuration now, then again each time the configuration or a local module that it imports changes. Each occurrence is the result of one build: the files written, or the failure. A failed build does not end the subscription. Ending the subscription stops the watch; files already written stay.", + "audience": [ + "cli", + "mcp", + "library" + ], + "input": { + "additionalProperties": false, + "properties": { + "color-formats": { + "default": [], + "description": "Extra color formats generated beside oklch(), added to the formats that the configuration declares.", + "items": { + "enum": [ + "hex", + "rgb" + ], + "type": "string" + }, + "type": "array", + "uniqueItems": true + }, + "config": { + "default": "./cssforge.config.ts", + "description": "The path of the configuration file.", + "minLength": 1, + "type": "string" + }, + "css": { + "default": "./.cssforge/output.css", + "description": "The path of the CSS file.", + "minLength": 1, + "type": "string" + }, + "json": { + "default": "./.cssforge/output.json", + "description": "The path of the JSON file.", + "minLength": 1, + "type": "string" + }, + "mode": { + "default": "all", + "description": "The output to write: one format, or all of them.", + "enum": [ + "css", + "json", + "ts", + "style-dictionary", + "all" + ], + "type": "string" + }, + "root": { + "description": "The directory that the relative paths of the input resolve against. The default is the working directory of the tools.", + "minLength": 1, + "type": "string" + }, + "style-dictionary": { + "default": "./.cssforge/tokens.sd.json", + "description": "The path of the Style Dictionary token JSON file.", + "minLength": 1, + "type": "string" + }, + "style-dictionary-value-mode": { + "default": "resolved", + "description": "How the Style Dictionary output writes values: css-reference for usage matching, resolved for previews and builds.", + "enum": [ + "css-reference", + "resolved" + ], + "type": "string" + }, + "ts": { + "default": "./.cssforge/output.ts", + "description": "The path of the TypeScript file.", + "minLength": 1, + "type": "string" + } + }, + "required": [], + "type": "object" + }, + "payload": { + "additionalProperties": false, + "properties": { + "dependencies": { + "description": "The absolute paths of the configuration and the local modules it imports.", + "items": { + "type": "string" + }, + "type": "array" + }, + "diagnostics": { + "items": { + "additionalProperties": false, + "description": "A warning about a value that generates, but likely not as intended.", + "properties": { + "code": { + "description": "A stable identifier of the warning.", + "type": "string" + }, + "message": { + "description": "What is wrong, and how to fix it.", + "type": "string" + }, + "path": { + "description": "The configuration path of the value.", + "type": "string" + }, + "severity": { + "enum": [ + "warning" + ], + "type": "string" + } + }, + "required": [ + "code", + "severity", + "path", + "message" + ], + "type": "object" + }, + "type": "array" + }, + "failure": { + "additionalProperties": false, + "description": "Why the build failed, when ok is false.", + "properties": { + "_tag": { + "enum": [ + "ConfigLoadFailed", + "InvalidConfig", + "WriteFailed" + ], + "type": "string" + }, + "message": { + "type": "string" + }, + "path": { + "type": "string" + } + }, + "required": [ + "_tag", + "message" + ], + "type": "object" + }, + "files": { + "description": "The files written.", + "items": { + "additionalProperties": false, + "properties": { + "format": { + "enum": [ + "css", + "json", + "ts", + "style-dictionary" + ], + "type": "string" + }, + "path": { + "description": "The absolute path of the file.", + "type": "string" + } + }, + "required": [ + "format", + "path" + ], + "type": "object" + }, + "type": "array" + }, + "ok": { + "description": "Whether the build wrote every output.", + "type": "boolean" + } + }, + "required": [ + "ok" + ], + "type": "object" + } + } + } +} diff --git a/packages/cssforge/jsr.json b/packages/cssforge/jsr.json index 424584b..8bd4546 100644 --- a/packages/cssforge/jsr.json +++ b/packages/cssforge/jsr.json @@ -5,10 +5,11 @@ "license": "MIT", "exports": { ".": "./src/mod.ts", - "./cli": "./src/cli.ts" + "./cli": "./src/cli.ts", + "./capabilities": "./src/capabilities.ts" }, "imports": { - "citty": "npm:citty@0.1.6", + "@acid-cat/core-ts": "npm:@acid-cat/core-ts@0.11.1", "chokidar": "npm:chokidar@4.0.3", "colorjs.io": "npm:colorjs.io@0.5.2", "utopia-core": "npm:utopia-core@1.6.0" diff --git a/packages/cssforge/moon.yml b/packages/cssforge/moon.yml index 3857a14..ec31ba6 100644 --- a/packages/cssforge/moon.yml +++ b/packages/cssforge/moon.yml @@ -127,6 +127,7 @@ tasks: inputs: - "src/**/*" - "tests/**/*" + - "cssforge.acidcat.json" - "vitest.config.ts" - "package.json" - "jsr.json" @@ -259,6 +260,25 @@ tasks: options: runInCI: false cache: false + catalog-write: + command: "node" + args: ["./scripts/catalog.ts"] + inputs: + - "src/**/*" + - "scripts/catalog.ts" + outputs: + - "cssforge.acidcat.json" + options: + runInCI: false + catalog-check: + # The committed catalog conforms to the AcidCat specification and is in + # canonical form. tests/acidcat.test.ts checks that it matches src/capabilities.ts. + command: "acid-cat" + args: ["check", "--strict", "cssforge.acidcat.json"] + inputs: + - "cssforge.acidcat.json" + options: + runInCI: "always" readme-update: command: "tsx" args: ["./scripts/update-readme.ts"] diff --git a/packages/cssforge/package.json b/packages/cssforge/package.json index d5a0769..2502996 100644 --- a/packages/cssforge/package.json +++ b/packages/cssforge/package.json @@ -20,6 +20,11 @@ "import": "./dist/cli.js", "default": "./dist/cli.js" }, + "./capabilities": { + "types": "./dist/capabilities.d.ts", + "import": "./dist/capabilities.js", + "default": "./dist/capabilities.js" + }, "./package.json": "./package.json" }, "repository": { @@ -42,15 +47,17 @@ "src", "README.md", "CHANGELOG.md", - "jsr.json" + "jsr.json", + "cssforge.acidcat.json" ], "dependencies": { + "@acid-cat/core-ts": "0.11.1", "chokidar": "4.0.3", - "citty": "0.1.6", "colorjs.io": "0.5.2", "utopia-core": "1.6.0" }, "devDependencies": { + "@acid-cat/cli": "0.11.1", "@biomejs/biome": "2.4.2", "@types/node": "24.3.0", "mdbox": "0.1.1", diff --git a/packages/cssforge/scripts/catalog.ts b/packages/cssforge/scripts/catalog.ts new file mode 100644 index 0000000..c36de74 --- /dev/null +++ b/packages/cssforge/scripts/catalog.ts @@ -0,0 +1,19 @@ +/** + * Writes the AcidCat catalog of the CSS Forge tools, `cssforge.acidcat.json`, + * from the application in `src/capabilities.ts`. + * + * The application is the source of the catalog; never edit the JSON by hand. + * `tests/acidcat.test.ts` fails when the committed catalog differs from the + * one the application writes. + * + * Usage: node ./scripts/catalog.ts + */ +import { writeFileSync } from "node:fs"; +import { resolve } from "node:path"; +import { renderCatalog } from "@acid-cat/core-ts"; +import { cssforge, toJsonSchema } from "../src/capabilities.ts"; + +const catalogPath = resolve(import.meta.dirname, "../cssforge.acidcat.json"); + +writeFileSync(catalogPath, renderCatalog(cssforge, { toJsonSchema })); +console.log(`Wrote ${catalogPath}`); diff --git a/packages/cssforge/scripts/jsr-smoke.ts b/packages/cssforge/scripts/jsr-smoke.ts index 582dd26..332de31 100644 --- a/packages/cssforge/scripts/jsr-smoke.ts +++ b/packages/cssforge/scripts/jsr-smoke.ts @@ -144,19 +144,27 @@ const main = async (): Promise => { check(typeof jsr.exports["."] === "string", "jsr.json must export a module entry"); check(typeof jsr.exports["./cli"] === "string", "jsr.json must export a cli entry"); + check( + typeof jsr.exports["./capabilities"] === "string", + "jsr.json must export a capabilities entry", + ); const moduleEntry = resolve(packageRoot, jsr.exports["."] ?? ""); const cliEntry = resolve(packageRoot, jsr.exports["./cli"] ?? ""); check(existsSync(moduleEntry), `the JSR module entry ${jsr.exports["."]} is missing`); check(existsSync(cliEntry), `the JSR CLI entry ${jsr.exports["./cli"]} is missing`); + const capabilitiesEntry = resolve(packageRoot, jsr.exports["./capabilities"] ?? ""); check( - isIncluded(jsr.exports["."] ?? ""), - `${jsr.exports["."]} is not covered by jsr.json publish.include`, + existsSync(capabilitiesEntry), + `the JSR capabilities entry ${jsr.exports["./capabilities"]} is missing`, ); check( - isIncluded(jsr.exports["./cli"] ?? ""), - `${jsr.exports["./cli"]} is not covered by jsr.json publish.include`, + isIncluded(jsr.exports["."] ?? ""), + `${jsr.exports["."]} is not covered by jsr.json publish.include`, ); + for (const entry of [jsr.exports["./cli"], jsr.exports["./capabilities"]]) { + check(isIncluded(entry ?? ""), `${entry} is not covered by jsr.json publish.include`); + } for (const [name, version] of Object.entries(manifest.dependencies)) { const expected = `npm:${name}@${version}`; @@ -184,7 +192,7 @@ export default defineConfig({ runEntry( cliEntry, - ["--config", configPath, "--mode", "css", "--css", cssOutput], + ["tokens", "build", "--config", configPath, "--mode", "css", "--css", cssOutput], workDir, ); const css = await readFile(cssOutput, "utf8"); @@ -219,12 +227,25 @@ const css = mod.generateCSS( if (!css.includes("--spacing-size-2")) { throw new Error("the JSR module entry did not generate the expected CSS"); } + +// The library target generates from the config of the working directory. +const capabilities = await import(${JSON.stringify(pathToFileURL(capabilitiesEntry).href)}); +await using session = capabilities.createSession(capabilities.cssforge, { + target: "library", + context: { cwd: process.cwd() }, + toJsonSchema: capabilities.toJsonSchema, +}); +const generated = await session.call(capabilities.tokensGenerate, { format: "css" }); + +if (!generated.ok || !generated.value.content.includes("--spacing-size-2")) { + throw new Error(\`the JSR capabilities entry did not generate: \${JSON.stringify(generated)}\`); +} `, "utf8", ); runEntry(moduleCheck, [], workDir); console.log( - `jsr smoke test: ${jsr.name}@${jsr.version} entries ${jsr.exports["."]} and ${jsr.exports["./cli"]} verified with node`, + `jsr smoke test: ${jsr.name}@${jsr.version} entries ${jsr.exports["."]}, ${jsr.exports["./cli"]} and ${jsr.exports["./capabilities"]} verified with node`, ); } finally { await rm(workDir, { recursive: true, force: true }); diff --git a/packages/cssforge/scripts/publish.ts b/packages/cssforge/scripts/publish.ts index ba61479..61cacf9 100644 --- a/packages/cssforge/scripts/publish.ts +++ b/packages/cssforge/scripts/publish.ts @@ -25,7 +25,13 @@ type PackageManifest = { }; const packageRoot = resolve(import.meta.dirname, ".."); -const requiredArtifacts = ["dist/mod.js", "dist/mod.d.ts", "dist/cli.js"]; +const requiredArtifacts = [ + "dist/mod.js", + "dist/mod.d.ts", + "dist/cli.js", + "dist/capabilities.js", + "dist/capabilities.d.ts", +]; const isRecord = (value: unknown): value is Record => typeof value === "object" && value !== null; diff --git a/packages/cssforge/scripts/smoke-test.ts b/packages/cssforge/scripts/smoke-test.ts index 572e905..4b8ad0a 100644 --- a/packages/cssforge/scripts/smoke-test.ts +++ b/packages/cssforge/scripts/smoke-test.ts @@ -119,8 +119,7 @@ const parsePackResult = (output: string, description: string): PackResult => { /** * npm needs `--` to separate its flags from the script's; pnpm forwards that - * `--` to the binary, where citty treats it as end-of-options and drops every - * flag after it. + * `--` to the binary, so it is left out for pnpm. */ const scriptInvocation = (manager: "npm" | "pnpm", cliArgs: string[]): string[] => manager === "npm" @@ -151,8 +150,8 @@ const run = ( }; /** - * `--version` is citty's version flag (it only answers a bare `--version`), so - * the reported string is the CLI metadata of the installed artifact. A package + * The CLI answers `--version` only when it is the only argument, so the + * reported string is the CLI metadata of the installed artifact. A package * manager prints its own banner around a script run and a pnpm shim can * interleave the CLI's own log output, so the version is located in the output * rather than assumed to be the whole of it. @@ -181,10 +180,11 @@ const assertReportsVersion = ( }; /** - * `pnpm run