@snappedly-tools/shipyard 0.7.0 → 0.9.0

package/dist/templates/parallel-planner-with-review/planner-branch.mts

@@ -0,0 +1,151 @@
+import { execFileSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+
+const PLANNER_BRANCH = "shipyard/planner";
+
+type BranchPrompt = (message: string) => Promise<string>;
+
+const askInTerminal: BranchPrompt = async (message) => {
+  const readline = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    return await readline.question(message);
+  } finally {
+    readline.close();
+  }
+};
+
+const refsConflict = (left: string, right: string): boolean =>
+  left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+
+const nextPlannerBranch = (localBranches: readonly string[]): string => {
+  for (let suffix = 2; ; suffix++) {
+    for (const candidate of [
+      `${PLANNER_BRANCH}-${suffix}`,
+      `shipyard-planner-${suffix}`,
+    ]) {
+      if (!localBranches.some((branch) => refsConflict(candidate, branch)))
+        return candidate;
+    }
+  }
+};
+
+const reusablePlannerBranch = (
+  localBranches: readonly string[],
+): string | undefined => {
+  const candidates = localBranches
+    .map((branch) => ({
+      branch,
+      suffix: /^(?:shipyard\/planner-|shipyard-planner-)(\d+)$/.exec(
+        branch,
+      )?.[1],
+    }))
+    .filter((candidate) => candidate.suffix !== undefined)
+    .sort((left, right) => Number(left.suffix) - Number(right.suffix));
+
+  return candidates.find(({ branch }) =>
+    localBranches.every(
+      (other) => other === branch || !refsConflict(branch, other),
+    ),
+  )?.branch;
+};
+
+export const resolvePlannerBranch = async (
+  localBranches: readonly string[],
+  options: {
+    isInteractive?: boolean;
+    ask?: BranchPrompt;
+    checkedOutBranches?: readonly string[];
+    mergedBranches?: readonly string[];
+    deleteBranches?: (branches: readonly string[]) => void;
+  } = {},
+): Promise<string> => {
+  const conflicts = localBranches.filter((branch) =>
+    refsConflict(PLANNER_BRANCH, branch),
+  );
+  if (conflicts.length === 0) return PLANNER_BRANCH;
+
+  const reusable = reusablePlannerBranch(localBranches);
+  if (reusable) return reusable;
+
+  const alternate = nextPlannerBranch(localBranches);
+
+  const conflictList = conflicts.map((branch) => `  - ${branch}`).join("\n");
+  const context =
+    `Planner branch '${PLANNER_BRANCH}' conflicts with local branch refs:\n${conflictList}\n` +
+    `Git cannot create both names. The listed local branches will be kept unless you choose deletion.`;
+  const isInteractive =
+    options.isInteractive ??
+    Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  if (!isInteractive) {
+    throw new Error(
+      `${context}\nRerun in an interactive terminal to keep them and use '${alternate}', or request local deletion after Git checks that they are merged and not checked out. No branches were changed.`,
+    );
+  }
+
+  const checkedOutBranches = new Set(
+    options.checkedOutBranches ??
+      execFileSync("git", ["worktree", "list", "--porcelain"], {
+        encoding: "utf8",
+      })
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith("branch refs/heads/"))
+        .map((line) => line.slice("branch refs/heads/".length)),
+  );
+  const mergedBranches = new Set(
+    options.mergedBranches ??
+      execFileSync(
+        "git",
+        ["branch", "--merged", "HEAD", "--format=%(refname:short)"],
+        { encoding: "utf8" },
+      )
+        .split(/\r?\n/)
+        .filter(Boolean),
+  );
+  const branchesSafeToDelete = conflicts.every(
+    (branch) => !checkedOutBranches.has(branch) && mergedBranches.has(branch),
+  );
+  const unsafeDeleteReasons = conflicts.flatMap((branch) => {
+    if (checkedOutBranches.has(branch))
+      return [`'${branch}' is checked out in a worktree`];
+    if (!mergedBranches.has(branch))
+      return [`'${branch}' has commits not merged into HEAD`];
+    return [];
+  });
+
+  const ask = options.ask ?? askInTerminal;
+  const answer = await ask(
+    `${context}\n[Y] Keep them and use '${alternate}' (recommended)\n` +
+      `[d] Delete these local branches and use '${PLANNER_BRANCH}'${
+        branchesSafeToDelete
+          ? ""
+          : ` (unavailable: ${unsafeDeleteReasons.join("; ")})`
+      }\n` +
+      `[n] Abort without changes\nChoose [Y/d/n]: `,
+  );
+  const choice = answer.trim().toLowerCase();
+  if (choice === "" || choice === "y" || choice === "yes") return alternate;
+  if (choice === "d" || choice === "delete") {
+    if (!branchesSafeToDelete) {
+      throw new Error(
+        `Cannot safely delete the conflicting branches: ${unsafeDeleteReasons.join("; ")}. No branches were changed. Use '${alternate}' or inspect the listed refs manually.`,
+      );
+    }
+    const deleteBranches =
+      options.deleteBranches ??
+      ((branches: readonly string[]) => {
+        for (const branch of branches)
+          execFileSync("git", ["branch", "-d", branch], {
+            encoding: "utf8",
+          });
+      });
+    deleteBranches(conflicts);
+    return PLANNER_BRANCH;
+  }
+
+  throw new Error(
+    `Planner branch selection cancelled. No branches were changed. Inspect with 'git worktree list' and 'git branch --list "shipyard/planner*"', then rerun.`,
+  );
+};

package/dist/templates/parallel-planner-with-review/setup.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# The sandbox starts from a temporary Git bundle, so reset its origin before Git pushes.
 if [[ -n ${GH_REPO:-} ]]; then
   [[ "$GH_REPO" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || { echo "Invalid GH_REPO" >&2; exit 1; }
   git remote set-url origin "https://github.com/$GH_REPO.git"

package/dist/templates/sequential-reviewer/main.mts

@@ -7,6 +7,55 @@ import { docker } from "@snappedly-tools/shipyard/sandboxes/docker";
 
 if (process.loadEnvFile && existsSync(".shipyard/.env"))
   process.loadEnvFile(".shipyard/.env");
+type ModelRole = "routine" | "strong";
+const CODEX_PROVIDER = true;
+const agentFactory = shipyard.codex;
+type AgentModel = Parameters<typeof agentFactory>[0];
+const readRoleModel = (role: ModelRole): string | undefined => {
+  const envName = `SHIPYARD_${role.toUpperCase()}_MODEL`;
+  const model = process.env[envName];
+  if (model !== undefined && model.trim().length === 0)
+    throw new Error(`${envName} must not be empty`);
+  return model;
+};
+const roleModels = {
+  routine: readRoleModel("routine"),
+  strong: readRoleModel("strong"),
+};
+const CODEX_REASONING_EFFORTS = shipyard.CODEX_REASONING_EFFORTS;
+type CodexReasoningEffort = shipyard.CodexReasoningEffort;
+const readCodexReasoningEffort = (
+  role: ModelRole,
+): CodexReasoningEffort | undefined => {
+  if (!CODEX_PROVIDER) return undefined;
+  const envName = `SHIPYARD_CODEX_${role.toUpperCase()}_REASONING_EFFORT`;
+  const effort = process.env[envName]?.trim();
+  if (!effort) return undefined;
+  if (!(CODEX_REASONING_EFFORTS as readonly string[]).includes(effort))
+    throw new Error(
+      `${envName} must be one of ${CODEX_REASONING_EFFORTS.join(", ")}; received "${effort}"`,
+    );
+  return effort as CodexReasoningEffort;
+};
+const roleEfforts = {
+  routine: readCodexReasoningEffort("routine"),
+  strong: readCodexReasoningEffort("strong"),
+};
+const readCodexRoleModel = (role: ModelRole, defaultModel: AgentModel) => {
+  if (!CODEX_PROVIDER || typeof defaultModel === "string") return defaultModel;
+  const envName = `SHIPYARD_CODEX_${role.toUpperCase()}_MODEL`;
+  const model = process.env[envName]?.trim();
+  return model ? { ...defaultModel, model } : defaultModel;
+};
+const roleAgent = (role: ModelRole, defaultModel: AgentModel) => {
+  const model = roleModels[role] ?? readCodexRoleModel(role, defaultModel);
+  const effort = roleEfforts[role];
+  if (typeof model !== "string")
+    return effort === undefined
+      ? agentFactory(model)
+      : agentFactory(model, { effort });
+  return agentFactory(model, { effort: effort ?? null });
+};
 const targetBranch = execFileSync("git", ["branch", "--show-current"], {
   encoding: "utf8",
 }).trim();
@@ -21,7 +70,11 @@ if (
 ) {
   throw new Error("Invalid target branch or GitHub repository");
 }
-process.env.GH_REPO = repository;
+const sandboxAuthOptions = {};
+const sandboxProvider = docker({
+  env: { GH_REPO: repository },
+  ...sandboxAuthOptions,
+});
 const MAX_ITERATIONS = 10;
 const hooks = {
   sandbox: {
@@ -126,7 +179,7 @@ for (let iteration = 0; iteration < MAX_ITERATIONS; iteration++) {
       ]);
     const sandbox = await shipyard.createSandbox({
       branch: issue.branch,
-      sandbox: docker(),
+      sandbox: sandboxProvider,
       hooks,
     });
     let evidence: string;
@@ -136,7 +189,7 @@ for (let iteration = 0; iteration < MAX_ITERATIONS; iteration++) {
         : [issue.id]) {
         await sandbox.run({
           name: `triage #${ticketId}`,
-          agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+          agent: roleAgent("routine", shipyard.CODEX_MODELS.routine),
           maxIterations: 1,
           promptFile: "./.shipyard/triage-prompt.md",
           promptArgs: { TASK_ID: ticketId },
@@ -146,7 +199,7 @@ for (let iteration = 0; iteration < MAX_ITERATIONS; iteration++) {
       const implement = await sandbox.run({
         name: "implementer",
         maxIterations: 1,
-        agent: shipyard.codex(shipyard.CODEX_MODELS.routine),
+        agent: roleAgent("routine", shipyard.CODEX_MODELS.routine),
         promptFile: "./.shipyard/implement-prompt.md",
         promptArgs: {
           TASK_ID: issue.id,
@@ -165,7 +218,7 @@ for (let iteration = 0; iteration < MAX_ITERATIONS; iteration++) {
       const review = await sandbox.run({
         name: "reviewer",
         maxIterations: 1,
-        agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+        agent: roleAgent("strong", shipyard.CODEX_MODELS.strong),
         promptFile: "./.shipyard/review-prompt.md",
         promptArgs: {
           BRANCH: issue.branch,
@@ -191,7 +244,7 @@ for (let iteration = 0; iteration < MAX_ITERATIONS; iteration++) {
 
     const publication = await shipyard.createSandbox({
       branch: issue.branch,
-      sandbox: docker(),
+      sandbox: sandboxProvider,
     });
     try {
       publicationUncertain = true;

package/dist/templates/sequential-reviewer/setup.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# The sandbox starts from a temporary Git bundle, so reset its origin before Git pushes.
 if [[ -n ${GH_REPO:-} ]]; then
   [[ "$GH_REPO" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || { echo "Invalid GH_REPO" >&2; exit 1; }
   git remote set-url origin "https://github.com/$GH_REPO.git"

package/dist/templates/shared/setup.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# The sandbox starts from a temporary Git bundle, so reset its origin before Git pushes.
 if [[ -n ${GH_REPO:-} ]]; then
   [[ "$GH_REPO" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || { echo "Invalid GH_REPO" >&2; exit 1; }
   git remote set-url origin "https://github.com/$GH_REPO.git"

package/dist/templates/simple-loop/main.mts

@@ -7,6 +7,55 @@ import { docker } from "@snappedly-tools/shipyard/sandboxes/docker";
 
 if (process.loadEnvFile && existsSync(".shipyard/.env"))
   process.loadEnvFile(".shipyard/.env");
+type ModelRole = "routine" | "strong";
+const CODEX_PROVIDER = true;
+const agentFactory = shipyard.codex;
+type AgentModel = Parameters<typeof agentFactory>[0];
+const readRoleModel = (role: ModelRole): string | undefined => {
+  const envName = `SHIPYARD_${role.toUpperCase()}_MODEL`;
+  const model = process.env[envName];
+  if (model !== undefined && model.trim().length === 0)
+    throw new Error(`${envName} must not be empty`);
+  return model;
+};
+const roleModels = {
+  routine: readRoleModel("routine"),
+  strong: readRoleModel("strong"),
+};
+const CODEX_REASONING_EFFORTS = shipyard.CODEX_REASONING_EFFORTS;
+type CodexReasoningEffort = shipyard.CodexReasoningEffort;
+const readCodexReasoningEffort = (
+  role: ModelRole,
+): CodexReasoningEffort | undefined => {
+  if (!CODEX_PROVIDER) return undefined;
+  const envName = `SHIPYARD_CODEX_${role.toUpperCase()}_REASONING_EFFORT`;
+  const effort = process.env[envName]?.trim();
+  if (!effort) return undefined;
+  if (!(CODEX_REASONING_EFFORTS as readonly string[]).includes(effort))
+    throw new Error(
+      `${envName} must be one of ${CODEX_REASONING_EFFORTS.join(", ")}; received "${effort}"`,
+    );
+  return effort as CodexReasoningEffort;
+};
+const roleEfforts = {
+  routine: readCodexReasoningEffort("routine"),
+  strong: readCodexReasoningEffort("strong"),
+};
+const readCodexRoleModel = (role: ModelRole, defaultModel: AgentModel) => {
+  if (!CODEX_PROVIDER || typeof defaultModel === "string") return defaultModel;
+  const envName = `SHIPYARD_CODEX_${role.toUpperCase()}_MODEL`;
+  const model = process.env[envName]?.trim();
+  return model ? { ...defaultModel, model } : defaultModel;
+};
+const roleAgent = (role: ModelRole, defaultModel: AgentModel) => {
+  const model = roleModels[role] ?? readCodexRoleModel(role, defaultModel);
+  const effort = roleEfforts[role];
+  if (typeof model !== "string")
+    return effort === undefined
+      ? agentFactory(model)
+      : agentFactory(model, { effort });
+  return agentFactory(model, { effort: effort ?? null });
+};
 const targetBranch = execFileSync("git", ["branch", "--show-current"], {
   encoding: "utf8",
 }).trim();
@@ -21,7 +70,11 @@ if (
 ) {
   throw new Error("Invalid target branch or GitHub repository");
 }
-process.env.GH_REPO = repository;
+const sandboxAuthOptions = {};
+const sandboxProvider = docker({
+  env: { GH_REPO: repository },
+  ...sandboxAuthOptions,
+});
 const hooks = {
   sandbox: {
     onSandboxReady: [
@@ -123,7 +176,7 @@ for (let iteration = 0; iteration < 3; iteration++) {
       ]);
     const sandbox = await shipyard.createSandbox({
       branch: issue.branch,
-      sandbox: docker(),
+      sandbox: sandboxProvider,
       hooks,
     });
     let evidence: string;
@@ -133,7 +186,7 @@ for (let iteration = 0; iteration < 3; iteration++) {
         : [issue.id]) {
         await sandbox.run({
           name: `triage #${ticketId}`,
-          agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+          agent: roleAgent("routine", shipyard.CODEX_MODELS.routine),
           maxIterations: 1,
           promptFile: "./.shipyard/triage-prompt.md",
           promptArgs: { TASK_ID: ticketId },
@@ -142,7 +195,7 @@ for (let iteration = 0; iteration < 3; iteration++) {
       }
       const result = await sandbox.run({
         name: "implementer",
-        agent: shipyard.codex(shipyard.CODEX_MODELS.routine),
+        agent: roleAgent("routine", shipyard.CODEX_MODELS.routine),
         maxIterations: 1,
         promptFile: "./.shipyard/prompt.md",
         promptArgs: {
@@ -171,7 +224,7 @@ for (let iteration = 0; iteration < 3; iteration++) {
     // branch so a later invocation can fast-forward the same PR.
     const publication = await shipyard.createSandbox({
       branch: issue.branch,
-      sandbox: docker(),
+      sandbox: sandboxProvider,
     });
     try {
       publicationUncertain = true;

package/dist/templates/simple-loop/setup.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# The sandbox starts from a temporary Git bundle, so reset its origin before Git pushes.
 if [[ -n ${GH_REPO:-} ]]; then
   [[ "$GH_REPO" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || { echo "Invalid GH_REPO" >&2; exit 1; }
   git remote set-url origin "https://github.com/$GH_REPO.git"

package/dist/workflow/coordinator/migrations/002_workflow_phase_records.sql

@@ -0,0 +1,11 @@
+-- Durable records for triage investigations and bounded repair publication.
+-- These records resume phase-specific work; the coordinator ledger remains
+-- responsible for job, dispatch, lease, and event state.
+
+CREATE TABLE IF NOT EXISTS shipyard_workflow_phase_records (
+  namespace TEXT NOT NULL CHECK (namespace IN ('triage', 'repair-batch')),
+  record_key TEXT NOT NULL,
+  record JSONB NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL,
+  PRIMARY KEY (namespace, record_key)
+);

package/dist/workflow/coordinator/migrations/003_phase_record_schema_version.sql

@@ -0,0 +1,6 @@
+-- Version phase records without breaking writers from the previous release.
+-- The default assigns old-format inserts version 1; code rollback can leave the
+-- additive column in place.
+ALTER TABLE shipyard_workflow_phase_records
+  ADD COLUMN IF NOT EXISTS schema_version INTEGER NOT NULL DEFAULT 1
+  CHECK (schema_version = 1);