@twentyfirstmedia/ui 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Twentyfirst Media
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The kits bundle these fonts, each under the SIL Open Font License 1.1; their license
+files ship next to the fonts in each package's `dist/fonts`:
+
+- Plus Jakarta Sans (Halo)
+- IBM Plex Mono (Halo)
+- Geist and Geist Mono (Pro)

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @twentyfirstmedia/ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The CLI and MCP server of the [Twentyfirst UI](https://ui.twentyfirst.media) kits.
+
+[Website](https://ui.twentyfirst.media) · [Halo docs](https://ui.twentyfirst.media/halo/) · [Pro docs](https://ui.twentyfirst.media/pro/) · [GitHub](https://github.com/twentyfirstmedia/ui) · [llms.txt](https://ui.twentyfirst.media/llms.txt)
+
+## Set up an app
+
+```sh
+npx @twentyfirstmedia/ui init --kit halo      # or pro; --both loads both kits
+npx @twentyfirstmedia/ui add DataTable        # copy a component into components/ui to own it
+npx @twentyfirstmedia/ui list                 # every component, copied ones marked
+npx @twentyfirstmedia/ui diff DataTable       # compare your copy with the package
+```
+
+`init` installs the kit, imports its styles (and the Tailwind v4 preset when the app uses Tailwind), creates `components/ui-root.tsx` with the `UIProvider` and wires up the Next.js layout. Running it again changes nothing.
+
+## MCP server for coding agents
+
+![An agent using the MCP server](https://raw.githubusercontent.com/twentyfirstmedia/ui/main/.github/assets/agents-light.png)
+
+```sh
+npx @twentyfirstmedia/ui mcp init                         # Claude Code, Cursor, VS Code + AGENTS.md rules
+claude mcp add twentyfirst-ui -- npx -y @twentyfirstmedia/ui mcp --kit halo
+```
+
+A stdio MCP server with the bundled docs of this version: offline, no account, no runtime dependencies.
+
+| Tool | Returns |
+| --- | --- |
+| `search_docs` | Matching components, patterns, guides, tokens and icons |
+| `list_components` | Every component page by group |
+| `get_component` | Import, description, example code and props |
+| `get_pattern` | A complete screen with its code |
+| `get_guide` | Installation, CLI, theming, AI agents, status and approvals |
+| `get_tokens` | Token names with Halo and Pro values |
+| `list_icons` | Every valid icon name |
+| `check_usage` | Unknown components, props or icons, missing required props, colour literals |
+
+Every page is also a resource (`twentyfirst-ui://components/DataTable`), and the prompts `build_screen` and `review_ui` start the two most common jobs. Docs: [AI agents and MCP](https://ui.twentyfirst.media/halo/ai/).
+
+## License
+
+[MIT](https://github.com/twentyfirstmedia/ui/blob/main/LICENSE) © Twentyfirst Media. Fonts under the SIL Open Font License 1.1.

package/dist/add.d.ts

@@ -0,0 +1,10 @@
+import { type Logger } from "./util.js";
+export interface AddOptions {
+    cwd: string;
+    components: string[];
+    overwrite?: boolean;
+    log: Logger;
+}
+export declare function targetPath(cwd: string, dir: string, name: string): string;
+export declare function add(o: AddOptions): string[];
+//# sourceMappingURL=add.d.ts.map

package/dist/add.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../src/add.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,MAAM,EAA4B,MAAM,WAAW,CAAC;AAElE,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED,wBAAgB,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,EAAE,CAqB3C"}

package/dist/add.js

@@ -0,0 +1,28 @@
+import { existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { buildCopy, loadCore } from "./source.js";
+import { kebab, readConfig, write } from "./util.js";
+export function targetPath(cwd, dir, name) {
+    return join(cwd, dir, `${kebab(name)}.tsx`);
+}
+export function add(o) {
+    const cfg = readConfig(o.cwd);
+    const dir = cfg?.components ?? "components/ui";
+    const core = loadCore(o.cwd);
+    const written = [];
+    for (const name of o.components) {
+        const copy = buildCopy(core, name);
+        const path = targetPath(o.cwd, dir, name);
+        if (existsSync(path) && !o.overwrite) {
+            o.log.warn(`  · ${relative(o.cwd, path)} exists; use --overwrite to replace it`);
+            continue;
+        }
+        write(path, copy.content);
+        written.push(path);
+        o.log.log(`  ✓ ${relative(o.cwd, path)}`);
+    }
+    if (written.length)
+        o.log.log(`\nImport from the copy instead of the package, e.g. import { ${o.components[0]} } from "@/${dir}/${kebab(o.components[0])}";`);
+    return written;
+}
+//# sourceMappingURL=add.js.map

package/dist/add.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.js","sourceRoot":"","sources":["../src/add.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAe,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AASlE,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,GAAW,EAAE,IAAY;IAC/D,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,CAAa;IAC/B,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,GAAG,GAAG,GAAG,EAAE,UAAU,IAAI,eAAe,CAAC;IAC/C,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACnC,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;QAC1C,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;YACrC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,wCAAwC,CAAC,CAAC;YACjF,SAAS;QACX,CAAC;QACD,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,IAAI,OAAO,CAAC,MAAM;QAChB,CAAC,CAAC,GAAG,CAAC,GAAG,CACP,gEAAgE,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,cAAc,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAW,CAAC,IAAI,CACzI,CAAC;IACJ,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/diff.d.ts

@@ -0,0 +1,6 @@
+import { type Logger } from "./util.js";
+/** Line diff (LCS) as unified-style lines prefixed with " ", "-" or "+". */
+export declare function lineDiff(a: string[], b: string[]): string[];
+/** Shows how the local copy differs from the current package source. Returns the number of changed lines. */
+export declare function diff(cwd: string, name: string, log: Logger): number;
+//# sourceMappingURL=diff.d.ts.map

package/dist/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,MAAM,EAAoB,MAAM,WAAW,CAAC;AAE1D,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAwB3D;AAKD,6GAA6G;AAC7G,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAqBnE"}

package/dist/diff.js

@@ -0,0 +1,57 @@
+import { relative } from "node:path";
+import { buildCopy, loadCore } from "./source.js";
+import { targetPath } from "./add.js";
+import { read, readConfig } from "./util.js";
+/** Line diff (LCS) as unified-style lines prefixed with " ", "-" or "+". */
+export function lineDiff(a, b) {
+    const n = a.length, m = b.length;
+    const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--)
+        for (let j = m - 1; j >= 0; j--)
+            dp[i][j] =
+                a[i] === b[j]
+                    ? dp[i + 1][j + 1] + 1
+                    : Math.max(dp[i + 1][j], dp[i][j + 1]);
+    const out = [];
+    let i = 0, j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            out.push(" " + a[i]);
+            i++;
+            j++;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1])
+            out.push("-" + a[i++]);
+        else
+            out.push("+" + b[j++]);
+    }
+    while (i < n)
+        out.push("-" + a[i++]);
+    while (j < m)
+        out.push("+" + b[j++]);
+    return out;
+}
+const body = (s) => s.split("\n").filter((l) => !/^\/\* (\w+: copied from|`twentyfirst-ui diff)/.test(l));
+/** Shows how the local copy differs from the current package source. Returns the number of changed lines. */
+export function diff(cwd, name, log) {
+    const dir = readConfig(cwd)?.components ?? "components/ui";
+    const path = targetPath(cwd, dir, name);
+    const local = read(path);
+    if (local == null)
+        throw new Error(`${relative(cwd, path)} does not exist. Add it with \`twentyfirst-ui add ${name}\`.`);
+    const upstream = buildCopy(loadCore(cwd), name).content;
+    const lines = lineDiff(body(upstream), body(local));
+    const changed = lines.filter((l) => l[0] !== " ");
+    if (!changed.length) {
+        log.log(`${name}: no changes against the package.`);
+        return 0;
+    }
+    log.log(`--- ${name} (package)\n+++ ${relative(cwd, path)} (yours)`);
+    lines.forEach((l, k) => {
+        const near = lines.slice(Math.max(0, k - 2), k + 3).some((x) => x[0] !== " ");
+        if (near)
+            log.log(l);
+    });
+    return changed.length;
+}
+//# sourceMappingURL=diff.js.map

package/dist/diff.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { type Logger } from "./util.js";
+export declare function parseArgs(argv: string[]): {
+    cmd: string;
+    args: string[];
+    flags: Record<string, string | boolean>;
+};
+/** Exit code; a promise while the MCP server runs (it resolves when stdin ends). */
+export declare function run(argv: string[], log?: Logger): number | Promise<number>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAWA,OAAO,EAA2B,KAAK,MAAM,EAAc,MAAM,WAAW,CAAC;AAsB7E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;CACzC,CAsBA;AASD,oFAAoF;AACpF,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAsB,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuEzF"}

package/dist/index.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { add } from "./add.js";
+import { diff } from "./diff.js";
+import { init } from "./init.js";
+import { list } from "./list.js";
+import { theme } from "./theme.js";
+import { createServer, loadKnowledge, serveStdio } from "./mcp.js";
+import { mcpInit, parseClients } from "./mcp-init.js";
+import { consoleLogger, readConfig } from "./util.js";
+const HELP = `twentyfirst-ui: set up and copy components of the Twentyfirst UI kits
+
+Usage
+  twentyfirst-ui init [--kit halo|pro] [--both] [--no-install] [--components components/ui]
+  twentyfirst-ui add <Component…> [--overwrite]
+  twentyfirst-ui list
+  twentyfirst-ui diff <Component>
+  twentyfirst-ui theme <preset|#colour[,#dark]|shadcn-theme.css> [--kit halo|pro] [--both] [--out app/theme.css]
+      write a shadcn-style theme (presets: blue, violet, emerald, orange, rose, teal) and import it
+  twentyfirst-ui mcp [--kit halo|pro]
+      start the MCP server for coding agents (stdio)
+  twentyfirst-ui mcp init [--client claude,cursor,vscode|all] [--kit halo|pro] [--no-rules]
+      register the MCP server in .mcp.json, .cursor/mcp.json and .vscode/mcp.json
+      and add the kit rules to AGENTS.md (and CLAUDE.md when it exists)
+
+Options
+  --cwd <dir>   run in another directory
+  --kit         defaults to the kit in twentyfirst.json, else halo
+`;
+export function parseArgs(argv) {
+    const [cmd = "help", ...rest] = argv;
+    const args = [];
+    const flags = {};
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a.startsWith("--no-"))
+            flags[a.slice(5)] = false;
+        else if (a.startsWith("--")) {
+            const [k, v] = a.slice(2).split("=");
+            const next = rest[i + 1];
+            if (v !== undefined)
+                flags[k] = v;
+            else if (next &&
+                !next.startsWith("--") &&
+                ["kit", "cwd", "components", "out", "client"].includes(k)) {
+                flags[k] = next;
+                i++;
+            }
+            else
+                flags[k] = true;
+        }
+        else
+            args.push(a);
+    }
+    return { cmd, args, flags };
+}
+/** The kit from --kit, else twentyfirst.json, else halo. */
+function resolveKit(flag, cwd) {
+    const kit = typeof flag === "string" ? flag : (readConfig(cwd)?.kit ?? "halo");
+    if (kit !== "halo" && kit !== "pro")
+        throw new Error(`--kit must be halo or pro, not ${kit}`);
+    return kit;
+}
+/** Exit code; a promise while the MCP server runs (it resolves when stdin ends). */
+export function run(argv, log = consoleLogger) {
+    const { cmd, args, flags } = parseArgs(argv);
+    const cwd = resolve(typeof flags.cwd === "string" ? flags.cwd : process.cwd());
+    try {
+        switch (cmd) {
+            case "init": {
+                const kit = (flags.kit ?? "halo");
+                if (kit !== "halo" && kit !== "pro")
+                    throw new Error(`--kit must be halo or pro, not ${String(kit)}`);
+                init({
+                    cwd,
+                    kit,
+                    both: flags.both === true,
+                    install: flags.install !== false,
+                    components: typeof flags.components === "string" ? flags.components : undefined,
+                    log,
+                });
+                return 0;
+            }
+            case "add":
+                if (!args.length)
+                    throw new Error("Name at least one component: twentyfirst-ui add Button");
+                add({ cwd, components: args, overwrite: flags.overwrite === true, log });
+                return 0;
+            case "list":
+                list(cwd, log);
+                return 0;
+            case "diff":
+                if (!args[0])
+                    throw new Error("Name a component: twentyfirst-ui diff Button");
+                diff(cwd, args[0], log);
+                return 0;
+            case "theme": {
+                if (!args[0])
+                    throw new Error("Name a preset, a colour or a shadcn theme file: twentyfirst-ui theme blue | #2563eb | theme.css");
+                const kit = typeof flags.kit === "string" ? resolveKit(flags.kit, cwd) : undefined;
+                theme({
+                    cwd,
+                    source: args[0],
+                    kit,
+                    both: flags.both === true ? true : undefined,
+                    out: typeof flags.out === "string" ? flags.out : undefined,
+                    log,
+                });
+                return 0;
+            }
+            case "mcp": {
+                const sub = args[0];
+                const kit = resolveKit(flags.kit, cwd);
+                if (sub === "init") {
+                    mcpInit({
+                        cwd,
+                        kit,
+                        clients: parseClients(flags.client),
+                        rules: flags.rules !== false,
+                        log,
+                    });
+                    return 0;
+                }
+                if (sub)
+                    throw new Error(`Unknown mcp command "${sub}". Use: twentyfirst-ui mcp [init]`);
+                const server = createServer(loadKnowledge(), { kit });
+                return serveStdio(server, { onError: (m) => log.warn(m) }).then(() => 0);
+            }
+            default:
+                log.log(HELP);
+                return cmd === "help" || flags.help ? 0 : 1;
+        }
+    }
+    catch (e) {
+        log.warn(`Error: ${e.message}`);
+        return 1;
+    }
+}
+const stderrLogger = {
+    log: (m) => console.error(m),
+    warn: (m) => console.error(m),
+};
+function isMain() {
+    try {
+        return (!!process.argv[1] &&
+            realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]));
+    }
+    catch {
+        return false;
+    }
+}
+if (isMain()) {
+    // the MCP server owns stdout; everything else goes to stderr there
+    const argv = process.argv.slice(2);
+    const log = argv[0] === "mcp" && argv[1] !== "init" ? stderrLogger : consoleLogger;
+    void Promise.resolve(run(argv, log)).then((code) => process.exit(code));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/init.d.ts

@@ -0,0 +1,12 @@
+import { type Config, type Kit, type Logger } from "./util.js";
+export interface InitOptions {
+    cwd: string;
+    kit: Kit;
+    /** Load both kits and switch at runtime. */
+    both?: boolean;
+    install?: boolean;
+    components?: string;
+    log: Logger;
+}
+export declare function init(o: InitOptions): Config;
+//# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAGA,OAAO,EAAe,KAAK,MAAM,EAAE,KAAK,GAAG,EAAE,KAAK,MAAM,EAAsB,MAAM,WAAW,CAAC;AAEhG,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,GAAG,CAAC;IACT,4CAA4C;IAC5C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;CACb;AAYD,wBAAgB,IAAI,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CAyE3C"}

package/dist/init.js

@@ -0,0 +1,79 @@
+import { execSync } from "node:child_process";
+import { join, relative } from "node:path";
+import { detect, installCommand } from "./project.js";
+import { CONFIG_FILE, SCOPE, read, write } from "./util.js";
+const PROVIDER = (kit, both) => `"use client";
+import type { ReactNode } from "react";
+import { UIProvider } from "${SCOPE}/${kit}";
+
+/** Kit settings for the whole app. Created by \`twentyfirst-ui init\`. */
+export function UIRoot({ children }: { children: ReactNode }) {
+  return <UIProvider${both ? ` kit="${kit}"` : ""}>{children}</UIProvider>;
+}
+`;
+export function init(o) {
+    const p = detect(o.cwd);
+    const pkgs = o.both ? [`${SCOPE}/halo`, `${SCOPE}/pro`] : [`${SCOPE}/${o.kit}`];
+    const done = [];
+    if (o.install !== false) {
+        const cmd = installCommand(p.pm, pkgs);
+        o.log.log(`$ ${cmd}`);
+        execSync(cmd, { cwd: o.cwd, stdio: "inherit" });
+        done.push(`installed ${pkgs.join(", ")}`);
+    }
+    // stylesheet
+    const css = p.css ?? join(o.cwd, p.srcDir ? "src/app/globals.css" : "app/globals.css");
+    let sheet = read(css) ?? "";
+    const styles = o.both ? `${SCOPE}/ui-core/themes.css` : `${SCOPE}/${o.kit}/styles.css`;
+    if (!sheet.includes(`${SCOPE}/`)) {
+        const imports = [`@import "${styles}";`];
+        if (p.usesTailwind)
+            imports.push(`@import "${SCOPE}/${o.kit}/tailwind.css";`);
+        if (p.usesTailwind) {
+            sheet = sheet.replace(/(@import\s+["']tailwindcss["'];?\s*\n?)/, (m) => `${m.endsWith("\n") ? m : m + "\n"}${imports.join("\n")}\n`);
+        }
+        else
+            sheet = imports.join("\n") + "\n" + sheet;
+        write(css, sheet);
+        done.push(`${relative(o.cwd, css)}: ${imports.length > 1 ? "kit styles and Tailwind preset" : "kit styles"}`);
+    }
+    // provider
+    const componentsDir = o.components ?? (p.srcDir ? "src/components/ui" : "components/ui");
+    const rootDir = join(o.cwd, componentsDir, "..");
+    const providerPath = join(rootDir, "ui-root.tsx");
+    if (!read(providerPath)) {
+        write(providerPath, PROVIDER(o.kit, !!o.both));
+        done.push(`${relative(o.cwd, providerPath)}: UIRoot with UIProvider`);
+    }
+    // layout: wrap children, set data-kit on <html> so the first paint is right
+    if (p.layout) {
+        let layout = read(p.layout);
+        if (!layout.includes("UIRoot")) {
+            const importPath = "./" +
+                relative(join(p.layout, ".."), providerPath)
+                    .replace(/\\/g, "/")
+                    .replace(/\.tsx$/, "");
+            const spec = importPath.startsWith("./..") ? importPath.slice(2) : importPath;
+            layout = layout.replace(/(\n?)((?:import[^\n]*\n)+)/, (_m, nl, imps) => `${nl}${imps}import { UIRoot } from "${spec}";\n`);
+            layout = layout.replace(/\{children\}/, "<UIRoot>{children}</UIRoot>");
+            layout = layout.replace(/<html(\s|>)/, (_m, c) => `<html data-kit="${o.kit}"${c}`);
+            write(p.layout, layout);
+            done.push(`${relative(o.cwd, p.layout)}: UIRoot around the app, data-kit on <html>`);
+        }
+    }
+    const config = {
+        kit: o.kit,
+        components: componentsDir,
+        css: relative(o.cwd, css),
+    };
+    if (o.both)
+        config.both = true;
+    write(join(o.cwd, CONFIG_FILE), JSON.stringify(config, null, 2) + "\n");
+    done.push(`${CONFIG_FILE}: settings for \`add\` and \`diff\``);
+    for (const d of done)
+        o.log.log(`  ✓ ${d}`);
+    if (o.install === false)
+        o.log.log(`  · then install: ${installCommand(p.pm, pkgs)}`);
+    return config;
+}
+//# sourceMappingURL=init.js.map

package/dist/init.js.map

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

package/dist/knowledge.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The docs as data: guides, components, patterns, props, tokens and icons of both kits.
+ *
+ * One source for three readers: the docs site (Markdown version of every page, llms.txt,
+ * llms-full.txt), the MCP server (`twentyfirst-ui mcp`) and agents reading either. The data is
+ * collected at build time by scripts/knowledge.ts; this module only renders and searches it.
+ * It has no imports, so node can also load it straight from scripts/.
+ */
+export type KitName = "halo" | "pro";
+export interface Prop {
+    name: string;
+    type: string;
+    optional: boolean;
+    doc: string;
+}
+/** A component page or a pattern page of the docs. */
+export interface Entry {
+    name: string;
+    title: string;
+    group: string;
+    /** First sentence of the description. */
+    summary: string;
+    /** Markdown. */
+    description: string;
+    /** Kit components the example uses (the props of these are documented on the page). */
+    components: string[];
+    /** The example, importing from @twentyfirstmedia/ui-core. */
+    code: string;
+    /** Path below /<kit>/, e.g. "components/Button". */
+    path: string;
+}
+export interface Guide {
+    slug: string;
+    title: string;
+    description: string;
+    /** Markdown with {{kit}}, {{Kit}}, {{other}}, {{Other}}, {{site}} placeholders. */
+    markdown: string;
+}
+export type TokenValue = string | {
+    light: string;
+    dark: string;
+};
+export interface Token {
+    name: string;
+    value: TokenValue;
+    usage?: string;
+}
+export interface KitInfo {
+    name: KitName;
+    label: string;
+    package: string;
+    tagline: string;
+    defaultTheme: string;
+    defaultDensity: string;
+    tokens: Record<string, Token[]>;
+}
+export interface Knowledge {
+    version: string;
+    /** Site URL including the base path, without a trailing slash. */
+    site: string;
+    kits: KitInfo[];
+    guides: Guide[];
+    components: Entry[];
+    patterns: Entry[];
+    props: Record<string, Prop[]>;
+    /** Source file → exported component names. */
+    exports: Record<string, string[]>;
+    /** Everything else the packages export: provider, hooks, formatters, Icon. */
+    utilities: string[];
+    icons: string[];
+}
+export declare const PRODUCT = "Twentyfirst UI";
+export declare const TOKEN_GROUPS: {
+    group: string;
+    title: string;
+}[];
+export declare function summaryOf(markdown: string): string;
+/** Markdown inline syntax removed, for meta descriptions and one-line summaries. */
+export declare function plain(s: string): string;
+export declare function kitInfo(k: Knowledge, kit: KitName): KitInfo;
+export declare function forKit(k: Knowledge, text: string, kit: KitName): string;
+/** Example code as an app writes it: imports from the kit package. */
+export declare function appCode(code: string, kit: KitName): string;
+export declare function pageUrl(k: Knowledge, kit: KitName, path: string): string;
+/** The Markdown twin of a page: /halo/components/Button/ → /halo/components/Button.md */
+export declare function mdPath(kit: KitName, path: string): string;
+export declare function mdUrl(k: Knowledge, kit: KitName, path: string): string;
+export declare function allEntries(k: Knowledge): Entry[];
+/** An entry by page name, title or any component it documents ("tabpanel" finds Tabs). */
+export declare function findEntry(k: Knowledge, name: string): Entry | undefined;
+export declare function findGuide(k: Knowledge, slug: string): Guide | undefined;
+export declare function exportedNames(k: Knowledge): Set<string>;
+export declare function propsMarkdown(k: Knowledge, component: string): string;
+export declare function entryMarkdown(k: Knowledge, e: Entry, kit: KitName): string;
+export declare function tokensMarkdown(k: Knowledge, group?: string): string;
+export declare function guideMarkdown(k: Knowledge, g: Guide, kit: KitName): string;
+/** /halo/components.md: every component by group with its one-line summary. */
+export declare function componentsIndexMarkdown(k: Knowledge, kit: KitName): string;
+/** Rules an agent should follow when it writes code with the kits. */
+export declare function agentRules(kit?: KitName | "both"): string;
+export declare function overviewMarkdown(k: Knowledge, kit: KitName): string;
+/** llms.txt (llmstxt.org): what the kits are, then a link list of every page's Markdown. */
+export declare function llmsTxt(k: Knowledge): string;
+/** llms-full.txt: every guide and every component page in one file (patterns are linked). */
+export declare function llmsFull(k: Knowledge): string;
+export interface Hit {
+    kind: "component" | "pattern" | "guide" | "token" | "icon";
+    name: string;
+    title: string;
+    summary: string;
+    score: number;
+}
+export declare function search(k: Knowledge, query: string, limit?: number): Hit[];
+export interface Finding {
+    line: number;
+    severity: "error" | "warning";
+    message: string;
+}
+/**
+ * A quick check of code that uses the kits: unknown components and props, missing required props,
+ * unknown icon names, colour literals and arbitrary Tailwind values. Heuristic, not a type checker.
+ */
+export declare function checkUsage(k: Knowledge, code: string): Finding[];
+//# sourceMappingURL=knowledge.d.ts.map

package/dist/knowledge.d.ts.map

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