cueloop 0.1.0-alpha.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "cueloop",
+  "version": "0.1.0-alpha.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "cueloop": "./src/main.ts"
+  },
+  "exports": {
+    ".": "./src/main.ts"
+  },
+  "dependencies": {
+    "@cueloop/schema": "workspace:*",
+    "@cueloop/daemon": "workspace:*",
+    "@cueloop/client": "workspace:*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mmurakaru/cueloop.git",
+    "directory": "packages/cli"
+  }
+}

package/src/args.ts

@@ -0,0 +1,37 @@
+/** Tiny flag parser: --key value, --key=value, boolean --flag, positionals. */
+
+export interface ParsedArgs {
+  positional: string[];
+  flags: Record<string, string | boolean>;
+}
+
+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);
+      continue;
+    }
+    const eq = a.indexOf("=");
+    if (eq !== -1) {
+      flags[a.slice(2, eq)] = a.slice(eq + 1);
+    } else {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    }
+  }
+  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;
+}

package/src/main.ts

@@ -0,0 +1,124 @@
+#!/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.
+ */
+
+import { parseArgs, flagStr } from "./args";
+import { sessionCommand } from "./session-cmds";
+import { resolveWorkspace, workingTreeDiff } from "./workspace";
+import { DaemonClient } from "@cueloop/daemon/client";
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+
+async function main(): Promise<number> {
+  switch (cmd) {
+    case "session":
+      return sessionCommand(argv.slice(1));
+    case "daemon": {
+      const { DaemonServer } = await import("@cueloop/daemon");
+      const server = new DaemonServer({ idleExitMs: 0 });
+      const path = server.start();
+      if (path === null) {
+        console.error("a cueloop daemon already owns this home - nothing to do");
+        return 1;
+      }
+      console.log(`cueloop daemon (foreground) on ${path}`);
+      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 "serve": {
+      const { positional, flags } = parseArgs(argv.slice(1));
+      const port = flagStr(flags, "port");
+      const { serveClient } = await import("@cueloop/client");
+      const handle = await serveClient({
+        port: port !== undefined ? Number(port) : undefined,
+        host: flagStr(flags, "host"),
+        sessionId: positional[0],
+      });
+      console.log(
+        [
+          "",
+          `observers join with:  ssh -p ${handle.port} ${handle.host === "0.0.0.0" || handle.host === "::" ? "<this-host>" : handle.host}`,
+          "",
+          "no passwords, no keys: anyone who can reach this address can watch.",
+          "share the address deliberately (SSH tunnel, tailnet). observers are",
+          "read-only; you stay the one writable controller via `cueloop` locally.",
+          "ctrl-c stops serving.",
+        ].join("\n"),
+      );
+      const stop = () => void handle.close().finally(() => process.exit(0));
+      process.on("SIGINT", stop);
+      process.on("SIGTERM", stop);
+      await new Promise(() => {}); // serve until signalled
+      return 0;
+    }
+    case "review": {
+      const { reviewCommand } = await import("./pr");
+      return reviewCommand(argv.slice(1));
+    }
+    case "review-post": {
+      const { reviewPostCommand } = await import("./pr");
+      return reviewPostCommand(argv.slice(1));
+    }
+    case "--help":
+    case "help":
+      printHelp();
+      return 0;
+    case undefined:
+      return runTui();
+    default: {
+      // `cueloop <session-id>` opens the TUI on that session
+      if (cmd.startsWith("ses_")) return runTui(cmd);
+      printHelp();
+      return 2;
+    }
+  }
+}
+
+async function runTui(sessionId?: string): Promise<number> {
+  const { runClient } = await import("@cueloop/client");
+  return runClient({ sessionId });
+}
+
+function printHelp(): void {
+  console.log(
+    [
+      "cueloop - review surface for coding agents",
+      "",
+      "usage:",
+      "  cueloop                          open the inbox",
+      "  cueloop <session-id>             open one session",
+      "  cueloop diff                     review the working tree",
+      "  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 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 session <verb> [flags]   script the daemon (create|get|list|wait|annotate|resolve|submit-revision)",
+      "  cueloop daemon                   run the daemon in the foreground",
+    ].join("\n"),
+  );
+}
+
+process.exit(await main());

package/src/pr.ts

@@ -0,0 +1,118 @@
+/**
+ * PR review entry (#18): `cueloop review <pr>` fetches the PR diff through the
+ * user's `gh` CLI (auth fully delegated), opens a diff session, and posts the
+ * verdict back to the PR as a real review when the session resolves.
+ * `cueloop review-post <session-id> <pr>` is the non-interactive post-back
+ * half for agents and scripts.
+ */
+
+import type { ReviewSession, VerdictKind } from "@cueloop/schema";
+import { DaemonClient } from "@cueloop/daemon/client";
+import { parseArgs } from "./args";
+import { resolveWorkspace } from "./workspace";
+
+/** The gh binary is injectable so tests can stub it. */
+function ghBin(): string {
+  return process.env.CUELOOP_GH || "gh";
+}
+
+interface GhResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+async function gh(args: string[]): Promise<GhResult> {
+  const proc = Bun.spawn([ghBin(), ...args], { stdout: "pipe", stderr: "pipe" });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { code, stdout, stderr };
+}
+
+/** Verdict kinds map 1:1 onto gh review flags. */
+const VERDICT_FLAG: Record<VerdictKind, string> = {
+  approve: "--approve",
+  request_changes: "--request-changes",
+  comment: "--comment",
+};
+
+export async function reviewCommand(argv: string[]): Promise<number> {
+  const { positional, flags } = parseArgs(argv);
+  const pr = positional[0];
+  if (!pr) {
+    console.error("usage: cueloop review <pr> [--no-tui]");
+    return 2;
+  }
+  const diff = await gh(["pr", "diff", pr]);
+  if (diff.code !== 0) {
+    console.error(diff.stderr.trim() || `gh pr diff ${pr} failed (exit ${diff.code})`);
+    return 1;
+  }
+  if (!diff.stdout.trim()) {
+    console.error(`PR ${pr} has an empty diff - nothing to review`);
+    return 1;
+  }
+  const workspace = await resolveWorkspace();
+  const client = await DaemonClient.connect({ autostart: true });
+  const session = await client.sessionCreate(workspace, {
+    type: "diff",
+    content: diff.stdout,
+    meta: { title: `PR ${pr}`, pr, cwd: process.cwd() },
+  });
+  client.close();
+
+  if (flags["no-tui"]) {
+    console.log(JSON.stringify(session, null, 2));
+    return 0;
+  }
+
+  const { runClient } = await import("@cueloop/client");
+  await runClient({ sessionId: session.id });
+
+  const after = await getSession(session.id);
+  if (after.status !== "resolved" || !after.verdict) {
+    console.log(`session ${session.id} is unresolved - nothing was posted to PR ${pr}`);
+    return 0;
+  }
+  return postVerdict(after, pr);
+}
+
+export async function reviewPostCommand(argv: string[]): Promise<number> {
+  const { positional } = parseArgs(argv);
+  const sessionId = positional[0];
+  const pr = positional[1];
+  if (!sessionId || !pr) {
+    console.error("usage: cueloop review-post <session-id> <pr>");
+    return 2;
+  }
+  const session = await getSession(sessionId);
+  if (session.status !== "resolved" || !session.verdict) {
+    console.error(`session ${sessionId} is unresolved - nothing was posted to PR ${pr}`);
+    return 1;
+  }
+  return postVerdict(session, pr);
+}
+
+async function getSession(id: string): Promise<ReviewSession> {
+  const client = await DaemonClient.connect({ autostart: true });
+  try {
+    return await client.sessionGet(id);
+  } finally {
+    client.close();
+  }
+}
+
+/** Post the resolved session's verdict to the PR: feedback.md is the review body. */
+async function postVerdict(session: ReviewSession, pr: string): Promise<number> {
+  const verdict = session.verdict!;
+  const result = await gh(["pr", "review", pr, VERDICT_FLAG[verdict.kind], "--body", verdict.feedback]);
+  if (result.code !== 0) {
+    console.error(result.stderr.trim() || `gh pr review ${pr} failed (exit ${result.code})`);
+    return 1;
+  }
+  console.log(`posted ${verdict.kind} review to PR ${pr} (session ${session.id})`);
+  return 0;
+}

package/src/session-cmds.ts

@@ -0,0 +1,114 @@
+/**
+ * `cueloop session *` - mirrors the daemon socket API 1:1 (#14). One surface,
+ * three consumers: agent adapters, the dev loop, and integrations. Output is
+ * JSON on stdout; exit code 0 unless the daemon returned an error.
+ */
+
+import type { ArtifactType, VerdictKind } from "@cueloop/schema";
+import { DaemonClient } from "@cueloop/daemon/client";
+import { parseArgs, flagStr } from "./args";
+import { resolveWorkspace } from "./workspace";
+
+async function readStdin(): Promise<string> {
+  return await new Response(Bun.stdin.stream()).text();
+}
+
+function out(value: unknown): void {
+  console.log(JSON.stringify(value, null, 2));
+}
+
+export async function sessionCommand(argv: string[]): Promise<number> {
+  const { positional, flags } = parseArgs(argv);
+  const verb = positional[0];
+  const client = await DaemonClient.connect({ autostart: true });
+  try {
+    switch (verb) {
+      case "create": {
+        const workspace = await resolveWorkspace(flagStr(flags, "cwd"));
+        const contentFile = flagStr(flags, "content-file");
+        const content = contentFile ? await Bun.file(contentFile).text() : await readStdin();
+        const session = await client.sessionCreate(workspace, {
+          type: (flagStr(flags, "type") ?? "plan") as ArtifactType,
+          content,
+          meta: {
+            agent: flagStr(flags, "agent"),
+            agentSessionId: flagStr(flags, "agent-session-id"),
+            planPath: flagStr(flags, "plan-path"),
+            title: flagStr(flags, "title"),
+            cwd: flagStr(flags, "cwd") ?? process.cwd(),
+          },
+        });
+        out(session);
+        return 0;
+      }
+      case "get": {
+        out(await client.sessionGet(required(positional[1], "session id")));
+        return 0;
+      }
+      case "list": {
+        const status = flagStr(flags, "status") as "pending" | "resolved" | undefined;
+        out(await client.sessionList(status ? { status } : undefined));
+        return 0;
+      }
+      case "wait": {
+        const id = required(positional[1], "session id");
+        const timeoutMs = Number(flagStr(flags, "timeout-ms") ?? "60000");
+        const session = await client.sessionWait(id, timeoutMs);
+        if (session === null) {
+          out({ status: "pending" });
+          return 0;
+        }
+        out({
+          status: "resolved",
+          allow: session.verdict!.kind === "approve",
+          verdict: session.verdict!.kind,
+          feedback: session.verdict!.feedback,
+        });
+        return 0;
+      }
+      case "annotate": {
+        const id = required(positional[1], "session id");
+        const body = flagStr(flags, "body") ?? "";
+        const quote = required(flagStr(flags, "quote"), "--quote");
+        out(
+          await client.sessionAnnotate(id, {
+            id: flagStr(flags, "annotation-id") ?? `a_${Date.now().toString(36)}`,
+            kind: flagStr(flags, "kind") ?? "comment",
+            anchor: {
+              quote,
+              prefix: flagStr(flags, "prefix") ?? "",
+              suffix: flagStr(flags, "suffix") ?? "",
+            },
+            body,
+          }),
+        );
+        return 0;
+      }
+      case "resolve": {
+        const id = required(positional[1], "session id");
+        const kind = required(flagStr(flags, "verdict"), "--verdict") as VerdictKind;
+        out(await client.sessionResolve(id, kind, flagStr(flags, "summary") ?? ""));
+        return 0;
+      }
+      case "submit-revision": {
+        const id = required(positional[1], "session id");
+        const contentFile = flagStr(flags, "content-file");
+        const content = contentFile ? await Bun.file(contentFile).text() : await readStdin();
+        out(await client.sessionSubmitRevision(id, content));
+        return 0;
+      }
+      default:
+        console.error(
+          "usage: cueloop session <create|get|list|wait|annotate|resolve|submit-revision> [flags]",
+        );
+        return 2;
+    }
+  } finally {
+    client.close();
+  }
+}
+
+function required<T>(v: T | undefined, what: string): T {
+  if (v === undefined) throw new Error(`missing ${what}`);
+  return v;
+}

package/src/workspace.ts

@@ -0,0 +1,35 @@
+/** Workspace key resolution (#9): repo root + branch from the cwd. */
+
+import type { WorkspaceKey } from "@cueloop/schema";
+
+async function git(args: string[], cwd: string): Promise<string | null> {
+  const proc = Bun.spawn(["git", ...args], { cwd, stdout: "pipe", stderr: "ignore" });
+  const out = await new Response(proc.stdout).text();
+  if ((await proc.exited) !== 0) return null;
+  return out.trim();
+}
+
+export async function resolveWorkspace(cwd = process.cwd()): Promise<WorkspaceKey> {
+  const repoRoot = (await git(["rev-parse", "--show-toplevel"], cwd)) ?? cwd;
+  const branch = (await git(["rev-parse", "--abbrev-ref", "HEAD"], cwd)) ?? "detached";
+  return { repoRoot, branch };
+}
+
+export async function workingTreeDiff(cwd = process.cwd()): Promise<string> {
+  const tracked = (await git(["diff", "HEAD"], cwd)) ?? "";
+  // untracked files included by default (map note: changed-first)
+  const untrackedList = (await git(["ls-files", "--others", "--exclude-standard"], cwd)) ?? "";
+  let untracked = "";
+  for (const file of untrackedList.split("\n").filter(Boolean)) {
+    // `git diff --no-index` exits 1 when the files differ - that is success here
+    const proc = Bun.spawn(["git", "diff", "--no-index", "--", "/dev/null", file], {
+      cwd,
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    const out = await new Response(proc.stdout).text();
+    const code = await proc.exited;
+    if ((code === 0 || code === 1) && out.trim()) untracked += out.trim() + "\n";
+  }
+  return [tracked, untracked].filter(Boolean).join("\n");
+}