Werewolf CLI (alpha)

Published on npm as [email protected] (dist tags latest and alpha). Run it with npx werewolf-ui from a supported app. Component APIs remain draft.

Platform token export (E1, shipped in PR #134)

After initializing a supported app, select one platform and a directory relative to that app's root:

npx werewolf-ui tokens build --out exported-tokens --yes --json
npx werewolf-ui tokens build --platform ios --out exported-tokens --cwd ./my-app --yes --json
npx werewolf-ui tokens build --platform android --out exported-tokens --yes --json

Platform defaults to web. A single --platform accepts web, ios or android; unknown or repeated platform options fail with exit 2 before project reads. --out is required and cannot be absolute, traverse parents or escape through a symlink. The command reuses supported app/config detection; it does not initialize a native project or require native app dependencies.

The export uses the initialized app's configured DTCG seed, preserving its bytes, metadata and file mode. Config, app stylesheet, components and agent rules stay unchanged. Each selection writes both json/dark.json and json/light.json plus only the selected platform's artifacts. Web adds dark.css, light.css, werewolf.css and tailwind.css in web/; ios adds WerewolfDark.swift and WerewolfLight.swift in ios/; android adds WerewolfDark.kt and WerewolfLight.kt in android/. Existing unselected outputs remain untouched. Rebuild each platform after changing the seed.

Swift and Compose use Joey's decided touch values: sm 28, md 36, lg 44, xl 48, size-target-min 44 and font-size-input 16. Swift dimensions are points; Compose control sizes/targets use dp and input text uses sp. Mode JSON retains the mouse base maps (md 32, lg 36, xl 44, target 24, input 14). Web CSS keeps those base values and the existing coarse-pointer overrides. Native components remain v2.

All modes format and pass engine checks before consumer writes. Artifacts and their hashes in .werewolf/managed.json commit through the existing staged transaction, with seed/config read guards and rollback on failure or cancellation. The in-process rollback limits described below apply. Identical files skip, unchanged recorded artifacts may update, and edited or unrecorded differing artifacts conflict. --yes does not discard edits. After reviewing one generated file for replacement:

npx werewolf-ui tokens build --platform ios --out exported-tokens --overwrite exported-tokens/ios/WerewolfDark.swift --yes --json

Repeated --overwrite selects exact project-relative artifact paths in this request. It cannot select seed, config, ownership records or another platform. JSON uses the standard envelope with command "tokens build" and data: dataVersion, platform, out, files (sorted project-relative artifact paths), changedFiles and skippedFiles. The latter two include the ownership record and unchanged read guards; files lists only exported artifacts. Exit 0 succeeds, 1 reports operational failure/conflict and 2 reports invalid arguments/config. Cancellation returns 130. No package-manager process runs during export.

Consumer lint (C3, shipped in PR #129)

Select the supported app with --cwd:

npx werewolf-ui lint --json
npx werewolf-ui lint src --cwd ./my-app --json
npx werewolf-ui lint src/App.tsx --fix --yes --json

Paths are literal project-relative files or directories, without traversal, absolute paths or globs. No paths scans eligible source under the app root. The scanner supports .js, .jsx, .ts, .tsx, .mjs and .css. It respects root and nested .gitignore, .ignore and .werewolfignore files, including negations. Explicit selections also respect ignores. Dependencies, .git, dist, build, coverage, .next, .nuxt, .turbo, .cache, .output, .vercel, .werewolf and the configured generated stylesheet are excluded. Symlinks are skipped with warnings during traversal; explicit symlink paths or ancestors fail. Invalid UTF-8 is an error.

Scanning is bounded to 500 source files, 500 directories, 20,000 visited entries and 100 path levels. Files and ignore policies are bounded to 1 MiB. Limits are explicit WW_LIMIT errors. Cancellation stops subsequent reads and uses exit 130. Root selection, aliases and framework checks follow B1. Init is optional for lint: a present consumer seed supplies choices, otherwise packaged defaults apply. Lint never initializes a project. It does not detect or require a package manager, so a missing, ambiguous or unsupported lockfile choice does not block it.

--fix consumes C2 metadata, deduplicates edits, rejects overlaps and invalid UTF-16 ranges, and preserves BOM, line endings, comments and unrelated bytes. It analyzes repaired content before writing. Parse/encoding/limit failures or truncated results prevent all fixes in that invocation. A newly introduced parse failure prevents writes. Config, seed, ignore policies and source bytes/physical targets are guarded; concurrent changes conflict. Writes stage beside destinations and roll back on failure or cancellation, preserving file modes. Rollback is in-process, not crash recovery. Failed rollback reports retained backup paths. Seed, theme, agent rules and installation ownership are not rewritten.

JSON stdout contains exactly one envelope. Outer diagnostics are the final report; data includes dataVersion, checkedFiles, changedFiles, skippedFiles, coverage, applied and remaining. Applied diagnostics retain original locations; remaining diagnostics use repaired-source locations. Human output shows coverage, changed paths, locations and suggestions. Exit 0 means no errors (warnings can remain), 1 means errors, operational failure or truncated diagnostics, and 2 means invalid options or project configuration. Inspect coverage and skippedFiles: exit 0 does not prove dynamic styles or skipped symlinks were analyzed.

Ambiguous literal colors and rem-based numeric spacing remain diagnostics with suggestions. A second fix pass is idempotent. The existing docs pr-28 conflict remains for layout/design review. See C3 evidence.

The help/version scaffold and offline catalog shipped on the repository's main branch in PR #117. Pure core theme generation shipped in PR #118. The portable token writer shipped in PR #119. B1 project detection, config, path policy and package-manager adapters shipped in PR #120. B2 idempotent init and reversible consumer writes shipped in PR #121. B3 component installation shipped in PR #123. B4 persistent themes shipped in PR #124. C1/C2 extraction and source-only rules shipped in PR #126/#128. C3 consumer lint shipped in PR #129. D1/D2 MCP tools and stdio launch shipped in PR #131/#132. D3 packed CLI/MCP equivalence shipped in PR #133. E1 platform token export and native touch formatting shipped in PR #134. E2 docs command and per-command help are implemented in this PR, pending review.

The local CLI supports help, version, init, add, theme, lint, mcp, tokens build and docs with optional --yes and --json. <command> --help prints that command's usage. MCP stdout remains protocol traffic with either flag. An unavailable command returns WW_COMMAND and exit code 2. The full option, exit-code and diagnostic-code reference is docs/cli.md.

Docs command (E2, pending review)

npx werewolf-ui docs
npx werewolf-ui docs date-picker
npx werewolf-ui docs button --json

Docs maps a known component to /components/<name> and no name to /docs/installation, using the site origin in the packaged catalog. It reads no consumer project. Unknown names return WW_COMPONENT (exit 2). The URL is always printed or returned as {url, opened}. A browser opens only when stdin and stderr are terminals and --json is absent. The opener runs from an absolute path with an argument list and no shell: /usr/bin/open, the system rundll32.exe url.dll,FileProtocolHandler on Windows, or xdg-open from an absolute PATH entry outside node_modules, so a project or dependency cannot substitute it. It accepts only http(s) URLs and waits at most 5 seconds. Failure keeps exit 0, sets opened: false and adds a WW_OPEN warning. All opener branches are tested with an injected spawn; a real browser launch is not part of the suite.

From any directory:

npx werewolf-ui --help
npx werewolf-ui --version --json
npx werewolf-ui init --yes --json
npx werewolf-ui add button input dialog --yes --json
npx werewolf-ui theme --accent "<hex>" --gray-tint 0.25 --radius-base 6px --yes --json

The package contains an offline, versioned catalog: handwritten component source, draft specs, English usage, dependency metadata, default token data and design rules. Component APIs retain their spec status.

For repository development:

npm run build:cli
npm test -w @werewolf-ui/core
npm test -w werewolf-ui

CLI JSON stdout contains one result document. Human errors go to stderr. The internal core bundle includes the existing color engine and its MIT notices in LICENSE. It loads its versioned token data from the packaged manifest, then generates both modes, touch overrides, web CSS and actual engine checks without filesystem or network calls.

Since A3, core.buildTokens({seed,out,platforms}) writes selected web, iOS or Android artifacts plus both JSON mode files. It inherits missing seed choices from the manifest and requires a non-empty list of unique platforms. It validates and formats every requested artifact before creating directories. Data and contrast failures leave existing files untouched; filesystem write failures can leave partial output. B2 consumer init uses the reversible write planner described below. B4 theme uses the same planner for seed and CSS.

The writer's serialization dependencies are bundled, with their license texts and notices in dist/THIRD-PARTY-NOTICES.txt. No runtime dependency installation is required. Pack/install/export checks cover Node 20 and preserve the repository build's web/JSON output bytes. E1 changes only the five native sizing constants approved by Joey on 2026-10-13; native formatting is pending review. The build tools remain development dependencies.

B1 exposes internal project modules in the package: dist/project.mjs, dist/paths.mjs and dist/package-manager.mjs. B2 consumes these modules for init. detectProject({cwd,overrides}) reads only the selected app's configuration and returns root, framework, packageManager, config, reactVersion, tailwindVersion and absolute paths (css, seed, output and directories). It requires Node 20+, React 19 and styling version 4. Installed metadata takes precedence; otherwise, the entire declared range must establish a supported major version.

Version 1 werewolf.json accepts framework, packageManager, css, seed, output, aliases (ui, lib, hooks) and directories (ui, lib, hooks). schemaVersion: 1 is required in a stored config; other fields may be omitted. Overrides take precedence over stored values, then compatible components.json mappings, then detected defaults. Unknown fields and incompatible registry settings fail. All targets are relative to the selected root. Defaults are tokens/seed.json, styles/werewolf.css and the compiler's mapped component, lib and hooks folders. The app CSS input, seed and generated output must be separate files.

Detection recognizes the two app-router CSS locations and the Vite src CSS location in the plan. Competing CSS files and lockfiles require explicit choices. Workspace roots require selecting the app directory. Existing compiler aliases are read from JSON with comments, local relative extends and direct project references; they are never rewritten. External compiler extends, multiple extends and ambiguous mappings require a local unambiguous alias config.

The shared resolveProjectPath({root,relativePath,mustExist}) export in dist/core.mjs validates reads and future write targets, including symlink ancestors. Detection is read-only. B2 revalidates paths and current bytes immediately before each file commit.

installDependencies({project,specs,spawn}) sorts and deduplicates specs, rejects version conflicts before spawning, preserves exact pins and returns {installed}. It supports all four adapters through argument arrays with no shell. On Windows it locates native executables or resolves standard .cmd launchers to their underlying scripts, then invokes Node directly. Unsupported custom launchers fail with remediation. Subprocess errors include the exit code or signal and up to 8 KiB of trailing stderr, without writing to CLI stdout. Windows launcher resolution has focused tests. The E3 consumer gate also tests real installers and platform behavior; see release checks for the evidence and remaining matrix limits.

The configuration and source parser dependencies are pinned in the build manifest, with ISC, MIT and Apache-2.0 license texts included in the tarball's notices. They are bundled for offline use, so the tarball does not install them as separate runtime dependencies.

B2 init creates werewolf.json and a default DTCG seed only if absent. A valid existing seed supplies the generated stylesheet and retains all bytes and metadata. Invalid seeds, missing styling imports, incompatible config and file conflicts fail before mutation. Init adds one relative theme import after the styling import, preserving the CSS BOM, newline style, comments and rules. Use --css, --seed, --output, --package-manager and --agent to select explicit defaults; edit an existing werewolf.json explicitly when changing its stored choices.

Init installs .agents/skills/werewolf-design/SKILL.md, a managed block delimited by and in AGENTS.md, and a Werewolf-only .cursor/rules/werewolf.mdc. Surrounding agent instructions stay intact. It does not install dependencies or write MCP client configuration. The core's internal getInitAssets() returns isolated copies of the selected package's default DTCG seed and design rules.

Init writes AGENTS.md, .agents/skills/werewolf-design/SKILL.md and the files of the selected coding agents. Select agents with --agent ; it accepts comma lists, repeats and all. An unknown id returns WW_PROJECT_CONFIG with exit 2 and writes nothing. Without --agent, init always keeps the Cursor rule (the previous default) and adds every agent detected from the environment of the calling agent or from project files (CLAUDE.md or .claude, .github/instructions or .github/copilot-instructions.md, .windsurf, .windsurfrules or .devin/rules, GEMINI.md or .gemini, .clinerules or .cline, .cursor or .cursorrules), and prints a hint about --agent. With nothing detected it writes the same files as before. Agent files already recorded in .werewolf/managed.json and existing Werewolf blocks keep updating on every run, even when their agent is not selected.

| Id | Files besides AGENTS.md | | --- | --- | | claude | Managed block with @AGENTS.md in CLAUDE.md (skipped when CLAUDE.md already has that line), .claude/skills/werewolf-design/SKILL.md | | copilot | .github/instructions/werewolf.instructions.md (applyTo: "**"). .github/copilot-instructions.md is never touched. | | windsurf | .windsurf/rules/werewolf.md (trigger: always_on), or .devin/rules/werewolf.md when .devin/ exists | | gemini | Managed block with @./AGENTS.md in GEMINI.md. If context.fileName is set in .gemini/settings.json, keep GEMINI.md or AGENTS.md in it. | | cline | .clinerules/werewolf.md | | cursor | .cursor/rules/werewolf.mdc (alwaysApply: true) | | codex, jules, amp, other | None; they read AGENTS.md |

Generated agent files use the ownership record like other generated files. Init never creates symlinks and never deletes files of agents that are not selected. --json reports data.agents (selected ids, the source flag, env, marker or default, and the detected signals with their confidence), files with the action created, updated or unchanged, conflicts, hints, changedFiles and skippedFiles. A conflict exits non-zero, lists every path in the diagnostic details and writes nothing.

Environment signals, each confirmed in official docs or the tool's source: CLAUDE_CODE_CHILD_SESSION or CLAUDECODE (claude), CURSOR_AGENT (cursor), GEMINI_CLI (gemini), CODEX_THREAD_ID or CODEX_SESSION_ID (codex), CLINE_ACTIVE=true (cline) and AI_AGENT=github_copilot_vscode_agent (copilot in VS Code). Other agents are detected only through project files or --agent. --agent other writes AGENTS.md and the skill only.

Prompt for a coding agent:

Set up the Werewolf UI design rules in this project.
Pick your own id from: claude, cursor, copilot, windsurf, gemini, cline, codex, jules, amp, other.
Run in the project root: npx werewolf-ui@latest init --agent <your-id> --yes --json
Do not add --overwrite. If the command reports conflicts, stop and show them to me.
Then tell me which files were created, updated or left unchanged, using the JSON output.

The ownership record .werewolf/managed.json stores version 1 SHA-256 hashes of managed generated files. Keep it with the generated files. Identical files skip; unmodified recorded files can update when the seed or packaged rules change. Different unrecorded files and edited generated files produce WW_CONFLICT, including in a non-TTY session. --yes never authorizes an overwrite. To replace one reviewed generated file explicitly:

npx werewolf-ui init --overwrite styles/werewolf.css --yes --json

--overwrite accepts repeated, exact generated paths. It cannot select the seed, config, app CSS, AGENTS.md or ownership record. Preserve or move edits aside if you do not want to overwrite them. Malformed blocks, duplicate imports and invalid ownership records include remediation in their diagnostics.

The internal planInit({project,core}) returns ordered files and conflicts. Each entry has path, before (exact bytes or null), after (exact bytes) and ownership (generated, component or user-managed-block). applyWritePlan accepts an explicit overwrite path list, preflights all entries, stages alongside each destination and renames. It checks current bytes and physical targets before each commit, including unchanged seed/config read guards. A failed write restores committed originals and removes new files and empty directories. Existing modes are retained. If restoration itself fails or concurrent edits prevent it, the error lists unresolved paths and retained backup files for recovery. This is an in-process rollback contract, not recovery from process termination or power loss.

runCli(argv, io) returns {exitCode,result} without writing to process streams. Injected stdout/stderr receive one result; the production bin serializes once. JSON is one document on stdout. Success is exit 0, operational conflicts exit 1, and invalid options, seeds or project configuration exit 2.

B3 add requires an initialized app. Missing config, seed or ownership record returns WW_NOT_INITIALIZED with the npx werewolf-ui init action. It resolves one or more component names and their registry dependencies in topological order, once per item. Utility and token registry items are local files, never external packages. Component APIs remain draft. C3 lint and D2 MCP launch ship on main and in the published alpha.

Add maps UI, lib and hooks source into the configured compiler aliases and directories. It parses source and edits only module specifiers under the known registry prefix. Directives, package imports (including server icon imports), comments, other strings, quote style and surrounding bytes remain intact. Unparseable or unmappable source fails before installation.

Add keeps existing seed and stylesheet bytes, including custom CSS. It skips the registry token item's default content. Only a missing generated stylesheet is rebuilt from the existing seed, with both themes checked first. A missing app CSS import needs an explicit init repair; add never performs a hidden init.

Identical component files skip. Any differing component or utility file conflicts, even if its bytes match the ownership record from an earlier package version. Use an exact path to select each file you have reviewed for replacement:

npx werewolf-ui add button --overwrite src/components/ui/button.tsx --yes --json

The selection applies only to component files in this request and a missing generated output being restored. It cannot overwrite seed, config, app CSS, agent instructions or ownership records. Existing theme edits stay intact.

The internal planAdd({project,core,names}) returns {writes,dependencySpecs,componentNames}. Writes use B2's WritePlan and ownership ledger. Conflict, byte, physical-target and root-confinement preflight runs before the package manager. Compatible declared dependencies skip installation; incompatible declarations and differing exact pins return WW_DEPENDENCY_CONFLICT before any subprocess. Ranged and pinned installs run separately so the package manager retains exact pins. Equivalent repeated adds invoke no installer and write no files.

Dependencies install first, then staged component files commit with byte and physical-target guards. Manager failure commits no component files. Diagnostics include actual package.json and lockfile changes, inspection failures and bounded installer stderr. Failed file commits reuse B2 rollback and report the dependencies already installed. File rollback does not undo external installation: manifests, lockfiles and node_modules may retain changes. Review the diagnostics before retrying; the CLI does not delete node_modules or regenerate unrelated lockfiles.

B3 adds a pinned source parser build dependency, typescript 5.9.3 (Apache-2.0), already present in the docs workspace. Its license and third-party notice text ship in dist/THIRD-PARTY-NOTICES.txt. The parser is bundled into the executable, so consumers do not resolve an unpublished workspace or parser package at runtime. The local tarball regression runs actual npm installation, repeated add and edited component refusal outside the repository. The E3 consumer gate extends these checks to real installers and browser behavior in both supported layouts.

B4 theme requires an initialized consumer app and at least one of --accent, --gray-tint or --radius-base. Accent is a 3 or 6 digit hex, gray tint is a finite number from 0 to 1, and radius is sharp, default, round, pill or a non-negative px value. Use --cwd to select the consumer root. Stored config supplies the seed and output paths; output must be a generated .css file. It never writes the repository seed.

Only requested $value fields change. Omitted choices, descriptions, extensions, group metadata, BOM and newline style survive. An equivalent repeat keeps exact seed bytes and writes nothing. Both modes and engine checks complete before mutation. The seed, CSS and ownership hash commit together through B2 rollback; config bytes and physical targets remain guarded. This is in-process rollback, not crash recovery.

Edited or unrecorded differing output returns WW_CONFLICT at its exact path, with no seed write. After reviewing a generated stylesheet for replacement:

npx werewolf-ui theme --accent "<hex>" --overwrite styles/werewolf.css --yes --json

Only the generated output in this request can be selected. Seed, config, app CSS, agent instructions, ownership records and components cannot be selected by theme. --yes never discards edits. Init after theme is idempotent; add keeps the custom seed and CSS. An edited component also conflicts when it is a dependency of a requested component.

To try unreleased changes, build and install a local tarball:

npm ci
npm run build:cli
npm pack --workspace werewolf-ui --pack-destination /absolute/path/to/output
cd /absolute/path/to/consumer
npm install /absolute/path/to/output/werewolf-ui-0.1.0-alpha.1.tgz --engine-strict

The supported alpha layouts are Next.js app-router (app or src/app) and Vite React TypeScript, with Node 20+, React 19, Tailwind CSS v4 and existing compiler aliases. The E3 consumer gate builds and packs locally, installs that exact tarball in isolated temporary apps, runs all five MCP tools, exercises init/add/theme and lint/fix, builds each app and verifies rendered token classes, keyboard focus, dialog focus return and coarse-pointer sizes in a browser:

npm exec --no -- playwright install chromium
npm run test:consumers

The default selection is npm in both layouts. Use WW_CONSUMER_MANAGERS and WW_CONSUMER_FRAMEWORKS to select real installed managers and layouts. Evidence, screenshots and the exact tested tarball go to dist/release; created temporary apps and processes are cleaned up. This network/browser gate runs separately from npm test. The prior acceptance entry delegates to the same gate. See release checks and publication handoff.

MIT License. See LICENSE. Bundled third-party notices ship in dist/THIRD-PARTY-NOTICES.txt.

MCP stdio launch

Run npx werewolf-ui mcp --cwd ./my-app. The default root is the current directory. Any existing directory is sufficient; init and framework detection are not required. The command accepts --yes and --json, but stdout always contains protocol traffic. Startup failures use stderr and exit codes.

To launch the published package without installing it in the app, use the version-pinned entry in docs/mcp.md. For a package installed in the app, configure this process entry in a compatible client's MCP settings. Replace both paths with the existing directory where the package is installed:

{
  "command": "npx",
  "args": ["--no-install", "werewolf-ui", "mcp", "--cwd", "/absolute/path/to/app"],
  "cwd": "/absolute/path/to/app"
}

The client must have Node 20+ and npx on its PATH. If it cannot set cwd, launch node with the absolute installed node_modules/werewolf-ui/dist/cli.mjs path, mcp, --cwd and the app path as separate arguments. Wrappers vary by client. Init never changes client settings. This local config does not fetch a public release; publication remains planned.

The five names are list_components, search, get_component, generate_theme and lint. Successful tools return matching JSON text and structuredContent with schemaVersion, dataVersion, ok, data and diagnostics. Lint findings live in data.diagnostics; ok means the tool ran, rather than that the source is clean. Check coverage for dynamic or unread source. Theme returns artifacts without writing them.

The server exposes exactly five read-only tools. Lint accepts submitted content or explicit source files under the canonical root, with the same file, byte and diagnostic limits as core lint. Directory/glob inputs and symlinks are rejected. No installation, fixes or consumer config execution occurs. EOF drains responses; signals and broken input close with bounded cleanup. See local MCP connection and tool documentation for the local tarball process config, illustrative future published config, tool examples, result envelopes and troubleshooting. D2 ships in PR #132. D3 packed comparisons and configured CLI-client evidence shipped in PR #133; desktop application registration remains untested. MCP lint uses the packaged default seed, while CLI lint reads the consumer seed for color suggestions.