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(panel): build global panel and open it without a directory

Erenfb5ef996ed87
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8fdc760..bf65329 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
+### Added
+- Global panel: `codelineage build` also refreshes `~/.config/codelineage/panel.html` (honouring `CODELINEAGE_HOME` / `XDG_CONFIG_HOME`) with one card per registered project — last activity, pending `needsUser` count, a `file://` link to its map, a "missing" mark when the directory is gone and read-only settings from `config.json`; `codelineage open` without a directory builds and opens it.
## [0.3.0] - 2026-10-21
### Added
diff --git a/packages/cli/src/commands/build.ts b/packages/cli/src/commands/build.ts
index 66a5851..15bdd4c 100644
--- a/packages/cli/src/commands/build.ts
+++ b/packages/cli/src/commands/build.ts
@@ -1,14 +1,12 @@
-import type { Dirent } from "node:fs";
-import { readdir } from "node:fs/promises";
import { resolve } from "node:path";
import { CliError, type Io } from "../io.js";
import { redactDeep } from "../redact.js";
-import type { Session } from "../schema/session.js";
import { atomicWrite } from "../store/fs.js";
import { projectPaths } from "../store/paths.js";
-import { loadProject, loadSession } from "../store/stores.js";
+import { loadAllSessions, loadProject } from "../store/stores.js";
import { buildViewModel, embedViewModel } from "../view/lineage.js";
import type { LineageViewModel } from "../view/model.js";
+import { buildPanel } from "../view/panel.js";
import { TEMPLATE_HTML } from "../view/template.js";
import { collectTranscriptIds } from "../view/transcripts.js";
@@ -21,38 +19,10 @@ export interface BuildOptions {
quiet?: boolean;
}
-async function listSessions(dir: string): Promise<string[]> {
- let entries: Dirent[];
- try {
- entries = await readdir(dir, { withFileTypes: true });
- } catch (err) {
- if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
- throw err;
- }
- return entries
- .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
- .map((entry) => entry.name.slice(0, -".json".length))
- .sort();
-}
-
-async function loadAllSessions(root: string, io: Io): Promise<Session[]> {
- const sessions: Session[] = [];
- for (const id of await listSessions(projectPaths(root).sessions)) {
- const loaded = await loadSession(root, id);
- if (!loaded.found) continue;
- if (!loaded.ok) {
- io.warn(`skipping session ${id}: ${loaded.error}`);
- continue;
- }
- for (const warning of loaded.warnings) io.warn(`session ${id}: ${warning}`);
- sessions.push(loaded.data);
- }
- return sessions;
-}
-
/**
- * Rebuilds `.codelineage/lineage.html` from `project.json` and every session file.
- * One unreadable session is a warning, never a failed build.
+ * Rebuilds `.codelineage/lineage.html` from `project.json` and every session file,
+ * then refreshes the global panel. One unreadable session is a warning, never a
+ * failed build; an unwritable global directory only skips the panel.
*/
export async function buildProject(opts: BuildOptions): Promise<LineageViewModel> {
const { io } = opts;
@@ -66,7 +36,7 @@ export async function buildProject(opts: BuildOptions): Promise<LineageViewModel
const paths = projectPaths(root);
const model = buildViewModel({
project: project.data,
- sessions: await loadAllSessions(root, io),
+ sessions: await loadAllSessions(root, io.warn),
path: root,
generatedAt: io.now(),
transcripts: await collectTranscriptIds(io.env),
@@ -78,5 +48,13 @@ export async function buildProject(opts: BuildOptions): Promise<LineageViewModel
const template = opts.templateHtml ?? TEMPLATE_HTML;
await atomicWrite(paths.html, embedViewModel(template, redacted.value));
if (!opts.quiet) io.out(`Wrote ${paths.html}`);
+
+ // The panel is derived state: a read-only home or a broken registry warning
+ // must never turn a successful map build into a failure.
+ try {
+ await buildPanel({ env: io.env, io, templateHtml: template });
+ } catch (err) {
+ io.warn(`could not build panel.html: ${(err as Error).message}`);
+ }
return redacted.value;
}
diff --git a/packages/cli/src/commands/open.ts b/packages/cli/src/commands/open.ts
index 2527c95..1b954ee 100644
--- a/packages/cli/src/commands/open.ts
+++ b/packages/cli/src/commands/open.ts
@@ -1,14 +1,11 @@
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 { globalPaths, projectPaths } from "../store/paths.js";
+import { buildPanel } from "../view/panel.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;
@@ -16,6 +13,10 @@ export interface OpenOptions {
launch?: (file: string) => Promise<boolean>;
}
+export interface OpenProjectOptions extends OpenOptions {
+ dir: string;
+}
+
export interface OpenerCommand {
command: string;
args: string[];
@@ -52,8 +53,20 @@ export function launchFile(file: string, spawnFn: SpawnLike = systemSpawn): Prom
});
}
+/** Hands a built page to the OS opener, or prints its path when none exists. */
+async function openFile(file: string, opts: OpenOptions): Promise<void> {
+ const { io } = opts;
+ const opened = await (opts.launch ?? launchFile)(file);
+ if (opened) {
+ io.out(`Opened ${file}`);
+ return;
+ }
+ io.out(file);
+ io.warn("no application opener found; open the file manually");
+}
+
/** Rebuilds the map, then hands `lineage.html` to the OS opener. */
-export async function openProject(opts: OpenOptions): Promise<void> {
+export async function openProject(opts: OpenProjectOptions): Promise<void> {
const { io } = opts;
const root = resolve(opts.dir);
await buildProject({
@@ -61,12 +74,15 @@ export async function openProject(opts: OpenOptions): Promise<void> {
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");
+ await openFile(projectPaths(root).html, opts);
+}
+
+/** Rebuilds the global panel, then hands `panel.html` to the OS opener. */
+export async function openPanel(opts: OpenOptions): Promise<void> {
+ await buildPanel({
+ env: opts.io.env,
+ io: opts.io,
+ ...(opts.templateHtml === undefined ? {} : { templateHtml: opts.templateHtml }),
+ });
+ await openFile(globalPaths(opts.io.env).panel, opts);
}
diff --git a/packages/cli/src/program.ts b/packages/cli/src/program.ts
index a131c02..c386212 100644
--- a/packages/cli/src/program.ts
+++ b/packages/cli/src/program.ts
@@ -4,7 +4,7 @@ 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 { openPanel, openProject } from "./commands/open.js";
import { sessionWrite } from "./commands/session.js";
import { CliError, type Io, processIo } from "./io.js";
@@ -70,20 +70,17 @@ export function createProgram(makeIo: IoFactory = processIo, deps: ProgramDeps =
program
.command("open")
- .description("build and open a project map (the global panel arrives with Epic 3)")
+ .description("build and open a project map, or the global panel without a directory")
.argument("[dir]", "project directory; omit to open the global panel")
.action(
run(async (dir?: string) => {
const io = makeIo(false);
+ const launch = deps.launch === undefined ? {} : { launch: deps.launch };
if (dir === undefined) {
- io.out(PANEL_NOT_READY);
+ await openPanel({ io, ...launch });
return;
}
- await openProject({
- dir,
- io,
- ...(deps.launch === undefined ? {} : { launch: deps.launch }),
- });
+ await openProject({ dir, io, ...launch });
}),
);
diff --git a/packages/cli/src/schema/config.ts b/packages/cli/src/schema/config.ts
index 6b40e99..be86ec9 100644
--- a/packages/cli/src/schema/config.ts
+++ b/packages/cli/src/schema/config.ts
@@ -26,4 +26,5 @@ export const Registry = z.object({
});
export type Config = z.infer<typeof Config>;
+export type RegistryEntry = z.infer<typeof RegistryEntry>;
export type Registry = z.infer<typeof Registry>;
diff --git a/packages/cli/src/store/stores.ts b/packages/cli/src/store/stores.ts
index b7e1cc6..3df6f73 100644
--- a/packages/cli/src/store/stores.ts
+++ b/packages/cli/src/store/stores.ts
@@ -1,3 +1,5 @@
+import type { Dirent } from "node:fs";
+import { readdir } from "node:fs/promises";
import type { z } from "zod";
import { CONFIG_SCHEMA, Config, Registry } from "../schema/config.js";
import { PROJECT_SCHEMA, Project } from "../schema/project.js";
@@ -60,6 +62,43 @@ export const updateProject = (
export const loadSession = (root: string, id: string) =>
load(projectPaths(root).session(id), Session, SESSION_SCHEMA);
+/** Ids of the `.json` files in the project's sessions directory, sorted. */
+export async function listSessionIds(dir: string): Promise<string[]> {
+ let entries: Dirent[];
+ try {
+ entries = await readdir(dir, { withFileTypes: true });
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+ throw err;
+ }
+ return entries
+ .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+ .map((entry) => entry.name.slice(0, -".json".length))
+ .sort();
+}
+
+/**
+ * Loads every valid session of a project. One unreadable or newer file is a
+ * warning, never a failure for the whole map or panel.
+ */
+export async function loadAllSessions(
+ root: string,
+ warn: (line: string) => void,
+): Promise<Session[]> {
+ const sessions: Session[] = [];
+ for (const id of await listSessionIds(projectPaths(root).sessions)) {
+ const loaded = await loadSession(root, id);
+ if (!loaded.found) continue;
+ if (!loaded.ok) {
+ warn(`skipping session ${id}: ${loaded.error}`);
+ continue;
+ }
+ for (const warning of loaded.warnings) warn(`session ${id}: ${warning}`);
+ sessions.push(loaded.data);
+ }
+ return sessions;
+}
+
export const updateSession = (
root: string,
id: string,
diff --git a/packages/cli/src/view/lineage.ts b/packages/cli/src/view/lineage.ts
index 72d6998..f91dcac 100644
--- a/packages/cli/src/view/lineage.ts
+++ b/packages/cli/src/view/lineage.ts
@@ -3,6 +3,7 @@ import type { LineageNode, Session } from "../schema/session.js";
import {
DATA_ELEMENT_ID,
type LineageViewModel,
+ type PageModel,
type StatusCard,
VIEW_SCHEMA,
type ViewEpoch,
@@ -188,7 +189,7 @@ export function escapeForScript(json: string): string {
}
/** Fills the template's empty data element with the serialized model. */
-export function embedViewModel(template: string, model: LineageViewModel): string {
+export function embedViewModel(template: string, model: PageModel): string {
if (!template.includes(EMPTY_DATA_ELEMENT)) {
throw new Error(`the template has no empty <script id="${DATA_ELEMENT_ID}"> element`);
}
diff --git a/packages/cli/src/view/model.ts b/packages/cli/src/view/model.ts
index ca5d6b1..fa8a438 100644
--- a/packages/cli/src/view/model.ts
+++ b/packages/cli/src/view/model.ts
@@ -75,3 +75,38 @@ export interface LineageViewModel {
/** Sessions with no epoch, or with an epoch that no longer exists. */
unassigned: ViewSession[];
}
+
+/** One project card in the global panel. */
+export interface PanelProject {
+ name: string;
+ path: string;
+ /** True when the registered directory no longer exists. */
+ missing: boolean;
+ /** `updatedAt` of the project's most recently updated session. */
+ lastActivity: string | null;
+ /** Pending items flagged `needsUser` after merging active sessions. */
+ needsUserCount: number;
+ /** `file://` URL of the project's map; null when the directory is gone. */
+ lineageUrl: string | null;
+}
+
+/** Global settings, shown read-only on the panel. */
+export interface PanelSettings {
+ language: string;
+ updateEveryTurns: number;
+ sessionEndCatchUp: boolean;
+ gitPolicy: "ignore" | "commit";
+ agents: string[];
+}
+
+export interface PanelViewModel {
+ kind: "panel";
+ schema: typeof VIEW_SCHEMA;
+ generatedAt: string;
+ settings: PanelSettings;
+ /** Registry order. */
+ projects: PanelProject[];
+}
+
+/** Either page the template can render; the embedded data decides which. */
+export type PageModel = LineageViewModel | PanelViewModel;
diff --git a/packages/cli/src/view/panel.ts b/packages/cli/src/view/panel.ts
new file mode 100644
index 0000000..fdffa8a
--- /dev/null
+++ b/packages/cli/src/view/panel.ts
@@ -0,0 +1,118 @@
+import { stat } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import type { Io } from "../io.js";
+import { redactDeep } from "../redact.js";
+import type { RegistryEntry } from "../schema/config.js";
+import { atomicWrite } from "../store/fs.js";
+import { globalPaths, projectPaths } from "../store/paths.js";
+import { loadAllSessions, loadConfig, loadRegistry } from "../store/stores.js";
+import { embedViewModel, statusCard } from "./lineage.js";
+import { type PanelProject, type PanelViewModel, VIEW_SCHEMA } from "./model.js";
+import { TEMPLATE_HTML } from "./template.js";
+
+export interface PanelOptions {
+ env: NodeJS.ProcessEnv;
+ io: Io;
+ /** Replaces the bundled template; tests inject a minimal page. */
+ templateHtml?: string;
+}
+
+const PANEL_TITLE = "<title>codelineage — panel</title>";
+
+async function isDirectory(path: string): Promise<boolean> {
+ try {
+ return (await stat(path)).isDirectory();
+ } catch {
+ return false;
+ }
+}
+
+/**
+ * One card per registry entry. A directory that is gone is marked missing
+ * instead of failing the panel; one unreadable project is a warning.
+ */
+export async function collectPanelProjects(
+ entries: RegistryEntry[],
+ generatedAt: string,
+ warn: (line: string) => void,
+): Promise<PanelProject[]> {
+ const projects: PanelProject[] = [];
+ for (const entry of entries) {
+ if (!(await isDirectory(entry.path))) {
+ projects.push({
+ name: entry.name,
+ path: entry.path,
+ missing: true,
+ lastActivity: null,
+ needsUserCount: 0,
+ lineageUrl: null,
+ });
+ continue;
+ }
+ try {
+ const card = statusCard(await loadAllSessions(entry.path, warn), generatedAt);
+ projects.push({
+ name: entry.name,
+ path: entry.path,
+ missing: false,
+ lastActivity: card.lastActivity,
+ needsUserCount: card.pending.filter((item) => item.needsUser).length,
+ lineageUrl: pathToFileURL(projectPaths(entry.path).html).href,
+ });
+ } catch (err) {
+ warn(`skipping project ${entry.path}: ${(err as Error).message}`);
+ projects.push({
+ name: entry.name,
+ path: entry.path,
+ missing: false,
+ lastActivity: null,
+ needsUserCount: 0,
+ lineageUrl: pathToFileURL(projectPaths(entry.path).html).href,
+ });
+ }
+ }
+ return projects;
+}
+
+/**
+ * Builds the global panel from `projects.json` and `config.json` and writes it
+ * next to them. The caller decides whether an unwritable global directory is a
+ * warning (`build`) or an error (`open` without a directory).
+ */
+export async function buildPanel(opts: PanelOptions): Promise<PanelViewModel> {
+ const { io } = opts;
+ const generatedAt = io.now();
+ const [config, registry] = await Promise.all([loadConfig(opts.env), loadRegistry(opts.env)]);
+ if (registry.found && !registry.ok) {
+ io.warn(`registry: ${registry.error}; showing no projects`);
+ } else if (registry.found) {
+ for (const warning of registry.warnings) io.warn(warning);
+ }
+ const entries = registry.found && registry.ok ? registry.data.projects : [];
+
+ const model: PanelViewModel = {
+ kind: "panel",
+ schema: VIEW_SCHEMA,
+ generatedAt,
+ settings: {
+ language: config.language,
+ updateEveryTurns: config.updateEveryTurns,
+ sessionEndCatchUp: config.sessionEndCatchUp,
+ gitPolicy: config.gitPolicy,
+ agents: config.agents,
+ },
+ projects: await collectPanelProjects(entries, generatedAt, io.warn),
+ };
+
+ // Same safety net as the map: nothing leaves this process unredacted.
+ const redacted = redactDeep(model);
+ if (redacted.count > 0)
+ io.warn(`redacted ${redacted.count} secret-looking value(s) in the panel`);
+
+ const template = (opts.templateHtml ?? TEMPLATE_HTML).replace(
+ /<title>[^<]*<\/title>/,
+ PANEL_TITLE,
+ );
+ await atomicWrite(globalPaths(opts.env).panel, embedViewModel(template, redacted.value));
+ return redacted.value;
+}
diff --git a/packages/cli/test/open.test.ts b/packages/cli/test/open.test.ts
index 6a78ca1..77cbe60 100644
--- a/packages/cli/test/open.test.ts
+++ b/packages/cli/test/open.test.ts
@@ -3,8 +3,8 @@ 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 { launchFile, openerCommand, openPanel, openProject } from "../src/commands/open.js";
+import { globalPaths, projectPaths } from "../src/store/paths.js";
import { DATA_ELEMENT_ID } from "../src/view/model.js";
import { envFor, type FakeIo, fakeIo, tempDir } from "./helpers.js";
@@ -94,3 +94,25 @@ describe("openProject", () => {
expect(io.warnings).toEqual(["no application opener found; open the file manually"]);
});
});
+
+describe("openPanel", () => {
+ it("builds the panel and opens it with the OS opener", async () => {
+ const launched: string[] = [];
+ await openPanel({
+ io,
+ templateHtml: TEMPLATE,
+ launch: async (file) => {
+ launched.push(file);
+ return true;
+ },
+ });
+ expect(launched).toEqual([globalPaths(io.env).panel]);
+ expect(io.lines).toEqual([`Opened ${globalPaths(io.env).panel}`]);
+ });
+
+ it("prints the panel path when no opener is available", async () => {
+ await openPanel({ io, templateHtml: TEMPLATE, launch: async () => false });
+ expect(io.lines.at(-1)).toBe(globalPaths(io.env).panel);
+ expect(io.warnings).toEqual(["no application opener found; open the file manually"]);
+ });
+});
diff --git a/packages/cli/test/panel.test.ts b/packages/cli/test/panel.test.ts
new file mode 100644
index 0000000..7891854
--- /dev/null
+++ b/packages/cli/test/panel.test.ts
@@ -0,0 +1,193 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { beforeEach, describe, expect, it } from "vitest";
+import { buildProject } from "../src/commands/build.js";
+import { configSet } from "../src/commands/config.js";
+import { init } from "../src/commands/init.js";
+import { sessionWrite } from "../src/commands/session.js";
+import { globalPaths, projectPaths } from "../src/store/paths.js";
+import { DATA_ELEMENT_ID, type PanelViewModel } from "../src/view/model.js";
+import { buildPanel } from "../src/view/panel.js";
+import { envFor, fakeIo, T0, tempDir } from "./helpers.js";
+
+const TEMPLATE = `<!doctype html><html><head><title>codelineage — lineage</title></head><body>
+ <div id="root"></div>
+ <script id="${DATA_ELEMENT_ID}" type="application/json"></script></body></html>`;
+
+const DATA_PREFIX = `<script id="${DATA_ELEMENT_ID}" type="application/json">`;
+
+function embedded(html: string): unknown {
+ const start = html.indexOf(DATA_PREFIX);
+ expect(start).toBeGreaterThanOrEqual(0);
+ const end = html.indexOf("</script>", start);
+ return JSON.parse(html.slice(start + DATA_PREFIX.length, end));
+}
+
+async function write(file: string, data: string): Promise<void> {
+ await mkdir(dirname(file), { recursive: true });
+ await writeFile(file, data);
+}
+
+/** init names the project after its directory when `--name` is not given. */
+async function initProject(root: string, env: NodeJS.ProcessEnv): Promise<void> {
+ await mkdir(root, { recursive: true });
+ await init(root, { retention: "keep", language: "auto" }, fakeIo(env));
+}
+
+let dir: string;
+let env: NodeJS.ProcessEnv;
+
+beforeEach(async () => {
+ dir = await tempDir();
+ env = envFor(dir);
+});
+
+describe("buildPanel", () => {
+ it("writes a card per project, marks a deleted directory missing and shows settings", async () => {
+ const alpha = join(dir, "alpha");
+ const beta = join(dir, "beta");
+ await initProject(alpha, env);
+ await initProject(beta, env);
+ // init names the project after its directory, which is what the panel shows.
+ await writeFile(
+ projectPaths(alpha).session("s1"),
+ JSON.stringify({
+ schema: 1,
+ sessionId: "s1",
+ startedAt: T0,
+ updatedAt: T0,
+ status: {
+ goal: "",
+ done: [],
+ pending: [
+ { text: "decide", needsUser: true },
+ { text: "later", needsUser: false },
+ ],
+ next: "",
+ },
+ nodes: [],
+ }),
+ );
+ await rm(beta, { recursive: true });
+
+ const io = fakeIo(env);
+ await configSet("updateEveryTurns", "7", io);
+ const model = await buildPanel({ env, io, templateHtml: TEMPLATE });
+
+ expect(model).toEqual({
+ kind: "panel",
+ schema: 1,
+ generatedAt: T0,
+ settings: {
+ language: "auto",
+ updateEveryTurns: 7,
+ sessionEndCatchUp: true,
+ gitPolicy: "ignore",
+ agents: ["claude-code"],
+ },
+ projects: [
+ {
+ name: "alpha",
+ path: alpha,
+ missing: false,
+ lastActivity: T0,
+ needsUserCount: 1,
+ lineageUrl: pathToFileURL(projectPaths(alpha).html).href,
+ },
+ {
+ name: "beta",
+ path: beta,
+ missing: true,
+ lastActivity: null,
+ needsUserCount: 0,
+ lineageUrl: null,
+ },
+ ],
+ });
+
+ const html = await readFile(globalPaths(env).panel, "utf8");
+ expect(html).toContain("<title>codelineage — panel</title>");
+ expect(embedded(html)).toEqual(model);
+ });
+
+ it("shows no projects for an unreadable registry and warns instead of failing", async () => {
+ await write(globalPaths(env).registry, "{nope");
+ const io = fakeIo(env);
+ const model = await buildPanel({ env, io, templateHtml: TEMPLATE });
+ expect(model.projects).toEqual([]);
+ expect(io.warnings).toEqual([expect.stringMatching(/^registry: invalid JSON/)]);
+ });
+
+ it("skips a project whose sessions path is unreadable but keeps its card", async () => {
+ const root = join(dir, "broken");
+ await mkdir(root, { recursive: true });
+ await write(projectPaths(root).sessions, "not a directory");
+ await write(
+ globalPaths(env).registry,
+ JSON.stringify({ schema: 1, projects: [{ path: root, name: "broken", addedAt: T0 }] }),
+ );
+
+ const io = fakeIo(env);
+ const model = await buildPanel({ env, io, templateHtml: TEMPLATE });
+ expect(model.projects).toEqual([
+ {
+ name: "broken",
+ path: root,
+ missing: false,
+ lastActivity: null,
+ needsUserCount: 0,
+ lineageUrl: pathToFileURL(projectPaths(root).html).href,
+ },
+ ]);
+ expect(io.warnings.join("\n")).toMatch(/^skipping project .*ENOTDIR/);
+ });
+
+ it("redacts a secret-shaped project name before writing the panel", async () => {
+ const root = join(dir, "proj");
+ await mkdir(root, { recursive: true });
+ const secret = "token ghp_abcdefghijklmnopqrstuvwxyz0123456789";
+ await write(
+ globalPaths(env).registry,
+ JSON.stringify({ schema: 1, projects: [{ path: root, name: secret, addedAt: T0 }] }),
+ );
+
+ const io = fakeIo(env);
+ const model = await buildPanel({ env, io, templateHtml: TEMPLATE });
+ expect(model.projects[0]?.name).toBe("token [REDACTED]");
+ expect(io.warnings).toContain("redacted 1 secret-looking value(s) in the panel");
+ });
+});
+
+describe("panel refresh from build", () => {
+ it("refreshes the panel after a project build and after a session write", async () => {
+ const root = join(dir, "proj");
+ await initProject(root, env);
+ await buildProject({ dir: root, io: fakeIo(env), templateHtml: TEMPLATE });
+
+ const afterBuild = embedded(await readFile(globalPaths(env).panel, "utf8")) as PanelViewModel;
+ expect(afterBuild.kind).toBe("panel");
+ expect(afterBuild.projects).toEqual([
+ expect.objectContaining({ name: "proj", path: root, missing: false }),
+ ]);
+
+ const io = fakeIo(env);
+ await sessionWrite({ dir: root }, io, async () => JSON.stringify({ sessionId: "s1" }));
+ const afterWrite = embedded(await readFile(globalPaths(env).panel, "utf8")) as PanelViewModel;
+ expect(afterWrite.projects[0]?.lastActivity).toBe(T0);
+ });
+
+ it("turns an unwritable global directory into a warning, not a failed build", async () => {
+ const home = join(dir, "home-file");
+ await writeFile(home, "not a directory");
+ const badEnv = { ...env, CODELINEAGE_HOME: home };
+ const root = join(dir, "proj");
+ await initProject(root, badEnv);
+
+ const io = fakeIo(badEnv);
+ await buildProject({ dir: root, io, templateHtml: TEMPLATE });
+ expect(existsSync(projectPaths(root).html)).toBe(true);
+ expect(io.warnings.join("\n")).toMatch(/could not build panel\.html/);
+ });
+});
diff --git a/packages/cli/test/program-commands.test.ts b/packages/cli/test/program-commands.test.ts
index 50309c7..e719e33 100644
--- a/packages/cli/test/program-commands.test.ts
+++ b/packages/cli/test/program-commands.test.ts
@@ -3,6 +3,7 @@ import { mkdir, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { beforeEach, describe, expect, it } from "vitest";
import { createProgram } from "../src/program.js";
+import { globalPaths } from "../src/store/paths.js";
import { loadConfig, loadProject } from "../src/store/stores.js";
import { envFor, type FakeIo, fakeIo, tempDir } from "./helpers.js";
@@ -86,15 +87,16 @@ 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 () => {
+ it("open builds then launches the map, and the panel without a directory", 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/);
+ expect(launched).toHaveLength(2);
+ expect(launched.at(-1)).toBe(globalPaths(io.env).panel);
+ expect(io.lines.at(-1)).toMatch(/^Opened .*panel\.html$/);
});
it("prints user errors as one line", async () => {
diff --git a/packages/template/src/Panel.tsx b/packages/template/src/Panel.tsx
new file mode 100644
index 0000000..94c3c0c
--- /dev/null
+++ b/packages/template/src/Panel.tsx
@@ -0,0 +1,79 @@
+import type { PanelSettings, PanelViewModel } from "../../cli/src/view/model.js";
+import { formatTime } from "./format.js";
+
+const SETTING_LABELS: [keyof PanelSettings, string][] = [
+ ["language", "Language"],
+ ["updateEveryTurns", "Update every turns"],
+ ["sessionEndCatchUp", "Catch up on session end"],
+ ["gitPolicy", "Git policy"],
+ ["agents", "Agents"],
+];
+
+function settingText(value: PanelSettings[keyof PanelSettings]): string {
+ if (Array.isArray(value)) return value.length > 0 ? value.join(", ") : "—";
+ if (typeof value === "boolean") return value ? "yes" : "no";
+ return String(value);
+}
+
+export function Panel({ model }: { model: PanelViewModel }) {
+ return (
+ <main>
+ <header className="project">
+ <div>
+ <h1>Projects</h1>
+ <p className="muted">Every project codelineage knows about.</p>
+ </div>
+ <div className="meta">
+ <span>
+ {model.projects.length} {model.projects.length === 1 ? "project" : "projects"}
+ </span>
+ <span className="muted">generated {formatTime(model.generatedAt)}</span>
+ </div>
+ </header>
+
+ {model.projects.length === 0 ? (
+ <p className="empty">No projects registered yet. Run `codelineage init` in a project.</p>
+ ) : (
+ <ul className="panel-grid">
+ {model.projects.map((project) => (
+ <li key={project.path} className={project.missing ? "card missing" : "card"}>
+ <div className="card-head">
+ <h2>{project.name}</h2>
+ {project.missing ? <span className="badge">missing</span> : null}
+ </div>
+ <p className="muted path">{project.path}</p>
+ <dl className="card-facts">
+ <div>
+ <dt>Last activity</dt>
+ <dd>{formatTime(project.lastActivity)}</dd>
+ </div>
+ <div>
+ <dt>Waiting on you</dt>
+ <dd>{project.needsUserCount}</dd>
+ </div>
+ </dl>
+ {project.lineageUrl ? (
+ <a href={project.lineageUrl}>Open the map →</a>
+ ) : (
+ <p className="empty">Directory not found.</p>
+ )}
+ </li>
+ ))}
+ </ul>
+ )}
+
+ <section className="settings" aria-label="Settings">
+ <h2>Settings</h2>
+ <p className="muted">Read-only; change them with `codelineage config set`.</p>
+ <dl>
+ {SETTING_LABELS.map(([key, label]) => (
+ <div key={key}>
+ <dt>{label}</dt>
+ <dd>{settingText(model.settings[key])}</dd>
+ </div>
+ ))}
+ </dl>
+ </section>
+ </main>
+ );
+}
diff --git a/packages/template/src/data.ts b/packages/template/src/data.ts
index 1213023..b221e65 100644
--- a/packages/template/src/data.ts
+++ b/packages/template/src/data.ts
@@ -1,6 +1,6 @@
-import { DATA_ELEMENT_ID, type LineageViewModel } from "../../cli/src/view/model.js";
+import { DATA_ELEMENT_ID, type PageModel } from "../../cli/src/view/model.js";
-function parse(text: string): LineageViewModel {
+function parse(text: string): PageModel {
let value: unknown;
try {
value = JSON.parse(text);
@@ -10,17 +10,17 @@ function parse(text: string): LineageViewModel {
if (typeof value !== "object" || value === null || !("kind" in value)) {
throw new Error("The embedded codelineage data is not a view model.");
}
- if (value.kind !== "lineage") {
+ if (value.kind !== "lineage" && value.kind !== "panel") {
throw new Error(`Unsupported codelineage view: ${String(value.kind)}`);
}
- return value as LineageViewModel;
+ return value as PageModel;
}
/**
* Reads the JSON contract from the page. Dev mode falls back to the fixture;
* production builds always embed the data, so a missing element is a real error.
*/
-export async function loadViewModel(doc: Document = document): Promise<LineageViewModel> {
+export async function loadViewModel(doc: Document = document): Promise<PageModel> {
const raw = doc.getElementById(DATA_ELEMENT_ID)?.textContent?.trim();
if (raw) return parse(raw);
if (import.meta.env.DEV) {
diff --git a/packages/template/src/main.tsx b/packages/template/src/main.tsx
index b32c9e4..8950210 100644
--- a/packages/template/src/main.tsx
+++ b/packages/template/src/main.tsx
@@ -2,6 +2,7 @@ import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { App } from "./App.js";
import { loadViewModel } from "./data.js";
+import { Panel } from "./Panel.js";
import "./styles.css";
const root = document.getElementById("root");
@@ -11,7 +12,7 @@ loadViewModel()
.then((model) => {
createRoot(root).render(
<StrictMode>
- <App model={model} />
+ {model.kind === "lineage" ? <App model={model} /> : <Panel model={model} />}
</StrictMode>,
);
})
diff --git a/packages/template/src/styles.css b/packages/template/src/styles.css
index d6a735b..ec78e33 100644
--- a/packages/template/src/styles.css
+++ b/packages/template/src/styles.css
@@ -594,6 +594,92 @@ time {
font-size: 12px;
}
+/* Global panel: one card per registered project. */
+.panel-grid {
+ display: grid;
+ grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
+ gap: 16px;
+ margin: 24px 0 32px;
+ padding: 0;
+ list-style: none;
+}
+
+.card {
+ display: flex;
+ flex-direction: column;
+ gap: 8px;
+ padding: 16px;
+ background: var(--panel);
+ border: 1px solid var(--line);
+ border-radius: 10px;
+}
+
+.card.missing {
+ border-color: var(--warn);
+}
+
+.card-head {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+}
+
+.card-head h2 {
+ font-size: 17px;
+}
+
+.card .path {
+ overflow-wrap: anywhere;
+}
+
+.card-facts,
+.settings dl {
+ display: grid;
+ gap: 4px;
+ margin: 0;
+}
+
+.card-facts div,
+.settings dl div {
+ display: flex;
+ justify-content: space-between;
+ gap: 12px;
+}
+
+.card-facts dt,
+.settings dt {
+ color: var(--muted);
+ font-size: 13px;
+}
+
+.card-facts dd,
+.settings dd {
+ margin: 0;
+ font-size: 13px;
+}
+
+.card a {
+ color: var(--accent);
+}
+
+.settings {
+ padding: 16px;
+ background: var(--panel);
+ border: 1px solid var(--line);
+ border-radius: 10px;
+}
+
+.settings h2 {
+ font-size: 12px;
+ text-transform: uppercase;
+ letter-spacing: 0.08em;
+ color: var(--muted);
+}
+
+.settings dl {
+ margin-top: 10px;
+}
+
@media (max-width: 720px) {
.status {
grid-template-columns: 1fr;