@zenginui/cli 0.1.0

package/README.md

@@ -0,0 +1,184 @@
+# @zenginui/cli
+
+The `zengin` command. The gate that actually protects the codebase: run it pre-commit and on every pull request. Same engine, same violations, same fixes as the MCP server and the hook.
+
+```
+zengin check [paths...]     check files (default: everything in scope)
+zengin explain [rule]       what each rule checks
+zengin init                 write a zengin.config.yaml in the current directory
+zengin create <dir>         a new project that owns its components, with the engine, MCP, hook and Storybook wired
+zengin add <items...>       components or templates from the registry into this project
+zengin theme [name]         list the registry's themes, or swap this project's brand for one
+zengin brand --name <name>  a brand from a name, a logo or a color: tokens, favicon, wordmark, index.html
+zengin tokens               zengin/tokens*.json to src/styles/generated/tokens.css
+zengin figma export|import|connect|plugin   tokens to Figma variables and back, Code Connect, the plugin
+zengin mock <presets...>    typed, seeded mock data modules into src/mock
+zengin registry build       the registry, from a Zengin repository checkout
+zengin report, rollup       drift and adoption, per repository and across them
+```
+
+## check
+
+```bash
+zengin check                                  # whole scope, pretty output
+zengin check src/features/review              # a directory
+zengin check --changed origin/main            # only files changed since a ref, plus uncommitted and untracked
+zengin check --staged                         # only staged files (pre-commit)
+zengin check --format github                  # GitHub Actions annotations on the PR
+zengin check --format json > report.json      # the full violation shape, for the rollup
+zengin check --rule color-literal --severity error
+zengin check --fail-on never                  # report, never fail
+```
+
+| Option | Values | Default |
+| --- | --- | --- |
+| `--config <path>` | | nearest `zengin.config.yaml` above cwd |
+| `--changed [ref]` | git ref | `HEAD` when given without a value |
+| `--staged` | | off |
+| `--rule <id>` | repeatable | all rules |
+| `--severity` | `error`, `warn`, `info` | all |
+| `--fail-on` | `error`, `warn`, `info`, `never` | `error` |
+| `--format` | `pretty`, `json`, `github` | `pretty` |
+| `--max <n>` | | `200` |
+
+Exit codes: `0` clean or below `--fail-on`, `1` violations at or above `--fail-on`, `2` usage or configuration error.
+
+Stylesheets outside the selected files still resolve class names for the files inside it, so `zengin check src/one/file.tsx` sees what `className="btn"` does even though the CSS file was not selected.
+
+## Pre-commit
+
+With [husky](https://typicode.github.io/husky/) or any pre-commit runner:
+
+```bash
+zengin check --staged
+```
+
+## GitHub Actions
+
+Until the packages are published, build them from source in the workflow. With published packages this collapses to one `npx zenginui check` step.
+
+```yaml
+name: design-system
+on: [pull_request]
+jobs:
+  zengin:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }            # --changed needs the base ref
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - run: pnpm exec zengin check --changed origin/${{ github.base_ref }} --format github
+```
+
+`--format github` emits workflow commands, so each violation appears as an inline annotation on the changed line with the fix in the message. The job fails on `error` severity unless `--fail-on` says otherwise.
+
+## create and add
+
+```bash
+zengin create acme --template marketing       # blank | marketing | review | saas | chat | auth | docs | storefront
+zengin create acme --template saas --framework next   # the App Router under src/app; the template mounted client-side from page.tsx
+zengin create acme --no-storybook
+zengin create acme --registry ./r --local ../zengin   # a local registry, packages linked from a checkout
+cd acme && zengin add dialog tooltip          # more items; --force overwrites files that exist
+zengin tokens                                 # after editing zengin/tokens*.json (dev and build run it)
+```
+
+`create` writes the project, copies the template's components in with the owned pragma, merges their manifest entries into `zengin/components.json`, builds `tokens.css`, and runs the engine on the result before it prints. `add` does the same for further items and records any npm packages they need in `package.json`. See [@zenginui/registry](../registry) for the layout and the registry format.
+
+## upgrade
+
+```bash
+zengin upgrade                 # a report: what the registry changed since each owned file was copied, and what you changed
+zengin upgrade --write         # take every upstream change the project did not touch; move the pinned version
+zengin upgrade button card     # only these items
+zengin upgrade --write --force # take upstream over a conflict too
+```
+
+Every owned file carries the hash of what was copied in its pragma (`/* zengin-owned Button, forked from @zenginui/ui@0.1.0, sha 3f9a1c0b2d4e */`). Comparing that hash with the file now says whether you edited it; comparing it with the registry says whether the system moved. Four answers per file: `current`, `upstream` (taken with `--write`), `local` (yours, left alone), `conflict` (both moved: the report shows the diff, `--force` takes upstream). Files copied before hashes existed show as `unknown` when they differ. When nothing is left behind, `zengin.config.yaml` is moved to the registry's version.
+
+## theme and brand
+
+```bash
+zengin theme                                  # list: brutal, default, meadow, plex, spec-sheet, zengin
+zengin theme plex                             # swap the brand file and the fonts link; nothing else changes
+zengin fonts                                  # list: archivo, brutal, dm, fraunces, geist, inter, manrope, playfair, plex, space
+zengin fonts fraunces                         # the three font tokens and the fonts link; palette untouched
+zengin fonts geist --self-host                # woff2 files into public/fonts, @font-face in src/theme/fonts.css
+zengin brand --name Acme --fonts plex         # a pairing instead of --font-display/--font-sans/--font-mono
+zengin icons                                  # list: lucide, tabler, phosphor, heroicons, feather, radix, material, bootstrap
+zengin icons tabler                           # every <Icon.Name /> draws from Tabler; direct icon-package imports become violations
+zengin create acme --theme spec-sheet         # or at creation
+
+zengin brand --name "Acme Reviews" --logo logo.svg --font-display Archivo --font-sans Inter --radius round
+zengin brand --name Nova --primary "#7C3AED"  # from a color alone
+```
+
+`theme` replaces `src/theme/brand.css` with the theme's file and puts its Google Fonts link in `index.html` (one link, marked `data-zengin="fonts"`, replaced by the next theme). `brand` derives a whole palette from one color, in OKLCH so steps look even, and pushes every pairing the components rely on (text on surface, on-primary on primary, soft-foreground on soft, and so on) until it meets WCAG AA in both schemes. It writes the brand file, `zengin/brand.json` (the inputs, for re-running), the logo into `public/`, a favicon when there is no SVG logo, `src/brand.ts` and a `BrandMark` component, and patches the title, theme-color, icon and fonts in `index.html`. An SVG logo also supplies the primary; a PNG needs `--primary`. Both commands run the engine afterwards; the project stays clean because the brand file is a foundation.
+
+## mock
+
+```bash
+zengin mock customers invoices            # presets: users, customers, companies, products, orders, invoices, events, messages, metrics
+zengin mock users --count 50 --seed 3
+zengin mock --schema mock.json            # your own entities; see @zenginui/mock for the field kinds
+```
+
+Writes `src/mock/rng.ts` (a seeded generator and the pools, no dependency) and one typed module per entity exporting the type, a factory and the array. The same seed gives the same data on every run, so screenshots and previews do not drift. See [@zenginui/mock](../mock).
+
+## figma
+
+```bash
+zengin figma export                          # zengin/tokens*.json -> figma/variables.json (the Variables payload)
+zengin figma plugin                          # a plugin into figma/plugin/ that imports that payload into any file
+zengin figma import figma/local.json         # what the plugin exported -> a report of what changed in Figma
+zengin figma import figma/local.json --write # and update the token files; then zengin tokens
+zengin figma connect --map figma/map.json    # Code Connect files from zengin/components.json
+```
+
+One naming rule carries both directions: `color.primary.soft` is `color/primary/soft` in Figma with `var(--color-primary-soft)` as its code syntax. See [@zenginui/figma](../figma).
+
+## report and rollup
+
+```bash
+zengin report --out zengin-report.json                      # in each consuming repository, in CI
+zengin rollup reports/*.json --previous last.json           # across repositories; markdown by default
+zengin rollup reports/*.json --format html --out rollup.html
+```
+
+`report` is the check plus an inventory: component usage (adoption), suppressions with and without reasons, owned forks with their versions, uncontracted components, and the pinned system version. `rollup` ranks repositories by drift, shows violations per 100 files so sizes compare, flags who is behind the latest version, computes deltas against a previous rollup, and lists what needs attention in priority order. See [`@zenginui/rollup`](../rollup) for the workflow recipe.
+
+## explain
+
+```bash
+zengin explain                     # all rules, plus how scope and suppressions work
+zengin explain classname-policy
+```
+
+## init
+
+```bash
+zengin init                     # a commented zengin.config.yaml template
+zengin init --from shadcn       # derive zengin/tokens.json, zengin/components.json and a config from a shadcn/ui project
+zengin init --from package @umami/react-zen   # the same from an installed design-system package: its CSS variables (names kept) and .d.ts
+zengin init --from shadcn --dir ../app --force
+```
+
+The template refuses to overwrite an existing config. The shadcn path reads the theme CSS, the Tailwind config and `components/ui`, writes the definitions, and prints the defaults worth reviewing. See [`@zenginui/adapter-shadcn`](../adapter-shadcn). The package path reads `node_modules/<name>`: its theme stylesheet, its precompiled utilities and its `.d.ts`; see [`@zenginui/adapter-css`](../adapter-css).
+
+## Not included, on purpose
+
+`zengin fix` would apply `exact` fixes automatically. It is a small addition, and it is left out for now because the first milestone's non-goals exclude tools that edit code. It is a candidate for later once the false-positive rate of the rules is measured on a real codebase.
+
+## History
+
+```bash
+zengin report --into reports          # files reports/<repo>/<time>.json instead of one --out file
+zengin rollup reports --format html --out public/rollup/index.html
+zengin report --into reports --at 2026-09-01T06:00:00Z --commit abc1234 --ref main   # backfill from an older checkout
+```
+
+`zengin rollup` accepts directories and reads every snapshot under them as history: the newest run per repository is the row, the one before is the delta, the series is the trend. See [`@zenginui/rollup`](../rollup#history-and-trends).

package/dist/check.d.ts

@@ -0,0 +1,38 @@
+import { type RuleId, type Severity, type Summary, type Violation } from "@zenginui/engine";
+export type Format = "pretty" | "json" | "github";
+export interface CheckOptions {
+    /** Explicit config path. Otherwise the nearest zengin.config.yaml walking up from cwd. */
+    config?: string;
+    cwd: string;
+    /** Project-relative or absolute paths. Empty means the whole scope. */
+    paths: string[];
+    /** Only files changed relative to this git ref. */
+    changed?: string;
+    /** Only files staged in git. */
+    staged: boolean;
+    rules?: RuleId[];
+    severity?: Severity;
+    /** Lowest severity that makes the exit code non-zero. */
+    failOn: Severity | "never";
+    format: Format;
+    /** Maximum violations rendered in pretty output. */
+    max: number;
+}
+export declare const DEFAULT_CHECK: Omit<CheckOptions, "cwd">;
+export interface CheckResult {
+    projectDir: string;
+    configPath: string;
+    system: {
+        package: string;
+        version: string;
+    };
+    filesChecked: number;
+    violations: Violation[];
+    summary: Summary;
+    /** 0 clean or below fail-on, 1 violations at or above fail-on. Usage and config errors throw. */
+    exitCode: 0 | 1;
+}
+export declare function findConfig(explicit: string | undefined, startDir: string): string;
+export declare function runCheck(opts: CheckOptions): Promise<CheckResult>;
+/** Reads a file for callers that want to show source context. */
+export declare function readSource(projectDir: string, rel: string): string | undefined;

package/dist/check.js

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { createEngine, loadConfigFile, readProjectFiles, resolveConfig, summarize, } from "@zenginui/engine";
+import { changedFiles, stagedFiles } from "./git.js";
+export const DEFAULT_CHECK = { paths: [], staged: false, failOn: "error", format: "pretty", max: 200 };
+const CONFIG_NAMES = ["zengin.config.yaml", "zengin.config.yml"];
+const RANK = { error: 3, warn: 2, info: 1 };
+export function findConfig(explicit, startDir) {
+    if (explicit) {
+        const p = resolve(startDir, explicit);
+        if (!existsSync(p))
+            throw new Error(`Config not found at ${p}.`);
+        return p;
+    }
+    let dir = resolve(startDir);
+    for (;;) {
+        for (const name of CONFIG_NAMES) {
+            const p = join(dir, name);
+            if (existsSync(p))
+                return p;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error(`No zengin.config.yaml found in ${startDir} or any parent. Run \`zengin init\` to create one, or pass --config.`);
+}
+function selectFiles(opts, projectDir, config) {
+    const inScope = readProjectFiles(projectDir, config.scope.include, config.scope.exclude);
+    const byPath = new Map(inScope.map((f) => [f.path, f]));
+    const toRel = (p) => relative(projectDir, isAbsolute(p) ? p : resolve(opts.cwd, p)).replace(/\\/g, "/");
+    let wanted;
+    if (opts.staged)
+        wanted = stagedFiles(projectDir);
+    else if (opts.changed !== undefined)
+        wanted = changedFiles(projectDir, opts.changed);
+    if (wanted) {
+        const explicit = opts.paths.map(toRel);
+        return wanted
+            .filter((p) => byPath.has(p) && (explicit.length === 0 || explicit.some((e) => p === e || p.startsWith(e + "/"))))
+            .map((p) => byPath.get(p));
+    }
+    if (opts.paths.length === 0)
+        return inScope;
+    const out = [];
+    for (const raw of opts.paths) {
+        const rel = toRel(raw);
+        const abs = join(projectDir, rel);
+        if (!existsSync(abs))
+            throw new Error(`Path not found: ${raw}`);
+        const hit = byPath.get(rel);
+        if (hit) {
+            out.push(hit);
+            continue;
+        }
+        // A directory: every in-scope file under it. A file outside scope: nothing, by design.
+        for (const f of inScope)
+            if (f.path.startsWith(rel + "/"))
+                out.push(f);
+    }
+    return out;
+}
+export async function runCheck(opts) {
+    const configPath = findConfig(opts.config, opts.cwd);
+    const { config, dir } = loadConfigFile(configPath);
+    const resolved = resolveConfig(config, dir);
+    const engine = await createEngine(resolved);
+    const files = selectFiles(opts, dir, resolved);
+    // Stylesheets outside the selection still resolve class names for the files in it.
+    engine.loadStylesheets(readProjectFiles(dir, resolved.scope.include, resolved.scope.exclude).filter((f) => /\.css$/.test(f.path)));
+    let violations = engine.check(files);
+    if (opts.rules)
+        violations = violations.filter((v) => opts.rules.includes(v.rule));
+    if (opts.severity)
+        violations = violations.filter((v) => v.severity === opts.severity);
+    const failing = opts.failOn !== "never" && violations.some((v) => RANK[v.severity] >= RANK[opts.failOn]);
+    return {
+        projectDir: dir,
+        configPath,
+        system: { package: resolved.system.package, version: resolved.system.version },
+        filesChecked: files.length,
+        violations,
+        summary: summarize(violations),
+        exitCode: failing ? 1 : 0,
+    };
+}
+/** Reads a file for callers that want to show source context. */
+export function readSource(projectDir, rel) {
+    const p = join(projectDir, rel);
+    return existsSync(p) ? readFileSync(p, "utf8") : undefined;
+}

package/dist/format-cli.d.ts

@@ -0,0 +1,6 @@
+import type { CheckResult } from "./check.js";
+/** Terminal rendering: grouped by file, one line per violation, fix underneath. */
+export declare function renderPretty(result: CheckResult, max: number): string;
+/** GitHub Actions workflow commands, so violations become inline annotations on the pull request. */
+export declare function renderGithub(result: CheckResult): string;
+export declare function renderJson(result: CheckResult): string;

package/dist/format-cli.js

@@ -0,0 +1,65 @@
+import { renderSummary } from "@zenginui/engine";
+const useColor = () => process.stdout.isTTY === true && !process.env["NO_COLOR"] && process.env["TERM"] !== "dumb";
+function paint(code) {
+    return useColor() ? (s) => `[${code}m${s}` : (s) => s;
+}
+const bold = paint("1");
+const dim = paint("2");
+const red = paint("31");
+const yellow = paint("33");
+const blue = paint("34");
+const green = paint("32");
+const cyan = paint("36");
+const SEVERITY_PAINT = { error: red, warn: yellow, info: blue };
+/** Terminal rendering: grouped by file, one line per violation, fix underneath. */
+export function renderPretty(result, max) {
+    const { violations, filesChecked, system } = result;
+    const lines = [];
+    const shown = violations.slice(0, max);
+    let current = "";
+    for (const v of shown) {
+        if (v.file !== current) {
+            current = v.file;
+            if (lines.length)
+                lines.push("");
+            lines.push(bold(v.file));
+        }
+        const loc = dim(`${v.range.start.line}:${v.range.start.col}`);
+        lines.push(`  ${loc}  ${SEVERITY_PAINT[v.severity](v.severity.padEnd(5))}  ${cyan(v.rule)}  ${v.message}`);
+        lines.push(`         ${dim("found")}  ${oneLine(v.found)}`);
+        if (v.fix.replace !== null)
+            lines.push(`         ${dim(`fix (${v.fix.confidence})`)}  ${green(oneLine(v.fix.replace))}`);
+        if (v.fix.note)
+            lines.push(`         ${dim("note")}  ${v.fix.note}`);
+        if (v.note)
+            lines.push(`         ${dim("note")}  ${v.note}`);
+    }
+    if (lines.length)
+        lines.push("");
+    const summary = renderSummary(result.summary);
+    const tail = `${filesChecked} file${filesChecked === 1 ? "" : "s"} checked against ${system.package}@${system.version}: ${summary}`;
+    lines.push(violations.length ? (result.exitCode ? red(tail) : yellow(tail)) : green(tail));
+    if (shown.length < violations.length)
+        lines.push(dim(`Showing the first ${shown.length}. Raise --max or use --format json for all.`));
+    return lines.join("\n");
+}
+/** GitHub Actions workflow commands, so violations become inline annotations on the pull request. */
+export function renderGithub(result) {
+    const level = (s) => (s === "error" ? "error" : s === "warn" ? "warning" : "notice");
+    const esc = (s) => s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+    const prop = (s) => esc(s).replace(/:/g, "%3A").replace(/,/g, "%2C");
+    const lines = result.violations.map((v) => {
+        const fix = v.fix.replace !== null ? ` Fix (${v.fix.confidence}): ${v.fix.replace}` : "";
+        return `::${level(v.severity)} file=${prop(v.file)},line=${v.range.start.line},endLine=${v.range.end.line},col=${v.range.start.col},endColumn=${v.range.end.col},title=${prop(`zengin ${v.rule}`)}::${esc(v.message + fix)}`;
+    });
+    lines.push(`${result.filesChecked} files checked against ${result.system.package}@${result.system.version}: ${renderSummary(result.summary)}`);
+    return lines.join("\n");
+}
+export function renderJson(result) {
+    const { projectDir, configPath, system, filesChecked, summary, violations, exitCode } = result;
+    return JSON.stringify({ projectDir, configPath, system, filesChecked, exitCode, summary, violations }, null, 2);
+}
+function oneLine(s) {
+    const flat = s.replace(/\s+/g, " ").trim();
+    return flat.length > 120 ? flat.slice(0, 117) + "..." : flat;
+}

package/dist/git.d.ts

@@ -0,0 +1,4 @@
+/** Files added, copied, modified or renamed relative to `ref`, plus uncommitted and untracked changes. */
+export declare function changedFiles(projectDir: string, ref: string): string[];
+/** Files staged for the next commit. */
+export declare function stagedFiles(projectDir: string): string[];

package/dist/git.js

@@ -0,0 +1,39 @@
+import { execFileSync } from "node:child_process";
+import { join, relative } from "node:path";
+function git(projectDir, args) {
+    let out;
+    try {
+        out = execFileSync("git", args, { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    }
+    catch (e) {
+        const msg = e instanceof Error && "stderr" in e ? String(e.stderr).trim() : String(e);
+        throw new Error(`git ${args.join(" ")} failed in ${projectDir}: ${msg || "is this a git repository?"}`);
+    }
+    return out
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean);
+}
+/**
+ * git reports paths relative to the repository root. The project may be a package inside a monorepo,
+ * so every path is re-based onto the project directory and anything outside it is dropped.
+ */
+function toProject(projectDir, rootRelative) {
+    const root = git(projectDir, ["rev-parse", "--show-toplevel"])[0];
+    return rootRelative
+        .map((p) => relative(projectDir, join(root, p)).replace(/\\/g, "/"))
+        .filter((p) => p && !p.startsWith("../") && p !== "..")
+        .sort();
+}
+/** Files added, copied, modified or renamed relative to `ref`, plus uncommitted and untracked changes. */
+export function changedFiles(projectDir, ref) {
+    const base = ref || "HEAD";
+    const committed = git(projectDir, ["diff", "--name-only", "--diff-filter=ACMR", `${base}...HEAD`]);
+    const working = git(projectDir, ["diff", "--name-only", "--diff-filter=ACMR", "HEAD"]);
+    const untracked = git(projectDir, ["ls-files", "--others", "--exclude-standard", "--full-name"]);
+    return toProject(projectDir, [...new Set([...committed, ...working, ...untracked])]);
+}
+/** Files staged for the next commit. */
+export function stagedFiles(projectDir) {
+    return toProject(projectDir, git(projectDir, ["diff", "--name-only", "--cached", "--diff-filter=ACMR"]));
+}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { type CheckOptions } from "./check.js";
+import { type ScaffoldOptions } from "./scaffold.js";
+interface Parsed {
+    command: "check" | "explain" | "init" | "report" | "rollup" | "create" | "add" | "tokens" | "registry" | "theme" | "fonts" | "icons" | "upgrade" | "brand" | "figma" | "mock" | "help";
+    positional: string[];
+    check: CheckOptions;
+    init: {
+        from?: string;
+        dir?: string;
+        force: boolean;
+    };
+    report: {
+        repo?: string;
+        includeViolations: boolean;
+        out?: string;
+        into?: string;
+        at?: string;
+        commit?: string;
+        ref?: string;
+    };
+    rollup: {
+        previous?: string;
+        format: "markdown" | "json" | "html";
+        out?: string;
+    };
+    scaffold: ScaffoldOptions;
+}
+export declare function parseArgs(argv: string[], cwd: string): Parsed;
+export declare function explain(rule: string | undefined): string;
+export {};