cueloop 0.1.0-alpha.67 → 0.1.0-alpha.69

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cueloop",
-  "version": "0.1.0-alpha.67",
+  "version": "0.1.0-alpha.69",
   "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": {
@@ -30,10 +30,10 @@
     "build:binary": "bun build --compile --external cpu-features ./src/main.ts --outfile dist/cueloop"
   },
   "dependencies": {
-    "@cueloop/adapters": "0.1.0-alpha.67",
-    "@cueloop/client": "0.1.0-alpha.67",
-    "@cueloop/daemon": "0.1.0-alpha.67",
-    "@cueloop/schema": "0.1.0-alpha.67",
+    "@cueloop/adapters": "0.1.0-alpha.69",
+    "@cueloop/client": "0.1.0-alpha.69",
+    "@cueloop/daemon": "0.1.0-alpha.69",
+    "@cueloop/schema": "0.1.0-alpha.69",
     "valibot": "^1.4.2"
   },
   "engines": {

package/src/main.ts

@@ -114,6 +114,7 @@ const commandHandlers: CommandHandlers = {
   wake: async (rest) => (await import("./wake-command")).wakeCommand(rest),
   actions: async (rest) => (await import("./actions-command")).actionsCommand(rest),
   refine: async (rest) => (await import("./refine-command")).refineCommand(rest),
+  update: async (rest) => (await import("./update-command")).updateCommand(rest),
   review: (rest) => reviewEntry(rest),
   "review-post": async (rest) => (await import("./pr")).reviewPostCommand(rest),
   dev: async () => (await import("./dev-command")).devCommand(),
@@ -202,26 +203,30 @@ async function replyCommand(argv: string[]): Promise<number> {
 }
 
 /**
- * `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.
+ * `cueloop prototype <file.md>` creates a review of a component design doc
+ * (API / Composition / Callstack); an `.html` file instead creates the opt-in
+ * experimental pixel mockup. 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;
+  // a markdown design doc is the default; an .html entry is the opt-in pixel mockup
+  const isHtmlPrototype = selector?.endsWith(".html") ?? false;
+  const isMarkdownPrototype = selector?.endsWith(".md") || selector?.endsWith(".markdown") || false;
   const looksLikeFile =
-    selector !== undefined && !isSessionId(selector) && selector.endsWith(".html");
+    selector !== undefined && !isSessionId(selector) && (isHtmlPrototype || isMarkdownPrototype);
 
   if (wantsOpen || !looksLikeFile)
     return openReviewOfKind(isPrototypeReview, "prototype", selector);
 
   const path = resolve(selector);
-  const html = await Bun.file(path)
+  const content = await Bun.file(path)
     .text()
     .catch(() => undefined);
 
-  if (html === undefined) {
+  if (content === undefined) {
     console.error(`prototype: cannot read ${path}`);
 
     return 1;
@@ -229,8 +234,9 @@ async function prototypeCommand(argv: string[]): Promise<number> {
   const client = await DaemonClient.connect({ autostart: true });
   const review = await openReview(client, {
     type: "prototype",
-    content: html,
-    prototypePath: path,
+    content,
+    // only an HTML entry carries a prototypePath, the signal for the experimental pixel mode
+    prototypePath: isHtmlPrototype ? path : undefined,
     title: basename(path),
   });
 
@@ -325,7 +331,7 @@ function printHelp(): void {
       "  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 prototype <file.html>    review a rendered HTML prototype (or open the latest by id/title)",
+      "  cueloop prototype <file.md>      review a component design doc (or open the latest by id/title)",
       "",
       "share:",
       "  cueloop serve [session-id]       share over ssh: observers are read-only,",
@@ -344,6 +350,7 @@ function printHelp(): void {
       "  cueloop session <primitive> [flags]   script the daemon (create|get|list|wait|annotate|remove|cut|restore|curate|set-viewed|navigate|branch|switch|label|fork|name-self|events|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 update [--dry-run]       update the installed cueloop binary (--dry-run reports the target only)",
       "  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",

package/src/session-commands.ts

@@ -16,6 +16,7 @@ import { DaemonClient } from "@cueloop/daemon/client";
 import { openHerdrPaneForReview } from "@cueloop/daemon/herdr-pane";
 import { openReview, verdictResponse } from "@cueloop/daemon/review";
 import { loadConfig, quickActionBody, resolveQuickAction } from "@cueloop/client/config";
+import { slashItemsFrom } from "@cueloop/client/slash-palette";
 import { parseArgs, stringFlag } from "./args";
 
 async function readStdin(): Promise<string> {
@@ -342,8 +343,15 @@ async function sessionResolveCommand({
 }: SessionContext): Promise<number> {
   const id = required(positional[1], "session id");
   const kind = v.parse(VerdictKindSchema, required(stringFlag(flags, "verdict"), "--verdict"));
+  // expand /name quick-action references in TUI-authored comments, so a CLI resolve sends the agent
+  // the action bodies too, not the bare references
+  const session = await client.sessionGet(id);
+  const actions = loadConfig({ repoRoot: session.workspace.repoRoot }).actions;
+  const actionBodies = Object.fromEntries(
+    slashItemsFrom(actions).map((item) => [item.name, item.body]),
+  );
 
-  out(await client.sessionResolve(id, kind, stringFlag(flags, "summary") ?? ""));
+  out(await client.sessionResolve(id, kind, stringFlag(flags, "summary") ?? "", actionBodies));
 
   return 0;
 }

package/src/update-command.test.ts

@@ -0,0 +1,163 @@
+/** update install-dir resolution and the update flow over injected deps: never the Bun `/$bunfs` path, an up-to-date short-circuit, and a restart notice on success. */
+
+import { describe, expect, mock, test } from "bun:test";
+import { resolveInstallDir, runUpdate, type UpdateDeps } from "./update-command";
+
+function depsSpy(overrides: Partial<UpdateDeps> = {}): UpdateDeps & { lines: string[] } {
+  const lines: string[] = [];
+
+  return {
+    currentVersion: "0.1.0-alpha.68",
+    installDir: () => "/Users/dev/.local/bin",
+    fetchLatestVersion: mock(async () => "0.1.0-alpha.68"),
+    runInstaller: mock(async () => 0),
+    out: (message: string) => void lines.push(message),
+    lines,
+    ...overrides,
+  };
+}
+
+describe("resolveInstallDir", () => {
+  test("rejects the Bun single-file virtual path and falls back to the per-user bin dir", () => {
+    // Arrange - a compiled binary that mistakenly reports its bunfs path
+    const env: NodeJS.ProcessEnv = { HOME: "/Users/dev" };
+
+    // Act
+    const dir = resolveInstallDir("/$bunfs/root/cueloop", env);
+
+    // Assert
+    expect(dir).toBe("/Users/dev/.local/bin");
+  });
+
+  test("uses the real on-disk directory of the invoked binary", () => {
+    // Arrange
+    const env: NodeJS.ProcessEnv = { HOME: "/Users/dev" };
+
+    // Act
+    const dir = resolveInstallDir("/usr/local/bin/cueloop", env);
+
+    // Assert
+    expect(dir).toBe("/usr/local/bin");
+  });
+
+  test("falls back to the per-user bin dir when not running as the compiled cueloop", () => {
+    // Arrange - execPath is the bun runtime, not cueloop
+    const env: NodeJS.ProcessEnv = { HOME: "/Users/dev" };
+
+    // Act
+    const dir = resolveInstallDir("/Users/dev/.bun/bin/bun", env);
+
+    // Assert
+    expect(dir).toBe("/Users/dev/.local/bin");
+  });
+
+  test("an explicit CUELOOP_INSTALL_DIR overrides everything", () => {
+    // Arrange
+    const env: NodeJS.ProcessEnv = { HOME: "/Users/dev", CUELOOP_INSTALL_DIR: "/opt/bin" };
+
+    // Act
+    const dir = resolveInstallDir("/$bunfs/root/cueloop", env);
+
+    // Assert
+    expect(dir).toBe("/opt/bin");
+  });
+});
+
+describe(runUpdate, () => {
+  test("--dry-run reports the target without any network or install work", async () => {
+    // Arrange
+    const deps = depsSpy();
+
+    // Act
+    const code = await runUpdate(deps, true);
+
+    // Assert
+    expect(code).toBe(0);
+    expect(deps.lines).toEqual([
+      "Current version: 0.1.0-alpha.68",
+      "cueloop would update in /Users/dev/.local/bin",
+    ]);
+    expect(deps.fetchLatestVersion).not.toHaveBeenCalled();
+    expect(deps.runInstaller).not.toHaveBeenCalled();
+  });
+
+  test("reports up to date and skips the installer when no newer version exists", async () => {
+    // Arrange - latest matches the current version
+    const deps = depsSpy({ fetchLatestVersion: mock(async () => "0.1.0-alpha.68") });
+
+    // Act
+    const code = await runUpdate(deps, false);
+
+    // Assert
+    expect(code).toBe(0);
+    expect(deps.lines).toContain("cueloop is up to date (0.1.0-alpha.68)");
+    expect(deps.runInstaller).not.toHaveBeenCalled();
+  });
+
+  test("does not downgrade when the newest release is older than the current build", async () => {
+    // Arrange - a dev build ahead of the published release
+    const deps = depsSpy({
+      currentVersion: "0.1.0-alpha.69",
+      fetchLatestVersion: mock(async () => "0.1.0-alpha.68"),
+    });
+
+    // Act
+    const code = await runUpdate(deps, false);
+
+    // Assert
+    expect(code).toBe(0);
+    expect(deps.runInstaller).not.toHaveBeenCalled();
+  });
+
+  test("runs the installer and prints a restart notice when a newer version exists", async () => {
+    // Arrange
+    const deps = depsSpy({ fetchLatestVersion: mock(async () => "0.1.0-alpha.99") });
+
+    // Act
+    const code = await runUpdate(deps, false);
+
+    // Assert
+    expect(code).toBe(0);
+    expect(deps.runInstaller).toHaveBeenCalledWith("/Users/dev/.local/bin");
+    expect(deps.lines).toContain("Update ran successfully! Please restart cueloop.");
+  });
+
+  test("proceeds with the update when the latest version cannot be determined", async () => {
+    // Arrange - releases API unreachable
+    const deps = depsSpy({ fetchLatestVersion: mock(async () => undefined) });
+
+    // Act
+    await runUpdate(deps, false);
+
+    // Assert
+    expect(deps.runInstaller).toHaveBeenCalledTimes(1);
+  });
+
+  test("does not print the restart notice when the installer fails", async () => {
+    // Arrange
+    const deps = depsSpy({
+      fetchLatestVersion: mock(async () => "0.1.0-alpha.99"),
+      runInstaller: mock(async () => 1),
+    });
+
+    // Act
+    const code = await runUpdate(deps, false);
+
+    // Assert
+    expect(code).toBe(1);
+    expect(deps.lines).not.toContain("Update ran successfully! Please restart cueloop.");
+  });
+
+  test("rejects a relative install dir before doing any work", async () => {
+    // Arrange
+    const deps = depsSpy({ installDir: () => "relative/dir" });
+
+    // Act
+    const code = await runUpdate(deps, false);
+
+    // Assert
+    expect(code).toBe(1);
+    expect(deps.lines[0]).toContain("must be an absolute path");
+    expect(deps.runInstaller).not.toHaveBeenCalled();
+  });
+});

package/src/update-command.ts

@@ -0,0 +1,177 @@
+import { basename, dirname, isAbsolute, resolve } from "node:path";
+import * as v from "valibot";
+import { CLI_VERSION } from "./version";
+
+const INSTALL_URL = "https://cueloop.dev/install.sh";
+const RELEASES_URL = "https://api.github.com/repos/mmurakaru/cueloop/releases?per_page=100";
+const RELEASE_TAG_PREFIX = "cueloop@";
+
+const InstallerScriptSchema = v.pipe(
+  v.string(),
+  v.minLength(1),
+  v.check(
+    (script) => script.includes("CUELOOP_INSTALL_DIR"),
+    "installer is not a cueloop installer",
+  ),
+);
+
+const ReleasesSchema = v.array(v.object({ tag_name: v.nullish(v.string()) }));
+
+function userBinInstallDir(env: NodeJS.ProcessEnv): string | undefined {
+  if (env.HOME === undefined) return undefined;
+
+  return `${env.HOME}/.local/bin`;
+}
+
+/**
+ * The directory that holds the running binary, or undefined when we are not the
+ * compiled cueloop. Reads `execPath` (the real on-disk executable), not
+ * `argv[1]`: a Bun single-file executable reports its virtual filesystem path
+ * (`/$bunfs/root/cueloop`) in `argv[1]`, and installing there fails with a
+ * read-only filesystem error. The `/$bunfs` guard is belt-and-braces.
+ */
+function invokedBinaryInstallDir(execPath: string): string | undefined {
+  if (basename(execPath) !== "cueloop") return undefined;
+
+  const dir = dirname(isAbsolute(execPath) ? execPath : resolve(execPath));
+
+  if (dir === "/$bunfs" || dir.startsWith("/$bunfs/")) return undefined;
+
+  return dir;
+}
+
+/** Where an update should land: an explicit override, else the binary's own directory, else the per-user bin dir. */
+export function resolveInstallDir(execPath: string, env: NodeJS.ProcessEnv): string | undefined {
+  return env.CUELOOP_INSTALL_DIR || invokedBinaryInstallDir(execPath) || userBinInstallDir(env);
+}
+
+/** The newest published cueloop version, or undefined when the releases API is unreachable or empty. */
+async function fetchLatestVersion(): Promise<string | undefined> {
+  try {
+    const response = await fetch(RELEASES_URL, { headers: { "user-agent": "cueloop-update" } });
+
+    if (!response.ok) return undefined;
+    const parsed = v.safeParse(ReleasesSchema, await response.json());
+
+    if (!parsed.success) return undefined;
+
+    for (const release of parsed.output) {
+      if (release.tag_name?.startsWith(RELEASE_TAG_PREFIX)) {
+        return release.tag_name.slice(RELEASE_TAG_PREFIX.length);
+      }
+    }
+
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** True when `latest` is strictly newer than `current`; unparseable versions fall through to attempting the update. */
+function isNewer(latest: string, current: string): boolean {
+  try {
+    return Bun.semver.order(latest, current) === 1;
+  } catch {
+    return true;
+  }
+}
+
+/** Fetch the published installer and run it, targeting `targetInstallDir`; returns the installer's exit code. */
+async function runInstaller(targetInstallDir: string): Promise<number> {
+  try {
+    const response = await fetch(INSTALL_URL);
+
+    if (!response.ok) {
+      console.error(`cueloop update: failed to fetch installer (${response.status})`);
+
+      return 1;
+    }
+    const parsed = v.safeParse(InstallerScriptSchema, await response.text());
+
+    if (!parsed.success) {
+      console.error("cueloop update: fetched installer failed validation");
+
+      return 1;
+    }
+    const child = Bun.spawn(["sh"], {
+      stdin: "pipe",
+      stdout: "inherit",
+      stderr: "inherit",
+      // an update replaces the binary in place; it never edits the user's shell rc
+      env: { ...process.env, CUELOOP_INSTALL_DIR: targetInstallDir, CUELOOP_NO_MODIFY_PATH: "1" },
+    });
+
+    child.stdin.write(parsed.output);
+    child.stdin.end();
+
+    return child.exited;
+  } catch (error) {
+    console.error(`cueloop update: ${error instanceof Error ? error.message : String(error)}`);
+
+    return 1;
+  }
+}
+
+export interface UpdateDeps {
+  currentVersion: string;
+  installDir: () => string | undefined;
+  fetchLatestVersion: () => Promise<string | undefined>;
+  runInstaller: (targetInstallDir: string) => Promise<number>;
+  out: (message: string) => void;
+}
+
+/**
+ * The update flow, over injectable dependencies: resolve the target directory,
+ * report the current version, and either report that we are up to date or re-run
+ * the installer. `--dry-run` resolves and reports the target without any network
+ * work, which is how the compiled-binary path resolution gets tested.
+ */
+export async function runUpdate(deps: UpdateDeps, dryRun: boolean): Promise<number> {
+  const targetInstallDir = deps.installDir();
+
+  if (targetInstallDir === undefined) {
+    deps.out("cueloop update: HOME is not set and the current binary path is unknown");
+
+    return 1;
+  }
+  if (!targetInstallDir.startsWith("/")) {
+    deps.out("cueloop update: CUELOOP_INSTALL_DIR must be an absolute path");
+
+    return 1;
+  }
+  deps.out(`Current version: ${deps.currentVersion}`);
+
+  if (dryRun) {
+    deps.out(`cueloop would update in ${targetInstallDir}`);
+
+    return 0;
+  }
+  deps.out("Checking for updates to latest version...");
+  const latest = await deps.fetchLatestVersion();
+
+  if (latest !== undefined && !isNewer(latest, deps.currentVersion)) {
+    deps.out(`cueloop is up to date (${deps.currentVersion})`);
+
+    return 0;
+  }
+  deps.out(`updating cueloop in ${targetInstallDir}...`);
+  const exitCode = await deps.runInstaller(targetInstallDir);
+
+  if (exitCode === 0) deps.out("Update ran successfully! Please restart cueloop.");
+
+  return exitCode;
+}
+
+/** `cueloop update [--dry-run]` - update the installed cueloop binary in place. */
+export async function updateCommand(argv: string[] = []): Promise<number> {
+  return runUpdate(
+    {
+      currentVersion: CLI_VERSION,
+      installDir: () => resolveInstallDir(process.execPath, process.env),
+      fetchLatestVersion,
+      runInstaller,
+      out: (message) => console.error(message),
+    },
+    argv.includes("--dry-run"),
+  );
+}