akm-cli 0.6.0-rc1 → 0.6.0-rc2

package/dist/{workflow-authoring.js → workflows/authoring.js}

@@ -1,10 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
-import { resolveAssetPathFromName } from "./asset-spec";
-import { isWithin, resolveStashDir } from "./common";
-import { UsageError } from "./errors";
-import { warn } from "./warn";
-import { parseWorkflowMarkdown, WorkflowValidationError } from "./workflow-markdown";
+import { resolveAssetPathFromName } from "../core/asset-spec";
+import { isWithin, resolveStashDir } from "../core/common";
+import { UsageError } from "../core/errors";
+import { warn } from "../core/warn";
+import { parseWorkflow } from "./parser";
 const DEFAULT_WORKFLOW_TEMPLATE = renderWorkflowTemplate({
     title: "Example Workflow",
     firstStepTitle: "First Step",
@@ -23,7 +23,10 @@ export function buildWorkflowTemplate(name) {
         firstStepTitle: `${title} Setup`,
         firstStepId: `${stepId}-setup`,
     });
-    parseWorkflowMarkdown(customized);
+    const result = parseWorkflow(customized, { path: `<template:${name}>` });
+    if (!result.ok) {
+        throw new UsageError(formatWorkflowErrors(`<template:${name}>`, result.errors));
+    }
     return customized;
 }
 export function createWorkflowAsset(input) {
@@ -41,14 +44,10 @@ export function createWorkflowAsset(input) {
     const content = input.from
         ? readWorkflowSource(input.from, stashDir)
         : (input.content ?? buildWorkflowTemplate(normalizedName));
-    try {
-        parseWorkflowMarkdown(content);
-    }
-    catch (error) {
-        if (error instanceof WorkflowValidationError) {
-            throw new UsageError(error.message);
-        }
-        throw error;
+    const sourcePath = input.from ?? `workflows/${normalizedName}.md`;
+    const result = parseWorkflow(content, { path: sourcePath });
+    if (!result.ok) {
+        throw new UsageError(formatWorkflowErrors(sourcePath, result.errors));
     }
     fs.mkdirSync(path.dirname(assetPath), { recursive: true });
     fs.writeFileSync(assetPath, content.endsWith("\n") ? content : `${content}\n`, "utf8");
@@ -110,6 +109,30 @@ function slugifyWorkflowStepId(name) {
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "") || "workflow");
 }
+export function formatWorkflowErrors(path, errors) {
+    const lines = errors.map((e) => `  ${path}:${e.line} — ${e.message}`);
+    const heading = errors.length === 1 ? "Workflow has 1 error:" : `Workflow has ${errors.length} errors:`;
+    return [heading, ...lines].join("\n");
+}
+/**
+ * Validate a workflow by ref (`workflow:<name>`) or filesystem path.
+ *
+ * Returns the parse result plus the source-relative path used. Throws
+ * `UsageError` only when the target cannot be located on disk; parse
+ * failures are returned as `{ ok: false, errors }` so callers can
+ * format them however they like.
+ */
+export function validateWorkflowSource(target) {
+    if (target.startsWith("workflow:")) {
+        throw new UsageError(`validateWorkflowSource expects a filesystem path; resolve refs to paths in the caller before invoking.`);
+    }
+    const resolved = path.resolve(target);
+    if (!fs.existsSync(resolved)) {
+        throw new UsageError(`Workflow file not found: "${target}".`);
+    }
+    const content = fs.readFileSync(resolved, "utf8");
+    return { path: target, parse: parseWorkflow(content, { path: target }) };
+}
 function renderWorkflowTemplate(input) {
     return `---
 description: Describe what this workflow accomplishes

package/dist/{workflow-cli.js → workflows/cli.js}

@@ -1,4 +1,4 @@
-import { UsageError } from "./errors";
+import { UsageError } from "../core/errors";
 export const WORKFLOW_STEP_STATES = [
     "completed",
     "blocked",
@@ -14,6 +14,7 @@ export const WORKFLOW_SUBCOMMANDS = new Set([
     "create",
     "template",
     "resume",
+    "validate",
 ]);
 export function parseWorkflowJsonObject(raw, flagName) {
     if (!raw)

package/dist/{workflow-db.js → workflows/db.js}

@@ -1,7 +1,7 @@
 import { Database } from "bun:sqlite";
 import fs from "node:fs";
 import path from "node:path";
-import { getWorkflowDbPath } from "./paths";
+import { getWorkflowDbPath } from "../core/paths";
 export function openWorkflowDatabase(dbPath = getWorkflowDbPath()) {
     const dir = path.dirname(dbPath);
     if (!fs.existsSync(dir)) {

package/dist/workflows/document-cache.js

@@ -0,0 +1,20 @@
+/**
+ * Side-channel cache that lets the workflow renderer hand a validated
+ * `WorkflowDocument` to the indexer without persisting it through the
+ * `entry_json` column or widening `StashEntry` with a workflow-shaped field.
+ *
+ * The renderer is called during metadata generation; the indexer writes the
+ * document to `workflow_documents` after `upsertEntry` returns the row id.
+ * A WeakMap keyed by the entry object preserves the parse work between the
+ * two phases without leaking memory if the entry is dropped.
+ */
+const cache = new WeakMap();
+export function cacheWorkflowDocument(entry, doc) {
+    cache.set(entry, doc);
+}
+export function takeWorkflowDocument(entry) {
+    const doc = cache.get(entry);
+    if (doc !== undefined)
+        cache.delete(entry);
+    return doc;
+}

package/dist/workflows/parser.js

@@ -0,0 +1,379 @@
+/**
+ * Workflow markdown → WorkflowDocument JSON.
+ *
+ * Composition over invention: frontmatter is parsed with the `yaml` package,
+ * heading discovery with `parseMarkdownToc`, and section bodies with
+ * `extractLineRange` — all already in the codebase. The parser walks the
+ * heading list once to assemble a `WorkflowDocument` with `SourceRef`
+ * line spans, accumulating `WorkflowError`s rather than throwing.
+ */
+import { parse as yamlParse } from "yaml";
+import { parseFrontmatterBlock } from "../core/frontmatter";
+import { parseMarkdownToc } from "../core/markdown";
+import { WORKFLOW_SCHEMA_VERSION, } from "./schema";
+import { runSemanticChecks } from "./validator";
+const WORKFLOW_TITLE_PREFIX = "Workflow:";
+const STEP_PREFIX = "Step:";
+const STEP_ID_LINE = /^Step ID:\s+(.+?)\s*$/;
+const BULLET_LINE = /^[-*]\s+(.+)$/;
+const SUBSECTION_INSTRUCTIONS = "Instructions";
+const SUBSECTION_COMPLETION_CRITERIA = "Completion Criteria";
+/**
+ * Cheap structural probe for the matcher. Returns true if the body has the
+ * unmistakable shape of a workflow file. Used in `src/indexer/matchers.ts` so
+ * the matcher and parser cannot drift.
+ */
+export function looksLikeWorkflow(body) {
+    return (/^#\s+Workflow:\s+/m.test(body) &&
+        /^##\s+Step:\s+/m.test(body) &&
+        /^Step ID:\s+/m.test(body) &&
+        /^###\s+Instructions\s*$/m.test(body));
+}
+export function parseWorkflow(markdown, source) {
+    const errors = [];
+    const path = source.path;
+    const lines = markdown.split(/\r?\n/);
+    const totalLines = lines.length;
+    const fmBlock = parseFrontmatterBlock(markdown);
+    const frontmatterEndLine = fmBlock ? Math.max(1, fmBlock.bodyStartLine - 1) : 1;
+    const fmData = readFrontmatter(fmBlock?.frontmatter, errors);
+    const description = readDescription(fmData);
+    const tags = readTags(fmData, errors, frontmatterEndLine);
+    const parameters = readParameters(fmData, errors, frontmatterEndLine, path);
+    const toc = parseMarkdownToc(markdown);
+    const { title, titleLine } = extractTitle(toc.headings, errors);
+    // Disallow stray level-1 and non-Step level-2 headings.
+    for (const h of toc.headings) {
+        if (h.level === 1 && !h.text.startsWith(WORKFLOW_TITLE_PREFIX)) {
+            errors.push({
+                line: h.line,
+                message: `Unexpected top-level heading "# ${h.text}" on line ${h.line}. A workflow file may only contain one "# Workflow: <title>" heading.`,
+            });
+        }
+        if (h.level === 2 && !h.text.startsWith(STEP_PREFIX)) {
+            errors.push({
+                line: h.line,
+                message: `Unexpected level-2 heading "## ${h.text}" on line ${h.line}. Only "## Step: <title>" sections are allowed.`,
+            });
+        }
+    }
+    const steps = extractSteps(toc.headings, lines, totalLines, path, errors);
+    if (steps.length === 0 && titleLine > 0) {
+        errors.push({
+            line: titleLine,
+            message: `Workflow has no "## Step: <title>" sections. Add at least one step.`,
+        });
+    }
+    const draft = {
+        schemaVersion: WORKFLOW_SCHEMA_VERSION,
+        title,
+        ...(description ? { description } : {}),
+        ...(tags ? { tags } : {}),
+        ...(parameters ? { parameters } : {}),
+        steps,
+        source: { path, lineCount: totalLines },
+    };
+    runSemanticChecks(draft, fmData, frontmatterEndLine, errors);
+    if (errors.length > 0) {
+        return { ok: false, errors: sortErrors(errors) };
+    }
+    return { ok: true, document: draft };
+}
+// ── Title ───────────────────────────────────────────────────────────────────
+function extractTitle(headings, errors) {
+    const titleHeadings = headings.filter((h) => h.level === 1 && h.text.startsWith(WORKFLOW_TITLE_PREFIX));
+    if (titleHeadings.length === 0) {
+        errors.push({
+            line: 1,
+            message: `Workflow markdown must start with a "# Workflow: <title>" heading. Add one at the top of the file.`,
+        });
+        return { title: "", titleLine: 0 };
+    }
+    if (titleHeadings.length > 1) {
+        for (const extra of titleHeadings.slice(1)) {
+            errors.push({
+                line: extra.line,
+                message: `Found a second "# Workflow:" heading on line ${extra.line}. A workflow file must contain exactly one.`,
+            });
+        }
+    }
+    const first = titleHeadings[0];
+    const title = first.text.slice(WORKFLOW_TITLE_PREFIX.length).trim();
+    if (!title) {
+        errors.push({
+            line: first.line,
+            message: `The "# Workflow:" heading on line ${first.line} is missing a title. Use "# Workflow: <title>".`,
+        });
+    }
+    return { title, titleLine: first.line };
+}
+// ── Steps ───────────────────────────────────────────────────────────────────
+function extractSteps(headings, lines, totalLines, path, errors) {
+    const steps = [];
+    let sequenceIndex = 0;
+    for (let i = 0; i < headings.length; i++) {
+        const h = headings[i];
+        if (h.level !== 2 || !h.text.startsWith(STEP_PREFIX))
+            continue;
+        const stepTitle = h.text.slice(STEP_PREFIX.length).trim();
+        if (!stepTitle) {
+            errors.push({
+                line: h.line,
+                message: `The "## Step:" heading on line ${h.line} is missing a title. Use "## Step: <title>".`,
+            });
+            continue;
+        }
+        const stepEnd = Math.min(findNextSiblingOrParentLine(headings, i, 2) - 1, totalLines);
+        const stepSource = { path, start: h.line, end: stepEnd };
+        const subsections = collectSubsections(headings, i, stepEnd);
+        const stepIdSearchEnd = subsections.length > 0 ? subsections[0].headingLine - 1 : stepEnd;
+        const stepId = scanStepId(lines, h.line + 1, stepIdSearchEnd, stepTitle, errors);
+        const { instructions, completionCriteria } = collectStepBody(subsections, lines, path, stepTitle, errors);
+        if (!stepId)
+            continue; // scanStepId already pushed the missing-id error
+        if (!instructions) {
+            errors.push({
+                line: h.line,
+                message: `Step "${stepTitle}" is missing the required "### Instructions" section. Add one under the step.`,
+            });
+            continue;
+        }
+        steps.push({
+            id: stepId,
+            title: stepTitle,
+            sequenceIndex: sequenceIndex++,
+            instructions,
+            ...(completionCriteria ? { completionCriteria } : {}),
+            source: stepSource,
+        });
+    }
+    return steps;
+}
+function collectSubsections(headings, stepIndex, stepEnd) {
+    const subs = [];
+    for (let j = stepIndex + 1; j < headings.length; j++) {
+        const sub = headings[j];
+        if (sub.level <= 2)
+            break;
+        if (sub.level !== 3)
+            continue;
+        const next = headings[j + 1];
+        const rawEnd = next ? next.line - 1 : stepEnd;
+        subs.push({
+            name: sub.text,
+            headingLine: sub.line,
+            bodyStart: sub.line + 1,
+            bodyEnd: Math.min(rawEnd, stepEnd),
+        });
+    }
+    return subs;
+}
+function collectStepBody(subsections, lines, path, stepTitle, errors) {
+    let instructions;
+    let completionCriteria;
+    for (const sub of subsections) {
+        if (sub.name === SUBSECTION_INSTRUCTIONS) {
+            if (instructions) {
+                errors.push({
+                    line: sub.headingLine,
+                    message: `Step "${stepTitle}" has more than one "### Instructions" section (line ${sub.headingLine}). Keep only one.`,
+                });
+                continue;
+            }
+            const text = sliceLines(lines, sub.bodyStart, sub.bodyEnd).trim();
+            if (!text) {
+                errors.push({
+                    line: sub.headingLine,
+                    message: `Step "${stepTitle}" has an empty "### Instructions" section. Add the instructions text below the heading.`,
+                });
+                continue;
+            }
+            instructions = {
+                text,
+                source: { path, start: sub.bodyStart, end: sub.bodyEnd },
+            };
+            continue;
+        }
+        if (sub.name === SUBSECTION_COMPLETION_CRITERIA) {
+            if (completionCriteria) {
+                errors.push({
+                    line: sub.headingLine,
+                    message: `Step "${stepTitle}" has more than one "### Completion Criteria" section (line ${sub.headingLine}). Keep only one.`,
+                });
+                continue;
+            }
+            const items = collectBullets(lines, sub.bodyStart, sub.bodyEnd, path);
+            if (items.length === 0) {
+                errors.push({
+                    line: sub.headingLine,
+                    message: `Step "${stepTitle}" has an empty "### Completion Criteria" section. Add at least one "- criterion" bullet.`,
+                });
+                continue;
+            }
+            completionCriteria = items;
+            continue;
+        }
+        errors.push({
+            line: sub.headingLine,
+            message: `Step "${stepTitle}" has an unknown "### ${sub.name}" section. Only "### Instructions" and "### Completion Criteria" are supported.`,
+        });
+    }
+    return {
+        ...(instructions ? { instructions } : {}),
+        ...(completionCriteria ? { completionCriteria } : {}),
+    };
+}
+function scanStepId(lines, startLineInclusive, endLineInclusive, stepTitle, errors) {
+    let foundId;
+    let foundLine = -1;
+    for (let lineNum = startLineInclusive; lineNum <= endLineInclusive; lineNum++) {
+        const trimmed = (lines[lineNum - 1] ?? "").trim();
+        if (!trimmed)
+            continue;
+        const match = trimmed.match(STEP_ID_LINE);
+        if (!match)
+            continue;
+        if (foundId !== undefined) {
+            errors.push({
+                line: lineNum,
+                message: `Step "${stepTitle}" has more than one "Step ID:" line (first on line ${foundLine}). Keep only one.`,
+            });
+            continue;
+        }
+        foundId = match[1].trim();
+        foundLine = lineNum;
+    }
+    if (!foundId) {
+        errors.push({
+            line: startLineInclusive,
+            message: `Step "${stepTitle}" is missing a "Step ID: <id>" line. Add one between the step heading and its subsections.`,
+        });
+    }
+    return foundId;
+}
+function collectBullets(lines, startLineInclusive, endLineInclusive, path) {
+    const items = [];
+    for (let lineNum = startLineInclusive; lineNum <= endLineInclusive; lineNum++) {
+        const trimmed = (lines[lineNum - 1] ?? "").trim();
+        if (!trimmed)
+            continue;
+        const match = trimmed.match(BULLET_LINE);
+        if (!match)
+            continue;
+        items.push({
+            text: match[1].trim(),
+            source: { path, start: lineNum, end: lineNum },
+        });
+    }
+    return items;
+}
+function findNextSiblingOrParentLine(headings, fromIndex, level) {
+    for (let i = fromIndex + 1; i < headings.length; i++) {
+        if (headings[i].level <= level)
+            return headings[i].line;
+    }
+    return Number.MAX_SAFE_INTEGER;
+}
+function sliceLines(lines, startLineInclusive, endLineInclusive) {
+    if (endLineInclusive < startLineInclusive)
+        return "";
+    const s = Math.max(1, startLineInclusive);
+    const e = Math.min(endLineInclusive, lines.length);
+    return lines.slice(s - 1, e).join("\n");
+}
+// ── Frontmatter ─────────────────────────────────────────────────────────────
+function readFrontmatter(frontmatter, errors) {
+    if (!frontmatter)
+        return {};
+    let parsed;
+    try {
+        parsed = yamlParse(frontmatter);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        errors.push({
+            line: 1,
+            message: `Workflow frontmatter is not valid YAML: ${msg}`,
+        });
+        return {};
+    }
+    if (parsed === null || parsed === undefined)
+        return {};
+    if (typeof parsed !== "object" || Array.isArray(parsed)) {
+        errors.push({
+            line: 1,
+            message: `Workflow frontmatter must be a YAML mapping (key: value pairs). Use "key: value" lines between the --- markers.`,
+        });
+        return {};
+    }
+    return parsed;
+}
+function readDescription(data) {
+    const v = data.description;
+    if (typeof v !== "string")
+        return undefined;
+    const trimmed = v.trim();
+    return trimmed || undefined;
+}
+function readTags(data, errors, fmEndLine) {
+    const v = data.tags;
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v === "string") {
+        const t = v.trim();
+        return t ? [t] : undefined;
+    }
+    if (!Array.isArray(v) || !v.every((tag) => typeof tag === "string" && tag.trim().length > 0)) {
+        errors.push({
+            line: fmEndLine,
+            message: `Workflow frontmatter "tags" must be a string or a list of non-empty strings.`,
+        });
+        return undefined;
+    }
+    return v.map((tag) => tag.trim());
+}
+function readParameters(data, errors, fmEndLine, path) {
+    const v = data.params;
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== "object" || Array.isArray(v)) {
+        errors.push({
+            line: fmEndLine,
+            message: `Workflow frontmatter "params" must be a mapping of parameter names to descriptions.`,
+        });
+        return undefined;
+    }
+    const entries = Object.entries(v);
+    if (entries.length === 0)
+        return undefined;
+    const out = [];
+    for (const [name, desc] of entries) {
+        const trimmedName = name.trim();
+        if (!trimmedName) {
+            errors.push({
+                line: fmEndLine,
+                message: `Workflow parameter names must be non-empty.`,
+            });
+            continue;
+        }
+        if (typeof desc !== "string" || !desc.trim()) {
+            errors.push({
+                line: fmEndLine,
+                message: `Workflow parameter "${trimmedName}" must have a non-empty string description in frontmatter "params".`,
+            });
+            continue;
+        }
+        out.push({
+            name: trimmedName,
+            description: desc.trim(),
+            // The frontmatter parser doesn't track per-key line numbers; anchor to the
+            // frontmatter block end so editors land somewhere sensible.
+            source: { path, start: 1, end: fmEndLine },
+        });
+    }
+    return out.length > 0 ? out : undefined;
+}
+// ── Error sorting ───────────────────────────────────────────────────────────
+function sortErrors(errors) {
+    return [...errors].sort((a, b) => a.line - b.line);
+}

package/dist/workflows/renderer.js

@@ -0,0 +1,78 @@
+/**
+ * Show + indexing renderer for workflow assets.
+ *
+ * Reads the markdown via `parseWorkflow` and projects the validated
+ * `WorkflowDocument` down to the public `ShowResponse` shape (which still
+ * uses the flat `WorkflowStepDefinition` type for backwards compatibility)
+ * and into search hints for the indexer.
+ */
+import { makeAssetRef } from "../core/asset-ref";
+import { UsageError } from "../core/errors";
+import { cacheWorkflowDocument } from "./document-cache";
+import { parseWorkflow } from "./parser";
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+export function buildWorkflowAction(ref) {
+    return `Resume the active run or start a new run with \`akm workflow next ${shellQuote(ref)}\`.`;
+}
+function deriveName(ctx) {
+    const metaName = ctx.matchResult.meta?.name;
+    if (typeof metaName === "string" && metaName)
+        return metaName;
+    const ext = ctx.relPath.lastIndexOf(".");
+    return ext > 0 ? ctx.relPath.slice(0, ext) : ctx.relPath;
+}
+function loadDocument(ctx) {
+    const result = parseWorkflow(ctx.content(), { path: ctx.relPath });
+    if (result.ok)
+        return result.document;
+    const summary = result.errors.map((e) => `${ctx.relPath}:${e.line} — ${e.message}`).join("\n");
+    throw new UsageError(`Workflow has errors:\n${summary}`);
+}
+export const workflowMdRenderer = {
+    name: "workflow-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const doc = loadDocument(ctx);
+        const ref = makeAssetRef("workflow", name, ctx.origin);
+        return {
+            type: "workflow",
+            name,
+            path: ctx.absPath,
+            action: buildWorkflowAction(ref),
+            description: doc.description,
+            workflowTitle: doc.title,
+            parameters: doc.parameters?.map((p) => p.name),
+            workflowParameters: doc.parameters?.map((p) => ({ name: p.name, description: p.description })),
+            steps: doc.steps.map((s) => ({
+                id: s.id,
+                title: s.title,
+                instructions: s.instructions.text,
+                ...(s.completionCriteria ? { completionCriteria: s.completionCriteria.map((c) => c.text) } : {}),
+                sequenceIndex: s.sequenceIndex,
+            })),
+        };
+    },
+    extractMetadata(entry, ctx) {
+        const doc = loadDocument(ctx);
+        const hints = new Set(entry.searchHints ?? []);
+        hints.add(doc.title);
+        for (const step of doc.steps) {
+            hints.add(step.title);
+            hints.add(step.id);
+            hints.add(step.instructions.text);
+            for (const criterion of step.completionCriteria ?? []) {
+                hints.add(criterion.text);
+            }
+        }
+        entry.searchHints = Array.from(hints).filter(Boolean);
+        if (doc.parameters?.length) {
+            entry.parameters = doc.parameters.map((p) => ({
+                name: p.name,
+                ...(p.description ? { description: p.description } : {}),
+            }));
+        }
+        cacheWorkflowDocument(entry, doc);
+    },
+};