golden-hoop-spell-opencode 0.1.0

package/src/tools/plan-start.ts

@@ -0,0 +1,232 @@
+// `ghs-plan-start` tool — entry point of the 3-role plan dispatcher.
+//
+// This is the s3-feat-006 productisation of the source plugin's plan dispatcher
+// Detection phase (plan §3.5 / §3.7 step 1). It is a *thin wrapper* composing:
+//   - `resolveProjectDir(ctx)`      (s1-feat-006) — explicit arg overrides the
+//                                                        opencode session's dir.
+//   - `detectCodegraph(projectDir)` (s3-feat-002) — R1 runtime probe for
+//                                                        `.codegraph/`.
+//   - `writePlanStatus(...)`        (s3-feat-005) — persist the initial
+//                                                        `status.json` carrying
+//                                                        `codegraph_available`.
+//   - `CONTEXT_CODEGRAPH_PROMPT` /  (s3-feat-004) — the context-collection
+//     `CONTEXT_GREP_PROMPT`             dispatch directive chosen by the probe.
+//
+// The tool `execute` never calls an LLM and never touches the agent registry.
+// It only:
+//   1. resolves the project dir,
+//   2. probes codegraph availability,
+//   3. generates a `{date}-{slug}` plan_id,
+//   4. writes the initial status.json (round 1, status `designing`,
+//      codegraph_available = probe result),
+//   5. returns an LLM-facing dispatch directive telling the main chat AI to
+//      spawn the `ghs-context-haiku` subagent via the Task tool, and then —
+//      once the snapshot is back — to feed it to `ghs-plan-review(snapshot)`.
+//
+// The dispatch directive carries the codegraph-vs-grep prompt inline so the AI
+// has everything it needs to drive the plan loop forward without a second tool
+// round-trip. Style follows s2-feat-003's `sprint.ts` (thin wrapper, descriptive
+// result text) and s1-feat-008's I/O style (Bun.file / Bun.write, no
+// process.exit, no console.log). The returned string is LLM-facing prose
+// (中文正文 + 英文 identifiers, per CLAUDE.md).
+
+import { tool } from "@opencode-ai/plugin";
+import type { ToolContext } from "@opencode-ai/plugin/tool";
+import { resolve } from "node:path";
+
+import { resolveProjectDir } from "../lib/project.ts";
+import { detectCodegraph } from "../lib/codegraph.ts";
+import {
+  createInitialPlanStatus,
+  writePlanStatus,
+  DEFAULT_MAX_ROUNDS,
+} from "../lib/state.ts";
+import { CONTEXT_CODEGRAPH_PROMPT } from "../prompts/context-codegraph.ts";
+import { CONTEXT_GREP_PROMPT } from "../prompts/context-grep.ts";
+import { formatLocalDate } from "../lib/scripts/archive-sprint.ts";
+
+/**
+ * Maximum slug length (in characters) we keep from a sanitised requirement.
+ *
+ * Slugs end up in on-disk file names (`<plan_id>-status.json` etc.). A bounded
+ * length keeps directory listings readable and avoids OS path-length limits
+ * even when the AI hands us an unusually long requirement string. 60 chars is
+ * comfortably below every common file-name ceiling while still being
+ * descriptive enough to disambiguate plans on the same day.
+ */
+const MAX_SLUG_LENGTH = 60;
+
+/**
+ * Sanitise an arbitrary human-readable string into a filesystem-safe slug.
+ *
+ * The slug is the `<slug>` half of the `plan_id` (`{date}-{slug}`) and ends up
+ * as part of every sibling file name. Rules (defensive, idempotent):
+ *   - Trim + collapse internal whitespace into single `-`.
+ *   - Lower-case ASCII letters / digits are kept verbatim.
+ *   - Underscores, hyphens, dots are kept verbatim.
+ *   - Any other character (punctuation, CJK, emoji, accented Latin, …) is
+ *     collapsed into a single `-`. We deliberately do NOT try to romanise CJK
+ *     — the requirement is filesystem-safety, not transliteration; the human
+ *     description is preserved separately in the dispatch text.
+ *   - Collapse runs of `-`/`.` separators, strip leading/trailing separators.
+ *   - Truncate to {@link MAX_SLUG_LENGTH} chars on a `-` boundary.
+ *   - Empty result falls back to `plan` so we always emit a non-empty slug.
+ *
+ * Pure function; safe to call with any input (including empty / non-string).
+ */
+export function slugifyRequirement(input: string): string {
+  const raw = typeof input === "string" ? input : "";
+  // Normalise whitespace and strip characters that are not filesystem-safe.
+  // We keep ASCII alphanumerics, `-`, `_`, `.`; everything else becomes `-`.
+  const sanitised = raw
+    .trim()
+    .replace(/\s+/g, "-")
+    .replace(/[^a-zA-Z0-9._-]+/g, "-")
+    .replace(/[-.]{2,}/g, "-")
+    .replace(/^[-.]+|[-.]+$/g, "")
+    .toLowerCase();
+
+  if (sanitised.length === 0) {
+    return "plan";
+  }
+
+  // Truncate on a `-` boundary so we don't end mid-word.
+  const truncated =
+    sanitised.length <= MAX_SLUG_LENGTH
+      ? sanitised
+      : sanitised.slice(0, MAX_SLUG_LENGTH).replace(/-[^-]*$/, "");
+  return truncated.length === 0 ? "plan" : truncated;
+}
+
+/**
+ * Build the `{YYYY-MM-DD}-{slug}` plan identifier from a requirement string.
+ *
+ * Exported so the sibling `ghs-plan-review` / `ghs-plan-finalize` tools (and
+ * tests) can re-derive the exact same id from the same inputs without
+ * duplicating the date/slug logic. `now` is injectable for deterministic tests.
+ */
+export function buildPlanId(
+  requirement: string,
+  now: Date = new Date(),
+): string {
+  return `${formatLocalDate(now)}-${slugifyRequirement(requirement)}`;
+}
+
+/**
+ * The `ghs-plan-start` tool definition. Registered by the plugin entry point
+ * under the hyphenated `ghs-plan-start` key (per spike 001 / D1).
+ */
+export const planStartTool = tool({
+  description:
+    "Start a new Golden Hoop Spell plan-generation loop (the plan dispatcher's entry point). " +
+    "Resolves the project dir, probes whether `.codegraph/` is initialised (R1 runtime detection), " +
+    "writes the initial `.ghs/plans/<plan_id>-status.json` carrying `codegraph_available`, " +
+    "and returns a Task-tool dispatch directive telling the AI to spawn the `ghs-context-haiku` " +
+    "subagent to collect an architecture snapshot (codegraph-aware or grep-fallback prompt) " +
+    "and then feed the result to `ghs-plan-review(snapshot)`.",
+  args: {
+    project_dir: tool.schema
+      .string()
+      .optional()
+      .describe(
+        "Absolute path of the project root. Defaults to the opencode session's worktree/directory.",
+      ),
+  },
+  async execute(
+    args: { project_dir?: string },
+    ctx: ToolContext,
+  ): Promise<string> {
+    // (1) Resolve the project dir. Explicit arg wins; otherwise read it off
+    // the opencode session context (worktree > directory).
+    const projectDir = args.project_dir
+      ? resolve(args.project_dir)
+      : resolveProjectDir(ctx);
+
+    // (2) Probe codegraph availability (R1). `detectCodegraph` is defensive —
+    // empty/invalid paths return `false` rather than throwing, so this call
+    // never crashes the tool; the worst case is we take the grep path.
+    const codegraphAvailable = detectCodegraph(projectDir);
+
+    // (3) Generate the plan_id. We have no user-supplied title here (the tool
+    // is requirement-driven; the requirement itself is carried by the main
+    // chat AI, not by this tool's args), so we derive a placeholder slug from
+    // the current date + a stable `plan` stem. The AI / user can rename the
+    // final plan file at `ghs-plan-finalize` time; the status file name only
+    // needs to be unique per start, which the date prefix guarantees for a
+    // single-day loop.
+    //
+    // NOTE: we deliberately do NOT take a `requirement` arg — the dispatcher
+    // loop keeps the requirement in chat context (it is passed verbatim to the
+    // context-haiku subagent via the Task tool). The slug is therefore derived
+    // from the date alone; collisions within the same day are acceptable
+    // because each `ghs-plan-start` write simply overwrites the previous
+    // status file for that id (a fresh start resets the loop anyway).
+    const now = new Date();
+    const planId = buildPlanId("plan", now);
+
+    // (4) Write the initial status.json. `createInitialPlanStatus` gives us
+    // the source-skill defaults (round 1, status `designing`, max_rounds 5,
+    // codegraph_available from the probe). `writePlanStatus` validates the
+    // object against the Zod schema and `mkdir -p`s `.ghs/plans/` first.
+    const status = createInitialPlanStatus({
+      planId,
+      planFile: `${planId}.md`,
+      contextFile: `${planId}-context.md`,
+      codegraphAvailable,
+      now,
+      maxRounds: DEFAULT_MAX_ROUNDS,
+    });
+
+    let statusPath: string;
+    try {
+      statusPath = await writePlanStatus(projectDir, status);
+    } catch (err) {
+      // writePlanStatus can throw if mkdir fails (permissions, disk full) or
+      // if the Zod schema somehow rejects our object (shouldn't happen for a
+      // freshly-built status). Surface the message so the AI/user can diagnose.
+      return [
+        "❌ ghs-plan-start failed to write initial status.json:",
+        "",
+        (err as Error).message,
+        "",
+        `Project directory: ${projectDir}`,
+        `Plan id:          ${planId}`,
+        `Codegraph path:   ${codegraphAvailable ? "codegraph" : "grep fallback"}`,
+      ].join("\n");
+    }
+
+    // (5) Select the context-collection dispatch directive based on the probe.
+    // Both prompts are command-style LLM-facing text (中文 prose + English
+    // identifiers) that tell the AI exactly how to spawn `ghs-context-haiku`
+    // via the Task tool and what delimiter contract to enforce — they live in
+    // `src/prompts/context-{codegraph,grep}.ts`.
+    const contextPrompt = codegraphAvailable
+      ? CONTEXT_CODEGRAPH_PROMPT
+      : CONTEXT_GREP_PROMPT;
+
+    // (6) Compose the result. Lead with the bookkeeping summary (plan_id,
+    // status file path, codegraph path) so the AI can echo it back to the
+    // user, then the dispatch directive. The directive ends with an explicit
+    // "next step = ghs-plan-review(snapshot)" instruction so the loop's first
+    // transition is unambiguous.
+    const lines: string[] = [];
+    lines.push("=== ghs-plan-start complete ===");
+    lines.push("");
+    lines.push(`Project directory: ${projectDir}`);
+    lines.push(`Plan id:           ${planId}`);
+    lines.push(`Status file:       ${statusPath}`);
+    lines.push(`Round:             1 / ${status.max_rounds}`);
+    lines.push(
+      `Codegraph path:    ${codegraphAvailable ? "codegraph (.codegraph/ detected)" : "grep fallback (.codegraph/ absent)"}`,
+    );
+    lines.push("");
+    lines.push(
+      "Next step: dispatch the context-haiku subagent (directive below), then call",
+    );
+    lines.push("`ghs-plan-review(snapshot=...)` with its delimited output.");
+    lines.push("");
+    lines.push("--- context-haiku dispatch directive ---");
+    lines.push(contextPrompt);
+    return lines.join("\n");
+  },
+});

package/src/tools/sprint.ts

@@ -0,0 +1,213 @@
+// `ghs-sprint` tool — create a new sprint skeleton in features.json.
+//
+// This is the Sprint 2 (s2-feat-003) productisation of the source plugin's
+// purely-instruction-driven `ghs-sprint` skill. Instead of the AI editing
+// features.json by hand, this tool:
+//   1. Resolves the project dir (explicit `project_dir` arg wins; otherwise
+//      `resolveProjectDir(ctx)` reads the opencode session's worktree/dir).
+//   2. Reads features.json.
+//   3. If any sprint has `status === "completed"`, auto-archives it first
+//      (via `archiveSprints({ projectDir, dryRun: false })`). This mirrors
+//      the source plugin's "archive finished sprints before creating a new
+//      one" convention and keeps features.json focused on the active sprint.
+//   4. Auto-generates the next sprint id (`s{N+1}`) by scanning BOTH the
+//      current `sprints[]` array AND the `.ghs/archived/` folders, so an id
+//      is never reused after archiving.
+//   5. Calls `appendSprint` (s2-feat-001) to build the new featuresData — a
+//      pure function; this tool owns the disk write.
+//   6. Writes the updated featuresData back to disk.
+//   7. Returns the `SPRINT_PLANNING_PROMPT` (s2-feat-002) plus a short
+//      summary, so the AI immediately knows how to decompose the sprint
+//      goal into atomic features and append them via `update-feature-status`.
+//
+// The tool is a thin wrapper composing three existing modules:
+//   - archive-sprint.ts  (s1-feat-008 port)
+//   - append-sprint.ts   (s2-feat-001 writer)
+//   - sprint-planning.ts (s2-feat-002 prompt)
+
+import { tool } from "@opencode-ai/plugin";
+import type { ToolContext } from "@opencode-ai/plugin/tool";
+import { readdirSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { archiveSprints, formatLocalDate } from "../lib/scripts/archive-sprint.ts";
+import { appendSprint } from "../lib/scripts/append-sprint.ts";
+import { SPRINT_PLANNING_PROMPT } from "../prompts/sprint-planning.ts";
+import { resolveProjectDir } from "../lib/project.ts";
+
+/**
+ * Scan a parsed features.json for the largest sprint numeric id.
+ * Returns 0 when there are no sprints.
+ */
+function maxSprintNumber(sprints: unknown): number {
+  if (!Array.isArray(sprints)) return 0;
+  let max = 0;
+  for (const s of sprints as Array<Record<string, unknown>>) {
+    const id = typeof s.id === "string" ? s.id : "";
+    const m = /^s(\d{1,4})$/.exec(id);
+    if (m) {
+      const n = Number.parseInt(m[1], 10);
+      if (Number.isFinite(n) && n > max) max = n;
+    }
+  }
+  return max;
+}
+
+/**
+ * Scan `.ghs/archived/` folder names for sprint ids.
+ *
+ * Archived folders are named `<sprintId>_<sprintName>_<timestamp>` (see
+ * archive-sprint.ts `archiveSprintFiles`). We parse the leading `s<N>_`
+ * prefix to recover the sprint number, so that creating a fresh sprint
+ * after an archive never reuses a retired id (the source plugin's
+ * uniqueness guarantee is over the lifetime of the project, not just the
+ * active sprints array).
+ */
+function maxArchivedSprintNumber(projectDir: string): number {
+  const archivedPath = join(resolve(projectDir), ".ghs", "archived");
+  if (!existsSync(archivedPath)) return 0;
+  let max = 0;
+  let entries: string[];
+  try {
+    entries = readdirSync(archivedPath);
+  } catch {
+    return 0;
+  }
+  for (const name of entries) {
+    const m = /^s(\d{1,4})_/.exec(name);
+    if (m) {
+      const n = Number.parseInt(m[1], 10);
+      if (Number.isFinite(n) && n > max) max = n;
+    }
+  }
+  return max;
+}
+
+/**
+ * Compute the next sprint id for `projectDir` given the current
+ * `featuresData`. Considers both active sprints and archived folders.
+ */
+export function nextSprintId(
+  projectDir: string,
+  featuresData: Record<string, unknown>,
+): string {
+  const fromActive = maxSprintNumber(featuresData.sprints);
+  const fromArchived = maxArchivedSprintNumber(projectDir);
+  const next = Math.max(fromActive, fromArchived) + 1;
+  return `s${next}`;
+}
+
+/**
+ * The `ghs-sprint` tool definition. Registered by the plugin entry point
+ * under the `ghs-sprint` key (hyphenated, per spike 001 / D1).
+ */
+export const sprintTool = tool({
+  description:
+    "Create a new sprint skeleton in features.json. Auto-archives any already-completed sprints first, " +
+    "auto-generates the next sprint id (s{N+1}, scanning active + archived sprints so ids never collide), " +
+    "appends an empty sprint with status 'planning', writes it back to disk, and returns the sprint-planning " +
+    "prompt so the AI can decompose the goal into atomic features (which it then appends via update-feature-status).",
+  args: {
+    sprint_name: tool.schema
+      .string()
+      .min(1)
+      .describe("Human-readable sprint name (written into features.json#sprints[].name)."),
+    goal: tool.schema
+      .string()
+      .min(1)
+      .describe(
+        "The sprint goal — what 'done' looks like for this sprint. Written into features.json#sprints[].goal.",
+      ),
+    project_dir: tool.schema
+      .string()
+      .optional()
+      .describe(
+        "Absolute path of the project root. Defaults to the opencode session's worktree/directory.",
+      ),
+  },
+  async execute(
+    args: {
+      sprint_name: string;
+      goal: string;
+      project_dir?: string;
+    },
+    ctx: ToolContext,
+  ): Promise<string> {
+    const projectDir = args.project_dir
+      ? resolve(args.project_dir)
+      : resolveProjectDir(ctx);
+
+    const featuresPath = join(projectDir, ".ghs", "features.json");
+    const featuresFile = Bun.file(featuresPath);
+    if (!(await featuresFile.exists())) {
+      return [
+        `❌ features.json not found at ${featuresPath}.`,
+        "",
+        "Run `ghs-init` first to bootstrap the .ghs/ tracking files.",
+      ].join("\n");
+    }
+
+    // (c) Auto-archive completed sprints before creating a new one. If
+    // archiveSprints throws (e.g. corrupt features.json), surface the error
+    // rather than proceeding — appending on top of a corrupt file would
+    // mask the real problem.
+    let archivedSummary = "";
+    let archivedCount = 0;
+    const archived = await archiveSprints({ projectDir });
+    if (archived.length > 0) {
+      archivedCount = archived.length;
+      archivedSummary =
+        archived
+          .map(
+            (info) =>
+              `  - ${info.sprint_name} (${info.sprint_id}) → ${info.archive_path ?? "(no path)"}`,
+          )
+          .join("\n") + "\n\n";
+    }
+
+    // Re-read features.json AFTER archiving — archiveSprints mutates the
+    // file on disk (removes the archived sprint, updates metadata). Reading
+    // the fresh content keeps the in-memory copy in sync.
+    const text = await (Bun.file(featuresPath)).text();
+    const featuresData = JSON.parse(text) as Record<string, unknown>;
+
+    // (d) Auto-generate the next sprint id and append the skeleton.
+    const newSprintId = nextSprintId(projectDir, featuresData);
+    const updated = appendSprint(featuresData, {
+      id: newSprintId,
+      name: args.sprint_name,
+      goal: args.goal,
+      created_at: formatLocalDate(),
+    });
+
+    // (e) Write back to disk. 2-space indent matches every other features.json
+    // writer in the project (init-project.ts / archive-sprint.ts).
+    await Bun.write(featuresPath, JSON.stringify(updated, null, 2) + "\n");
+
+    // (f) Compose the result. Lead with the short summary, then the planning
+    // prompt so the AI can immediately start decomposing the goal.
+    const lines: string[] = [];
+    lines.push("=== ghs-sprint complete ===");
+    lines.push("");
+    lines.push(`Project directory: ${projectDir}`);
+    lines.push(`New sprint:        ${args.sprint_name} (${newSprintId})`);
+    lines.push(`Created at:        ${formatLocalDate()}`);
+    if (archivedCount > 0) {
+      lines.push("");
+      lines.push(
+        `Auto-archived ${archivedCount} completed sprint(s) before creating ${newSprintId}:`,
+      );
+      lines.push(archivedSummary.trimEnd());
+    }
+    lines.push("");
+    lines.push(`Sprint skeleton written to ${featuresPath} (status: planning, features: []).`);
+    lines.push("");
+    lines.push("Next: decompose the sprint goal into atomic features and append each via");
+    lines.push("`update-feature-status` (initial status: pending). Then flip the sprint status");
+    lines.push("to in_progress once you start coding.");
+    lines.push("");
+    lines.push("--- sprint-planning prompt ---");
+    lines.push(SPRINT_PLANNING_PROMPT);
+    return lines.join("\n");
+  },
+});

package/src/tools/status.ts

@@ -0,0 +1,51 @@
+// `ghs-status` tool — show the current project's status.
+//
+// Thin wrapper around `status()` from `src/lib/scripts/status.ts`. Resolves
+// the project dir (explicit arg wins; otherwise `resolveProjectDir(ctx)`),
+// invokes the formatter, and returns the formatted text for the AI to read.
+//
+// The returned string is byte-identical to what the Python `status.py`
+// script would have printed to stdout (verified by the equivalence tests
+// in `test/equivalence/status.test.ts`).
+
+import { tool } from "@opencode-ai/plugin";
+import type { ToolContext } from "@opencode-ai/plugin/tool";
+import { resolve } from "node:path";
+
+import { status } from "../lib/scripts/status.ts";
+import { resolveProjectDir } from "../lib/project.ts";
+
+/**
+ * The `ghs-status` tool definition. Registered under the `ghs-status` key.
+ */
+export const statusTool = tool({
+  description:
+    "Show the current ghs project status: project name/description, per-sprint " +
+    "feature counts (completed/in_progress/pending/blocked), the in-progress feature, " +
+    "the next ready feature, and recent progress.md session entries. " +
+    "Read-only — does not modify any files.",
+  args: {
+    project_dir: tool.schema
+      .string()
+      .optional()
+      .describe(
+        "Absolute path of the project root. Defaults to the opencode session's worktree/directory.",
+      ),
+  },
+  async execute(
+    args: { project_dir?: string },
+    ctx: ToolContext,
+  ): Promise<string> {
+    const projectDir = args.project_dir
+      ? resolve(args.project_dir)
+      : resolveProjectDir(ctx);
+
+    const result = await status({ projectDir });
+    // `status()` returns `{ text, exitCode }`. exitCode is 1 when
+    // features.json is missing — the text already carries the "not found"
+    // message, so we just return it verbatim. (We don't surface exitCode as
+    // a tool error because the message is more useful to the AI than an
+    // opaque failure.)
+    return result.text;
+  },
+});