golden-hoop-spell-opencode 0.1.0

package/src/lib/scripts/init-project.ts

@@ -0,0 +1,291 @@
+// Port of golden-hoop-spell/plugin/shared/scripts/init_project.py.
+//
+// Behavior source-of-truth:
+//   /Users/tom/github/golden-hoop-spell/plugin/shared/scripts/init_project.py
+//
+// Faithful port notes:
+//   - JSON output uses `JSON.stringify(obj, null, 2)` which matches Python's
+//     `json.dump(obj, f, indent=2)` (both use 2-space indent, comma-newline,
+//     colon-space). Python's `ensure_ascii=True` default would escape non-ASCII
+//     as \uXXXX — but the source features.json template is pure ASCII, so the
+//     byte-for-byte equivalence holds for the generated files in practice.
+//   - Date format: Python uses `datetime.now().strftime("%Y-%m-%d")` which is
+//     a naive local date. We mirror this via `formatLocalDate()`.
+//   - This module exports functions — NO console.log to stdout, NO process.exit.
+//     The CLI wrapper (s1-feat-009) is responsible for printing the human-facing
+//     status lines. Here we return a structured result.
+
+import { existsSync, realpathSync } from "node:fs";
+import { mkdir, readFile, writeFile, copyFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+/**
+ * Resolve the plugin root (the directory that contains `src/` and `shared/`).
+ *
+ * Note: This mirrors the behaviour that will be exported from
+ * `src/lib/paths.ts` (s1-feat-006). The local copy keeps this module
+ * self-contained — s1-feat-008 has no dependency on s1-feat-006, so we
+ * duplicate the one-line primitive rather than importing across the
+ * not-yet-implemented module boundary. When s1-feat-006 lands and exports
+ * `pluginRoot`, callers may pass `pluginRootPath` explicitly to override.
+ */
+function defaultPluginRoot(): string {
+  // import.meta.dir is the directory of this source file
+  // (src/lib/scripts/), so the plugin root is three levels up.
+  return resolve(import.meta.dir, "..", "..", "..");
+}
+
+/**
+ * Resolve a path the way Python's `pathlib.Path.resolve(strict=False)` does:
+ * apply `realpathSync` to the longest existing prefix, then append the
+ * remaining components verbatim. Necessary on macOS where `/tmp` is a
+ * symlink to `/private/tmp`. See resolve-project-dir.ts for the same helper.
+ */
+function pyResolve(p: string): string {
+  const absolute = resolve(p);
+  let existing = absolute;
+  while (existing !== parentOf(existing) && !existsSync(existing)) {
+    existing = parentOf(existing);
+  }
+  if (!existsSync(existing)) {
+    return absolute;
+  }
+  const real = realpathSync(existing);
+  if (existing === absolute) {
+    return real;
+  }
+  return real + absolute.slice(existing.length);
+}
+
+/** Parent directory of `dir`, or `dir` itself at the filesystem root. */
+function parentOf(dir: string): string {
+  const parent = resolve(dir, "..");
+  return parent === dir ? dir : parent;
+}
+
+/** Options accepted by initProject. */
+export interface InitProjectOptions {
+  /** Project name (required). */
+  projectName: string;
+  /** Optional project description; defaults to `<projectName> project`. */
+  description?: string;
+  /**
+   * Output directory (the project root where `.ghs/` will be created).
+   * Defaults to the current working directory.
+   */
+  projectDir?: string;
+  /** When true, overwrite existing `.ghs/features.json` or `.ghs/progress.md`. */
+  force?: boolean;
+  /**
+   * Override the plugin root (used to locate `shared/assets/` templates).
+   * Defaults to the plugin root resolved from `import.meta.dir`.
+   */
+  pluginRootPath?: string;
+}
+
+/** Result returned by initProject. */
+export interface InitProjectResult {
+  /** Absolute path to the project directory the files were written into. */
+  outputDir: string;
+  /** Absolute path of the created features.json. */
+  featuresFile: string;
+  /** Absolute path of the created progress.md. */
+  progressFile: string;
+  /** Absolute path of the touched .gitignore. */
+  gitignoreFile: string;
+  /** Whether .gitignore was modified (true) or already contained `.ghs` (false). */
+  gitignoreUpdated: boolean;
+  /** The project name written into features.json. */
+  projectName: string;
+  /** The project description written into features.json. */
+  projectDescription: string;
+}
+
+/** Format a Date the way Python's `datetime.now().strftime("%Y-%m-%d")` does. */
+export function formatLocalDate(now: Date = new Date()): string {
+  const y = now.getFullYear();
+  const m = String(now.getMonth() + 1).padStart(2, "0");
+  const d = String(now.getDate()).padStart(2, "0");
+  return `${y}-${m}-${d}`;
+}
+
+/**
+ * Create `.ghs/features.json` from the shared template, substituting
+ * `project.name`, `project.description`, `project.created_at`, and
+ * `metadata.last_updated`.
+ *
+ * Mirrors Python `create_features_json`.
+ */
+export async function createFeaturesJson(
+  projectName: string,
+  projectDescription: string,
+  outputDir: string,
+  pluginRootPath: string = defaultPluginRoot(),
+): Promise<string> {
+  const templatePath = join(pluginRootPath, "shared", "assets", "features.json");
+
+  if (!existsSync(templatePath)) {
+    throw new Error(`Template not found: ${templatePath}`);
+  }
+
+  const templateText = await readFile(templatePath, "utf8");
+  const featuresData = JSON.parse(templateText) as Record<string, unknown>;
+
+  const project = (featuresData.project ?? {}) as Record<string, unknown>;
+  project.name = projectName;
+  project.description = projectDescription;
+  project.created_at = formatLocalDate();
+  featuresData.project = project;
+
+  const metadata = (featuresData.metadata ?? {}) as Record<string, unknown>;
+  metadata.last_updated = formatLocalDate();
+  featuresData.metadata = metadata;
+
+  const outputFile = join(outputDir, ".ghs", "features.json");
+  await mkdir(dirname(outputFile), { recursive: true });
+  await writeFile(outputFile, JSON.stringify(featuresData, null, 2), "utf8");
+
+  return outputFile;
+}
+
+/**
+ * Append `.ghs` to `.gitignore` if not already present; create the file if
+ * missing. Mirrors Python `ensure_gitignore`.
+ *
+ * @returns `[absolutePath, updated]` — `updated` is true when the file was
+ *   created or modified, false when `.ghs` was already present.
+ */
+export async function ensureGitignore(
+  outputDir: string,
+): Promise<[string, boolean]> {
+  const gitignorePath = join(outputDir, ".gitignore");
+  const entry = ".ghs";
+
+  if (existsSync(gitignorePath)) {
+    const content = await readFile(gitignorePath, "utf8");
+    const lines = content.split(/\r?\n/).map((l) => l.trim());
+    if (lines.includes(entry)) {
+      return [gitignorePath, false];
+    }
+    let next = content;
+    if (content.length > 0 && !content.endsWith("\n")) {
+      next += "\n";
+    }
+    next += `${entry}\n`;
+    await writeFile(gitignorePath, next, "utf8");
+    return [gitignorePath, true];
+  }
+
+  await writeFile(gitignorePath, `${entry}\n`, "utf8");
+  return [gitignorePath, true];
+}
+
+/**
+ * Copy the shared `assets/progress.md` template to `<outputDir>/.ghs/progress.md`.
+ * Mirrors Python `create_progress_md`.
+ */
+export async function createProgressMd(
+  outputDir: string,
+  pluginRootPath: string = defaultPluginRoot(),
+): Promise<string> {
+  const templatePath = join(pluginRootPath, "shared", "assets", "progress.md");
+
+  if (!existsSync(templatePath)) {
+    throw new Error(`Template not found: ${templatePath}`);
+  }
+
+  const ghsDir = join(outputDir, ".ghs");
+  await mkdir(ghsDir, { recursive: true });
+  const outputFile = join(ghsDir, "progress.md");
+  await copyFile(templatePath, outputFile);
+
+  return outputFile;
+}
+
+/**
+ * Initialize the `.ghs/` tracking files for a project.
+ *
+ * Mirrors the body of Python `main()` minus the stdout prints: it validates
+ * preconditions (existing files vs `force`), creates features.json +
+ * progress.md, and updates .gitignore.
+ *
+ * @throws when the templates cannot be found, or when files already exist and
+ *   `force` is not set.
+ */
+export async function initProject(
+  options: InitProjectOptions,
+): Promise<InitProjectResult> {
+  const outputDir = pyResolve(options.projectDir ?? process.cwd());
+  await mkdir(outputDir, { recursive: true });
+
+  const projectName = options.projectName;
+  const projectDescription = options.description?.length
+    ? options.description
+    : `${projectName} project`;
+
+  // Check for existing .ghs files unless --force is passed.
+  if (!options.force) {
+    const existingFiles: string[] = [];
+    const featuresPath = join(outputDir, ".ghs", "features.json");
+    const progressPath = join(outputDir, ".ghs", "progress.md");
+    if (existsSync(featuresPath)) {
+      existingFiles.push(relativeOrSame(featuresPath, outputDir));
+    }
+    if (existsSync(progressPath)) {
+      existingFiles.push(relativeOrSame(progressPath, outputDir));
+    }
+    if (existingFiles.length > 0) {
+      throw new InitFilesExistError(existingFiles, outputDir);
+    }
+  }
+
+  const pluginRootPath = options.pluginRootPath ?? defaultPluginRoot();
+  const featuresFile = await createFeaturesJson(
+    projectName,
+    projectDescription,
+    outputDir,
+    pluginRootPath,
+  );
+  const progressFile = await createProgressMd(outputDir, pluginRootPath);
+  const [gitignoreFile, gitignoreUpdated] = await ensureGitignore(outputDir);
+
+  return {
+    outputDir,
+    featuresFile,
+    progressFile,
+    gitignoreFile,
+    gitignoreUpdated,
+    projectName,
+    projectDescription,
+  };
+}
+
+/** Compute path relative to `outputDir`, falling back to the absolute path. */
+function relativeOrSame(target: string, base: string): string {
+  const rel = target.startsWith(base + "/") || target.startsWith(base)
+    ? target.slice(base.length).replace(/^\/+/, "")
+    : target;
+  return rel;
+}
+
+/**
+ * Error thrown when `.ghs/features.json` or `.ghs/progress.md` already exist
+ * and the caller did not pass `force: true`. Mirrors Python's diagnostic
+ * output: the file list + the `Use --force to overwrite existing files` hint.
+ */
+export class InitFilesExistError extends Error {
+  readonly existingFiles: string[];
+  readonly outputDir: string;
+
+  constructor(existingFiles: string[], outputDir: string) {
+    const lines = [
+      "Error: The following .ghs files already exist:",
+      ...existingFiles.map((f) => `  - ${f}`),
+      "Use --force to overwrite existing files.",
+    ].join("\n");
+    super(lines);
+    this.name = "InitFilesExistError";
+    this.existingFiles = existingFiles;
+    this.outputDir = outputDir;
+  }
+}

package/src/lib/scripts/parallel-utils.ts

@@ -0,0 +1,380 @@
+// Port of golden-hoop-spell/plugin/shared/scripts/parallel_utils.py.
+//
+// Behavior source-of-truth:
+//   /Users/tom/.claude/plugins/cache/golden-hoop-spell/golden-hoop-spell/0.4.0/shared/scripts/parallel_utils.py
+//
+// Faithful port notes (plan §3.4 D4 — line-by-line port):
+//   - The Python source is both a library (`detect_cycles` /
+//     `get_ready_features` / `build_parallel_batches`) and a CLI wrapper
+//     (`main()` reads features.json via argparse and prints JSON). We port the
+//     *library* core verbatim-by-behavior; the CLI layer (argparse / stdout /
+//     `json.dump` / `sys.exit`) is intentionally omitted because the OpenCode
+//     plugin consumes this as an in-process TS module — the tool layer
+//     (`ghs-code`) calls `getReadyFeatures()` / `buildBatches()` directly and
+//     renders the result itself.
+//   - The three library functions are pure: no FS, no subprocess, no global
+//     mutation. They take already-parsed `features.json` objects. File reading
+//     is left to the caller (mirrors how the other ports in this directory
+//     split: `readFeaturesJson` lives next to each consumer rather than here,
+//     and `status.ts` already exposes one).
+//   - Iteration-order hazard (called out in the feature's technical_notes):
+//       Python dict preserves insertion order and so does JS object iteration,
+//       so the `feature_index` / `completed_ids` lookups behave the same.
+//       The one place ordering is *observable* is `build_parallel_batches`'s
+//       output: we sort by `files_affected.length` descending (Python
+//       `sorted(..., key=lambda f: len(f.get('files_affected', [])),
+//       reverse=True)`). JS `Array.prototype.sort` is stable as of ES2019, so
+//       ties keep their original relative order — same as Python's stable
+//       Timsort. No extra tiebreaker is needed for parity.
+//   - Cycle detection is the iterative-but-recursive DFS with white/gray/black
+//     coloring from the Python source. We keep it recursive in JS too (the
+//     feature graphs in practice are tiny — tens of features per sprint — so
+//     stack depth is a non-issue).
+//   - Style follows s1-feat-008: no `process.exit`, no `console.log`, all
+//     exported functions are pure.
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Loose structural types mirroring the shape of `features.json`. We keep these
+ * deliberately permissive (`Record<string, unknown>`) rather than redefining a
+ * strict Zod schema here — the file is already validated upstream by
+ * `validate-structure.ts` (s1-feat-012) before any tool invokes this module,
+ * and the Python original also operated on untyped `Dict`s. Field access uses
+ * the same `.get(...)` / `?? []` defensive pattern as the source.
+ */
+type JsonObject = Record<string, unknown>;
+export type Feature = JsonObject;
+export type Sprint = JsonObject;
+export type FeaturesData = JsonObject;
+
+/** Color used by the DFS cycle finder. Mirrors Python WHITE/GRAY/BLACK. */
+const WHITE = 0;
+const GRAY = 1;
+const BLACK = 2;
+
+export interface ReadyFeaturesResult {
+  /** Features whose status is `pending`, deps all completed, not in a cycle. */
+  ready: Feature[];
+  /** Everything else: wrong status, unmet deps, or cycle-participating. */
+  skipped: Feature[];
+  /** Detected cycles; each is a list of feature IDs forming the loop. */
+  cycles: string[][];
+  /** IDs of any feature that participates in at least one cycle. */
+  cycle_feature_ids: string[];
+}
+
+// ---------------------------------------------------------------------------
+// detect_cycles — 1:1 port of the Python DFS coloring algorithm.
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect circular dependencies in the feature dependency graph.
+ *
+ * Uses recursive DFS with white/gray/black coloring to find every cycle.
+ * Returns a list of cycles, where each cycle is a list of feature IDs forming
+ * the loop. A dependency that is not in `feature_index` is skipped (mirrors
+ * Python `if dep not in feature_index: continue`).
+ *
+ * Port of `detect_cycles(features, feature_index)`.
+ */
+export function detectCycles(
+  features: Feature[],
+  featureIndex: Record<string, Feature>,
+): string[][] {
+  const color = new Map<string, number>();
+  const cycles: string[][] = [];
+  const path: string[] = [];
+  const pathSet = new Set<string>();
+
+  const dfs = (node: string): void => {
+    color.set(node, GRAY);
+    path.push(node);
+    pathSet.add(node);
+
+    const feat = featureIndex[node] ?? {};
+    const deps = (feat["dependencies"] as string[] | undefined) ?? [];
+    for (const dep of deps) {
+      if (!(dep in featureIndex)) {
+        continue;
+      }
+      if (color.get(dep) === GRAY) {
+        // Found a cycle — extract it from the current DFS path.
+        const cycleStart = path.indexOf(dep);
+        cycles.push(path.slice(cycleStart));
+      } else if ((color.get(dep) ?? WHITE) === WHITE) {
+        dfs(dep);
+      }
+    }
+
+    path.pop();
+    pathSet.delete(node);
+    color.set(node, BLACK);
+  };
+
+  for (const feat of features) {
+    const fid = (feat["id"] as string | undefined) ?? "";
+    if ((color.get(fid) ?? WHITE) === WHITE) {
+      dfs(fid);
+    }
+  }
+
+  return cycles;
+}
+
+// ---------------------------------------------------------------------------
+// get_ready_features — 1:1 port of get_ready_features.
+// ---------------------------------------------------------------------------
+
+/**
+ * Identify features whose dependencies are all completed.
+ *
+ * Selection of the sprint to analyze mirrors Python exactly:
+ *   - If `sprintId` is given, the first sprint with that `id` is used.
+ *   - Otherwise the first sprint with `status === "in_progress"` is used; if
+ *     none, the first sprint in the array.
+ *   - If no sprint matches (empty list, missing id), all four result fields
+ *     are empty arrays.
+ *
+ * A feature is `ready` iff:
+ *   1. `status === "pending"`,
+ *   2. it is not part of any detected dependency cycle, AND
+ *   3. every entry in its `dependencies` is in the completed set.
+ *
+ * Port of `get_ready_features(features_data, sprint_id=None)`.
+ */
+export function getReadyFeatures(
+  featuresData: FeaturesData,
+  sprintId?: string | null,
+): ReadyFeaturesResult {
+  const empty: ReadyFeaturesResult = {
+    ready: [],
+    skipped: [],
+    cycles: [],
+    cycle_feature_ids: [],
+  };
+
+  const sprints = (featuresData["sprints"] as Sprint[] | undefined) ?? [];
+
+  let sprint: Sprint | null = null;
+  if (sprintId) {
+    for (const s of sprints) {
+      if (s["id"] === sprintId) {
+        sprint = s;
+        break;
+      }
+    }
+  } else {
+    // Use the first in_progress sprint, or fall back to the first sprint.
+    for (const s of sprints) {
+      if (s["status"] === "in_progress") {
+        sprint = s;
+        break;
+      }
+    }
+    if (sprint === null && sprints.length > 0) {
+      sprint = sprints[0];
+    }
+  }
+
+  if (sprint === null) {
+    return empty;
+  }
+
+  const features = (sprint["features"] as Feature[] | undefined) ?? [];
+
+  // Build index keyed by id, and the completed-id set.
+  const featureIndex: Record<string, Feature> = {};
+  for (const f of features) {
+    const fid = (f["id"] as string | undefined) ?? "";
+    if (fid) {
+      featureIndex[fid] = f;
+    }
+  }
+  const completedIds = new Set<string>();
+  for (const f of features) {
+    if (f["status"] === "completed") {
+      const fid = (f["id"] as string | undefined) ?? "";
+      if (fid) {
+        completedIds.add(fid);
+      }
+    }
+  }
+
+  // Detect cycles and union the participating ids.
+  const cycles = detectCycles(features, featureIndex);
+  const cycleFeatureIdSet = new Set<string>();
+  for (const cycle of cycles) {
+    for (const id of cycle) {
+      cycleFeatureIdSet.add(id);
+    }
+  }
+
+  const ready: Feature[] = [];
+  const skipped: Feature[] = [];
+
+  for (const feat of features) {
+    const fid = (feat["id"] as string | undefined) ?? "";
+    const status = (feat["status"] as string | undefined) ?? "";
+
+    // Only pending features can be ready.
+    if (status !== "pending") {
+      skipped.push(feat);
+      continue;
+    }
+
+    // Skip features involved in dependency cycles.
+    if (cycleFeatureIdSet.has(fid)) {
+      skipped.push(feat);
+      continue;
+    }
+
+    // Check all dependencies are completed.
+    //
+    // Faithful port of the Python conditional — the second disjunct is
+    // logically redundant (`dep_id in completed_ids` already covers it) but we
+    // keep it verbatim for byte-for-byte behavioral parity:
+    //   dep_id in completed_ids or
+    //   (dep_id not in feature_index and dep_id in completed_ids)
+    const deps = (feat["dependencies"] as string[] | undefined) ?? [];
+    const depsMet = deps.every(
+      (depId) =>
+        completedIds.has(depId) ||
+        (!(depId in featureIndex) && completedIds.has(depId)),
+    );
+
+    if (depsMet) {
+      ready.push(feat);
+    } else {
+      skipped.push(feat);
+    }
+  }
+
+  return {
+    ready,
+    skipped,
+    cycles,
+    cycle_feature_ids: Array.from(cycleFeatureIdSet),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// build_parallel_batches — 1:1 port of build_parallel_batches.
+// ---------------------------------------------------------------------------
+
+/**
+ * Group non-conflicting ready features into parallel batches.
+ *
+ * Heuristic (verbatim from Python): sort by `files_affected` length descending,
+ * then greedily place each feature into the first existing batch that (a) is
+ * under `maxParallel` and (b) has no `files_affected` overlap. If none fits,
+ * start a new batch.
+ *
+ * The descending-file-count sort tends to spread high-overlap features across
+ * different batches first. Features with overlapping `files_affected` are never
+ * placed in the same batch to avoid merge conflicts during parallel execution.
+ *
+ * Port of `build_parallel_batches(ready_features, max_parallel=5)`.
+ */
+export function buildBatches(
+  readyFeatures: Feature[],
+  maxParallel = 5,
+): Feature[][] {
+  if (readyFeatures.length === 0) {
+    return [];
+  }
+
+  // Sort by number of files_affected descending. JS Array.sort is stable
+  // (ES2019+), so ties preserve input order — matching Python's Timsort.
+  const sortedFeatures = [...readyFeatures].sort(
+    (a, b) =>
+      (((b["files_affected"] as unknown[] | undefined) ?? []).length) -
+      (((a["files_affected"] as unknown[] | undefined) ?? []).length),
+  );
+
+  const batches: Feature[][] = [];
+  const assigned = new Set<string>();
+
+  for (const feat of sortedFeatures) {
+    const fid = (feat["id"] as string | undefined) ?? "";
+    if (assigned.has(fid)) {
+      continue;
+    }
+
+    const featFiles = new Set<string>(
+      ((feat["files_affected"] as string[] | undefined) ?? []),
+    );
+
+    // Try to place in an existing batch.
+    let placed = false;
+    for (const batch of batches) {
+      if (batch.length >= maxParallel) {
+        continue;
+      }
+
+      // Check for file conflicts with features already in the batch.
+      let hasConflict = false;
+      for (const existing of batch) {
+        const existingFiles = new Set<string>(
+          ((existing["files_affected"] as string[] | undefined) ?? []),
+        );
+        // Set intersection: if any element of featFiles is in existingFiles.
+        for (const f of featFiles) {
+          if (existingFiles.has(f)) {
+            hasConflict = true;
+            break;
+          }
+        }
+        if (hasConflict) {
+          break;
+        }
+      }
+
+      if (!hasConflict) {
+        batch.push(feat);
+        assigned.add(fid);
+        placed = true;
+        break;
+      }
+    }
+
+    // If no existing batch fits, start a new one.
+    if (!placed) {
+      batches.push([feat]);
+      assigned.add(fid);
+    }
+  }
+
+  return batches;
+}
+
+// ---------------------------------------------------------------------------
+// summarizeFeature — port of the inline `summarize_feature` used by main().
+//   Kept here (not in the CLI) because the ghs-code tool wants the same
+//   trimmed projection of a feature for its dispatch-plan output.
+// ---------------------------------------------------------------------------
+
+export interface FeatureSummary {
+  id: string;
+  title: string;
+  status: string;
+  files_affected: string[];
+  dependencies: string[];
+}
+
+/**
+ * Project a feature dict onto the small summary shape the Python CLI emitted
+ * in its JSON output (`id`, `title`, `status`, `files_affected`,
+ * `dependencies`). Port of `summarize_feature` inside `main()`.
+ */
+export function summarizeFeature(feat: Feature): FeatureSummary {
+  return {
+    id: (feat["id"] as string | undefined) ?? "",
+    title: (feat["title"] as string | undefined) ?? "",
+    status: (feat["status"] as string | undefined) ?? "",
+    files_affected: (feat["files_affected"] as string[] | undefined) ?? [],
+    dependencies: (feat["dependencies"] as string[] | undefined) ?? [],
+  };
+}