akm-cli 0.4.1 → 0.5.0-rc1

package/dist/workflow-authoring.js

@@ -0,0 +1,131 @@
+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 { parseWorkflowMarkdown, WorkflowValidationError } from "./workflow-markdown";
+const DEFAULT_WORKFLOW_TEMPLATE = renderWorkflowTemplate({
+    title: "Example Workflow",
+    firstStepTitle: "First Step",
+    firstStepId: "first-step",
+});
+export function getWorkflowTemplate() {
+    return DEFAULT_WORKFLOW_TEMPLATE;
+}
+export function buildWorkflowTemplate(name) {
+    if (!name)
+        return DEFAULT_WORKFLOW_TEMPLATE;
+    const title = humanizeWorkflowName(name);
+    const stepId = slugifyWorkflowStepId(name);
+    const customized = renderWorkflowTemplate({
+        title,
+        firstStepTitle: `${title} Setup`,
+        firstStepId: `${stepId}-setup`,
+    });
+    parseWorkflowMarkdown(customized);
+    return customized;
+}
+export function createWorkflowAsset(input) {
+    const stashDir = resolveStashDir();
+    const typeRoot = path.join(stashDir, "workflows");
+    fs.mkdirSync(typeRoot, { recursive: true });
+    const normalizedName = normalizeWorkflowName(input.name);
+    const assetPath = resolveAssetPathFromName("workflow", typeRoot, normalizedName);
+    if (!isWithin(assetPath, typeRoot)) {
+        throw new UsageError(`Resolved workflow path escapes the stash: "${normalizedName}"`);
+    }
+    if (fs.existsSync(assetPath) && !input.force) {
+        throw new UsageError(`Workflow "${normalizedName}" already exists. Re-run with --force to overwrite it.`);
+    }
+    const content = input.from
+        ? readWorkflowSource(input.from)
+        : (input.content ?? buildWorkflowTemplate(normalizedName));
+    try {
+        parseWorkflowMarkdown(content);
+    }
+    catch (error) {
+        if (error instanceof WorkflowValidationError) {
+            throw new UsageError(error.message);
+        }
+        throw error;
+    }
+    fs.mkdirSync(path.dirname(assetPath), { recursive: true });
+    fs.writeFileSync(assetPath, content.endsWith("\n") ? content : `${content}\n`, "utf8");
+    return {
+        ref: `workflow:${normalizedName}`,
+        path: assetPath,
+        stashDir,
+    };
+}
+function readWorkflowSource(source) {
+    const resolved = path.resolve(source);
+    let stat;
+    try {
+        stat = fs.statSync(resolved);
+    }
+    catch {
+        throw new UsageError(`Workflow source not found: "${source}".`);
+    }
+    if (!stat.isFile()) {
+        throw new UsageError(`Workflow source must be a file: "${source}".`);
+    }
+    return fs.readFileSync(resolved, "utf8");
+}
+function normalizeWorkflowName(name) {
+    const normalized = name
+        .trim()
+        .replace(/\\/g, "/")
+        .replace(/^\/+|\/+$/g, "")
+        .replace(/\.md$/i, "");
+    if (!normalized) {
+        throw new UsageError("Workflow name cannot be empty.");
+    }
+    const segments = normalized.split("/");
+    if (segments.some((segment) => !segment || segment === "." || segment === "..")) {
+        throw new UsageError("Workflow name must be a relative path without '.' or '..' segments.");
+    }
+    return normalized;
+}
+function humanizeWorkflowName(name) {
+    return (name
+        .split("/")
+        .pop()
+        ?.replace(/[-_]+/g, " ")
+        .replace(/\b\w/g, (match) => match.toUpperCase())
+        .trim() || "Example Workflow");
+}
+function slugifyWorkflowStepId(name) {
+    return (name
+        .split("/")
+        .pop()
+        ?.toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "workflow");
+}
+function renderWorkflowTemplate(input) {
+    return `---
+description: Describe what this workflow accomplishes
+tags:
+  - example
+params:
+  example_param: Explain this parameter
+---
+
+# Workflow: ${input.title}
+
+## Step: ${input.firstStepTitle}
+Step ID: ${input.firstStepId}
+
+### Instructions
+Describe what to do in this step.
+
+### Completion Criteria
+- Confirm the first step is complete
+
+## Step: Second Step
+Step ID: second-step
+
+### Instructions
+Describe what happens next.
+`;
+}

package/dist/workflow-cli.js

@@ -0,0 +1,44 @@
+import { UsageError } from "./errors";
+export const WORKFLOW_STEP_STATES = [
+    "completed",
+    "blocked",
+    "failed",
+    "skipped",
+];
+export const WORKFLOW_SUBCOMMANDS = new Set([
+    "start",
+    "next",
+    "complete",
+    "status",
+    "list",
+    "create",
+    "template",
+    "resume",
+]);
+export function parseWorkflowJsonObject(raw, flagName) {
+    if (!raw)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new UsageError(`${flagName} must be valid JSON.`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new UsageError(`${flagName} must be a JSON object.`);
+    }
+    return parsed;
+}
+export function parseWorkflowStepState(value) {
+    if (!value)
+        return "completed";
+    if (WORKFLOW_STEP_STATES.includes(value)) {
+        return value;
+    }
+    throw new UsageError(`Invalid workflow step state "${value}". Expected one of: ${WORKFLOW_STEP_STATES.join(", ")}`);
+}
+export function hasWorkflowSubcommand(args) {
+    const command = Array.isArray(args._) ? args._[0] : undefined;
+    return typeof command === "string" && WORKFLOW_SUBCOMMANDS.has(command);
+}

package/dist/workflow-db.js

@@ -0,0 +1,55 @@
+import { Database } from "bun:sqlite";
+import fs from "node:fs";
+import path from "node:path";
+import { getWorkflowDbPath } from "./paths";
+export function openWorkflowDatabase(dbPath = getWorkflowDbPath()) {
+    const dir = path.dirname(dbPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const db = new Database(dbPath);
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA foreign_keys = ON");
+    ensureWorkflowSchema(db);
+    return db;
+}
+export function closeWorkflowDatabase(db) {
+    db.close();
+}
+function ensureWorkflowSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS workflow_runs (
+      id                TEXT PRIMARY KEY,
+      workflow_ref      TEXT NOT NULL,
+      workflow_entry_id INTEGER,
+      workflow_title    TEXT NOT NULL,
+      status            TEXT NOT NULL CHECK (status IN ('active', 'completed', 'blocked', 'failed')),
+      params_json       TEXT NOT NULL DEFAULT '{}',
+      current_step_id   TEXT,
+      created_at        TEXT NOT NULL,
+      updated_at        TEXT NOT NULL,
+      completed_at      TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_workflow_runs_ref ON workflow_runs(workflow_ref);
+    CREATE INDEX IF NOT EXISTS idx_workflow_runs_status ON workflow_runs(status);
+
+    CREATE TABLE IF NOT EXISTS workflow_run_steps (
+      run_id          TEXT NOT NULL,
+      step_id         TEXT NOT NULL,
+      step_title      TEXT NOT NULL,
+      instructions    TEXT NOT NULL,
+      completion_json TEXT,
+      sequence_index  INTEGER NOT NULL,
+      status          TEXT NOT NULL CHECK (status IN ('pending', 'completed', 'blocked', 'failed', 'skipped')),
+      notes           TEXT,
+      evidence_json   TEXT,
+      completed_at    TEXT,
+      PRIMARY KEY (run_id, step_id),
+      FOREIGN KEY (run_id) REFERENCES workflow_runs(id) ON DELETE CASCADE
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_workflow_run_steps_run_sequence
+      ON workflow_run_steps(run_id, sequence_index);
+  `);
+}

package/dist/workflow-markdown.js

@@ -0,0 +1,251 @@
+import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
+const ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params"]);
+const STEP_ID_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export class WorkflowValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WorkflowValidationError";
+    }
+}
+export function parseWorkflowMarkdown(markdown) {
+    const parsed = parseFrontmatter(markdown);
+    validateFrontmatter(parsed.data);
+    const title = extractWorkflowTitle(parsed.content);
+    const parameters = extractWorkflowParameters(parsed.data);
+    const tags = extractWorkflowTags(parsed.data, parsed.frontmatter);
+    const steps = extractWorkflowSteps(parsed.content);
+    return {
+        title,
+        description: toStringOrUndefined(parsed.data.description),
+        ...(tags ? { tags } : {}),
+        ...(parameters ? { parameters } : {}),
+        steps,
+    };
+}
+function validateFrontmatter(data) {
+    const unsupported = Object.keys(data).filter((key) => !ALLOWED_FRONTMATTER_KEYS.has(key));
+    if (unsupported.length > 0) {
+        throw new WorkflowValidationError(`Workflow frontmatter only supports description, tags, and params. Unsupported key(s): ${unsupported.join(", ")}`);
+    }
+}
+function extractWorkflowTitle(body) {
+    const matches = Array.from(body.matchAll(/^#\s+Workflow:\s+(.+?)\s*$/gm));
+    if (matches.length === 0) {
+        throw new WorkflowValidationError('Workflow markdown must contain a "# Workflow: <title>" heading.');
+    }
+    if (matches.length > 1) {
+        throw new WorkflowValidationError('Workflow markdown must contain exactly one "# Workflow: <title>" heading.');
+    }
+    const title = matches[0]?.[1]?.trim() ?? "";
+    if (!title) {
+        throw new WorkflowValidationError('Workflow markdown must contain a non-empty "# Workflow: <title>" heading.');
+    }
+    return title;
+}
+function extractWorkflowTags(data, frontmatter) {
+    const tags = data.tags;
+    if (typeof tags === "undefined")
+        return undefined;
+    if (typeof tags === "string") {
+        const trimmed = tags.trim();
+        return trimmed ? [trimmed] : undefined;
+    }
+    if (frontmatter &&
+        typeof tags === "object" &&
+        tags !== null &&
+        !Array.isArray(tags) &&
+        Object.keys(tags).length === 0) {
+        const blockTags = extractTagListFromFrontmatter(frontmatter);
+        if (blockTags)
+            return blockTags;
+    }
+    if (!Array.isArray(tags) || !tags.every((tag) => typeof tag === "string" && tag.trim().length > 0)) {
+        throw new WorkflowValidationError("Workflow frontmatter `tags` must be a string or an array of non-empty strings.");
+    }
+    return tags.map((tag) => tag.trim());
+}
+function extractWorkflowParameters(data) {
+    const params = data.params;
+    if (typeof params === "undefined")
+        return undefined;
+    if (typeof params !== "object" || params === null || Array.isArray(params)) {
+        throw new WorkflowValidationError("Workflow frontmatter `params` must be a mapping of parameter names to descriptions.");
+    }
+    const entries = Object.entries(params);
+    if (entries.length === 0)
+        return undefined;
+    return entries.map(([name, description]) => {
+        if (!name.trim()) {
+            throw new WorkflowValidationError("Workflow parameter names must be non-empty.");
+        }
+        if (typeof description !== "string" || !description.trim()) {
+            throw new WorkflowValidationError(`Workflow parameter "${name}" must have a non-empty string description in frontmatter params.`);
+        }
+        return { name: name.trim(), description: description.trim() };
+    });
+}
+function extractWorkflowSteps(body) {
+    const lines = normalizeLines(body);
+    const titleLineIndex = lines.findIndex((line) => /^#\s+Workflow:\s+/.test(line));
+    if (titleLineIndex === -1) {
+        throw new WorkflowValidationError('Workflow markdown must contain a "# Workflow: <title>" heading.');
+    }
+    const steps = [];
+    let index = titleLineIndex + 1;
+    while (index < lines.length) {
+        const line = lines[index] ?? "";
+        const trimmed = line.trim();
+        if (!trimmed) {
+            index++;
+            continue;
+        }
+        if (trimmed.startsWith("# ") && !/^#\s+Workflow:\s+/.test(trimmed)) {
+            throw new WorkflowValidationError(`Unexpected top-level heading after workflow title: "${trimmed}".`);
+        }
+        const stepHeader = trimmed.match(/^##\s+Step:\s+(.+?)\s*$/);
+        if (!stepHeader) {
+            throw new WorkflowValidationError(`Expected a "## Step: <title>" section after the workflow title, but found: "${trimmed}".`);
+        }
+        const stepTitle = stepHeader[1].trim();
+        const sequenceIndex = steps.length;
+        index++;
+        let stepId;
+        let instructions;
+        let completionCriteria;
+        while (index < lines.length) {
+            const current = lines[index] ?? "";
+            const currentTrimmed = current.trim();
+            if (/^##\s+Step:\s+/.test(currentTrimmed))
+                break;
+            if (/^#\s+/.test(currentTrimmed)) {
+                throw new WorkflowValidationError(`Unexpected heading "${currentTrimmed}" inside step "${stepTitle}". Only step sections and step subsections are allowed.`);
+            }
+            if (!currentTrimmed) {
+                index++;
+                continue;
+            }
+            const stepIdMatch = currentTrimmed.match(/^Step ID:\s+(.+?)\s*$/);
+            if (stepIdMatch) {
+                if (stepId) {
+                    throw new WorkflowValidationError(`Step "${stepTitle}" must contain exactly one "Step ID: <id>" line.`);
+                }
+                stepId = stepIdMatch[1].trim();
+                if (!STEP_ID_REGEX.test(stepId)) {
+                    throw new WorkflowValidationError(`Step "${stepTitle}" has invalid Step ID "${stepId}". Use letters, numbers, ".", "_" or "-".`);
+                }
+                index++;
+                continue;
+            }
+            const subsection = currentTrimmed.match(/^###\s+(.+?)\s*$/);
+            if (!subsection) {
+                throw new WorkflowValidationError(`Unexpected content in step "${stepTitle}". Add "Step ID: <id>" before subsections or move text under "### Instructions".`);
+            }
+            const subsectionName = subsection[1].trim();
+            index++;
+            const block = collectSectionBlock(lines, index);
+            index = block.nextIndex;
+            if (subsectionName === "Instructions") {
+                if (instructions) {
+                    throw new WorkflowValidationError(`Step "${stepTitle}" must contain exactly one "### Instructions" section.`);
+                }
+                instructions = block.text;
+                if (!instructions) {
+                    throw new WorkflowValidationError(`Step "${stepTitle}" must include instructions text.`);
+                }
+                continue;
+            }
+            if (subsectionName === "Completion Criteria") {
+                if (completionCriteria) {
+                    throw new WorkflowValidationError(`Step "${stepTitle}" must contain at most one "### Completion Criteria" section.`);
+                }
+                completionCriteria = block.items;
+                if (!completionCriteria || completionCriteria.length === 0) {
+                    throw new WorkflowValidationError(`Step "${stepTitle}" has an empty "### Completion Criteria" section.`);
+                }
+                continue;
+            }
+            throw new WorkflowValidationError(`Unknown subsection "### ${subsectionName}" in step "${stepTitle}". Only "### Instructions" and optional "### Completion Criteria" are supported.`);
+        }
+        if (!stepId) {
+            throw new WorkflowValidationError(`Step "${stepTitle}" must contain exactly one "Step ID: <id>" line.`);
+        }
+        if (!instructions) {
+            throw new WorkflowValidationError(`Step "${stepTitle}" must contain a "### Instructions" section.`);
+        }
+        steps.push({
+            id: stepId,
+            title: stepTitle,
+            instructions,
+            ...(completionCriteria ? { completionCriteria } : {}),
+            sequenceIndex,
+        });
+    }
+    if (steps.length === 0) {
+        throw new WorkflowValidationError('Workflow markdown must contain at least one "## Step: <title>" section.');
+    }
+    const seenStepIds = new Set();
+    for (const step of steps) {
+        if (seenStepIds.has(step.id)) {
+            throw new WorkflowValidationError(`Workflow step IDs must be unique. Duplicate Step ID: "${step.id}".`);
+        }
+        seenStepIds.add(step.id);
+    }
+    return steps;
+}
+function normalizeLines(body) {
+    return body.replace(/\r\n|\r/g, "\n").split("\n");
+}
+function collectSectionBlock(lines, startIndex) {
+    const collected = [];
+    let index = startIndex;
+    while (index < lines.length) {
+        const line = lines[index] ?? "";
+        const trimmed = line.trim();
+        if (/^##\s+Step:\s+/.test(trimmed) || /^###\s+/.test(trimmed) || /^#\s+/.test(trimmed))
+            break;
+        collected.push(line);
+        index++;
+    }
+    const text = collected.join("\n").trim();
+    const items = text
+        ? text
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => line.replace(/^[-*]\s*/, "").trim())
+            .filter(Boolean)
+        : undefined;
+    return { text, items, nextIndex: index };
+}
+function extractTagListFromFrontmatter(frontmatter) {
+    const lines = frontmatter.split("\n");
+    const tagIndex = lines.findIndex((line) => /^tags:\s*$/.test(line.trim()));
+    if (tagIndex === -1)
+        return undefined;
+    const tags = [];
+    for (let index = tagIndex + 1; index < lines.length; index++) {
+        const line = lines[index] ?? "";
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        if (!line.startsWith("  "))
+            break;
+        const match = trimmed.match(/^-\s+(.+?)\s*$/);
+        if (!match) {
+            throw new WorkflowValidationError("Workflow frontmatter `tags` must contain only dash-prefixed list items when declared as a block list.");
+        }
+        const tag = stripMatchingQuotes(match[1]?.trim() ?? "");
+        if (tag)
+            tags.push(tag);
+    }
+    return tags.length > 0 ? tags : undefined;
+}
+function stripMatchingQuotes(value) {
+    if (value.length >= 2) {
+        const quote = value[0];
+        if ((quote === '"' || quote === "'") && value[value.length - 1] === quote) {
+            return value.slice(1, -1).trim();
+        }
+    }
+    return value;
+}