akm-cli 0.5.0 → 0.6.0-rc2

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);
+    },
+};

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

@@ -1,15 +1,16 @@
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
-import { loadConfig } from "./config";
-import { closeDatabase, openDatabase } from "./db";
-import { NotFoundError, UsageError } from "./errors";
-import { resolveSourcesForOrigin } from "./origin-resolve";
-import { getDbPath } from "./paths";
-import { resolveStashSources } from "./search-source";
-import { parseAssetRef } from "./stash-ref";
-import { resolveAssetPath } from "./stash-resolve";
-import { closeWorkflowDatabase, openWorkflowDatabase } from "./workflow-db";
-import { parseWorkflowMarkdown, WorkflowValidationError } from "./workflow-markdown";
+import { parseAssetRef } from "../core/asset-ref";
+import { loadConfig } from "../core/config";
+import { NotFoundError, UsageError } from "../core/errors";
+import { getDbPath } from "../core/paths";
+import { closeDatabase, openDatabase } from "../indexer/db";
+import { resolveSourceEntries } from "../indexer/search-source";
+import { resolveSourcesForOrigin } from "../registry/origin-resolve";
+import { resolveAssetPath } from "../sources/resolve";
+import { formatWorkflowErrors } from "./authoring";
+import { closeWorkflowDatabase, openWorkflowDatabase } from "./db";
+import { parseWorkflow } from "./parser";
 export async function startWorkflowRun(ref, params = {}) {
     const asset = await loadWorkflowAsset(ref);
     const workflowDb = openWorkflowDatabase();
@@ -108,9 +109,19 @@ export function resumeWorkflowRun(runId) {
             const steps = readWorkflowRunSteps(workflowDb, run.id);
             return buildWorkflowRunDetail(run, steps);
         }
-        // blocked or failed → flip back to active
+        // blocked or failed → flip back to active and re-open the current step so
+        // it can be reclassified (completed, failed, skipped) after resuming.
         const now = new Date().toISOString();
-        workflowDb.prepare("UPDATE workflow_runs SET status = 'active', updated_at = ? WHERE id = ?").run(now, run.id);
+        workflowDb.transaction(() => {
+            if (run.current_step_id) {
+                workflowDb
+                    .prepare(`UPDATE workflow_run_steps
+             SET status = 'pending', notes = NULL, evidence_json = NULL, completed_at = NULL
+             WHERE run_id = ? AND step_id = ? AND status IN ('blocked', 'failed')`)
+                    .run(run.id, run.current_step_id);
+            }
+            workflowDb.prepare("UPDATE workflow_runs SET status = 'active', updated_at = ? WHERE id = ?").run(now, run.id);
+        })();
         const updated = { ...run, status: "active", updated_at: now };
         const steps = readWorkflowRunSteps(workflowDb, run.id);
         return buildWorkflowRunDetail(updated, steps);
@@ -199,7 +210,7 @@ async function loadWorkflowAsset(ref) {
         throw new UsageError(`Expected a workflow ref (workflow:<name>), got "${ref}".`);
     }
     const config = loadConfig();
-    const allSources = resolveStashSources(undefined, config);
+    const allSources = resolveSourceEntries(undefined, config);
     const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
     let assetPath;
     let sourcePath;
@@ -216,15 +227,69 @@ async function loadWorkflowAsset(ref) {
     if (!assetPath) {
         throw new NotFoundError(`Workflow not found for ref: workflow:${parsed.name}`);
     }
+    const resolvedSourcePath = sourcePath ?? loadConfig().stashDir ?? assetPath;
+    const fullRef = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
+    const cached = readWorkflowDocumentFromIndex(resolvedSourcePath, fullRef);
+    const document = cached ?? loadWorkflowDocumentFromDisk(assetPath);
+    return projectAsset(document, fullRef, assetPath, resolvedSourcePath);
+}
+function loadWorkflowDocumentFromDisk(assetPath) {
     const content = fs.readFileSync(assetPath, "utf8");
-    const workflow = parseWorkflowDocument(content);
+    const result = parseWorkflow(content, { path: assetPath });
+    if (!result.ok) {
+        throw new UsageError(formatWorkflowErrors(assetPath, result.errors));
+    }
+    return result.document;
+}
+function readWorkflowDocumentFromIndex(sourcePath, ref) {
+    const dbPath = getDbPath();
+    if (!fs.existsSync(dbPath))
+        return null;
+    const db = openDatabase(dbPath);
+    try {
+        const parsed = parseAssetRef(ref);
+        const entryKey = `${sourcePath}:${parsed.type}:${parsed.name}`;
+        const row = db
+            .prepare(`SELECT wd.document_json AS document_json
+           FROM workflow_documents wd
+           JOIN entries e ON e.id = wd.entry_id
+          WHERE e.entry_type = 'workflow' AND e.entry_key = ?
+          LIMIT 1`)
+            .get(entryKey);
+        if (!row)
+            return null;
+        try {
+            return JSON.parse(row.document_json);
+        }
+        catch {
+            return null;
+        }
+    }
+    finally {
+        closeDatabase(db);
+    }
+}
+function projectAsset(doc, ref, assetPath, sourcePath) {
     return {
-        ref: `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`,
+        ref,
         path: assetPath,
-        sourcePath: sourcePath ?? loadConfig().stashDir ?? assetPath,
-        title: workflow.title,
-        ...(workflow.parameters ? { parameters: workflow.parameters } : {}),
-        steps: workflow.steps,
+        sourcePath,
+        title: doc.title,
+        ...(doc.parameters
+            ? {
+                parameters: doc.parameters.map((p) => ({
+                    name: p.name,
+                    ...(p.description ? { 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,
+        })),
     };
 }
 function resolveWorkflowEntryId(sourcePath, ref) {
@@ -351,14 +416,3 @@ function parseJsonArray(value) {
     }
     return undefined;
 }
-function parseWorkflowDocument(content) {
-    try {
-        return parseWorkflowMarkdown(content);
-    }
-    catch (error) {
-        if (error instanceof WorkflowValidationError) {
-            throw new UsageError(error.message);
-        }
-        throw error;
-    }
-}

package/dist/workflows/schema.js

@@ -0,0 +1,11 @@
+/**
+ * Validated JSON shape for a workflow asset.
+ *
+ * `parseWorkflow` (parser.ts) converts a workflow markdown file into a
+ * `WorkflowDocument` plus a list of `WorkflowError`s. The document is the
+ * single source of truth consumed by the renderer, the indexer (cached
+ * into `workflow_documents` in `index.db`), and the run engine. Source
+ * markdown is referenced by `SourceRef` line spans so editors and agents
+ * can rewrite content in place without a full re-parse.
+ */
+export const WORKFLOW_SCHEMA_VERSION = 1;

package/dist/workflows/validator.js

@@ -0,0 +1,48 @@
+/**
+ * Cross-cutting semantic checks over an assembled WorkflowDocument draft.
+ *
+ * The parser handles per-line shape checks; this module runs rules that need
+ * the whole document or the raw frontmatter at once: duplicate step IDs,
+ * step-id format, and the frontmatter key whitelist.
+ */
+const STEP_ID_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params"]);
+export function runSemanticChecks(draft, frontmatterData, frontmatterEndLine, errors) {
+    checkFrontmatterKeys(frontmatterData, frontmatterEndLine, errors);
+    checkStepIdFormat(draft, errors);
+    checkDuplicateStepIds(draft, errors);
+}
+function checkFrontmatterKeys(data, fmEndLine, errors) {
+    for (const key of Object.keys(data)) {
+        if (ALLOWED_FRONTMATTER_KEYS.has(key))
+            continue;
+        errors.push({
+            line: fmEndLine,
+            message: `Workflow frontmatter "${key}" is not supported. Use only: description, tags, params.`,
+        });
+    }
+}
+function checkStepIdFormat(draft, errors) {
+    for (const step of draft.steps) {
+        if (STEP_ID_REGEX.test(step.id))
+            continue;
+        errors.push({
+            line: step.source.start,
+            message: `Step ID "${step.id}" is invalid. Use letters, numbers, ".", "_" or "-" (e.g. "deploy-job").`,
+        });
+    }
+}
+function checkDuplicateStepIds(draft, errors) {
+    const firstSeenLine = new Map();
+    for (const step of draft.steps) {
+        const previous = firstSeenLine.get(step.id);
+        if (previous !== undefined) {
+            errors.push({
+                line: step.source.start,
+                message: `Step ID "${step.id}" is already used on line ${previous}. Step IDs must be unique within a workflow.`,
+            });
+            continue;
+        }
+        firstSeenLine.set(step.id, step.source.start);
+    }
+}