@ikenga/cli 0.2.0 → 0.3.1

package/README.md

@@ -1,6 +1,17 @@
 # @ikenga/cli
 
-Command-line tool for managing Ikenga pkgs.
+[![Version](https://img.shields.io/badge/version-v0.3.0-blue.svg)](https://github.com/Royalti-io/ikenga-cli/releases)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
+> `ikenga` — the disk-side package manager for the Ikenga workspace. Install, update, and
+> hot-mount pkgs.
+
+## What it is
+
+`ikenga` manages packages on disk: what's installed, what's available in the registry, and
+the dev loop for authoring your own. It's one of two Ikenga CLIs — the **disk-side** one.
+(The other, [`iyke`](https://github.com/Royalti-io/iyke-cli), drives a *running* shell.
+They share no code.)
 
 ## Install
 
@@ -26,11 +37,38 @@ 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
+```
+
+`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.
 ```
 
-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.
+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).
+
+## Links
+
+- [`iyke-cli`](https://github.com/Royalti-io/iyke-cli) — the runtime controller (the *other* CLI)
+- [`ikenga`](https://github.com/Royalti-io/ikenga) — the desktop shell
+
+## License
+
+Apache-2.0 — see [`LICENSE`](LICENSE).

package/dist/index.js

@@ -1,21 +1,17 @@
 #!/usr/bin/env bun
 // @bun
 var __defProp = Object.defineProperty;
-var __returnValue = (v) => v;
-function __exportSetter(name, newValue) {
-  this[name] = __returnValue.bind(null, newValue);
-}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: __exportSetter.bind(all, name)
+      set: (newValue) => all[name] = () => newValue
     });
 };
 
-// node_modules/zod/v3/external.js
+// ../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/external.js
 var exports_external = {};
 __export(exports_external, {
   void: () => voidType,
@@ -127,7 +123,7 @@ __export(exports_external, {
   BRAND: () => BRAND
 });
 
-// node_modules/zod/v3/helpers/util.js
+// ../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/helpers/util.js
 var util;
 (function(util2) {
   util2.assertEqual = (_) => {};
@@ -258,7 +254,7 @@ var getParsedType = (data) => {
   }
 };
 
-// node_modules/zod/v3/ZodError.js
+// ../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/ZodError.js
 var ZodIssueCode = util.arrayToEnum([
   "invalid_type",
   "invalid_literal",
@@ -377,7 +373,7 @@ ZodError.create = (issues) => {
   return error;
 };
 
-// node_modules/zod/v3/locales/en.js
+// ../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/locales/en.js
 var errorMap = (issue, _ctx) => {
   let message;
   switch (issue.code) {
@@ -480,7 +476,7 @@ var errorMap = (issue, _ctx) => {
 };
 var en_default = errorMap;
 
-// node_modules/zod/v3/errors.js
+// ../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/errors.js
 var overrideErrorMap = en_default;
 function setErrorMap(map) {
   overrideErrorMap = map;
@@ -488,7 +484,7 @@ function setErrorMap(map) {
 function getErrorMap() {
   return overrideErrorMap;
 }
-// node_modules/zod/v3/helpers/parseUtil.js
+// ../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
   const { data, path, errorMaps, issueData } = params;
   const fullPath = [...path, ...issueData.path || []];
@@ -594,14 +590,14 @@ var isAborted = (x) => x.status === "aborted";
 var isDirty = (x) => x.status === "dirty";
 var isValid = (x) => x.status === "valid";
 var isAsync = (x) => typeof Promise !== "undefined" && x instanceof Promise;
-// node_modules/zod/v3/helpers/errorUtil.js
+// ../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/helpers/errorUtil.js
 var errorUtil;
 (function(errorUtil2) {
   errorUtil2.errToObj = (message) => typeof message === "string" ? { message } : message || {};
   errorUtil2.toString = (message) => typeof message === "string" ? message : message?.message;
 })(errorUtil || (errorUtil = {}));
 
-// node_modules/zod/v3/types.js
+// ../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/types.js
 class ParseInputLazyPath {
   constructor(parent, value, path, key) {
     this._cachedPath = [];
@@ -3988,7 +3984,7 @@ var coerce = {
   date: (arg) => ZodDate.create({ ...arg, coerce: true })
 };
 var NEVER = INVALID;
-// node_modules/@ikenga/contract/dist/engine.js
+// ../node_modules/.pnpm/@ikenga+contract@0.5.0/node_modules/@ikenga/contract/dist/engine.js
 var AgentCapabilitiesSchema = exports_external.object({
   streaming: exports_external.boolean(),
   toolUse: exports_external.boolean(),
@@ -4019,7 +4015,7 @@ var EngineProvidesSchema = exports_external.object({
   })
 });
 
-// node_modules/@ikenga/contract/dist/manifest.js
+// ../node_modules/.pnpm/@ikenga+contract@0.5.0/node_modules/@ikenga/contract/dist/manifest.js
 var AuthorSchema = exports_external.object({
   name: exports_external.string(),
   key: exports_external.string().optional()
@@ -4134,7 +4130,7 @@ var ManifestSchema = exports_external.object({
   engine: EngineProvidesSchema.optional()
 });
 
-// node_modules/@ikenga/contract/dist/registry.js
+// ../node_modules/.pnpm/@ikenga+contract@0.5.0/node_modules/@ikenga/contract/dist/registry.js
 var REGISTRY_SCHEMA_VERSION = 1;
 var PkgDepSchema = exports_external.object({
   name: exports_external.string(),
@@ -4174,7 +4170,7 @@ function pkgDetailPath(npmName) {
   return `pkgs/${pkgShortName(npmName)}.json`;
 }
 
-// node_modules/@noble/ed25519/index.js
+// ../node_modules/.pnpm/@noble+ed25519@2.3.0/node_modules/@noble/ed25519/index.js
 /*! noble-ed25519 - MIT License (c) 2019 Paul Miller (paulmillr.com) */
 var ed25519_CURVE = {
   p: 0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffedn,
@@ -4595,7 +4591,7 @@ var wNAF = (n) => {
   return { p, f };
 };
 
-// node_modules/@noble/hashes/esm/utils.js
+// ../node_modules/.pnpm/@noble+hashes@1.8.0/node_modules/@noble/hashes/esm/utils.js
 /*! noble-hashes - MIT License (c) 2022 Paul Miller (paulmillr.com) */
 function isBytes2(a) {
   return a instanceof Uint8Array || ArrayBuffer.isView(a) && a.constructor.name === "Uint8Array";
@@ -4676,7 +4672,7 @@ function createOptHasher(hashCons) {
   return hashC;
 }
 
-// node_modules/@noble/hashes/esm/_blake.js
+// ../node_modules/.pnpm/@noble+hashes@1.8.0/node_modules/@noble/hashes/esm/_blake.js
 var BSIGMA = /* @__PURE__ */ Uint8Array.from([
   0,
   1,
@@ -4936,7 +4932,7 @@ var BSIGMA = /* @__PURE__ */ Uint8Array.from([
   9
 ]);
 
-// node_modules/@noble/hashes/esm/_md.js
+// ../node_modules/.pnpm/@noble+hashes@1.8.0/node_modules/@noble/hashes/esm/_md.js
 function setBigUint64(view, byteOffset, value, isLE2) {
   if (typeof view.setBigUint64 === "function")
     return view.setBigUint64(byteOffset, value, isLE2);
@@ -5058,7 +5054,7 @@ var SHA512_IV = /* @__PURE__ */ Uint32Array.from([
   327033209
 ]);
 
-// node_modules/@noble/hashes/esm/_u64.js
+// ../node_modules/.pnpm/@noble+hashes@1.8.0/node_modules/@noble/hashes/esm/_u64.js
 var U32_MASK64 = /* @__PURE__ */ BigInt(2 ** 32 - 1);
 var _32n = /* @__PURE__ */ BigInt(32);
 function fromBig(n, le = false) {
@@ -5095,7 +5091,7 @@ var add4H = (low, Ah, Bh, Ch, Dh) => Ah + Bh + Ch + Dh + (low / 2 ** 32 | 0) | 0
 var add5L = (Al, Bl, Cl, Dl, El) => (Al >>> 0) + (Bl >>> 0) + (Cl >>> 0) + (Dl >>> 0) + (El >>> 0);
 var add5H = (low, Ah, Bh, Ch, Dh, Eh) => Ah + Bh + Ch + Dh + Eh + (low / 2 ** 32 | 0) | 0;
 
-// node_modules/@noble/hashes/esm/blake2.js
+// ../node_modules/.pnpm/@noble+hashes@1.8.0/node_modules/@noble/hashes/esm/blake2.js
 var B2B_IV = /* @__PURE__ */ Uint32Array.from([
   4089235720,
   1779033703,
@@ -5378,10 +5374,10 @@ class BLAKE2b extends BLAKE2 {
 }
 var blake2b = /* @__PURE__ */ createOptHasher((opts) => new BLAKE2b(opts));
 
-// node_modules/@noble/hashes/esm/blake2b.js
+// ../node_modules/.pnpm/@noble+hashes@1.8.0/node_modules/@noble/hashes/esm/blake2b.js
 var blake2b2 = blake2b;
 
-// node_modules/@noble/hashes/esm/sha2.js
+// ../node_modules/.pnpm/@noble+hashes@1.8.0/node_modules/@noble/hashes/esm/sha2.js
 var K512 = /* @__PURE__ */ (() => split([
   "0x428a2f98d728ae22",
   "0x7137449123ef65cd",
@@ -5580,10 +5576,10 @@ class SHA512 extends HashMD {
 }
 var sha512 = /* @__PURE__ */ createHasher(() => new SHA512);
 
-// node_modules/@noble/hashes/esm/sha512.js
+// ../node_modules/.pnpm/@noble+hashes@1.8.0/node_modules/@noble/hashes/esm/sha512.js
 var sha5122 = sha512;
 
-// node_modules/@ikenga/registry-client/dist/minisign.js
+// ../node_modules/.pnpm/@ikenga+registry-client@0.1.0/node_modules/@ikenga/registry-client/dist/minisign.js
 etc.sha512Sync = (...m) => sha5122(etc.concatBytes(...m));
 var ALG_ED25519_LEGACY = new Uint8Array([69, 100]);
 var ALG_ED25519_PREHASHED = new Uint8Array([69, 68]);
@@ -5673,7 +5669,7 @@ function hex(bytes) {
   return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 
-// node_modules/@ikenga/registry-client/dist/fetch.js
+// ../node_modules/.pnpm/@ikenga+registry-client@0.1.0/node_modules/@ikenga/registry-client/dist/fetch.js
 async function fetchIndex(opts) {
   const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
   if (!fetchImpl) {
@@ -5719,7 +5715,7 @@ async function fetchPkgDetail(opts) {
   const json = await res.json();
   return PkgDetailSchema.parse(json);
 }
-// node_modules/@ikenga/registry-client/dist/resolve.js
+// ../node_modules/.pnpm/@ikenga+registry-client@0.1.0/node_modules/@ikenga/registry-client/dist/resolve.js
 async function resolveInstallPlan(opts) {
   const plan = [];
   const seen = new Map;
@@ -5827,7 +5823,7 @@ import {
 } from "fs";
 import { join as join2 } from "path";
 
-// node_modules/tar/dist/esm/index.min.js
+// ../node_modules/.pnpm/tar@7.5.15/node_modules/tar/dist/esm/index.min.js
 import Vr from "events";
 import I2 from "fs";
 import { EventEmitter as Li } from "events";
@@ -9208,20 +9204,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 +9500,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 +9695,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 +9704,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 +9714,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 +9733,7 @@ async function main() {
     return 0;
   }
   if (sub === "--version" || sub === "-V") {
-    process.stdout.write(`ikenga ${"0.2.0"}
+    process.stdout.write(`ikenga ${"0.3.1"}
 `);
     return 0;
   }
@@ -9514,6 +9774,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.1",
   "description": "Command-line tool for installing, updating, and managing Ikenga pkgs.",
   "license": "Apache-2.0",
   "repository": {