Use show for chapter imports

Author: dastratakos

README.md

@@ -26,6 +26,12 @@ In your AI agent, run:
 
 This breaks your branch's diff into reviewable "chapters".
 
+To open a generated chapters file directly:
+
+```bash
+stage-cli show path/to/chapters.json
+```
+
 ## What it does
 
 - Splits a local git branch diff into logical review chapters

src/__tests__/ingest.test.ts src/__tests__/import-chapters.test.tssrc/__tests__/ingest.test.ts renamed to src/__tests__/import-chapters.test.ts

@@ -2,16 +2,16 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { ingest, insertChaptersFile } from "../commands/ingest.js";
 import { closeDb, getDb } from "../db/client.js";
 import { chapter, chapterRun, keyChange } from "../db/schema/index.js";
+import { importChaptersFile, insertChaptersFile } from "../runs/import-chapters.js";
 import { makeFixture } from "./fixtures.js";
 
 let tmpDir: string;
 let dbPath: string;
 
 beforeEach(async () => {
-  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "stage-cli-ingest-"));
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "stage-cli-import-"));
   dbPath = path.join(tmpDir, "db.sqlite");
   closeDb();
 });
@@ -21,14 +21,14 @@ afterEach(async () => {
   await fs.rm(tmpDir, { recursive: true, force: true });
 });
 
-describe("ingest", () => {
+describe("chapter import", () => {
   it("inserts a run, chapters, and key_changes atomically and returns the runId", async () => {
     const db = getDb({ dbPath });
     const fixture = makeFixture();
     const fixturePath = path.join(tmpDir, "chapters.json");
     await fs.writeFile(fixturePath, JSON.stringify(fixture));
 
-    const result = ingest(fixturePath, db);
+    const result = importChaptersFile(fixturePath, db);
 
     expect(result.runId).toMatch(/^[0-9a-f-]{36}$/);
     expect(result.chapterCount).toBe(1);
@@ -56,7 +56,7 @@ describe("ingest", () => {
     ]);
   });
 
-  it("creates a new run on re-ingest of identical content (history preserved)", () => {
+  it("creates a new run when importing identical content again (history preserved)", () => {
     const db = getDb({ dbPath });
     const fixture = makeFixture();
 
@@ -68,7 +68,7 @@ describe("ingest", () => {
     expect(db.select().from(chapter).all()).toHaveLength(2);
   });
 
-  it("derives stable externalIds for key_changes across re-ingests of the same scope", () => {
+  it("derives stable externalIds for key_changes across repeated imports of the same scope", () => {
     const db = getDb({ dbPath });
     const fixture = makeFixture();
 
@@ -80,7 +80,7 @@ describe("ingest", () => {
     expect(all[0]?.externalId).toBe(all[1]?.externalId);
   });
 
-  it("derives stable chapter externalIds across re-ingests of the same scope", () => {
+  it("derives stable chapter externalIds across repeated imports of the same scope", () => {
     const db = getDb({ dbPath });
     insertChaptersFile(db, makeFixture(), "/repo");
     insertChaptersFile(db, makeFixture(), "/repo");
@@ -165,7 +165,7 @@ describe("ingest", () => {
       }),
     );
 
-    expect(() => ingest(bad, db)).toThrow();
+    expect(() => importChaptersFile(bad, db)).toThrow();
     expect(db.select().from(chapterRun).all()).toHaveLength(0);
     expect(db.select().from(chapter).all()).toHaveLength(0);
   });

src/__tests__/runs.routes.test.ts

@@ -3,9 +3,9 @@ import http from "node:http";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { insertChaptersFile } from "../commands/ingest.js";
 import { closeDb, getDb } from "../db/client.js";
 import { runRoutes } from "../routes/runs.js";
+import { insertChaptersFile } from "../runs/import-chapters.js";
 import { LOOPBACK_HOST, type ServerHandle, startServer } from "../server.js";
 import { makeFixture } from "./fixtures.js";
 

src/index.ts

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { ingest } from "./commands/ingest.js";
 import { show } from "./show.js";
 
 const program = new Command();
@@ -9,19 +8,10 @@ program.name("stage-cli").description("Chapter-style code review against your lo
 
 program
   .command("show")
-  .description("Serve the Stage CLI SPA in a local browser")
-  .argument("[runId]", "Run ID to show (defaults to the latest run)")
-  .action(async (runId?: string) => {
-    await show(runId);
-  });
-
-program
-  .command("ingest")
-  .description("Load a chapters.json file into the local SQLite store")
-  .argument("<path>", "Path to a chapters.json file produced by the agent")
-  .action((jsonPath: string) => {
-    const { runId } = ingest(jsonPath);
-    process.stdout.write(`${runId}\n`);
+  .description("Load a chapters.json file and open it in a local browser")
+  .argument("[path]", "Path to a chapters.json file (defaults to the latest run)")
+  .action(async (jsonPath?: string) => {
+    await show(jsonPath);
   });
 
 program.parseAsync(process.argv).catch((err) => {

src/routes/runs.ts

@@ -46,8 +46,6 @@ export function runRoutes(db: StageDb): Route[] {
           .all();
 
         const chapterIds = chapters.map((c) => c.id);
-        // No `orderBy` — mirrors hosted stage's relations query, which surfaces key_changes
-        // in natural query order. Both DBs return rows in insertion order in practice.
         const keyChanges =
           chapterIds.length > 0
             ? db.select().from(keyChange).where(inArray(keyChange.chapterId, chapterIds)).all()

src/commands/ingest.ts src/runs/import-chapters.tssrc/commands/ingest.ts renamed to src/runs/import-chapters.ts

@@ -6,13 +6,16 @@ import { getRepoRoot } from "../db/path.js";
 import { chapter, chapterRun, keyChange } from "../db/schema/index.js";
 import { type ChaptersFile, ChaptersFileSchema, SCOPE_KIND, type Scope } from "../schema.js";
 
-export interface IngestResult {
+export interface ImportChaptersResult {
   runId: string;
   chapterCount: number;
   keyChangeCount: number;
 }
 
-export function ingest(jsonPath: string, db: StageDb = getDb()): IngestResult {
+export function importChaptersFile(
+  jsonPath: string,
+  db: StageDb = getDb(),
+): ImportChaptersResult {
   const absolute = path.resolve(jsonPath);
   const raw = readFileSync(absolute, "utf8");
   const parsed = JSON.parse(raw) as unknown;
@@ -24,7 +27,7 @@ export function insertChaptersFile(
   db: StageDb,
   file: ChaptersFile,
   repoRoot: string,
-): IngestResult {
+): ImportChaptersResult {
   return db.transaction((tx) => {
     const [runRow] = tx
       .insert(chapterRun)

src/show.ts

@@ -3,10 +3,12 @@ import open from "open";
 import { closeDb, getDb } from "./db/client.js";
 import { chapterRun } from "./db/schema/index.js";
 import { runRoutes } from "./routes/runs.js";
+import { importChaptersFile } from "./runs/import-chapters.js";
 import { LOOPBACK_HOST, startServer } from "./server.js";
 
-export async function show(runId?: string): Promise<void> {
+export async function show(jsonPath?: string): Promise<void> {
   const db = getDb();
+  const runId = jsonPath ? importChaptersFile(jsonPath, db).runId : undefined;
 
   if (runId !== undefined) {
     const exists = db