karajan-code 4.70.4 → 5.0.0

package/src/hu/store.js

@@ -1,394 +0,0 @@
-/**
- * HU (Historia de Usuario / User Story) storage. Persists HU batches and
- * their stories to the session directory.
- *
- * @typedef {import("../types/hu.js").HUStory} HUStory
- * @typedef {import("../types/hu.js").HUBatch} HUBatch
- * @typedef {import("../types/hu.js").HUStatus} HUStatus
- */
-
-import fs from "node:fs/promises";
-import path from "node:path";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-
-const execFileAsync = promisify(execFile);
-import { getKarajanHome } from "../utils/paths.js";
-
-// FUTURE: hu-storage adapter for PG/Trello/etc — currently local files only
-
-/**
- * Valid HU story status values.
- * @type {Readonly<{PENDING: "pending", CODING: "coding", REVIEWING: "reviewing", DONE: "done", FAILED: "failed", BLOCKED: "blocked", CERTIFIED: "certified", NEEDS_CONTEXT: "needs_context"}>}
- */
-export const HU_STATUS = Object.freeze({
-  PENDING: "pending",
-  CODING: "coding",
-  REVIEWING: "reviewing",
-  DONE: "done",
-  FAILED: "failed",
-  BLOCKED: "blocked",
-  CERTIFIED: "certified",
-  NEEDS_CONTEXT: "needs_context"
-});
-
-/** @returns {string} Path to the hu-stories directory (evaluated at call time). */
-function getHuDir() {
-  return path.join(getKarajanHome(), "hu-stories");
-}
-
-/**
- * Create a new HU batch from an array of story definitions.
- * @param {string} sessionId - The session identifier.
- * @param {Array<{id?: string, text: string, blocked_by?: string[]}>} stories - Raw story inputs.
- * @returns {Promise<object>} The created batch object.
- */
-export async function createHuBatch(sessionId, stories) {
-  const dir = path.join(getHuDir(), sessionId);
-  await fs.mkdir(dir, { recursive: true });
-
-  const batch = {
-    session_id: sessionId,
-    created_at: new Date().toISOString(),
-    stories: stories.map((s, i) => ({
-      id: s.id || `HU-${Date.now()}-${i}`,
-      status: "pending",
-      original: { text: s.text },
-      blocked_by: s.blocked_by || [],
-      // KJC-TSK-0698: the tier travels with the HU; a story without one (single auto-story) carries none.
-      ...(s.complexity ? { complexity: s.complexity } : {}),
-      certified: null,
-      quality: null,
-      context_requests: [],
-      created_at: new Date().toISOString(),
-      updated_at: new Date().toISOString()
-    }))
-  };
-
-  await fs.writeFile(path.join(dir, "batch.json"), JSON.stringify(batch, null, 2));
-  return batch;
-}
-
-/**
- * Load an existing HU batch from disk.
- * @param {string} sessionId - The session identifier.
- * @returns {Promise<object>} The loaded batch object.
- */
-export async function loadHuBatch(sessionId) {
-  const file = path.join(getHuDir(), sessionId, "batch.json");
-  const raw = await fs.readFile(file, "utf8");
-  return JSON.parse(raw);
-}
-
-/**
- * Save a batch back to disk.
- *
- * Ensures the target directory exists before writing — the previous
- * implementation assumed createHuBatch had already done the mkdir,
- * which holds for the auto-HU path but NOT for plan-driven runs:
- * `kj run --plan <id>` derives a batchSessionId from the plan id,
- * loads the (non-existent) batch.json, falls back to in-memory, then
- * crashes here with ENOENT on the first save attempt because no one
- * created `~/.karajan/hu-stories/<sessionId>/`. The fix is one
- * mkdir -p; cheap and idempotent.
- *
- * @param {string} sessionId - The session identifier.
- * @param {object} batch - The batch object to persist.
- * @returns {Promise<void>}
- */
-export async function saveHuBatch(sessionId, batch) {
-  const dir = path.join(getHuDir(), sessionId);
-  await fs.mkdir(dir, { recursive: true });
-  batch.updated_at = new Date().toISOString();
-  await fs.writeFile(path.join(dir, "batch.json"), JSON.stringify(batch, null, 2));
-}
-
-/**
- * Update the status of a single story within a batch.
- * @param {object} batch - The batch object.
- * @param {string} storyId - Story ID to update.
- * @param {string} status - New status value.
- * @param {object} [extra={}] - Additional fields to merge.
- * @returns {object} The updated story.
- */
-export function updateStoryStatus(batch, storyId, status, extra = {}) {
-  const story = batch.stories.find(s => s.id === storyId);
-  if (!story) throw new Error(`Story ${storyId} not found`);
-  story.status = status;
-  const now = new Date().toISOString();
-  story.statusChangedAt = now;
-  story.updated_at = now;
-  Object.assign(story, extra);
-  return story;
-}
-
-/**
- * Store quality scores on a story.
- * @param {object} batch - The batch object.
- * @param {string} storyId - Story ID.
- * @param {object} quality - Quality scores object.
- * @returns {object} The updated story.
- */
-export function updateStoryQuality(batch, storyId, quality) {
-  const story = batch.stories.find(s => s.id === storyId);
-  if (!story) throw new Error(`Story ${storyId} not found`);
-  story.quality = { ...quality, evaluated_at: new Date().toISOString() };
-  story.updated_at = new Date().toISOString();
-  return story;
-}
-
-/**
- * Mark a story as certified with the provided certified data.
- * @param {object} batch - The batch object.
- * @param {string} storyId - Story ID.
- * @param {object} certified - Certified HU data.
- * @returns {object} The updated story.
- */
-export function updateStoryCertified(batch, storyId, certified) {
-  const story = batch.stories.find(s => s.id === storyId);
-  if (!story) throw new Error(`Story ${storyId} not found`);
-  story.certified = certified;
-  story.status = "certified";
-  story.updated_at = new Date().toISOString();
-  return story;
-}
-
-/**
- * Add a context request to a story and set its status to needs_context.
- * @param {object} batch - The batch object.
- * @param {string} storyId - Story ID.
- * @param {{fields_needed: string[], question: string}} request - Context request.
- * @returns {object} The updated story.
- */
-export function addContextRequest(batch, storyId, request) {
-  const story = batch.stories.find(s => s.id === storyId);
-  if (!story) throw new Error(`Story ${storyId} not found`);
-  story.context_requests.push({
-    requested_at: new Date().toISOString(),
-    fields_needed: request.fields_needed,
-    question_to_fde: request.question,
-    answered_at: null,
-    answer: null
-  });
-  story.status = "needs_context";
-  story.updated_at = new Date().toISOString();
-  return story;
-}
-
-/**
- * Answer the most recent pending context request and reset status to pending.
- * @param {object} batch - The batch object.
- * @param {string} storyId - Story ID.
- * @param {string} answer - The FDE's answer.
- * @returns {object} The updated story.
- */
-export function answerContextRequest(batch, storyId, answer) {
-  const story = batch.stories.find(s => s.id === storyId);
-  if (!story) throw new Error(`Story ${storyId} not found`);
-  const pending = story.context_requests.find(r => !r.answered_at);
-  if (pending) {
-    pending.answered_at = new Date().toISOString();
-    pending.answer = answer;
-  }
-  story.status = "pending"; // back to pending for re-evaluation
-  story.updated_at = new Date().toISOString();
-  return story;
-}
-
-/**
- * Create a lightweight history record for a pipeline run.
- * Stores a minimal single-HU batch in the same hu-stories directory
- * so the HU Board can pick it up alongside full batches.
- * @param {string} sessionId - The session identifier.
- * @param {{task: string, result: string, approved: boolean, summary?: string, timestamp?: string}} data
- * @returns {Promise<object>} The created batch object.
- */
-export async function createHistoryRecord(sessionId, { task, result, approved, summary, timestamp }) {
-  const ts = timestamp || new Date().toISOString();
-  const dir = path.join(getHuDir(), sessionId);
-  await fs.mkdir(dir, { recursive: true });
-
-  const batch = {
-    session_id: sessionId,
-    created_at: ts,
-    stories: [
-      {
-        id: `HU-hist-${sessionId}`,
-        status: approved ? "certified" : "failed",
-        original: { text: task },
-        blocked_by: [],
-        certified: approved ? { summary: summary || result } : null,
-        quality: null,
-        context_requests: [],
-        created_at: ts,
-        updated_at: ts
-      }
-    ],
-    history: {
-      task,
-      result,
-      approved,
-      summary: summary || null,
-      timestamp: ts
-    }
-  };
-
-  await fs.writeFile(path.join(dir, "batch.json"), JSON.stringify(batch, null, 2));
-  return batch;
-}
-
-/* ── Splitting metadata ──────────────────────────────────────────── */
-
-/**
- * Add splitting metadata to a story within a batch.
- * Used to track the relationship between an original HU and its sub-HUs
- * after a split operation.
- *
- * @param {object} batch - The batch object.
- * @param {string} huId - Story ID to annotate.
- * @param {{ original_hu_id?: string, split_children?: string[], indicators_detected?: string[], heuristic_applied?: string, split_confirmed_by_fde?: boolean, validation?: object }} metadata - Splitting metadata.
- * @returns {object} The updated story.
- */
-export function addSplittingMetadata(batch, huId, metadata) {
-  const story = batch.stories.find(s => s.id === huId);
-  if (!story) throw new Error(`Story ${huId} not found`);
-  story.splitting = { ...(story.splitting || {}), ...metadata };
-  story.updated_at = new Date().toISOString();
-  return story;
-}
-
-/* ── Manual HU management ─────────────────────────────────────────── */
-
-/**
- * Detect project info from the given directory.
- * @param {string} cwd - Directory to detect project from.
- * @returns {Promise<{ name: string, remoteUrl: string|null }>}
- */
-export async function detectProject(cwd) {
-  const name = path.basename(cwd);
-  let remoteUrl = null;
-  try {
-    const { stdout } = await execFileAsync("git", ["remote", "get-url", "origin"], { cwd, encoding: "utf8" });
-    remoteUrl = stdout.trim();
-  } catch { /* not a git repo or no remote */ }
-  return { name, remoteUrl };
-}
-
-/**
- * Derive a project slug from a directory path.
- * @param {string} projectDir - Absolute path to the project.
- * @returns {string}
- */
-function projectSlug(projectDir) {
-  return path.basename(projectDir);
-}
-
-/**
- * Get the batch file path for a project.
- * @param {string} projectDir
- * @returns {string}
- */
-function projectBatchPath(projectDir) {
-  return path.join(getHuDir(), projectSlug(projectDir), "batch.json");
-}
-
-/**
- * Load the project batch, or return a fresh empty batch if none exists.
- * @param {string} projectDir
- * @returns {Promise<object>}
- */
-async function loadProjectBatch(projectDir) {
-  const filePath = projectBatchPath(projectDir);
-  try {
-    const raw = await fs.readFile(filePath, "utf8");
-    return JSON.parse(raw);
-  } catch { /* no saved batch for this project */
-    return {
-      project: projectSlug(projectDir),
-      created_at: new Date().toISOString(),
-      stories: []
-    };
-  }
-}
-
-/**
- * Save a project batch to disk (auto-creates directory).
- * @param {string} projectDir
- * @param {object} batch
- */
-async function saveProjectBatch(projectDir, batch) {
-  const filePath = projectBatchPath(projectDir);
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
-  batch.updated_at = new Date().toISOString();
-  await fs.writeFile(filePath, JSON.stringify(batch, null, 2));
-}
-
-/**
- * Create a manual HU (user story) for a project.
- * Auto-creates the batch file if it doesn't exist.
- * @param {string} projectDir
- * @param {{ title: string, description?: string, status?: string, acceptanceCriteria?: string }} data
- * @returns {Promise<object>} The created HU.
- */
-export async function createManualHu(projectDir, { title, description, status, acceptanceCriteria }) {
-  if (!title) throw new Error("title is required to create a HU");
-  const batch = await loadProjectBatch(projectDir);
-  const now = new Date().toISOString();
-  const hu = {
-    id: `HU-${Date.now()}-${batch.stories.length}`,
-    title,
-    description: description || "",
-    status: status || HU_STATUS.PENDING,
-    acceptanceCriteria: acceptanceCriteria || "",
-    createdAt: now,
-    updatedAt: now
-  };
-  batch.stories.push(hu);
-  await saveProjectBatch(projectDir, batch);
-  return hu;
-}
-
-/**
- * List all HUs for a project.
- * @param {string} projectDir
- * @returns {Promise<Array<{ id: string, title: string, status: string, createdAt: string }>>}
- */
-export async function listHus(projectDir) {
-  const batch = await loadProjectBatch(projectDir);
-  return batch.stories.map(s => ({
-    id: s.id,
-    title: s.title,
-    status: s.status,
-    createdAt: s.createdAt
-  }));
-}
-
-/**
- * Update the status of a specific HU.
- * @param {string} projectDir
- * @param {string} huId
- * @param {string} status
- * @returns {Promise<object>} The updated HU.
- */
-export async function updateHuStatus(projectDir, huId, status) {
-  const batch = await loadProjectBatch(projectDir);
-  const hu = batch.stories.find(s => s.id === huId);
-  if (!hu) throw new Error(`HU ${huId} not found`);
-  hu.status = status;
-  hu.updatedAt = new Date().toISOString();
-  await saveProjectBatch(projectDir, batch);
-  return hu;
-}
-
-/**
- * Get a single HU by id.
- * @param {string} projectDir
- * @param {string} huId
- * @returns {Promise<object>}
- */
-export async function getHu(projectDir, huId) {
-  const batch = await loadProjectBatch(projectDir);
-  const hu = batch.stories.find(s => s.id === huId);
-  if (!hu) throw new Error(`HU ${huId} not found`);
-  return hu;
-}

package/src/infrastructure/mocks.js

@@ -1,182 +0,0 @@
-/**
- * Test doubles for the DI surfaces. Intentionally dumb — tests stage inputs
- * through simple setters and assert on recorded calls.
- *
- * @typedef {import("./file-system-service.js").FileSystemService} FileSystemService
- * @typedef {import("./command-runner.js").CommandRunner} CommandRunner
- * @typedef {import("./command-runner.js").CommandRunResult} CommandRunResult
- * @typedef {import("./command-runner.js").CommandRunOptions} CommandRunOptions
- */
-
-/**
- * In-memory file system. Paths are stored as-is (no normalization) to keep
- * behaviour predictable in tests.
- */
-export class MockFileSystem {
-  constructor(initial = {}) {
-    /** @type {Map<string, string|Buffer>} */
-    this.files = new Map(Object.entries(initial));
-    /** @type {Set<string>} */
-    this.directories = new Set();
-    /** @type {Array<{op: string, path: string, args?: unknown}>} */
-    this.calls = [];
-  }
-
-  _record(op, path, args) {
-    this.calls.push({ op, path, args });
-  }
-
-  async readFile(path, encoding = "utf8") {
-    this._record("readFile", path, { encoding });
-    if (!this.files.has(path)) {
-      const err = new Error(`ENOENT: no such file or directory, open '${path}'`);
-      err.code = "ENOENT";
-      throw err;
-    }
-    const data = this.files.get(path);
-    if (Buffer.isBuffer(data) && encoding) return data.toString(encoding);
-    return data;
-  }
-
-  async writeFile(path, data, encoding = "utf8") {
-    this._record("writeFile", path, { encoding });
-    this.files.set(path, data);
-  }
-
-  async appendFile(path, data, encoding = "utf8") {
-    this._record("appendFile", path, { encoding });
-    const prev = this.files.get(path) ?? "";
-    this.files.set(path, String(prev) + String(data));
-  }
-
-  async exists(path) {
-    this._record("exists", path);
-    return this.files.has(path) || this.directories.has(path);
-  }
-
-  async ensureDir(path) {
-    this._record("ensureDir", path);
-    this.directories.add(path);
-  }
-
-  async readdir(path) {
-    this._record("readdir", path);
-    const prefix = path.endsWith("/") ? path : path + "/";
-    const entries = new Set();
-    for (const p of this.files.keys()) {
-      if (p.startsWith(prefix)) {
-        const tail = p.slice(prefix.length).split("/")[0];
-        if (tail) entries.add(tail);
-      }
-    }
-    if (!entries.size && !this.directories.has(path)) {
-      const err = new Error(`ENOENT: no such file or directory, scandir '${path}'`);
-      err.code = "ENOENT";
-      throw err;
-    }
-    return [...entries];
-  }
-
-  async copyFile(src, dest) {
-    this._record("copyFile", src, { dest });
-    if (!this.files.has(src)) {
-      const err = new Error(`ENOENT: no such file or directory, copyfile '${src}' -> '${dest}'`);
-      err.code = "ENOENT";
-      throw err;
-    }
-    this.files.set(dest, this.files.get(src));
-  }
-
-  async stat(path) {
-    this._record("stat", path);
-    if (this.files.has(path)) {
-      const data = this.files.get(path);
-      const size = Buffer.isBuffer(data) ? data.length : Buffer.byteLength(String(data));
-      return {
-        size,
-        isDirectory: () => false,
-        isFile: () => true
-      };
-    }
-    if (this.directories.has(path)) {
-      return {
-        size: 0,
-        isDirectory: () => true,
-        isFile: () => false
-      };
-    }
-    const err = new Error(`ENOENT: no such file or directory, stat '${path}'`);
-    err.code = "ENOENT";
-    throw err;
-  }
-}
-
-/**
- * Scripted command runner. Tests call enqueue() to stage responses in order,
- * or setResponder() for a per-invocation decision. Every run() is recorded.
- */
-export class MockCommandRunner {
-  constructor() {
-    /** @type {Array<CommandRunResult>} */
-    this.queue = [];
-    /** @type {Array<{command: string, args: string[], options: CommandRunOptions}>} */
-    this.calls = [];
-    /** @type {null | ((args: {command: string, args: string[], options: CommandRunOptions}) => CommandRunResult|Promise<CommandRunResult>)} */
-    this.responder = null;
-    /** @type {CommandRunResult} */
-    this.defaultResponse = { exitCode: 0, stdout: "", stderr: "" };
-  }
-
-  /**
-   * Queue a response. FIFO — first enqueued is returned on the first run().
-   * @param {Partial<CommandRunResult>} response
-   */
-  enqueue(response) {
-    this.queue.push({ exitCode: 0, stdout: "", stderr: "", ...response });
-    return this;
-  }
-
-  /**
-   * Replace FIFO queue with a function that decides per-call.
-   * @param {(args: {command: string, args: string[], options: CommandRunOptions}) => CommandRunResult|Promise<CommandRunResult>} fn
-   */
-  setResponder(fn) {
-    this.responder = fn;
-    return this;
-  }
-
-  /**
-   * @param {string} command
-   * @param {string[]} args
-   * @param {CommandRunOptions} options
-   * @returns {Promise<CommandRunResult>}
-   */
-  async run(command, args = [], options = {}) {
-    this.calls.push({ command, args: [...args], options: { ...options } });
-    if (this.responder) return this.responder({ command, args, options });
-    if (this.queue.length > 0) return this.queue.shift();
-    return { ...this.defaultResponse };
-  }
-
-  /**
-   * Convenience: last recorded invocation, or null.
-   */
-  get lastCall() {
-    return this.calls.at(-1) ?? null;
-  }
-}
-
-/**
- * Build an Environment backed by the mocks above. Useful shorthand in tests:
- *
- *   const { env, fs, runner } = buildMockEnvironment();
- *   const agent = new BaseAgent(..., env);
- *
- * @param {{files?: Record<string, string|Buffer>}} [opts]
- */
-export function buildMockEnvironment({ files } = {}) {
-  const fs = new MockFileSystem(files);
-  const runner = new MockCommandRunner();
-  const env = Object.freeze({ fs, runner });
-  return { env, fs, runner };
-}