cueloop 0.1.0-alpha.5 → 0.1.0-alpha.50

package/package.json

@@ -1,37 +1,38 @@
 {
   "name": "cueloop",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.50",
+  "description": "Terminal review surface for coding agents: annotate plans and diffs, return a verdict, send structured feedback back",
+  "homepage": "https://github.com/mmurakaru/cueloop#readme",
+  "bugs": {
+    "url": "https://github.com/mmurakaru/cueloop/issues"
+  },
   "license": "Apache-2.0",
-  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mmurakaru/cueloop.git",
+    "directory": "packages/cli"
+  },
   "bin": {
     "cueloop": "./src/main.ts"
   },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "type": "module",
   "exports": {
     ".": "./src/main.ts"
   },
-  "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.5",
-    "@cueloop/daemon": "0.1.0-alpha.5",
-    "@cueloop/client": "0.1.0-alpha.5"
-  },
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "src",
-    "README.md"
-  ],
+  "dependencies": {
+    "@cueloop/adapters": "0.1.0-alpha.50",
+    "@cueloop/client": "0.1.0-alpha.50",
+    "@cueloop/daemon": "0.1.0-alpha.50",
+    "@cueloop/schema": "0.1.0-alpha.50"
+  },
   "engines": {
     "bun": ">=1.3.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mmurakaru/cueloop.git",
-    "directory": "packages/cli"
-  },
-  "homepage": "https://github.com/mmurakaru/cueloop#readme",
-  "bugs": {
-    "url": "https://github.com/mmurakaru/cueloop/issues"
-  },
-  "description": "Terminal review surface for coding agents: annotate plans and diffs, return a verdict, send structured feedback back"
-}
+  }
+}

package/src/actions-command.ts

@@ -0,0 +1,44 @@
+/**
+ * `cueloop actions list [--session <id>]` - print the quick-action vocabulary
+ * (the same presets a human picks in the marker popover) so a review-side agent
+ * can reference one by name or index via `session annotate --action`. With
+ * `--session`, the vocabulary comes from that session's repo (matching what
+ * `--action` will resolve); otherwise from the caller's cwd. JSON on stdout.
+ */
+
+import { loadConfig } from "@cueloop/client/config";
+import { DaemonClient } from "@cueloop/daemon/client";
+import { parseArgs, stringFlag } from "./args";
+
+export async function actionsCommand(argv: string[]): Promise<number> {
+  const { positional, flags } = parseArgs(argv);
+  const verb = positional[0] ?? "list";
+  if (verb !== "list") {
+    console.error("usage: cueloop actions list [--session <id>]");
+    return 2;
+  }
+  const role = stringFlag(flags, "role") === "agent" ? "agent" : undefined;
+  const repoRoot = await repoRootForSession(stringFlag(flags, "session"), role);
+  const actions = loadConfig({ repoRoot }).actions;
+  const numbered = actions.map((action, index) => ({
+    index: index + 1,
+    prompt: action.prompt,
+    metadata: action.metadata,
+  }));
+  console.log(JSON.stringify(numbered, null, 2));
+  return 0;
+}
+
+/** The repo the given session lives in, or the caller's cwd when no session is named. */
+async function repoRootForSession(
+  sessionId: string | undefined,
+  role: "agent" | undefined,
+): Promise<string> {
+  if (sessionId === undefined) return process.cwd();
+  const client = await DaemonClient.connect({ autostart: true, role });
+  try {
+    return (await client.sessionGet(sessionId)).workspace.repoRoot;
+  } finally {
+    client.close();
+  }
+}

package/src/args.ts

@@ -9,16 +9,16 @@ export function parseArgs(argv: string[]): ParsedArgs {
   const positional: string[] = [];
   const flags: Record<string, string | boolean> = {};
   for (let i = 0; i < argv.length; i++) {
-    const a = argv[i]!;
-    if (!a.startsWith("--")) {
-      positional.push(a);
+    const argument = argv[i]!;
+    if (!argument.startsWith("--")) {
+      positional.push(argument);
       continue;
     }
-    const eq = a.indexOf("=");
-    if (eq !== -1) {
-      flags[a.slice(2, eq)] = a.slice(eq + 1);
+    const equalsIndex = argument.indexOf("=");
+    if (equalsIndex !== -1) {
+      flags[argument.slice(2, equalsIndex)] = argument.slice(equalsIndex + 1);
     } else {
-      const key = a.slice(2);
+      const key = argument.slice(2);
       const next = argv[i + 1];
       if (next !== undefined && !next.startsWith("--")) {
         flags[key] = next;
@@ -31,7 +31,10 @@ export function parseArgs(argv: string[]): ParsedArgs {
   return { positional, flags };
 }
 
-export function flagStr(flags: Record<string, string | boolean>, key: string): string | undefined {
-  const v = flags[key];
-  return typeof v === "string" ? v : undefined;
+export function stringFlag(
+  flags: Record<string, string | boolean>,
+  key: string,
+): string | undefined {
+  const value = flags[key];
+  return typeof value === "string" ? value : undefined;
 }

package/src/main.ts

@@ -1,16 +1,30 @@
 #!/usr/bin/env bun
 /**
- * cueloop entry points (#18): `cueloop` opens the TUI on the inbox,
- * `cueloop diff` reviews the working tree, `cueloop review <pr>` a PR,
- * `cueloop session *` mirrors the daemon API for agents and scripts,
- * `cueloop serve` shares a session over ssh (read-only observers),
- * `cueloop daemon` runs the daemon in the foreground.
+ * cueloop entry points: `cueloop` opens the TUI on the inbox, the verb-first
+ * openers `cueloop plan|diff|review` open the latest pending review of that
+ * type (or address one by id/title), `cueloop diff`/`cueloop review <pr>` also
+ * keep their create paths, `cueloop session *` mirrors the daemon API for
+ * agents and scripts, `cueloop serve` shares a session over ssh (read-only
+ * observers), `cueloop daemon` runs the daemon in the foreground.
  */
 
-import { parseArgs, flagStr } from "./args";
-import { sessionCommand } from "./session-cmds";
-import { resolveWorkspace, workingTreeDiff } from "./workspace";
+import { basename, resolve } from "node:path";
+import { parseArgs, stringFlag, type ParsedArgs } from "./args";
+import {
+  isDiffReview,
+  isPlanReview,
+  isPrototypeReview,
+  isPrReview,
+  isSessionId,
+  openTargetMessage,
+  resolveOpenTarget,
+} from "./open-target";
+import { sessionCommand } from "./session-commands";
+import { CLI_VERSION } from "./version";
 import { DaemonClient } from "@cueloop/daemon/client";
+import { workingTreeDiff } from "@cueloop/daemon/working-tree";
+import type { ReviewSession } from "@cueloop/schema";
+import { openReview, resolveWorkspace } from "@cueloop/daemon/review";
 
 const argv = process.argv.slice(2);
 const cmd = argv[0];
@@ -31,29 +45,19 @@ async function main(): Promise<number> {
       await new Promise(() => {}); // run until signalled
       return 0;
     }
-    case "diff": {
-      const workspace = await resolveWorkspace();
-      const diff = await workingTreeDiff();
-      if (!diff.trim()) {
-        console.error("working tree is clean - nothing to review");
-        return 1;
-      }
-      const client = await DaemonClient.connect({ autostart: true });
-      const session = await client.sessionCreate(workspace, {
-        type: "diff",
-        content: diff,
-        meta: { title: `working tree @ ${workspace.branch}`, cwd: process.cwd() },
-      });
-      client.close();
-      return runTui(session.id);
-    }
+    case "plan":
+      return planCommand(argv.slice(1));
+    case "diff":
+      return diffCommand(argv.slice(1));
+    case "prototype":
+      return prototypeCommand(argv.slice(1));
     case "serve": {
       const { positional, flags } = parseArgs(argv.slice(1));
-      const port = flagStr(flags, "port");
+      const port = stringFlag(flags, "port");
       const { serveClient } = await import("@cueloop/client");
       const handle = await serveClient({
         port: port !== undefined ? Number(port) : undefined,
-        host: flagStr(flags, "host"),
+        host: stringFlag(flags, "host"),
         sessionId: positional[0],
       });
       console.log(
@@ -73,14 +77,42 @@ async function main(): Promise<number> {
       await new Promise(() => {}); // serve until signalled
       return 0;
     }
-    case "review": {
-      const { reviewCommand } = await import("./pr");
-      return reviewCommand(argv.slice(1));
+    case "share": {
+      const { positional, flags } = parseArgs(argv.slice(1));
+      const { shareCommand, sharePullCommand } = await import("./share-command");
+      const port = stringFlag(flags, "port");
+      const target = {
+        host: stringFlag(flags, "host"),
+        port: port !== undefined ? Number(port) : undefined,
+      };
+      if (positional[0] === "pull")
+        return sharePullCommand({ ...target, sessionId: positional[1] });
+      return shareCommand({ ...target, sessionId: positional[0] });
+    }
+    case "wake": {
+      const { wakeCommand } = await import("./wake-command");
+      return wakeCommand(argv.slice(1));
     }
+    case "actions": {
+      const { actionsCommand } = await import("./actions-command");
+      return actionsCommand(argv.slice(1));
+    }
+    case "refine": {
+      const { refineCommand } = await import("./refine-command");
+      return refineCommand(argv.slice(1));
+    }
+    case "review":
+      return reviewEntry(argv.slice(1));
     case "review-post": {
       const { reviewPostCommand } = await import("./pr");
       return reviewPostCommand(argv.slice(1));
     }
+    case "-v":
+    case "--version":
+    case "version":
+      console.log(CLI_VERSION);
+      return 0;
+    case "-h":
     case "--help":
     case "help":
       printHelp();
@@ -96,6 +128,143 @@ async function main(): Promise<number> {
   }
 }
 
+/**
+ * The id-or-title selector for a verb-first opener: the bare positional, or a
+ * value handed to `--open`/`--latest`. A bare `--latest`/`--open` flag carries
+ * no value, so the selector stays undefined and the opener defaults to the
+ * latest pending review.
+ */
+function openSelector(parsed: ParsedArgs): string | undefined {
+  return (
+    parsed.positional[0] ?? stringFlag(parsed.flags, "open") ?? stringFlag(parsed.flags, "latest")
+  );
+}
+
+/**
+ * Resolve one review of the verb's scope and open it in the TUI, or print the
+ * miss and fail. `emptyMessage` overrides the default no-pending line for the
+ * one caller that needs a scope-specific hint (a clean working tree).
+ */
+async function openReviewOfKind(
+  match: (session: ReviewSession) => boolean,
+  label: string,
+  selector: string | undefined,
+  emptyMessage?: string,
+): Promise<number> {
+  const client = await DaemonClient.connect({ autostart: true });
+  let sessions: ReviewSession[];
+  try {
+    sessions = await client.sessionList();
+  } finally {
+    client.close();
+  }
+  const target = resolveOpenTarget(sessions, { match, selector });
+  if (target.kind === "session") return runTui(target.sessionId);
+  if (target.kind === "no-pending" && emptyMessage !== undefined) {
+    console.error(emptyMessage);
+    return 1;
+  }
+  console.error(openTargetMessage(label, target));
+  return 1;
+}
+
+/** `cueloop plan [id|title]` - open the latest pending plan, or address one. */
+async function planCommand(argv: string[]): Promise<number> {
+  return openReviewOfKind(isPlanReview, "plan", openSelector(parseArgs(argv)));
+}
+
+/**
+ * `cueloop prototype <file.html>` creates a review of a rendered HTML file;
+ * a selector or `--open`/`--latest` (or a bare call with no file) opens the
+ * latest pending prototype review instead.
+ */
+async function prototypeCommand(argv: string[]): Promise<number> {
+  const parsed = parseArgs(argv);
+  const selector = openSelector(parsed);
+  const wantsOpen = "open" in parsed.flags || "latest" in parsed.flags;
+  const looksLikeFile =
+    selector !== undefined && !isSessionId(selector) && selector.endsWith(".html");
+  if (wantsOpen || !looksLikeFile)
+    return openReviewOfKind(isPrototypeReview, "prototype", selector);
+
+  const path = resolve(selector);
+  const html = await Bun.file(path)
+    .text()
+    .catch(() => undefined);
+  if (html === undefined) {
+    console.error(`prototype: cannot read ${path}`);
+    return 1;
+  }
+  const client = await DaemonClient.connect({ autostart: true });
+  const review = await openReview(client, {
+    type: "prototype",
+    content: html,
+    prototypePath: path,
+    title: basename(path),
+  });
+  client.close();
+  return runTui(review.id);
+}
+
+/**
+ * `cueloop diff` disambiguates create from open by intent:
+ *   - a selector (`cueloop diff <id|title>`) or an explicit `--open`/`--latest`
+ *     opens a pending diff review;
+ *   - otherwise a dirty working tree still creates a review as before;
+ *   - a clean working tree carries no create input, so it opens the latest
+ *     pending diff review instead of erroring.
+ */
+async function diffCommand(argv: string[]): Promise<number> {
+  const parsed = parseArgs(argv);
+  const selector = openSelector(parsed);
+  const wantsOpen = selector !== undefined || "open" in parsed.flags || "latest" in parsed.flags;
+  if (wantsOpen) return openReviewOfKind(isDiffReview, "diff", selector);
+
+  const workspace = await resolveWorkspace();
+  const diff = await workingTreeDiff();
+  if (!diff.patch.trim()) {
+    return openReviewOfKind(
+      isDiffReview,
+      "diff",
+      undefined,
+      "working tree is clean and no pending diff review - nothing to open",
+    );
+  }
+  const client = await DaemonClient.connect({ autostart: true });
+  const review = await openReview(client, {
+    type: "diff",
+    content: diff.patch,
+    files: diff.files,
+    workspace,
+    title: `working tree @ ${workspace.branch}`,
+  });
+  client.close();
+  return runTui(review.id);
+}
+
+/**
+ * `cueloop review` disambiguates create from open by intent:
+ *   - bare `cueloop review`, `--open`/`--latest`, or a `ses_*` selector opens a
+ *     pending PR review (a diff carrying a `pr` reference);
+ *   - any other positional is a PR reference and takes the create path in pr.ts.
+ */
+async function reviewEntry(argv: string[]): Promise<number> {
+  const parsed = parseArgs(argv);
+  const explicitOpen = "open" in parsed.flags || "latest" in parsed.flags;
+  const selector = openSelector(parsed);
+  const looksLikeSessionId = selector !== undefined && isSessionId(selector);
+  const wantsCreate = !explicitOpen && !looksLikeSessionId && selector !== undefined;
+  if (wantsCreate) {
+    const { reviewCommand } = await import("./pr");
+    return reviewCommand(argv);
+  }
+  return openReviewOfKind(
+    isPrReview,
+    "PR",
+    explicitOpen || looksLikeSessionId ? selector : undefined,
+  );
+}
+
 async function runTui(sessionId?: string): Promise<number> {
   const { runClient } = await import("@cueloop/client");
   return runClient({ sessionId });
@@ -106,17 +275,39 @@ function printHelp(): void {
     [
       "cueloop - review surface for coding agents",
       "",
-      "usage:",
+      "usage: cueloop [command] [options]",
+      "",
+      "common commands:",
       "  cueloop                          open the inbox",
-      "  cueloop <session-id>             open one session",
-      "  cueloop diff                     review the working tree",
+      "  cueloop plan [id|title]          open the latest pending plan review (or one by id/title)",
+      "  cueloop diff [id|title]          review your working tree (untracked files included);",
+      "                                   with a clean tree, open the latest pending diff review",
       "  cueloop review <pr>              review a pull request (--no-tui prints the session)",
-      "  cueloop review-post <id> <pr>    post a resolved session's verdict back to the PR",
+      "  cueloop prototype <file.html>    review a rendered HTML prototype (or open the latest by id/title)",
+      "",
+      "share:",
       "  cueloop serve [session-id]       share over ssh: observers are read-only,",
       "                                   you stay the controller (--port 2222, --host 127.0.0.1;",
       "                                   password-less - share the address deliberately)",
+      "  cueloop share [session-id]       hand a plan to a teammate: copies one",
+      "                                   ssh line (--host cueloop.dev, --port 22)",
+      "  cueloop share pull [session-id]  pull a teammate's annotations back into the plan",
+      "",
+      "open a specific review:",
+      "  cueloop <session-id>             open one session",
+      "  cueloop review [id|title]        open the latest pending PR review (or one by id/title)",
+      "  cueloop <plan|diff|review> --latest  open the latest pending review of that type",
+      "",
+      "scripting:",
       "  cueloop session <verb> [flags]   script the daemon (create|get|list|wait|annotate|resolve|submit-revision)",
+      "  cueloop actions list             list the quick-action vocabulary (for annotate --action)",
+      "  cueloop refine                   mine past reviews into a markdown report + writeback proposals",
+      "  cueloop wake <id> [--harness codex --thread <id>]  resume the agent with the verdict (spawn detached)",
+      "  cueloop review-post <id> <pr>    post a resolved session's verdict back to the PR",
       "  cueloop daemon                   run the daemon in the foreground",
+      "",
+      "  cueloop -v, --version            print the installed version",
+      "  cueloop -h, --help               print this help",
     ].join("\n"),
   );
 }