@ikenga/cli 0.2.0 → 0.3.0

package/README.md

@@ -26,11 +26,29 @@ ikenga update <pkg>                      # update one
 ikenga update --all                      # update everything outdated
 ikenga remove com.ikenga.hello           # by manifest id, or...
 ikenga remove @ikenga/pkg-hello          # ...by npm name
+ikenga dev ./my-pkg                      # hot-mount into running shell
 ```
 
-Installs land in the shell's pkgs directory (overridable with `IKENGA_APP_DATA_DIR`). The shell registers them on next boot. The CLI does not currently talk to a running shell over IPC; that's a planned enhancement.
+`list / add / update / remove` mutate the shell's pkgs directory (overridable with `IKENGA_APP_DATA_DIR`); the shell registers them on next boot.
+
+### `ikenga dev <path>` — hot-mount for development
+
+Different shape: `dev` talks to a **running** shell over its localhost iyke bridge instead of touching disk. Registers the pkg with `source.kind = "dev"` (auto-trusted, regardless of id namespace) and spawns a manifest watcher in the kernel so edits to `manifest.json` or any `restart_when_changed` glob trip an in-place reload — no shell restart.
+
+Requires the shell to be running. The CLI discovers its port + bearer token from `control.json` in the shell's local data dir.
+
+```bash
+ikenga dev /home/me/code/my-pkg
+# → mounted as com.example.my-pkg v0.1.0
+# →   Routes: /pkg/com.example.my-pkg/
+# Edit manifest.json or watched src/ files; reload fires automatically.
+# Ctrl-C to unregister.
+```
+
+Iframe code changes flow through your dev server's HMR (Vite, Next, …); sidecar / MCP source edits respawn via the supervisor watcher; manifest edits trigger a full pkg reload that emits a `pkg-reloaded` event the shell's iframe + webview hosts listen for. See [`docs/pkg-patterns/07-dev-mode.md`](https://github.com/Royalti-io/ikenga/blob/main/docs/pkg-patterns/07-dev-mode.md) for the kernel semantics.
 
 ## Versioning
 
+`v0.3.0` — adds `ikenga dev <path>` for hot-mounting pkgs into a running shell via the iyke localhost bridge. Watcher-driven manifest reload + clean `Ctrl-C` unregister. Requires the corresponding shell-side dev-mode kernel (lands in shell `v0.0.5+`).
 `v0.2.0` — JS-source npm distribution; requires Bun on `$PATH`.
 `v0.1.x` — bun-compiled standalone binaries (deprecated; available on the GitHub Releases page until the next archive sweep).

package/dist/index.js

@@ -9208,20 +9208,277 @@ function parseSpec(spec) {
   return { name: spec.slice(0, idx), version: spec.slice(idx + 1) || undefined };
 }
 
-// src/lib/installed.ts
-import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync2, statSync } from "fs";
+// src/commands/dev.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3, statSync as statSync2 } from "fs";
+import { resolve } from "path";
+
+// src/lib/iyke-bridge.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, statSync, unlinkSync } from "fs";
+import { homedir as homedir2, platform as platform2 } from "os";
 import { join as join3 } from "path";
+var APP_IDENTIFIER = "app.ikenga";
+var STALE_THRESHOLD_SECS = 5 * 60;
+function appLocalDataDir() {
+  const override = process.env.IKENGA_APP_LOCAL_DATA_DIR;
+  if (override)
+    return override;
+  const home = homedir2();
+  switch (platform2()) {
+    case "darwin":
+      return join3(home, "Library", "Application Support", APP_IDENTIFIER);
+    case "win32": {
+      const local = process.env.LOCALAPPDATA;
+      if (local)
+        return join3(local, APP_IDENTIFIER);
+      return join3(home, "AppData", "Local", APP_IDENTIFIER);
+    }
+    default: {
+      const xdg = process.env.XDG_DATA_HOME;
+      if (xdg)
+        return join3(xdg, APP_IDENTIFIER);
+      return join3(home, ".local", "share", APP_IDENTIFIER);
+    }
+  }
+}
+function controlPath() {
+  return join3(appLocalDataDir(), "control.json");
+}
+function isPidAlive(pid) {
+  if (platform2() === "win32")
+    return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    const err2 = e;
+    return err2.code === "EPERM";
+  }
+}
+function loadControl() {
+  const path = controlPath();
+  if (!existsSync2(path)) {
+    return { kind: "missing" };
+  }
+  const raw = readFileSync2(path, "utf8");
+  const cf = JSON.parse(raw);
+  if (cf.schema_version !== 1) {
+    throw new Error(`unsupported control.json schema_version: ${cf.schema_version} (CLI built for v1)`);
+  }
+  if (isPidAlive(cf.pid)) {
+    return { kind: "ok", cf };
+  }
+  const nowMs = Date.now();
+  const ageMs = Math.max(0, nowMs - cf.started_at_unix_ms);
+  const ageSecs = Math.floor(ageMs / 1000);
+  if (ageSecs >= STALE_THRESHOLD_SECS) {
+    try {
+      unlinkSync(path);
+    } catch {}
+    return { kind: "stale_removed" };
+  }
+  return { kind: "stale_young", age_secs: ageSecs };
+}
+
+class IykeClient {
+  base;
+  token;
+  constructor(cf) {
+    this.base = `http://127.0.0.1:${cf.port}`;
+    this.token = cf.token;
+  }
+  async post(path, body) {
+    const res = await fetch(`${this.base}${path}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.token}`
+      },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      const text2 = await res.text().catch(() => "");
+      throw new Error(`POST ${path} failed: ${res.status} ${text2}`);
+    }
+    const text = await res.text();
+    return text ? JSON.parse(text) : {};
+  }
+  async get(path) {
+    const res = await fetch(`${this.base}${path}`, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${this.token}` }
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`GET ${path} failed: ${res.status} ${text}`);
+    }
+    return await res.json();
+  }
+}
+function connectOrThrow() {
+  const outcome = loadControl();
+  switch (outcome.kind) {
+    case "ok":
+      return new IykeClient(outcome.cf);
+    case "missing":
+      throw new Error(`Ikenga shell is not running.
+  Expected control.json at ${controlPath()}
+  Start the shell, then re-run this command.`);
+    case "stale_removed":
+      throw new Error(`Ikenga shell control file was stale (crashed shell) \u2014 cleaned up.
+  Start the shell and re-run this command.`);
+    case "stale_young":
+      throw new Error(`Ikenga shell control file is ${outcome.age_secs}s old but the PID is dead.
+  Likely a launch race. Retry in a moment or remove ${controlPath()} manually.`);
+  }
+}
+
+// src/commands/dev.ts
+async function devCommand(rawPath) {
+  const path = resolve(rawPath);
+  if (!existsSync3(path)) {
+    process.stderr.write(`error: ${path} does not exist
+`);
+    return 1;
+  }
+  if (!statSync2(path).isDirectory()) {
+    process.stderr.write(`error: ${path} is not a directory
+`);
+    return 1;
+  }
+  const manifestPath = `${path}/manifest.json`;
+  if (!existsSync3(manifestPath)) {
+    process.stderr.write(`error: no manifest.json at ${manifestPath}
+`);
+    return 1;
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync3(manifestPath, "utf8"));
+  } catch (err2) {
+    process.stderr.write(`error: failed to parse manifest.json: ${err2.message}
+`);
+    return 1;
+  }
+  if (!manifest.id || !manifest.name || !manifest.version || !manifest.ikenga_api) {
+    process.stderr.write(`error: manifest missing required fields (id, name, version, ikenga_api)
+`);
+    return 1;
+  }
+  let client;
+  try {
+    client = connectOrThrow();
+  } catch (err2) {
+    process.stderr.write(`error: ${err2.message}
+`);
+    return 1;
+  }
+  process.stdout.write(`\u2192 registering ${manifest.id}@${manifest.version} from ${path}
+`);
+  let registered;
+  try {
+    registered = await client.post("/iyke/pkg/dev/register", {
+      install_path: path
+    });
+  } catch (err2) {
+    process.stderr.write(`error: ${err2.message}
+`);
+    return 1;
+  }
+  process.stdout.write(`
+\u2713 mounted as ${registered.installed.id} v${registered.installed.version}
+`);
+  printPkgSurface(manifest);
+  process.stdout.write(`
+Watching manifest.json + restart_when_changed globs.
+`);
+  process.stdout.write(`  Edit the manifest to trigger a reload (250ms debounce).
+`);
+  process.stdout.write(`  Sidecar / MCP code changes restart via the supervisor watcher.
+`);
+  process.stdout.write(`  Iframe code changes flow through your dev server's HMR.
+`);
+  process.stdout.write(`
+  Ctrl-C to unregister and exit.
+`);
+  const pkgId = registered.installed.id;
+  return new Promise((resolveExit) => {
+    let unregistering = false;
+    const cleanup = async () => {
+      if (unregistering)
+        return;
+      unregistering = true;
+      process.stdout.write(`
+\u2192 unregistering ${pkgId}
+`);
+      try {
+        await client.post("/iyke/pkg/dev/unregister", { pkg_id: pkgId });
+        process.stdout.write(`\u2713 done
+`);
+        resolveExit(0);
+      } catch (err2) {
+        process.stderr.write(`error: ${err2.message}
+`);
+        resolveExit(1);
+      }
+    };
+    process.on("SIGINT", () => {
+      cleanup();
+    });
+    process.on("SIGTERM", () => {
+      cleanup();
+    });
+    setInterval(() => {}, 60000);
+  });
+}
+function printPkgSurface(m2) {
+  if (m2.ui?.routes?.length) {
+    process.stdout.write(`
+  Routes:
+`);
+    for (const r of m2.ui.routes) {
+      process.stdout.write(`    /pkg/${m2.id}${r.path}   (${r.kind}: ${r.source})
+`);
+    }
+  }
+  if (m2.mcp?.length) {
+    process.stdout.write(`
+  MCP servers:
+`);
+    for (const s3 of m2.mcp) {
+      process.stdout.write(`    ${s3.name}
+`);
+    }
+  }
+  if (m2.sidecars?.length) {
+    process.stdout.write(`
+  Sidecars:
+`);
+    for (const s3 of m2.sidecars) {
+      process.stdout.write(`    ${s3.name}
+`);
+    }
+  }
+  if (m2.engine?.agentId) {
+    process.stdout.write(`
+  Engine: ${m2.engine.agentId}
+`);
+  }
+}
+
+// src/lib/installed.ts
+import { existsSync as existsSync4, readdirSync, readFileSync as readFileSync4, statSync as statSync3 } from "fs";
+import { join as join4 } from "path";
 function listInstalled() {
   const root = pkgsDir();
-  if (!existsSync2(root))
+  if (!existsSync4(root))
     return [];
   const out = [];
   for (const name of readdirSync(root)) {
     if (name.startsWith("."))
       continue;
-    const dir = join3(root, name);
+    const dir = join4(root, name);
     try {
-      if (!statSync(dir).isDirectory())
+      if (!statSync3(dir).isDirectory())
         continue;
     } catch {
       continue;
@@ -9247,11 +9504,11 @@ function findInstalled(pkgId) {
   return listInstalled().find((p2) => p2.id === pkgId) ?? null;
 }
 function readManifest(dir) {
-  const path = join3(dir, "manifest.json");
-  if (!existsSync2(path))
+  const path = join4(dir, "manifest.json");
+  if (!existsSync4(path))
     return null;
   try {
-    const json = JSON.parse(readFileSync2(path, "utf8"));
+    const json = JSON.parse(readFileSync4(path, "utf8"));
     if (typeof json?.id !== "string" || typeof json?.version !== "string") {
       return null;
     }
@@ -9442,7 +9699,7 @@ function npmNameToPkgId2(npmName) {
 }
 
 // src/index.ts
-var SUBCOMMANDS = ["list", "add", "update", "remove"];
+var SUBCOMMANDS = ["list", "add", "update", "remove", "dev"];
 function usage() {
   return `ikenga \u2014 pkg manager for the Ikenga shell
 
@@ -9451,6 +9708,7 @@ Usage:
   ikenga add <pkg>[@<version>] [--dry-run]
   ikenga update [<pkg> | --all] [--dry-run]
   ikenga remove <pkg>
+  ikenga dev <path>
 
 Examples:
   ikenga list                              # what's installed locally
@@ -9460,9 +9718,15 @@ Examples:
   ikenga update --all                      # update everything outdated
   ikenga remove com.ikenga.hello           # by manifest id, or...
   ikenga remove @ikenga/pkg-hello          # ...by npm name
+  ikenga dev ./my-pkg                      # hot-mount into running shell
 
 Installs land in the shell's pkgs directory (overridable with
 IKENGA_APP_DATA_DIR). The shell registers them on next boot.
+
+\`ikenga dev <path>\` is different \u2014 it talks to a running shell over its
+localhost iyke bridge, registers the pkg with hot-reload semantics
+(manifest edits trigger an in-place reload, no shell restart), and
+unregisters cleanly on Ctrl-C. Requires the shell to be running.
 `;
 }
 async function main() {
@@ -9473,7 +9737,7 @@ async function main() {
     return 0;
   }
   if (sub === "--version" || sub === "-V") {
-    process.stdout.write(`ikenga ${"0.2.0"}
+    process.stdout.write(`ikenga ${"0.3.0"}
 `);
     return 0;
   }
@@ -9514,6 +9778,15 @@ async function main() {
       }
       return removeCommand(spec);
     }
+    case "dev": {
+      const path = rest.find((a) => !a.startsWith("-"));
+      if (!path) {
+        process.stderr.write(`usage: ikenga dev <path>
+`);
+        return 1;
+      }
+      return devCommand(path);
+    }
   }
 }
 var code = await main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikenga/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Command-line tool for installing, updating, and managing Ikenga pkgs.",
   "license": "Apache-2.0",
   "repository": {