@seqyuan/ennote 0.4.0 → 0.6.0

package/bin/ennote.js

@@ -16,7 +16,20 @@ const DEFAULT_PORT = "45131";
 const DEFAULT_HOSTNAME = "127.0.0.1";
 const START_TIMEOUT_MS = 45_000;
 const STOP_TIMEOUT_MS = 15_000;
-const GITHUB_RELEASES_BASE = "https://github.com/seqyuan/ennote/releases/download";
+const PACK_INSPECT_TIMEOUT_MS = 15_000;
+const PACK_REQUEST_TIMEOUT_MS = 15_000;
+const DEFAULT_RELEASES_BASE = "https://github.com/seqyuan/ennote/releases/download";
+
+// releasesBase honours ENNOTE_RELEASES_BASE so a mirror (or an air-gapped
+// install serving the release assets locally) can be used instead of GitHub.
+// The value is read at call time, not import time, so a wrapper script that
+// sets it still affects this process. HTTPS is enforced by requireHTTPS.
+function releasesBase() {
+  const override = String(process.env.ENNOTE_RELEASES_BASE ?? "").trim();
+  return override === "" ? DEFAULT_RELEASES_BASE : override.replace(/\/+$/, "");
+}
+
+const BINARY_NAMES = ["ennogate", "ennoworker"];
 
 function platformSuffix(platform = os.platform(), arch = os.arch()) {
   if (!new Set(["linux", "darwin"]).has(platform)) {
@@ -54,6 +67,18 @@ function statePaths(home) {
   };
 }
 
+// workerStatePath is the owner-only handshake file ennoworker writes and
+// ennogate supervises (see internal/runtimeinfo.WorkerState).
+function workerStatePath(home) {
+  return path.join(home, "runtime", "worker-state.json");
+}
+
+function usageError(message) {
+  const error = new Error(message);
+  error.exitCode = 2;
+  return error;
+}
+
 function validateRuntime(paths) {
   for (const [name, file] of [["ennogate", paths.gate], ["ennoworker", paths.worker]]) {
     if (!fs.existsSync(file)) throw new Error(`Missing ${name} binary: ${file}`);
@@ -87,6 +112,53 @@ function removeFile(file) {
   }
 }
 
+// compareVersions orders dotted numeric versions. A pre-release suffix sorts
+// before the release it belongs to, so 0.5.0-rc1 < 0.5.0.
+function compareVersions(left, right) {
+  const parse = (value) => {
+    const [core, ...pre] = String(value).split("-");
+    return { parts: core.split(".").map((part) => Number.parseInt(part, 10) || 0), pre: pre.join("-") };
+  };
+  const a = parse(left);
+  const b = parse(right);
+  const length = Math.max(a.parts.length, b.parts.length);
+  for (let index = 0; index < length; index += 1) {
+    const difference = (a.parts[index] ?? 0) - (b.parts[index] ?? 0);
+    if (difference !== 0) return difference;
+  }
+  if (a.pre === b.pre) return 0;
+  if (a.pre === "") return 1;
+  if (b.pre === "") return -1;
+  return a.pre < b.pre ? -1 : 1;
+}
+
+// cachedBinaryVersions lists the versions that already have BOTH binaries for
+// this platform, newest first. A version with only one binary is an abandoned
+// partial download and must not be offered as a fallback. Selection is explicit
+// rather than readdir order, which is filesystem-defined.
+function cachedBinaryVersions(home, suffix) {
+  const binDir = runtimeBinDir(home);
+  let entries;
+  try {
+    entries = fs.readdirSync(binDir);
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+  const versions = new Set();
+  for (const entry of entries) {
+    for (const name of BINARY_NAMES) {
+      const postfix = `-${suffix}`;
+      if (!entry.startsWith(`${name}-`) || !entry.endsWith(postfix)) continue;
+      const version = entry.slice(name.length + 1, entry.length - postfix.length);
+      if (version !== "") versions.add(version);
+    }
+  }
+  return [...versions]
+    .filter((version) => BINARY_NAMES.every((name) => fs.existsSync(path.join(binDir, `${name}-${version}-${suffix}`))))
+    .sort((a, b) => compareVersions(b, a));
+}
+
 function isPidAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
   try {
@@ -246,33 +318,56 @@ function downloadText(url) {
   });
 }
 
-async function ensureBinaries(home, pkg, log, platform = os.platform(), arch = os.arch()) {
+async function ensureBinaries(home, pkg, log, platform = os.platform(), arch = os.arch(), download = {}) {
   const suffix = platformSuffix(platform, arch);
   const version = pkg.version;
   const binDir = runtimeBinDir(home);
   ensureDirectory(binDir);
-  const gatePath = path.join(binDir, `ennogate-${version}-${suffix}`);
-  const workerPath = path.join(binDir, `ennoworker-${version}-${suffix}`);
-  const needed = [];
-  if (!fs.existsSync(gatePath)) needed.push({ name: "ennogate", path: gatePath });
-  if (!fs.existsSync(workerPath)) needed.push({ name: "ennoworker", path: workerPath });
-  if (needed.length === 0) return;
-  log(`Downloading ${needed.length} binary(s) for ${suffix}...`);
-  const sumsUrl = `${GITHUB_RELEASES_BASE}/v${version}/SHA256SUMS`;
-  const sumsText = await downloadText(sumsUrl);
-  for (const { name, path: dest } of needed) {
-    const filename = `${name}-${suffix}`;
-    const expected = parseSHA256SUMS(sumsText, filename);
-    const url = `${GITHUB_RELEASES_BASE}/v${version}/${filename}`;
-    await downloadFile(url, dest);
-    try {
-      verifyFileSHA256(dest, expected);
-    } catch (error) {
-      try { fs.unlinkSync(dest); } catch {}
-      throw error;
+  const binaryPath = (name, at) => path.join(binDir, `${name}-${at}-${suffix}`);
+  const missing = BINARY_NAMES.filter((name) => !fs.existsSync(binaryPath(name, version)));
+  if (missing.length === 0) return { version, fallback: false };
+
+  const base = releasesBase();
+  const fetchText = download.downloadText ?? downloadText;
+  const fetchFile = download.downloadFile ?? downloadFile;
+  const sumsUrl = `${base}/v${version}/SHA256SUMS`;
+  log(`Downloading ${missing.length} binary(s) for ${suffix}...`);
+  try {
+    const sumsText = await fetchText(sumsUrl);
+    for (const name of missing) {
+      const filename = `${name}-${suffix}`;
+      const dest = binaryPath(name, version);
+      const expected = parseSHA256SUMS(sumsText, filename);
+      try {
+        await fetchFile(`${base}/v${version}/${filename}`, dest);
+        verifyFileSHA256(dest, expected);
+      } catch (error) {
+        // Never leave a partial or unverified binary behind: it would look like
+        // a usable cache entry to the next run.
+        removeFile(dest);
+        throw error;
+      }
+    }
+    return { version, fallback: false };
+  } catch (error) {
+    // Downloading needs GitHub. A local-first runtime should still start from a
+    // binary that is already on disk rather than fail on a network the user may
+    // not have, so an older cached version is better than no server.
+    const fallback = cachedBinaryVersions(home, suffix)[0];
+    if (!fallback) {
+      throw new Error(
+        `failed to install Ennote ${version} binaries: ${error.message}; ` +
+        `attempted ${sumsUrl} and found no complete cached build under ${binDir} for ${suffix}. ` +
+        `Install the release assets manually or set ENNOTE_RELEASES_BASE to a mirror.`,
+      );
     }
+    log(
+      `warning: failed to install Ennote ${version} binaries (${error.message}); ` +
+      `using cached ${fallback} for ${suffix} instead. ` +
+      `The Worker is older than the CLI's expected ${version}; re-run with network access to update.`,
+    );
+    return { version: fallback, fallback: true };
   }
-  log("Binaries ready.");
 }
 
 async function startService(options) {
@@ -290,8 +385,8 @@ async function startService(options) {
   if (!await canBind(port, hostname)) throw new Error(`Port ${port} is already in use on ${hostname}`);
 
   const pkg = JSON.parse(fs.readFileSync(path.join(packageDir, "package.json"), "utf8"));
-  await ensureBinaries(home, pkg, log);
-  const runtime = runtimePaths(packageDir, home, pkg.version);
+  const binaries = await ensureBinaries(home, pkg, log);
+  const runtime = runtimePaths(packageDir, home, binaries.version);
   validateRuntime(runtime);
   ensureDirectory(home);
   const output = fs.openSync(files.log, "a", 0o600);
@@ -302,6 +397,9 @@ async function startService(options) {
       ENNOTE_HOME: home,
       ENNOTE_STATIC_DIR: runtime.staticDir,
       ENNOTE_WORKER_PATH: runtime.worker,
+      ...(fs.existsSync(path.join(packageDir, "skills"))
+        ? { ENNOTE_BUILTIN_SKILLS_DIR: path.join(packageDir, "skills") }
+        : {}),
       PORT: String(port),
       ENNOTE_HOSTNAME: hostname,
     },
@@ -315,9 +413,14 @@ async function startService(options) {
     port: String(port),
     hostname,
     url,
+    // Which build is actually serving: an offline start can run a cached
+    // version older than this CLI, and that has to be recoverable after the
+    // fact rather than only visible in one warning line.
+    binaryVersion: binaries.version,
+    binaryFallback: binaries.fallback,
     startedAt: new Date().toISOString(),
   });
-  log(`starting ennogate pid=${child.pid} url=${url}`);
+  log(`starting ennogate pid=${child.pid} url=${url} bin=${binaries.version}${binaries.fallback ? " (cached fallback)" : ""}`);
 
   const deadline = Date.now() + START_TIMEOUT_MS;
   while (Date.now() < deadline) {
@@ -359,7 +462,381 @@ async function serviceStatus(home) {
     return { running: false, stale: Boolean(state) };
   }
   const healthy = await healthCheck(state.url);
-  return { running: healthy, healthy, pid: state.pid, url: state.url, port: state.port };
+  return {
+    running: healthy,
+    healthy,
+    pid: state.pid,
+    url: state.url,
+    port: state.port,
+    ...(state.binaryVersion ? { binaryVersion: state.binaryVersion, binaryFallback: Boolean(state.binaryFallback) } : {}),
+  };
+}
+
+function isLoopbackHostname(hostname) {
+  const name = String(hostname ?? "").replace(/^\[|\]$/g, "").toLowerCase();
+  if (name === "localhost" || name === "::1") return true;
+  const match = name.match(/^127\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  return Boolean(match) && match.slice(1).every(part => Number(part) <= 255);
+}
+
+// loadWorkerEndpoint reads the Worker handshake written by ennoworker and
+// refuses anything that is not a live loopback http Worker: ennote pack inspect
+// talks to the real Worker instead of re-implementing pack parsing in Node.
+function loadWorkerEndpoint(home) {
+  const file = workerStatePath(home);
+  if (!fs.existsSync(file)) {
+    throw new Error(`Ennote Worker is not running (${file} is missing). Start it with: ennote start`);
+  }
+  let state;
+  try {
+    state = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    throw new Error(`Ennote Worker state ${file} is unreadable. Restart it with: ennote restart`);
+  }
+  let parsed;
+  try {
+    parsed = new URL(String(state?.url ?? ""));
+  } catch {
+    throw new Error(`Ennote Worker state ${file} has an invalid url: ${state?.url ?? ""}`);
+  }
+  if (parsed.protocol !== "http:") {
+    throw new Error(`refusing Worker url ${state.url}: expected http:`);
+  }
+  if (!isLoopbackHostname(parsed.hostname)) {
+    throw new Error(`refusing non-loopback Worker url ${state.url}`);
+  }
+  if (!isPidAlive(state.pid)) {
+    throw new Error(`Ennote Worker pid ${state.pid} is not running. Start it with: ennote start`);
+  }
+  if (typeof state.bootstrapToken !== "string" || state.bootstrapToken === "") {
+    throw new Error(`Ennote Worker state ${file} has no bootstrap token. Restart it with: ennote restart`);
+  }
+  return { url: parsed.origin, token: state.bootstrapToken, pid: state.pid, instanceId: state.instanceId };
+}
+
+function postJSON(url, body, headers, timeoutMs) {
+  return httpRequest("POST", url, body, headers, timeoutMs);
+}
+
+// httpRequest is the one place the CLI talks to the Worker. GET/DELETE carry no
+// body; POST serializes it. The Worker url is already pinned to loopback http by
+// loadWorkerEndpoint, so no transport negotiation happens here.
+function httpRequest(method, url, body, headers, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const payload = body === undefined || body === null ? null : Buffer.from(JSON.stringify(body), "utf8");
+    const request = http.request(url, {
+      method,
+      headers: payload
+        ? { "Content-Type": "application/json", "Content-Length": payload.length, ...headers }
+        : headers,
+    }, (response) => {
+      const chunks = [];
+      response.on("data", (chunk) => chunks.push(chunk));
+      response.on("end", () => resolve({
+        statusCode: response.statusCode ?? 0,
+        body: Buffer.concat(chunks).toString("utf8"),
+      }));
+    });
+    request.once("error", reject);
+    request.setTimeout(timeoutMs, () => {
+      request.destroy(new Error(`Worker request timed out after ${timeoutMs / 1000}s`));
+    });
+    request.end(payload ?? undefined);
+  });
+}
+
+// decodeWorkerResponse unwraps the Worker error envelope and the data envelope.
+// A 204 (pack remove) has no data and yields null.
+function decodeWorkerResponse(response, action) {
+  if (response.statusCode < 200 || response.statusCode >= 300) {
+    let message = `Worker returned HTTP ${response.statusCode}`;
+    let code;
+    try {
+      const parsed = JSON.parse(response.body);
+      code = parsed?.error?.code;
+      if (parsed?.error?.message) message = parsed.error.message;
+    } catch {
+      // A non-JSON error body keeps the status-only message.
+    }
+    const error = new Error(code ? `${message} (${code})` : message);
+    error.code = code;
+    error.statusCode = response.statusCode;
+    throw error;
+  }
+  if (response.statusCode === 204 || response.body.trim() === "") return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(response.body);
+  } catch {
+    throw new Error(`Worker returned an unreadable ${action} response`);
+  }
+  if (!parsed || typeof parsed !== "object" || parsed.data == null) {
+    throw new Error(`Worker returned an unexpected ${action} response`);
+  }
+  return parsed.data;
+}
+
+// requestJSON performs one authenticated Worker call. Every pack command except
+// install is GET/DELETE; install reuses postJSON so its body and headers stay in
+// one place.
+async function requestJSON(endpoint, method, pathname, options = {}) {
+  if (method === "POST") {
+    const response = await postJSON(
+      `${endpoint.url}${pathname}`,
+      options.body,
+      { Authorization: `Bearer ${endpoint.token}` },
+      options.timeoutMs ?? PACK_REQUEST_TIMEOUT_MS,
+    );
+    return decodeWorkerResponse(response, options.action ?? "pack");
+  }
+  const response = await httpRequest(
+    method,
+    `${endpoint.url}${pathname}`,
+    undefined,
+    { Authorization: `Bearer ${endpoint.token}` },
+    options.timeoutMs ?? PACK_REQUEST_TIMEOUT_MS,
+  );
+  return decodeWorkerResponse(response, options.action ?? "pack");
+}
+
+async function requestPackInspect(endpoint, target, options = {}) {
+  const body = {
+    source: { kind: "path", path: target },
+    includeDocuments: Boolean(options.documents),
+  };
+  if (options.expectedDigest) body.expectedDigest = options.expectedDigest;
+  const response = await postJSON(
+    `${endpoint.url}/v1/packs/inspect`,
+    body,
+    { Authorization: `Bearer ${endpoint.token}` },
+    options.timeoutMs ?? PACK_INSPECT_TIMEOUT_MS,
+  );
+  return decodeWorkerResponse(response, "inspect");
+}
+
+function formatPackSummary(data) {
+  const pack = data.pack ?? {};
+  const container = data.container ?? {};
+  const signature = data.signature ?? {};
+  const lines = [];
+  lines.push(`${pack.name ?? "(unnamed pack)"} (${pack.id ?? "?"}@${pack.version ?? "?"})`);
+  if (pack.description) lines.push(pack.description);
+  lines.push(`Source:   ${data.source?.path ?? "?"} (${container.kind ?? "?"}, ${container.bytes ?? 0} bytes)`);
+  lines.push(signature.present
+    ? `Signature: ${signature.algorithm} at ${signature.path} — UNVERIFIED (inspect never verifies signatures)`
+    : "Signature: Unsigned");
+  lines.push(`Manifest: ${data.manifestDigest ?? "?"}`);
+  lines.push(`Pack:     ${data.packDigest ?? "?"}`);
+
+  const flows = data.flows ?? [];
+  lines.push(`Flows (${flows.length})`);
+  for (const flow of flows) {
+    lines.push(`  - ${flow.id} [${flow.format}] ${flow.taskCount} task(s), ${flow.checkTasks} check, ${flow.fanOutTasks} fan-out, ${flow.maxTotalTokens} tokens`);
+  }
+  const roles = data.roles ?? [];
+  lines.push(`Roles (${roles.length})`);
+  for (const role of roles) {
+    lines.push(`  - ${role.handle} (${role.scope}) ${role.authority}, tools: ${(role.allowedTools ?? []).join(", ") || "none"}`);
+  }
+  const skills = data.skills ?? [];
+  lines.push(`Skills (${skills.length})`);
+  for (const skill of skills) {
+    lines.push(`  - ${skill.kind === "external" ? skill.ref : skill.id} (${skill.kind})`);
+  }
+  // External MCP profile refs are reported but never resolved: the summary says
+  // so explicitly so a reviewer does not read the line as an installed profile.
+  const mcp = data.mcp ?? [];
+  if (mcp.length > 0) {
+    lines.push(`MCP (${mcp.length})`);
+    for (const profile of mcp) {
+      lines.push(`  - ${profile.ref} (external ref, not resolved or executed)`);
+    }
+  }
+  const envelope = data.capabilityEnvelope ?? {};
+  lines.push(`Checks:   ${(envelope.checkCommands ?? []).join(", ") || "none"}`);
+  lines.push(`Writes:   ${(envelope.writes ?? []).join(", ") || "none"}`);
+  lines.push(`Files:    ${data.filesTotal ?? 0}${data.filesTruncated ? " (truncated)" : ""}`);
+
+  const warnings = data.warnings ?? [];
+  lines.push(`Warnings (${warnings.length})`);
+  for (const warning of warnings) lines.push(`  - ${warning.code} (${warning.severity}): ${warning.message}`);
+  return lines.join("\n");
+}
+
+async function packCommand(home, positionals, values) {
+  const action = positionals[1];
+  const target = positionals[2];
+  if (action === "inspect") {
+    if (!target) {
+      throw usageError("Usage: ennote pack inspect <file|dir> [--json] [--documents]");
+    }
+    const endpoint = loadWorkerEndpoint(home);
+    const data = await requestPackInspect(endpoint, path.resolve(target), {
+      documents: values.documents,
+    });
+    if (values.json) console.log(JSON.stringify(data));
+    else console.log(formatPackSummary(data));
+    return;
+  }
+  if (action === "install") {
+    if (!target) {
+      throw usageError("Usage: ennote pack install <file|dir> [--dry-run] [--json] [--as-flow old=new] [--as-role old=new]");
+    }
+    // Renames are validated before the Worker is contacted, so a typo is a
+    // usage error instead of a refused install.
+    const renames = {
+      flows: parsePackRenames(values["as-flow"], "--as-flow"),
+      roles: parsePackRenames(values["as-role"], "--as-role"),
+    };
+    const endpoint = loadWorkerEndpoint(home);
+    const plan = await requestPackInstall(endpoint, path.resolve(target), {
+      dryRun: Boolean(values["dry-run"]),
+      renames,
+    });
+    if (values.json) console.log(JSON.stringify(plan));
+    else console.log(formatPackInstallPlan(plan, { dryRun: Boolean(values["dry-run"]) }));
+    return;
+  }
+  if (action === "list") {
+    const endpoint = loadWorkerEndpoint(home);
+    const summaries = await requestJSON(endpoint, "GET", "/v1/packs", { action: "pack list" });
+    if (values.json) console.log(JSON.stringify(summaries ?? []));
+    else console.log(formatPackList(summaries ?? []));
+    return;
+  }
+  if (action === "remove") {
+    if (!target) {
+      throw usageError("Usage: ennote pack remove <publisher>/<name> [--force] [--json]");
+    }
+    const packId = parsePackID(target);
+    const endpoint = loadWorkerEndpoint(home);
+    const [publisher, name] = packId.split("/");
+    const query = values.force ? "?force=1" : "";
+    const pathname = `/v1/packs/${encodeURIComponent(publisher)}/${encodeURIComponent(name)}${query}`;
+    // A 204 carries no body; the CLI still reports the same shape as --json so
+    // scripts do not have to special-case the empty response.
+    const data = (await requestJSON(endpoint, "DELETE", pathname, { action: "pack remove" })) ?? {
+      packId,
+      removed: true,
+    };
+    if (values.json) console.log(JSON.stringify(data));
+    else console.log(`Removed ${data.packId ?? packId}${values.force ? " (forced)" : ""}`);
+    return;
+  }
+  throw usageError(
+    `Unknown pack command: ${action ?? ""}\nUsage: ennote pack <inspect|install|list|remove> ...`,
+  );
+}
+
+// parsePackRenames turns repeated --as-flow/--as-role old=new flags into the
+// renames object. A rename only changes the installed store id.
+function parsePackRenames(entries, flag) {
+  const renames = {};
+  for (const entry of entries ?? []) {
+    const text = String(entry);
+    const separator = text.indexOf("=");
+    if (separator <= 0 || separator === text.length - 1) {
+      throw usageError(`${flag} expects old=new, got ${text}`);
+    }
+    const from = text.slice(0, separator).trim();
+    const to = text.slice(separator + 1).trim();
+    if (from === "" || to === "") throw usageError(`${flag} expects old=new, got ${text}`);
+    if (Object.prototype.hasOwnProperty.call(renames, from) && renames[from] !== to) {
+      throw usageError(`${flag} maps ${from} twice (${renames[from]} and ${to})`);
+    }
+    renames[from] = to;
+  }
+  return renames;
+}
+
+// parsePackID validates <publisher>/<name> before it goes on the wire: a bad id
+// is a usage error, not a Worker 400/404.
+function parsePackID(value) {
+  const segments = String(value).split("/");
+  if (segments.length !== 2 || segments.some(segment => segment === "" || segment === "." || segment === "..")) {
+    throw usageError(`pack id must be <publisher>/<name>, got ${value}`);
+  }
+  return segments.join("/");
+}
+
+async function requestPackInstall(endpoint, target, options = {}) {
+  const body = { source: { kind: "path", path: target }, dryRun: Boolean(options.dryRun) };
+  const renames = options.renames ?? {};
+  const encoded = {};
+  if (Object.keys(renames.flows ?? {}).length > 0) encoded.flows = renames.flows;
+  if (Object.keys(renames.roles ?? {}).length > 0) encoded.roles = renames.roles;
+  if (Object.keys(encoded).length > 0) body.renames = encoded;
+  return requestJSON(endpoint, "POST", "/v1/packs/install", { body, action: "pack install" });
+}
+
+function formatPackActionCounts(actions) {
+  const counts = new Map();
+  for (const action of actions) {
+    counts.set(action.action, (counts.get(action.action) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, count]) => `${count} ${name}`)
+    .join(", ");
+}
+
+function formatPackInstallPlan(plan, options = {}) {
+  const pack = plan?.pack ?? {};
+  const lines = [];
+  const headline = plan?.reinstall === "noop"
+    ? "Already installed"
+    : options.dryRun ? "Dry run (nothing written)" : "Installed";
+  lines.push(`${headline}: ${pack.name ?? "(unnamed pack)"} (${pack.id ?? "?"}@${pack.version ?? "?"})`);
+  lines.push(`Manifest: ${plan?.manifestDigest ?? "?"}`);
+  lines.push(`Pack:     ${plan?.packDigest ?? "?"}`);
+
+  const actions = plan?.actions ?? [];
+  lines.push(`Actions (${actions.length}): ${formatPackActionCounts(actions) || "none"}`);
+  for (const action of actions) {
+    const scope = action.scope ? ` (${action.scope})` : "";
+    lines.push(`  - ${action.action} ${action.kind} ${action.storeId}${scope}`);
+  }
+
+  const state = plan?.state;
+  if (state) {
+    lines.push(`State:    ${state.installState ?? "?"}; flows ${state.flows?.length ?? 0}, roles ${state.roles?.length ?? 0}, skills ${state.skills?.length ?? 0}`);
+    const drafts = (state.flows ?? []).filter(flow => !flow.publishedRevision);
+    if (drafts.length > 0) {
+      lines.push(`Disabled: ${drafts.map(flow => flow.storeId).join(", ")} (draft Graph, no published revision — publish it to enable runs)`);
+    }
+    if (state.source?.path) lines.push(`Source:   ${state.source.path}`);
+    const external = state.externalRefs ?? {};
+    const externalSkills = external.skills ?? [];
+    const externalMcp = external.mcp ?? [];
+    if (externalSkills.length > 0 || externalMcp.length > 0) {
+      lines.push(`Recorded (not installed): skills ${externalSkills.join(", ") || "none"}; mcp ${externalMcp.join(", ") || "none"}`);
+    }
+  } else if (options.dryRun) {
+    lines.push("State:    not written (dry run)");
+  }
+
+  const blockers = plan?.blockers ?? [];
+  lines.push(`Blockers (${blockers.length})`);
+  for (const blocker of blockers) {
+    lines.push(`  - ${blocker.code} (${blocker.severity ?? "error"}): ${blocker.message}`);
+  }
+  const warnings = plan?.warnings ?? [];
+  lines.push(`Warnings (${warnings.length})`);
+  for (const warning of warnings) {
+    lines.push(`  - ${warning.code} (${warning.severity ?? "warning"}): ${warning.message}`);
+  }
+  return lines.join("\n");
+}
+
+function formatPackList(summaries) {
+  if (summaries.length === 0) return "No Agent Packs installed.";
+  const lines = [`Installed Agent Packs (${summaries.length})`];
+  for (const summary of summaries) {
+    const pack = summary.pack ?? {};
+    lines.push(`  - ${pack.name ?? "(unnamed pack)"} (${pack.id ?? "?"}@${pack.version ?? "?"}) ${summary.installState ?? "?"}`);
+    lines.push(`    flows ${summary.flowCount ?? 0}, roles ${summary.roleCount ?? 0}, skills ${summary.skillCount ?? 0}; installed ${summary.installedAt ?? "?"}`);
+  }
+  return lines.join("\n");
 }
 
 async function setPassword(home, reset) {
@@ -397,11 +874,20 @@ Commands:
   logs            Show recent service logs
   passwd          Set the local password
   passwd --reset  Remove the local password and require setup
+  pack inspect    Inspect an Agent Pack (.enpack or directory) without installing
+  pack install    Install an Agent Pack from a .enpack file or directory
+  pack list       List installed Agent Packs
+  pack remove     Uninstall an Agent Pack (<publisher>/<name>)
 
 Options:
   --port, -p      Browser-facing port (default ${DEFAULT_PORT})
   --hostname, -H  Bind address (default ${DEFAULT_HOSTNAME})
-  --json          Machine-readable output
+  --json          Machine-readable output (prints the Worker data payload)
+  --documents     pack inspect: include flow, role, and skill source text
+  --dry-run       pack install: plan only and write nothing
+  --as-flow       pack install: old=new rename of an installed Graph id
+  --as-role       pack install: old=new rename of an installed Role handle
+  --force         pack remove: override local edits and shared global Roles
   --version, -v   Show version
   --help, -h      Show this help`);
 }
@@ -415,6 +901,11 @@ async function main(argv = process.argv.slice(2)) {
       port: { type: "string", short: "p", default: DEFAULT_PORT },
       hostname: { type: "string", short: "H", default: DEFAULT_HOSTNAME },
       json: { type: "boolean", default: false },
+      documents: { type: "boolean", default: false },
+      "dry-run": { type: "boolean", default: false },
+      "as-flow": { type: "string", multiple: true },
+      "as-role": { type: "string", multiple: true },
+      force: { type: "boolean", default: false },
       reset: { type: "boolean", default: false },
       version: { type: "boolean", short: "v", default: false },
       help: { type: "boolean", short: "h", default: false },
@@ -451,6 +942,11 @@ async function main(argv = process.argv.slice(2)) {
     case "passwd":
       result = await setPassword(home, values.reset);
       break;
+    case "pack":
+      // Every pack command talks to the running Worker instead of re-implementing
+      // manifest parsing, installation, or store writes in Node.
+      await packCommand(home, positionals, values);
+      return;
     default:
       throw new Error(`Unknown command: ${command}`);
   }
@@ -466,6 +962,7 @@ module.exports = {
   runtimeBinDir,
   runtimePaths,
   statePaths,
+  workerStatePath,
   serviceURL,
   validateRuntime,
   healthCheck,
@@ -473,17 +970,31 @@ module.exports = {
   parseSHA256SUMS,
   fileSHA256,
   verifyFileSHA256,
+  compareVersions,
+  cachedBinaryVersions,
+  releasesBase,
   ensureBinaries,
   startService,
   stopService,
   serviceStatus,
   setPassword,
+  isLoopbackHostname,
+  loadWorkerEndpoint,
+  requestPackInspect,
+  formatPackSummary,
+  requestJSON,
+  requestPackInstall,
+  parsePackRenames,
+  parsePackID,
+  formatPackInstallPlan,
+  formatPackList,
+  packCommand,
   main,
 };
 
 if (require.main === module) {
   main().catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 1;
+    process.exitCode = Number.isInteger(error?.exitCode) ? error.exitCode : 1;
   });
 }