@kynetic-ai/spec 0.9.0 → 0.10.0

package/dist/parser/yaml.js

@@ -4,6 +4,7 @@ import * as path from "node:path";
 import { ulid } from "ulid";
 import * as YAML from "yaml";
 import { withFileLock } from "./file-lock.js";
+import { accessBufferAware, getActiveBatchBuffer, readdirBufferAware, } from "../cli/batch-write-buffer.js";
 import { InboxFileSchema, InboxItemSchema, ManifestSchema, SpecItemSchema, TaskSchema, TasksFileSchema, TriageFileSchema, TriageRecordSchema, } from "../schema/index.js";
 import { errors } from "../strings/index.js";
 import { ItemIndex } from "./items.js";
@@ -68,10 +69,32 @@ export function toYaml(obj) {
     return yamlString;
 }
 /**
- * Read and parse a YAML file
+ * Read a text file with batch buffer overlay semantics.
+ */
+export async function readFileBufferAware(filePath) {
+    // AC: @batch-write-buffer ac-2 — check buffer first for read-after-write consistency
+    const buffer = getActiveBatchBuffer();
+    if (buffer?.isInScope(filePath)) {
+        const buffered = buffer.read(filePath);
+        if (buffered !== undefined) {
+            if (buffered === null) {
+                // File was deleted in this batch
+                throw Object.assign(new Error(`ENOENT: no such file or directory, open '${filePath}'`), {
+                    code: "ENOENT",
+                });
+            }
+            return typeof buffered === "string"
+                ? buffered
+                : Buffer.from(buffered).toString("utf-8");
+        }
+    }
+    return fs.readFile(filePath, "utf-8");
+}
+/**
+ * Read and parse a YAML file.
  */
 export async function readYamlFile(filePath) {
-    const content = await fs.readFile(filePath, "utf-8");
+    const content = await readFileBufferAware(filePath);
     return parseYaml(content);
 }
 /**
@@ -79,6 +102,12 @@ export async function readYamlFile(filePath) {
  */
 export async function writeYamlFile(filePath, data) {
     const content = toYaml(data);
+    // AC: @batch-write-buffer ac-1 — buffer write if in batch mode
+    const buffer = getActiveBatchBuffer();
+    if (buffer?.isInScope(filePath)) {
+        buffer.write(filePath, content);
+        return;
+    }
     await fs.writeFile(filePath, content, "utf-8");
 }
 /**
@@ -90,6 +119,12 @@ export async function writeYamlFile(filePath, data) {
  */
 export async function writeYamlFilePreserveFormat(filePath, data) {
     const content = toYaml(data);
+    // AC: @batch-write-buffer ac-1 — buffer write if in batch mode
+    const buffer = getActiveBatchBuffer();
+    if (buffer?.isInScope(filePath)) {
+        buffer.write(filePath, content);
+        return;
+    }
     await fs.writeFile(filePath, content, "utf-8");
 }
 /**
@@ -98,7 +133,7 @@ export async function writeYamlFilePreserveFormat(filePath, data) {
 export async function findTaskFiles(dir) {
     const files = [];
     try {
-        const entries = await fs.readdir(dir, { withFileTypes: true });
+        const entries = await readdirBufferAware(dir, { withFileTypes: true });
         for (const entry of entries) {
             const fullPath = path.join(dir, entry.name);
             if (entry.isDirectory()) {
@@ -292,7 +327,7 @@ async function findManifestInDir(dir) {
     for (const candidate of priorityCandidates) {
         const filePath = path.join(dir, candidate);
         try {
-            await fs.access(filePath);
+            await accessBufferAware(filePath);
             return filePath;
         }
         catch {
@@ -301,7 +336,7 @@ async function findManifestInDir(dir) {
     }
     // AC: @manifest-discovery ac-3, ac-4, ac-5 - glob fallback with validation
     try {
-        const entries = await fs.readdir(dir);
+        const entries = await readdirBufferAware(dir);
         // AC: @manifest-discovery ac-4 - alphabetical order
         const candidates = entries.filter(isManifestCandidate).sort();
         for (const candidate of candidates) {
@@ -373,8 +408,10 @@ async function loadTasksFromFile(filePath) {
  */
 export async function loadAllTasks(ctx) {
     const tasks = [];
-    // When shadow is enabled, look only in specDir
-    if (ctx.shadow?.enabled) {
+    // When shadow is enabled (or spec dir is explicitly overridden), look only in specDir.
+    // KSPEC_SPEC_DIR override is used by batch mode and some integration tests to isolate
+    // task state to a temp directory; scanning ctx.rootDir can leak tasks from parent dirs.
+    if (ctx.shadow?.enabled || Boolean(process.env.KSPEC_SPEC_DIR)) {
         const taskFiles = await findTaskFiles(ctx.specDir);
         // Also check for standalone files in specDir
         const standaloneLocations = [
@@ -386,7 +423,7 @@ export async function loadAllTasks(ctx) {
         ];
         for (const loc of standaloneLocations) {
             try {
-                await fs.access(loc);
+                await accessBufferAware(loc);
                 if (!taskFiles.includes(loc)) {
                     taskFiles.push(loc);
                 }
@@ -424,7 +461,7 @@ export async function loadAllTasks(ctx) {
     ];
     for (const loc of standaloneLocations) {
         try {
-            await fs.access(loc);
+            await accessBufferAware(loc);
             if (!taskFiles.includes(loc)) {
                 taskFiles.push(loc);
             }
@@ -554,6 +591,58 @@ export async function saveTask(ctx, task) {
         }
     });
 }
+/**
+ * Atomically mutate a task using the latest on-disk state.
+ *
+ * The callback receives the current task value while holding the task file lock,
+ * so concurrent writers cannot clobber unrelated fields (for example status vs notes).
+ */
+export async function mutateTaskAtomically(ctx, task, mutate) {
+    const taskFilePath = task._sourceFile || getDefaultTaskFilePath(ctx);
+    let updatedTask;
+    await withFileLock(taskFilePath, async () => {
+        // Ensure directory exists (important for default path in new repos)
+        const dir = path.dirname(taskFilePath);
+        await fs.mkdir(dir, { recursive: true });
+        // Preserve existing file format (tasks wrapper vs plain array)
+        let existingRaw = null;
+        let useTasksWrapper = false;
+        try {
+            existingRaw = await readYamlFile(taskFilePath);
+            if (existingRaw &&
+                typeof existingRaw === "object" &&
+                "tasks" in existingRaw) {
+                useTasksWrapper = true;
+            }
+        }
+        catch {
+            throw new Error(`Task file not found: ${taskFilePath}`);
+        }
+        const fileTasks = await loadTasksFromFile(taskFilePath);
+        const taskIndex = fileTasks.findIndex((t) => t._ulid === task._ulid);
+        if (taskIndex === -1) {
+            throw new Error(`Task not found in file: ${task._ulid}`);
+        }
+        const latestTask = fileTasks[taskIndex];
+        const mutatedTask = await mutate(latestTask);
+        const cleanMutatedTask = stripRuntimeMetadata(mutatedTask);
+        const serializedTasks = fileTasks.map((fileTask, index) => index === taskIndex ? cleanMutatedTask : stripRuntimeMetadata(fileTask));
+        if (useTasksWrapper) {
+            await writeYamlFilePreserveFormat(taskFilePath, { tasks: serializedTasks });
+        }
+        else {
+            await writeYamlFilePreserveFormat(taskFilePath, serializedTasks);
+        }
+        updatedTask = {
+            ...cleanMutatedTask,
+            _sourceFile: taskFilePath,
+        };
+    });
+    if (!updatedTask) {
+        throw new Error(`Failed to mutate task atomically: ${task._ulid}`);
+    }
+    return updatedTask;
+}
 /**
  * Delete a task from its source file.
  * Requires _sourceFile to know which file to modify.
@@ -736,28 +825,34 @@ export function areDependenciesMet(task, allTasks) {
     return true;
 }
 /**
- * Check if task is ready (pending + deps met + not blocked)
+ * Check if task is ready (pending/needs_work + deps met + not blocked)
  */
 export function isTaskReady(task, allTasks) {
-    if (task.status !== "pending")
+    if (task.status !== "pending" && task.status !== "needs_work")
         return false;
     if (task.blocked_by.length > 0)
         return false;
     return areDependenciesMet(task, allTasks);
 }
 /**
- * Get ready tasks (pending + deps met + not blocked), sorted by priority then creation time.
- * Within the same priority tier, older tasks come first (FIFO).
+ * Get ready tasks (pending/needs_work + deps met + not blocked), sorted by
+ * status (needs_work first), then priority, then creation time.
+ * Within the same tier, older tasks come first (FIFO).
  */
 export function getReadyTasks(tasks) {
     return tasks
         .filter((task) => isTaskReady(task, tasks))
         .sort((a, b) => {
-        // Primary: priority (lower number = higher priority)
+        // Primary: needs_work before pending (fix cycles take priority)
+        const statusOrder = (s) => (s === "needs_work" ? 0 : 1);
+        const statusDiff = statusOrder(a.status) - statusOrder(b.status);
+        if (statusDiff !== 0)
+            return statusDiff;
+        // Secondary: priority (lower number = higher priority)
         if (a.priority !== b.priority) {
             return a.priority - b.priority;
         }
-        // Secondary: creation time (older first - FIFO within priority)
+        // Tertiary: creation time (older first - FIFO within priority)
         return (new Date(a.created_at).getTime() - new Date(b.created_at).getTime());
     });
 }
@@ -775,7 +870,7 @@ export async function expandIncludePattern(pattern, baseDir) {
     // If no glob characters, just return the path if it exists
     if (!pattern.includes("*")) {
         try {
-            await fs.access(fullPattern);
+            await accessBufferAware(fullPattern);
             return [fullPattern];
         }
         catch {
@@ -805,7 +900,7 @@ async function expandGlobRecursive(dir, pattern, result) {
     const currentPattern = parts[0];
     const remainingPattern = parts.slice(1).join("/");
     try {
-        const entries = await fs.readdir(dir, { withFileTypes: true });
+        const entries = await readdirBufferAware(dir, { withFileTypes: true });
         for (const entry of entries) {
             const matches = matchGlobPart(entry.name, currentPattern);
             if (matches) {
@@ -948,7 +1043,7 @@ export function extractItemsFromRaw(raw, sourceFile, items = [], currentPath = "
  */
 export async function loadSpecFile(filePath) {
     try {
-        const content = await fs.readFile(filePath, "utf-8");
+        const content = await readFileBufferAware(filePath);
         const items = [];
         // Parse all YAML documents in the file (handles files with ---)
         const documents = YAML.parseAllDocuments(content);
@@ -1058,6 +1153,12 @@ function stripSpecItemMetadata(item) {
     const { _sourceFile, _path, ...cleanItem } = item;
     return cleanItem;
 }
+function assertSpecItemPatch(updates, operation) {
+    const patch = updates;
+    if ("_sourceFile" in patch || "_path" in patch) {
+        throw new Error(`${operation} expects a patch object, not a full LoadedSpecItem. Pass only intended fields to update.`);
+    }
+}
 /**
  * Parse a path string into segments.
  * e.g., "features[0].requirements[2]" -> [["features", 0], ["requirements", 2]]
@@ -1225,6 +1326,7 @@ export async function updateSpecItem(_ctx, item, updates) {
     if (!item._sourceFile) {
         throw new Error("Item has no source file");
     }
+    assertSpecItemPatch(updates, "updateSpecItem");
     // Lock the file to prevent concurrent read-modify-write races
     return withFileLock(item._sourceFile, async () => {
         // Load the raw YAML
@@ -1233,10 +1335,19 @@ export async function updateSpecItem(_ctx, item, updates) {
         let targetObj;
         if (item._path) {
             const nav = navigateToPath(raw, item._path);
-            if (!nav) {
-                throw new Error(`Could not navigate to path: ${item._path}`);
+            const candidate = nav?.array[nav.index];
+            if (candidate &&
+                typeof candidate === "object" &&
+                candidate._ulid === item._ulid) {
+                targetObj = candidate;
+            }
+            else {
+                const found = findItemInStructure(raw, item._ulid);
+                if (!found) {
+                    throw new Error(`Could not find item ${item._ulid} in structure (path: ${item._path})`);
+                }
+                targetObj = found.item;
             }
-            targetObj = nav.array[nav.index];
         }
         else {
             // Item might be the root, or we need to find it
@@ -1334,10 +1445,14 @@ export async function deleteSpecItem(_ctx, item) {
  * Save a spec item - either updates existing or adds to parent.
  * For new items, use addChildItem instead.
  */
-export async function saveSpecItem(ctx, item) {
+export async function saveSpecItem(ctx, item, updates) {
+    assertSpecItemPatch(updates, "saveSpecItem");
+    if (Object.keys(updates).length === 0) {
+        throw new Error("Cannot save spec item without updates. Pass a patch.");
+    }
     // If item has a source file and path, it's an update
     if (item._sourceFile && item._path) {
-        await updateSpecItem(ctx, item, item);
+        await updateSpecItem(ctx, item, updates);
         return;
     }
     // Otherwise, this is more complex - would need a parent
@@ -1353,34 +1468,60 @@ export function getInboxFilePath(ctx) {
     return path.join(ctx.specDir, "project.inbox.yaml");
 }
 /**
- * Load all inbox items from the project.
+ * Parse inbox items from raw YAML payload.
+ *
+ * Supports canonical { inbox: [...] } shape and legacy plain-array shape.
  */
-export async function loadInboxItems(ctx) {
-    const inboxPath = getInboxFilePath(ctx);
-    try {
-        const raw = await readYamlFile(inboxPath);
-        // Handle { inbox: [...] } format
-        if (raw && typeof raw === "object" && "inbox" in raw) {
-            const parsed = InboxFileSchema.safeParse(raw);
-            if (parsed.success) {
-                return parsed.data.inbox.map((item) => ({
-                    ...item,
-                    _sourceFile: inboxPath,
-                }));
-            }
-        }
-        // Handle plain array format
-        if (Array.isArray(raw)) {
+function parseInboxItemsFromRaw(raw) {
+    // Handle { inbox: [...] } format
+    if (raw && typeof raw === "object" && "inbox" in raw) {
+        const parsed = InboxFileSchema.safeParse(raw);
+        if (parsed.success) {
+            return parsed.data.inbox;
+        }
+        const fallbackItems = raw.inbox;
+        if (Array.isArray(fallbackItems)) {
             const items = [];
-            for (const item of raw) {
+            for (const item of fallbackItems) {
                 const result = InboxItemSchema.safeParse(item);
                 if (result.success) {
-                    items.push({ ...result.data, _sourceFile: inboxPath });
+                    items.push(result.data);
                 }
             }
             return items;
         }
-        return [];
+    }
+    // Handle plain array format
+    if (Array.isArray(raw)) {
+        const items = [];
+        for (const item of raw) {
+            const result = InboxItemSchema.safeParse(item);
+            if (result.success) {
+                items.push(result.data);
+            }
+        }
+        return items;
+    }
+    return [];
+}
+/**
+ * Load inbox items from an explicit file path.
+ */
+async function loadInboxItemsFromFile(inboxPath) {
+    const raw = await readYamlFile(inboxPath);
+    return parseInboxItemsFromRaw(raw);
+}
+/**
+ * Load all inbox items from the project.
+ */
+export async function loadInboxItems(ctx) {
+    const inboxPath = getInboxFilePath(ctx);
+    try {
+        const items = await loadInboxItemsFromFile(inboxPath);
+        return items.map((item) => ({
+            ...item,
+            _sourceFile: inboxPath,
+        }));
     }
     catch {
         // File doesn't exist or parse error
@@ -1424,21 +1565,7 @@ export async function saveInboxItem(ctx, item) {
         // Load existing items
         let existingItems = [];
         try {
-            const raw = await readYamlFile(inboxPath);
-            if (raw && typeof raw === "object" && "inbox" in raw) {
-                const parsed = InboxFileSchema.safeParse(raw);
-                if (parsed.success) {
-                    existingItems = parsed.data.inbox;
-                }
-            }
-            else if (Array.isArray(raw)) {
-                for (const i of raw) {
-                    const result = InboxItemSchema.safeParse(i);
-                    if (result.success) {
-                        existingItems.push(result.data);
-                    }
-                }
-            }
+            existingItems = await loadInboxItemsFromFile(inboxPath);
         }
         catch {
             // File doesn't exist, start fresh
@@ -1456,6 +1583,48 @@ export async function saveInboxItem(ctx, item) {
         await writeYamlFilePreserveFormat(inboxPath, { inbox: existingItems });
     });
 }
+/**
+ * Atomically mutate an inbox item using the latest on-disk state.
+ *
+ * The callback receives the current item value while holding the inbox file lock,
+ * so concurrent writers do not clobber unrelated fields (for example text vs tags).
+ */
+export async function mutateInboxItemAtomically(ctx, item, mutate) {
+    const inboxPath = item._sourceFile || getInboxFilePath(ctx);
+    let updatedItem;
+    await withFileLock(inboxPath, async () => {
+        // Ensure directory exists (important for default path in new repos)
+        const dir = path.dirname(inboxPath);
+        await fs.mkdir(dir, { recursive: true });
+        let existingItems = [];
+        try {
+            existingItems = await loadInboxItemsFromFile(inboxPath);
+        }
+        catch {
+            throw new Error(`Inbox file not found: ${inboxPath}`);
+        }
+        const itemIndex = existingItems.findIndex((existingItem) => existingItem._ulid === item._ulid);
+        if (itemIndex === -1) {
+            throw new Error(`Inbox item not found in file: ${item._ulid}`);
+        }
+        const latestItem = {
+            ...existingItems[itemIndex],
+            _sourceFile: inboxPath,
+        };
+        const mutatedItem = await mutate(latestItem);
+        const cleanMutatedItem = stripInboxMetadata(mutatedItem);
+        existingItems[itemIndex] = cleanMutatedItem;
+        await writeYamlFilePreserveFormat(inboxPath, { inbox: existingItems });
+        updatedItem = {
+            ...cleanMutatedItem,
+            _sourceFile: inboxPath,
+        };
+    });
+    if (!updatedItem) {
+        throw new Error(`Failed to mutate inbox item atomically: ${item._ulid}`);
+    }
+    return updatedItem;
+}
 /**
  * Delete an inbox item by ULID.
  */
@@ -1464,14 +1633,7 @@ export async function deleteInboxItem(ctx, ulid) {
     // Lock the file to prevent concurrent read-modify-write races
     return withFileLock(inboxPath, async () => {
         try {
-            const raw = await readYamlFile(inboxPath);
-            let existingItems = [];
-            if (raw && typeof raw === "object" && "inbox" in raw) {
-                const parsed = InboxFileSchema.safeParse(raw);
-                if (parsed.success) {
-                    existingItems = parsed.data.inbox;
-                }
-            }
+            const existingItems = await loadInboxItemsFromFile(inboxPath);
             const index = existingItems.findIndex((i) => i._ulid === ulid);
             if (index < 0) {
                 return false;