@kurajs/cli 0.0.1 → 0.0.3

package/dist/cli.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
 // Kura CLI.
-//   kura index [--out app/_index.bin] [--model Xenova/bge-m3]
-//     Build the search index for the current Kura docs app: embed every doc from the
-//     June-frozen app/_content.ts and write a compact index the app loads at runtime.
+//   kura index [--model Xenova/bge-m3]
+//     Build the search index + precompiled MDX for the current Kura docs app and FREEZE both
+//     as importable modules (app/_index.ts, app/_mdx.ts) — so the worker bundle imports them
+//     and never reads the filesystem (Workers-safe; mirrors June's app/_content.ts freeze).
+//     A content hash short-circuits re-embedding when nothing changed (cheap to run pre-dev).
 import { buildIndex } from "@kurajs/docs/search";
 import { transformers } from "@kurajs/transformers";
 import fs from "node:fs";
 import path from "node:path";
+import crypto from "node:crypto";
 import { pathToFileURL } from "node:url";
 function arg(name, def) {
     const i = process.argv.indexOf(`--${name}`);
@@ -19,8 +22,9 @@ async function cmdIndex() {
         console.error("kura index: app/_content.ts not found — run `june gen` first (in a Kura docs app).");
         process.exit(1);
     }
-    const out = arg("out", path.join("app", "_index.bin"));
     const model = arg("model", "Xenova/bge-m3");
+    const indexTs = path.join(cwd, "app", "_index.ts");
+    const mdxTs = path.join(cwd, "app", "_mdx.ts");
     const mod = (await import(pathToFileURL(contentPath).href));
     const DOCS = mod.DOCS ?? [];
     if (!DOCS.length) {
@@ -49,18 +53,42 @@ async function cmdIndex() {
             if (e.locale === locale)
                 variants.push(e);
     const allEntries = [...DOCS, ...variants];
-    const localeTag = locales.size ? ` (+${variants.length} variants across ${locales.size} locales)` : "";
-    console.log(`kura index: embedding ${DOCS.length} docs${localeTag} (model ${model})…`);
-    const t0 = Date.now();
-    const bytes = await buildIndex({ entries: allEntries, embedder: transformers({ model }) });
-    fs.mkdirSync(path.dirname(out), { recursive: true });
-    fs.writeFileSync(out, bytes);
-    console.log(`kura index: wrote ${out} (${(fs.statSync(out).size / 1024).toFixed(0)}KB) in ${((Date.now() - t0) / 1000).toFixed(1)}s`);
-    // Precompile MDX -> static HTML with curated components (build-time; Workers-safe at
-    // runtime). Bucketed by locale: "default" for the flat (default-locale) files, plus one
-    // bucket per variant locale. The app picks the bucket per entry.
+    // --no-embed: skip the search index entirely (build MDX only). Use it when the site runs
+    // WITHOUT a runtime embedder — search degrades to a lexical scan, so no model/index is needed
+    // (e.g. a Cloudflare Workers deploy without Workers AI).
+    const noEmbed = process.argv.includes("--no-embed");
+    // Content hash — skip rebuilds when nothing changed, so `kura index` is cheap to run before
+    // every dev/build. Covers the mode + model + locale/slug/body of every entry.
+    const hashInput = JSON.stringify([model, noEmbed, allEntries.map((e) => [e.locale ?? "", e.slug, e.body])]);
+    const contentHash = crypto.createHash("sha256").update(hashInput).digest("hex").slice(0, 16);
+    const stamp = `// content-hash: ${contentHash}\n`;
+    const hashOf = (f) => (fs.existsSync(f) ? fs.readFileSync(f, "utf8").match(/content-hash: (\S+)/)?.[1] : undefined);
+    const upToDate = noEmbed ? hashOf(mdxTs) === contentHash : hashOf(indexTs) === contentHash && fs.existsSync(mdxTs);
+    if (upToDate) {
+        console.log(`kura index: up to date (${allEntries.length} docs, hash ${contentHash}) — skipped`);
+        return;
+    }
+    fs.mkdirSync(path.dirname(mdxTs), { recursive: true });
+    if (!noEmbed) {
+        const localeTag = locales.size ? ` (+${variants.length} variants across ${locales.size} locales)` : "";
+        console.log(`kura index: embedding ${DOCS.length} docs${localeTag} (model ${model})…`);
+        const t0 = Date.now();
+        const bytes = await buildIndex({ entries: allEntries, embedder: transformers({ model }) });
+        const b64 = Buffer.from(bytes).toString("base64");
+        fs.writeFileSync(indexTs, stamp +
+            "// AUTO-GENERATED by `kura index` — do not edit. Frozen search index (base64) so the worker\n" +
+            "// bundle imports it instead of reading the filesystem (Workers-safe).\n" +
+            `export const INDEX_B64 = ${JSON.stringify(b64)};\n`);
+        console.log(`kura index: wrote app/_index.ts (${(bytes.length / 1024).toFixed(0)}KB index) in ${((Date.now() - t0) / 1000).toFixed(1)}s`);
+    }
+    else {
+        if (fs.existsSync(indexTs))
+            fs.rmSync(indexTs);
+        console.log("kura index: --no-embed — MDX only, no search index (runtime search is lexical)");
+    }
+    // Precompile MDX -> static HTML with curated components (build-time; Workers-safe at runtime).
+    // Bucketed by locale: "default" for the flat (default-locale) files, plus one per variant locale.
     const { mdxToHtml } = await import("@kurajs/docs/mdx");
-    const mdxOut = path.join(cwd, "app", "_mdx.json");
     const map = { default: {} };
     let ok = 0;
     const render = async (bucket, e) => {
@@ -76,16 +104,20 @@ async function cmdIndex() {
         await render("default", d);
     for (const e of variants)
         await render(e.locale, e);
-    fs.writeFileSync(mdxOut, JSON.stringify(map));
+    fs.writeFileSync(mdxTs, stamp +
+        "// AUTO-GENERATED by `kura index` — do not edit. Frozen precompiled MDX (locale → slug → html).\n" +
+        `export const MDX: Record<string, Record<string, string>> = ${JSON.stringify(map)};\n`);
     const total = Object.values(map).reduce((n, b) => n + Object.keys(b).length, 0);
     const tag = locales.size ? ` across ${locales.size + 1} locales` : "";
-    console.log(`kura index: rendered ${ok}/${total} docs via MDX${tag} -> ${path.relative(cwd, mdxOut)}`);
+    console.log(`kura index: rendered ${ok}/${total} docs via MDX${tag} -> app/_mdx.ts`);
 }
 const cmd = process.argv[2];
 if (cmd === "index") {
     await cmdIndex();
 }
 else {
-    console.log("Kura CLI\n  kura index [--out app/_index.bin] [--model <hf-model>]   build the docs search index");
+    console.log("Kura CLI\n" +
+        "  kura index [--model <hf-model>]   build & freeze the docs search index + MDX\n" +
+        "  kura index --no-embed             MDX only, no search index (runtime search is lexical)");
     process.exit(cmd ? 1 : 0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurajs/cli",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "description": "Kura CLI — build the docs search index (kura index).",
   "bin": {
@@ -15,7 +15,7 @@
   "license": "MIT",
   "dependencies": {
     "@kurajs/core": "^0.0.1",
-    "@kurajs/docs": "^0.0.1",
+    "@kurajs/docs": "^0.0.3",
     "@kurajs/transformers": "^0.0.1"
   },
   "peerDependencies": {
@@ -25,7 +25,7 @@
     "@huggingface/transformers": "3.8.1",
     "typescript": "^5.7.0"
   },
-  "author": "Yi-Ru Lin",
+  "author": "Lawrence Lin",
   "publishConfig": {
     "access": "public"
   },
@@ -38,5 +38,10 @@
     "search",
     "index",
     "mcp"
-  ]
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kurajs/kura.git",
+    "directory": "packages/cli"
+  }
 }