@aerovato/operator-helper 1.2.1 → 1.3.1

package/dist/index.js

@@ -17998,7 +17998,7 @@ var Uint8Array2 = /* @__PURE__ */ instanceOf(globalThis.Uint8Array, {
 // package.json
 var package_default = {
   name: "@aerovato/operator-helper",
-  version: "1.2.1",
+  version: "1.3.1",
   description: "Installation and setup CLI for Operator Memory",
   license: "BSD-3-Clause",
   author: "Aerovato Research",
@@ -18025,7 +18025,8 @@ var package_default = {
     node: ">=20"
   },
   files: [
-    "dist"
+    "dist",
+    "!dist/*.map"
   ],
   keywords: [
     "opencode",
@@ -19041,16 +19042,82 @@ var inspectMainIndex = fn2("inspectMainIndex")(function* (cwd, partitionRoot) {
 
 // src/commands/install/code-puppy.ts
 import { randomUUID } from "node:crypto";
-import { lstat, mkdir as mkdir2, readFile as readFile3, rename as rename3, rm as rm2, writeFile as writeFile3 } from "node:fs/promises";
+import { mkdir as mkdir2, readFile as readFile4, rename as rename3, rm as rm2, writeFile as writeFile3 } from "node:fs/promises";
 import { join as join2 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// src/commands/common.ts
+import { lstat, readFile as readFile3 } from "node:fs/promises";
+function fileFailure(error) {
+  return { exitCode: 1, output: fileErrorMessage(error) };
+}
+function fileErrorMessage(error) {
+  if (error instanceof PathKindError) {
+    return `✗ ${error.path}: Expected a ${error.expected}, found ${error.actual}`;
+  }
+  const path = error.reason instanceof SystemError ? `${error.reason.pathOrDescriptor}: ` : "";
+  return `✗ ${path}${error.reason.description ?? error.message}`;
+}
+function runProcess(executable, arguments_, cwd, environment) {
+  return gen2(function* () {
+    const spawner = yield* ChildProcessSpawner;
+    const command = make11(executable, [...arguments_], {
+      cwd,
+      env: environment ?? undefined,
+      extendEnv: true
+    });
+    const execution = yield* scoped2(gen2(function* () {
+      const handle = yield* spawner.spawn(command);
+      const [stdout, stderr, exitCode] = yield* all2([
+        handle.stdout.pipe(decodeText(), mkString),
+        handle.stderr.pipe(decodeText(), mkString),
+        handle.exitCode
+      ], { concurrency: "unbounded" });
+      return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode: Number(exitCode) };
+    })).pipe(result2);
+    if (isFailure2(execution)) {
+      const error = execution.failure instanceof PlatformError ? execution.failure.reason.description ?? execution.failure.message : getErrorMessage(execution.failure);
+      return { ok: false, error };
+    }
+    return {
+      ok: true,
+      ...execution.success,
+      output: [execution.success.stdout, execution.success.stderr].filter(Boolean).join(`
+`)
+    };
+  });
+}
+async function pathKind(path) {
+  try {
+    const info = await lstat(path);
+    return info.isFile() ? "file" : info.isDirectory() ? "directory" : "other";
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT")
+      return "missing";
+    throw error;
+  }
+}
+async function readOptionalFile(path) {
+  try {
+    return await readFile3(path, "utf8");
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT")
+      return null;
+    throw error;
+  }
+}
+function isNodeError(error) {
+  return error instanceof Error && "code" in error;
+}
+
+// src/commands/install/code-puppy.ts
 var CODE_PUPPY_MARKER = `Operator Memory managed Code Puppy plugin.
 `;
 var CODE_PUPPY_MARKER_FILE = ".operator-managed";
 var installCodePuppy = fn2("installCodePuppy")(function* (context) {
   return yield* promise2(async () => {
     try {
-      const source = await readFile3(await codePuppyAdapterPath(), "utf8");
+      const source = await readFile4(await codePuppyAdapterPath(), "utf8");
       const plugins = join2(context.home, ".code_puppy", "plugins");
       const target = join2(plugins, "operator");
       const marker = join2(target, CODE_PUPPY_MARKER_FILE);
@@ -19069,13 +19136,13 @@ var installCodePuppy = fn2("installCodePuppy")(function* (context) {
         }
         return { exitCode: 0, output: "✓ Code Puppy plugin installed" };
       }
-      if (targetKind !== "directory" || await pathKind(marker) !== "file" || await readOptional(marker) !== CODE_PUPPY_MARKER) {
+      if (targetKind !== "directory" || await pathKind(marker) !== "file" || await readOptionalFile(marker) !== CODE_PUPPY_MARKER) {
         return {
           exitCode: 1,
           output: `✗ Preserved unmanaged Code Puppy plugin at ${target}`
         };
       }
-      if (await readOptional(callbacks) === source) {
+      if (await readOptionalFile(callbacks) === source) {
         return { exitCode: 0, output: "✓ Code Puppy plugin is current" };
       }
       const staged = `${callbacks}.tmp-${randomUUID()}`;
@@ -19107,36 +19174,116 @@ async function codePuppyAdapterPath() {
   }
   throw new Error("bundled Code Puppy adapter is missing");
 }
-async function pathKind(path) {
-  try {
-    const info = await lstat(path);
-    return info.isFile() ? "file" : info.isDirectory() ? "directory" : "other";
-  } catch (error) {
-    if (isNodeError(error) && error.code === "ENOENT") {
-      return "missing";
+
+// src/commands/install/codex.ts
+import { mkdir as mkdir3, writeFile as writeFile4 } from "node:fs/promises";
+import { join as join3 } from "node:path";
+var MARKETPLACE_MARKER = `Operator Memory managed Codex marketplace.
+`;
+var MARKETPLACE_NAME = "operator-memory";
+var PLUGIN_NAME = "aerovato";
+var PLUGIN_ID = `${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
+var MARKETPLACE = `${JSON.stringify({
+  name: MARKETPLACE_NAME,
+  plugins: [
+    {
+      name: PLUGIN_NAME,
+      source: {
+        source: "npm",
+        package: "@aerovato/operator-codex",
+        version: "latest"
+      },
+      policy: { installation: "AVAILABLE" }
     }
-    throw error;
+  ]
+}, null, 2)}
+`;
+var installCodex = fn2("installCodex")(function* (context) {
+  const marketplace = yield* writeMarketplace(context.home);
+  if (!marketplace.ok)
+    return marketplace.result;
+  const addMarketplace = yield* runProcess("codex", ["plugin", "marketplace", "add", marketplace.path, "--json"], context.cwd, { NPM_CONFIG_MIN_RELEASE_AGE: "0" });
+  const addFailure = commandFailure(addMarketplace, "Codex marketplace installation failed");
+  if (addFailure !== null)
+    return addFailure;
+  const install = yield* runProcess("codex", ["plugin", "add", PLUGIN_ID, "--json"], context.cwd, {
+    NPM_CONFIG_MIN_RELEASE_AGE: "0"
+  });
+  const installFailure = commandFailure(install, "Codex plugin installation failed");
+  if (installFailure !== null)
+    return installFailure;
+  const status = yield* runProcess("codex", ["plugin", "list", "--marketplace", MARKETPLACE_NAME, "--json"], context.cwd, { NPM_CONFIG_MIN_RELEASE_AGE: "0" });
+  const statusFailure = commandFailure(status, "Could not verify Codex plugin installation");
+  if (statusFailure !== null)
+    return statusFailure;
+  if (!(status.ok && isInstalledAndEnabled(status.stdout))) {
+    return {
+      exitCode: 1,
+      output: "✗ Codex plugin installation finished but the plugin is not installed and enabled"
+    };
   }
+  return {
+    exitCode: 0,
+    output: [
+      "✓ Codex plugin installed and enabled",
+      "Start a new Codex session and approve the Operator hooks if prompted."
+    ].join(`
+`)
+  };
+});
+function writeMarketplace(home) {
+  return promise2(async () => {
+    const root = join3(home, ".operator-helper", "codex-marketplace");
+    const marker = join3(root, ".operator-managed");
+    const marketplace = join3(root, ".agents", "plugins", "marketplace.json");
+    try {
+      const kind = await pathKind(root);
+      if (kind !== "missing" && (kind !== "directory" || await readOptionalFile(marker) !== MARKETPLACE_MARKER)) {
+        return {
+          ok: false,
+          result: {
+            exitCode: 1,
+            output: `✗ Preserved unmanaged Codex marketplace at ${root}`
+          }
+        };
+      }
+      await mkdir3(join3(root, ".agents", "plugins"), { recursive: true });
+      await writeFile4(marker, MARKETPLACE_MARKER);
+      await writeFile4(marketplace, MARKETPLACE);
+      return { ok: true, path: root };
+    } catch (error) {
+      return {
+        ok: false,
+        result: {
+          exitCode: 1,
+          output: `✗ Could not prepare Codex marketplace: ${getErrorMessage(error)}`
+        }
+      };
+    }
+  });
 }
-async function readOptional(path) {
+function isInstalledAndEnabled(output) {
   try {
-    return await readFile3(path, "utf8");
-  } catch (error) {
-    if (isNodeError(error) && error.code === "ENOENT") {
-      return null;
-    }
-    throw error;
+    const value = JSON.parse(output);
+    if (typeof value !== "object" || value === null || !("installed" in value))
+      return false;
+    const installed = value.installed;
+    return Array.isArray(installed) && installed.some((plugin) => typeof plugin === "object" && plugin !== null && ("pluginId" in plugin) && plugin.pluginId === PLUGIN_ID && ("installed" in plugin) && plugin.installed === true && ("enabled" in plugin) && plugin.enabled === true);
+  } catch {
+    return false;
   }
 }
-function isNodeError(error) {
-  return error instanceof Error && "code" in error;
+function commandFailure(result, fallback) {
+  if (!result.ok)
+    return { exitCode: 1, output: `✗ Could not run codex: ${result.error}` };
+  return result.exitCode === 0 ? null : { exitCode: result.exitCode, output: result.output || fallback };
 }
+
 // src/commands/install/opencode.ts
 var OPENCODE_PLUGIN = "@aerovato/operator-opencode@latest";
 var installOpenCode = fn2("installOpenCode")(function* (context) {
   const fileSystem = yield* FileSystem;
   const path = yield* Path;
-  const spawner = yield* ChildProcessSpawner;
   const cacheRoot = process.env.XDG_CACHE_HOME || path.join(context.home, ".cache");
   const isCacheRemoved = yield* fileSystem.remove(path.join(cacheRoot, "opencode", "packages", "@aerovato", "operator-opencode@latest"), {
     recursive: true,
@@ -19148,85 +19295,39 @@ var installOpenCode = fn2("installOpenCode")(function* (context) {
       output: `✗ Could not clear the OpenCode plugin cache`
     };
   }
-  const command = make11("opencode", ["plugin", OPENCODE_PLUGIN, "--global", "--force"], {
-    cwd: context.cwd,
-    env: { NPM_CONFIG_MIN_RELEASE_AGE: "0" },
-    extendEnv: true
-  });
-  const execution = yield* scoped2(gen2(function* () {
-    const handle = yield* spawner.spawn(command);
-    const [stdout, stderr, exitCode] = yield* all2([
-      handle.stdout.pipe(decodeText(), mkString),
-      handle.stderr.pipe(decodeText(), mkString),
-      handle.exitCode
-    ], { concurrency: "unbounded" });
-    return { stdout, stderr, exitCode: Number(exitCode) };
-  })).pipe(result2);
-  if (isFailure2(execution)) {
-    const message = execution.failure instanceof PlatformError ? execution.failure.reason.description ?? execution.failure.message : getErrorMessage(execution.failure);
-    return { exitCode: 1, output: `✗ Could not run opencode: ${message}` };
+  const execution = yield* runProcess("opencode", ["plugin", OPENCODE_PLUGIN, "--global", "--force"], context.cwd, { NPM_CONFIG_MIN_RELEASE_AGE: "0" });
+  if (!execution.ok) {
+    return { exitCode: 1, output: `✗ Could not run opencode: ${execution.error}` };
   }
-  const output = [execution.success.stdout.trim(), execution.success.stderr.trim()].filter(Boolean).join(`
-`);
-  return execution.success.exitCode === 0 ? { exitCode: 0, output } : {
-    exitCode: execution.success.exitCode,
-    output: output || "OpenCode plugin installation failed"
+  return execution.exitCode === 0 ? { exitCode: 0, output: execution.output } : {
+    exitCode: execution.exitCode,
+    output: execution.output || "OpenCode plugin installation failed"
   };
 });
 
 // src/commands/install/opencode-v2.ts
 var OPENCODE_V2_PLUGIN = "@aerovato/operator-opencode-v2@latest";
 var installOpenCodeV2 = fn2("installOpenCodeV2")(function* (context) {
-  const spawner = yield* ChildProcessSpawner;
-  const command = make11("opencode", ["plugin", "add", OPENCODE_V2_PLUGIN], {
-    cwd: context.cwd,
-    env: { NPM_CONFIG_MIN_RELEASE_AGE: "0" },
-    extendEnv: true
-  });
-  const execution = yield* scoped2(gen2(function* () {
-    const handle = yield* spawner.spawn(command);
-    const [stdout, stderr, exitCode] = yield* all2([
-      handle.stdout.pipe(decodeText(), mkString),
-      handle.stderr.pipe(decodeText(), mkString),
-      handle.exitCode
-    ], { concurrency: "unbounded" });
-    return { stdout, stderr, exitCode: Number(exitCode) };
-  })).pipe(result2);
-  if (isFailure2(execution)) {
-    const message = execution.failure instanceof PlatformError ? execution.failure.reason.description ?? execution.failure.message : getErrorMessage(execution.failure);
-    return { exitCode: 1, output: `✗ Could not run opencode: ${message}` };
+  const execution = yield* runProcess("opencode", ["plugin", "add", OPENCODE_V2_PLUGIN], context.cwd, { NPM_CONFIG_MIN_RELEASE_AGE: "0" });
+  if (!execution.ok) {
+    return { exitCode: 1, output: `✗ Could not run opencode: ${execution.error}` };
   }
-  const output = [execution.success.stdout.trim(), execution.success.stderr.trim()].filter(Boolean).join(`
-`);
-  return execution.success.exitCode === 0 ? { exitCode: 0, output } : {
-    exitCode: execution.success.exitCode,
-    output: output || "OpenCode V2 plugin installation failed"
+  return execution.exitCode === 0 ? { exitCode: 0, output: execution.output } : {
+    exitCode: execution.exitCode,
+    output: execution.output || "OpenCode V2 plugin installation failed"
   };
 });
 
 // src/commands/install/pi.ts
 var PI_PLUGIN = "npm:@aerovato/operator-pi";
 var installPi = fn2("installPi")(function* (context) {
-  const spawner = yield* ChildProcessSpawner;
-  const command = make11("pi", ["install", PI_PLUGIN], { cwd: context.cwd });
-  const execution = yield* scoped2(gen2(function* () {
-    const handle = yield* spawner.spawn(command);
-    const [stdout, stderr, exitCode] = yield* all2([
-      handle.stdout.pipe(decodeText(), mkString),
-      handle.stderr.pipe(decodeText(), mkString),
-      handle.exitCode
-    ], { concurrency: "unbounded" });
-    return { stdout, stderr, exitCode: Number(exitCode) };
-  })).pipe(result2);
-  if (isFailure2(execution)) {
-    const message = execution.failure instanceof PlatformError ? execution.failure.reason.description ?? execution.failure.message : getErrorMessage(execution.failure);
-    return { exitCode: 1, output: `✗ Could not run pi: ${message}` };
+  const execution = yield* runProcess("pi", ["install", PI_PLUGIN], context.cwd, null);
+  if (!execution.ok) {
+    return { exitCode: 1, output: `✗ Could not run pi: ${execution.error}` };
   }
-  const output = [execution.success.stdout.trim(), execution.success.stderr.trim()].filter(Boolean).join(`
-`);
-  return execution.success.exitCode === 0 ? { exitCode: 0, output } : {
-    exitCode: execution.success.exitCode,
-    output: output || "Pi plugin installation failed"
+  return execution.exitCode === 0 ? { exitCode: 0, output: execution.output } : {
+    exitCode: execution.exitCode,
+    output: execution.output || "Pi plugin installation failed"
   };
 });
 
@@ -19234,7 +19335,7 @@ var installPi = fn2("installPi")(function* (context) {
 import { resolve as resolve3 } from "node:path";
 
 // ../core/src/memory/project.ts
-import { extname, join as join3, relative, sep } from "node:path";
+import { extname, join as join4, relative, sep } from "node:path";
 
 // ../core/src/utils.ts
 function success(value) {
@@ -19259,17 +19360,17 @@ function readString(value, key) {
 
 // ../core/src/memory/common.ts
 import { constants as constants2 } from "node:fs";
-import { access as access3, readdir, readFile as readFile4, stat as stat3 } from "node:fs/promises";
+import { access as access3, readdir, readFile as readFile5, stat as stat3 } from "node:fs/promises";
 async function readOptionalContent(path) {
   try {
-    return success(await readFile4(path, "utf8"));
+    return success(await readFile5(path, "utf8"));
   } catch (cause) {
     return hasNodeErrorCode(cause, "ENOENT") ? success(null) : failure({ path, cause });
   }
 }
 async function readContent(path) {
   try {
-    return success(await readFile4(path, "utf8"));
+    return success(await readFile5(path, "utf8"));
   } catch (cause) {
     return failure({ path, cause });
   }
@@ -19348,13 +19449,13 @@ async function loadProjectPartition(root, loadFiles) {
     return hasNodeErrorCode(directory.error.cause, "ENOENT") ? success(loadFiles ? { exists: false, operatorInstructions: null, catalog: null, indexes: [] } : { exists: false }) : directory;
   }
   if (!loadFiles) {
-    for (const path of [join3(root, "operator.md"), join3(root, "catalog.md")]) {
+    for (const path of [join4(root, "operator.md"), join4(root, "catalog.md")]) {
       const file = await checkOptionalReadableFile(path);
       if (!file.ok) {
         return file;
       }
     }
-    const indexRoot = join3(root, "index");
+    const indexRoot = join4(root, "index");
     const indexPaths = await listMarkdownFiles(indexRoot, indexRoot);
     if (!indexPaths.ok) {
       return indexPaths;
@@ -19367,15 +19468,15 @@ async function loadProjectPartition(root, loadFiles) {
     }
     return success({ exists: true });
   }
-  const operatorInstructions = await readOptionalContent(join3(root, "operator.md"));
+  const operatorInstructions = await readOptionalContent(join4(root, "operator.md"));
   if (!operatorInstructions.ok) {
     return operatorInstructions;
   }
-  const catalog = await readOptionalContent(join3(root, "catalog.md"));
+  const catalog = await readOptionalContent(join4(root, "catalog.md"));
   if (!catalog.ok) {
     return catalog;
   }
-  const indexes = await readIndexes(join3(root, "index"));
+  const indexes = await readIndexes(join4(root, "index"));
   if (!indexes.ok) {
     return indexes;
   }
@@ -19413,7 +19514,7 @@ async function listMarkdownFiles(root, directory) {
   }
   const paths = [];
   for (const entry of entries.value) {
-    const path = join3(directory, entry.name);
+    const path = join4(directory, entry.name);
     if (entry.isDirectory()) {
       const nestedPaths = await listMarkdownFiles(root, path);
       if (!nestedPaths.ok) {
@@ -19434,14 +19535,14 @@ function compareStrings2(left, right) {
 }
 
 // ../core/src/memory/user.ts
-import { join as join4 } from "node:path";
+import { join as join5 } from "node:path";
 async function loadUserPartition(root, loadFiles) {
   if (!loadFiles) {
     const directory = await readDirectory2(root);
     if (!directory.ok) {
       return hasNodeErrorCode(directory.error.cause, "ENOENT") ? success({ exists: false }) : directory;
     }
-    for (const path of [join4(root, "operator.md"), join4(root, "catalog.md")]) {
+    for (const path of [join5(root, "operator.md"), join5(root, "catalog.md")]) {
       const file = await checkOptionalReadableFile(path);
       if (!file.ok) {
         return file;
@@ -19449,11 +19550,11 @@ async function loadUserPartition(root, loadFiles) {
     }
     return success({ exists: true });
   }
-  const operatorInstructions = await readOptionalContent(join4(root, "operator.md"));
+  const operatorInstructions = await readOptionalContent(join5(root, "operator.md"));
   if (!operatorInstructions.ok) {
     return operatorInstructions;
   }
-  const catalog = await readOptionalContent(join4(root, "catalog.md"));
+  const catalog = await readOptionalContent(join5(root, "catalog.md"));
   if (!catalog.ok) {
     return catalog;
   }
@@ -19979,18 +20080,6 @@ var hasTrackedPrivateFiles = fn2("hasTrackedPrivateFiles")(function* (cwd) {
   return tracked.trim() !== "";
 });
 
-// src/commands/common.ts
-function fileFailure(error) {
-  return { exitCode: 1, output: fileErrorMessage(error) };
-}
-function fileErrorMessage(error) {
-  if (error instanceof PathKindError) {
-    return `✗ ${error.path}: Expected a ${error.expected}, found ${error.actual}`;
-  }
-  const path = error.reason instanceof SystemError ? `${error.reason.pathOrDescriptor}: ` : "";
-  return `✗ ${path}${error.reason.description ?? error.message}`;
-}
-
 // src/commands/project/common.ts
 var PRIVATE_ROOT2 = ".operator";
 var SHARED_ROOT2 = ".operator-shared";
@@ -20240,92 +20329,10 @@ var userStatus = fn2("userStatus")(function* (context) {
 `) };
 });
 
-// src/cli.ts
-var HELP = `Operator Helper
-
-USER COMMANDS
-
-${renderTable([
-  ["help", "Show help for operator-helper"],
-  ["version", "Show the installed version"],
-  ["operator-helper install opencode", "Install or update the OpenCode plugin"],
-  ["operator-helper install opencode-v2", "Install or update the OpenCode V2 plugin"],
-  ["operator-helper install pi", "Install or update the Pi plugin"],
-  ["operator-helper install code-puppy", "Install or update the Code Puppy plugin"]
-])}
-
-AGENT COMMANDS
-
-${renderTable([
-  ["operator-helper user status", "Show User Partition status"],
-  ["operator-helper user init", "Initialize User Partition core files without overwriting content"],
-  ["operator-helper user guide", "Print the agent guide for completing User Setup"],
-  [
-    "operator-helper project status",
-    "Show Project Private, Shared, Git ignore, and tracking status"
-  ],
-  ["operator-helper project init", "Initialize project partitions and global Git ignore"],
-  ["operator-helper project guide", "Print the agent guide for completing Project Setup"],
-  ["operator-helper index status", "Show Private and Shared main Project Index status"],
-  ["operator-helper index guide", "Print the agent guide for building or refreshing indexes"],
-  ["operator-helper index lint", "Check Project Index structure and frontmatter"],
-  ["operator-helper memory check", "Check that all Operator memory can be loaded"],
-  ["operator-helper preamble", "Render the Operator preamble"]
-])}`;
-function runCli(arguments_, context) {
-  return gen2(function* () {
-    if (arguments_.length === 1 && arguments_[0] === "help") {
-      return { exitCode: 0, output: HELP };
-    }
-    if (arguments_.length === 1 && arguments_[0] === "version") {
-      return { exitCode: 0, output: context.version };
-    }
-    if (arguments_.length === 1 && arguments_[0] === "preamble") {
-      return yield* preamble(context);
-    }
-    if (arguments_.length !== 2) {
-      return { exitCode: 2, output: HELP };
-    }
-    const command = `${arguments_[0]} ${arguments_[1]}`;
-    switch (command) {
-      case "user status":
-        return yield* userStatus(context);
-      case "user init":
-        return yield* userInit(context);
-      case "user guide":
-        return yield* userGuide();
-      case "project status":
-        return yield* projectStatus(context);
-      case "project init":
-        return yield* projectInit(context);
-      case "project guide":
-        return yield* projectGuide();
-      case "index status":
-        return yield* indexStatus(context);
-      case "index guide":
-        return yield* indexGuide();
-      case "index lint":
-        return yield* indexLint(context);
-      case "memory check":
-        return yield* memoryCheck(context);
-      case "install opencode":
-        return yield* installOpenCode(context);
-      case "install opencode-v2":
-        return yield* installOpenCodeV2(context);
-      case "install pi":
-        return yield* installPi(context);
-      case "install code-puppy":
-        return yield* installCodePuppy(context);
-      default:
-        return {
-          exitCode: 2,
-          output: `Unknown command: ${command}
-
-${HELP}`
-        };
-    }
-  }).pipe(catch_2((error) => succeed6(fileFailure(error))));
-}
+// src/update.ts
+import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile5 } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import { dirname as dirname2, join as join6, sep as sep2 } from "node:path";
 
 // src/npm-registry.ts
 class NpmRegistryError extends TaggedError2("NpmRegistryError") {
@@ -20363,9 +20370,6 @@ var NpmRegistry;
 })(NpmRegistry ||= {});
 
 // src/update.ts
-import { mkdir as mkdir3, readFile as readFile5, writeFile as writeFile4 } from "node:fs/promises";
-import { realpathSync } from "node:fs";
-import { dirname as dirname2, join as join5, sep as sep2 } from "node:path";
 var HELPER_PACKAGE = "@aerovato/operator-helper";
 var UPDATE_TIMEOUT = "60 seconds";
 var SUCCESS_COOLDOWN = 60 * 60 * 1000;
@@ -20381,11 +20385,11 @@ var UpdateCheck = Union2([
 ]);
 var decodeUpdateCheck = decodeUnknownSync(fromJsonString2(UpdateCheck));
 function updateCheckPath(context) {
-  const cache = process.env.XDG_CACHE_HOME || join5(context.home, ".cache");
-  return join5(cache, "operator", "helper-update.json");
+  const cache = process.env.XDG_CACHE_HOME || join6(context.home, ".cache");
+  return join6(cache, "operator", "helper-update.json");
 }
-var autoUpdate = fn2("autoUpdate")(function* (currentVersion, context) {
-  const cached = yield* promise2(() => readUpdateCheck(context));
+var autoUpdate = fn2("autoUpdate")(function* (currentVersion, context, bypassCache) {
+  const cached = bypassCache ? null : yield* promise2(() => readUpdateCheck(context));
   if (cached !== null && isFresh(cached)) {
     if (cached.status === "unknown") {
       return { status: "unknown", latest: cached.latest };
@@ -20420,7 +20424,7 @@ var autoUpdate = fn2("autoUpdate")(function* (currentVersion, context) {
   const execution = yield* run3(spawner, command).pipe(timeout2(UPDATE_TIMEOUT), option2);
   if (isSome2(execution) && execution.value.exitCode === 0) {
     yield* promise2(() => writeUpdateCheck(context, { checkedAt: Date.now(), status: "current" }));
-    return { status: "updated" };
+    return { status: "updated", latest: latest.value };
   }
   yield* promise2(() => writeUpdateCheck(context, { checkedAt: Date.now(), status: "failed" }));
   return { status: "failed" };
@@ -20432,7 +20436,7 @@ function isFresh(check) {
 }
 async function readUpdateCheck(context) {
   try {
-    return decodeUpdateCheck(await readFile5(updateCheckPath(context), "utf8"));
+    return decodeUpdateCheck(await readFile6(updateCheckPath(context), "utf8"));
   } catch {
     return null;
   }
@@ -20440,8 +20444,8 @@ async function readUpdateCheck(context) {
 async function writeUpdateCheck(context, check) {
   const path = updateCheckPath(context);
   try {
-    await mkdir3(dirname2(path), { recursive: true, mode: 448 });
-    await writeFile4(path, JSON.stringify(check), { mode: 384 });
+    await mkdir4(dirname2(path), { recursive: true, mode: 448 });
+    await writeFile5(path, JSON.stringify(check), { mode: 384 });
   } catch {}
 }
 function detectInstallationChannel(spawner, cwd, executablePath) {
@@ -20504,6 +20508,118 @@ function parseVersion(value) {
   return [Number(match[1]), Number(match[2]), Number(match[3])];
 }
 
+// src/commands/upgrade.ts
+var upgrade = fn2("upgrade")(function* (context) {
+  const result = yield* autoUpdate(context.version, context, true);
+  switch (result.status) {
+    case "current":
+      return { exitCode: 0, output: `Operator Helper ${context.version} is up to date.` };
+    case "updated":
+      return { exitCode: 0, output: `Operator Helper updated to ${result.latest}.` };
+    case "unknown":
+      return {
+        exitCode: 1,
+        output: `Operator Helper ${result.latest} is available, but the update could not determine whether Bun or npm owns this installation. Update operator-helper manually using the original installation method.`
+      };
+    case "failed":
+      return { exitCode: 1, output: "Operator Helper update failed." };
+  }
+});
+
+// src/cli.ts
+var HELP = `Operator Helper
+
+USER COMMANDS
+
+${renderTable([
+  ["help", "Show help for operator-helper"],
+  ["version", "Show the installed version"],
+  ["upgrade", "Update Operator Helper to the latest release"],
+  ["operator-helper install codex", "Install or update the Codex plugin"],
+  ["operator-helper install opencode", "Install or update the OpenCode plugin"],
+  ["operator-helper install opencode-v2", "Install or update the OpenCode V2 plugin"],
+  ["operator-helper install pi", "Install or update the Pi plugin"],
+  ["operator-helper install code-puppy", "Install or update the Code Puppy plugin"]
+])}
+
+AGENT COMMANDS
+
+${renderTable([
+  ["operator-helper user status", "Show User Partition status"],
+  ["operator-helper user init", "Initialize User Partition core files without overwriting content"],
+  ["operator-helper user guide", "Print the agent guide for completing User Setup"],
+  [
+    "operator-helper project status",
+    "Show Project Private, Shared, Git ignore, and tracking status"
+  ],
+  ["operator-helper project init", "Initialize project partitions and global Git ignore"],
+  ["operator-helper project guide", "Print the agent guide for completing Project Setup"],
+  ["operator-helper index status", "Show Private and Shared main Project Index status"],
+  ["operator-helper index guide", "Print the agent guide for building or refreshing indexes"],
+  ["operator-helper index lint", "Check Project Index structure and frontmatter"],
+  ["operator-helper memory check", "Check that all Operator memory can be loaded"],
+  ["operator-helper preamble", "Render the Operator preamble"]
+])}`;
+function runCli(arguments_, context) {
+  return gen2(function* () {
+    if (arguments_.length === 1 && arguments_[0] === "help") {
+      return { exitCode: 0, output: HELP };
+    }
+    if (arguments_.length === 1 && arguments_[0] === "version") {
+      return { exitCode: 0, output: context.version };
+    }
+    if (arguments_.length === 1 && arguments_[0] === "preamble") {
+      return yield* preamble(context);
+    }
+    if (arguments_.length === 1 && arguments_[0] === "upgrade") {
+      return yield* upgrade(context);
+    }
+    if (arguments_.length !== 2) {
+      return { exitCode: 2, output: HELP };
+    }
+    const command = `${arguments_[0]} ${arguments_[1]}`;
+    switch (command) {
+      case "user status":
+        return yield* userStatus(context);
+      case "user init":
+        return yield* userInit(context);
+      case "user guide":
+        return yield* userGuide();
+      case "project status":
+        return yield* projectStatus(context);
+      case "project init":
+        return yield* projectInit(context);
+      case "project guide":
+        return yield* projectGuide();
+      case "index status":
+        return yield* indexStatus(context);
+      case "index guide":
+        return yield* indexGuide();
+      case "index lint":
+        return yield* indexLint(context);
+      case "memory check":
+        return yield* memoryCheck(context);
+      case "install codex":
+        return yield* installCodex(context);
+      case "install opencode":
+        return yield* installOpenCode(context);
+      case "install opencode-v2":
+        return yield* installOpenCodeV2(context);
+      case "install pi":
+        return yield* installPi(context);
+      case "install code-puppy":
+        return yield* installCodePuppy(context);
+      default:
+        return {
+          exitCode: 2,
+          output: `Unknown command: ${command}
+
+${HELP}`
+        };
+    }
+  }).pipe(catch_2((error) => succeed6(fileFailure(error))));
+}
+
 // src/index.ts
 var SKIP_UPDATE_ENVIRONMENT_VARIABLE = "OPERATOR_HELPER_SKIP_UPDATE";
 var ChildProcessLayer = layer.pipe(provide2(layer3), provide2(layer5));
@@ -20517,7 +20633,7 @@ var main = gen2(function* () {
     version: package_default.version
   };
   if (process.env[SKIP_UPDATE_ENVIRONMENT_VARIABLE] !== "1") {
-    const update = yield* autoUpdate(package_default.version, environment);
+    const update = yield* autoUpdate(package_default.version, environment, false);
     if (update.status === "updated") {
       const entrypoint = process.argv[1];
       if (entrypoint !== undefined) {
@@ -20546,4 +20662,4 @@ var main = gen2(function* () {
 }).pipe(provide4(LiveLayers));
 runMain2(main);
 
-//# debugId=6692B2A2E88947E864756E2164756E21
+//# debugId=F79207A63C841C4D64756E2164756E21