akm-cli 0.4.1 → 0.5.0-rc2

package/dist/workflow-runs.js

@@ -0,0 +1,364 @@
+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";
+export async function startWorkflowRun(ref, params = {}) {
+    const asset = await loadWorkflowAsset(ref);
+    const workflowDb = openWorkflowDatabase();
+    try {
+        const now = new Date().toISOString();
+        const runId = randomUUID();
+        const currentStepId = asset.steps[0]?.id ?? null;
+        const workflowEntryId = resolveWorkflowEntryId(asset.sourcePath, asset.ref);
+        workflowDb.transaction(() => {
+            workflowDb
+                .prepare(`INSERT INTO workflow_runs (
+          id, workflow_ref, workflow_entry_id, workflow_title, status, params_json, current_step_id, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, 'active', ?, ?, ?, ?)`)
+                .run(runId, asset.ref, workflowEntryId, asset.title, JSON.stringify(params), currentStepId, now, now);
+            const insertStep = workflowDb.prepare(`INSERT INTO workflow_run_steps (
+          run_id, step_id, step_title, instructions, completion_json, sequence_index, status
+        ) VALUES (?, ?, ?, ?, ?, ?, 'pending')`);
+            for (const step of asset.steps) {
+                insertStep.run(runId, step.id, step.title, step.instructions, step.completionCriteria ? JSON.stringify(step.completionCriteria) : null, step.sequenceIndex ?? 0);
+            }
+        })();
+        return getWorkflowStatus(runId);
+    }
+    finally {
+        closeWorkflowDatabase(workflowDb);
+    }
+}
+export function getWorkflowStatus(runId) {
+    const workflowDb = openWorkflowDatabase();
+    try {
+        const run = readWorkflowRun(workflowDb, runId);
+        const steps = readWorkflowRunSteps(workflowDb, run.id);
+        return buildWorkflowRunDetail(run, steps);
+    }
+    finally {
+        closeWorkflowDatabase(workflowDb);
+    }
+}
+export function listWorkflowRuns(input) {
+    const workflowDb = openWorkflowDatabase();
+    try {
+        const filters = [];
+        const params = [];
+        if (input?.workflowRef) {
+            const parsed = parseAssetRef(input.workflowRef);
+            if (parsed.type !== "workflow") {
+                throw new UsageError(`Expected a workflow ref (workflow:<name>), got "${input.workflowRef}".`);
+            }
+            filters.push("workflow_ref = ?");
+            params.push(`${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`);
+        }
+        if (input?.activeOnly) {
+            filters.push("status IN ('active', 'blocked')");
+        }
+        const where = filters.length > 0 ? `WHERE ${filters.join(" AND ")}` : "";
+        const rows = workflowDb
+            .prepare(`SELECT * FROM workflow_runs ${where} ORDER BY updated_at DESC, created_at DESC`)
+            .all(...params);
+        return { runs: rows.map(toWorkflowRunSummary) };
+    }
+    finally {
+        closeWorkflowDatabase(workflowDb);
+    }
+}
+export async function getNextWorkflowStep(specifier, params) {
+    const workflowDb = openWorkflowDatabase();
+    try {
+        const { run, autoStarted } = await resolveRunSpecifier(workflowDb, specifier, params);
+        const steps = readWorkflowRunSteps(workflowDb, run.id);
+        const currentStep = resolveCurrentStep(run, steps);
+        const done = run.status === "completed" ? true : undefined;
+        return {
+            run: toWorkflowRunSummary(run),
+            workflow: {
+                ref: run.workflow_ref,
+                title: run.workflow_title,
+                steps: steps.map(toWorkflowRunStepState),
+            },
+            step: currentStep ? toWorkflowRunStepState(currentStep) : null,
+            ...(done ? { done } : {}),
+            ...(autoStarted ? { autoStarted } : {}),
+        };
+    }
+    finally {
+        closeWorkflowDatabase(workflowDb);
+    }
+}
+export function resumeWorkflowRun(runId) {
+    const workflowDb = openWorkflowDatabase();
+    try {
+        const run = readWorkflowRun(workflowDb, runId);
+        if (run.status === "completed") {
+            throw new UsageError(`Workflow run ${run.id} is already completed and cannot be resumed.`);
+        }
+        if (run.status === "active") {
+            const steps = readWorkflowRunSteps(workflowDb, run.id);
+            return buildWorkflowRunDetail(run, steps);
+        }
+        // blocked or failed → flip back to active
+        const now = new Date().toISOString();
+        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);
+    }
+    finally {
+        closeWorkflowDatabase(workflowDb);
+    }
+}
+export function completeWorkflowStep(input) {
+    const workflowDb = openWorkflowDatabase();
+    try {
+        let updatedRun;
+        let refreshedSteps = [];
+        workflowDb.transaction(() => {
+            const run = readWorkflowRun(workflowDb, input.runId);
+            if (run.status !== "active") {
+                throw new UsageError(`Workflow run ${run.id} is ${run.status} and cannot be updated.`);
+            }
+            const existing = workflowDb
+                .prepare("SELECT * FROM workflow_run_steps WHERE run_id = ? AND step_id = ?")
+                .get(run.id, input.stepId);
+            if (!existing) {
+                throw new NotFoundError(`Step "${input.stepId}" was not found in workflow run ${run.id}.`);
+            }
+            if (existing.status !== "pending") {
+                throw new UsageError(`Step "${input.stepId}" is already ${existing.status} in workflow run ${run.id}.`);
+            }
+            if (run.current_step_id !== existing.step_id) {
+                throw new UsageError(`Step "${input.stepId}" is not the current step for workflow run ${run.id}. Complete "${run.current_step_id}" first.`);
+            }
+            const completedAt = new Date().toISOString();
+            workflowDb
+                .prepare(`UPDATE workflow_run_steps
+           SET status = ?, notes = ?, evidence_json = ?, completed_at = ?
+           WHERE run_id = ? AND step_id = ?`)
+                .run(input.status, input.notes?.trim() || null, input.evidence ? JSON.stringify(input.evidence) : null, completedAt, run.id, input.stepId);
+            refreshedSteps = readWorkflowRunSteps(workflowDb, run.id);
+            const state = deriveRunState(refreshedSteps);
+            workflowDb
+                .prepare(`UPDATE workflow_runs
+           SET status = ?, current_step_id = ?, updated_at = ?, completed_at = ?
+           WHERE id = ?`)
+                .run(state.status, state.currentStepId, completedAt, state.completedAt, run.id);
+            updatedRun = {
+                ...run,
+                status: state.status,
+                current_step_id: state.currentStepId,
+                updated_at: completedAt,
+                completed_at: state.completedAt,
+            };
+        })();
+        return buildWorkflowRunDetail(updatedRun, refreshedSteps);
+    }
+    finally {
+        closeWorkflowDatabase(workflowDb);
+    }
+}
+async function resolveRunSpecifier(db, specifier, params) {
+    const explicitRun = db.prepare("SELECT * FROM workflow_runs WHERE id = ?").get(specifier);
+    if (explicitRun) {
+        if (params && Object.keys(params).length > 0) {
+            throw new UsageError(`--params can only be used when starting a new run from a workflow ref, not with an existing run id ("${specifier}")`);
+        }
+        return { run: explicitRun, autoStarted: false };
+    }
+    const parsed = parseAssetRef(specifier);
+    if (parsed.type !== "workflow") {
+        throw new UsageError(`Expected a workflow ref or workflow run id, got "${specifier}".`);
+    }
+    const ref = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
+    const active = db
+        .prepare("SELECT * FROM workflow_runs WHERE workflow_ref = ? AND status = 'active' ORDER BY updated_at DESC LIMIT 1")
+        .get(ref);
+    if (active) {
+        if (params && Object.keys(params).length > 0) {
+            throw new UsageError(`--params can only be set on a new run; ${ref} already has an active run`);
+        }
+        return { run: active, autoStarted: false };
+    }
+    const started = await startWorkflowRun(ref, params ?? {});
+    return { run: readWorkflowRun(db, started.run.id), autoStarted: true };
+}
+async function loadWorkflowAsset(ref) {
+    const parsed = parseAssetRef(ref);
+    if (parsed.type !== "workflow") {
+        throw new UsageError(`Expected a workflow ref (workflow:<name>), got "${ref}".`);
+    }
+    const config = loadConfig();
+    const allSources = resolveStashSources(undefined, config);
+    const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
+    let assetPath;
+    let sourcePath;
+    for (const source of searchSources) {
+        try {
+            assetPath = await resolveAssetPath(source.path, "workflow", parsed.name);
+            sourcePath = source.path;
+            break;
+        }
+        catch {
+            /* continue */
+        }
+    }
+    if (!assetPath) {
+        throw new NotFoundError(`Workflow not found for ref: workflow:${parsed.name}`);
+    }
+    const content = fs.readFileSync(assetPath, "utf8");
+    const workflow = parseWorkflowDocument(content);
+    return {
+        ref: `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`,
+        path: assetPath,
+        sourcePath: sourcePath ?? loadConfig().stashDir ?? assetPath,
+        title: workflow.title,
+        ...(workflow.parameters ? { parameters: workflow.parameters } : {}),
+        steps: workflow.steps,
+    };
+}
+function resolveWorkflowEntryId(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 id
+         FROM entries
+         WHERE entry_type = 'workflow'
+            AND entry_key = ?
+          LIMIT 1`)
+            .get(entryKey);
+        return row?.id ?? null;
+    }
+    finally {
+        closeDatabase(db);
+    }
+}
+function readWorkflowRun(db, runId) {
+    const run = db.prepare("SELECT * FROM workflow_runs WHERE id = ?").get(runId);
+    if (!run) {
+        throw new NotFoundError(`Workflow run not found: ${runId}`);
+    }
+    return run;
+}
+function readWorkflowRunSteps(db, runId) {
+    return db
+        .prepare("SELECT * FROM workflow_run_steps WHERE run_id = ? ORDER BY sequence_index ASC")
+        .all(runId);
+}
+function buildWorkflowRunDetail(run, steps) {
+    return {
+        run: toWorkflowRunSummary(run),
+        workflow: {
+            ref: run.workflow_ref,
+            title: run.workflow_title,
+            steps: steps.map(toWorkflowRunStepState),
+        },
+    };
+}
+function toWorkflowRunSummary(run) {
+    return {
+        id: run.id,
+        workflowRef: run.workflow_ref,
+        workflowEntryId: run.workflow_entry_id,
+        workflowTitle: run.workflow_title,
+        status: run.status,
+        currentStepId: run.current_step_id,
+        createdAt: run.created_at,
+        updatedAt: run.updated_at,
+        completedAt: run.completed_at,
+        params: parseJsonObject(run.params_json),
+    };
+}
+function toWorkflowRunStepState(step) {
+    return {
+        id: step.step_id,
+        title: step.step_title,
+        instructions: step.instructions,
+        completionCriteria: parseJsonArray(step.completion_json),
+        sequenceIndex: step.sequence_index,
+        status: step.status,
+        notes: step.notes ?? undefined,
+        evidence: parseJsonObject(step.evidence_json),
+        completedAt: step.completed_at,
+    };
+}
+function resolveCurrentStep(run, steps) {
+    if (run.current_step_id) {
+        return steps.find((step) => step.step_id === run.current_step_id);
+    }
+    return steps.find((step) => step.status === "pending");
+}
+function deriveRunState(steps) {
+    const unresolved = steps.find((step) => step.status === "failed" || step.status === "blocked");
+    if (unresolved) {
+        return {
+            status: unresolved.status === "failed" ? "failed" : "blocked",
+            currentStepId: unresolved.step_id,
+            completedAt: null,
+        };
+    }
+    const pending = steps.find((step) => step.status === "pending");
+    if (pending) {
+        return { status: "active", currentStepId: pending.step_id, completedAt: null };
+    }
+    const completedAt = steps
+        .map((step) => step.completed_at)
+        .filter((value) => typeof value === "string")
+        .sort()
+        .at(-1);
+    return { status: "completed", currentStepId: null, completedAt: completedAt ?? null };
+}
+function parseJsonObject(value) {
+    if (!value)
+        return undefined;
+    try {
+        const parsed = JSON.parse(value);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        /* ignore corrupt data */
+    }
+    return undefined;
+}
+function parseJsonArray(value) {
+    if (!value)
+        return undefined;
+    try {
+        const parsed = JSON.parse(value);
+        if (Array.isArray(parsed)) {
+            return parsed.filter((item) => typeof item === "string");
+        }
+    }
+    catch {
+        /* ignore corrupt data */
+    }
+    return undefined;
+}
+function parseWorkflowDocument(content) {
+    try {
+        return parseWorkflowMarkdown(content);
+    }
+    catch (error) {
+        if (error instanceof WorkflowValidationError) {
+            throw new UsageError(error.message);
+        }
+        throw error;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.4.1",
+  "version": "0.5.0-rc2",
   "type": "module",
   "description": "akm (Agent Kit Manager) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [
@@ -34,6 +34,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "bin": {
@@ -70,6 +71,7 @@
   "dependencies": {
     "@clack/prompts": "^1.1.0",
     "citty": "^0.2.1",
+    "dotenv": "^17.4.2",
     "yaml": "^2.8.2"
   }
 }