akm-cli 0.6.1 → 0.7.0-rc1

package/dist/tests/workflow-cli.test.js

@@ -0,0 +1,271 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parseWorkflow } from "../src/workflows/parser";
+const CLI = path.join(__dirname, "..", "src", "cli.ts");
+const tempDirs = [];
+function makeTempDir(prefix) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    tempDirs.push(dir);
+    return dir;
+}
+function createWorkflowEnv() {
+    const stashDir = makeTempDir("akm-workflow-stash-");
+    const xdgCache = makeTempDir("akm-workflow-cache-");
+    const xdgConfig = makeTempDir("akm-workflow-config-");
+    return {
+        ...process.env,
+        AKM_STASH_DIR: stashDir,
+        XDG_CACHE_HOME: xdgCache,
+        XDG_CONFIG_HOME: xdgConfig,
+    };
+}
+function writeConfig(env, config) {
+    const configDir = path.join(String(env.XDG_CONFIG_HOME), "akm");
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(path.join(configDir, "config.json"), `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+/**
+ * Pull the JSON error envelope out of stderr. Stderr may contain
+ * preceding `warn(...)` lines (e.g. the "Importing workflow content
+ * from outside the stash" notice) before the (possibly multi-line) JSON
+ * envelope. We slice from the last `{` at column 0 to the end and parse
+ * that.
+ */
+function parseLastJsonLine(stderr) {
+    const lines = stderr.split("\n");
+    let startIdx = -1;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (lines[i].startsWith("{")) {
+            startIdx = i;
+            break;
+        }
+    }
+    if (startIdx === -1)
+        throw new Error(`stderr did not contain a JSON envelope: ${stderr}`);
+    const tail = lines.slice(startIdx).join("\n").trim();
+    return JSON.parse(tail);
+}
+function runCli(args, env) {
+    return spawnSync("bun", [CLI, ...args], {
+        encoding: "utf8",
+        timeout: 30_000,
+        env,
+    });
+}
+afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+const RELEASE_WORKFLOW = `---
+description: Ship a release
+tags:
+  - release
+params:
+  version: Version being released
+---
+
+# Workflow: Ship Release
+
+## Step: Validate Release Inputs
+Step ID: validate
+
+### Instructions
+Confirm release notes, tag, and version are present.
+
+### Completion Criteria
+- Release notes reviewed
+- Version matches tag
+
+## Step: Deploy Release
+Step ID: deploy
+
+### Instructions
+Run the deployment command and watch health checks.
+`;
+describe("workflow CLI", () => {
+    test("template prints a valid workflow document", () => {
+        const env = createWorkflowEnv();
+        const result = runCli(["workflow", "template"], env);
+        expect(result.status).toBe(0);
+        const parsed = parseWorkflow(result.stdout, { path: "<template>" });
+        if (!parsed.ok) {
+            throw new Error(`template did not parse: ${parsed.errors.map((e) => e.message).join("; ")}`);
+        }
+        expect(parsed.document.steps.length).toBeGreaterThan(0);
+    });
+    test("create writes a workflow and show returns structured step data", () => {
+        const env = createWorkflowEnv();
+        const result = runCli(["workflow", "create", "release-flow"], env);
+        expect(result.status).toBe(0);
+        const created = JSON.parse(result.stdout);
+        expect(created.ref).toBe("workflow:release-flow");
+        expect(fs.existsSync(created.path)).toBe(true);
+        const shown = runCli(["show", "workflow:release-flow"], env);
+        expect(shown.status).toBe(0);
+        const json = JSON.parse(shown.stdout);
+        expect(json.type).toBe("workflow");
+        expect(json.workflowTitle).toBe("Release Flow");
+        expect(json.steps[0]?.id).toBe("release-flow-setup");
+    });
+    test("create --from rejects invalid workflow documents", () => {
+        const env = createWorkflowEnv();
+        const sourceDir = makeTempDir("akm-workflow-source-");
+        const sourcePath = path.join(sourceDir, "invalid.md");
+        fs.writeFileSync(sourcePath, "# Workflow: Broken\n\n## Step: Missing Instructions\nStep ID: broken\n", "utf8");
+        const result = runCli(["workflow", "create", "broken", "--from", sourcePath], env);
+        expect(result.status).toBe(2);
+        const error = parseLastJsonLine(result.stderr);
+        expect(error.error).toContain('"### Instructions" section');
+    });
+    test("create --from rejects duplicate step ids", () => {
+        const env = createWorkflowEnv();
+        const sourceDir = makeTempDir("akm-workflow-source-");
+        const sourcePath = path.join(sourceDir, "duplicate.md");
+        fs.writeFileSync(sourcePath, RELEASE_WORKFLOW.replace("Step ID: deploy", "Step ID: validate"), "utf8");
+        const result = runCli(["workflow", "create", "duplicate", "--from", sourcePath], env);
+        expect(result.status).toBe(2);
+        const error = parseLastJsonLine(result.stderr);
+        expect(error.error).toContain('"validate"');
+        expect(error.error).toContain("already used");
+    });
+    test("start, next, complete, list, and status manage persisted workflow runs", () => {
+        const env = createWorkflowEnv();
+        const sourceDir = makeTempDir("akm-workflow-source-");
+        const sourcePath = path.join(sourceDir, "release.md");
+        fs.writeFileSync(sourcePath, RELEASE_WORKFLOW, "utf8");
+        expect(runCli(["workflow", "create", "release", "--from", sourcePath], env).status).toBe(0);
+        const started = runCli(["workflow", "start", "workflow:release", "--params", '{"version":"1.2.3"}'], env);
+        expect(started.status).toBe(0);
+        const startJson = JSON.parse(started.stdout);
+        expect(startJson.run.currentStepId).toBe("validate");
+        expect(startJson.run.params.version).toBe("1.2.3");
+        const next = runCli(["workflow", "next", startJson.run.id], env);
+        expect(next.status).toBe(0);
+        const nextJson = JSON.parse(next.stdout);
+        expect(nextJson.step.id).toBe("validate");
+        expect(nextJson.step.completionCriteria).toEqual(["Release notes reviewed", "Version matches tag"]);
+        const completed = runCli([
+            "workflow",
+            "complete",
+            startJson.run.id,
+            "--step",
+            "validate",
+            "--notes",
+            "Inputs verified",
+            "--evidence",
+            '{"checkedBy":"copilot"}',
+        ], env);
+        expect(completed.status).toBe(0);
+        const completedJson = JSON.parse(completed.stdout);
+        expect(completedJson.run.currentStepId).toBe("deploy");
+        expect(completedJson.workflow.steps).toHaveLength(2);
+        const status = runCli(["workflow", "status", startJson.run.id], env);
+        expect(status.status).toBe(0);
+        const statusJson = JSON.parse(status.stdout);
+        expect(statusJson.run.status).toBe("active");
+        expect(statusJson.run.currentStepId).toBe("deploy");
+        expect(statusJson.workflow.steps[0]).toMatchObject({
+            id: "validate",
+            status: "completed",
+            notes: "Inputs verified",
+            evidence: { checkedBy: "copilot" },
+        });
+        const listed = runCli(["workflow", "list", "--ref", "workflow:release", "--active"], env);
+        expect(listed.status).toBe(0);
+        const listJson = JSON.parse(listed.stdout);
+        expect(listJson.runs).toHaveLength(1);
+        expect(listJson.runs[0]?.workflowRef).toBe("workflow:release");
+        expect(runCli(["workflow", "complete", startJson.run.id, "--step", "deploy"], env).status).toBe(0);
+        const afterComplete = runCli(["workflow", "status", startJson.run.id], env);
+        const finalStatus = JSON.parse(afterComplete.stdout);
+        expect(finalStatus.run.status).toBe("completed");
+        expect(finalStatus.run.currentStepId ?? null).toBeNull();
+    });
+    test("next auto-starts a workflow and run state survives full index rebuilds", () => {
+        const env = createWorkflowEnv();
+        const sourceDir = makeTempDir("akm-workflow-source-");
+        const sourcePath = path.join(sourceDir, "release.md");
+        fs.writeFileSync(sourcePath, RELEASE_WORKFLOW, "utf8");
+        expect(runCli(["workflow", "create", "release", "--from", sourcePath], env).status).toBe(0);
+        const indexed = runCli(["index", "--full"], env);
+        expect(indexed.status).toBe(0);
+        const search = runCli(["search", "health checks", "--type", "workflow", "--detail", "full"], env);
+        expect(search.status).toBe(0);
+        const searchJson = JSON.parse(search.stdout);
+        expect(searchJson.hits[0]?.ref).toBe("workflow:release");
+        expect(searchJson.hits[0]?.action).toContain("akm workflow next 'workflow:release'");
+        const next = runCli(["workflow", "next", "workflow:release"], env);
+        expect(next.status).toBe(0);
+        const nextJson = JSON.parse(next.stdout);
+        expect(nextJson.run.status).toBe("active");
+        expect(nextJson.step.id).toBe("validate");
+        const rebuilt = runCli(["index", "--full"], env);
+        expect(rebuilt.status).toBe(0);
+        const status = runCli(["workflow", "status", nextJson.run.id], env);
+        expect(status.status).toBe(0);
+        const statusJson = JSON.parse(status.stdout);
+        expect(statusJson.run.id).toBe(nextJson.run.id);
+        expect(statusJson.run.status).toBe("active");
+        expect(statusJson.run.currentStepId).toBe("validate");
+    });
+    test("complete rejects non-current and finalized step updates", () => {
+        const env = createWorkflowEnv();
+        const sourceDir = makeTempDir("akm-workflow-source-");
+        const sourcePath = path.join(sourceDir, "release.md");
+        fs.writeFileSync(sourcePath, RELEASE_WORKFLOW, "utf8");
+        expect(runCli(["workflow", "create", "release", "--from", sourcePath], env).status).toBe(0);
+        const started = runCli(["workflow", "start", "workflow:release"], env);
+        expect(started.status).toBe(0);
+        const startJson = JSON.parse(started.stdout);
+        const wrongStep = runCli(["workflow", "complete", startJson.run.id, "--step", "deploy"], env);
+        expect(wrongStep.status).toBe(2);
+        expect(JSON.parse(wrongStep.stderr).error).toContain("is not the current step");
+        expect(runCli(["workflow", "complete", startJson.run.id, "--step", "validate"], env).status).toBe(0);
+        const repeated = runCli(["workflow", "complete", startJson.run.id, "--step", "validate"], env);
+        expect(repeated.status).toBe(2);
+        expect(JSON.parse(repeated.stderr).error).toContain("already completed");
+        expect(runCli(["workflow", "complete", startJson.run.id, "--step", "deploy", "--state", "blocked"], env).status).toBe(0);
+        const blockedRun = runCli(["workflow", "complete", startJson.run.id, "--step", "deploy"], env);
+        expect(blockedRun.status).toBe(2);
+        expect(JSON.parse(blockedRun.stderr).error).toContain("is blocked and cannot be updated");
+    });
+    test("next on a blocked run starts a new run for workflow refs", () => {
+        const env = createWorkflowEnv();
+        const sourceDir = makeTempDir("akm-workflow-source-");
+        const sourcePath = path.join(sourceDir, "release.md");
+        fs.writeFileSync(sourcePath, RELEASE_WORKFLOW, "utf8");
+        expect(runCli(["workflow", "create", "release", "--from", sourcePath], env).status).toBe(0);
+        const started = runCli(["workflow", "start", "workflow:release"], env);
+        expect(started.status).toBe(0);
+        const startJson = JSON.parse(started.stdout);
+        expect(runCli(["workflow", "complete", startJson.run.id, "--step", "validate"], env).status).toBe(0);
+        expect(runCli(["workflow", "complete", startJson.run.id, "--step", "deploy", "--state", "blocked"], env).status).toBe(0);
+        const next = runCli(["workflow", "next", "workflow:release"], env);
+        expect(next.status).toBe(0);
+        const nextJson = JSON.parse(next.stdout);
+        expect(nextJson.run.id).not.toBe(startJson.run.id);
+        expect(nextJson.run.status).toBe("active");
+        expect(nextJson.step.id).toBe("validate");
+    });
+    test("start links workflow_entry_id for workflows from an additional stash source", () => {
+        const env = createWorkflowEnv();
+        const extraStash = makeTempDir("akm-workflow-extra-stash-");
+        const workflowPath = path.join(extraStash, "workflows", "shared-release.md");
+        fs.mkdirSync(path.dirname(workflowPath), { recursive: true });
+        fs.writeFileSync(workflowPath, RELEASE_WORKFLOW, "utf8");
+        writeConfig(env, {
+            semanticSearchMode: "off",
+            sources: [{ type: "filesystem", path: extraStash, name: "extra" }],
+        });
+        expect(runCli(["index", "--full"], env).status).toBe(0);
+        const started = runCli(["workflow", "start", "extra//workflow:shared-release"], env);
+        expect(started.status).toBe(0);
+        const startJson = JSON.parse(started.stdout);
+        expect(startJson.run.workflowRef).toBe("extra//workflow:shared-release");
+        expect(typeof startJson.run.workflowEntryId).toBe("number");
+    });
+});

package/dist/tests/workflow-markdown.test.js

@@ -0,0 +1,171 @@
+import { describe, expect, test } from "bun:test";
+import { parseWorkflow } from "../src/workflows/parser";
+const VALID_WORKFLOW = `---
+description: Ship a release with validation checks
+tags:
+  - release
+  - deploy
+params:
+  version: Version being released
+---
+
+# Workflow: Ship Release
+
+## Step: Validate Release Inputs
+Step ID: validate
+
+### Instructions
+Confirm release notes, tag, and version are present.
+
+### Completion Criteria
+- Release notes reviewed
+- Version matches tag
+
+## Step: Deploy Release
+Step ID: deploy
+
+### Instructions
+Run the deployment command and watch health checks.
+`;
+function parse(markdown, path = "workflows/test.md") {
+    return parseWorkflow(markdown, { path });
+}
+function expectOk(result) {
+    if (!result.ok) {
+        throw new Error(`Expected ok parse, got errors: ${result.errors.map((e) => `${e.line}: ${e.message}`).join("; ")}`);
+    }
+}
+describe("parseWorkflow", () => {
+    test("parses a valid workflow document into structured steps", () => {
+        const result = parse(VALID_WORKFLOW);
+        expectOk(result);
+        const doc = result.document;
+        expect(doc.title).toBe("Ship Release");
+        expect(doc.description).toBe("Ship a release with validation checks");
+        expect(doc.tags).toEqual(["release", "deploy"]);
+        expect(doc.parameters?.map((p) => ({ name: p.name, description: p.description }))).toEqual([
+            { name: "version", description: "Version being released" },
+        ]);
+        expect(doc.steps).toHaveLength(2);
+        expect(doc.steps[0].id).toBe("validate");
+        expect(doc.steps[0].title).toBe("Validate Release Inputs");
+        expect(doc.steps[0].instructions.text).toBe("Confirm release notes, tag, and version are present.");
+        expect(doc.steps[0].completionCriteria?.map((c) => c.text)).toEqual([
+            "Release notes reviewed",
+            "Version matches tag",
+        ]);
+        expect(doc.steps[0].sequenceIndex).toBe(0);
+        expect(doc.steps[1].completionCriteria).toBeUndefined();
+    });
+    test("attaches accurate SourceRef line spans to steps and instructions", () => {
+        const result = parse(VALID_WORKFLOW);
+        expectOk(result);
+        const [first, second] = result.document.steps;
+        // VALID_WORKFLOW: frontmatter ends at line 8, "# Workflow: Ship Release" at line 10,
+        // first "## Step:" at line 12, second "## Step:" at line 22.
+        expect(first.source.path).toBe("workflows/test.md");
+        expect(first.source.start).toBe(12);
+        expect(first.instructions.source.start).toBeGreaterThanOrEqual(first.source.start);
+        expect(first.instructions.source.end).toBeLessThan(second.source.start);
+        expect(first.completionCriteria?.[0].source.start).toBeGreaterThan(first.instructions.source.end);
+        expect(second.source.start).toBe(22);
+    });
+    test("rejects missing workflow title", () => {
+        const result = parse(VALID_WORKFLOW.replace("# Workflow: Ship Release\n\n", ""));
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            return;
+        expect(result.errors[0].message).toContain('"# Workflow: <title>"');
+    });
+    test("rejects duplicate step ids", () => {
+        const result = parse(VALID_WORKFLOW.replace("Step ID: deploy", "Step ID: validate"));
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            return;
+        expect(result.errors.some((e) => e.message.includes('"validate"') && e.message.includes("already used"))).toBe(true);
+    });
+    test("rejects missing instructions sections", () => {
+        const invalid = VALID_WORKFLOW.replace("### Instructions\nRun the deployment command and watch health checks.\n", "");
+        const result = parse(invalid);
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            return;
+        expect(result.errors.some((e) => e.message.includes("Instructions"))).toBe(true);
+    });
+    test("rejects unknown step subsections", () => {
+        const invalid = VALID_WORKFLOW.replace("### Completion Criteria\n- Release notes reviewed\n- Version matches tag\n", "### Notes\nDo something else\n");
+        const result = parse(invalid);
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            return;
+        expect(result.errors.some((e) => e.message.includes("Notes"))).toBe(true);
+    });
+    test("rejects unsupported workflow frontmatter keys", () => {
+        const invalid = VALID_WORKFLOW.replace("---\n", "---\nmodel: gpt-5\n");
+        const result = parse(invalid);
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            return;
+        expect(result.errors.some((e) => e.message.includes("model"))).toBe(true);
+    });
+    test("collects every error in one pass instead of stopping at the first", () => {
+        const broken = `# Workflow: Multi
+
+## Step: One
+Step ID: A B
+### Instructions
+do A
+
+## Step: Two
+Step ID: A B
+### Instructions
+do B
+`;
+        const result = parse(broken);
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            return;
+        // Both invalid step IDs should be reported, not just the first.
+        const idErrors = result.errors.filter((e) => e.message.includes("Step ID"));
+        expect(idErrors.length).toBeGreaterThanOrEqual(2);
+    });
+});
+describe("parseWorkflow — intro paragraph (issue #158)", () => {
+    const WORKFLOW_WITH_INTRO = `# Workflow: Example
+
+This workflow is advisory and should only prepare commands.
+
+## Step: First Step
+Step ID: first-step
+
+### Instructions
+Do the thing.
+`;
+    test("parses cleanly when intro paragraph precedes first step", () => {
+        const result = parse(WORKFLOW_WITH_INTRO);
+        expectOk(result);
+        expect(result.document.title).toBe("Example");
+        expect(result.document.steps).toHaveLength(1);
+        expect(result.document.steps[0].id).toBe("first-step");
+        expect(result.document.steps[0].title).toBe("First Step");
+    });
+    test("existing valid workflows without intro paragraph parse identically", () => {
+        const result = parse(VALID_WORKFLOW);
+        expectOk(result);
+        expect(result.document.title).toBe("Ship Release");
+        expect(result.document.steps).toHaveLength(2);
+        expect(result.document.steps[0].id).toBe("validate");
+        expect(result.document.steps[1].id).toBe("deploy");
+    });
+    test("rejects workflow with intro paragraph but no steps", () => {
+        const noSteps = `# Workflow: No Steps
+
+This workflow has an intro but no steps at all.
+`;
+        const result = parse(noSteps);
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            return;
+        expect(result.errors.some((e) => e.message.includes("Step"))).toBe(true);
+    });
+});

package/dist/tests/workflow-path-escape.test.js

@@ -0,0 +1,132 @@
+/**
+ * Regression tests for issue #157:
+ * `akm workflow create <name>` failing with "Resolved workflow path escapes the
+ * stash" for valid bare names on systems with symlinks in the path hierarchy.
+ *
+ * Root cause: `safeRealpath` resolved existing directories through symlinks
+ * (via `fs.realpathSync`) but fell back to the raw `path.resolve` for
+ * non-existent paths.  When the directory tree contains a symlink (e.g.
+ * macOS /tmp → /private/tmp, or a HOME that is itself a symlink), the two
+ * resolved paths could disagree, causing `isWithin` to return false.
+ *
+ * Fix: walk up to the nearest existing ancestor, resolve that ancestor via
+ * `realpathSync`, then reconstruct the full path.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createWorkflowAsset } from "../src/workflows/authoring";
+const tempDirs = [];
+function makeTempDir(prefix) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    tempDirs.push(dir);
+    return dir;
+}
+afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+    delete process.env.AKM_STASH_DIR;
+    delete process.env.XDG_CONFIG_HOME;
+    delete process.env.XDG_CACHE_HOME;
+});
+// ── Happy path: clean stash ─────────────────────────────────────────────────
+describe("createWorkflowAsset — clean stash (issue #157)", () => {
+    test("bare name resolves correctly in a freshly created stash", () => {
+        const stashDir = makeTempDir("akm-issue157-stash-");
+        const xdgCache = makeTempDir("akm-issue157-cache-");
+        const xdgConfig = makeTempDir("akm-issue157-config-");
+        process.env.AKM_STASH_DIR = stashDir;
+        process.env.XDG_CACHE_HOME = xdgCache;
+        process.env.XDG_CONFIG_HOME = xdgConfig;
+        const result = createWorkflowAsset({ name: "agentic-test-workflow" });
+        expect(result.ref).toBe("workflow:agentic-test-workflow");
+        expect(fs.existsSync(result.path)).toBe(true);
+        expect(result.path).toBe(path.join(stashDir, "workflows", "agentic-test-workflow.md"));
+    });
+    test("bare name with hyphens resolves correctly", () => {
+        const stashDir = makeTempDir("akm-issue157-stash-");
+        process.env.AKM_STASH_DIR = stashDir;
+        const result = createWorkflowAsset({ name: "my-multi-step-workflow" });
+        expect(result.ref).toBe("workflow:my-multi-step-workflow");
+        expect(fs.existsSync(result.path)).toBe(true);
+    });
+    test("nested name (subdirectory) resolves correctly", () => {
+        const stashDir = makeTempDir("akm-issue157-stash-");
+        process.env.AKM_STASH_DIR = stashDir;
+        const result = createWorkflowAsset({ name: "team/release-flow" });
+        expect(result.ref).toBe("workflow:team/release-flow");
+        expect(fs.existsSync(result.path)).toBe(true);
+        expect(result.path).toContain(path.join("workflows", "team", "release-flow.md"));
+    });
+    test("resolves correctly when stash dir path contains a symlink", () => {
+        // Create a real directory and a symlink pointing to it, then use the
+        // symlink path as the stash dir.  This simulates environments where HOME
+        // or a parent directory is a symlink (e.g. macOS /tmp → /private/tmp).
+        const realDir = makeTempDir("akm-issue157-real-");
+        const symlinkDir = path.join(os.tmpdir(), `akm-issue157-link-${Date.now()}`);
+        tempDirs.push(symlinkDir); // cleaned up by afterEach (rm -rf is ok for dead links)
+        fs.symlinkSync(realDir, symlinkDir);
+        process.env.AKM_STASH_DIR = symlinkDir;
+        // Must not throw "Resolved workflow path escapes the stash"
+        const result = createWorkflowAsset({ name: "agentic-test-workflow" });
+        expect(result.ref).toBe("workflow:agentic-test-workflow");
+        expect(fs.existsSync(result.path)).toBe(true);
+    });
+    test("--from succeeds with valid workflow markdown", () => {
+        const stashDir = makeTempDir("akm-issue157-stash-");
+        const srcDir = makeTempDir("akm-issue157-src-");
+        process.env.AKM_STASH_DIR = stashDir;
+        const srcPath = path.join(srcDir, "release.md");
+        const content = `---
+description: A release workflow
+tags:
+  - release
+---
+
+# Workflow: Release
+
+## Step: Validate
+Step ID: validate
+
+### Instructions
+Check all inputs.
+
+### Completion Criteria
+- Inputs confirmed
+`;
+        fs.writeFileSync(srcPath, content, "utf8");
+        const result = createWorkflowAsset({ name: "release", from: srcPath });
+        expect(result.ref).toBe("workflow:release");
+        expect(fs.existsSync(result.path)).toBe(true);
+        expect(fs.readFileSync(result.path, "utf8")).toContain("# Workflow: Release");
+    });
+});
+// ── Security: path traversal must still be rejected ─────────────────────────
+describe("createWorkflowAsset — path escape rejection", () => {
+    test("../traversal is rejected", () => {
+        const stashDir = makeTempDir("akm-issue157-stash-");
+        process.env.AKM_STASH_DIR = stashDir;
+        expect(() => createWorkflowAsset({ name: "../outside" })).toThrow("must be a relative path without");
+    });
+    test("deep traversal is rejected", () => {
+        const stashDir = makeTempDir("akm-issue157-stash-");
+        process.env.AKM_STASH_DIR = stashDir;
+        expect(() => createWorkflowAsset({ name: "a/../../outside" })).toThrow("must be a relative path without");
+    });
+    test("absolute path is sanitized into a relative name inside the stash", () => {
+        // normalizeWorkflowName strips leading slashes, so "/etc/passwd" becomes
+        // "etc/passwd" — a relative name that resolves safely inside the stash.
+        // This is by design: the function converts absolute-looking user input
+        // into a relative name rather than treating it as a filesystem path.
+        const stashDir = makeTempDir("akm-issue157-stash-");
+        process.env.AKM_STASH_DIR = stashDir;
+        const result = createWorkflowAsset({ name: "/etc/passwd" });
+        // Leading slash is stripped → name becomes "etc/passwd"
+        expect(result.ref).toBe("workflow:etc/passwd");
+        // The resulting file is inside the stash workflows dir, not at /etc/passwd
+        expect(result.path.startsWith(stashDir)).toBe(true);
+        expect(result.path).toContain(path.join("workflows", "etc", "passwd.md"));
+    });
+});