@opsee/cli 0.11.9

package/src/commands/initiative.ts

@@ -0,0 +1,192 @@
+/**
+ * `opsee initiative` (phase 1): list, show, create, and the memory log.
+ *
+ * Thin on purpose. Every one of these calls the same RPC the matching MCP tool calls and prints the
+ * same formatter's output (`@opsee/mcp-server/src/utils/format/initiative.js`), so the two surfaces
+ * cannot drift about what an Initiative looks like — a reader who has seen one has seen the other.
+ * Nothing here decides anything the MCP tools decide differently, and nothing formats an Initiative
+ * of its own.
+ *
+ * What the commands add over the tools is the two things a terminal has and an agent does not: a
+ * project resolved from `--project` or from the account having only one (`pickProject`, shared with
+ * `opsee init`), and a core idea read from a file or stdin, because a markdown body does not fit in
+ * argv.
+ */
+import { readFileSync } from "node:fs";
+import type { ApiClients } from "@opsee/mcp-server/src/client/api.js";
+import { formatInitiative, formatInitiativeContext, formatInitiativeList, formatInitiativeMemoryEntry, formatInitiativeMemoryList } from "@opsee/mcp-server/src/utils/format/initiative.js";
+import type { InitiativeCreateArgs, InitiativeListArgs, InitiativeMemoryArgs, InitiativeNoteArgs, InitiativeShowArgs } from "../args.js";
+import { pickProject, type ProjectChoice } from "../init/project.js";
+
+/** The memory kinds the Initiative log takes (api.v1: decision | outcome | learning | blocker |
+ * context). Checked here rather than left to the backend so a typo answers in the CLI's own words
+ * with the list, instead of as an InvalidArgument from a service the user never called by name. */
+export const MEMORY_KINDS = ["decision", "outcome", "learning", "blocker", "context"] as const;
+
+/**
+ * What `note` writes when no `--kind` is given.
+ *
+ * `opsee_add_initiative_memory` requires the kind, and is right to: an agent logging as it goes
+ * should be deliberate about whether this is a decision or a blocker. A person typing a note at a
+ * terminal should not have to be, and `context` is the kind that claims the least — it is a note,
+ * not a decision anyone else should read as settled.
+ */
+export const DEFAULT_NOTE_KIND = "context";
+
+/** The Initiative statuses the API takes. Same reasoning as `MEMORY_KINDS`. */
+export const INITIATIVE_STATUSES = ["draft", "active", "paused", "done", "archived"] as const;
+
+/** A refusal the user can fix, reported as a plain message rather than a stack; `cli.ts` prints it
+ * and exits non-zero, the way `AccountError` is handled. */
+export class InitiativeError extends Error {}
+
+export interface InitiativeDeps {
+  clients: ApiClients;
+  out: (line: string) => void;
+  /** Reads a core idea file. Injected so the tests never touch a real path. */
+  readFile?: (path: string) => string;
+  /** Reads the core idea from stdin, for `--core-idea-file -`. */
+  readStdin?: () => Promise<string>;
+}
+
+/** How many memory entries `show --context` and `memory` ask for when nothing says otherwise; the
+ * service has its own default, and this is only the flag's shape. */
+const DEFAULT_MEMORY_LIMIT = 0;
+
+function positiveInteger(flag: string, text: string | undefined): number | undefined {
+  if (text === undefined) return undefined;
+  // `Number` would take "0x10" as 16 and " 7\n" as 7, under a message that says whole number.
+  if (!/^\d+$/.test(text)) throw new InitiativeError(`${flag} must be a whole number`);
+  return Number(text);
+}
+
+function oneOf<T extends readonly string[]>(flag: string, value: string | undefined, allowed: T): T[number] | undefined {
+  if (value === undefined) return undefined;
+  if (!(allowed as readonly string[]).includes(value)) {
+    throw new InitiativeError(`${flag} must be one of: ${allowed.join(", ")} (got "${value}")`);
+  }
+  return value;
+}
+
+/**
+ * The project a command runs against: the `--project` key, or the account's only project.
+ *
+ * `pickProject` is `opsee init`'s, with no way to choose interactively — these commands are as
+ * likely to run in a script as at a keyboard, and a prompt in a pipe is a hang. With several
+ * projects and no `--project`, it answers with the message naming the keys.
+ */
+async function resolveProject(deps: InitiativeDeps, key: string | undefined): Promise<ProjectChoice> {
+  const res = await deps.clients.projects.getProjects({ pagination: { page: 1, pageSize: 200 } });
+  const projects: ProjectChoice[] = res.projects.map((p) => ({ id: p.id, key: p.key, name: p.name }));
+  const picked = await pickProject(projects, key, async () => null);
+  if (typeof picked === "string") throw new InitiativeError(picked);
+  return picked;
+}
+
+export async function runInitiativeList(deps: InitiativeDeps, args: InitiativeListArgs): Promise<number> {
+  const project = await resolveProject(deps, args.project);
+  const res = await deps.clients.initiatives.getInitiatives({
+    projectId: project.id,
+    pagination: { page: 1, pageSize: 200 },
+    filterOptions: args.search ? { search: args.search } : undefined,
+  });
+  deps.out(formatInitiativeList(res.initiatives));
+  return 0;
+}
+
+export async function runInitiativeShow(deps: InitiativeDeps, args: InitiativeShowArgs): Promise<number> {
+  if (args.context) {
+    const memoryLimit = positiveInteger("--memory", args.memory) ?? DEFAULT_MEMORY_LIMIT;
+    const res = await deps.clients.initiatives.getInitiativeContext({ initiativeId: args.initiativeId, memoryLimit });
+    if (!res.initiative) throw new InitiativeError(`No Initiative ${args.initiativeId}`);
+    // The tool's own renderer, working agreement and all: an operator reading this and an agent
+    // that called `opsee_get_initiative_context` are looking at the same page.
+    deps.out(formatInitiativeContext(res.initiative, res.graph, res.memoryEntries, res.pullRequests, res.comments));
+    return 0;
+  }
+  // `--memory` says nothing without `--context`; refused rather than ignored, since a flag that
+  // silently does nothing is a flag the user believes worked.
+  if (args.memory !== undefined) throw new InitiativeError("--memory only applies with --context; without it, show prints the Initiative's details alone. For the log on its own: opsee initiative memory <initiativeId>");
+  const res = await deps.clients.initiatives.getInitiative({ id: args.initiativeId });
+  if (!res.initiative) throw new InitiativeError(`No Initiative ${args.initiativeId}`);
+  deps.out(formatInitiative(res.initiative));
+  return 0;
+}
+
+/** The core idea's body: a file, or stdin when the path is `-`. Absent when no flag was given. */
+async function coreIdeaOf(deps: InitiativeDeps, path: string | undefined): Promise<string | undefined> {
+  if (path === undefined) return undefined;
+  if (path === "-") {
+    const read = deps.readStdin ?? readStdin;
+    const body = await read();
+    if (body.trim() === "") throw new InitiativeError("The core idea read from stdin is empty");
+    return body;
+  }
+  try {
+    const body = (deps.readFile ?? ((p: string) => readFileSync(p, "utf8")))(path);
+    if (body.trim() === "") throw new InitiativeError(`The core idea file is empty: ${path}`);
+    return body;
+  } catch (error) {
+    if (error instanceof InitiativeError) throw error;
+    throw new InitiativeError(`Could not read the core idea file ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => (body += chunk));
+    process.stdin.on("end", () => resolve(body));
+    process.stdin.on("error", reject);
+  });
+}
+
+export async function runInitiativeCreate(deps: InitiativeDeps, args: InitiativeCreateArgs): Promise<number> {
+  const status = oneOf("--status", args.status, INITIATIVE_STATUSES) ?? "draft";
+  // Before the project is resolved: a bad flag should be refused without a round trip.
+  const coreIdea = await coreIdeaOf(deps, args.coreIdeaFile);
+  const project = await resolveProject(deps, args.project);
+  const res = await deps.clients.initiatives.addInitiative({
+    projectId: project.id,
+    title: args.title!,
+    summary: args.summary,
+    status,
+    anchorType: "none",
+    coreIdea,
+    // Markdown, as the MCP tool sends it: the UI parses it on read.
+    coreIdeaContentType: "text",
+  });
+  if (!res.initiative) throw new InitiativeError("The backend created no Initiative and reported no error. Try again; if it persists, say so to the Opsee team.");
+  deps.out(`Initiative created in ${project.key}:`);
+  deps.out(formatInitiative(res.initiative));
+  return 0;
+}
+
+export async function runInitiativeMemory(deps: InitiativeDeps, args: InitiativeMemoryArgs): Promise<number> {
+  const kind = oneOf("--kind", args.kind, MEMORY_KINDS);
+  const limit = positiveInteger("--limit", args.limit);
+  const res = await deps.clients.initiatives.getInitiativeMemory({
+    initiativeId: args.initiativeId,
+    pagination: { page: 1, pageSize: limit && limit > 0 ? limit : 200 },
+    // `kinds` is a list on the wire; the flag takes one, since filtering a log by two kinds at a
+    // terminal is a thing to do with `grep`.
+    kinds: kind ? [kind] : undefined,
+  });
+  deps.out(formatInitiativeMemoryList(res.memoryEntries));
+  return 0;
+}
+
+export async function runInitiativeNote(deps: InitiativeDeps, args: InitiativeNoteArgs): Promise<number> {
+  const kind = oneOf("--kind", args.kind, MEMORY_KINDS) ?? DEFAULT_NOTE_KIND;
+  const res = await deps.clients.initiatives.addInitiativeMemoryEntry({
+    initiativeId: args.initiativeId,
+    kind,
+    body: args.body,
+    contentType: "text",
+    sourceType: "none",
+  });
+  if (!res.memoryEntry) throw new InitiativeError("The backend recorded no memory entry and reported no error. Try again; if it persists, say so to the Opsee team.");
+  deps.out(formatInitiativeMemoryEntry(res.memoryEntry));
+  return 0;
+}

package/src/commands/login.ts

@@ -0,0 +1,24 @@
+import { fetchIdentity, formatIdentity, identityIfAuthorized } from "../identity.js";
+import type { CommandDeps } from "./deps.js";
+
+export interface LoginDeps extends CommandDeps {
+  /** The MCP package's browser OAuth flow; resolves once the callback has written credentials. */
+  startLoginFlow: () => Promise<void>;
+}
+
+/** Returns the process exit code. Already logged in is a no-op that reports the identity; a stored
+ * token the backend no longer accepts is treated as logged out and the flow runs again. */
+export async function runLogin(deps: LoginDeps): Promise<number> {
+  if (deps.isAuthenticated()) {
+    const current = await identityIfAuthorized(deps.users);
+    if (current) {
+      deps.out(`Already logged in as ${formatIdentity(current)}`);
+      return 0;
+    }
+  }
+
+  await deps.startLoginFlow();
+  const id = await fetchIdentity(deps.users);
+  deps.out(`Logged in as ${formatIdentity(id)}`);
+  return 0;
+}

package/src/commands/whoami.ts

@@ -0,0 +1,15 @@
+import { formatIdentity, identityIfAuthorized } from "../identity.js";
+import type { CommandDeps } from "./deps.js";
+
+export const NOT_LOGGED_IN = "Not logged in. Run `opsee login` to connect your Opsee account.";
+
+/** Returns the process exit code. */
+export async function runWhoami(deps: CommandDeps): Promise<number> {
+  const id = deps.isAuthenticated() ? await identityIfAuthorized(deps.users) : null;
+  if (!id) {
+    deps.out(NOT_LOGGED_IN);
+    return 1;
+  }
+  deps.out(formatIdentity(id));
+  return 0;
+}

package/src/foreman/account-store.ts

@@ -0,0 +1,96 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { AccountError, MAX_CAP, type Account } from "./account.js";
+
+/** Where registered Accounts live; the file store is the real one, the memory store is for tests. */
+export interface AccountStore {
+  load(): Account[];
+  save(accounts: Account[]): void;
+}
+
+export class MemoryAccountStore implements AccountStore {
+  private accounts: Account[] = [];
+  load(): Account[] {
+    return this.accounts.map((a) => ({ ...a }));
+  }
+  save(accounts: Account[]): void {
+    this.accounts = accounts.map((a) => ({ ...a }));
+  }
+}
+
+/** Sibling of the credentials file mcp's auth module keeps in `~/.opsee/`, never inside it. */
+export function accountsFilePath(): string {
+  return process.env.OPSEE_FOREMAN_ACCOUNTS_PATH || join(homedir(), ".opsee", "foreman-accounts.json");
+}
+
+interface AccountsFile {
+  version: 1;
+  accounts: Account[];
+}
+
+/** JSON on disk, owner-readable only, matching how the credentials file beside it is kept. */
+export class FileAccountStore implements AccountStore {
+  constructor(private readonly path: string) {}
+
+  load(): Account[] {
+    if (!existsSync(this.path)) return [];
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readFileSync(this.path, "utf-8"));
+    } catch (error) {
+      throw new AccountError(`Accounts file is not valid JSON: ${this.path} (${(error as Error).message})`);
+    }
+    const file = parsed as Partial<AccountsFile> | null;
+    if (!file || file.version !== 1 || !Array.isArray(file.accounts)) {
+      throw new AccountError(`Accounts file has an unexpected shape: ${this.path}`);
+    }
+    // The cap is checked here rather than where it is first used, so a hand-edited file is refused
+    // as a message the moment it is read: `new Slots(cap)` (core/scheduler.ts) is the last guard
+    // behind this one and it can only throw, which mid-Run reads as a crash rather than a mistake
+    // in a file the human wrote.
+    for (const account of file.accounts) {
+      const cap = (account as Partial<Account> | null)?.cap;
+      if (!Number.isInteger(cap) || (cap as number) < 1 || (cap as number) > MAX_CAP) {
+        const name = (account as Partial<Account> | null)?.name ?? "(unnamed)";
+        throw new AccountError(
+          `Account "${name}" in ${this.path} has cap ${JSON.stringify(cap)}; a cap is a whole number from 1 to ${MAX_CAP}. Fix the file, or set it with: opsee foreman account set ${name} --cap <n>`,
+        );
+      }
+    }
+    return file.accounts;
+  }
+
+  /**
+   * Writes the whole file, through a temp file in the same directory that is renamed over the
+   * target. `rename` inside one directory is atomic, so a reader — this Foreman, the next one, or
+   * `foreman account list` in another terminal — sees either the old file or the new one, never a
+   * half-written one. Without that, a crash or a full disk mid-write leaves JSON that `load`
+   * refuses, and every Foreman command then fails until a human repairs the file by hand.
+   *
+   * It does not make a concurrent read-modify-write safe: the daemon writing a pause and
+   * `foreman account set --cap` in another terminal both load, change and save, and the later save
+   * wins whole. Fixing that wants a lock file around load-and-save, which is its own change; what
+   * this rules out is the failure that needs a human, not the one that loses an edit.
+   */
+  save(accounts: Account[]): void {
+    mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+    const file: AccountsFile = { version: 1, accounts };
+    // Same directory, so the rename never crosses a file system; the pid keeps two processes
+    // writing at once from using each other's temp file.
+    const temp = `${this.path}.${process.pid}.tmp`;
+    try {
+      writeFileSync(temp, JSON.stringify(file, null, 2) + "\n", { mode: 0o600, encoding: "utf-8" });
+      renameSync(temp, this.path);
+    } catch (error) {
+      // A temp file left behind would be read by nothing, but it would sit beside the real one
+      // looking like state; best-effort, since the write's own failure is what matters.
+      try {
+        rmSync(temp, { force: true });
+      } catch {
+        /* the write's error is the one worth reporting */
+      }
+      throw error;
+    }
+  }
+}