@wrongstack/core 0.283.1 → 0.284.0

package/dist/tasking/index.d.ts

@@ -0,0 +1,124 @@
+import { d as TaskGraph, e as TaskNode, k as TaskFilter, l as TaskSort, c as TaskProgress } from '../task-graph-CH3acNQ7.js';
+
+interface TaskStore {
+    saveGraph(graph: TaskGraph): Promise<void>;
+    loadGraph(id: string): Promise<TaskGraph | null>;
+    listGraphs(): Promise<{
+        id: string;
+        title: string;
+        updatedAt: number;
+    }[]>;
+    deleteGraph(id: string): Promise<void>;
+}
+interface TaskTrackerOptions {
+    store: TaskStore;
+    /**
+     * Called when an in-the-background persistence (`saveGraph`) rejects.
+     * The synchronous TaskTracker methods (addNode/addEdge/updateNodeStatus)
+     * fire-and-forget their writes; without this, a failing store silently
+     * loses graph mutations. Defaults to a console.warn.
+     */
+    onPersistError?: (((err: unknown) => void)) | undefined;
+}
+interface TaskTransition {
+    from: TaskNode['status'];
+    to: TaskNode['status'];
+    timestamp: number;
+    reason?: string | undefined;
+}
+/** A change notification emitted to `TaskTracker.subscribe` listeners. */
+interface TaskTrackerChange {
+    type: 'node_added' | 'node_updated' | 'status_changed' | 'node_removed';
+    nodeId: string;
+    /** For `node_removed` this is the node as it was just before deletion. */
+    node: TaskNode;
+    transition?: TaskTransition | undefined;
+}
+type TaskTrackerListener = (change: TaskTrackerChange) => void;
+declare class TaskTracker {
+    private readonly opts;
+    private graph;
+    private transitions;
+    private listeners;
+    constructor(opts: TaskTrackerOptions);
+    /**
+     * Subscribe to live task mutations (add / update / status change). Returns an
+     * unsubscribe fn. This is the hook the board projector uses to stream a live
+     * snapshot — the tracker was previously fire-and-forget with no observability.
+     */
+    subscribe(listener: TaskTrackerListener): () => void;
+    private notifyChange;
+    /**
+     * Attach an existing graph (used by PhaseOrchestrator to associate a tracker
+     * with a phase's pre-built task graph without re-creating it).
+     */
+    setGraph(graph: TaskGraph): void;
+    createGraph(specId: string, title: string): Promise<TaskGraph>;
+    loadGraph(id: string): Promise<TaskGraph | null>;
+    addNode(node: Omit<TaskNode, 'id' | 'createdAt' | 'updatedAt'>): TaskNode;
+    addEdge(from: string, to: string, type?: TaskGraph['edges'][0]['type']): void;
+    /**
+     * Declare that `taskId` depends on `depId` (a `depends_on` edge `depId → taskId`),
+     * guarding against self-loops, duplicates, missing nodes, and cycles. Returns
+     * true if the dependency now holds (added or already present), false if it was
+     * rejected (would create a cycle / unknown node). This is the safe entry point
+     * for wiring agent-declared `dependsOn` references into the graph.
+     */
+    addDependency(depId: string, taskId: string): boolean;
+    /** True when `taskId` transitively depends on `targetId` (follows depends_on blockers). */
+    private dependsOnTransitively;
+    /**
+     * Merge `patch` into a node's `metadata` (used for per-task model/provider/
+     * fallback assignment and the cancel marker). Persists + notifies as a node
+     * update. No-op if the node is missing.
+     */
+    patchMetadata(id: string, patch: Record<string, unknown>): void;
+    /**
+     * Remove a node and every edge touching it. Intended for deleting a task that
+     * has not started yet — callers must gate on status (do not remove a running
+     * task). Dependents simply lose this blocker (re-evaluated by `canStart`).
+     * Returns true if a node was removed.
+     */
+    removeNode(id: string): boolean;
+    updateNodeStatus(id: string, status: TaskNode['status'], reason?: string): void;
+    updateNode(id: string, patch: Partial<Pick<TaskNode, 'title' | 'description' | 'priority' | 'estimateHours' | 'tags' | 'assignee'>>): void;
+    getNode(id: string): TaskNode | undefined;
+    getAllNodes(filter?: TaskFilter, sort?: TaskSort): TaskNode[];
+    getChildren(parentId: string): TaskNode[];
+    getDependents(taskId: string): string[];
+    getBlockers(taskId: string): string[];
+    canStart(taskId: string): boolean;
+    getProgress(): TaskProgress;
+    getTransitions(_taskId?: string): TaskTransition[];
+    private unblockDependents;
+    private checkAndBlockIfNeeded;
+    /**
+     * Fire-and-forget persistence with attached error handler.
+     * Synchronous mutators (addNode/addEdge/updateNodeStatus) use this to
+     * avoid forcing an async cascade through every caller; if the store
+     * is missing or throwing, the error is surfaced via onPersistError.
+     */
+    private persist;
+}
+
+/**
+ * In-memory task-graph store used by AutoPhase and tests.
+ *
+ * The store clones the graph container on read/write so callers cannot replace
+ * its Maps/arrays behind the store's back. Task nodes themselves intentionally
+ * remain shared: TaskTracker owns node mutation and persists after each change.
+ */
+declare class DefaultTaskStore implements TaskStore {
+    private readonly graphs;
+    saveGraph(graph: TaskGraph): Promise<void>;
+    loadGraph(id: string): Promise<TaskGraph | null>;
+    listGraphs(): Promise<Array<{
+        id: string;
+        title: string;
+        updatedAt: number;
+    }>>;
+    deleteGraph(id: string): Promise<void>;
+    private cloneGraph;
+}
+
+export { DefaultTaskStore, type TaskStore, TaskTracker, type TaskTrackerChange, type TaskTrackerListener, type TaskTrackerOptions, type TaskTransition };

package/dist/tasking/index.js

@@ -0,0 +1,492 @@
+// src/tasking/task-store.ts
+var DefaultTaskStore = class {
+  graphs = /* @__PURE__ */ new Map();
+  async saveGraph(graph) {
+    this.graphs.set(graph.id, this.cloneGraph(graph));
+  }
+  async loadGraph(id) {
+    const graph = this.graphs.get(id);
+    return graph ? this.cloneGraph(graph) : null;
+  }
+  async listGraphs() {
+    return Array.from(this.graphs.values()).map((graph) => ({
+      id: graph.id,
+      title: graph.title,
+      updatedAt: graph.updatedAt
+    }));
+  }
+  async deleteGraph(id) {
+    this.graphs.delete(id);
+  }
+  cloneGraph(graph) {
+    return {
+      ...graph,
+      nodes: new Map(graph.nodes),
+      edges: [...graph.edges],
+      rootNodes: [...graph.rootNodes]
+    };
+  }
+};
+
+// src/types/task-graph.ts
+function computeTaskProgress(graph) {
+  let completed = 0;
+  let pending = 0;
+  let inProgress = 0;
+  let blocked = 0;
+  let failed = 0;
+  let review = 0;
+  let estimatedHours = 0;
+  let actualHours = 0;
+  for (const n of graph.nodes.values()) {
+    switch (n.status) {
+      case "completed":
+        completed++;
+        break;
+      case "pending":
+        pending++;
+        break;
+      case "in_progress":
+        inProgress++;
+        break;
+      case "blocked":
+        blocked++;
+        break;
+      case "failed":
+        failed++;
+        break;
+      case "review":
+        review++;
+        break;
+    }
+    estimatedHours += n.estimateHours ?? 0;
+    actualHours += n.actualHours ?? 0;
+  }
+  const total = graph.nodes.size;
+  return {
+    total,
+    pending,
+    inProgress,
+    blocked,
+    failed,
+    review,
+    completed,
+    percentComplete: total > 0 ? Math.round(completed / total * 100) : 0,
+    estimatedHours,
+    actualHours
+  };
+}
+
+// src/utils/error.ts
+function toErrorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/types/errors.ts
+var ERROR_CODES = {
+  SDD_PARSE_FAILED: "SDD_PARSE_FAILED",
+  SDD_INVALID_STATE: "SDD_INVALID_STATE",
+  SDD_NOT_READY: "SDD_NOT_READY"};
+var WrongStackError = class extends Error {
+  code;
+  subsystem;
+  severity;
+  recoverable;
+  context;
+  constructor(opts) {
+    super(opts.message, { cause: opts.cause });
+    this.name = "WrongStackError";
+    this.code = opts.code;
+    this.subsystem = opts.subsystem;
+    this.severity = opts.severity ?? "error";
+    this.recoverable = opts.recoverable ?? false;
+    this.context = opts.context;
+  }
+  /**
+   * Render a one-line user-facing description.
+   * Subclasses should override for domain-specific formatting.
+   */
+  describe() {
+    const ctx = this.context ? ` ${formatContext(this.context)}` : "";
+    return `${this.code}: ${this.message}${ctx}`;
+  }
+};
+function formatContext(ctx) {
+  const parts = Object.entries(ctx).filter(([, v]) => v !== void 0).slice(0, 3).map(([k, v]) => `${k}=${String(v)}`);
+  return parts.length > 0 ? `[${parts.join(" ")}]` : "";
+}
+var SddError = class extends WrongStackError {
+  constructor(opts) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: "sdd",
+      severity: opts.code === ERROR_CODES.SDD_PARSE_FAILED ? "warning" : "error",
+      recoverable: opts.code === ERROR_CODES.SDD_NOT_READY,
+      context: opts.context,
+      cause: opts.cause
+    });
+    this.name = "SddError";
+  }
+};
+
+// src/tasking/task-tracker.ts
+var TaskTracker = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  graph = null;
+  transitions = [];
+  listeners = [];
+  /**
+   * Subscribe to live task mutations (add / update / status change). Returns an
+   * unsubscribe fn. This is the hook the board projector uses to stream a live
+   * snapshot — the tracker was previously fire-and-forget with no observability.
+   */
+  subscribe(listener) {
+    this.listeners.push(listener);
+    return () => {
+      const i = this.listeners.indexOf(listener);
+      if (i >= 0) this.listeners.splice(i, 1);
+    };
+  }
+  notifyChange(change) {
+    for (const l of this.listeners) {
+      try {
+        l(change);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Attach an existing graph (used by PhaseOrchestrator to associate a tracker
+   * with a phase's pre-built task graph without re-creating it).
+   */
+  setGraph(graph) {
+    this.graph = graph;
+  }
+  async createGraph(specId, title) {
+    this.graph = {
+      id: crypto.randomUUID(),
+      specId,
+      title,
+      nodes: /* @__PURE__ */ new Map(),
+      edges: [],
+      rootNodes: [],
+      createdAt: Date.now(),
+      updatedAt: Date.now()
+    };
+    await this.opts.store.saveGraph(this.graph);
+    return this.graph;
+  }
+  async loadGraph(id) {
+    this.graph = await this.opts.store.loadGraph(id);
+    return this.graph;
+  }
+  addNode(node) {
+    if (!this.graph) throw new SddError({
+      message: "No graph loaded",
+      code: ERROR_CODES.SDD_INVALID_STATE
+    });
+    const now = Date.now();
+    const newNode = {
+      ...node,
+      id: crypto.randomUUID(),
+      status: node.status ?? "pending",
+      createdAt: now,
+      updatedAt: now
+    };
+    this.graph.nodes.set(newNode.id, newNode);
+    if (!node.parentId) {
+      this.graph.rootNodes.push(newNode.id);
+    }
+    this.graph.updatedAt = now;
+    this.persist();
+    this.notifyChange({ type: "node_added", nodeId: newNode.id, node: newNode });
+    return newNode;
+  }
+  addEdge(from, to, type = "depends_on") {
+    if (!this.graph) throw new SddError({
+      message: "No graph loaded",
+      code: ERROR_CODES.SDD_INVALID_STATE
+    });
+    this.graph.edges.push({
+      id: crypto.randomUUID(),
+      from,
+      to,
+      type
+    });
+    this.graph.updatedAt = Date.now();
+    this.persist();
+  }
+  /**
+   * Declare that `taskId` depends on `depId` (a `depends_on` edge `depId → taskId`),
+   * guarding against self-loops, duplicates, missing nodes, and cycles. Returns
+   * true if the dependency now holds (added or already present), false if it was
+   * rejected (would create a cycle / unknown node). This is the safe entry point
+   * for wiring agent-declared `dependsOn` references into the graph.
+   */
+  addDependency(depId, taskId) {
+    if (!this.graph) return false;
+    if (depId === taskId) return false;
+    if (!this.graph.nodes.has(depId) || !this.graph.nodes.has(taskId)) return false;
+    if (this.getBlockers(taskId).includes(depId)) return true;
+    if (this.dependsOnTransitively(depId, taskId, /* @__PURE__ */ new Set())) return false;
+    this.addEdge(depId, taskId, "depends_on");
+    return true;
+  }
+  /** True when `taskId` transitively depends on `targetId` (follows depends_on blockers). */
+  dependsOnTransitively(taskId, targetId, seen) {
+    if (taskId === targetId) return true;
+    if (seen.has(taskId)) return false;
+    seen.add(taskId);
+    for (const blocker of this.getBlockers(taskId)) {
+      if (this.dependsOnTransitively(blocker, targetId, seen)) return true;
+    }
+    return false;
+  }
+  /**
+   * Merge `patch` into a node's `metadata` (used for per-task model/provider/
+   * fallback assignment and the cancel marker). Persists + notifies as a node
+   * update. No-op if the node is missing.
+   */
+  patchMetadata(id, patch) {
+    if (!this.graph) return;
+    const node = this.graph.nodes.get(id);
+    if (!node) return;
+    node.metadata = { ...node.metadata, ...patch };
+    node.updatedAt = Date.now();
+    this.graph.updatedAt = node.updatedAt;
+    this.persist();
+    this.notifyChange({ type: "node_updated", nodeId: id, node });
+  }
+  /**
+   * Remove a node and every edge touching it. Intended for deleting a task that
+   * has not started yet — callers must gate on status (do not remove a running
+   * task). Dependents simply lose this blocker (re-evaluated by `canStart`).
+   * Returns true if a node was removed.
+   */
+  removeNode(id) {
+    if (!this.graph) return false;
+    const node = this.graph.nodes.get(id);
+    if (!node) return false;
+    this.graph.nodes.delete(id);
+    this.graph.edges = this.graph.edges.filter((e) => e.from !== id && e.to !== id);
+    this.graph.rootNodes = this.graph.rootNodes.filter((r) => r !== id);
+    for (const n of this.graph.nodes.values()) {
+      if (n.children?.includes(id)) n.children = n.children.filter((c) => c !== id);
+    }
+    this.graph.updatedAt = Date.now();
+    this.persist();
+    this.notifyChange({ type: "node_removed", nodeId: id, node });
+    return true;
+  }
+  updateNodeStatus(id, status, reason) {
+    if (!this.graph) throw new SddError({
+      message: "No graph loaded",
+      code: ERROR_CODES.SDD_INVALID_STATE
+    });
+    const node = this.graph.nodes.get(id);
+    if (!node) throw new SddError({
+      message: `Node ${id} not found`,
+      code: ERROR_CODES.SDD_NOT_READY,
+      context: { nodeId: id }
+    });
+    const from = node.status;
+    const now = Date.now();
+    node.status = status;
+    node.updatedAt = now;
+    if (status === "completed") {
+      node.completedAt = now;
+      node.startedAt = node.startedAt ?? now;
+    }
+    if (status === "in_progress") {
+      node.startedAt = now;
+    }
+    this.transitions.push({ from, to: status, timestamp: now, reason });
+    if (status === "completed") {
+      this.unblockDependents(id);
+    }
+    if (status === "in_progress") {
+      this.checkAndBlockIfNeeded(id);
+    }
+    this.graph.updatedAt = now;
+    this.persist();
+    this.notifyChange({
+      type: "status_changed",
+      nodeId: id,
+      node,
+      transition: { from, to: status, timestamp: now, reason }
+    });
+  }
+  updateNode(id, patch) {
+    if (!this.graph) throw new SddError({
+      message: "No graph loaded",
+      code: ERROR_CODES.SDD_INVALID_STATE
+    });
+    const node = this.graph.nodes.get(id);
+    if (!node) throw new SddError({
+      message: `Node ${id} not found`,
+      code: ERROR_CODES.SDD_NOT_READY,
+      context: { nodeId: id }
+    });
+    if (patch.title !== void 0) node.title = patch.title;
+    if (patch.description !== void 0) node.description = patch.description;
+    if (patch.priority !== void 0) node.priority = patch.priority;
+    if (patch.estimateHours !== void 0) node.estimateHours = patch.estimateHours;
+    if (patch.tags !== void 0) node.tags = patch.tags;
+    if (patch.assignee !== void 0) node.assignee = patch.assignee;
+    node.updatedAt = Date.now();
+    this.graph.updatedAt = node.updatedAt;
+    this.persist();
+    this.notifyChange({ type: "node_updated", nodeId: id, node });
+  }
+  getNode(id) {
+    return this.graph?.nodes.get(id);
+  }
+  getAllNodes(filter, sort) {
+    if (!this.graph) return [];
+    let nodes = Array.from(this.graph.nodes.values());
+    if (filter) {
+      nodes = nodes.filter((n) => {
+        if (filter.status?.length && !filter.status.includes(n.status)) return false;
+        if (filter.priority?.length && !filter.priority.includes(n.priority)) return false;
+        if (filter.type?.length && !filter.type.includes(n.type)) return false;
+        if (filter.assignee?.length && n.assignee && !filter.assignee.includes(n.assignee))
+          return false;
+        if (filter.tags?.length && n.tags && !n.tags.some((t) => filter.tags?.includes(t)))
+          return false;
+        if (filter.specRequirementId && n.specRequirementId !== filter.specRequirementId)
+          return false;
+        return true;
+      });
+    }
+    if (sort) {
+      nodes.sort((a, b) => {
+        const cmp = compareByField(a, b, sort.field);
+        return sort.direction === "asc" ? cmp : -cmp;
+      });
+    }
+    return nodes;
+  }
+  getChildren(parentId) {
+    if (!this.graph) return [];
+    return Array.from(this.graph.nodes.values()).filter((n) => n.parentId === parentId);
+  }
+  getDependents(taskId) {
+    if (!this.graph) return [];
+    return this.graph.edges.filter((e) => e.from === taskId && e.type === "depends_on").map((e) => e.to);
+  }
+  getBlockers(taskId) {
+    if (!this.graph) return [];
+    return this.graph.edges.filter((e) => e.to === taskId && e.type === "depends_on").map((e) => e.from);
+  }
+  canStart(taskId) {
+    const blockers = this.getBlockers(taskId);
+    return blockers.every((id) => {
+      const node = this.graph?.nodes.get(id);
+      return node?.status === "completed" || node?.status === "failed";
+    });
+  }
+  getProgress() {
+    if (!this.graph) {
+      return {
+        total: 0,
+        pending: 0,
+        inProgress: 0,
+        blocked: 0,
+        failed: 0,
+        review: 0,
+        completed: 0,
+        percentComplete: 0,
+        estimatedHours: 0,
+        actualHours: 0
+      };
+    }
+    return computeTaskProgress(this.graph);
+  }
+  getTransitions(_taskId) {
+    return [...this.transitions];
+  }
+  unblockDependents(completedId) {
+    if (!this.graph) return;
+    const dependents = this.getDependents(completedId);
+    for (const depId of dependents) {
+      const dep = this.graph.nodes.get(depId);
+      if (dep?.status === "blocked") {
+        const remainingBlockers = this.getBlockers(depId);
+        const allUnblocked = remainingBlockers.every((id) => {
+          const blocker = this.graph?.nodes.get(id);
+          return blocker?.status === "completed" || blocker?.status === "failed";
+        });
+        if (allUnblocked) {
+          dep.status = "pending";
+          dep.updatedAt = Date.now();
+        }
+      }
+    }
+  }
+  checkAndBlockIfNeeded(taskId) {
+    if (!this.graph) return;
+    const blockers = this.getBlockers(taskId);
+    const someBlocked = blockers.some((id) => {
+      const blocker = this.graph?.nodes.get(id);
+      return blocker?.status !== "completed" && blocker?.status !== "failed";
+    });
+    if (someBlocked) {
+      const node = this.graph.nodes.get(taskId);
+      if (node) {
+        node.status = "blocked";
+        node.updatedAt = Date.now();
+      }
+    }
+  }
+  /**
+   * Fire-and-forget persistence with attached error handler.
+   * Synchronous mutators (addNode/addEdge/updateNodeStatus) use this to
+   * avoid forcing an async cascade through every caller; if the store
+   * is missing or throwing, the error is surfaced via onPersistError.
+   */
+  persist() {
+    if (!this.graph) return;
+    this.opts.store.saveGraph(this.graph).catch((err) => {
+      this.opts.onPersistError ? this.opts.onPersistError(err) : console.warn(JSON.stringify({
+        level: "warn",
+        event: "task_tracker.save_graph_failed",
+        message: toErrorMessage(err),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }));
+    });
+  }
+};
+var PRIORITY_RANK = {
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3
+};
+var STATUS_RANK = {
+  in_progress: 0,
+  pending: 1,
+  review: 2,
+  blocked: 3,
+  failed: 4,
+  completed: 5
+};
+function compareByField(a, b, field) {
+  switch (field) {
+    case "priority":
+      return PRIORITY_RANK[a.priority] - PRIORITY_RANK[b.priority];
+    case "status":
+      return STATUS_RANK[a.status] - STATUS_RANK[b.status];
+    case "createdAt":
+      return a.createdAt - b.createdAt;
+    case "updatedAt":
+      return a.updatedAt - b.updatedAt;
+  }
+}
+
+export { DefaultTaskStore, TaskTracker };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map