Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.
JavaScript ai-codingclaudeclaude-codeclaude-code-pluginclicoding-agentsdeveloper-toolsgitllmtypescript
feat(cli): add open command with OS opener
Eren349db6558c1d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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"/);});