@opsee/cli 0.11.9

package/src/cli.ts

@@ -0,0 +1,341 @@
+import { execFile } from "node:child_process";
+import { accessSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { authManager } from "@opsee/mcp-server/src/auth/manager.js";
+import { startLoginFlow } from "@opsee/mcp-server/src/auth/login.js";
+import { createClients, type ApiClients } from "@opsee/mcp-server/src/client/api.js";
+import { parseCommand, usage } from "./args.js";
+import { runAccountAdd, runAccountList, runAccountRemove, runAccountResume, runAccountSet, type AccountDeps } from "./commands/account.js";
+import { runInitiativeCreate, runInitiativeList, runInitiativeMemory, runInitiativeNote, runInitiativeShow, type InitiativeDeps } from "./commands/initiative.js";
+import type { CommandDeps } from "./commands/deps.js";
+import { runForemanDebugReady, runForemanDebugServe, runForemanDebugTurn } from "./commands/foreman-debug.js";
+import { currentRepoRoot, runForemanRun, type ForemanLocal } from "./commands/foreman.js";
+import { runForemanPlan } from "./commands/foreman-plan.js";
+import { runForemanService } from "./commands/foreman-service.js";
+import { runForemanAttach, runForemanCancel, runForemanPause, runForemanRelease, runForemanResume, type ForemanControlDeps } from "./commands/foreman-control.js";
+import { runForemanUp } from "./commands/foreman-up.js";
+import { runForemanLogs, runForemanReview, runForemanStatus } from "./commands/foreman-views.js";
+import { ClaudeWorkerAdapter } from "./foreman/claude-worker-adapter.js";
+import { CodexWorkerAdapter } from "./foreman/codex-worker-adapter.js";
+import type { Account } from "./foreman/account.js";
+import { runLogin } from "./commands/login.js";
+import { runWhoami, NOT_LOGGED_IN } from "./commands/whoami.js";
+import { runInit } from "./commands/init.js";
+import { accountsFilePath, FileAccountStore } from "./foreman/account-store.js";
+import { ProcessTable } from "./foreman/core/process-table.js";
+import { ForemanError } from "./foreman/core/run.js";
+import { TranscriptStore } from "./foreman/core/transcripts.js";
+import { hostIsLaptop } from "./foreman/host.js";
+import { daemonPidPath, foremanLocalDir, processTablePath, transcriptsDir } from "./foreman/local-dir.js";
+import type { ConfigDirFs } from "./foreman/account.js";
+import { OpseeTrackerAdapter } from "./foreman/opsee-tracker-adapter.js";
+import type { Vendor } from "./foreman/vendor.js";
+import type { WorkerAdapter } from "./foreman/worker-adapter.js";
+import { askRecipe, chooseProject } from "./init/prompt.js";
+import { DEFAULT_MCP_URL, SKILLS_DIR, TRACKER_TEMPLATE_PATH } from "./init/paths.js";
+
+export interface CliIo {
+  log: (line: string) => void;
+  error: (line: string) => void;
+}
+
+/** What the CLI sends as X-Opsee-Client: the backend treats it, like `mcp`, as an automation
+ * client acting with a user's token. */
+export const CLI_CLIENT_MARKER = "cli";
+
+let cachedClients: ApiClients | null = null;
+function clients(): ApiClients {
+  if (!cachedClients) cachedClients = createClients({ marker: CLI_CLIENT_MARKER });
+  return cachedClients;
+}
+
+export function describeError(error: unknown): string {
+  if (error instanceof ConnectError) {
+    if (error.code === Code.Unauthenticated) return NOT_LOGGED_IN;
+    if (error.code === Code.Unavailable) {
+      return `Could not reach Opsee API at ${authManager.getServerUrl()}. Check your connection and OPSEE_API_URL. (${error.rawMessage})`;
+    }
+    return `[${Code[error.code]}] ${error.rawMessage}`;
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** The Worker Adapter for each vendor an Account can name (ADR-0001). */
+const WORKER_ADAPTERS: Readonly<Record<Vendor, (options: { onLine?: (line: string) => void }) => WorkerAdapter>> = {
+  claude: (options) => new ClaudeWorkerAdapter(options),
+  codex: (options) => new CodexWorkerAdapter(options),
+};
+
+/** The machine-local record (ADR-0009), opened once per command that runs or serves a Run. */
+function foremanLocal(): ForemanLocal {
+  return { table: ProcessTable.open(processTablePath()), transcripts: new TranscriptStore(transcriptsDir()), pidFile: daemonPidPath() };
+}
+
+/** The real file system, narrowed to the two calls Account registration may make. */
+const configDirFs: ConfigDirFs = { statSync, accessSync };
+
+/** The CLI entry a service unit runs: bin/opsee.js beside src/, absolute (story 16). */
+const CLI_BIN = fileURLToPath(new URL("../bin/opsee.js", import.meta.url));
+
+/** One command's stdout, or a rejection when it is missing or fails; for the host probe. */
+function execOutput(file: string, args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(file, args, { timeout: 5_000 }, (error, stdout) => (error ? reject(error) : resolve(stdout)));
+  });
+}
+
+/** One service-manager command's exit code and combined output; never a shell. */
+function execResult(file: string, args: string[]): Promise<{ code: number; output: string }> {
+  return new Promise((resolve) => {
+    execFile(file, args, { timeout: 30_000 }, (error, stdout, stderr) => {
+      // A missing binary has a string code (ENOENT); an exit status a number.
+      const code = error ? (typeof error.code === "number" ? error.code : 1) : 0;
+      resolve({ code, output: `${stdout}${stderr}` });
+    });
+  });
+}
+
+/** Whether this machine has an internal battery (story 17), through the real commands and sysfs. */
+const realHost = { platform: process.platform, isLaptop: () => hostIsLaptop({ platform: process.platform, exec: execOutput, readdir: (dir) => readdirSync(dir), readFile: (path) => readFileSync(path, "utf8") }) };
+
+/** The node binary a service unit runs: this process's, which must be node itself. Under another
+ * runtime (bun, a wrapper) the unit would run that instead, with launchd's bare environment and no
+ * shell to find node. */
+function serviceNode(): string {
+  const node = process.execPath;
+  if (!/^node(\.exe)?$/.test(basename(node))) {
+    throw new ForemanError(`foreman service must run under node so the unit can run the same binary; this is ${node}. Run it as: node bin/opsee.js foreman service ...`);
+  }
+  return node;
+}
+
+/** Ctrl-C as a promise, for the two views that keep reading until told to stop (`foreman status
+ * --watch`, a followed `foreman logs`). `on`, not `once`, like the daemon's: the listener keeps
+ * the default handler from ending the process mid-repaint, and the command returns through its own
+ * loop instead. Neither view owns a Worker, so there is nothing to stop but the reading. */
+function untilInterrupted(): Promise<void> {
+  return new Promise((resolve) => {
+    process.on("SIGINT", () => resolve());
+    process.on("SIGTERM", () => resolve());
+  });
+}
+
+/** The Worker Adapter for an Account's vendor, from the table above. */
+function workerAdapterFor(account: Account, options: { onLine?: (line: string) => void } = {}): WorkerAdapter {
+  const make = WORKER_ADAPTERS[account.vendor];
+  if (!make) throw new Error(`No Worker Adapter for vendor "${account.vendor}"`);
+  return make(options);
+}
+
+/** What login and whoami need: mcp's auth module and generated clients (ADR-0010). */
+function apiDeps(io: CliIo): CommandDeps {
+  return {
+    isAuthenticated: () => authManager.isAuthenticated(),
+    users: clients().users,
+    out: io.log,
+  };
+}
+
+/** What the Run controls need: the Tracker for the Run Record, the Accounts and adapters for the
+ * attended turn, and the machine-local record they steer through. */
+function controlDeps(io: CliIo): ForemanControlDeps {
+  return {
+    store: new FileAccountStore(accountsFilePath()),
+    tracker: new OpseeTrackerAdapter(clients()),
+    adapterFor: (account) => workerAdapterFor(account),
+    out: io.log,
+    local: foremanLocal(),
+  };
+}
+
+/** What the Foreman Account commands need: local files only, no client and no login. */
+/** Every Initiative command needs the same two things: the API and somewhere to print. */
+function initiativeDeps(io: CliIo): InitiativeDeps {
+  return { clients: clients(), out: io.log };
+}
+
+function accountDeps(io: CliIo): AccountDeps {
+  return {
+    store: new FileAccountStore(accountsFilePath()),
+    fs: configDirFs,
+    env: process.env,
+    out: io.log,
+  };
+}
+
+/** Runs one invocation of `opsee` and returns the exit code. One credential for the MCP server
+ * and the CLI: both read and write through mcp's auth module, and both talk to the backend through
+ * mcp's generated Connect-RPC clients (ADR-0010). */
+export async function main(argv: string[], io: CliIo = console): Promise<number> {
+  const command = parseCommand(argv);
+  if (command.kind === "help") {
+    io.log(usage());
+    return 0;
+  }
+  if (command.kind === "unknown") {
+    io.error(`Unknown command: ${command.input}\n`);
+    io.error(usage());
+    return 2;
+  }
+  if (command.kind === "usage-error") {
+    io.error(`${command.message}\n`);
+    io.error(usage());
+    return 2;
+  }
+
+  try {
+    switch (command.kind) {
+      case "login":
+        return await runLogin({ ...apiDeps(io), startLoginFlow });
+      case "whoami":
+        return await runWhoami(apiDeps(io));
+      case "init": {
+        const { projects, labels, boards, boardColumns, taskTypes, taskPriorities } = clients();
+        return await runInit({
+          isAuthenticated: () => authManager.isAuthenticated(),
+          out: io.log,
+          api: { projects, labels, boards, boardColumns, taskTypes, taskPriorities },
+          root: process.cwd(),
+          projectKey: command.projectKey,
+          choose: chooseProject,
+          mcpUrl: process.env.OPSEE_MCP_URL || DEFAULT_MCP_URL,
+          skillsDir: SKILLS_DIR,
+          trackerTemplate: readFileSync(TRACKER_TEMPLATE_PATH, "utf8"),
+          recipeFlags: command.recipe,
+          askRecipe,
+        });
+      }
+      case "foreman-account-add":
+        return await runAccountAdd(accountDeps(io), command.args);
+      case "foreman-account-list":
+        return await runAccountList(accountDeps(io));
+      case "foreman-account-set":
+        return await runAccountSet(accountDeps(io), command.args);
+      case "foreman-account-remove":
+        return await runAccountRemove(accountDeps(io), command.name);
+      case "foreman-account-resume":
+        return await runAccountResume(accountDeps(io), command.name);
+      case "initiative-list":
+        return await runInitiativeList(initiativeDeps(io), command.args);
+      case "initiative-show":
+        return await runInitiativeShow(initiativeDeps(io), command.args);
+      case "initiative-create":
+        return await runInitiativeCreate(initiativeDeps(io), command.args);
+      case "initiative-memory":
+        return await runInitiativeMemory(initiativeDeps(io), command.args);
+      case "initiative-note":
+        return await runInitiativeNote(initiativeDeps(io), command.args);
+      case "foreman-up":
+        return await runForemanUp({
+          store: new FileAccountStore(accountsFilePath()),
+          tracker: new OpseeTrackerAdapter(clients()),
+          adapterFor: (account) => workerAdapterFor(account),
+          repoRoot: currentRepoRoot,
+          out: io.log,
+          local: foremanLocal(),
+          host: realHost,
+          // `on`, not `once`, for the same reason as debug serve below; the Worker hooks see this
+          // listener and do not re-raise, so the daemon leaves through its own loop.
+          untilStop: new Promise((resolve) => {
+            process.on("SIGINT", () => resolve());
+            process.on("SIGTERM", () => resolve());
+          }),
+        });
+      case "foreman-run":
+        return await runForemanRun(
+          {
+            store: new FileAccountStore(accountsFilePath()),
+            tracker: new OpseeTrackerAdapter(clients()),
+            adapterFor: (account) => workerAdapterFor(account),
+            repoRoot: currentRepoRoot,
+            out: io.log,
+            local: foremanLocal(),
+          },
+          command.args,
+        );
+      case "foreman-plan":
+        return await runForemanPlan(
+          {
+            store: new FileAccountStore(accountsFilePath()),
+            tracker: new OpseeTrackerAdapter(clients()),
+            adapterFor: (account) => workerAdapterFor(account),
+            repoRoot: currentRepoRoot,
+            out: io.log,
+          },
+          command.args,
+        );
+      case "foreman-service":
+        return await runForemanService(
+          {
+            platform: process.platform,
+            home: homedir(),
+            uid: process.getuid?.(),
+            node: serviceNode(),
+            bin: CLI_BIN,
+            repoRoot: currentRepoRoot,
+            localDir: foremanLocalDir(),
+            pidFile: daemonPidPath(),
+            env: process.env,
+            store: new FileAccountStore(accountsFilePath()),
+            exec: execResult,
+            out: io.log,
+          },
+          command.args,
+        );
+      // `untilInterrupted` is passed as the function it is, not called here: it installs SIGINT and
+      // SIGTERM handlers, and installing those for a one-shot `status` or a `logs --no-follow`
+      // that never awaits the promise would leave Ctrl-C doing nothing at all on a command that
+      // should simply die. Each command calls it only on the branch that waits.
+      case "foreman-status":
+        return await runForemanStatus(
+          { store: new FileAccountStore(accountsFilePath()), local: foremanLocal(), out: io.log, untilStop: untilInterrupted },
+          command.args,
+        );
+      case "foreman-logs":
+        return await runForemanLogs(
+          { local: foremanLocal(), tracker: new OpseeTrackerAdapter(clients()), out: io.log, untilStop: untilInterrupted },
+          command.args,
+        );
+      case "foreman-review":
+        return await runForemanReview({ tracker: new OpseeTrackerAdapter(clients()), local: foremanLocal(), out: io.log }, command.args);
+      case "foreman-attach":
+        return await runForemanAttach(controlDeps(io), command.taskId);
+      case "foreman-release":
+        return await runForemanRelease(controlDeps(io), command.taskId);
+      case "foreman-cancel":
+        return await runForemanCancel(controlDeps(io), command.taskId);
+      case "foreman-pause":
+        return await runForemanPause(controlDeps(io), command.initiativeId);
+      case "foreman-resume":
+        return await runForemanResume(controlDeps(io), command.initiativeId);
+      case "foreman-debug-ready":
+        return await runForemanDebugReady(
+          { tracker: new OpseeTrackerAdapter(clients()), out: io.log },
+          command.initiativeId,
+        );
+      case "foreman-debug-serve":
+        return await runForemanDebugServe(
+          // `on`, not `once`: a terminal's Ctrl-C and the bin wrapper's forward both arrive, and
+          // a second SIGINT with no listener left would kill the process before the app is stopped.
+          { root: process.cwd(), out: io.log, untilStop: new Promise((resolve) => process.on("SIGINT", () => resolve())) },
+          command.port,
+        );
+      case "foreman-debug-turn":
+        return await runForemanDebugTurn(
+          {
+            store: new FileAccountStore(accountsFilePath()),
+            adapterFor: (account, { raw }) => workerAdapterFor(account, { onLine: raw ? io.log : undefined }),
+            isDirectory: (path) => statSync(path).isDirectory(),
+            out: io.log,
+          },
+          command.args,
+        );
+    }
+  } catch (error) {
+    io.error(describeError(error));
+    return 1;
+  }
+}

package/src/commands/account.ts

@@ -0,0 +1,121 @@
+import type { AccountAddArgs, AccountSetArgs } from "../args.js";
+import {
+  AccountError,
+  clearQuarantine,
+  describeAccount,
+  describeLimits,
+  formatAccountTable,
+  registerAccount,
+  noteResumed,
+  removeAccount,
+  resumeAccount,
+  setAccountLimits,
+  type ConfigDirFs,
+} from "../foreman/account.js";
+import type { AccountStore } from "../foreman/account-store.js";
+import { printableOneLine } from "../foreman/core/text.js";
+
+/** Account commands are local: no backend, no login. The fs seam is the whole of their file-system
+ * reach beyond the store; `env` is only ever asked whether a name is set, never for a value. */
+export interface AccountDeps {
+  store: AccountStore;
+  fs: ConfigDirFs;
+  env: Readonly<Record<string, string | undefined>>;
+  out: (line: string) => void;
+}
+
+/** Returns the process exit code. Validation failures throw AccountError for the CLI to report. */
+export async function runAccountAdd(deps: AccountDeps, args: AccountAddArgs): Promise<number> {
+  if (args.vendor === undefined) {
+    throw new AccountError("--vendor is required");
+  }
+  const account = registerAccount(deps.store, deps.fs, {
+    vendor: args.vendor,
+    name: args.name,
+    configDir: args.configDir,
+    keyRef: args.keyEnv,
+    cap: positiveInteger("--cap", args.cap),
+  });
+  deps.out(`Registered ${describeAccount(account)}`);
+  if (account.type === "api_key" && !(account.keyRef in deps.env)) {
+    deps.out(`Note: ${account.keyRef} is not set in this shell; a Worker on this Account needs it at launch.`);
+  }
+  return 0;
+}
+
+export async function runAccountList(deps: AccountDeps): Promise<number> {
+  const accounts = deps.store.load();
+  if (accounts.length === 0) {
+    deps.out("No Accounts registered. Run `opsee foreman account add` to register one.");
+    return 0;
+  }
+  for (const line of formatAccountTable(accounts)) deps.out(line);
+  return 0;
+}
+
+/** `opsee foreman account set <name>` (story 27): the Account's Slot cap and per-turn limits.
+ * Raising a cap is only ever this command — the Foreman never widens one on its own, so the
+ * concurrency a vendor sees on an identity stays something a person chose. */
+export async function runAccountSet(deps: AccountDeps, args: AccountSetArgs): Promise<number> {
+  const account = setAccountLimits(deps.store, args.name, {
+    cap: positiveInteger("--cap", args.cap),
+    maxTurns: positiveInteger("--max-turns", args.maxTurns),
+    stallTimeoutMs: positiveInteger("--stall-timeout", args.stallTimeoutMs),
+  });
+  deps.out(`Account "${account.name}": ${describeLimits(account)}`);
+  return 0;
+}
+
+/** A flag's value as digits and nothing else, refused here in the words the model layer uses. It is
+ * `Number` this stands in for: `Number("0x10")` is 16, `Number("1e3")` is 1000 and `Number(" 7\\n")`
+ * is 7, so `--cap 0x10` would have quietly registered an Account at cap 16 under a message that
+ * says positive integer. The range itself (`MAX_CAP`, `MIN_STALL_TIMEOUT_MS`) is the model's. */
+function positiveInteger(flag: string, text: string | undefined): number | undefined {
+  if (text === undefined) return undefined;
+  if (!/^\d+$/.test(text)) throw new AccountError(`${flag} must be a positive integer`);
+  return Number(text);
+}
+
+/**
+ * `opsee foreman account resume <name>` (OPS-288): lifts a quarantine, and a pause with it.
+ *
+ * A quarantine is the one Account state nothing clears by itself, and registering the Account again
+ * is the documented way out — but `account add` refuses a name or a source it already has, so that
+ * path is really remove-then-add, which silently drops the Account's cap and per-turn limits. This
+ * is the same lift without that cost, for the ordinary case: the operator has just logged the
+ * vendor back in and the credential behind the unchanged path is live again.
+ *
+ * It also clears a pause, which needs no command of its own (resume is time-based) but would be
+ * surprising to leave behind on an Account the operator has just asked to come back.
+ */
+export async function runAccountResume(deps: AccountDeps, name: string): Promise<number> {
+  const before = deps.store.load().find((a) => a.name === name);
+  if (!before) {
+    throw new AccountError(`No Account named "${name}"`);
+  }
+  const account = clearQuarantine(deps.store, name);
+  if (!account) {
+    throw new AccountError(`No Account named "${name}"`);
+  }
+  resumeAccount(deps.store, name);
+  // Stamped for the Run Record, which this command cannot reach: it has no Initiative, and a Run
+  // Record belongs to one. The next Run that builds a Lane on this Account reports the lift with
+  // this timestamp (`ResumedState`, core/run.ts `reportResumedAccounts`).
+  const wasPaused = before.paused !== null && before.paused !== undefined;
+  const from = before.quarantined ? (wasPaused ? "both" : "quarantined") : "paused";
+  noteResumed(deps.store, name, new Date(), from);
+  // Said plainly either way: "nothing was wrong with it" is an answer the operator came for just as
+  // much as the lift, and a silent success would read as the quarantine having been the problem.
+  deps.out(
+    before.quarantined
+      ? `Account "${account.name}" is no longer quarantined (it was, since ${before.quarantined.at}: ${printableOneLine(before.quarantined.reason)}). The next tick may dispatch on it.`
+      : `Account "${account.name}" was not quarantined; any pause on it is cleared.`,
+  );
+  return 0;
+}
+
+export async function runAccountRemove(deps: AccountDeps, name: string): Promise<number> {
+  const removed = removeAccount(deps.store, name);
+  deps.out(`Removed Account "${removed.name}"`);
+  return 0;
+}

package/src/commands/deps.ts

@@ -0,0 +1,11 @@
+import type { IdentityClient } from "../identity.js";
+
+/** What the backend-facing commands (login, whoami) need from the outside world; cli.ts builds it
+ * from mcp's auth module and generated clients, tests hand in fakes. Foreman Account commands are
+ * local and take AccountDeps instead. */
+export interface CommandDeps {
+  /** Whether a usable token is stored (mcp's AuthManager.isAuthenticated). */
+  isAuthenticated: () => boolean;
+  users: IdentityClient;
+  out: (line: string) => void;
+}