@snappedly-tools/shipyard 0.5.0 → 0.7.0-staging.36081473933

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

@@ -1,51 +1,245 @@
-import { CODEX_MODELS, run, codex } from "@snappedly-tools/shipyard";
+// Simple loop: select one activated issue scope per iteration, implement it,
+// then hand its verified commit to a human through a pull request.
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import * as shipyard from "@snappedly-tools/shipyard";
 import { docker } from "@snappedly-tools/shipyard/sandboxes/docker";
 
-// Simple loop: an agent that picks open issues one by one and closes them.
-// Generated entrypoint: .shipyard/main.mts
-// Run this with: npx shipyard run
-// Or add to package.json scripts: "shipyard": "shipyard run"
-
-await run({
-  // A name for this run, shown as a prefix in log output.
-  name: "worker",
-
-  // Sandbox provider — runs the agent inside an isolated container.
-  sandbox: docker(),
-
-  // The agent provider. The routine configured Codex model runs at max
-  // reasoning by default. Switch to CODEX_MODELS.strong for more demanding
-  // planning or review work.
-  agent: codex(CODEX_MODELS.routine),
-
-  // Path to the prompt file. Shell expressions inside are evaluated inside the
-  // sandbox at the start of each iteration, so the agent always sees fresh data.
-  promptFile: "./.shipyard/prompt.md",
+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();
+const repository = execFileSync(
+  "gh",
+  ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"],
+  { encoding: "utf8" },
+).trim();
+if (
+  !/^[A-Za-z0-9._/-]+$/.test(targetBranch) ||
+  !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository)
+) {
+  throw new Error("Invalid target branch or GitHub repository");
+}
+process.env.GH_REPO = repository;
+const hooks = {
+  sandbox: {
+    onSandboxReady: [
+      { command: "timeout 300 bash .shipyard/setup.sh", timeoutMs: 300_000 },
+    ],
+  },
+};
+const closeClean = async (sandbox: {
+  close: () => Promise<{ preservedWorktreePath?: string }>;
+}) => {
+  const { preservedWorktreePath } = await sandbox.close();
+  if (preservedWorktreePath)
+    throw new Error(`Sandbox has uncommitted work at ${preservedWorktreePath}`);
+};
+const verifyTriage = (ticketId: string) => {
+  try {
+    execFileSync("bash", [".shipyard/verify-triage.sh", ticketId, repository], {
+      encoding: "utf8",
+    });
+  } catch (error) {
+    const detail = (error as { stderr?: string | Buffer }).stderr
+      ?.toString()
+      .trim();
+    throw new Error(detail || `Could not verify triage for #${ticketId}`);
+  }
+};
 
-  // Maximum number of iterations (agent invocations) to run in a session.
-  // Each iteration works on a single issue. Increase this to process more issues
-  // per run, or set it to 1 for a single-shot mode.
-  maxIterations: 3,
+const blockScope = (
+  scope: { id: string; branch: string; tickets?: Array<{ id: string }> },
+  error: unknown,
+) => {
+  const reason = (error instanceof Error ? error.message : String(error)).slice(
+    0,
+    3000,
+  );
+  execFileSync(
+    "bash",
+    [
+      ".shipyard/block-scope.sh",
+      scope.id,
+      scope.id,
+      repository,
+      [scope.id, ...(scope.tickets ?? []).map((ticket) => ticket.id)].join(","),
+      scope.branch,
+    ],
+    { input: reason, encoding: "utf8" },
+  );
+  console.error(`Shipyard blocked issue #${scope.id}: ${reason}`);
+};
 
-  // Branch strategy — merge-to-head creates a temporary branch for the agent
-  // to work on, then merges the result back to HEAD when the run completes.
-  // This is required when using copyToWorktree, since head mode bind-mounts
-  // the host directory directly (no worktree to copy into).
-  branchStrategy: { type: "merge-to-head" },
+for (let iteration = 0; iteration < 3; iteration++) {
+  const issues = JSON.parse(
+    execFileSync("node", [".shipyard/select-issues.mjs"], { encoding: "utf8" }),
+  ) as Array<{
+    id: string;
+    title: string;
+    branch: string;
+    kind: "standalone" | "spec";
+    body?: string;
+    tickets?: Array<{
+      id: string;
+      title: string;
+      body: string;
+      state: string;
+      blockedBy: Array<{ id: string; title: string; state: string }>;
+    }>;
+    completedTicketIds?: string[];
+    outstandingTicketIds?: string[];
+  }>;
+  const issue = issues[0];
+  if (!issue) break;
 
-  // Copy node_modules from the host into the worktree before the sandbox
-  // starts. This avoids a full npm install from scratch on every iteration.
-  // The onSandboxReady hook still runs npm install as a safety net to handle
-  // platform-specific binaries and any packages added since the last copy.
-  copyToWorktree: ["node_modules"],
+  let handedOff = false;
+  let publicationUncertain = false;
+  try {
+    execFileSync("gh", [
+      "label",
+      "create",
+      "shipyard:pending",
+      "--repo",
+      repository,
+      "--color",
+      "1D76DB",
+      "--description",
+      "Shipyard is working on this ticket",
+      "--force",
+    ]);
+    for (const ticketId of issue.kind === "spec"
+      ? (issue.tickets ?? []).map((ticket) => ticket.id)
+      : [issue.id])
+      execFileSync("gh", [
+        "issue",
+        "edit",
+        ticketId,
+        "--repo",
+        repository,
+        "--add-label",
+        "shipyard:pending",
+      ]);
+    const sandbox = await shipyard.createSandbox({
+      branch: issue.branch,
+      sandbox: docker(),
+      hooks,
+    });
+    let evidence: string;
+    try {
+      for (const ticketId of issue.kind === "spec"
+        ? (issue.tickets ?? []).map((ticket) => ticket.id)
+        : [issue.id]) {
+        await sandbox.run({
+          name: `triage #${ticketId}`,
+          agent: roleAgent("routine", shipyard.CODEX_MODELS.routine),
+          maxIterations: 1,
+          promptFile: "./.shipyard/triage-prompt.md",
+          promptArgs: { TASK_ID: ticketId },
+        });
+        verifyTriage(ticketId);
+      }
+      const result = await sandbox.run({
+        name: "implementer",
+        agent: roleAgent("routine", shipyard.CODEX_MODELS.routine),
+        maxIterations: 1,
+        promptFile: "./.shipyard/prompt.md",
+        promptArgs: {
+          TASK_ID: issue.id,
+          ISSUE_TITLE: issue.title,
+          BRANCH: issue.branch,
+          SCOPE: JSON.stringify(issue),
+          SKILL: issue.kind === "spec" ? "/implement-spec" : "/implement",
+        },
+      });
+      const packet = [
+        ...result.stdout.matchAll(/<handoff>([\s\S]*?)<\/handoff>/g),
+      ]
+        .at(-1)?.[1]
+        ?.trim();
+      if (!result.completionSignal || !packet)
+        throw new Error(
+          `Issue #${issue.id} has no verified completion evidence: ${result.stdout.trim().slice(-1200)}`,
+        );
+      evidence = packet;
+    } finally {
+      await closeClean(sandbox);
+    }
 
-  // Lifecycle hooks — commands grouped by where they run (host or sandbox).
-  hooks: {
-    sandbox: {
-      // onSandboxReady runs once after the sandbox is initialised and the repo is
-      // synced in, before the agent starts. Use it to install dependencies or run
-      // any other setup steps your project needs.
-      onSandboxReady: [{ command: "npm install" }],
-    },
-  },
-});
+    // Sync-out rewrites sandbox commits on the host. Publish from the synced
+    // branch so a later invocation can fast-forward the same PR.
+    const publication = await shipyard.createSandbox({
+      branch: issue.branch,
+      sandbox: docker(),
+    });
+    try {
+      publicationUncertain = true;
+      const handoff = await publication.exec(
+        `bash .shipyard/handoff.sh ${issue.id} ${issue.branch} ${targetBranch} ${repository} ${[issue.id, ...(issue.tickets ?? []).map((ticket) => ticket.id)].join(",")} ${issue.outstandingTicketIds?.join(",") || "-"} ${issue.completedTicketIds?.join(",") || "-"}`,
+        { stdin: evidence },
+      );
+      publicationUncertain = handoff.exitCode === 75;
+      if (handoff.exitCode !== 0)
+        throw new Error(
+          `PR handoff for #${issue.id} failed: ${handoff.stderr || handoff.stdout}`,
+        );
+      console.log(handoff.stdout.trim());
+      handedOff = true;
+    } finally {
+      await publication.close();
+    }
+  } catch (error) {
+    if (handedOff || publicationUncertain) throw error;
+    blockScope(issue, error);
+  }
+}

package/dist/templates/simple-loop/prompt.md

@@ -1,53 +1,19 @@
-# Context
+# Assigned issue scope
 
-## Open issues
+Implement scope #{{TASK_ID}} ({{ISSUE_TITLE}}) on branch `{{BRANCH}}`.
+Read it with `gh issue view {{TASK_ID}} --comments`, including acceptance criteria, and read `AGENTS.md`, `CONTEXT.md`, `docs/agents/workflow.md`, and relevant ADRs. The selector resolved the selected tickets and their dependencies below.
 
-!`{{LIST_TASKS_COMMAND}}`
+Follow {{SKILL}} for this scope. For a planning spec, deliver only tickets in `SCOPE.tickets` in dependency order on this one branch. Other linked tickets are context; do not implement them. Integrate, clean up, and review the selected work before handoff. Child workers may follow `/implement` under `/implement-spec` coordination. Do not create separate child PRs. Use `/tdd` for changed logic, then `/code-cleanup` and `/code-review` as the skill and repository policy require. Run candidate dependency installation again after changing manifests: `bash .shipyard/setup.sh`. Complete the required checks, resolve review findings, and commit all task work. Do not close the issue, merge into the target branch, or publish the PR; the surrounding workflow handles handoff.
 
-The list above has already been filtered to issues ready for work and is the sole source of truth for what work exists. Do not run your own unfiltered query to find more issues — if the list is empty, there is nothing to do.
+If requirements, checks, or review are unresolved, describe the blocker and stop without the completion marker. Only after the verified commit, finish with a concise evidence packet containing changed scope, `Checks: <commands and results>`, `Review: APPROVED`, and limitations:
 
-## Recent RALPH commits (last 10)
-
-!`git log --oneline --grep="RALPH" -10`
-
-# Task
-
-You are RALPH — an autonomous coding agent working through issues one at a time.
-
-## Priority order
-
-Work on issues in this order:
-
-1. **Bug fixes** — broken behaviour affecting users
-2. **Tracer bullets** — thin end-to-end slices that prove an approach works
-3. **Polish** — improving existing functionality (error messages, UX, docs)
-4. **Refactors** — internal cleanups with no user-visible change
-
-Pick the highest-priority open issue that is not blocked by another open issue.
-
-## Workflow
-
-1. **Explore** — read the issue carefully. Pull in the parent PRD if referenced. Read the relevant source files and tests before writing any code.
-2. **Plan** — decide what to change and why. Keep the change as small as possible.
-3. **Execute** — use RGR (Red → Green → Repeat → Refactor): write a failing test first, then write the implementation to pass it.
-4. **Verify** — read the repository's configured feedback-loop contract and run every applicable check for this change. Use the configured static check and focused behavior tests when they exist; include formatting, build, or broader checks when the contract or change requires them. Fix failures before proceeding.
-5. **Commit** — make a single git commit. The message MUST:
-   - Start with `RALPH:` prefix
-   - Include the task completed and any PRD reference
-   - List key decisions made
-   - List files changed
-   - Note any blockers for the next iteration
-6. **Close** — close the issue with `{{CLOSE_TASK_COMMAND}}` explaining what was done.
-
-## Rules
-
-- Work on **one issue per iteration**. Do not attempt multiple issues in a single iteration.
-- Do not close an issue until you have committed the fix and verified tests pass.
-- Do not leave commented-out code or TODO comments in committed code.
-- If you are blocked (missing context, failing tests you cannot fix, external dependency), leave a comment on the issue and move on — do not close it.
+<handoff>...</handoff>
+<promise>COMPLETE</promise>
 
-# Done
+## Resolved scope
 
-When all actionable issues are complete (or you are blocked on all remaining ones), or the open-issues block at the top of this prompt is empty, output the completion signal:
+```json
+{{SCOPE}}
+```
 
-<promise>COMPLETE</promise>
+Read the complete parent and child issue bodies and comments with `gh issue view`, including repository guidance and dependency links.