@substrate-kit/cli 0.1.2 → 0.2.0

package/dist/mcp/tools/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C,wBAAsB,YAAY,CAChC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;GAsC5C"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAE/D,wBAAsB,YAAY,CAChC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;GAgC5C"}

package/dist/mcp/tools/search.js

@@ -1,3 +1,4 @@
+import { matchesQuery } from "../../registry.js";
 export async function handleSearch(registry, args) {
     let items = registry.items;
     if (args.category) {
@@ -6,10 +7,7 @@ export async function handleSearch(registry, args) {
     }
     if (args.query) {
         const q = args.query.toLowerCase();
-        items = items.filter((i) => i.name.includes(q) ||
-            (i.title || "").toLowerCase().includes(q) ||
-            (i.description || "").toLowerCase().includes(q) ||
-            (i.categories || []).some((c) => c.toLowerCase().includes(q)));
+        items = items.filter((i) => matchesQuery(i, q));
     }
     const results = items.map((i) => ({
         name: i.name,

package/dist/mcp/tools/search.js.map

@@ -1 +1 @@
-{"version":3,"file":"search.js","sourceRoot":"","sources":["../../../src/mcp/tools/search.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAkB,EAClB,IAA2C;IAE3C,IAAI,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAA;IAE1B,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAA;QACvC,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CACzB,CAAC,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,GAAG,CAAC,CAC1D,CAAA;IACH,CAAC;IAED,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAA;QAClC,KAAK,GAAG,KAAK,CAAC,MAAM,CAClB,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;YAClB,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;YACzC,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;YAC/C,CAAC,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAChE,CAAA;IACH,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAChC,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,OAAO,EAAE,yBAAyB,CAAC,CAAC,IAAI,EAAE;KAC3C,CAAC,CAAC,CAAA;IAEH,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;aACvC;SACF;KACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../../src/mcp/tools/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAiB,MAAM,mBAAmB,CAAA;AAE/D,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAkB,EAClB,IAA2C;IAE3C,IAAI,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAA;IAE1B,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAA;QACvC,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CACzB,CAAC,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,GAAG,CAAC,CAC1D,CAAA;IACH,CAAC;IAED,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAA;QAClC,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IACjD,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAChC,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,OAAO,EAAE,yBAAyB,CAAC,CAAC,IAAI,EAAE;KAC3C,CAAC,CAAC,CAAA;IAEH,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;aACvC;SACF;KACF,CAAA;AACH,CAAC"}

package/dist/{mcp/types.d.ts → registry.d.ts}

@@ -1,3 +1,5 @@
+export declare const SITE_URL = "https://substrate.georgedrury.co.uk";
+export declare const REGISTRY_BASE: string;
 export interface RegistryItem {
     name: string;
     type: string;
@@ -28,4 +30,7 @@ export interface RegistryItem {
 export interface Registry {
     items: RegistryItem[];
 }
-//# sourceMappingURL=types.d.ts.map
+export declare function loadRegistry(): Promise<Registry>;
+export declare function overrideKeys(item: RegistryItem): string[];
+export declare function matchesQuery(item: RegistryItem, query: string): boolean;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,QAAQ,wCAAwC,CAAA;AAG7D,eAAO,MAAM,aAAa,QAAwD,CAAA;AAKlF,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC/B,IAAI,CAAC,EAAE;QACN,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,OAAO,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAChD,CAAA;IACD,OAAO,CAAC,EAAE;QACT,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC9B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC9B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAC7B,CAAA;IACD,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC7D;AAED,MAAM,WAAW,QAAQ;IACxB,KAAK,EAAE,YAAY,EAAE,CAAA;CACrB;AAKD,wBAAsB,YAAY,IAAI,OAAO,CAAC,QAAQ,CAAC,CAkBtD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,EAAE,CAOzD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAQvE"}

package/dist/registry.js

@@ -0,0 +1,48 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PACKAGE_ROOT } from "./utils/version.js";
+export const SITE_URL = "https://substrate.georgedrury.co.uk";
+// SUBSTRATE_REGISTRY_URL points installs at a local registry for testing
+export const REGISTRY_BASE = process.env.SUBSTRATE_REGISTRY_URL ?? `${SITE_URL}/r`;
+const REGISTRY_URL = `${SITE_URL}/registry.json`;
+const FETCH_TIMEOUT_MS = 5000;
+// The live registry is the newest; the copy bundled with the package keeps
+// the CLI working offline. A registry.json in the current folder is never
+// read, since it could belong to an unrelated project.
+export async function loadRegistry() {
+    try {
+        const res = await fetch(REGISTRY_URL, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+        if (res.ok)
+            return (await res.json());
+    }
+    catch {
+        /* fall through to the bundled copy */
+    }
+    const bundled = join(PACKAGE_ROOT, "registry.json");
+    if (existsSync(bundled)) {
+        try {
+            return JSON.parse(readFileSync(bundled, "utf-8"));
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    throw new Error("Could not load the Substrate registry");
+}
+export function overrideKeys(item) {
+    const keys = [];
+    for (const value of Object.values(item.cssVars?.theme ?? {})) {
+        const match = value.match(/^var\(--([^,)]+)/);
+        if (match)
+            keys.push(`--${match[1]}`);
+    }
+    return keys;
+}
+export function matchesQuery(item, query) {
+    const q = query.toLowerCase();
+    return (item.name.includes(q) ||
+        (item.title ?? "").toLowerCase().includes(q) ||
+        (item.description ?? "").toLowerCase().includes(q) ||
+        (item.categories ?? []).some((c) => c.toLowerCase().includes(q)));
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjD,MAAM,CAAC,MAAM,QAAQ,GAAG,qCAAqC,CAAA;AAE7D,yEAAyE;AACzE,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,GAAG,QAAQ,IAAI,CAAA;AAElF,MAAM,YAAY,GAAG,GAAG,QAAQ,gBAAgB,CAAA;AAChD,MAAM,gBAAgB,GAAG,IAAI,CAAA;AA2B7B,2EAA2E;AAC3E,0EAA0E;AAC1E,uDAAuD;AACvD,MAAM,CAAC,KAAK,UAAU,YAAY;IACjC,IAAI,CAAC;QACJ,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,YAAY,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAA;QACxF,IAAI,GAAG,CAAC,EAAE;YAAE,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAa,CAAA;IAClD,CAAC;IAAC,MAAM,CAAC;QACR,sCAAsC;IACvC,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,EAAE,eAAe,CAAC,CAAA;IACnD,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACzB,IAAI,CAAC;YACJ,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAa,CAAA;QAC9D,CAAC;QAAC,MAAM,CAAC;YACR,kBAAkB;QACnB,CAAC;IACF,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAA;AACzD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAkB;IAC9C,MAAM,IAAI,GAAa,EAAE,CAAA;IACzB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;QAC9D,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAA;QAC7C,IAAI,KAAK;YAAE,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IACtC,CAAC;IACD,OAAO,IAAI,CAAA;AACZ,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAkB,EAAE,KAAa;IAC7D,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,CAAA;IAC7B,OAAO,CACN,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;QACrB,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC5C,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;QAClD,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAChE,CAAA;AACF,CAAC"}

package/dist/utils/agents-file.d.ts

@@ -0,0 +1,4 @@
+export declare function agentsSection(): string;
+export type MergeResult = "created" | "added" | "updated" | "unchanged";
+export declare function mergeSection(file: string, section: string): MergeResult;
+//# sourceMappingURL=agents-file.d.ts.map

package/dist/utils/agents-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-file.d.ts","sourceRoot":"","sources":["../../src/utils/agents-file.ts"],"names":[],"mappings":"AAQA,wBAAgB,aAAa,IAAI,MAAM,CAGtC;AAED,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,CAAA;AAIvE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,CAuBvE"}

package/dist/utils/agents-file.js

@@ -0,0 +1,36 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { exists, writeFile } from "./fs.js";
+import { PACKAGE_ROOT } from "./version.js";
+const START = "<!-- substrate:start -->";
+const END = "<!-- substrate:end -->";
+export function agentsSection() {
+    const body = readFileSync(join(PACKAGE_ROOT, "templates", "agents-section.md"), "utf-8").trimEnd();
+    return `${START}\n${body}\n${END}\n`;
+}
+// Puts the Substrate guidance between markers so it can be refreshed later
+// without touching anything the project wrote itself.
+export function mergeSection(file, section) {
+    if (!exists(file)) {
+        writeFile(file, section);
+        return "created";
+    }
+    const current = readFileSync(file, "utf-8");
+    const start = current.indexOf(START);
+    const end = current.indexOf(END);
+    let next;
+    let result;
+    if (start !== -1 && end > start) {
+        next = current.slice(0, start) + section.trimEnd() + current.slice(end + END.length);
+        result = "updated";
+    }
+    else {
+        next = `${current.trimEnd()}\n\n${section}`;
+        result = "added";
+    }
+    if (next === current)
+        return "unchanged";
+    writeFile(file, next);
+    return result;
+}
+//# sourceMappingURL=agents-file.js.map

package/dist/utils/agents-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-file.js","sourceRoot":"","sources":["../../src/utils/agents-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAE3C,MAAM,KAAK,GAAG,0BAA0B,CAAA;AACxC,MAAM,GAAG,GAAG,wBAAwB,CAAA;AAEpC,MAAM,UAAU,aAAa;IAC5B,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,EAAE,mBAAmB,CAAC,EAAE,OAAO,CAAC,CAAC,OAAO,EAAE,CAAA;IAClG,OAAO,GAAG,KAAK,KAAK,IAAI,KAAK,GAAG,IAAI,CAAA;AACrC,CAAC;AAID,2EAA2E;AAC3E,sDAAsD;AACtD,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,OAAe;IACzD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACnB,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QACxB,OAAO,SAAS,CAAA;IACjB,CAAC;IAED,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IAC3C,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IACpC,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAEhC,IAAI,IAAY,CAAA;IAChB,IAAI,MAAmB,CAAA;IACvB,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,GAAG,GAAG,KAAK,EAAE,CAAC;QACjC,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,CAAA;QACpF,MAAM,GAAG,SAAS,CAAA;IACnB,CAAC;SAAM,CAAC;QACP,IAAI,GAAG,GAAG,OAAO,CAAC,OAAO,EAAE,OAAO,OAAO,EAAE,CAAA;QAC3C,MAAM,GAAG,OAAO,CAAA;IACjB,CAAC;IAED,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,WAAW,CAAA;IACxC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IACrB,OAAO,MAAM,CAAA;AACd,CAAC"}

package/dist/utils/docs.d.ts

@@ -0,0 +1,7 @@
+export interface DocsPage {
+    url: string;
+    content: string;
+}
+export declare function findDocsPage(name: string): DocsPage | null;
+export declare function docsUrl(name: string): string;
+//# sourceMappingURL=docs.d.ts.map

package/dist/utils/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/utils/docs.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,QAAQ;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;CACf;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAa1D;AAGD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C"}

package/dist/utils/docs.js

@@ -0,0 +1,28 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { SITE_URL } from "../registry.js";
+import { PACKAGE_ROOT } from "./version.js";
+// Docs pages are copied into the package at publish time (see
+// scripts/bundle-cli-assets.mjs), one folder per section of the docs site.
+const DOCS_DIR = join(PACKAGE_ROOT, "docs");
+export function findDocsPage(name) {
+    if (!/^[a-z0-9-]+$/.test(name) || !existsSync(DOCS_DIR))
+        return null;
+    for (const section of readdirSync(DOCS_DIR, { withFileTypes: true })) {
+        if (!section.isDirectory())
+            continue;
+        const file = join(DOCS_DIR, section.name, `${name}.mdx`);
+        if (existsSync(file)) {
+            return {
+                url: `${SITE_URL}/docs/${section.name}/${name}`,
+                content: readFileSync(file, "utf-8"),
+            };
+        }
+    }
+    return null;
+}
+// Hooks and utilities live under their own sections of the docs site
+export function docsUrl(name) {
+    return findDocsPage(name)?.url ?? `${SITE_URL}/docs/components/${name}`;
+}
+//# sourceMappingURL=docs.js.map

package/dist/utils/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../src/utils/docs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAE3C,8DAA8D;AAC9D,2EAA2E;AAC3E,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,CAAA;AAO3C,MAAM,UAAU,YAAY,CAAC,IAAY;IACxC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAA;IACpE,KAAK,MAAM,OAAO,IAAI,WAAW,CAAC,QAAQ,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QACtE,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE;YAAE,SAAQ;QACpC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE,GAAG,IAAI,MAAM,CAAC,CAAA;QACxD,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,OAAO;gBACN,GAAG,EAAE,GAAG,QAAQ,SAAS,OAAO,CAAC,IAAI,IAAI,IAAI,EAAE;gBAC/C,OAAO,EAAE,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC;aACpC,CAAA;QACF,CAAC;IACF,CAAC;IACD,OAAO,IAAI,CAAA;AACZ,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,OAAO,CAAC,IAAY;IACnC,OAAO,YAAY,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,GAAG,QAAQ,oBAAoB,IAAI,EAAE,CAAA;AACxE,CAAC"}

package/dist/utils/shadcn.d.ts

@@ -2,6 +2,11 @@ export interface ShadcnAddOptions {
     cwd?: string;
     /** Capture output instead of printing it (used by the MCP server) */
     silent?: boolean;
+    /** Pass --yes so shadcn skips its confirmation prompts */
+    yes?: boolean;
+    /** How many times to try before giving up (default 3) */
+    attempts?: number;
 }
-export declare function shadcnAdd(url: string, options?: ShadcnAddOptions): void;
+export type RetryHandler = (attempt: number, error: unknown) => void;
+export declare function shadcnAdd(urls: string[], options?: ShadcnAddOptions, onRetry?: RetryHandler): void;
 //# sourceMappingURL=shadcn.d.ts.map

package/dist/utils/shadcn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shadcn.d.ts","sourceRoot":"","sources":["../../src/utils/shadcn.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,MAAM,CAAC,EAAE,OAAO,CAAA;CAChB;AAKD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,IAAI,CAW3E"}
+{"version":3,"file":"shadcn.d.ts","sourceRoot":"","sources":["../../src/utils/shadcn.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAA;CACjB;AAGD,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;AAOpE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,gBAAqB,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI,CAoBtG"}

package/dist/utils/shadcn.js

@@ -1,16 +1,29 @@
-import { execSync } from "node:child_process";
-// shadcn asks before overwriting a file that differs from the registry. With
-// no terminal to answer, it exits successfully having written nothing, so
-// answer "no" for it: existing files are kept and the rest are installed.
-export function shadcnAdd(url, options = {}) {
-    const { cwd, silent = false } = options;
+import { execFileSync } from "node:child_process";
+// One shadcn call installs every item, so shared dependencies are resolved
+// once. shadcn asks before overwriting a file that differs from the registry;
+// with no terminal to answer it exits successfully having written nothing,
+// so answer "no" for it: existing files are kept and the rest are installed.
+// A dropped request fails the whole call, so it is retried.
+export function shadcnAdd(urls, options = {}, onRetry) {
+    const { cwd, silent = false, yes = false, attempts = 3 } = options;
     const interactive = !silent && process.stdin.isTTY === true;
     const output = silent ? "pipe" : "inherit";
-    execSync(`npx shadcn@latest add ${url}`, {
-        cwd,
-        encoding: "utf-8",
-        stdio: interactive ? "inherit" : ["pipe", output, output],
-        input: interactive ? undefined : "n\n".repeat(200),
-    });
+    const npx = process.platform === "win32" ? "npx.cmd" : "npx";
+    for (let attempt = 1;; attempt++) {
+        try {
+            execFileSync(npx, ["shadcn@latest", "add", ...(yes ? ["--yes"] : []), ...urls], {
+                cwd,
+                encoding: "utf-8",
+                stdio: interactive ? "inherit" : ["pipe", output, output],
+                input: interactive ? undefined : "n\n".repeat(200),
+            });
+            return;
+        }
+        catch (error) {
+            if (attempt >= attempts)
+                throw error;
+            onRetry?.(attempt, error);
+        }
+    }
 }
 //# sourceMappingURL=shadcn.js.map

package/dist/utils/shadcn.js.map

@@ -1 +1 @@
-{"version":3,"file":"shadcn.js","sourceRoot":"","sources":["../../src/utils/shadcn.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAQ7C,6EAA6E;AAC7E,0EAA0E;AAC1E,0EAA0E;AAC1E,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,UAA4B,EAAE;IACpE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,KAAK,EAAE,GAAG,OAAO,CAAA;IACvC,MAAM,WAAW,GAAG,CAAC,MAAM,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,CAAA;IAC3D,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAA;IAE1C,QAAQ,CAAC,yBAAyB,GAAG,EAAE,EAAE;QACxC,GAAG;QACH,QAAQ,EAAE,OAAO;QACjB,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;QACzD,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC;KAClD,CAAC,CAAA;AACH,CAAC"}
+{"version":3,"file":"shadcn.js","sourceRoot":"","sources":["../../src/utils/shadcn.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAejD,2EAA2E;AAC3E,8EAA8E;AAC9E,2EAA2E;AAC3E,6EAA6E;AAC7E,4DAA4D;AAC5D,MAAM,UAAU,SAAS,CAAC,IAAc,EAAE,UAA4B,EAAE,EAAE,OAAsB;IAC/F,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,KAAK,EAAE,GAAG,GAAG,KAAK,EAAE,QAAQ,GAAG,CAAC,EAAE,GAAG,OAAO,CAAA;IAClE,MAAM,WAAW,GAAG,CAAC,MAAM,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,CAAA;IAC3D,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAA;IAC1C,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAA;IAE5D,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;QACnC,IAAI,CAAC;YACJ,YAAY,CAAC,GAAG,EAAE,CAAC,eAAe,EAAE,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE;gBAC/E,GAAG;gBACH,QAAQ,EAAE,OAAO;gBACjB,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;gBACzD,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC;aAClD,CAAC,CAAA;YACF,OAAM;QACP,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,OAAO,IAAI,QAAQ;gBAAE,MAAM,KAAK,CAAA;YACpC,OAAO,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;QAC1B,CAAC;IACF,CAAC;AACF,CAAC"}

package/dist/utils/version.d.ts

@@ -0,0 +1,3 @@
+export declare const PACKAGE_ROOT: string;
+export declare const VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/utils/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/utils/version.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,YAAY,QAAc,CAAA;AAEvC,eAAO,MAAM,OAAO,EAAE,MAEb,CAAA"}

package/dist/utils/version.js

@@ -0,0 +1,8 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// Both src/utils and dist/utils sit two levels below the package root
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+export const PACKAGE_ROOT = packageRoot;
+export const VERSION = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf-8")).version;
+//# sourceMappingURL=version.js.map

package/dist/utils/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/utils/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC,sEAAsE;AACtE,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;AAE7E,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAA;AAEvC,MAAM,CAAC,MAAM,OAAO,GACnB,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CACnE,CAAC,OAAO,CAAA"}

package/docs/components/action.mdx

@@ -0,0 +1,30 @@
+---
+title: Action
+description: Form field row layout for property editors.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/action
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="action-demo" />
+
+### With colour picker
+
+`ActionControls` automatically sizes and strips borders from nested `ColourSwatch`, `Slider`, `NumberInput`, and other slot-aware components.
+
+<ComponentPreview name="action-colour" />
+
+## Components
+
+| Component        | Description                            |
+| ---------------- | -------------------------------------- |
+| `Action`         | Container with flex row layout and gap |
+| `ActionLabel`    | Fixed-width label                      |
+| `ActionControls` | Flex-1 control area                    |

package/docs/components/alignment-controls.mdx

@@ -0,0 +1,30 @@
+---
+title: Alignment controls
+description: Align and distribute selected elements – left, centre, right, top, middle, bottom.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/alignment-controls
+```
+
+## Examples
+
+### Default
+
+The first row shows all controls including distribute. The second row hides distribute with `showDistribute={false}`.
+
+<ComponentPreview name="alignment-controls-demo" />
+
+## Props
+
+| Prop             | Type                            | Default | Description                         |
+| ---------------- | ------------------------------- | ------- | ----------------------------------- |
+| `onAlign`        | `(action: AlignAction) => void` | —       | Called with the alignment action    |
+| `showDistribute` | `boolean`                       | `true`  | Show distribute horizontal/vertical |
+| `disabled`       | `boolean`                       | —       | Disables all buttons                |
+
+### AlignAction values
+
+`left` · `center-h` · `right` · `top` · `center-v` · `bottom` · `distribute-h` · `distribute-v`

package/docs/components/badge.mdx

@@ -0,0 +1,22 @@
+---
+title: Badge
+description: Small label for element types, node categories, and status indicators.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/badge
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="badge-demo" />
+
+## Props
+
+| Prop      | Type                                                     | Default     | Description  |
+| --------- | -------------------------------------------------------- | ----------- | ------------ |
+| `variant` | `"default"` \| `"secondary"` \| `"outline"` \| `"muted"` | `"default"` | Visual style |

package/docs/components/breadcrumbs.mdx

@@ -0,0 +1,25 @@
+---
+title: Breadcrumbs
+description: Navigation path for drilling into nested frames and groups.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/breadcrumbs
+```
+
+## Examples
+
+### Default
+
+Click any ancestor to navigate back up. The active (last) item is bold and non-clickable.
+
+<ComponentPreview name="breadcrumbs-demo" />
+
+## Components
+
+| Component        | Description                                      |
+| ---------------- | ------------------------------------------------ |
+| `Breadcrumbs`    | `nav` wrapper with horizontal flex layout        |
+| `BreadcrumbItem` | Clickable path segment with auto separator arrow |

package/docs/components/collapsible-pane.mdx

@@ -0,0 +1,35 @@
+---
+title: Collapsible pane
+description: Pane section with expand/collapse toggle. Built on Radix Collapsible with animated height transitions.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/collapsible-pane
+```
+
+## Examples
+
+### Default
+
+The first section starts open, the second starts collapsed. Click the chevron to toggle.
+
+<ComponentPreview name="collapsible-pane-demo" />
+
+## Components
+
+| Component                | Description                                 |
+| ------------------------ | ------------------------------------------- |
+| `CollapsiblePane`        | Root wrapper with Radix Collapsible state   |
+| `CollapsiblePaneHeader`  | Header row with expand/collapse chevron     |
+| `CollapsiblePaneLabel`   | Section title text                          |
+| `CollapsiblePaneContent` | Animated body that collapses to zero height |
+
+## Props (CollapsiblePane)
+
+| Prop           | Type                      | Default | Description                       |
+| -------------- | ------------------------- | ------- | --------------------------------- |
+| `defaultOpen`  | `boolean`                 | `true`  | Initial open state (uncontrolled) |
+| `open`         | `boolean`                 | —       | Controlled open state             |
+| `onOpenChange` | `(open: boolean) => void` | —       | Called when open state changes    |

package/docs/components/colour-picker.mdx

@@ -0,0 +1,66 @@
+---
+title: Colour picker
+description: Hex colour picker with swatch trigger, popover panel, and text input — built on react-colorful and Radix Popover.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/colour-picker
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="colour-picker-demo" />
+
+### Inline
+
+<ComponentPreview name="colour-picker-inline" />
+
+### Custom trigger
+
+<ComponentPreview name="colour-picker-custom-trigger" />
+
+## Components
+
+| Component             | Description                                                            |
+| --------------------- | ---------------------------------------------------------------------- |
+| `ColourPicker`        | Popover wrapper — renders swatch trigger and picker content in a panel |
+| `ColourPickerContent` | Saturation/hue picker with hex input and preview swatch                |
+| `ColourSwatch`        | Colour preview button sized `sm` (20px) or `md` (28px)                 |
+| `ColourInput`         | Hex colour text input wrapping `HexColorInput` from react-colorful     |
+
+## Props
+
+### ColourPicker
+
+| Prop       | Type                       | Default | Description                |
+| ---------- | -------------------------- | ------- | -------------------------- |
+| `value`    | `string`                   | —       | Current colour, in any CSS format (hex, `oklch()`, `rgb()`, named) |
+| `onChange` | `(colour: string) => void` | —       | Called with the new colour as hex |
+| `onStart`  | `() => void`               | —       | Called when a drag or edit begins. Useful for undo snapshots. |
+| `children` | `React.ReactNode`          | Swatch  | Custom trigger element     |
+
+### ColourPickerContent
+
+| Prop       | Type                       | Default | Description                |
+| ---------- | -------------------------- | ------- | -------------------------- |
+| `value`    | `string`                   | —       | Current colour, in any CSS format |
+| `onChange` | `(colour: string) => void` | —       | Called with the new colour as hex |
+| `onStart`  | `() => void`               | —       | Called when a drag or edit begins |
+
+### ColourSwatch
+
+| Prop     | Type           | Default | Description           |
+| -------- | -------------- | ------- | --------------------- |
+| `colour` | `string`       | —       | Any CSS colour to display |
+| `size`   | `"sm" \| "md"` | `"md"`  | Swatch size           |
+
+### ColourInput
+
+| Prop       | Type                       | Default | Description                |
+| ---------- | -------------------------- | ------- | -------------------------- |
+| `value`    | `string`                   | —       | Current hex colour value   |
+| `onChange` | `(colour: string) => void` | —       | Called when colour changes |

package/docs/components/command-palette.mdx

@@ -0,0 +1,36 @@
+---
+title: Command palette
+description: Cmd+K search dialog for tools, actions, and keyboard shortcuts. Built on cmdk and Radix Dialog.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/command-palette
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="command-palette-demo" />
+
+## Interaction
+
+- **⌘K / Ctrl+K** opens and closes the palette.
+- Type to fuzzy-search across all items.
+- Arrow keys to navigate, Enter to select.
+- Escape to dismiss.
+
+## Components
+
+| Component          | Description                             |
+| ------------------ | --------------------------------------- |
+| `CommandPalette`   | Dialog wrapper with ⌘K listener         |
+| `CommandInput`     | Search input with magnifying glass icon |
+| `CommandList`      | Scrollable results container            |
+| `CommandEmpty`     | Shown when no results match             |
+| `CommandGroup`     | Labelled group of items                 |
+| `CommandItem`      | Selectable result row                   |
+| `CommandShortcut`  | Right-aligned keyboard shortcut hint    |
+| `CommandSeparator` | Horizontal divider between groups       |

package/docs/components/context-menu.mdx

@@ -0,0 +1,31 @@
+---
+title: Context menu
+description: Right-click menu built on Radix ContextMenu with keyboard shortcut display and submenus.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/context-menu
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="context-menu-demo" />
+
+## Components
+
+| Component               | Description                           |
+| ----------------------- | ------------------------------------- |
+| `ContextMenu`           | Root wrapper (Radix ContextMenu.Root) |
+| `ContextMenuTrigger`    | Area that responds to right-click     |
+| `ContextMenuContent`    | Popover menu panel                    |
+| `ContextMenuItem`       | Clickable menu item                   |
+| `ContextMenuSeparator`  | Horizontal divider                    |
+| `ContextMenuLabel`      | Non-interactive section heading       |
+| `ContextMenuShortcut`   | Right-aligned keyboard shortcut hint  |
+| `ContextMenuSub`        | Submenu root                          |
+| `ContextMenuSubTrigger` | Item that opens a submenu             |
+| `ContextMenuSubContent` | Submenu panel                         |