Skip to content

armgit / cogit

Public Imported from GitHub
0

Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.

feat(cli): add open command with OS opener

Eren349db6558c1d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bbe4641..1b9aee2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
+- `codelineage open [dir]`: rebuilds the map and hands `lineage.html` to the OS opener (`xdg-open`, `open` or `start`), printing the path when no opener is found; without a directory it explains that the global panel arrives with Epic 3.
- Experimental outline side view in the map: a collapsible epoch → session → node tree behind a "Show outline" toggle (off by default); selecting a row expands the graph groups it needs, centres that node and opens the drill-down panel, while graph clicks highlight the matching row.
- Drill-down side panel in the map: clicking a node or session shows title, kind, summary, why, timestamps and the owning session, with a "Copy resume command" button (`cd '<path>' && claude --resume <id>`, clipboard plus a `file://` fallback). `build` marks sessions whose Claude Code transcript no longer exists, disabling the button with "session no longer available".
- Nested lineage graph in the map: React Flow 12 renders epochs → sessions → nodes as collapsible groups, ELK lays them out top-down in the page, with a minimap, controls and kind colours; the latest session opens expanded. 495 nodes lay out in ~96–155 ms per change in Chromium from `file://`.
diff --git a/packages/cli/src/commands/open.ts b/packages/cli/src/commands/open.ts
new file mode 100644
index 0000000..2527c95
--- /dev/null
+++ b/packages/cli/src/commands/open.ts
@@ -0,0 +1,72 @@
+import { type SpawnOptions, spawn } from "node:child_process";
+import { resolve } from "node:path";
+import type { Io } from "../io.js";
+import { projectPaths } from "../store/paths.js";
+import { buildProject } from "./build.js";
+
+export const PANEL_NOT_READY =
+ "The global panel arrives with Epic 3. Run `codelineage open <dir>` to open a project's map.";
+
+export interface OpenOptions {
+ dir: string;
+ io: Io;
+ /** Tests inject a minimal page instead of the bundled template. */
+ templateHtml?: string;
+ /** Tests replace the OS opener; resolves false when none is available. */
+ launch?: (file: string) => Promise<boolean>;
+}
+
+export interface OpenerCommand {
+ command: string;
+ args: string[];
+}
+
+/** The opener that ships with the platform; Windows `start` is a shell builtin. */
+export function openerCommand(platform: NodeJS.Platform, file: string): OpenerCommand {
+ if (platform === "darwin") return { command: "open", args: [file] };
+ if (platform === "win32") return { command: "cmd", args: ["/c", "start", "", file] };
+ return { command: "xdg-open", args: [file] };
+}
+
+type SpawnLike = (
+ command: string,
+ args: string[],
+ options: SpawnOptions,
+) => { once: (event: "spawn" | "error", listener: () => void) => unknown; unref: () => void };
+
+const systemSpawn: SpawnLike = (command, args, options) => spawn(command, args, options);
+
+/**
+ * Starts the OS opener detached. Resolves false when the binary is missing so
+ * the caller can print the path instead of leaving the user without anything.
+ */
+export function launchFile(file: string, spawnFn: SpawnLike = systemSpawn): Promise<boolean> {
+ const { command, args } = openerCommand(process.platform, file);
+ return new Promise((done) => {
+ const child = spawnFn(command, args, { detached: true, stdio: "ignore" });
+ child.once("error", () => done(false));
+ child.once("spawn", () => {
+ child.unref();
+ done(true);
+ });
+ });
+}
+
+/** Rebuilds the map, then hands `lineage.html` to the OS opener. */
+export async function openProject(opts: OpenOptions): Promise<void> {
+ const { io } = opts;
+ const root = resolve(opts.dir);
+ await buildProject({
+ dir: root,
+ io,
+ ...(opts.templateHtml === undefined ? {} : { templateHtml: opts.templateHtml }),
+ });
+ const html = projectPaths(root).html;
+ const opened = await (opts.launch ?? launchFile)(html);
+ if (opened) {
+ io.out(`Opened ${html}`);
+ return;
+ }
+ io.out(html);
+ io.warn("no application opener found; open the file manually");
+}
diff --git a/packages/cli/src/program.ts b/packages/cli/src/program.ts
index 6be505b..a131c02 100644
--- a/packages/cli/src/program.ts
+++ b/packages/cli/src/program.ts
@@ -4,11 +4,17 @@ import { buildProject } from "./commands/build.js";
import { configGet, configSet } from "./commands/config.js";
import { epochAdd } from "./commands/epoch.js";
import { type InitOptions, init } from "./commands/init.js";
+import { openProject, PANEL_NOT_READY } from "./commands/open.js";
import { sessionWrite } from "./commands/session.js";
import { CliError, type Io, processIo } from "./io.js";
export type IoFactory = (interactive: boolean) => Io;
+/** Test seams for effects that would leave this process (opening a browser). */
+export interface ProgramDeps {
+ launch?: (file: string) => Promise<boolean>;
+}
+
function retention(value: string): number | "keep" {
if (value === "keep") return value;
const days = Number(value);
@@ -16,7 +22,7 @@ function retention(value: string): number | "keep" {
return days;
}
-export function createProgram(makeIo: IoFactory = processIo): Command {
+export function createProgram(makeIo: IoFactory = processIo, deps: ProgramDeps = {}): Command {
const program = new Command()
.name("codelineage")
.description(pkg.description)
@@ -62,6 +68,25 @@ export function createProgram(makeIo: IoFactory = processIo): Command {
}),
);
+ program
+ .command("open")
+ .description("build and open a project map (the global panel arrives with Epic 3)")
+ .argument("[dir]", "project directory; omit to open the global panel")
+ .action(
+ run(async (dir?: string) => {
+ const io = makeIo(false);
+ if (dir === undefined) {
+ io.out(PANEL_NOT_READY);
+ return;
+ }
+ await openProject({
+ dir,
+ io,
+ ...(deps.launch === undefined ? {} : { launch: deps.launch }),
+ });
+ }),
+ );
+
const config = program.command("config").description("read or change global settings");
config
.command("get")
diff --git a/packages/cli/test/open.test.ts b/packages/cli/test/open.test.ts
new file mode 100644
index 0000000..6a78ca1
--- /dev/null
+++ b/packages/cli/test/open.test.ts
@@ -0,0 +1,96 @@
+import { EventEmitter } from "node:events";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { beforeEach, describe, expect, it } from "vitest";
+import { init } from "../src/commands/init.js";
+import { launchFile, openerCommand, openProject } from "../src/commands/open.js";
+import { projectPaths } from "../src/store/paths.js";
+import { DATA_ELEMENT_ID } from "../src/view/model.js";
+import { envFor, type FakeIo, fakeIo, tempDir } from "./helpers.js";
+
+const TEMPLATE = `<!doctype html><html><body><div id="root"></div>
+ <script id="${DATA_ELEMENT_ID}" type="application/json"></script></body></html>`;
+
+let dir: string;
+let root: string;
+let io: FakeIo;
+
+beforeEach(async () => {
+ dir = await tempDir();
+ root = join(dir, "proj");
+ await mkdir(root);
+ io = fakeIo(envFor(dir));
+ await init(root, { name: "proj", retention: "keep", language: "auto" }, fakeIo(envFor(dir)));
+});
+
+class FakeChild extends EventEmitter {
+ unref(): void {}
+}
+
+function fakeSpawn(
+ event: "spawn" | "error",
+ calls: string[][],
+): (command: string, args: string[]) => FakeChild {
+ return (command: string, args: string[]) => {
+ calls.push([command, ...args]);
+ const child = new FakeChild();
+ queueMicrotask(() => child.emit(event));
+ return child;
+ };
+}
+
+describe("openerCommand", () => {
+ it("picks the opener each platform ships with", () => {
+ expect(openerCommand("darwin", "/p/lineage.html")).toEqual({
+ command: "open",
+ args: ["/p/lineage.html"],
+ });
+ expect(openerCommand("win32", "/p/lineage.html")).toEqual({
+ command: "cmd",
+ args: ["/c", "start", "", "/p/lineage.html"],
+ });
+ expect(openerCommand("linux", "/p/lineage.html")).toEqual({
+ command: "xdg-open",
+ args: ["/p/lineage.html"],
+ });
+ });
+});
+
+describe("launchFile", () => {
+ it("resolves true once the opener starts", async () => {
+ const calls: string[][] = [];
+ expect(await launchFile("/p/lineage.html", fakeSpawn("spawn", calls))).toBe(true);
+ const { command } = openerCommand(process.platform, "/p/lineage.html");
+ expect(calls).toEqual([[command, "/p/lineage.html"]]);
+ });
+
+ it("resolves false when the opener binary is missing", async () => {
+ expect(await launchFile("/p/lineage.html", fakeSpawn("error", []))).toBe(false);
+ });
+});
+
+describe("openProject", () => {
+ it("builds the map and opens it with the OS opener", async () => {
+ const launched: string[] = [];
+ await openProject({
+ dir: root,
+ io,
+ templateHtml: TEMPLATE,
+ launch: async (file) => {
+ launched.push(file);
+ return true;
+ },
+ });
+ expect(launched).toEqual([projectPaths(root).html]);
+ expect(io.lines).toEqual([
+ `Wrote ${projectPaths(root).html}`,
+ `Opened ${projectPaths(root).html}`,
+ ]);
+ });
+
+ it("prints the path when no opener is available", async () => {
+ await openProject({ dir: root, io, templateHtml: TEMPLATE, launch: async () => false });
+ expect(io.lines.at(-1)).toBe(projectPaths(root).html);
+ expect(io.warnings).toEqual(["no application opener found; open the file manually"]);
+ });
+});
diff --git a/packages/cli/test/program-commands.test.ts b/packages/cli/test/program-commands.test.ts
index 45605d2..50309c7 100644
--- a/packages/cli/test/program-commands.test.ts
+++ b/packages/cli/test/program-commands.test.ts
@@ -10,6 +10,7 @@ let dir: string;
let root: string;
let io: FakeIo;
let interactive: boolean[];
+let launched: string[];
beforeEach(async () => {
dir = await tempDir();
@@ -17,14 +18,23 @@ beforeEach(async () => {
await mkdir(root);
io = fakeIo(envFor(dir));
interactive = [];
+ launched = [];
});
async function cli(...args: string[]): Promise<string> {
let err = "";
- const program = createProgram((i) => {
- interactive.push(i);
- return io;
- });
+ const program = createProgram(
+ (i) => {
+ interactive.push(i);
+ return io;
+ },
+ {
+ launch: async (file) => {
+ launched.push(file);
+ return true;
+ },
+ },
+ );
program.exitOverride().configureOutput({ writeErr: (s) => (err += s), writeOut: () => {} });
for (const c of program.commands)
c.exitOverride().configureOutput({ writeErr: (s) => (err += s) });
@@ -76,6 +86,17 @@ describe("commands through the CLI", () => {
expect(existsSync(join(root, ".codelineage", "lineage.html"))).toBe(true);
});
+ it("open builds then launches the map, and explains the missing panel", async () => {
+ await cli("init", root, "--yes", "--retention", "keep");
+ await cli("open", root);
+ expect(launched).toEqual([join(root, ".codelineage", "lineage.html")]);
+ expect(io.lines.at(-1)).toMatch(/^Opened .*lineage\.html$/);
+ expect(interactive).toEqual([false, false]);
+ await cli("open");
+ expect(launched).toHaveLength(1);
+ expect(io.lines.at(-1)).toMatch(/Epic 3/);
+ });
+
it("prints user errors as one line", async () => {
expect(await cli("config", "get", "nope")).toMatch(/^error: unknown key "nope"/);
});