@astrosheep/keiyaku 0.1.19 → 0.1.21

package/build/workflow/start.js

@@ -1,24 +1,22 @@
 import * as fs from "fs/promises";
 import * as path from "path";
 import { KEIYAKU_DRAFT_FILE, KEIYAKU_FILE, TRACE_FILE } from "../common/constants.js";
-import { appendDebugLog } from "../utils/debug-log.js";
+import { appendDebugLog, shouldEmitProgressLogs } from "../utils/debug-log.js";
 import { FlowError, isFlowError, wrapFlowError } from "../common/errors.js";
 import * as git from "../utils/git.js";
 import { computeTraceState, readTraceContent } from "../utils/trace.js";
 import { buildStartPrompt } from "./prompts.js";
-import { parseToAST, parseMarkdownStructure, renderSectionContent, extractListItems, renderKeiyaku, } from "../utils/keiyaku-document.js";
+import { parseMarkdownStructure } from "../utils/keiyaku-document.js";
 import { resolveTermPreset } from "../config/term-presets.js";
 import { renderRoundSummary, TOOL_DEFAULT_POLICY } from "./round-summary.js";
 import { flattenMarkdownList } from "../utils/text-utils.js";
 import { assertCleanWorkingTree } from "./contract.js";
 import { runAndRecordRound } from "./round.js";
+import { renderKeiyaku } from "./keiyaku-document-builder.js";
+import { normalizeDraftMarkdownListItems, parseAndValidateKeiyakuDraft, } from "./keiyaku-draft.js";
 const BASE_CONSTRAINTS_FILE = path.join(".keiyaku", "base-constraints.md");
 const ACTIVE_KEIYAKU_PREVIEW_MAX_CHARS = 8000;
-const KNOWN_SECTIONS = new Set(["goal", "directive", "context", "constraints", "criteria", "acceptance criteria"]);
 const INTERNAL_START_DIRTY_ALLOWLIST = [];
-function normalizeSectionTitle(title) {
-    return title.trim().toLowerCase().replace(/\s+/g, " ");
-}
 function requireText(name, value) {
     const normalized = value.trim();
     if (!normalized) {
@@ -47,130 +45,6 @@ function normalizeOptionalStringList(name, value) {
         return requireText(`${name}[${index}]`, item);
     });
 }
-function normalizeMarkdownListItems(name, values) {
-    const normalized = [];
-    for (const [index, value] of values.entries()) {
-        const normalizedValue = requireText(`${name}[${index}]`, value);
-        const ast = parseToAST(normalizedValue, { allowSections: false });
-        const sectionNode = { type: "section", level: 2, title: "", children: ast.children };
-        const parsedItems = extractListItems(sectionNode);
-        if (parsedItems.length > 0) {
-            normalized.push(...parsedItems);
-            continue;
-        }
-        const grouped = splitHeadingGroups(sectionNode);
-        if (grouped.length > 0) {
-            normalized.push(...grouped);
-            continue;
-        }
-        const rendered = renderSectionContent(sectionNode).trim();
-        if (rendered.length > 0) {
-            normalized.push(rendered);
-            continue;
-        }
-        normalized.push(normalizedValue);
-    }
-    return normalized;
-}
-function splitHeadingGroups(sectionNode) {
-    const firstMeaningful = sectionNode.children.find((child) => {
-        if (child.type !== "text")
-            return true;
-        return child.value.trim().length > 0;
-    });
-    if (!firstMeaningful || firstMeaningful.type !== "heading" || firstMeaningful.level < 2) {
-        return [];
-    }
-    const groups = [];
-    let currentChildren = [];
-    const commit = () => {
-        if (currentChildren.length === 0)
-            return;
-        groups.push({
-            type: "section",
-            level: 2,
-            title: "",
-            children: currentChildren,
-        });
-        currentChildren = [];
-    };
-    for (const child of sectionNode.children) {
-        if (child.type === "heading" && child.level >= 2) {
-            commit();
-            currentChildren = [child];
-            continue;
-        }
-        currentChildren.push(child);
-    }
-    commit();
-    return groups
-        .map((group) => renderSectionContent(group).trim())
-        .filter((item) => item.length > 0);
-}
-function collectSectionItems(ast, sectionTitle) {
-    const normalizedSectionTitle = normalizeSectionTitle(sectionTitle);
-    const targetSection = ast.children.find((node) => {
-        if (node.type !== "section")
-            return false;
-        if (node.level !== 2)
-            return false;
-        return normalizeSectionTitle(node.title) === normalizedSectionTitle;
-    });
-    if (!targetSection || targetSection.type !== "section") {
-        return [];
-    }
-    const listItems = extractListItems(targetSection);
-    if (listItems.length > 0) {
-        return listItems;
-    }
-    const grouped = splitHeadingGroups(targetSection);
-    if (grouped.length > 0) {
-        return grouped;
-    }
-    const content = renderSectionContent(targetSection).trim();
-    return content ? [content] : [];
-}
-function parseAndValidateKeiyakuDraft(content) {
-    const ast = parseToAST(content);
-    const sections = new Map();
-    let title;
-    for (const node of ast.children) {
-        if (node.type !== "section")
-            continue;
-        if (node.level === 1 && !title) {
-            title = node.title.trim() || undefined;
-            continue;
-        }
-        if (node.level !== 2)
-            continue;
-        const normalizedSection = normalizeSectionTitle(node.title);
-        if (sections.has(normalizedSection)) {
-            throw new FlowError("INVALID_KEIYAKU_DRAFT", `invalid keiyaku draft: duplicate section header '${normalizedSection}'`);
-        }
-        sections.set(normalizedSection, renderSectionContent(node).trim());
-    }
-    const unknownSections = [...sections.keys()].filter((section) => !KNOWN_SECTIONS.has(section));
-    if (unknownSections.length > 0) {
-        throw new FlowError("INVALID_KEIYAKU_DRAFT", `invalid keiyaku draft: unknown section header(s): ${unknownSections.map((section) => `'${section}'`).join(", ")}`);
-    }
-    const goal = sections.get("goal")?.trim();
-    const directive = sections.get("directive")?.trim();
-    const context = sections.get("context")?.trim();
-    const constraints = sections.has("constraints") ? collectSectionItems(ast, "constraints") : undefined;
-    const criteria = sections.has("acceptance criteria")
-        ? collectSectionItems(ast, "acceptance criteria")
-        : sections.has("criteria")
-            ? collectSectionItems(ast, "criteria")
-            : undefined;
-    return {
-        title: title?.trim() || undefined,
-        goal: goal || undefined,
-        directive: directive || undefined,
-        context: context || undefined,
-        constraints: constraints && constraints.length > 0 ? constraints : undefined,
-        criteria: criteria && criteria.length > 0 ? criteria : undefined,
-    };
-}
 function truncateForMessage(text, maxChars) {
     if (text.length <= maxChars)
         return text;
@@ -235,24 +109,11 @@ async function fileExists(filePath) {
         throw error;
     }
 }
-function resolveFromFilePath(cwd, fromFile) {
-    return path.isAbsolute(fromFile) ? path.resolve(fromFile) : path.resolve(cwd, fromFile);
-}
-function isCanonicalDraftFromFile(cwd, fromFile) {
-    if (!fromFile)
-        return false;
-    return resolveFromFilePath(cwd, fromFile) === path.resolve(cwd, KEIYAKU_DRAFT_FILE);
-}
-async function assertStartPreFlight(cwd, fromFile) {
+async function assertStartPreFlight(cwd) {
     const keiyakuPath = path.join(cwd, KEIYAKU_FILE);
     if (await fileExists(keiyakuPath)) {
         throw new FlowError("KEIYAKU_FILE_EXISTS", `pre-flight failed: ${KEIYAKU_FILE} already exists in cwd`);
     }
-    const draftPath = path.join(cwd, KEIYAKU_DRAFT_FILE);
-    const draftExists = await fileExists(draftPath);
-    if (draftExists && !isCanonicalDraftFromFile(cwd, fromFile)) {
-        throw new FlowError("DRAFT_FILE_EXISTS", `pre-flight failed: ${KEIYAKU_DRAFT_FILE} exists but from_file does not target it`);
-    }
 }
 function normalizeTitleForBranch(title) {
     const normalized = title
@@ -296,8 +157,8 @@ async function resolveStartInput(cwd, input) {
             goal: provided.goal,
             directive: provided.directive,
             context: provided.context,
-            criteria: normalizeMarkdownListItems("criteria", provided.criteria),
-            constraints: normalizeMarkdownListItems("constraints", provided.constraints ?? []),
+            criteria: normalizeDraftMarkdownListItems("criteria", provided.criteria),
+            constraints: normalizeDraftMarkdownListItems("constraints", provided.constraints ?? []),
             fromFile: undefined,
             dirtyAllowlist,
         };
@@ -337,8 +198,8 @@ async function resolveStartInput(cwd, input) {
         goal,
         directive,
         context,
-        criteria: normalizeMarkdownListItems("criteria", criteria),
-        constraints: normalizeMarkdownListItems("constraints", constraints),
+        criteria: normalizeDraftMarkdownListItems("criteria", criteria),
+        constraints: normalizeDraftMarkdownListItems("constraints", constraints),
         fromFile,
         dirtyAllowlist,
     };
@@ -383,18 +244,22 @@ async function handleStartFailure(cwd, error, keiyakuContent, fromFile) {
         try {
             const draftPath = path.join(cwd, KEIYAKU_DRAFT_FILE);
             if (await fileExists(draftPath)) {
-                console.warn("[keiyaku] Race condition: Draft file exists. Content not saved.");
+                if (shouldEmitProgressLogs())
+                    console.warn("[keiyaku] Race condition: Draft file exists. Content not saved.");
             }
             else {
                 await fs.writeFile(draftPath, keiyakuContent, { flag: "wx" });
                 const startToolName = resolveTermPreset().tools.start.name;
-                console.error(`[keiyaku] Start failed. Draft saved to ${KEIYAKU_DRAFT_FILE}. Retry with: ${startToolName} --from_file ${KEIYAKU_DRAFT_FILE}`);
+                if (shouldEmitProgressLogs()) {
+                    console.error(`[keiyaku] Start failed. Draft saved to ${KEIYAKU_DRAFT_FILE}. Retry with: ${startToolName} --from_file ${KEIYAKU_DRAFT_FILE}`);
+                }
                 savedDraft = true;
             }
         }
         catch (draftSaveError) {
             const message = draftSaveError instanceof Error ? draftSaveError.message : String(draftSaveError);
-            console.error(`[keiyaku] Failed to save draft file: ${message}`);
+            if (shouldEmitProgressLogs())
+                console.error(`[keiyaku] Failed to save draft file: ${message}`);
         }
     }
     if (savedDraft) {
@@ -412,7 +277,6 @@ async function handleStartFailure(cwd, error, keiyakuContent, fromFile) {
 export async function startKeiyaku(input) {
     const { cwd, signal, name } = input;
     const resolved = await resolveStartInput(cwd, input);
-    const startedFromCanonicalDraft = isCanonicalDraftFromFile(cwd, resolved.fromFile);
     let keiyakuContent;
     let createdBranch = false;
     let keiyakuBranch;
@@ -431,11 +295,14 @@ export async function startKeiyaku(input) {
         const existingBranches = await git.listLocalKeiyakuBranches(cwd);
         if (existingBranches.length > 0) {
             const branchWarning = `[keiyaku] existing local keiyaku branches detected (non-blocking): ${existingBranches.join(", ")}`;
-            console.error(branchWarning);
+            if (shouldEmitProgressLogs())
+                console.error(branchWarning);
             appendDebugLog(branchWarning, { cwd, section: "script" });
         }
-        await assertStartPreFlight(cwd, resolved.fromFile);
-        const dirtyAllowlist = Array.from(new Set([...(resolved.fromFile ? [resolved.fromFile] : []), ...resolved.dirtyAllowlist]));
+        await assertStartPreFlight(cwd);
+        // `KEIYAKU.draft.md` is a recovery artifact and should not block starting a new session
+        // (unless the user explicitly chooses to start from it).
+        const dirtyAllowlist = Array.from(new Set([KEIYAKU_DRAFT_FILE, ...(resolved.fromFile ? [resolved.fromFile] : []), ...resolved.dirtyAllowlist]));
         await assertCleanWorkingTree(cwd, dirtyAllowlist.length > 0 ? dirtyAllowlist : undefined);
         baseBranch = await git.getCurrentBranch(cwd);
         const branchToken = normalizeTitleForBranch(resolved.title);
@@ -445,7 +312,8 @@ export async function startKeiyaku(input) {
         createdBranch = true;
         await git.setKeiyakuBase(cwd, keiyakuBranch, baseBranch);
         const switchedLog = `Switched to branch: ${keiyakuBranch} (base: ${baseBranch})`;
-        console.error(switchedLog);
+        if (shouldEmitProgressLogs())
+            console.error(switchedLog);
         appendDebugLog(switchedLog, { cwd, section: "script" });
         // Ensure we write the content we prepared.
         if (!keiyakuContent) {
@@ -468,16 +336,6 @@ export async function startKeiyaku(input) {
         });
         const summary = renderRoundSummary(roundSummary, TOOL_DEFAULT_POLICY);
         const diff = await git.getIncrementalDiff(cwd);
-        if (startedFromCanonicalDraft) {
-            try {
-                await fs.unlink(path.join(cwd, KEIYAKU_DRAFT_FILE));
-            }
-            catch (error) {
-                if (error?.code !== "ENOENT") {
-                    throw error;
-                }
-            }
-        }
         return {
             status: "success",
             round: 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "MCP server for running iterative keiyaku workflows with Codex subagents.",
   "license": "MIT",
   "type": "module",
@@ -24,8 +24,8 @@
     "prepublishOnly": "npm run build",
     "start": "node build/index.js",
     "test:unit": "node --import tsx --test --test-concurrency=1 tests/unit/unit.test.ts src/utils/keiyaku-document.test.ts",
-    "test:integration": "npx tsc && node --import tsx --test --test-concurrency=1 tests/integration/integration.test.ts",
-    "test": "node --import tsx --test --test-concurrency=1 tests/unit/unit.test.ts src/utils/keiyaku-document.test.ts && npx tsc && node --import tsx --test --test-concurrency=1 tests/integration/integration.test.ts"
+    "test:integration": "npx tsc && node --import tsx --test --test-concurrency=3 tests/integration/integration.test.ts",
+    "test": "node --import tsx --test --test-concurrency=1 tests/unit/unit.test.ts src/utils/keiyaku-document.test.ts && npx tsc && node --import tsx --test --test-concurrency=3 tests/integration/integration.test.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "*",