@chiralkit/cli 0.1.0-alpha.0

package/dist/spec-from-stencil.js

@@ -0,0 +1,275 @@
+import { access, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseModule } from "@chiralkit/registry-schema";
+import { resolveKitsRoot } from "@chiralkit/kits";
+import { MODULE_ENVELOPE_FILENAME } from "./registry-layout.js";
+// Resolve the registry root via workspace alias — no relative path.
+const registryRoot = join(resolveKitsRoot(), "ui", "registry");
+// spec-from-stencil is Stencil-only, so its default target (when the caller
+// doesn't pass an explicit registryDir — i.e. the direct `chiralkit spec
+// from-stencil <name>` CLI command) always lives under the design-system
+// family.
+const DESIGN_SYSTEM_FAMILY = "design-system";
+// The @Prop decorator regex captures:
+//   1: name
+//   2: TS type annotation (may be a union, wraps across lines in source
+//      but we normalize whitespace before matching)
+//   3: default value (may be undefined)
+// A trailing `?` on the name means optional; `!` means required-no-default.
+// Both `:type` and `=default` are optional individually — Stencil accepts
+// `@Prop() disabled = false;` (type inferred from initializer) as well as
+// `@Prop() code!: string;` (required, no default). When only a default is
+// present, `parsePropTypeFromDefault` recovers the type from typeof(default).
+const PROP_RE = /@Prop\(\)\s+(\w+)([!?])?\s*(?::\s*([^=;]+?))?\s*(?:=\s*([^;]+?))?\s*;/g;
+// The @Event decorator regex:
+//   1: name
+//   2: payload type (inside EventEmitter<...>)
+const EVENT_RE = /@Event\(\)\s+(\w+)!?\s*:\s*EventEmitter\s*<\s*([^>]+?)\s*>\s*;/g;
+// @Component({ tag: "ds-foo", ... }) — extracts the tag name.
+const COMPONENT_TAG_RE = /@Component\s*\(\s*\{[^}]*?\btag\s*:\s*["']([^"']+)["']/;
+// CSS token references — captures category + name from `var(--ds-<cat>-<name>)`.
+const TOKEN_RE = /var\(--ds-([a-z]+)-([a-z0-9-]+)\)/g;
+// Parses one prop's type annotation into a structured shape. Handles:
+//   - `boolean` → { type: boolean }
+//   - `string` → { type: string }
+//   - `number` → { type: number }
+//   - `"a" | "b" | "c"` → { type: enum, values: [a, b, c] }
+//   - Anything else → { type: string } with a WARN comment (safe default).
+function parsePropType(annotation) {
+    // Normalize: collapse whitespace, trim, and strip an optional leading `|`
+    // (TypeScript allows `variant: | "a" | "b"` — common for multi-line
+    // unions like ds-badge's). Without stripping the leading pipe the
+    // enum-shape regex below fails to match those (subtle plan-authoring bug
+    // caught during Plan 2 Task 1 execution).
+    const normalized = annotation
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/^\|\s*/, "");
+    if (normalized === "boolean")
+        return { type: "boolean" };
+    if (normalized === "string")
+        return { type: "string" };
+    if (normalized === "number")
+        return { type: "number" };
+    // String-literal union → enum. Matches `"a" | "b"` or `'a' | 'b'`.
+    const litRe = /["']([^"']+)["']/g;
+    const values = [];
+    let m;
+    while ((m = litRe.exec(normalized)) !== null) {
+        if (m[1] !== undefined)
+            values.push(m[1]);
+    }
+    if (values.length > 0 && /^["'].+["']\s*(\|\s*["'].+["']\s*)+$/.test(normalized)) {
+        return { type: "enum", values };
+    }
+    // Unknown / complex type — fall back to string (spec.json only handles the
+    // four primitives above; anything richer needs human review anyway).
+    return { type: "string" };
+}
+function parsePropDefault(raw) {
+    if (raw === undefined)
+        return undefined;
+    const t = raw.trim();
+    if (t === "true")
+        return true;
+    if (t === "false")
+        return false;
+    if (/^-?\d+(\.\d+)?$/.test(t))
+        return Number(t);
+    const stringMatch = t.match(/^["']([^"']*)["']$/);
+    if (stringMatch)
+        return stringMatch[1];
+    return undefined;
+}
+// Falls back to inferring a prop's type from its default value when the
+// source has no explicit annotation (Stencil pattern: `@Prop() flag = false;`).
+function parsePropTypeFromDefault(parsedDefault) {
+    const t = typeof parsedDefault;
+    if (t === "boolean")
+        return { type: "boolean" };
+    if (t === "number")
+        return { type: "number" };
+    return { type: "string" };
+}
+function extractProps(source) {
+    const normalized = source.replace(/\r\n/g, "\n");
+    // Collapse multi-line prop declarations onto one line so PROP_RE catches
+    // them (e.g. `@Prop() variant:\n | "a"\n | "b" = "a";` in ds-badge).
+    const flattened = normalized.replace(/@Prop\(\)[\s\S]*?;/g, (m) => m.replace(/\s+/g, " "));
+    const props = [];
+    let m;
+    while ((m = PROP_RE.exec(flattened)) !== null) {
+        const name = m[1];
+        const marker = m[2];
+        const typeAnnotation = m[3];
+        const defaultRaw = m[4];
+        const parsedDefault = defaultRaw !== undefined ? parsePropDefault(defaultRaw) : undefined;
+        const parsed = typeAnnotation !== undefined
+            ? parsePropType(typeAnnotation)
+            : parsePropTypeFromDefault(parsedDefault);
+        props.push({
+            name,
+            type: parsed.type,
+            ...(parsed.values ? { values: parsed.values } : {}),
+            ...(parsedDefault !== undefined ? { default: parsedDefault } : {}),
+            optional: marker === "?" || defaultRaw !== undefined,
+        });
+    }
+    return props;
+}
+function extractEvents(source) {
+    const events = [];
+    let m;
+    while ((m = EVENT_RE.exec(source)) !== null) {
+        events.push({ name: m[1], payload: m[2].trim() });
+    }
+    return events;
+}
+function extractTag(source) {
+    const m = source.match(COMPONENT_TAG_RE);
+    return m?.[1];
+}
+function extractTokensUsed(css) {
+    const result = {
+        colors: [],
+        spacing: [],
+        radius: [],
+        font: [],
+        shadow: [],
+    };
+    const seen = new Set();
+    let m;
+    while ((m = TOKEN_RE.exec(css)) !== null) {
+        const category = m[1];
+        const name = m[2];
+        const key = `${category}:${name}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        // Map category to the tokens_used bucket. Unknown categories are skipped.
+        switch (category) {
+            case "color":
+                result.colors.push(name);
+                break;
+            case "spacing":
+                result.spacing.push(name);
+                break;
+            case "radius":
+                result.radius.push(name);
+                break;
+            case "font":
+                result.font.push(name);
+                break;
+            case "shadow":
+                result.shadow.push(name);
+                break;
+            // ignore other categories (e.g. --ds-transition-*) until schema grows
+        }
+    }
+    return result;
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runFromStencil(name, opts) {
+    // opts.registryDir / opts.sourceDir let callers (e.g. runScaffoldRegistry)
+    // point this extractor at a tmpdir fixture or a scaffold-in-progress
+    // layout instead of the workspace-resolved @chiralkit/registry package.
+    // The existing `spec from-stencil` CLI command never passes either, so
+    // it falls through to the original defaults unchanged.
+    const moduleDir = opts.registryDir ?? join(registryRoot, DESIGN_SYSTEM_FAMILY, name);
+    const stencilDir = opts.sourceDir ?? join(moduleDir, "implementations", "stencil");
+    // The envelope (module.json) is only expected to already exist for the
+    // "regenerate spec.json for an existing registry module" flow. When
+    // opts.sourceDir is provided, the caller is scaffolding a brand-new module
+    // (module.json hasn't been written yet) and already knows this is a
+    // Stencil component — skip the envelope lookup/validation in that case.
+    let envelopeTag;
+    if (opts.sourceDir === undefined) {
+        const envelopePath = join(moduleDir, MODULE_ENVELOPE_FILENAME);
+        if (!(await fileExists(envelopePath))) {
+            console.error(`spec from-stencil: no such module '${name}' at ${moduleDir}`);
+            process.exit(1);
+        }
+        const envelope = parseModule(JSON.parse(await readFile(envelopePath, "utf8")));
+        if (envelope.type !== "ui-component") {
+            console.error(`spec from-stencil: '${name}' is type ${envelope.type}, not ui-component`);
+            process.exit(1);
+        }
+        const envelopeSpec = envelope.spec;
+        if (envelopeSpec.tech !== "stencil") {
+            console.error(`spec from-stencil: '${name}' spec.tech is '${envelopeSpec.tech}', not stencil`);
+            process.exit(1);
+        }
+        envelopeTag = envelopeSpec.tag;
+    }
+    const entries = await readdir(stencilDir);
+    const tsxName = entries.find((e) => e.endsWith(".tsx"));
+    const cssName = entries.find((e) => e.endsWith(".css"));
+    if (!tsxName) {
+        console.error(`spec from-stencil: no .tsx file found under ${stencilDir}`);
+        process.exit(1);
+    }
+    const tsxSource = await readFile(join(stencilDir, tsxName), "utf8");
+    const cssSource = cssName
+        ? await readFile(join(stencilDir, cssName), "utf8")
+        : "";
+    const tag = extractTag(tsxSource) ?? envelopeTag ?? `ds-${name}`;
+    const props = extractProps(tsxSource);
+    const events = extractEvents(tsxSource);
+    const tokens = extractTokensUsed(cssSource);
+    // Build the draft. Every top-level key is optional per componentContractSchema
+    // except name and version; we emit only what we have.
+    const draft = {
+        name,
+        version: "1.0.0",
+    };
+    if (props.length > 0) {
+        draft.props = Object.fromEntries(props.map((p) => {
+            const shape = { type: p.type };
+            if (p.values)
+                shape.values = p.values;
+            if (p.default !== undefined)
+                shape.default = p.default;
+            return [p.name, shape];
+        }));
+    }
+    if (events.length > 0) {
+        draft.events = Object.fromEntries(events.map((e) => [e.name, e.payload ? { payload: e.payload } : {}]));
+    }
+    // Only include tokens buckets that have at least one entry — schema allows
+    // omission of any bucket, so the output stays minimal.
+    const tokensFiltered = Object.fromEntries(Object.entries(tokens).filter(([, v]) => v.length > 0));
+    if (Object.keys(tokensFiltered).length > 0) {
+        draft.tokens_used = tokensFiltered;
+    }
+    // Write output.
+    const outPath = join(moduleDir, "spec.json");
+    const exists = await fileExists(outPath);
+    if (exists && !opts.force) {
+        console.error(`spec from-stencil: ${outPath} already exists; pass --force to overwrite`);
+        process.exit(1);
+    }
+    // moduleDir may not exist yet when opts.registryDir points at a
+    // scaffold-in-progress target (runScaffoldRegistry calls this before the
+    // rest of the registry entry is written). No-op for the existing-module
+    // flow, where moduleDir is already present.
+    await mkdir(moduleDir, { recursive: true });
+    await writeFile(outPath, JSON.stringify(draft, null, 2) + "\n", "utf8");
+    // Summary + explicit review-required nudge.
+    console.log(`Wrote draft: ${outPath}`);
+    console.log(`  tag:         ${tag}`);
+    console.log(`  props:       ${props.length}`);
+    console.log(`  events:      ${events.length}`);
+    console.log(`  tokens_used: ${Object.values(tokens).reduce((s, arr) => s + arr.length, 0)} references across ${Object.keys(tokensFiltered).length} categories`);
+    console.log("");
+    console.log("This is a draft. Review and add slot, a11y, and state_machine (for patterns) by hand.");
+    console.log("Complex prop types (non-primitive, non-enum unions) fell back to 'string' — verify and adjust.");
+}
+//# sourceMappingURL=spec-from-stencil.js.map

package/dist/spec-from-stencil.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-from-stencil.js","sourceRoot":"","sources":["../src/spec-from-stencil.ts"],"names":[],"mappings":"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"}

package/dist/spec.d.ts

@@ -0,0 +1 @@
+export declare function runSpec(rest: string[]): Promise<void>;

package/dist/spec.js

@@ -0,0 +1,60 @@
+import { runFromStencil } from "./spec-from-stencil.js";
+import { runFromReact } from "./spec-from-react.js";
+// Subcommand dispatcher for `chiralkit spec ...`. Currently one action;
+// grows as Plan 2+ add spec-authoring aids (spec new, spec validate, ...).
+export async function runSpec(rest) {
+    const [action, ...args] = rest;
+    switch (action) {
+        case "from-stencil": {
+            const name = args[0];
+            if (!name) {
+                console.error("spec from-stencil: missing module name");
+                console.error("Usage: chiralkit spec from-stencil <name> [--force]");
+                process.exit(1);
+            }
+            const force = args.includes("--force");
+            await runFromStencil(name, { force });
+            return;
+        }
+        case "from-react": {
+            const sourcePath = args[0];
+            if (!sourcePath) {
+                console.error("spec from-react: missing source path");
+                console.error('Usage: chiralkit spec from-react <path-to-tsx> --tokens-map <path> [--name <slug>] [--export <Name>] [--version <semver>] [--out <path>] [--force] [--strict] [--dry-run]');
+                process.exit(1);
+            }
+            const tokensIdx = args.indexOf("--tokens-map");
+            if (tokensIdx === -1 || args[tokensIdx + 1] === undefined) {
+                console.error("spec from-react: --tokens-map <path> is required");
+                process.exit(1);
+            }
+            const tokensMapPath = args[tokensIdx + 1];
+            const readFlagValue = (flag) => {
+                const i = args.indexOf(flag);
+                return i === -1 ? undefined : args[i + 1];
+            };
+            await runFromReact(sourcePath, {
+                tokensMapPath,
+                name: readFlagValue("--name"),
+                exportName: readFlagValue("--export"),
+                version: readFlagValue("--version"),
+                outPath: readFlagValue("--out"),
+                force: args.includes("--force"),
+                strict: args.includes("--strict"),
+                dryRun: args.includes("--dry-run"),
+            });
+            return;
+        }
+        case undefined:
+            console.error("spec: missing action");
+            console.error("Actions:");
+            console.error("  from-stencil <name> [--force]");
+            console.error("  from-react <path-to-tsx> --tokens-map <path> [--name --export --version --out --force --strict --dry-run]");
+            process.exit(1);
+            return;
+        default:
+            console.error(`spec: unknown action '${action}'`);
+            process.exit(1);
+    }
+}
+//# sourceMappingURL=spec.js.map

package/dist/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"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"}

package/dist/tokens-map.d.ts

@@ -0,0 +1,11 @@
+export type TokensCategory = "colors" | "spacing" | "radius" | "font" | "shadow";
+export interface TokensMap {
+    readonly $schema?: string;
+    readonly generatedFrom?: string;
+    readonly colors: Readonly<Record<string, string>>;
+    readonly spacing: Readonly<Record<string, string>>;
+    readonly radius: Readonly<Record<string, string>>;
+    readonly font: Readonly<Record<string, string>>;
+    readonly shadow: Readonly<Record<string, string>>;
+}
+export declare function loadTokensMap(path: string): Promise<TokensMap>;

package/dist/tokens-map.js

@@ -0,0 +1,43 @@
+import { readFile } from "node:fs/promises";
+const CATEGORIES = [
+    "colors",
+    "spacing",
+    "radius",
+    "font",
+    "shadow",
+];
+// Loads and structurally validates a tokens map. Rejects with a clear error
+// on missing categories, non-object entries, or non-string values. The
+// validation is intentionally lax on the mapping itself (any Tailwind class
+// name is accepted as a key) — the domain check is "does the class name
+// appear in the source?" and that happens later in the extractor.
+export async function loadTokensMap(path) {
+    const raw = await readFile(path, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`tokens map at ${path} is not valid JSON: ${err.message}`);
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        throw new Error(`tokens map at ${path} must be a JSON object`);
+    }
+    const obj = parsed;
+    for (const cat of CATEGORIES) {
+        const val = obj[cat];
+        if (val === undefined) {
+            throw new Error(`tokens map at ${path} is missing category "${cat}" (expected object; may be empty)`);
+        }
+        if (val === null || typeof val !== "object" || Array.isArray(val)) {
+            throw new Error(`tokens map at ${path}: category "${cat}" must be a JSON object`);
+        }
+        for (const [k, v] of Object.entries(val)) {
+            if (typeof v !== "string") {
+                throw new Error(`tokens map at ${path}: ${cat}["${k}"] must be a string, got ${typeof v}`);
+            }
+        }
+    }
+    return parsed;
+}
+//# sourceMappingURL=tokens-map.js.map

package/dist/tokens-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens-map.js","sourceRoot":"","sources":["../src/tokens-map.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAc5C,MAAM,UAAU,GAA8B;IAC5C,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,MAAM;IACN,QAAQ;CACT,CAAC;AAEF,4EAA4E;AAC5E,uEAAuE;AACvE,4EAA4E;AAC5E,wEAAwE;AACxE,kEAAkE;AAClE,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAY;IAC9C,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACzC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,iBAAiB,IAAI,uBAAwB,GAAa,CAAC,OAAO,EAAE,CACrE,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAI,wBAAwB,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,GAAG,GAAG,MAAiC,CAAC;IAC9C,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACrB,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CACb,iBAAiB,IAAI,yBAAyB,GAAG,mCAAmC,CACrF,CAAC;QACJ,CAAC;QACD,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAClE,MAAM,IAAI,KAAK,CACb,iBAAiB,IAAI,eAAe,GAAG,yBAAyB,CACjE,CAAC;QACJ,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACzC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;gBAC1B,MAAM,IAAI,KAAK,CACb,iBAAiB,IAAI,KAAK,GAAG,KAAK,CAAC,4BAA4B,OAAO,CAAC,EAAE,CAC1E,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,MAAmB,CAAC;AAC7B,CAAC"}

package/dist/update.d.ts

@@ -0,0 +1,39 @@
+import { type ModuleType } from "@chiralkit/registry-schema";
+export interface ModuleUpdatePlan {
+    key: string;
+    name: string;
+    type: ModuleType;
+    fromVersion: string;
+    toVersion: string;
+    changes: FileChange[];
+    localEdits: LocalEdit[];
+}
+export interface FileChange {
+    kind: "modified" | "added" | "removed";
+    relPath: string;
+    patch: string;
+}
+export interface LocalEdit {
+    relPath: string;
+    patch: string;
+}
+export interface UpdateOptions {
+    moduleFilter?: string;
+    type?: ModuleType;
+    check?: boolean;
+    yes?: boolean;
+    cwd?: string;
+    confirm?: (message: string) => Promise<boolean>;
+    now?: () => string;
+    kitsRoot?: string;
+}
+export declare function runUpdate(argv: string[]): Promise<number>;
+export declare function runUpdateWith(opts: UpdateOptions): Promise<number>;
+export declare function unifiedDiff(fromLabel: string, toLabel: string, a: string, b: string): string;
+export interface LockInitOptions {
+    cwd?: string;
+    now?: () => string;
+    kitsRoot?: string;
+}
+export declare function runLock(argv: string[]): Promise<number>;
+export declare function runLockInit(opts: LockInitOptions): Promise<number>;