golden-hoop-spell-opencode 0.1.0

package/src/lib/nonce.ts

@@ -0,0 +1,56 @@
+// Transcription nonce gate for `ghs-force-archive`.
+//
+// `ghs-force-archive` archives ALL sprints regardless of status — destructive.
+// The source Claude Code plugin (see
+// `plugin/skills/ghs-force-archive/SKILL.md`) gates the archive behind an
+// explicit user confirmation: the agent shows the nonce and asks the user to
+// transcribe it back before proceeding. We replicate that gate here.
+//
+// Comparison semantics (must match the source behaviour):
+//   - Case-insensitive: `AbC123` matches `abc123`.
+//   - Whitespace-trimmed: leading/trailing whitespace on either side is
+//     stripped before comparison. Internal whitespace is preserved.
+//
+// The nonce is a random alphanumeric string — short enough to transcribe,
+// long enough that a careless "yes" / "confirmed" won't accidentally match.
+
+const NONCE_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+const NONCE_LENGTH = 8;
+
+/**
+ * Generate a random alphanumeric nonce suitable for transcription comparison.
+ *
+ * Uses `crypto.getRandomValues` for cryptographic randomness. The result is
+ * 8 characters drawn from `[A-Za-z0-9]`.
+ */
+export function generateNonce(): string {
+  const bytes = new Uint8Array(NONCE_LENGTH);
+  crypto.getRandomValues(bytes);
+  let out = "";
+  for (let i = 0; i < NONCE_LENGTH; i++) {
+    out += NONCE_ALPHABET[bytes[i] % NONCE_ALPHABET.length];
+  }
+  return out;
+}
+
+/**
+ * Verify that a user-supplied transcription matches the issued nonce.
+ *
+ * Comparison is case-insensitive and trims leading/trailing whitespace on
+ * both inputs before comparing. Returns `true` only if the normalised forms
+ * are byte-identical.
+ *
+ * @param nonce        - the nonce originally issued by `generateNonce()`.
+ * @param transcription - the string the user typed back.
+ */
+export function verifyTranscribeNonce(nonce: string, transcription: string): boolean {
+  if (typeof nonce !== "string" || typeof transcription !== "string") {
+    return false;
+  }
+  const a = nonce.trim().toLowerCase();
+  const b = transcription.trim().toLowerCase();
+  if (a.length === 0 || b.length === 0) {
+    return false;
+  }
+  return a === b;
+}

package/src/lib/parse.ts

@@ -0,0 +1,175 @@
+// Thin convenience wrappers around `src/lib/scripts/parse-delimited-output.ts`.
+//
+// The delimited-output parser is the core extraction primitive the plan
+// dispatcher uses to pull structured content out of subagent responses. The
+// underlying `parseDelimitedOutput()` is fully generic (arbitrary `kind`,
+// custom tokens, configurable min length). The three plan tools
+// (`ghs-plan-review` in its three modes) all want the *same* canned
+// configuration — one per subagent output family — so this module centralises
+// those presets. That keeps the tool layer readable and makes the delimiter /
+// signal / min-length contract a single source of truth.
+//
+// This file deliberately adds NO new parsing logic — every behaviour path
+// delegates to the ported parser, preserving the equivalence guarantee
+// established by `test/equivalence/parse-delimited-output.test.ts`. Style
+// follows s2-feat-001: pure re-exports + thin wrappers, no I/O, no
+// `process.exit`, no `console.log`.
+
+import {
+  parseDelimitedOutput,
+  type ParseDelimitedOutputArgs,
+  type ParseResult,
+  type Verdict,
+} from "./scripts/parse-delimited-output.ts";
+
+// -----------------------------------------------------------------------------
+// Re-exports — give the plan tools a single import surface for the parser.
+// -----------------------------------------------------------------------------
+
+export {
+  parseDelimitedOutput,
+  serializeResult,
+  type ParseDelimitedOutputArgs,
+  type ParseResult,
+  type ParseStatus,
+  type ParseStrategy,
+  type Verdict,
+} from "./scripts/parse-delimited-output.ts";
+
+// -----------------------------------------------------------------------------
+// Completion-signal constants per subagent family.
+// -----------------------------------------------------------------------------
+
+/**
+ * Completion-signal line the `plan-designer` subagent prints at the end of its
+ * response. The parser strips this line (and anything after) from the
+ * extracted content and surfaces it in `ParseResult.completion_signal`.
+ *
+ * Mirrors the source skill's `PLAN DESIGN COMPLETE` signal (the parser's
+ * `stripCompletionSignal` helper is line-anchored and word-boundary aware, so
+ * trailing variables like `| Verdict: PASS` ride along on the same line).
+ */
+export const PLAN_COMPLETION_SIGNAL = "PLAN DESIGN COMPLETE";
+
+/**
+ * Completion-signal line the `plan-reviewer` subagent prints. Carries the
+ * `Verdict: PASS|FAIL` marker the dispatcher keys off.
+ */
+export const REVIEW_COMPLETION_SIGNAL = "PLAN REVIEW COMPLETE";
+
+/**
+ * Completion-signal line the `ghs-context-haiku` subagent prints when it
+ * finishes emitting the architecture snapshot.
+ */
+export const CONTEXT_SNAPSHOT_COMPLETION_SIGNAL = "CONTEXT SNAPSHOT COMPLETE";
+
+// -----------------------------------------------------------------------------
+// Preset wrappers — one per subagent output family.
+// -----------------------------------------------------------------------------
+
+/**
+ * Default minimum stripped-content length. Subagent outputs shorter than this
+ * after extraction are classified as `empty` (the parser found *something* but
+ * it was too short to be a real artefact) rather than `ok`. Mirrors the
+ * parser's own `DEFAULT_MIN_LENGTH`; re-exposed here so tool-layer callers can
+ * reference a named constant instead of magic-numbering `200`.
+ */
+export const DEFAULT_MIN_LENGTH = 200;
+
+/**
+ * Parse a `plan-designer` subagent response.
+ *
+ * Pre-configures the `kind: "plan"` delimiter family (`<<<PLAN_START>>>` /
+ * `<<<PLAN_END>>>`), the `PLAN DESIGN COMPLETE` completion signal, and the
+ * default min length. The caller just hands over the raw subagent text.
+ *
+ * @param text       - raw response from the `ghs-plan-designer` subagent.
+ * @param overrides  - optional per-call overrides (e.g. a larger `minLength`
+ *                     for a plan expected to be long). Merged into the preset.
+ */
+export function parsePlan(
+  text: string,
+  overrides: Partial<ParseDelimitedOutputArgs> = {},
+): ParseResult {
+  return parseDelimitedOutput(text, {
+    kind: "plan",
+    completionSignal: PLAN_COMPLETION_SIGNAL,
+    minLength: DEFAULT_MIN_LENGTH,
+    ...overrides,
+  });
+}
+
+/**
+ * Parse a `plan-reviewer` subagent response.
+ *
+ * Pre-configures the `kind: "review"` delimiter family
+ * (`<<<REVIEW_START>>>` / `<<<REVIEW_END>>>`) and the `PLAN REVIEW COMPLETE`
+ * completion signal. The parser automatically extracts the `Verdict: PASS|FAIL`
+ * marker for review-kind input and surfaces it on `ParseResult.verdict`; use
+ * {@link extractVerdict} to pull it out cleanly.
+ *
+ * @param text       - raw response from the `ghs-plan-reviewer` subagent.
+ * @param overrides  - optional per-call overrides.
+ */
+export function parseReview(
+  text: string,
+  overrides: Partial<ParseDelimitedOutputArgs> = {},
+): ParseResult {
+  return parseDelimitedOutput(text, {
+    kind: "review",
+    completionSignal: REVIEW_COMPLETION_SIGNAL,
+    minLength: DEFAULT_MIN_LENGTH,
+    ...overrides,
+  });
+}
+
+/**
+ * Parse a `ghs-context-haiku` subagent response.
+ *
+ * Pre-configures the `kind: "context_snapshot"` delimiter family
+ * (`<<<CONTEXT_SNAPSHOT_START>>>` / `<<<CONTEXT_SNAPSHOT_END>>>`) and the
+ * `CONTEXT SNAPSHOT COMPLETE` completion signal.
+ *
+ * @param text       - raw response from the `ghs-context-haiku` subagent.
+ * @param overrides  - optional per-call overrides.
+ */
+export function parseContextSnapshot(
+  text: string,
+  overrides: Partial<ParseDelimitedOutputArgs> = {},
+): ParseResult {
+  return parseDelimitedOutput(text, {
+    kind: "context_snapshot",
+    completionSignal: CONTEXT_SNAPSHOT_COMPLETION_SIGNAL,
+    minLength: DEFAULT_MIN_LENGTH,
+    ...overrides,
+  });
+}
+
+// -----------------------------------------------------------------------------
+// Verdict helper
+// -----------------------------------------------------------------------------
+
+/**
+ * Extract a `PASS` / `FAIL` verdict from a review parse result.
+ *
+ * The parser already populates `ParseResult.verdict` for `kind: "review"`
+ * input; this helper just narrows the type and gives callers a single
+ * expression (`extractVerdict(result)`) instead of reaching into the result
+ * object directly. Returns `null` when no verdict marker was found — the
+ * dispatcher treats that as "reviewer did not emit a verdict" and prompts for
+ * a retry.
+ *
+ * Accepts either a full `ParseResult` or a bare `Verdict` so callers that
+ * already destructured the field can pass it through unchanged.
+ */
+export function extractVerdict(
+  input: ParseResult | Verdict,
+): Verdict {
+  if (input === null) {
+    return null;
+  }
+  if (typeof input === "string") {
+    return input;
+  }
+  return input.verdict;
+}

package/src/lib/paths.ts

@@ -0,0 +1,26 @@
+// Plugin root resolution.
+//
+// `import.meta.dir` is Bun's canonical primitive for "the directory of the
+// current source file". This file lives at `src/lib/paths.ts`, so two levels
+// up is the plugin package root (the directory containing `src/index.ts` and
+// `shared/`). We use this instead of `process.cwd()` or `__dirname` because:
+//
+//   - `process.cwd()` is the *host project's* working directory, not the
+//     plugin's install location — using it would resolve assets relative to
+//     the wrong tree entirely.
+//   - `__dirname` is a CommonJS construct; this package is `"type": "module"`.
+//
+// Spike 001 confirmed `import.meta.dir` works under Bun + opencode runtime.
+
+import { resolve } from "node:path";
+
+/**
+ * Returns the absolute path to the directory containing `src/index.ts` —
+ * i.e. the plugin package root. Under that root live `src/`, `shared/`,
+ * `package.json`, etc.
+ */
+export function pluginRoot(): string {
+  // `import.meta.dir` = absolute path to `src/lib/` (this file's directory).
+  // Two `..` segments climb to the plugin package root.
+  return resolve(import.meta.dir, "..", "..");
+}

package/src/lib/project.ts

@@ -0,0 +1,28 @@
+// Resolve the active project directory from an OpenCode tool context.
+//
+// `ToolContext` exposes two path fields:
+//   - `worktree`:  the project worktree root (stable across agent working dirs)
+//   - `directory`: the per-session working directory (may be a subdir)
+//
+// Per the feature spec we prefer `worktree` when set so writes land in a
+// stable location regardless of which subdirectory the agent is currently
+// operating in. We fall back to `directory` when `worktree` is empty.
+//
+// Note: this is the OpenCode TS port. The source Python script
+// `plugin/shared/scripts/resolve_project_dir.py` walks up from a start dir
+// looking for `.ghs/features.json`. Here we don't walk — we trust the
+// context's fields, which the runtime has already resolved for us. The
+// walk-up behaviour is implemented separately in `scripts/resolve-project-dir.ts`
+// (s1-feat-008) for parity with the Python entry-point script.
+
+import type { ToolContext } from "@opencode-ai/plugin/tool";
+
+/**
+ * Resolve the project directory the plugin should read/write under.
+ *
+ * @param ctx - the OpenCode tool execution context.
+ * @returns `ctx.worktree` when non-empty, otherwise `ctx.directory`.
+ */
+export function resolveProjectDir(ctx: ToolContext): string {
+  return ctx.worktree || ctx.directory;
+}

package/src/lib/scripts/append-progress-session.ts

@@ -0,0 +1,178 @@
+// Insert a new progress session entry into a progress.md document (in-memory).
+//
+// This is one of the three "writer" modules introduced in s2-feat-001. Like
+// its siblings it has no source-plugin Python equivalent — the source
+// `ghs-sprint` skill had the AI edit progress.md directly. This module
+// refactors that into a pure function that returns the updated markdown.
+//
+// Design principles match append-sprint.ts / update-feature-status.ts: pure
+// function, no I/O, no stdout, no process.exit, immutable return, Zod-validated
+// session object.
+
+import { z } from "zod";
+
+// -----------------------------------------------------------------------------
+// Schema
+// -----------------------------------------------------------------------------
+
+/**
+ * Zod schema for a single progress session.
+ *
+ * The rendered markdown mirrors the `## Session Template` block in
+ * `shared/assets/progress.md`. Required fields are the ones that make a session
+ * identifiable and useful; the rest are optional so a minimal session still
+ * renders cleanly.
+ *
+ * - `title`: the `## Session N - YYYY-MM-DD` heading line (without the leading
+ *   `## `). Required.
+ * - `agent`: rendered as `**Agent**: <value>`.
+ * - `sprint`, `feature`: optional metadata lines.
+ * - `work_completed`, `tests_performed`, `issues`, `decisions`, `next_steps`:
+ *   optional string arrays rendered as `- <item>` bullet lists under their
+ *   respective `### ` sub-headings.
+ */
+const stringList = z.array(z.string()).default([]);
+
+export const ProgressSessionSchema = z.object({
+  title: z.string().min(1, "title is required"),
+  agent: z.string().min(1, "agent is required"),
+  sprint: z.string().optional(),
+  feature: z.string().optional(),
+  work_completed: stringList,
+  tests_performed: stringList,
+  issues: stringList,
+  decisions: stringList,
+  next_steps: stringList,
+});
+
+export type ProgressSession = z.infer<typeof ProgressSessionSchema>;
+
+// -----------------------------------------------------------------------------
+// Renderer
+// -----------------------------------------------------------------------------
+
+/**
+ * Render a {@link ProgressSession} as a markdown block (without a trailing
+ * newline beyond the single one that ends the block).
+ *
+ * Section sub-headings are always emitted (even when the list is empty) so the
+ * shape matches the `## Session Template` in `shared/assets/progress.md` — this
+ * keeps the file skimmable and gives the AI consistent anchors to fill in
+ * later.
+ */
+export function renderSession(session: ProgressSession): string {
+  const lines: string[] = [];
+  lines.push(`## ${session.title}`);
+  lines.push(`**Agent**: ${session.agent}`);
+  if (session.sprint !== undefined && session.sprint !== "") {
+    lines.push(`**Sprint**: ${session.sprint}`);
+  }
+  if (session.feature !== undefined && session.feature !== "") {
+    lines.push(`**Feature**: ${session.feature}`);
+  }
+  lines.push("");
+  lines.push("### Work Completed");
+  if (session.work_completed.length > 0) {
+    for (const item of session.work_completed) lines.push(`- ${item}`);
+  }
+  lines.push("");
+  lines.push("### Tests Performed");
+  if (session.tests_performed.length > 0) {
+    for (const item of session.tests_performed) lines.push(`- ${item}`);
+  }
+  lines.push("");
+  lines.push("### Issues Encountered");
+  if (session.issues.length > 0) {
+    for (const item of session.issues) lines.push(`- ${item}`);
+  }
+  lines.push("");
+  lines.push("### Decisions Made");
+  if (session.decisions.length > 0) {
+    for (const item of session.decisions) lines.push(`- ${item}`);
+  }
+  lines.push("");
+  lines.push("### Next Steps");
+  if (session.next_steps.length > 0) {
+    for (const item of session.next_steps) lines.push(`- ${item}`);
+  }
+  return lines.join("\n");
+}
+
+// -----------------------------------------------------------------------------
+// Writer
+// -----------------------------------------------------------------------------
+
+/**
+ * Insert `session` into `progressMd` immediately after the `## Sessions`
+ * heading and before the first existing session entry, so the newest session
+ * stays at the top.
+ *
+ * Behavior:
+ *   1. Validate `session` against {@link ProgressSessionSchema} (throws
+ *      ZodError on invalid input).
+ *   2. Locate the `## Sessions` heading (matched case-sensitively as a line
+ *      starting with `## Sessions`). If missing, throw a descriptive Error —
+ *      appending to a progress.md without the anchor would silently corrupt
+ *      the document structure.
+ *   3. Find the position of the first *existing session entry*: the next
+ *      `## ` heading after `## Sessions` that is NOT `## Sessions` itself. This
+ *      skips template scaffolding (HTML comments, the `## Session Template`
+ *      block that lives above `## Sessions`, etc.) and lands the new entry
+ *      directly above the previous newest session.
+ *   4. If no existing session entry exists, append at the end of the document.
+ *   5. Return the new markdown string. The new session is separated from
+ *      surrounding content by blank lines.
+ *
+ * This function does NOT write to disk. The caller (tool layer) is responsible
+ * for persistence.
+ */
+export function appendProgressSession(
+  progressMd: string,
+  session: ProgressSession,
+): string {
+  const validated = ProgressSessionSchema.parse(session);
+  const rendered = renderSession(validated);
+
+  const lines = progressMd.split("\n");
+
+  // Locate the `## Sessions` heading line. Matched case-sensitively and
+  // anchored so `## Session Template` (which lives above this heading in the
+  // default template) is not confused with it.
+  let sessionsHeadingIndex = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^##\s+Sessions\s*$/.test(lines[i])) {
+      sessionsHeadingIndex = i;
+      break;
+    }
+  }
+  if (sessionsHeadingIndex === -1) {
+    throw new Error(
+      "progress.md is missing the '## Sessions' heading — cannot insert session",
+    );
+  }
+
+  // Find the position immediately before the first existing session entry.
+  // An "existing session entry" is any `## ` heading that appears AFTER the
+  // `## Sessions` heading. Content between the heading and that first entry
+  // (e.g. the `<!-- New sessions should be added above this line -->`
+  // comment in the default template) is preserved verbatim and ends up below
+  // the newly inserted session — which is exactly the "newest on top"
+  // invariant the acceptance criterion asks for.
+  let firstEntryIndex = -1;
+  for (let i = sessionsHeadingIndex + 1; i < lines.length; i++) {
+    if (/^##\s+\S/.test(lines[i])) {
+      firstEntryIndex = i;
+      break;
+    }
+  }
+  // When there is no existing session entry, append at the end of the file.
+  const insertAt = firstEntryIndex === -1 ? lines.length : firstEntryIndex;
+
+  // Build the insertion: a blank line, the rendered session, a blank line.
+  // The trailing blank line guarantees separation from whatever follows
+  // (the first existing entry, or end-of-document).
+  const block = ["", rendered, ""];
+
+  const next = lines.slice(0, insertAt).concat(block, lines.slice(insertAt));
+  return next.join("\n");
+}

package/src/lib/scripts/append-sprint.ts

@@ -0,0 +1,121 @@
+// Append a new sprint to a features.json object (in-memory; no I/O).
+//
+// This is one of the three "writer" modules introduced in s2-feat-001. The
+// source plugin had no equivalent Python script — its `ghs-sprint` skill
+// instructed the AI to edit features.json directly with the Edit tool. This
+// module refactors that into "AI provides a spec, a pure function returns the
+// updated object" so the tool layer (s2-feat-003) controls disk persistence.
+//
+// Design principles (from s2-feat-001 technical_notes + s1-feat-008 style):
+//   - Pure function: no Bun.write / fs.writeFileSync. Persistence is the
+//     caller's responsibility.
+//   - No stdout / console.log.
+//   - No process.exit.
+//   - Zod-validated input spec.
+//   - Immutable: returns a NEW object; the input is not modified.
+//
+// Style mirrors archive-sprint.ts / init-project.ts.
+
+import { z } from "zod";
+
+// -----------------------------------------------------------------------------
+// Types
+// -----------------------------------------------------------------------------
+
+type JsonObject = Record<string, unknown>;
+export type FeaturesData = JsonObject;
+export type Sprint = JsonObject;
+
+// -----------------------------------------------------------------------------
+// Schema
+// -----------------------------------------------------------------------------
+
+/**
+ * Zod schema for the "append a sprint" spec.
+ *
+ * - `id`: matches the sprint ID format enforced by validate-structure.ts
+ *   (`^s\d{1,4}$`). We re-declare the pattern here rather than importing a
+ *   shared constant, to keep this module self-contained (consistent with the
+ *   no-cross-module-dependency style of the s1-feat-008 ports).
+ * - `name`, `goal`: non-empty strings.
+ * - `created_at`: `YYYY-MM-DD` (the same format init-project.ts emits via
+ *   `formatLocalDate`).
+ */
+const SPRINT_ID_PATTERN = /^s\d{1,4}$/;
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+export const AppendSprintSpecSchema = z.object({
+  id: z
+    .string()
+    .regex(
+      SPRINT_ID_PATTERN,
+      "sprint id must match ^s\\d{1,4}$ (e.g. s1, s12, s1234)",
+    ),
+  name: z.string().min(1, "name is required"),
+  goal: z.string().min(1, "goal is required"),
+  created_at: z
+    .string()
+    .regex(DATE_PATTERN, "created_at must be YYYY-MM-DD"),
+});
+
+export type AppendSprintSpec = z.infer<typeof AppendSprintSpecSchema>;
+
+// -----------------------------------------------------------------------------
+// Writer
+// -----------------------------------------------------------------------------
+
+/**
+ * Append a new (empty) sprint to `featuresData.sprints` and return a NEW
+ * featuresData object. The input is not modified.
+ *
+ * Behavior:
+ *   1. Validate `spec` against {@link AppendSprintSpecSchema} (throws ZodError
+ *      on invalid input).
+ *   2. Scan existing `sprints[].id` (treats a missing/empty array as "no
+ *      sprints") and throw a descriptive Error if `spec.id` already exists.
+ *   3. Return a shallow-cloned featuresData with a shallow-cloned `sprints`
+ *      array that has the new sprint appended. The new sprint carries an empty
+ *      `features: []` array and `status: "planning"` (matches the source
+ *      plugin's convention — a freshly created sprint starts in planning until
+ *      the AI finishes decomposing it into features).
+ *
+ * The clone strategy is intentionally shallow at the top level: existing
+ * sprint/feature objects are shared by reference (they are not mutated), while
+ * the container arrays and the new sprint object are fresh. This satisfies the
+ * "do not modify the input object" acceptance criterion without paying for a
+ * deep clone of potentially large feature trees.
+ */
+export function appendSprint(
+  featuresData: FeaturesData,
+  spec: AppendSprintSpec,
+): FeaturesData {
+  const validated = AppendSprintSpecSchema.parse(spec);
+
+  const sprints = Array.isArray(featuresData.sprints)
+    ? (featuresData.sprints as Sprint[])
+    : [];
+
+  // Uniqueness check — cross all existing sprints.
+  const clash = sprints.find((s) => s.id === validated.id);
+  if (clash !== undefined) {
+    throw new Error(
+      `Sprint id '${validated.id}' already exists ` +
+        `(name: ${JSON.stringify(clash.name ?? "<unnamed>")})`,
+    );
+  }
+
+  const newSprint: Sprint = {
+    id: validated.id,
+    name: validated.name,
+    goal: validated.goal,
+    status: "planning",
+    created_at: validated.created_at,
+    features: [],
+  };
+
+  // Shallow-clone the container so callers can safely keep using the original.
+  return {
+    ...featuresData,
+    sprints: [...sprints, newSprint],
+  };
+}