golden-hoop-spell-opencode 0.1.0

package/src/lib/scripts/resolve-project-dir.ts

@@ -0,0 +1,130 @@
+// Port of golden-hoop-spell/plugin/shared/scripts/resolve_project_dir.py.
+//
+// Behavior source-of-truth:
+//   /Users/tom/github/golden-hoop-spell/plugin/shared/scripts/resolve_project_dir.py
+//
+// Faithful port notes:
+//   - Walks up from the start directory looking for a `.ghs/` directory that
+//     contains at least one marker file (`features.json` or `progress.md`).
+//   - Mirrors Python's loop-termination: the loop `while current != current.parent`
+//     stops one level before the filesystem root, then the root is checked
+//     separately. We do the same with `current === current.parent` as the
+//     termination sentinel.
+
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+
+const GHS_DIR = ".ghs";
+const MARKER_FILES = ["features.json", "progress.md"];
+
+/**
+ * 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. This matters on macOS where `/tmp` is a
+ * symlink to `/private/tmp` — Node's `path.resolve()` does NOT follow
+ * symlinks, but Python's `Path.resolve()` does. To stay byte-faithful with
+ * the source script we mirror the Python behaviour.
+ *
+ * Falls back to `path.resolve(...)` when no prefix of the path exists.
+ */
+function pyResolve(p: string): string {
+  const absolute = resolve(p);
+  // Walk from the full path upward, find the longest existing prefix.
+  let existing = absolute;
+  while (existing !== parentOf(existing) && !existsSync(existing)) {
+    existing = parentOf(existing);
+  }
+  if (!existsSync(existing)) {
+    // Nothing on disk matches — fall back to lexical resolution.
+    return absolute;
+  }
+  const real = realpathSync(existing);
+  if (existing === absolute) {
+    return real;
+  }
+  const tail = absolute.slice(existing.length);
+  return real + tail;
+}
+
+/**
+ * Walk up from `startDir` to find the directory whose `.ghs/` subdirectory
+ * contains at least one marker file.
+ *
+ * Returns `null` if no marker files are found in any ancestor — mirrors
+ * Python's `find_project_dir`.
+ */
+export function findProjectDir(startDir: string): string | null {
+  let current = pyResolve(startDir);
+
+  while (current !== parentOf(current)) {
+    if (hasMarkerFiles(current)) {
+      return current;
+    }
+    current = parentOf(current);
+  }
+
+  // Check the root directory too (mirrors Python's post-loop check).
+  if (hasMarkerFiles(current)) {
+    return current;
+  }
+
+  return null;
+}
+
+/**
+ * Resolve the ghs project directory or throw a descriptive error.
+ *
+ * Mirrors Python's `main()` minus the stderr print: instead of printing +
+ * exit(1), we throw `ProjectDirNotFoundError` so the tool layer can format
+ * the user-facing message.
+ */
+export function resolveProjectDir(startDir?: string): string {
+  const start = startDir ? pyResolve(startDir) : pyResolve(process.cwd());
+  const projectDir = findProjectDir(start);
+
+  if (projectDir === null) {
+    throw new ProjectDirNotFoundError(start);
+  }
+
+  return projectDir;
+}
+
+/** Return the parent directory of `dir`, or `dir` itself when already at root. */
+function parentOf(dir: string): string {
+  const parent = resolve(dir, "..");
+  // On the filesystem root, resolve(dir, "..") === dir.
+  return parent === dir ? dir : parent;
+}
+
+/** True iff `<dir>/.ghs/` is a directory that contains a marker file. */
+function hasMarkerFiles(dir: string): boolean {
+  const ghs = join(dir, GHS_DIR);
+  if (!existsSync(ghs) || !statSync(ghs).isDirectory()) {
+    return false;
+  }
+  for (const marker of MARKER_FILES) {
+    if (existsSync(join(ghs, marker))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Error thrown when no `.ghs/` directory is found in any ancestor. */
+export class ProjectDirNotFoundError extends Error {
+  readonly startDir: string;
+
+  constructor(startDir: string) {
+    super(
+      "Error: No project directory found. No .ghs/features.json or .ghs/progress.md in any parent directory. " +
+        "Run /ghs:init to create a new project.",
+    );
+    this.name = "ProjectDirNotFoundError";
+    this.startDir = startDir;
+  }
+}
+
+// Re-exported to keep the `sep` import meaningful for downstream tooling
+// that may want to know the platform separator (currently unused at runtime
+// but referenced by tests).
+export const pathSeparator: typeof sep = sep;

package/src/lib/scripts/status.ts

@@ -0,0 +1,292 @@
+// Port of golden-hoop-spell/plugin/shared/scripts/status.py.
+//
+// Behavior source-of-truth:
+//   /Users/tom/github/golden-hoop-spell/plugin/shared/scripts/status.py
+//
+// Faithful port notes:
+//   - The Python script prints the formatted status to stdout. Here we
+//     return the same text via `formatStatus()` so the tool layer can render
+//     or post-process it. The text is byte-for-byte identical to what Python
+//     would have printed (verified by walking through each `print()` call).
+//   - The H2-section splitter mirrors Python's `re.split(r"^## ", content,
+//     flags=re.MULTILINE)`: in JS we use `/^## /m` and keep only sections
+//     whose first line contains a `\d{4}-\d{2}-\d{2}` date.
+
+import { existsSync, realpathSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+type JsonObject = Record<string, unknown>;
+type Feature = JsonObject;
+type Sprint = JsonObject;
+type FeaturesData = JsonObject;
+
+/** Read and parse features.json. Returns `null` when the file does not exist. */
+export async function readFeaturesJson(
+  filepath: string,
+): Promise<FeaturesData | null> {
+  if (!existsSync(filepath)) {
+    return null;
+  }
+  const text = await readFile(filepath, "utf8");
+  return JSON.parse(text) as FeaturesData;
+}
+
+/** Read the last `lastN` sessions from progress.md. Returns `null` if the file is missing. */
+export async function readProgressMd(
+  filepath: string,
+  lastN = 5,
+): Promise<string[] | null> {
+  if (!existsSync(filepath)) {
+    return null;
+  }
+  const content = await readFile(filepath, "utf8");
+  return extractSessions(content, lastN);
+}
+
+/**
+ * Split content on `^## ` headings (multiline) and keep only sections whose
+ * first line contains a `\d{4}-\d{2}-\d{2}` date.
+ *
+ * Mirrors Python:
+ *   sections = re.split(r"^## ", content, flags=re.MULTILINE)
+ *   sessions = [s for s in sections if re.search(r"\d{4}-\d{2}-\d{2}", s.split("\n", 1)[0])]
+ *   return sessions[:last_n]
+ */
+export function extractSessions(content: string, lastN = 5): string[] {
+  const sections = content.split(/^## /m);
+  const sessions: string[] = [];
+  for (const section of sections) {
+    const firstLine = section.split("\n", 1)[0];
+    if (/\d{4}-\d{2}-\d{2}/.test(firstLine)) {
+      sessions.push(section);
+    }
+  }
+  return sessions.slice(0, lastN);
+}
+
+/** Compute per-status feature counts. Mirrors Python `format_feature_status`. */
+export function formatFeatureStatus(
+  features: Feature[],
+): Record<"pending" | "in_progress" | "completed" | "blocked", number> {
+  const statusCounts = {
+    pending: 0,
+    in_progress: 0,
+    completed: 0,
+    blocked: 0,
+  } as Record<"pending" | "in_progress" | "completed" | "blocked", number>;
+
+  for (const feature of features) {
+    const status = ((feature.status as string | undefined) ?? "pending") as
+      | "pending"
+      | "in_progress"
+      | "completed"
+      | "blocked";
+    if (status in statusCounts) {
+      statusCounts[status] += 1;
+    } else {
+      // Mirrors Python's `.get(status, 0) + 1` — we don't track unknown
+      // statuses in the counts dict but we do keep the call side-effect-free.
+      // Python silently drops unknown statuses; we mirror that.
+    }
+  }
+
+  return statusCounts;
+}
+
+/** Options accepted by formatStatus / status. */
+export interface StatusOptions {
+  /** Project directory (the directory containing `.ghs/`). Defaults to cwd. */
+  projectDir?: string;
+}
+
+/** Result returned by `status()`. */
+export interface StatusResult {
+  /** Byte-identical to what status.py would have printed to stdout. */
+  text: string;
+  /** 0 on success, 1 when features.json is missing (matches Python exit code). */
+  exitCode: 0 | 1;
+}
+
+/**
+ * Format the project status as a text block.
+ *
+ * The returned string is byte-identical to Python `main()`'s stdout, including
+ * the trailing blank lines. Mirrors the early-return when features.json is
+ * missing (text = `❌ features.json not found. Run init-project.py first.\n`).
+ */
+export async function formatStatus(options: StatusOptions = {}): Promise<string> {
+  const projectDir = pyResolve(options.projectDir ?? process.cwd());
+  const featuresPath = join(projectDir, ".ghs", "features.json");
+  const progressPath = join(projectDir, ".ghs", "progress.md");
+
+  const lines: string[] = [];
+
+  if (!existsSync(featuresPath)) {
+    lines.push("❌ features.json not found. Run init-project.py first.");
+    return lines.join("\n") + "\n";
+  }
+
+  lines.push("=== Project Status ===");
+  lines.push("");
+
+  const featuresData = (await readFeaturesJson(featuresPath)) as FeaturesData | null;
+
+  if (featuresData) {
+    const project = (featuresData.project ?? {}) as JsonObject;
+    lines.push(`📦 Project: ${(project.name as string | undefined) ?? "Unknown"}`);
+    lines.push(
+      `📝 Description: ${(project.description as string | undefined) ?? "No description"}`,
+    );
+    lines.push(`📅 Created: ${(project.created_at as string | undefined) ?? "Unknown"}`);
+    lines.push("");
+
+    const sprints = (featuresData.sprints ?? []) as Sprint[];
+
+    if (sprints.length === 0) {
+      lines.push("⚠️  No sprints defined yet. Run Sprint Agent to plan features.");
+      // Python `return 0` here — no further output (no progress sessions).
+      return lines.join("\n") + "\n";
+    }
+
+    for (const sprint of sprints) {
+      const sprintId = (sprint.id as string | undefined) ?? "unknown";
+      const sprintName = (sprint.name as string | undefined) ?? "Unnamed Sprint";
+      const sprintStatus = (sprint.status as string | undefined) ?? "planning";
+      const features = (sprint.features ?? []) as Feature[];
+
+      const statusEmoji = sprintStatusEmoji(sprintStatus);
+      lines.push(`${statusEmoji} Sprint: ${sprintName} (${sprintId})`);
+      lines.push(`   Status: ${sprintStatus}`);
+      lines.push(`   Goal: ${(sprint.goal as string | undefined) ?? "No goal defined"}`);
+      lines.push("");
+
+      const statusCounts = formatFeatureStatus(features);
+
+      lines.push("   Features:");
+      lines.push(`     ✅ Completed:    ${statusCounts.completed}`);
+      lines.push(`     🚧 In Progress:  ${statusCounts.in_progress}`);
+      lines.push(`     ⏳ Pending:      ${statusCounts.pending}`);
+      lines.push(`     🚫 Blocked:      ${statusCounts.blocked}`);
+      lines.push(`     ━━━━━━━━━━━━━━━━━━━━`);
+      lines.push(`     📊 Total:        ${features.length}`);
+      lines.push("");
+
+      if (statusCounts.in_progress > 0) {
+        const inProgress = features.filter((f) => f.status === "in_progress");
+        for (const feat of inProgress) {
+          lines.push(
+            `   🔨 Working on: ${(feat.title as string | undefined) ?? "Unknown"} (${(feat.id as string | undefined) ?? ""})`,
+          );
+        }
+      }
+
+      if (statusCounts.pending > 0) {
+        const pending = features.filter((f) => f.status === "pending");
+        const completedIds = new Set(
+          features.filter((f) => f.status === "completed").map((f) => f.id as string),
+        );
+        const ready = pending.filter((f) => {
+          const deps = (f.dependencies ?? []) as string[];
+          return deps.every((dep) => completedIds.has(dep));
+        });
+        if (ready.length > 0) {
+          const nextFeature = ready[0];
+          lines.push(
+            `   ▶️  Next up: ${(nextFeature.title as string | undefined) ?? "Unknown"} (${(nextFeature.id as string | undefined) ?? ""})`,
+          );
+        } else {
+          lines.push(
+            "   ⏸️  No ready features — all pending features have unmet dependencies",
+          );
+        }
+      }
+
+      lines.push("");
+    }
+  }
+
+  const sessions = await readProgressMd(progressPath);
+  if (sessions && sessions.length > 0) {
+    lines.push("📜 Recent Sessions:");
+    for (const session of sessions.slice(0, 3)) {
+      const sessionLines = session.trim().split("\n").slice(0, 3);
+      for (const line of sessionLines) {
+        if (line.trim()) {
+          lines.push(`   ${line.trim()}`);
+        }
+      }
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Resolve the sprint status emoji. Mirrors Python's `status_emoji.get(..., "❓")`.
+ */
+function sprintStatusEmoji(status: string): string {
+  switch (status) {
+    case "planning":
+      return "📋";
+    case "in_progress":
+      return "🚀";
+    case "completed":
+      return "✅";
+    case "on_hold":
+      return "⏸️";
+    default:
+      return "❓";
+  }
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Compute the project status and return `{ text, exitCode }`.
+ *
+ * `exitCode` mirrors Python's `main()` return value: 0 on success, 1 when
+ * features.json is missing. The tool layer decides whether to surface the
+ * non-zero code as a tool error.
+ */
+export async function status(options: StatusOptions = {}): Promise<StatusResult> {
+  const projectDir = pyResolve(options.projectDir ?? process.cwd());
+  const featuresPath = join(projectDir, ".ghs", "features.json");
+
+  if (!existsSync(featuresPath)) {
+    return {
+      text: "❌ features.json not found. Run init-project.py first.\n",
+      exitCode: 1,
+    };
+  }
+
+  const text = await formatStatus(options);
+  return { text, exitCode: 0 };
+}

package/src/lib/scripts/update-feature-status.ts

@@ -0,0 +1,169 @@
+// Update a feature's status inside a features.json object (in-memory; no I/O).
+//
+// This is one of the three "writer" modules introduced in s2-feat-001. Like
+// append-sprint.ts, it has no source-plugin Python equivalent — the source
+// `ghs-sprint` / `ghs-code` skills had the AI edit features.json directly.
+// This module refactors that into a pure, Zod-validated function.
+//
+// Design principles match append-sprint.ts: pure function, no I/O, no stdout,
+// no process.exit, immutable return, Zod-validated spec.
+
+import { z } from "zod";
+
+// -----------------------------------------------------------------------------
+// Types
+// -----------------------------------------------------------------------------
+
+type JsonObject = Record<string, unknown>;
+export type FeaturesData = JsonObject;
+export type Feature = JsonObject;
+export type Sprint = JsonObject;
+
+// -----------------------------------------------------------------------------
+// Schema
+// -----------------------------------------------------------------------------
+
+/**
+ * Allowed feature statuses. Kept in sync with validate-structure.ts
+ * `VALID_FEATURE_STATUSES`. Re-declared locally to avoid a cross-module
+ * dependency (see the rationale in append-sprint.ts).
+ */
+export const VALID_FEATURE_STATUSES = [
+  "pending",
+  "in_progress",
+  "completed",
+  "blocked",
+] as const;
+
+/**
+ * Zod schema for the "update feature status" spec.
+ *
+ * - `feature_id`: matches the feature ID format enforced by
+ *   validate-structure.ts (`^s\d{1,4}-feat-\d{3}$`).
+ * - `status`: one of {@link VALID_FEATURE_STATUSES}.
+ * - `blocked_reason`: required when `status === "blocked"` (matches the
+ *   optional-field convention documented in features.json's `_schema_docs`).
+ */
+const FEATURE_ID_PATTERN = /^s\d{1,4}-feat-\d{3}$/;
+
+export const UpdateFeatureStatusSpecSchema = z
+  .object({
+    feature_id: z
+      .string()
+      .regex(
+        FEATURE_ID_PATTERN,
+        "feature_id must match ^s\\d{1,4}-feat-\\d{3}$ (e.g. s1-feat-001)",
+      ),
+    status: z.enum(VALID_FEATURE_STATUSES),
+    blocked_reason: z.string().min(1).optional(),
+  })
+  .refine(
+    (spec) => spec.status !== "blocked" || (spec.blocked_reason ?? "") !== "",
+    {
+      message:
+        "blocked_reason is required when status is 'blocked'",
+      path: ["blocked_reason"],
+    },
+  );
+
+export type UpdateFeatureStatusSpec = z.infer<
+  typeof UpdateFeatureStatusSpecSchema
+>;
+
+// -----------------------------------------------------------------------------
+// Writer
+// -----------------------------------------------------------------------------
+
+/** Result of locating a feature: the sprint it lives in and the feature itself. */
+interface LocatedFeature {
+  sprintIndex: number;
+  featureIndex: number;
+}
+
+/**
+ * Find a feature by ID across all sprints. Returns the sprint/feature indices
+ * or `null` when not found.
+ */
+function locateFeature(
+  featuresData: FeaturesData,
+  featureId: string,
+): LocatedFeature | null {
+  const sprints = Array.isArray(featuresData.sprints)
+    ? (featuresData.sprints as Sprint[])
+    : [];
+  for (let si = 0; si < sprints.length; si++) {
+    const features = Array.isArray(sprints[si].features)
+      ? (sprints[si].features as Feature[])
+      : [];
+    for (let fi = 0; fi < features.length; fi++) {
+      if (features[fi].id === featureId) {
+        return { sprintIndex: si, featureIndex: fi };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Update the status of a single feature (located by ID, searched across ALL
+ * sprints) and return a NEW featuresData object. The input is not modified.
+ *
+ * Behavior:
+ *   1. Validate `spec` against {@link UpdateFeatureStatusSpecSchema}. This
+ *      enforces the feature_id format, the status enum, and the rule that
+ *      `status === "blocked"` requires a non-empty `blocked_reason`. A ZodError
+ *      is thrown on invalid input.
+ *   2. Locate the feature by `spec.feature_id`. Throw a descriptive Error if no
+ *      sprint contains it.
+ *   3. Return a shallow-cloned featuresData where the located sprint and its
+ *      `features` array are shallow-cloned, and the target feature is replaced
+ *      with a cloned object carrying the new `status` (and `blocked_reason`
+ *      when applicable). Other features/sprints are shared by reference.
+ *
+ * When transitioning OUT of "blocked", any pre-existing `blocked_reason` field
+ * is removed from the updated feature (so the file does not carry a stale
+ * reason for a non-blocked feature).
+ */
+export function updateFeatureStatus(
+  featuresData: FeaturesData,
+  spec: UpdateFeatureStatusSpec,
+): FeaturesData {
+  const validated = UpdateFeatureStatusSpecSchema.parse(spec);
+
+  const located = locateFeature(featuresData, validated.feature_id);
+  if (located === null) {
+    throw new Error(
+      `Feature '${validated.feature_id}' not found in any sprint`,
+    );
+  }
+
+  const sprints = Array.isArray(featuresData.sprints)
+    ? (featuresData.sprints as Sprint[])
+    : [];
+
+  const { sprintIndex, featureIndex } = located;
+  const targetSprint = sprints[sprintIndex];
+  const features = (targetSprint.features as Feature[]) ?? [];
+  const targetFeature = features[featureIndex];
+
+  // Build the updated feature. Start from a shallow clone of the original so
+  // unrelated fields are preserved.
+  const updatedFeature: Feature = { ...targetFeature };
+  updatedFeature.status = validated.status;
+  if (validated.status === "blocked") {
+    updatedFeature.blocked_reason = validated.blocked_reason;
+  } else if ("blocked_reason" in updatedFeature) {
+    delete updatedFeature.blocked_reason;
+  }
+
+  // Rebuild the path from the root to the updated feature with shallow clones
+  // at each container level. Everything else is shared by reference.
+  const updatedFeatures = features.slice();
+  updatedFeatures[featureIndex] = updatedFeature;
+
+  const updatedSprint: Sprint = { ...targetSprint, features: updatedFeatures };
+  const updatedSprints = sprints.slice();
+  updatedSprints[sprintIndex] = updatedSprint;
+
+  return { ...featuresData, sprints: updatedSprints };
+}