@kitn.ai/cli 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# @kitn.ai/cli
+
+The `kai` command line for [`@kitn.ai/ui`](https://www.npmjs.com/package/@kitn.ai/ui): scaffold a
+project or add a block to one, diagnose its kit wiring, and run the construct tooling.
+
+It is optional. `npm install @kitn.ai/ui` and importing components needs no command line at all;
+this is the tool you install when you want the convenience.
+
+## Install
+
+```bash
+npm i -g @kitn.ai/cli      # kai ... anywhere, like any other CLI
+npm i -D @kitn.ai/cli      # pinned per project: npx kai ...
+npx -y @kitn.ai/cli add support-widget   # no install at all
+```
+
+## Verbs
+
+| verb | what it does |
+|---|---|
+| `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 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 |
+| `kai dev --builder` | the visual builder plus live preview |
+| `kai compile <construct.json> [outDir]` | one self-registering `.js` |
+| `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 |
+
+## doctor
+
+```bash
+kai doctor          # human-readable
+kai doctor --json   # the findings, for a CI job or an agent
+```
+
+It reports the CLI version and the kit it was built against, the kit range this project declares
+versus the version actually installed, whether `kai.json` is present, whether anything under `src/`
+references the kit, whether a kit stylesheet is referenced, and whether the MCP package is
+installed. It exits non-zero only for a real problem; "no `kai.json`" is information, because a
+hand-built project is not broken.
+
+## How the forwards work
+
+`create` and `add` are implemented by [`create-kai`](https://www.npmjs.com/package/create-kai), the
+package `npm create kai` resolves — so there is one implementation, and `kai add` and
+`npx create-kai add` cannot drift. `kai mcp` forwards to
+[`@kitn.ai/mcp`](https://www.npmjs.com/package/@kitn.ai/mcp) when it is installed, and otherwise
+says so and names `npx -y @kitn.ai/mcp`. That split is deliberate: the MCP is the only piece that
+needs the MCP SDK, and installing this CLI should not download it.
+
+## Docs
+
+- [Getting started](https://ui.kitn.ai/guides/getting-started/) — scaffold your first project
+- [For AI agents](https://ui.kitn.ai/guides/for-ai-agents/) — wiring the MCP into a harness (Claude Code, Codex, VS Code, Copilot, Cursor, Windsurf, Cline, Zed, Gemini CLI, OpenCode, dsh, Hermes; and what to do on Pi, which has no MCP in its core)
+- [Blocks](https://ui.kitn.ai/blocks/) — what `kai add` can write

package/bin/kai.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+// The `kai` launcher: the one command for @kitn.ai/ui's dev tooling.
+//
+// THREE KINDS OF VERB, and the distinction is the design (see bin/route.js):
+//
+//   local    dev, compile, eject, validate (the construct engine) and doctor. Their
+//            bundles are in THIS package's dist/, built by config/vite/node.ts.
+//   forward  create and add are `create-kai`'s, and mcp is `@kitn.ai/mcp`'s. Both are
+//            separate published programs reached by resolving their bin and spawning it
+//            with this process's stdio, so the prompt, the TTY and the exit code behave
+//            exactly as if the user had run that program directly.
+//   error    anything else, loudly, with the valid command list.
+//
+// WHY THE FORWARDS ARE NOT BUNDLED HERE. Measured: `@modelcontextprotocol/sdk` is 5.9 MB
+// installed with 17 direct dependencies, and `dist/construct-cli.es.js` does not import the
+// kit or the SDK at runtime at all. Bundling the MCP into this package would put that tree
+// into the install of everyone who only wants `kai add`. And create-kai is the package
+// npm's own `create` convention resolves for `npm create kai`, so its implementation has to
+// stay there; forwarding keeps one implementation rather than two.
+//
+// A missing forward target is a LOUD failure with the one-line fix, never a silent no-op:
+// a harness pointed at `kai mcp` in a project where @kitn.ai/mcp is not installed must not
+// look like a server that started and then said nothing.
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { decideEntry, KNOWN_COMMANDS } from './route.js';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG = join(HERE, '..');
+const require = createRequire(import.meta.url);
+
+const HELP = `kai — the @kitn.ai/ui command line
+
+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 doctor                 diagnose this project's kit wiring, versions and registration
+
+  kai mcp                    run the MCP server for AI coding harnesses (@kitn.ai/mcp)
+  kai dev <construct.json>   live preview with reload-on-edit
+  kai dev --builder          visual builder + live preview
+  kai compile <c.json> [out] one self-registering .js
+  kai eject <c.json> <outDir> write the generated Solid project (it's yours)
+  kai validate <c.json>      check a construct, print problems with paths
+
+Options
+  -h, --help                 this
+  -v, --version              print this CLI's version
+
+Installing
+  npm create kai             no install: npm resolves the create-kai package
+  npx -y @kitn.ai/mcp        the MCP server alone, for an MCP client config
+  npm i -g @kitn.ai/cli      kai on your PATH, for every project
+  npm i -D @kitn.ai/cli      pinned per project (npx kai ...)
+`;
+
+/** This package's own version, read from the manifest that ships beside this file. */
+function cliVersion() {
+  try {
+    return JSON.parse(readFileSync(join(PKG, 'package.json'), 'utf8')).version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Resolve another package's bin from its manifest and run it with this process's stdio.
+ *
+ * The bin is looked up through the PACKAGE (its `bin` field), not by path arithmetic into
+ * that package's internals: `bin` is the public contract, and a package that renames its
+ * dist file must not break this.
+ */
+function spawnBin(specifier, args, verb) {
+  let manifestPath;
+  try {
+    manifestPath = require.resolve(`${specifier}/package.json`);
+  } catch {
+    console.error(`[kai] ${verb}: ${specifier} is not installed, and it implements this verb.`);
+    console.error(`[kai]   install it once:  npm i -g ${specifier}`);
+    console.error(`[kai]   or run it without installing:  npx -y ${specifier}${verb === 'mcp' ? '' : ` ${verb}`}`);
+    process.exit(2);
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  const binField = manifest.bin;
+  const relative =
+    typeof binField === 'string' ? binField : Object.values(binField ?? {})[0];
+  if (!relative || typeof relative !== 'string') {
+    console.error(`[kai] ${verb}: ${specifier} declares no bin, so there is nothing to run.`);
+    process.exit(2);
+  }
+  const bin = join(dirname(manifestPath), relative);
+  const child = spawn(process.execPath, [bin, ...args], { stdio: 'inherit' });
+  child.on('error', (err) => {
+    console.error(`[kai] ${verb}: could not start ${specifier}:`, err);
+    process.exit(1);
+  });
+  child.on('exit', (code, signal) => {
+    process.exit(signal ? 1 : (code ?? 0));
+  });
+}
+
+/** Import a bundle this package built. `doctor` is called with its flags; the construct CLI
+ *  parses `process.argv` itself and sets `process.exitCode`, exactly as it did under its old bin. */
+async function runLocal(verb, args) {
+  if (verb === 'doctor') {
+    const bundle = pathToFileURL(join(PKG, 'dist', 'doctor.es.js')).href;
+    try {
+      const mod = await import(bundle);
+      return (await mod.runDoctor(args)) ?? 0;
+    } catch (err) {
+      console.error('[kai] doctor: could not load dist/doctor.es.js. If you are running from a checkout, build first: npm run build');
+      console.error(err);
+      process.exit(1);
+    }
+  }
+  const bundle = pathToFileURL(join(PKG, 'dist', 'construct-cli.es.js')).href;
+  try {
+    await import(bundle);
+  } catch (err) {
+    console.error(`[kai] ${verb}: could not load dist/construct-cli.es.js. If you are running from a checkout, build first: npm run build`);
+    console.error(err);
+    process.exit(1);
+  }
+  return undefined;
+}
+
+const [, , command, ...rest] = process.argv;
+const decision = decideEntry(command, rest);
+
+switch (decision.kind) {
+  case 'help':
+    console.log(HELP);
+    break;
+  case 'version':
+    console.log(cliVersion());
+    break;
+  case 'error':
+    console.error(`[kai] ${decision.message}`);
+    console.error(`[kai] run \`kai --help\` for the full surface.`);
+    process.exitCode = 2;
+    break;
+  case 'forward':
+    spawnBin(decision.pkg, decision.args, command);
+    break;
+  case 'local': {
+    // `doctor`'s own flags start after the verb; the construct CLI parses argv itself, so it
+    // gets nothing from here.
+    const code = await runLocal(decision.verb, decision.verb === 'doctor' ? rest : []);
+    if (typeof code === 'number') process.exitCode = code;
+    break;
+  }
+  default:
+    console.error(`[kai] ${KNOWN_COMMANDS.length} verbs are defined but this one is not routed: ${decision.kind}`);
+    process.exitCode = 2;
+}

package/bin/route.js

@@ -0,0 +1,61 @@
+// Pure command routing for the `kai` bin, extracted so it can be tested without
+// spawning a process or reading the filesystem. `bin/kai.js` does the actual work
+// based on what this returns.
+//
+// THREE KINDS OF VERB, and the distinction is the whole design:
+//
+//   '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
+//                   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.
+//   'error'      -- anything else. A typo must never fall through to a server or a verb
+//                   that does the wrong thing; it names the valid commands instead.
+//
+// `mcp` stays a verb even though the server is its own package, so `kai --help` remains
+// the complete surface and a harness config can still say `kai mcp` once both packages
+// are installed. When @kitn.ai/mcp is absent the forwarder says so and names the one-line
+// fix rather than failing obscurely.
+
+export const CONSTRUCT_COMMANDS = ['dev', 'compile', 'eject', 'validate'];
+
+/** Verbs a human types, whether or not the target package is installed. */
+export const KNOWN_COMMANDS = [
+  'create',
+  'add',
+  'doctor',
+  'mcp',
+  ...CONSTRUCT_COMMANDS,
+];
+
+/**
+ * @param {string | undefined} command
+ * @returns {{ kind: 'local', verb: string }
+ *          | { kind: 'forward', pkg: string, args: string[] }
+ *          | { kind: 'help' }
+ *          | { kind: 'version' }
+ *          | { kind: 'error', message: string }}
+ */
+export function decideEntry(command, rest = []) {
+  if (command === undefined || command === 'help' || command === '--help' || command === '-h') {
+    return { kind: 'help' };
+  }
+  if (command === 'version' || command === '--version' || command === '-v') {
+    return { kind: 'version' };
+  }
+  // `kai create [dir]` and `kai add <block>` are create-kai's verbs, unchanged: the
+  // 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] };
+  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' };
+  return {
+    kind: 'error',
+    message: `unknown command "${command}" — valid commands: ${KNOWN_COMMANDS.join(', ')}`,
+  };
+}