@printpractical/cruze 0.0.2 → 0.0.4

package/src/adapters/outbound/node_project_files.ts

@@ -1,6 +1,7 @@
 import { appendFile, lstat, mkdir, readFile, readdir, rename, rm, symlink, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import type { ProjectFiles } from "../../app/ports/project_files.ts";
+import { CruzeError } from "../../domain/cruze_error.ts";
 
 /** Project files on the local disk, confined to one root directory. */
 export class NodeProjectFiles implements ProjectFiles {
@@ -78,7 +79,8 @@ export class NodeProjectFiles implements ProjectFiles {
     this.assertInsideRoot(resolve(dirname(linkPath), target));
     await mkdir(dirname(linkPath), { recursive: true });
     await rm(linkPath, { recursive: true, force: true });
-    await symlink(target, linkPath, "dir");
+    // No link type: on Windows, Node picks a file or directory link from what the target is.
+    await symlink(target, linkPath);
   }
 
   /** Resolves a project-relative path, refusing anything outside the root. */
@@ -91,7 +93,7 @@ export class NodeProjectFiles implements ProjectFiles {
   private assertInsideRoot(absolute: string): void {
     const fromRoot = relative(this.root, absolute);
     if (fromRoot.startsWith("..") || isAbsolute(fromRoot)) {
-      throw new Error(`Path escapes the project root: ${absolute}`);
+      throw new CruzeError("outside-project", `${absolute} is outside the project at ${this.root}`);
     }
   }
 }

package/src/adapters/outbound/process_agent_runner.ts

@@ -11,15 +11,20 @@ export class ProcessAgentRunner implements AgentRunner {
 
   run(command: string[], prompt: string): Promise<AgentRun> {
     const [program, ...args] = command;
-    if (program === undefined) return Promise.resolve({ exitCode: 127, output: "", error: "no command configured" });
+    if (program === undefined) return Promise.resolve({ kind: "missing" });
     return new Promise((resolve) => {
       const child = spawn(program, args, { cwd: this.cwd, stdio: ["pipe", "pipe", "pipe"] });
       let output = "";
       let error = "";
       child.stdout.on("data", (chunk: Buffer) => (output += chunk.toString("utf8")));
       child.stderr.on("data", (chunk: Buffer) => (error += chunk.toString("utf8")));
-      child.on("error", (failure) => resolve({ exitCode: 127, output, error: `${error}${failure.message}` }));
-      child.on("close", (code) => resolve({ exitCode: code ?? 1, output, error }));
+      // Spawning reports ENOENT when the program isn't on the PATH.
+      child.on("error", (failure: NodeJS.ErrnoException) =>
+        resolve(failure.code === "ENOENT" ? { kind: "missing" } : { kind: "finished", exitCode: 127, output, error: `${error}${failure.message}` }),
+      );
+      child.on("close", (code) => resolve({ kind: "finished", exitCode: code ?? 1, output, error }));
+      // A program that never started closes stdin; ignore the write error, since the spawn error reports it.
+      child.stdin.on("error", () => {});
       child.stdin.end(prompt);
     });
   }

package/src/app/ports/agent_runner.ts

@@ -1,11 +1,10 @@
 /** Starts a coding agent in a fresh context, non-interactively, and collects what it reports. */
 export interface AgentRunner {
-  /** Runs `command` in the project root with `prompt` on standard input. */
+  /**
+   * Runs `command` in the project root with `prompt` on standard input. Reports `missing`,
+   * without running anything, when the command's program isn't installed.
+   */
   run(command: string[], prompt: string): Promise<AgentRun>;
 }
 
-export interface AgentRun {
-  exitCode: number;
-  output: string;
-  error: string;
-}
+export type AgentRun = { kind: "finished"; exitCode: number; output: string; error: string } | { kind: "missing" };

package/src/app/use_cases/init_project.ts

@@ -1,5 +1,7 @@
+import { CruzeError } from "../../domain/cruze_error.ts";
+import { agentSkillHome } from "../../domain/agent_skill_homes.ts";
 import { parseProjectName } from "../../domain/project_name.ts";
-import { INIT_SCAFFOLD, renderTemplate } from "../../domain/scaffold.ts";
+import { CLAUDE_INSTRUCTIONS, INIT_AGENTS, INIT_SCAFFOLD, type InitAgent, renderTemplate, reviewSettingTemplate } from "../../domain/scaffold.ts";
 import type { Bundle } from "../ports/bundle.ts";
 import type { ProjectFiles } from "../ports/project_files.ts";
 import type { Prompter } from "../ports/prompter.ts";
@@ -10,6 +12,7 @@ export interface InitProjectRequest {
   name?: string;
   /** Offered as the default answer when asking for the name. */
   defaultName: string;
+  /** From `--agent`: `claude`, `other`, or agents to link skills for. Asked for when it names neither. */
   agents: string[];
   /**
    * How CI runs this version of Cruze through npx, such as `github:PrintPractical/cruze#v0.0.1`
@@ -20,6 +23,7 @@ export interface InitProjectRequest {
 
 export interface InitProjectReport {
   project: string;
+  agent: InitAgent;
   created: string[];
   /** Files that already existed and were left untouched. */
   skipped: string[];
@@ -36,11 +40,13 @@ export async function initProject(
 ): Promise<InitProjectReport> {
   const { files, bundle, prompter } = deps;
   const project = parseProjectName(request.name ?? (await prompter.ask("Project name", request.defaultName)));
+  const agent = await chooseAgent(files, prompter, request.agents);
   const values = {
     project_name: project,
     project_name_quoted: JSON.stringify(project),
     cruze_version: bundle.version,
     cruze_package: request.package ?? `@printpractical/cruze@${bundle.version}`,
+    review_setting: (await bundle.template(reviewSettingTemplate(agent))).trimEnd(),
   };
 
   const created: string[] = [];
@@ -53,7 +59,29 @@ export async function initProject(
     await files.writeText(entry.path, renderTemplate(await bundle.template(entry.template), values));
     created.push(entry.path);
   }
+  if (agent === "claude") {
+    if (await files.exists(CLAUDE_INSTRUCTIONS.path)) skipped.push(CLAUDE_INSTRUCTIONS.path);
+    else {
+      await files.link(CLAUDE_INSTRUCTIONS.path, CLAUDE_INSTRUCTIONS.target);
+      created.push(CLAUDE_INSTRUCTIONS.path);
+    }
+  }
 
-  const skills = await installSkills({ files, bundle }, { agents: request.agents });
-  return { project, created, skipped, skills };
+  const linkFor = new Set(request.agents.filter((a) => a !== "other"));
+  if (agent === "claude") linkFor.add("claude");
+  const skills = await installSkills({ files, bundle }, { agents: [...linkFor] });
+  return { project, agent, created, skipped, skills };
+}
+
+/** The agent named with `--agent`, or shown by the project's files, or else the answer to asking. */
+async function chooseAgent(files: ProjectFiles, prompter: Prompter, requested: string[]): Promise<InitAgent> {
+  if (requested.includes("claude")) return "claude";
+  if (requested.includes("other")) return "other";
+  for (const marker of agentSkillHome("claude")?.markers ?? []) {
+    if (await files.exists(marker)) return "claude";
+  }
+  const answer = (await prompter.ask(`Coding agent (${INIT_AGENTS.join(" or ")})`, "claude")).trim().toLowerCase();
+  const agent = INIT_AGENTS.find((a) => a === answer);
+  if (agent === undefined) throw new CruzeError("unknown-agent", `Unknown agent: ${answer}. Answer ${INIT_AGENTS.join(" or ")}, or pass --agent.`);
+  return agent;
 }

package/src/app/use_cases/journal_events.ts

@@ -1,5 +1,5 @@
 import { CruzeError } from "../../domain/cruze_error.ts";
-import { recordedEventProblems, recordedFields, type JournalEntry } from "../../domain/journal.ts";
+import { journalPath, parseJournal, recordedEventProblems, recordedFields, type JournalEntry } from "../../domain/journal.ts";
 import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
 import { appendJournal, loadView, type ProjectDeps } from "../project_context.ts";
 
@@ -18,9 +18,17 @@ export async function recordEvent(deps: ProjectDeps, event: string, fields: Reco
   return appendJournal(deps, folder, event, { ...recorded, cruze: deps.bundle.version });
 }
 
-export async function listEvents(deps: ProjectDeps, event?: string): Promise<JournalEntry[]> {
-  const { journal } = await loadView(deps.files);
-  return event === undefined ? journal : journal.filter((entry) => entry.event === event);
+/** The journal, or one feature's or change's part of it: its own journal, and a feature's changes' too. */
+export async function listEvents(deps: ProjectDeps, event?: string, item?: string): Promise<JournalEntry[]> {
+  const view = await loadView(deps.files);
+  let entries = view.journal;
+  if (item !== undefined) {
+    const resolved = resolveArtifact(view, item).item;
+    if (resolved === undefined) throw new CruzeError("not-found", `"${item}" is not a feature or change`);
+    const parts = [resolved, ...view.items.filter((i) => resolved.kind === "feature" && i.featureRef === resolved.ref)];
+    entries = parts.flatMap((part) => parseJournal(view.snapshot.get(journalPath(part.folder))).entries).sort((a, b) => a.at.localeCompare(b.at));
+  }
+  return event === undefined ? entries : entries.filter((entry) => entry.event === event);
 }
 
 export interface FeedbackExport {

package/src/app/use_cases/project_status.ts

@@ -1,6 +1,7 @@
 import { CruzeError } from "../../domain/cruze_error.ts";
 import { readProgress } from "../../domain/project/progress.ts";
 import { buildProjectView } from "../../domain/project/project_view.ts";
+import { findWorkItem, type WorkItem } from "../../domain/project/work_items.ts";
 import { nextSteps, type NextReport } from "../../domain/status/next_step.ts";
 import { activeChange, buildGateReasons, projectStatus, touchedIds, type ProjectStatus } from "../../domain/status/work_status.ts";
 import { appendJournal, loadView, type ProjectDeps } from "../project_context.ts";
@@ -59,10 +60,11 @@ export async function findOverlaps(deps: ProjectDeps, ref?: string): Promise<{ c
   const overlaps: Overlap[] = [];
   for (const other of await deps.repository.otherBranches()) {
     const theirs = buildProjectView(new Map([...view.snapshot].filter(([p]) => p.startsWith("docs/")).concat([...(await deps.repository.filesOnBranch(other, ".cruze"))])));
-    // Work in flight on a branch is the change bound to it.
+    // Work in flight on a branch is the change bound to it that hasn't landed, there or here.
     const boundThere = theirs.items.filter((i) => {
       const bound = readProgress(i.doc).branch;
-      return !i.archived && i.ref !== change.ref && bound !== undefined && (other === bound || other.endsWith(`/${bound}`));
+      const here = findWorkItem(view.items, i.ref);
+      return !landed(i) && (here === undefined || !landed(here)) && i.ref !== change.ref && bound !== undefined && (other === bound || other.endsWith(`/${bound}`));
     });
     for (const item of boundThere) {
       const shared = [...touchedIds(theirs, item)].filter((id) => mine.has(id));
@@ -71,3 +73,7 @@ export async function findOverlaps(deps: ProjectDeps, ref?: string): Promise<{ c
   }
   return { change: change.ref, overlaps };
 }
+
+function landed(item: WorkItem): boolean {
+  return item.archived || readProgress(item.doc).landed !== undefined;
+}

package/src/app/use_cases/record_progress.ts

@@ -58,6 +58,23 @@ export async function addFutureFeature(deps: ProjectDeps, slug: string, summary:
   return { feature: slug };
 }
 
+/**
+ * Replaces a feature's summary on the feature map, in the future list or the implemented list,
+ * when a decision changed what the feature delivers. Its goals or release stay as they are.
+ */
+export async function updateFeatureSummary(deps: ProjectDeps, slug: string, summary: string): Promise<{ feature: string; list: "Future" | "Implemented" }> {
+  if (summary.trim() === "") throw new CruzeError("missing-summary", "a feature needs a summary");
+  const vision = await requireVision(deps);
+  const future = readRows(vision, "Future").find((row) => row[0] === slug);
+  const implemented = readRows(vision, "Implemented").find((row) => row[0] === slug);
+  if (future === undefined && implemented === undefined) throw new CruzeError("not-found", `${slug} is not on the feature map`);
+  const list = future !== undefined ? "Future" : "Implemented";
+  const cells = future !== undefined ? [slug, summary.trim(), future[2] ?? ""] : [slug, implemented?.[1] ?? "", summary.trim()];
+  await deps.files.writeText(PATHS.vision, upsertRow(vision, list, cells));
+  await appendJournal(deps, ".cruze", "feature-map", { action: "update", feature: slug, summary: summary.trim() });
+  return { feature: slug, list };
+}
+
 export async function dropFutureFeature(deps: ProjectDeps, slug: string, reason: string): Promise<{ feature: string }> {
   const vision = await requireVision(deps);
   const { text, removed } = removeRow(vision, "Future", slug);

package/src/app/use_cases/run_review.ts

@@ -18,16 +18,19 @@ export interface ReviewRequest {
   base?: string;
 }
 
-export interface ReviewReport {
-  role: Role;
-  item?: string;
-  command: string[];
-  report: string;
-}
+/**
+ * The role's report, or, when the configured agent isn't installed, the prompt for the calling
+ * agent to run in a helper of its own.
+ */
+export type ReviewReport = { role: Role; item?: string; command?: string[] } & (
+  | { status: "reported"; report: string }
+  | { status: "run-in-helper"; instruction: string; prompt: string }
+);
 
 /**
  * Runs a Cruze role in a fresh agent context: the role's prompt, what it reviews, and nothing
- * from the conversation that produced the work. Returns the role's report as written.
+ * from the conversation that produced the work. Returns the role's report as written, or the
+ * prompt to run in a helper when the configured agent isn't installed.
  */
 export async function runReview(deps: ProjectDeps & { runner: AgentRunner }, request: ReviewRequest): Promise<ReviewReport> {
   if (!(ROLES as readonly string[]).includes(request.role)) throw new CruzeError("unknown-role", `the roles are ${ROLES.join(", ")}`);
@@ -55,12 +58,23 @@ export async function runReview(deps: ProjectDeps & { runner: AgentRunner }, req
     context.map((line) => `- ${line}`).join("\n"),
   ].join("\n\n");
 
-  const command = view.config?.config?.review.command ?? [];
+  const subject = { role, ...(request.item === undefined ? {} : { item: request.item }) };
+  const command = view.config?.config?.review.command;
+  if (command === undefined) return { ...subject, status: "run-in-helper", instruction: helperInstruction(undefined), prompt };
   const run = await deps.runner.run(command, prompt);
+  if (run.kind === "missing") return { ...subject, command, status: "run-in-helper", instruction: helperInstruction(command[0]), prompt };
   if (run.exitCode !== 0) throw new CruzeError("review-failed", `${command.join(" ")} exited with ${run.exitCode}: ${run.error.trim() || run.output.trim()}`);
-  const report: ReviewReport = { role, command, report: run.output.trim() };
-  if (request.item !== undefined) report.item = request.item;
-  return report;
+  return { ...subject, command, status: "reported", report: run.output.trim() };
+}
+
+/** Why cruze review can't start the fresh context itself, and how the calling agent does instead. */
+function helperInstruction(program: string | undefined): string {
+  return [
+    program === undefined ? "No review agent is configured under review.command." : `${program} is not installed, so cruze review can't start a fresh context.`,
+    "Start a helper agent with no conversation history, give it this prompt and nothing else, and take its report as the role's report.",
+    "If you can't start a helper, tell the user, and have them run the prompt in a new session.",
+    "To have cruze review start an agent itself, set review.command in .cruze/config.yaml.",
+  ].join(" ");
 }
 
 async function bundledRole(deps: ProjectDeps, role: Role): Promise<string> {

package/src/domain/config.ts

@@ -19,13 +19,13 @@ export interface CruzeConfig {
   layers: Layer[];
   /** Named project commands, such as `test: cargo test`, shown in AGENTS.md. */
   commands: Record<string, string>;
-  /** How `cruze review` starts an agent in a fresh context: the program and its arguments. */
-  review: { command: string[] };
+  /**
+   * How `cruze review` starts an agent in a fresh context: the program and its arguments.
+   * Without one, the calling agent runs the role's prompt in a helper of its own.
+   */
+  review: { command?: string[] };
 }
 
-/** Claude Code in print mode, allowed to read the project, its history and run `cruze`, but not to edit. */
-export const DEFAULT_REVIEW_COMMAND = ["claude", "-p", "--allowedTools", "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git show:*) Bash(cruze:*)"];
-
 export interface Layer {
   name: string;
   paths: string[];
@@ -95,8 +95,8 @@ export function parseConfig(text: string): ConfigResult {
     }
   }
   const review = asRecord(root["review"]) ?? {};
-  const reviewCommand = review["command"] === undefined ? DEFAULT_REVIEW_COMMAND : stringList(review["command"], "review.command", problems);
-  if (reviewCommand.length === 0) problems.push("review.command needs at least the program to run");
+  const reviewCommand = review["command"] === undefined ? undefined : stringList(review["command"], "review.command", problems);
+  if (reviewCommand?.length === 0) problems.push("review.command needs at least the program to run");
 
   const config: CruzeConfig = {
     version: 1,
@@ -109,7 +109,7 @@ export function parseConfig(text: string): ConfigResult {
     check: { maxLines: maxLines ?? 250, maxTypes: maxTypes ?? 5, exceptions },
     layers,
     commands,
-    review: { command: reviewCommand.length === 0 ? DEFAULT_REVIEW_COMMAND : reviewCommand },
+    review: reviewCommand === undefined || reviewCommand.length === 0 ? {} : { command: reviewCommand },
   };
   return { config, problems };
 }

package/src/domain/scaffold.ts

@@ -11,12 +11,26 @@ export const INIT_SCAFFOLD: readonly ScaffoldEntry[] = [
   { path: "README.md", template: "init/README.md" },
   { path: "CHANGELOG.md", template: "init/CHANGELOG.md" },
   { path: "AGENTS.md", template: "init/AGENTS.md" },
-  { path: "CLAUDE.md", template: "init/CLAUDE.md" },
   { path: ".cruze/config.yaml", template: "init/config.yaml" },
   { path: ".github/workflows/ci.yml", template: "init/ci.yml" },
   { path: ".gitattributes", template: "init/gitattributes" },
 ];
 
+/**
+ * The agents `cruze init` sets a project up for: Claude Code, which gets `CLAUDE.md`, linked skills
+ * and a review command, or any other agent, which reads `AGENTS.md` and `.agents/skills/`.
+ */
+export const INIT_AGENTS = ["claude", "other"] as const;
+export type InitAgent = (typeof INIT_AGENTS)[number];
+
+/** Claude Code reads `CLAUDE.md`, so init links it to `AGENTS.md` rather than keeping a second copy. */
+export const CLAUDE_INSTRUCTIONS = { path: "CLAUDE.md", target: "AGENTS.md" };
+
+/** The template for the config's `review:` setting, which only Claude Code gets filled in. */
+export function reviewSettingTemplate(agent: InitAgent): string {
+  return `init/review/${agent}.yaml`;
+}
+
 /** Replaces every `{{key}}` with its value; an unknown key is a template bug. */
 export function renderTemplate(template: string, values: Record<string, string>): string {
   return template.replace(/\{\{([a-z_]+)\}\}/g, (placeholder, key: string) => {

package/src/domain/status/work_status.ts

@@ -1,5 +1,4 @@
 import { evaluateApproval, type ApprovalStatus } from "../approvals/evaluate.ts";
-import { findIds } from "../ids.ts";
 import { PATHS } from "../project/layout.ts";
 import { readDelta } from "../project/deltas.ts";
 import { readScope } from "../project/plan_parts.ts";
@@ -89,13 +88,12 @@ export function buildGateReasons(view: ProjectView, branch: string | null): stri
   });
 }
 
-/** The elements a change touches: its scope plus every ID its documents cite. */
+/** The elements a change touches: its scope and its delta, not the elements it only cites, such as a test seam. */
 export function touchedIds(view: ProjectView, change: WorkItem): Set<string> {
   const feature = featureOf(view.items, change);
   const scope = readScope(change.doc);
   const ids = new Set([...(scope?.delivers ?? []), ...(scope?.builds ?? []), ...(scope?.removes ?? [])]);
   const deltaDoc = feature?.doc ?? change.doc;
   for (const id of readDelta(deltaDoc).ids) ids.add(id);
-  for (const id of findIds(change.doc.lines.join("\n"))) ids.add(id);
   return new Set([...ids].filter((id) => !id.startsWith("RULE-")));
 }

package/templates/init/config.yaml

@@ -29,9 +29,4 @@ layers: []
 # walking-skeleton change fills them in; `cruze land` copies them into AGENTS.md.
 commands: {}
 
-# How `cruze review` starts an agent in a fresh context to run a role, with the
-# prompt on standard input. The default lets Claude Code read the project and run
-# git and cruze. The verifier runs the system, so add the project's build and run
-# commands, such as "Bash(cargo:*)". For Codex, use ["codex", "exec", "-"].
-review:
-  command: ["claude", "-p", "--allowedTools", "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git show:*) Bash(cruze:*)"]
+{{review_setting}}

package/templates/init/review/claude.yaml

@@ -0,0 +1,7 @@
+# How `cruze review` starts an agent in a fresh context to run a role, with the
+# prompt on standard input. This lets Claude Code read the project and run git
+# and cruze. The verifier runs the system, so add the project's build and run
+# commands, such as "Bash(cargo:*)". Without review.command, your agent runs each
+# role in a helper of its own.
+review:
+  command: ["claude", "-p", "--allowedTools", "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git show:*) Bash(cruze:*)"]

package/templates/init/review/other.yaml

@@ -0,0 +1,7 @@
+# How `cruze review` starts an agent in a fresh context to run a role, with the
+# prompt on standard input. Without it, your agent runs each role in a helper
+# of its own. To have cruze review start one instead, set the command, such as
+# ["codex", "exec", "-"] for Codex or ["opencode", "run", "--agent", "plan"] for
+# OpenCode.
+# review:
+#   command: ["codex", "exec", "-"]

package/templates/init/CLAUDE.md

@@ -1 +0,0 @@
-@AGENTS.md