golden-hoop-spell-opencode 0.1.0

package/src/tools/force-archive.ts

@@ -0,0 +1,195 @@
+// `ghs-force-archive` tool — destructive archive of ALL sprints.
+//
+// Unlike `ghs-archive`, which only touches `status: completed` sprints, this
+// tool moves every sprint (including in_progress / planning / blocked ones)
+// into `.ghs/archived/`. It is the "I know what I'm doing, wipe it all"
+// escape hatch.
+//
+// Because that's destructive, we gate it behind a transcription nonce:
+//   - The user first calls `ghs-archive` (any mode). When there are any
+//     incomplete sprints, `ghs-archive` issues a random alphanumeric nonce
+//     and writes it to `.ghs/.force-archive-nonce`, surfacing it in the tool
+//     result.
+//   - The user then calls this tool with the nonce transcribed into the
+//     `transcription` arg. We read the nonce file, verify via
+//     `verifyTranscribeNonce`, and only then proceed.
+//   - The nonce is consumed (file deleted) on a successful verification so a
+//     captured nonce can't be replayed.
+//
+// Per the feature's `technical_notes` this is weaker than the source plugin's
+// `AskUserQuestion` sync-block (a nonce is guessable by a determined LLM),
+// but it satisfies the AC: "missing or incorrect transcription → error +
+// no archive; matching transcription → archive".
+
+import { tool } from "@opencode-ai/plugin";
+import type { ToolContext } from "@opencode-ai/plugin/tool";
+import { resolve, join } from "node:path";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+
+import {
+  archiveSprints,
+  getAllSprints,
+  formatArchiveReport,
+  type ArchivedSprintInfo,
+} from "../lib/scripts/archive-sprint.ts";
+import { verifyTranscribeNonce } from "../lib/nonce.ts";
+import { resolveProjectDir } from "../lib/project.ts";
+import { readNonce, nonceFilePath } from "./archive.ts";
+
+/** Load features.json. Returns null if missing. */
+async function loadFeaturesData(
+  projectDir: string,
+): Promise<Record<string, unknown> | null> {
+  const path = join(resolve(projectDir), ".ghs", "features.json");
+  if (!existsSync(path)) {
+    return null;
+  }
+  const text = await readFile(path, "utf8");
+  return JSON.parse(text) as Record<string, unknown>;
+}
+
+/**
+ * The `ghs-force-archive` tool definition. Registered under the
+ * `ghs-force-archive` key.
+ */
+export const forceArchiveTool = tool({
+  description:
+    "⚠️  Destructive: archive ALL sprints regardless of status (including in_progress / planning / blocked). " +
+    "Use `ghs-archive` instead for the normal completed-sprint flow. " +
+    "Requires a `transcription` token — call `ghs-archive` first; when incomplete sprints remain it will " +
+    "issue a nonce, which you transcribe back here to confirm. Without a matching transcription the tool " +
+    "refuses to archive anything.",
+  args: {
+    project_dir: tool.schema
+      .string()
+      .optional()
+      .describe(
+        "Absolute path of the project root. Defaults to the opencode session's worktree/directory.",
+      ),
+    transcription: tool.schema
+      .string()
+      .describe(
+        "The nonce token issued by a prior `ghs-archive` call (when incomplete sprints existed). " +
+          "Must match the issued nonce (case-insensitive, whitespace-trimmed) for the archive to proceed.",
+      ),
+  },
+  async execute(
+    args: { project_dir?: string; transcription: string },
+    ctx: ToolContext,
+  ): Promise<string> {
+    const projectDir = args.project_dir
+      ? resolve(args.project_dir)
+      : resolveProjectDir(ctx);
+
+    // ----- Pre-flight: does the project even have features.json? -----
+    const features = await loadFeaturesData(projectDir);
+    if (!features) {
+      return [
+        "=== Sprint Archiver (force) ===",
+        "",
+        `Project directory: ${projectDir}`,
+        "",
+        "❌ features.json not found. Run `ghs-init` first.",
+      ].join("\n") + "\n";
+    }
+
+    const allSprints = getAllSprints(features);
+    if (allSprints.length === 0) {
+      return formatArchiveReport({
+        projectDir,
+        mode: "archive",
+        force: true,
+        sprintsConsidered: [],
+        archived: [],
+        remainingCount: 0,
+        resetProgress: false,
+      });
+    }
+
+    // ----- Nonce gate -----
+    const issuedNonce = await readNonce(projectDir, /* consume: */ false);
+    if (issuedNonce === null) {
+      return [
+        "❌ ghs-force-archive: no transcription nonce on file.",
+        "",
+        "Call `ghs-archive` first; when there are incomplete sprints it will issue a nonce token.",
+        "Then transcribe that token back as the `transcription` arg of this tool.",
+        "",
+        `Expected nonce file: ${nonceFilePath(projectDir)}`,
+      ].join("\n") + "\n";
+    }
+
+    const ok = verifyTranscribeNonce(issuedNonce, args.transcription);
+    if (!ok) {
+      return [
+        "❌ ghs-force-archive: transcription does not match the issued nonce.",
+        "",
+        "No files were modified. To retry:",
+        "  1. Call `ghs-archive` (any mode) to get a fresh nonce, OR",
+        `  2. Re-transcribe the existing nonce (case-insensitive, trimmed) into the \`transcription\` arg.`,
+      ].join("\n") + "\n";
+    }
+
+    // Gate passed — consume the nonce so it can't be replayed.
+    await readNonce(projectDir, /* consume: */ true);
+
+    // ----- Force archive -----
+    // We collect the preview first (force + dry-run) so the report can show
+    // sprintsConsidered, then run the real archive.
+    const preview = await archiveSprints({
+      projectDir,
+      dryRun: true,
+      force: true,
+    });
+
+    const archived: ArchivedSprintInfo[] = await archiveSprints({
+      projectDir,
+      dryRun: false,
+      force: true,
+    });
+
+    // After force-archive there are no sprints left → resetProgress is true
+    // when archiveSprints actually moved something.
+    const featuresAfter = await loadFeaturesData(projectDir);
+    const remainingCount = featuresAfter
+      ? getAllSprints(featuresAfter).length
+      : 0;
+    const resetProgress = archived.length > 0 && remainingCount === 0;
+
+    // sprintsConsidered is `Record<string, unknown>[]` which matches the
+    // `Sprint[]` param of formatArchiveReport (Sprint === JsonObject
+    // internally).
+    const sprintsConsidered = preview.map((info) => ({
+      id: info.sprint_id,
+      name: info.sprint_name,
+      status: info.sprint_status,
+    }));
+
+    if (archived.length === 0) {
+      // Shouldn't normally happen (we checked allSprints.length > 0 above)
+      // but guard anyway — return the canonical "no sprints" report.
+      return formatArchiveReport({
+        projectDir,
+        mode: "archive",
+        force: true,
+        sprintsConsidered,
+        archived: [],
+        remainingCount,
+        resetProgress,
+      });
+    }
+
+    const report = formatArchiveReport({
+      projectDir,
+      mode: "archive",
+      force: true,
+      sprintsConsidered,
+      archived,
+      remainingCount,
+      resetProgress,
+    });
+
+    return report;
+  },
+});

package/src/tools/init.ts

@@ -0,0 +1,193 @@
+// `ghs-init` tool — initialise the `.ghs/` tracking files for a host project.
+//
+// This is the entry point a user (or the AI on the user's behalf) calls to
+// bootstrap ghs in a project. It:
+//   1. Resolves the target project dir (explicit `project_dir` arg wins;
+//      otherwise `resolveProjectDir(ctx)` reads the opencode session's
+//      worktree/directory).
+//   2. Calls `initProject` to create `.ghs/features.json` + `.ghs/progress.md`
+//      from the shared templates + update `.gitignore`.
+//   3. Calls `validateFeaturesJson` on the freshly-created features.json so
+//      the AI sees a confirmation (or, in the unlikely case the shared
+//      template is corrupt, an error) inline.
+//   4. Copies `shared/ghs.default.json` to `<projectDir>/.ghs/ghs.json` when
+//      the user doesn't already have one — so they have a starting point to
+//      customise model IDs (R3).
+//   5. Calls `syncAgents` to render the 3 agent markdown files into
+//      `<projectDir>/.opencode/agents/`. This is a direct function import,
+//      NOT a tool invocation (per plan §3.4 D2).
+//
+// All file I/O is pure — no LLM calls. The returned string is what the AI
+// sees as the tool result.
+
+import { tool } from "@opencode-ai/plugin";
+import type { ToolContext } from "@opencode-ai/plugin/tool";
+import { join, resolve } from "node:path";
+import { copyFile, mkdir } from "node:fs/promises";
+
+import {
+  initProject,
+  InitFilesExistError,
+} from "../lib/scripts/init-project.ts";
+import {
+  validateFeaturesJson,
+  formatValidationReport,
+} from "../lib/scripts/validate-structure.ts";
+import { syncAgents } from "../lib/config.ts";
+import { pluginRoot } from "../lib/paths.ts";
+import { resolveProjectDir } from "../lib/project.ts";
+
+/**
+ * Copy the plugin's `shared/ghs.default.json` to `<projectDir>/.ghs/ghs.json`
+ * when the user doesn't already have one. Returns true when a copy happened,
+ * false when the destination already existed.
+ */
+async function seedGhsJsonIfMissing(
+  projectDir: string,
+  pluginRootDir: string,
+): Promise<boolean> {
+  const dest = join(resolve(projectDir), ".ghs", "ghs.json");
+  const destFile = Bun.file(dest);
+  if (await destFile.exists()) {
+    return false;
+  }
+  const src = join(pluginRootDir, "shared", "ghs.default.json");
+  // Ensure `.ghs/` exists (initProject already created it, but be defensive
+  // — this function is also callable on a project where only .opencode/
+  // exists).
+  await mkdir(join(resolve(projectDir), ".ghs"), { recursive: true });
+  await copyFile(src, dest);
+  return true;
+}
+
+/**
+ * The `ghs-init` tool definition. Registered by the plugin entry point under
+ * the `ghs-init` key (hyphenated, per spike 001 / D1).
+ */
+export const initTool = tool({
+  description:
+    "Initialise the Golden Hoop Spell (ghs) tracking files for the current project. " +
+    "Creates `.ghs/features.json`, `.ghs/progress.md`, `.ghs/ghs.json` (with default model IDs), " +
+    "and the 3 subagent markdown files under `.opencode/agents/ghs-*.md`. " +
+    "Also appends `.ghs` to `.gitignore`. " +
+    "Re-run with `force: true` to overwrite existing `.ghs/features.json` and `.ghs/progress.md`.",
+  args: {
+    project_name: tool.schema
+      .string()
+      .describe("Human-readable project name (written into features.json#project.name)."),
+    description: tool.schema
+      .string()
+      .optional()
+      .describe(
+        "Optional project description. Defaults to '<project_name> project' when omitted.",
+      ),
+    project_dir: tool.schema
+      .string()
+      .optional()
+      .describe(
+        "Absolute path of the project root to initialise. Defaults to the opencode session's worktree/directory.",
+      ),
+    force: tool.schema
+      .boolean()
+      .optional()
+      .describe(
+        "When true, overwrite existing `.ghs/features.json` and `.ghs/progress.md`. Default false.",
+      ),
+  },
+  async execute(
+    args: {
+      project_name: string;
+      description?: string;
+      project_dir?: string;
+      force?: boolean;
+    },
+    ctx: ToolContext,
+  ): Promise<string> {
+    const projectDir = args.project_dir
+      ? resolve(args.project_dir)
+      : resolveProjectDir(ctx);
+    const root = pluginRoot();
+
+    // Step 1: create .ghs/features.json + .ghs/progress.md + .gitignore.
+    let initResult;
+    try {
+      initResult = await initProject({
+        projectName: args.project_name,
+        description: args.description,
+        projectDir,
+        force: args.force === true,
+        pluginRootPath: root,
+      });
+    } catch (err) {
+      if (err instanceof InitFilesExistError) {
+        return [
+          "❌ ghs-init refused to overwrite existing files:",
+          "",
+          err.message,
+          "",
+          "Re-run with `force: true` to overwrite.",
+        ].join("\n");
+      }
+      throw err;
+    }
+
+    // Step 2: validate the freshly-created features.json. In the happy path
+    // this always passes (we just wrote it from the shared template); running
+    // it here surfaces a useful confirmation to the AI and guards against a
+    // corrupt shared template.
+    const validation = await validateFeaturesJson(initResult.featuresFile);
+    const validationReport = formatValidationReport(validation);
+
+    // Step 3: seed .ghs/ghs.json from the plugin default if the user hasn't
+    // placed one yet. Returns whether a copy happened.
+    const seededGhsJson = await seedGhsJsonIfMissing(projectDir, root);
+
+    // Step 4: render the 3 subagent markdowns into .opencode/agents/.
+    const sync = await syncAgents(projectDir, root);
+
+    // Format the result string the AI sees. Keep it human-readable and
+    // include the validation outcome + the restart hint (syncAgents writes
+    // files but opencode only picks them up on next process start — spike 004).
+    const lines: string[] = [];
+    lines.push("=== ghs-init complete ===");
+    lines.push("");
+    lines.push(`Project directory: ${initResult.outputDir}`);
+    lines.push(`Project name:      ${initResult.projectName}`);
+    lines.push(`Description:       ${initResult.projectDescription}`);
+    lines.push("");
+    lines.push("Files created:");
+    lines.push(`  - ${initResult.featuresFile}`);
+    lines.push(`  - ${initResult.progressFile}`);
+    if (initResult.gitignoreUpdated) {
+      lines.push(`  - ${initResult.gitignoreFile} (appended \`.ghs\`)`);
+    } else {
+      lines.push(
+        `  - ${initResult.gitignoreFile} (already contained \`.ghs\`)`,
+      );
+    }
+    if (seededGhsJson) {
+      lines.push(`  - ${join(projectDir, ".ghs", "ghs.json")} (copied from plugin default)`);
+    }
+    for (const agentPath of sync.written) {
+      lines.push(`  - ${agentPath}`);
+    }
+    lines.push("");
+    lines.push("Resolved model IDs:");
+    lines.push(`  context:  ${sync.models.context}${sync.defaults_used ? "  (default)" : ""}`);
+    lines.push(`  designer: ${sync.models.designer}${sync.defaults_used ? "  (default)" : ""}`);
+    lines.push(`  reviewer: ${sync.models.reviewer}${sync.defaults_used ? "  (default)" : ""}`);
+    if (sync.defaults_used) {
+      lines.push("");
+      lines.push(
+        "ℹ️  Model IDs came from the plugin default. Edit `.ghs/ghs.json` to customise, then call `ghs-config`.",
+      );
+    }
+    lines.push("");
+    lines.push("Restart your OpenCode session for the new agent definitions to take effect.");
+    lines.push("");
+    lines.push("--- features.json validation ---");
+    lines.push(validationReport);
+
+    return lines.join("\n");
+  },
+});