From df9415bf0db95870b1f9b21d122af5b8b8eb55e0 Mon Sep 17 00:00:00 2001 From: Hebilicious Date: Mon, 16 Nov 2026 16:27:09 +0700 Subject: [PATCH 1/3] feat(cli)!: rewrite the CLI with AcidCat and add an MCP server One AcidCat application (src/app.ts) declares the capabilities tokens.build, tokens.generate and config.check, and the event tokens.built. The command line, the MCP server (`cssforge mcp`, stdio) and typed handles for a future user interface (`@hebilicious/cssforge/app`) all come from it. The catalog is committed as cssforge.acidcat.json and checked against the application. The operations live in src/forge.ts and return reports instead of logging, so every surface and the kept build()/watch() API share them. The schemas are JSON Schema documents validated by a small local validator, so the catalog and the runtime check cannot disagree. `cssforge [flags]` with no command still builds, and -w, -m, --prefix and comma separated --color-formats keep working. citty is removed. --- .changeset/acidcat-cli-mcp.md | 11 + README.md | 88 +- packages/cssforge/README.md | 88 +- packages/cssforge/cssforge.acidcat.json | 752 ++++++++++++++++++ packages/cssforge/jsr.json | 5 +- packages/cssforge/moon.yml | 20 + packages/cssforge/package.json | 10 +- packages/cssforge/scripts/catalog.ts | 19 + packages/cssforge/scripts/smoke-test.ts | 20 +- packages/cssforge/src/app.ts | 475 +++++++++++ packages/cssforge/src/cli.ts | 620 +++++++-------- packages/cssforge/src/forge.ts | 388 +++++++++ packages/cssforge/src/schema.ts | 214 +++++ packages/cssforge/tests/acidcat.test.ts | 198 +++++ .../cssforge/tests/cli-color-formats.test.ts | 10 +- .../cssforge/tests/cli-diagnostics.test.ts | 16 +- packages/cssforge/tests/cli-entry.test.ts | 2 +- packages/cssforge/tests/cli-mode.test.ts | 11 +- packages/cssforge/tests/generator.test.ts | 6 +- packages/cssforge/tests/helpers.ts | 4 +- packages/cssforge/tests/quick-start.test.ts | 26 +- .../cssforge/tests/version-artifact.test.ts | 18 +- packages/cssforge/tsup.config.ts | 1 + packages/docs/agents.md | 7 +- pnpm-lock.yaml | 36 +- skills/cssforge/SKILL.md | 5 +- skills/cssforge/references/cli-reference.md | 61 +- 27 files changed, 2639 insertions(+), 472 deletions(-) create mode 100644 .changeset/acidcat-cli-mcp.md create mode 100644 packages/cssforge/cssforge.acidcat.json create mode 100644 packages/cssforge/scripts/catalog.ts create mode 100644 packages/cssforge/src/app.ts create mode 100644 packages/cssforge/src/forge.ts create mode 100644 packages/cssforge/src/schema.ts create mode 100644 packages/cssforge/tests/acidcat.test.ts diff --git a/.changeset/acidcat-cli-mcp.md b/.changeset/acidcat-cli-mcp.md new file mode 100644 index 0000000..2a0c07d --- /dev/null +++ b/.changeset/acidcat-cli-mcp.md @@ -0,0 +1,11 @@ +--- +"@hebilicious/cssforge": minor +--- + +Rewrite the CLI with AcidCat, and add an MCP server. + +- New 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 capabilities to an agent as MCP tools, through stdio. +- `@hebilicious/cssforge/app` exports the AcidCat application, for typed calls from a user interface. The catalog ships as `cssforge.acidcat.json`. +- `cssforge [flags]`, with no command, still builds, and `-w`, `-m`, `--prefix` and `--color-formats hex,rgb` still work. +- Breaking: the output of the CLI 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`. The `--color-formats` flag of a command takes one format per flag or a JSON array. The default export of `@hebilicious/cssforge/cli` (a citty command) is removed, and so is the `citty` dependency. `build()` and `watch()` keep their behavior. diff --git a/README.md b/README.md index e662943..baf7686 100644 --- a/README.md +++ b/README.md @@ -153,8 +153,8 @@ export default defineConfig({ ```bash cssforge # Basic usage -cssforge --help # To see all options -cssforge --watch # To watch for changes +cssforge --help # To see all commands +cssforge watch tokens.built # To watch for changes ``` 3. Use the generated variables in your CSS: @@ -1984,29 +1984,61 @@ The pow representation of a step adds a `pow` segment, as in ## CLI Usage +The `cssforge` command line, its MCP server and its typed API all come from one +[AcidCat](https://github.com/Hebilicious/acidcat) catalog, +[`cssforge.acidcat.json`](packages/cssforge/cssforge.acidcat.json). Each command answers with +JSON on stdout. + ```bash -# Basic usage -cssforge +# Write every output of ./cssforge.config.ts. `cssforge` with flags and no command is the same. +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 -w` is the same. +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`. + +The flags of the earlier versions still work without a command: `cssforge --mode css`, +`-m css`, `-w`, `--prefix ` (now `--root`) and `--color-formats hex,rgb`. ## Programmatic Usage @@ -2167,9 +2199,31 @@ 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. +`cssforge mcp` serves the CLI capabilities to an agent 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 +``` + +A user interface can call the same capabilities through typed handles: + +```typescript +import { createSession } from "@acid-cat/core-ts"; +import { cssforge, tokensGenerate, toJsonSchema } from "@hebilicious/cssforge/app"; + +await using session = createSession(cssforge, { + target: "app", + context: { cwd: process.cwd() }, + toJsonSchema, +}); +const result = await session.call(tokensGenerate, { format: "css" }); +if (result.ok) console.log(result.value.content); +``` + +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/README.md b/packages/cssforge/README.md index e662943..baf7686 100644 --- a/packages/cssforge/README.md +++ b/packages/cssforge/README.md @@ -153,8 +153,8 @@ export default defineConfig({ ```bash cssforge # Basic usage -cssforge --help # To see all options -cssforge --watch # To watch for changes +cssforge --help # To see all commands +cssforge watch tokens.built # To watch for changes ``` 3. Use the generated variables in your CSS: @@ -1984,29 +1984,61 @@ The pow representation of a step adds a `pow` segment, as in ## CLI Usage +The `cssforge` command line, its MCP server and its typed API all come from one +[AcidCat](https://github.com/Hebilicious/acidcat) catalog, +[`cssforge.acidcat.json`](packages/cssforge/cssforge.acidcat.json). Each command answers with +JSON on stdout. + ```bash -# Basic usage -cssforge +# Write every output of ./cssforge.config.ts. `cssforge` with flags and no command is the same. +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 -w` is the same. +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`. + +The flags of the earlier versions still work without a command: `cssforge --mode css`, +`-m css`, `-w`, `--prefix ` (now `--root`) and `--color-formats hex,rgb`. ## Programmatic Usage @@ -2167,9 +2199,31 @@ 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. +`cssforge mcp` serves the CLI capabilities to an agent 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 +``` + +A user interface can call the same capabilities through typed handles: + +```typescript +import { createSession } from "@acid-cat/core-ts"; +import { cssforge, tokensGenerate, toJsonSchema } from "@hebilicious/cssforge/app"; + +await using session = createSession(cssforge, { + target: "app", + context: { cwd: process.cwd() }, + toJsonSchema, +}); +const result = await session.call(tokensGenerate, { format: "css" }); +if (result.ok) console.log(result.value.content); +``` + +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..bc8cf2e --- /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": { + "app": { + "bindings": [ + "typescript" + ], + "description": "Typed handles for a user interface." + }, + "cli": { + "bindings": [ + "cli" + ], + "description": "The cssforge command line." + }, + "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", + "app" + ], + "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", + "app" + ], + "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", + "app" + ], + "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", + "app" + ], + "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..e52a5cf 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", + "./app": "./src/app.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..67a33ad 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/app.ts. + command: "npx" + args: ["-y", "@acid-cat/cli@0.11.1", "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..16e65bd 100644 --- a/packages/cssforge/package.json +++ b/packages/cssforge/package.json @@ -20,6 +20,11 @@ "import": "./dist/cli.js", "default": "./dist/cli.js" }, + "./app": { + "types": "./dist/app.d.ts", + "import": "./dist/app.js", + "default": "./dist/app.js" + }, "./package.json": "./package.json" }, "repository": { @@ -42,11 +47,12 @@ "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" }, diff --git a/packages/cssforge/scripts/catalog.ts b/packages/cssforge/scripts/catalog.ts new file mode 100644 index 0000000..4321b15 --- /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/app.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/app.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/smoke-test.ts b/packages/cssforge/scripts/smoke-test.ts index 572e905..8f1a9ef 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,10 @@ const assertReportsVersion = ( }; /** - * `pnpm run