@wrongstack/core 0.5.5 → 0.5.6

package/dist/{director-state-BUxlqkOa.d.ts → plan-templates-DaxTCPfk.d.ts}

@@ -452,6 +452,22 @@ declare function setPlanItemStatus(plan: PlanFile, idOrIndex: string, status: Pl
 declare function clearPlan(plan: PlanFile): PlanFile;
 /** Render the plan as a short markdown-ish string suitable for slash output. */
 declare function formatPlan(plan: PlanFile): string;
+/**
+ * Promote a plan item to a set of todo items.
+ * The plan item is marked 'in_progress' (if not already done) and its
+ * title + details become the first todo; additional subtasks are appended.
+ * Returns the derived todo list so the caller can pass it to `todoTool`
+ * or `ctx.state.replaceTodos()`.
+ */
+declare function deriveTodosFromPlanItem(plan: PlanFile, idOrIndex: string, subtasks?: string[]): {
+    plan: PlanFile;
+    todos: Array<{
+        id: string;
+        content: string;
+        status: 'pending' | 'in_progress' | 'completed';
+        activeForm?: string;
+    }>;
+} | null;
 /**
  * Optional: attach a state-listener so meta operations (storing a plan
  * id on ctx.meta) trigger a save. Currently a stub — plans don't live
@@ -461,79 +477,24 @@ declare function formatPlan(plan: PlanFile): string;
 declare function attachPlanCheckpoint(_state: ConversationState, _filePath: string, _sessionId: string): () => void;
 
 /**
- * Director state checkpoint — written incrementally throughout a fleet
- * run so a crashed director can be inspected (and eventually resumed)
- * instead of leaving only a final `fleet.json` manifest after `shutdown()`.
+ * Plan templates — pre-defined plan skeletons for common workflows.
  *
- * Schema is JSON-friendly and deliberately denormalized. Each mutation
- * triggers an atomic-write of the whole file — small payloads (typically
- * < 10 KB even with dozens of subagents) make this cheap.
- */
-interface DirectorSubagentState {
-    id: string;
-    name?: string;
-    role?: string;
-    provider?: string;
-    model?: string;
-    spawnedAt: string;
-}
-interface DirectorTaskState {
-    taskId: string;
-    subagentId?: string;
-    description?: string;
-    status: 'pending' | 'running' | 'completed' | 'failed' | 'stopped' | 'timeout';
-    assignedAt?: string;
-    completedAt?: string;
-    iterations?: number;
-    toolCalls?: number;
-    durationMs?: number;
-    error?: string;
-}
-interface DirectorStateSnapshot {
-    version: 1;
-    directorRunId: string;
-    updatedAt: string;
-    spawnCount: number;
-    maxSpawns?: number;
-    spawnDepth: number;
-    maxSpawnDepth: number;
-    subagents: DirectorSubagentState[];
-    tasks: DirectorTaskState[];
-    /** Aggregated usage snapshot. Optional — populated by the Director on save when available. */
-    usage?: unknown;
-}
-declare function loadDirectorState(filePath: string): Promise<DirectorStateSnapshot | null>;
-/**
- * In-memory accumulator with atomic-write checkpoint. The Director keeps
- * an instance, mutates it on every spawn/assign/complete/fail event, and
- * the instance debounces writes so a burst of activity collapses into a
- * single disk hit.
+ * Templates are stored in-memory (no disk I/O). Users instantiate them
+ * via `/plan template use <name>` or `planTool(action: 'template_use')`.
+ * Each template is a function that returns an array of item titles, so
+ * dynamic content (dates, project names) can be injected later.
  */
-declare class DirectorStateCheckpoint {
-    private snapshot;
-    private readonly filePath;
-    private timer;
-    private readonly debounceMs;
-    private writing;
-    private rewriteRequested;
-    constructor(filePath: string, init: {
-        directorRunId: string;
-        maxSpawns?: number;
-        spawnDepth: number;
-        maxSpawnDepth: number;
-    }, debounceMs?: number);
-    current(): DirectorStateSnapshot;
-    recordSpawn(sub: DirectorSubagentState, spawnCount: number): void;
-    recordTaskAssigned(task: DirectorTaskState): void;
-    recordTaskStatus(taskId: string, patch: Partial<DirectorTaskState> & {
-        status: DirectorTaskState['status'];
-    }): void;
-    setUsage(usage: unknown): void;
-    /** Force a synchronous flush — used by Director.shutdown(). */
-    flush(): Promise<void>;
-    private bumpUpdatedAt;
-    private schedule;
-    private persist;
+interface PlanTemplate {
+    name: string;
+    description: string;
+    category: 'development' | 'release' | 'maintenance' | 'infrastructure';
+    items: Array<{
+        title: string;
+        details?: string;
+    }>;
 }
+declare function listPlanTemplates(): PlanTemplate[];
+declare function getPlanTemplate(name: string): PlanTemplate | undefined;
+declare function formatPlanTemplates(): string;
 
-export { type AbandonedSession as A, loadPlan as B, type ConfigLoaderOptions as C, DEFAULT_CONFIG_MIGRATIONS as D, loadTodosCheckpoint as E, removePlanItem as F, runConfigMigrations as G, savePlan as H, saveTodosCheckpoint as I, setPlanItemStatus as J, type MemoryStoreOptions as M, type PersistedQueueItem as P, QueueStore as Q, RecoveryLock as R, SessionAnalyzer as S, type TodosCheckpointFile as T, type AttachmentStoreOptions as a, type ConfigMigration as b, ConfigMigrationError as c, type ConfigSource as d, DefaultAttachmentStore as e, DefaultConfigLoader as f, DefaultConfigStore as g, DefaultMemoryStore as h, DefaultSessionStore as i, DirectorStateCheckpoint as j, type DirectorStateSnapshot as k, type DirectorSubagentState as l, type DirectorTaskState as m, type MigrationContext as n, type MigrationResult as o, type PlanFile as p, type PlanItem as q, type RecoveryLockOptions as r, type SessionStoreOptions as s, addPlanItem as t, attachPlanCheckpoint as u, attachTodosCheckpoint as v, clearPlan as w, emptyPlan as x, formatPlan as y, loadDirectorState as z };
+export { type AbandonedSession as A, loadPlan as B, type ConfigLoaderOptions as C, DEFAULT_CONFIG_MIGRATIONS as D, loadTodosCheckpoint as E, removePlanItem as F, runConfigMigrations as G, savePlan as H, saveTodosCheckpoint as I, setPlanItemStatus as J, type MemoryStoreOptions as M, type PersistedQueueItem as P, QueueStore as Q, RecoveryLock as R, SessionAnalyzer as S, type TodosCheckpointFile as T, type AttachmentStoreOptions as a, type ConfigMigration as b, ConfigMigrationError as c, type ConfigSource as d, DefaultAttachmentStore as e, DefaultConfigLoader as f, DefaultConfigStore as g, DefaultMemoryStore as h, DefaultSessionStore as i, type MigrationContext as j, type MigrationResult as k, type PlanFile as l, type PlanItem as m, type PlanTemplate as n, type RecoveryLockOptions as o, type SessionStoreOptions as p, addPlanItem as q, attachPlanCheckpoint as r, attachTodosCheckpoint as s, clearPlan as t, deriveTodosFromPlanItem as u, emptyPlan as v, formatPlan as w, formatPlanTemplates as x, getPlanTemplate as y, listPlanTemplates as z };

package/dist/storage/index.d.ts

@@ -1,6 +1,7 @@
-export { A as AbandonedSession, a as AttachmentStoreOptions, C as ConfigLoaderOptions, b as ConfigMigration, c as ConfigMigrationError, d as ConfigSource, D as DEFAULT_CONFIG_MIGRATIONS, e as DefaultAttachmentStore, f as DefaultConfigLoader, g as DefaultConfigStore, h as DefaultMemoryStore, i as DefaultSessionStore, j as DirectorStateCheckpoint, k as DirectorStateSnapshot, l as DirectorSubagentState, m as DirectorTaskState, M as MemoryStoreOptions, n as MigrationContext, o as MigrationResult, P as PersistedQueueItem, p as PlanFile, q as PlanItem, Q as QueueStore, R as RecoveryLock, r as RecoveryLockOptions, S as SessionAnalyzer, s as SessionStoreOptions, T as TodosCheckpointFile, t as addPlanItem, u as attachPlanCheckpoint, v as attachTodosCheckpoint, w as clearPlan, x as emptyPlan, y as formatPlan, z as loadDirectorState, B as loadPlan, E as loadTodosCheckpoint, F as removePlanItem, G as runConfigMigrations, H as savePlan, I as saveTodosCheckpoint, J as setPlanItemStatus } from '../director-state-BUxlqkOa.js';
+export { A as AbandonedSession, a as AttachmentStoreOptions, C as ConfigLoaderOptions, b as ConfigMigration, c as ConfigMigrationError, d as ConfigSource, D as DEFAULT_CONFIG_MIGRATIONS, e as DefaultAttachmentStore, f as DefaultConfigLoader, g as DefaultConfigStore, h as DefaultMemoryStore, i as DefaultSessionStore, M as MemoryStoreOptions, j as MigrationContext, k as MigrationResult, P as PersistedQueueItem, l as PlanFile, m as PlanItem, n as PlanTemplate, Q as QueueStore, R as RecoveryLock, o as RecoveryLockOptions, S as SessionAnalyzer, p as SessionStoreOptions, T as TodosCheckpointFile, q as addPlanItem, r as attachPlanCheckpoint, s as attachTodosCheckpoint, t as clearPlan, u as deriveTodosFromPlanItem, v as emptyPlan, w as formatPlan, x as formatPlanTemplates, y as getPlanTemplate, z as listPlanTemplates, B as loadPlan, E as loadTodosCheckpoint, F as removePlanItem, G as runConfigMigrations, H as savePlan, I as saveTodosCheckpoint, J as setPlanItemStatus } from '../plan-templates-DaxTCPfk.js';
 export { D as DefaultSessionReader } from '../session-reader-4jxsYLZ8.js';
 import { S as SessionRewinder, C as CheckpointInfo, a as RewindResultExtended } from '../session-rewinder-C9HnMkhP.js';
+export { D as DirectorStateCheckpoint, a as DirectorStateSnapshot, b as DirectorSubagentState, c as DirectorTaskState, l as loadDirectorState } from '../director-state-BmYi3DGA.js';
 import '../events-qnDZbrtb.js';
 import '../context-CLZXPPYk.js';
 import '../memory-CEXuo7sz.js';

package/dist/storage/index.js

@@ -3,7 +3,12 @@ import * as fsp from 'fs/promises';
 import * as path2 from 'path';
 import * as os from 'os';
 
-// src/storage/session-store.ts
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
 async function atomicWrite(targetPath, content, opts = {}) {
   const dir = path2.dirname(targetPath);
   await fsp.mkdir(dir, { recursive: true });
@@ -2182,9 +2187,149 @@ function matchIndex(plan, idOrIndex) {
   const lower = idOrIndex.toLowerCase();
   return plan.items.findIndex((it) => it.title.toLowerCase().includes(lower));
 }
+function deriveTodosFromPlanItem(plan, idOrIndex, subtasks) {
+  const idx = matchIndex(plan, idOrIndex);
+  if (idx === -1) return null;
+  const item = plan.items[idx];
+  if (!item) return null;
+  let updatedPlan = plan;
+  if (item.status !== "done") {
+    updatedPlan = setPlanItemStatus(plan, idOrIndex, "in_progress");
+  }
+  const todos = [];
+  todos.push({
+    id: `todo_${Date.now()}_plan`,
+    content: item.title,
+    status: "in_progress",
+    activeForm: item.title
+  });
+  if (subtasks && subtasks.length > 0) {
+    for (const st of subtasks) {
+      todos.push({
+        id: `todo_${Date.now()}_${randomUUID().slice(0, 6)}`,
+        content: st,
+        status: "pending"
+      });
+    }
+  }
+  return { plan: updatedPlan, todos };
+}
 function attachPlanCheckpoint(_state, _filePath, _sessionId) {
   return () => void 0;
 }
+
+// src/storage/plan-templates.ts
+var templates = {
+  "new-feature": {
+    name: "new-feature",
+    description: "Standard workflow for adding a new feature",
+    category: "development",
+    items: [
+      { title: "Write specification / design doc", details: "Define scope, acceptance criteria, edge cases" },
+      { title: "Set up feature branch", details: "git checkout -b feature/..." },
+      { title: "Implement core logic", details: "TDD preferred \u2014 write tests first" },
+      { title: "Add unit tests", details: ">= 80% coverage for new code" },
+      { title: "Add integration tests", details: "End-to-end happy path + error paths" },
+      { title: "Update documentation", details: "README, API docs, changelog" },
+      { title: "Code review", details: "Self-review before requesting review" },
+      { title: "Merge and deploy", details: "CI green, tag release" }
+    ]
+  },
+  "bug-fix": {
+    name: "bug-fix",
+    description: "Systematic approach to fixing bugs",
+    category: "maintenance",
+    items: [
+      { title: "Reproduce the bug", details: "Minimal reproduction case" },
+      { title: "Root cause analysis", details: "Trace through logs, debugger" },
+      { title: "Write failing test", details: "Test must fail before fix" },
+      { title: "Implement fix", details: "Smallest possible change" },
+      { title: "Verify fix", details: "Test passes, reproduction no longer fails" },
+      { title: "Regression test", details: "Ensure no related tests broken" },
+      { title: "Document in changelog", details: "Brief description + issue link" }
+    ]
+  },
+  "refactor": {
+    name: "refactor",
+    description: "Safe refactoring workflow",
+    category: "maintenance",
+    items: [
+      { title: "Identify refactoring target", details: "Code smell, performance bottleneck, or tech debt" },
+      { title: "Ensure test coverage", details: "Existing tests must pass before and after" },
+      { title: "Write characterization tests", details: "Capture current behavior if tests weak" },
+      { title: "Apply refactoring", details: "Small steps, frequent commits" },
+      { title: "Run full test suite", details: "All tests must pass" },
+      { title: "Performance check", details: "Ensure no regression" },
+      { title: "Code review", details: "Explain the why, not just the what" }
+    ]
+  },
+  "release": {
+    name: "release",
+    description: "Preparing a new release",
+    category: "release",
+    items: [
+      { title: "Version bump", details: "package.json, lockfiles, tags" },
+      { title: "Update changelog", details: "All changes since last release" },
+      { title: "Run full test suite", details: "Unit + integration + e2e" },
+      { title: "Build artifacts", details: "Docker images, bundles, binaries" },
+      { title: "Staging smoke tests", details: "Deploy to staging, verify" },
+      { title: "Production deploy", details: "Blue-green or canary" },
+      { title: "Post-deploy verification", details: "Health checks, error rates" },
+      { title: "Announce release", details: "Slack, email, GitHub release notes" }
+    ]
+  },
+  "security-audit": {
+    name: "security-audit",
+    description: "Security review and hardening",
+    category: "infrastructure",
+    items: [
+      { title: "Dependency audit", details: "npm audit, Snyk, Dependabot alerts" },
+      { title: "Secret scan", details: "git-secrets, truffleHog, manual review" },
+      { title: "Access control review", details: "IAM, roles, least privilege" },
+      { title: "Input validation audit", details: "SQL injection, XSS, path traversal" },
+      { title: "Authentication review", details: "Session management, MFA, password policy" },
+      { title: "Logging and monitoring", details: "PII in logs, audit trails" },
+      { title: "Incident response plan", details: "Runbooks, contacts, escalation" }
+    ]
+  },
+  "onboarding": {
+    name: "onboarding",
+    description: "New developer onboarding checklist",
+    category: "infrastructure",
+    items: [
+      { title: "Repository access", details: "GitHub/GitLab permissions" },
+      { title: "Local environment setup", details: "Docker, dependencies, env files" },
+      { title: "Run tests locally", details: "Verify green suite" },
+      { title: "Read architecture docs", details: "ADR, README, onboarding guide" },
+      { title: "First commit", details: "Docs fix or small improvement" },
+      { title: "Pair programming session", details: "Walk through codebase with buddy" },
+      { title: "Deploy to staging", details: "Verify CI/CD access" }
+    ]
+  }
+};
+function listPlanTemplates() {
+  return Object.values(templates);
+}
+function getPlanTemplate(name) {
+  return templates[name];
+}
+function formatPlanTemplates() {
+  const cats = /* @__PURE__ */ new Map();
+  for (const t of Object.values(templates)) {
+    const arr = cats.get(t.category) ?? [];
+    arr.push(t);
+    cats.set(t.category, arr);
+  }
+  const lines = ["Available plan templates:"];
+  for (const [cat, items] of cats) {
+    lines.push(`
+${cat}:`);
+    for (const t of items) {
+      lines.push(`  ${t.name.padEnd(18)} \u2014 ${t.description}`);
+    }
+  }
+  return lines.join("\n");
+}
 async function loadDirectorState(filePath) {
   let raw;
   try {
@@ -2200,15 +2345,48 @@ async function loadDirectorState(filePath) {
     return null;
   }
 }
+async function acquireDirectorStateLock(lockPath, processId = process.pid) {
+  let existing;
+  try {
+    existing = await fsp.readFile(lockPath, "utf8");
+  } catch {
+  }
+  if (existing) {
+    try {
+      const lock2 = JSON.parse(existing);
+      try {
+        process.kill(lock2.pid, 0);
+        return false;
+      } catch {
+      }
+    } catch {
+    }
+  }
+  const lock = {
+    pid: processId,
+    hostname: __require("os").hostname(),
+    startedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await atomicWrite(lockPath, JSON.stringify(lock), { mode: 384 });
+  return true;
+}
+async function releaseDirectorStateLock(lockPath) {
+  try {
+    await fsp.unlink(lockPath);
+  } catch {
+  }
+}
 var DirectorStateCheckpoint = class {
   snapshot;
   filePath;
+  lockPath;
   timer = null;
   debounceMs;
   writing = false;
   rewriteRequested = false;
   constructor(filePath, init, debounceMs = 250) {
     this.filePath = filePath;
+    this.lockPath = `${filePath}.lock`;
     this.debounceMs = debounceMs;
     this.snapshot = {
       version: 1,
@@ -2218,10 +2396,36 @@ var DirectorStateCheckpoint = class {
       maxSpawns: init.maxSpawns,
       spawnDepth: init.spawnDepth,
       maxSpawnDepth: init.maxSpawnDepth,
+      directorBudget: init.directorBudget,
       subagents: [],
       tasks: []
     };
   }
+  /**
+   * Attempt to acquire the lock for this checkpoint. Call this before
+   * resuming a crashed director run. If it returns false, another
+   * director process is still running this fleet — do not resume.
+   */
+  async acquireLock() {
+    return acquireDirectorStateLock(this.lockPath);
+  }
+  /**
+   * Release the lock on graceful shutdown. Call `flush()` first to ensure
+   * the final checkpoint state is on disk before removing the lock.
+   * Without this, the next resume will see a stale-lock and refuse.
+   */
+  async releaseLock() {
+    return releaseDirectorStateLock(this.lockPath);
+  }
+  /**
+   * Resume from a snapshot previously loaded via `loadDirectorState()`.
+   * Use this when `--resume <runId>` is triggered — the snapshot has
+   * the full fleet state (subagents, tasks) from before the crash; the
+   * checkpoint continues from there.
+   */
+  resume(snapshot) {
+    this.snapshot = snapshot;
+  }
   current() {
     return this.snapshot;
   }
@@ -2305,6 +2509,6 @@ var DirectorStateCheckpoint = class {
   }
 };
 
-export { ConfigMigrationError, DEFAULT_CONFIG_MIGRATIONS, DefaultAttachmentStore, DefaultConfigLoader, DefaultConfigStore, DefaultMemoryStore, DefaultSessionReader, DefaultSessionRewinder, DefaultSessionStore, DirectorStateCheckpoint, QueueStore, RecoveryLock, SessionAnalyzer, addPlanItem, attachPlanCheckpoint, attachTodosCheckpoint, clearPlan, emptyPlan, formatPlan, loadDirectorState, loadPlan, loadTodosCheckpoint, removePlanItem, runConfigMigrations, savePlan, saveTodosCheckpoint, setPlanItemStatus };
+export { ConfigMigrationError, DEFAULT_CONFIG_MIGRATIONS, DefaultAttachmentStore, DefaultConfigLoader, DefaultConfigStore, DefaultMemoryStore, DefaultSessionReader, DefaultSessionRewinder, DefaultSessionStore, DirectorStateCheckpoint, QueueStore, RecoveryLock, SessionAnalyzer, addPlanItem, attachPlanCheckpoint, attachTodosCheckpoint, clearPlan, deriveTodosFromPlanItem, emptyPlan, formatPlan, formatPlanTemplates, getPlanTemplate, listPlanTemplates, loadDirectorState, loadPlan, loadTodosCheckpoint, removePlanItem, runConfigMigrations, savePlan, saveTodosCheckpoint, setPlanItemStatus };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map