@kitn.ai/cli 0.3.0 → 0.4.0

package/README.md

@@ -21,6 +21,8 @@ npx -y @kitn.ai/cli add support-widget   # no install at all
 | `kai create [dir]` | the scaffolder wizard (the same one `npm create kai` runs) |
 | `kai add <block>` | writes a block from the registry into an existing project |
 | `kai add --list` | prints the blocks this release ships |
+| `kai init [--form <id>]` | makes an EXISTING project kai-aware: adds the kit at this CLI's pin and prints the wiring that framework needs |
+| `kai upgrade [--write]` | brings a SCAFFOLDED project up to the template this CLI emits: it replaces the files you never touched and reports the ones you edited. `--strict` exits non-zero on drift |
 | `kai doctor` | diagnoses this project's kit wiring, versions and registration |
 | `kai mcp` | runs the MCP server for an AI coding harness, if that package is installed |
 | `kai dev <construct.json>` | live preview with reload-on-edit |
@@ -29,6 +31,20 @@ npx -y @kitn.ai/cli add support-widget   # no install at all
 | `kai eject <construct.json> <outDir>` | writes the generated Solid project out; the source is yours |
 | `kai validate <construct.json>` | checks a construct and prints problems with paths |
 
+## upgrade
+
+A project made with `npm create kai` is a copy of a template, and the templates move. `kai upgrade` brings that copy up to what the current CLI emits and **never overwrites something you wrote**:
+
+| | verdict | `--write` |
+|---|---|---|
+| `^` | outdated: untouched since you scaffolded it, so the template moved | replaces it |
+| `+` | missing: the template emits it and you do not have it | adds it |
+| `!` | edited: you changed it | nothing, ever |
+| `?` | unknown: it differs, and there is no baseline to say whose change it is | nothing |
+| `=` | same: already current | nothing |
+
+`kai.json` records a sha256 of every file the scaffolder wrote, which is what makes that distinction possible. A project scaffolded before that was recorded has no baseline, so `upgrade` reports the drift and refuses to write. It renders into a temp directory with the same code the scaffolder runs, it deletes nothing, and `--strict` makes drift exit non-zero for CI. `doctor` reads the same recorded hashes and reports how far your copy has moved, without rendering anything.
+
 ## doctor
 
 ```bash

package/bin/kai.js

@@ -38,6 +38,8 @@ Usage
   kai create [dir]           scaffold a project (the same wizard as \`npm create kai\`)
   kai add <block>            write a block from the registry into an existing project
   kai add --list             print the blocks this release ships
+  kai init [--form <id>]     make an EXISTING project kai-aware: add the kit and print the wiring
+  kai upgrade [--write]      bring a SCAFFOLDED project up to this CLI's template (never your edits)
 
   kai doctor                 diagnose this project's kit wiring, versions and registration
   kai doctor --strict        the same, but warnings fail the run (for CI)

package/bin/route.js

@@ -7,9 +7,9 @@
 //   'local'      -- a bundle inside THIS package. dev/compile/eject/validate are the
 //                   construct engine; doctor is the wiring diagnosis.
 //   'forward'    -- a SEPARATE published program, launched by resolving that package's
-//                   bin and spawning it with this process's stdio. create/add are
-//                   `create-kai`'s wizard and block registry (the same implementation
-//                   `npm create kai` runs), and mcp is `@kitn.ai/mcp`'s server. They are
+//                   bin and spawning it with this process's stdio. create/add/init are
+//                   `create-kai`'s (the same implementation `npm create kai` runs), and
+//                   mcp is `@kitn.ai/mcp`'s server. They are
 //                   not bundled into this package because neither belongs to its install
 //                   weight: create-kai is the scaffolder npm's own `create` convention
 //                   reaches, and the MCP is the only thing carrying the 5.9 MB SDK.
@@ -27,6 +27,8 @@ export const CONSTRUCT_COMMANDS = ['dev', 'compile', 'eject', 'validate'];
 export const KNOWN_COMMANDS = [
   'create',
   'add',
+  'init',
+  'upgrade',
   'doctor',
   'mcp',
   ...CONSTRUCT_COMMANDS,
@@ -51,6 +53,11 @@ export function decideEntry(command, rest = []) {
   // wizard is the from-scratch door, `add` the into-an-existing-project door.
   if (command === 'create') return { kind: 'forward', pkg: 'create-kai', args: rest };
   if (command === 'add') return { kind: 'forward', pkg: 'create-kai', args: ['add', ...rest] };
+  // `init` makes an EXISTING project kai-aware: it merges the dependency and prints the wiring.
+  if (command === 'init') return { kind: 'forward', pkg: 'create-kai', args: ['init', ...rest] };
+  // `upgrade` re-diffs a scaffolded project against the template this CLI emits; it replaces the
+  // files the user never touched and reports the ones they did.
+  if (command === 'upgrade') return { kind: 'forward', pkg: 'create-kai', args: ['upgrade', ...rest] };
   if (command === 'mcp') return { kind: 'forward', pkg: '@kitn.ai/mcp', args: [] };
   if (command === 'doctor') return { kind: 'local', verb: 'doctor' };
   if (CONSTRUCT_COMMANDS.includes(command)) return { kind: 'local', verb: 'construct' };

package/dist/doctor.es.js

@@ -1,4 +1,5 @@
 import { readFileSync, statSync, readdirSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { join, relative } from "node:path";
 const RULES = [
   {
@@ -239,6 +240,23 @@ function sourceFiles(dir, limit = 400) {
   if (statSync(dir, { throwIfNoEntry: false })?.isDirectory()) walk(dir);
   return out;
 }
+function baselineDrift(cwd, files) {
+  const changed = [];
+  const gone = [];
+  let same = 0;
+  for (const [file, recorded] of Object.entries(files)) {
+    let text;
+    try {
+      text = readFileSync(join(cwd, file), "utf8");
+    } catch {
+      gone.push(file);
+      continue;
+    }
+    if (createHash("sha256").update(text, "utf8").digest("hex") === recorded) same += 1;
+    else changed.push(file);
+  }
+  return { changed: changed.sort(), gone: gone.sort(), same };
+}
 const readAll = (files) => files.flatMap((file) => {
   try {
     return [{ file, text: readFileSync(file, "utf8") }];
@@ -305,7 +323,38 @@ function diagnose(input) {
     const framework = kaiJson.framework ?? "?";
     const built = kaiJson.kitBuiltAgainst ?? "?";
     const features = Array.isArray(kaiJson.features) ? kaiJson.features.join(", ") : "?";
-    findings.push({ severity: "ok", title: `${KAI_JSON}: framework ${framework}, features ${features}`, detail: `scaffolded against kit ${built}` });
+    findings.push({
+      severity: "ok",
+      title: `${KAI_JSON}: framework ${framework}, features ${features}`,
+      detail: `scaffolded against kit ${built}`
+    });
+    const baseline = kaiJson.files;
+    if (baseline !== null && typeof baseline === "object" && Object.keys(baseline).length > 0) {
+      const files = baseline;
+      const { changed, gone, same } = baselineDrift(input.cwd, files);
+      if (changed.length === 0 && gone.length === 0) {
+        findings.push({
+          severity: "ok",
+          title: `${KAI_JSON}'s baseline: all ${same} scaffolded file(s) are exactly as written`
+        });
+      } else {
+        const names = [...changed, ...gone];
+        const shown = names.slice(0, 3).join(", ");
+        const more = names.length > 3 ? ` (and ${names.length - 3} more)` : "";
+        findings.push({
+          severity: "info",
+          title: `${KAI_JSON}'s baseline: ${same} of ${Object.keys(files).length} scaffolded file(s) are as written, ${changed.length} changed, ${gone.length} gone`,
+          detail: `${shown}${more}
+Run \`kai upgrade\` to see what the template this CLI emits would change (it replaces only the files you never touched), or \`kai upgrade --strict\` in CI.`
+        });
+      }
+    } else {
+      findings.push({
+        severity: "info",
+        title: `${KAI_JSON} has no baseline`,
+        detail: "it predates the recorded hashes, so this cannot tell your edits from a template change. `kai upgrade` still diffs the project against the template this CLI emits, and will not write without a baseline."
+      });
+    }
   } else {
     findings.push({
       severity: "info",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitn.ai/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "MIT",
   "type": "module",
   "description": "The kai command line for @kitn.ai/ui: scaffold a project or add a block to one, diagnose its wiring, and run the construct dev/eject/compile tooling.",
@@ -56,7 +56,7 @@
     "lint:cli-invocations": "node scripts/lint-cli-invocations.mjs --self-test && node scripts/lint-cli-invocations.mjs"
   },
   "dependencies": {
-    "create-kai": "^0.7.1",
+    "create-kai": "^0.8.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {