akm-cli 0.6.1 → 0.7.0-rc1

package/dist/tests/fixtures/stashes/load.js

@@ -0,0 +1,166 @@
+/**
+ * Shared fixture-stash loader for tests/*.test.ts and bench tasks.
+ *
+ * Each fixture lives at `tests/fixtures/stashes/<name>/` with a `MANIFEST.json`
+ * and the standard akm stash layout. `loadFixtureStash(name)` copies the
+ * fixture into a fresh tmp dir, sets `AKM_STASH_DIR`, runs `akm index`, and
+ * returns the materialised path plus a cleanup function.
+ *
+ * See docs/technical/benchmark.md §5.5 for the contract.
+ */
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const FIXTURES_ROOT = __dirname;
+const REPO_ROOT = path.resolve(FIXTURES_ROOT, "..", "..", "..");
+const CLI_ENTRY = path.join(REPO_ROOT, "src", "cli.ts");
+/**
+ * List the fixture names available under `tests/fixtures/stashes/`.
+ *
+ * A directory is considered a fixture iff it contains a `MANIFEST.json`.
+ * Returned names are sorted alphabetically.
+ */
+export function listFixtures() {
+    const entries = fs.readdirSync(FIXTURES_ROOT, { withFileTypes: true });
+    const names = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const manifest = path.join(FIXTURES_ROOT, entry.name, "MANIFEST.json");
+        if (fs.existsSync(manifest))
+            names.push(entry.name);
+    }
+    names.sort();
+    return names;
+}
+/**
+ * Synchronous, deterministic SHA-256 hex of every file under the named
+ * fixture. Hash input is `<relative-path>\0<file-bytes>\0` for each file in
+ * sorted-relative-path order. Used by `bench compare` to refuse cross-fixture
+ * diffs.
+ *
+ * Also exported as `computeFixtureContentHash` for callers that prefer the
+ * `compute*` naming convention used by sibling helpers in `tests/bench/`
+ * (see `computeTaskCorpusHash` in corpus.ts). The two names point at the
+ * SAME implementation — there is exactly one fixture-content hash function
+ * in this codebase, and `LoadedFixtureStash.contentHash` reuses it.
+ */
+export function fixtureContentHash(name) {
+    const root = fixtureSourceDir(name);
+    const files = collectFilesSorted(root);
+    const hash = createHash("sha256");
+    for (const rel of files) {
+        hash.update(rel);
+        hash.update("\0");
+        hash.update(fs.readFileSync(path.join(root, rel)));
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+/**
+ * Alias for `fixtureContentHash` matching the `compute*` naming used by
+ * sibling helpers in `tests/bench/`. Reuses the SAME implementation —
+ * defining a separate hash function for the same content would risk drift
+ * between the report-stamping path and `LoadedFixtureStash.contentHash`.
+ */
+export const computeFixtureContentHash = fixtureContentHash;
+/**
+ * Copy the named fixture into a fresh tmp dir, set `AKM_STASH_DIR`, and run
+ * `akm index` against it. Returns the tmp path plus a cleanup function that
+ * restores the prior env value and recursively removes the tmp dir.
+ *
+ * Pass `{ skipIndex: true }` if the caller will build its own index and the
+ * helper's `akm index` spawn would be wasted work.
+ */
+export function loadFixtureStash(name, options = {}) {
+    const sourceDir = fixtureSourceDir(name);
+    const contentHash = fixtureContentHash(name);
+    const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), `akm-fixture-${name}-`));
+    const stashDir = path.join(tmpRoot, "stash");
+    const cacheHome = path.join(tmpRoot, "cache");
+    const configHome = path.join(tmpRoot, "config");
+    copyDirRecursive(sourceDir, stashDir);
+    fs.mkdirSync(cacheHome, { recursive: true });
+    fs.mkdirSync(configHome, { recursive: true });
+    const priorAkmStashDir = process.env.AKM_STASH_DIR;
+    process.env.AKM_STASH_DIR = stashDir;
+    if (!options.skipIndex) {
+        // Use isolated XDG dirs for the index invocation so the helper never
+        // touches the operator's real ~/.cache/akm or pulls in their configured
+        // registries / sources. The shipped fixture is the only thing indexed.
+        const result = Bun.spawnSync({
+            cmd: ["bun", "run", CLI_ENTRY, "index"],
+            cwd: stashDir,
+            env: {
+                ...process.env,
+                AKM_STASH_DIR: stashDir,
+                XDG_CACHE_HOME: cacheHome,
+                XDG_CONFIG_HOME: configHome,
+            },
+            stdout: "pipe",
+            stderr: "pipe",
+        });
+        if (result.exitCode !== 0) {
+            // Restore env and clean up before throwing so the caller is not left
+            // with a leaked tmp dir or mutated process state.
+            if (priorAkmStashDir === undefined)
+                delete process.env.AKM_STASH_DIR;
+            else
+                process.env.AKM_STASH_DIR = priorAkmStashDir;
+            fs.rmSync(tmpRoot, { recursive: true, force: true });
+            const stderr = result.stderr ? new TextDecoder().decode(result.stderr) : "";
+            throw new Error(`akm index failed for fixture "${name}" (exit ${result.exitCode}): ${stderr}`);
+        }
+    }
+    const cleanup = () => {
+        if (priorAkmStashDir === undefined)
+            delete process.env.AKM_STASH_DIR;
+        else
+            process.env.AKM_STASH_DIR = priorAkmStashDir;
+        fs.rmSync(tmpRoot, { recursive: true, force: true });
+    };
+    return { stashDir, cleanup, contentHash };
+}
+// ── Internals ───────────────────────────────────────────────────────────────
+function fixtureSourceDir(name) {
+    if (!isSafeName(name)) {
+        throw new Error(`invalid fixture name: ${JSON.stringify(name)}`);
+    }
+    const dir = path.join(FIXTURES_ROOT, name);
+    if (!fs.existsSync(path.join(dir, "MANIFEST.json"))) {
+        throw new Error(`fixture not found: ${name} (expected ${dir}/MANIFEST.json)`);
+    }
+    return dir;
+}
+function isSafeName(name) {
+    return /^[a-zA-Z0-9._-]+$/.test(name);
+}
+function collectFilesSorted(root) {
+    const out = [];
+    const walk = (dir) => {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const abs = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(abs);
+            else if (entry.isFile())
+                out.push(path.relative(root, abs));
+        }
+    };
+    walk(root);
+    out.sort();
+    return out;
+}
+function copyDirRecursive(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const s = path.join(src, entry.name);
+        const d = path.join(dest, entry.name);
+        if (entry.isDirectory())
+            copyDirRecursive(s, d);
+        else if (entry.isFile())
+            fs.copyFileSync(s, d);
+    }
+}

package/dist/tests/fixtures/stashes/load.test.js

@@ -0,0 +1,88 @@
+/**
+ * Smoke tests for the shared fixture-stash loader.
+ *
+ * Validates that loadFixtureStash, fixtureContentHash, and listFixtures
+ * behave as advertised in docs/technical/benchmark.md §5.5.
+ */
+import { describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import path from "node:path";
+import { computeFixtureContentHash, fixtureContentHash, listFixtures, loadFixtureStash } from "./load";
+describe("loadFixtureStash", () => {
+    test("materialises the minimal fixture and cleanup removes it", () => {
+        const priorAkmStashDir = process.env.AKM_STASH_DIR;
+        const sentinel = "/tmp/some-prior-value";
+        process.env.AKM_STASH_DIR = sentinel;
+        const { stashDir, cleanup, contentHash } = loadFixtureStash("minimal");
+        try {
+            expect(fs.existsSync(stashDir)).toBe(true);
+            expect(fs.statSync(stashDir).isDirectory()).toBe(true);
+            // All five core asset directories from the minimal fixture.
+            for (const sub of ["skills", "commands", "agents", "knowledge", "scripts"]) {
+                expect(fs.existsSync(path.join(stashDir, sub))).toBe(true);
+            }
+            // Content hash is non-empty hex.
+            expect(contentHash).toMatch(/^[0-9a-f]{64}$/);
+            // The helper set AKM_STASH_DIR to the materialised path.
+            expect(process.env.AKM_STASH_DIR).toBe(stashDir);
+            // Default behaviour runs `akm index`, which writes the SQLite DB into
+            // the helper's isolated XDG_CACHE_HOME (sibling of stashDir).
+            const tmpRoot = path.dirname(stashDir);
+            const dbPath = path.join(tmpRoot, "cache", "akm", "index.db");
+            expect(fs.existsSync(dbPath)).toBe(true);
+        }
+        finally {
+            cleanup();
+        }
+        // After cleanup, the tmp tree is gone and AKM_STASH_DIR is restored.
+        expect(fs.existsSync(stashDir)).toBe(false);
+        expect(process.env.AKM_STASH_DIR).toBe(sentinel);
+        // Restore the test's own prior value rather than the synthetic sentinel.
+        if (priorAkmStashDir === undefined)
+            delete process.env.AKM_STASH_DIR;
+        else
+            process.env.AKM_STASH_DIR = priorAkmStashDir;
+    });
+    test("with { skipIndex: true } does not invoke akm index", () => {
+        const priorAkmStashDir = process.env.AKM_STASH_DIR;
+        const { stashDir, cleanup } = loadFixtureStash("minimal", { skipIndex: true });
+        try {
+            // The fixture is still materialised and AKM_STASH_DIR is still set.
+            expect(fs.existsSync(stashDir)).toBe(true);
+            expect(process.env.AKM_STASH_DIR).toBe(stashDir);
+            // But the index DB the helper would otherwise have created in the
+            // isolated XDG_CACHE_HOME is absent — proving no `akm index` ran.
+            const tmpRoot = path.dirname(stashDir);
+            const dbPath = path.join(tmpRoot, "cache", "akm", "index.db");
+            expect(fs.existsSync(dbPath)).toBe(false);
+        }
+        finally {
+            cleanup();
+        }
+        if (priorAkmStashDir === undefined)
+            delete process.env.AKM_STASH_DIR;
+        else
+            process.env.AKM_STASH_DIR = priorAkmStashDir;
+    });
+});
+describe("fixtureContentHash", () => {
+    test("is deterministic for the same fixture", () => {
+        const a = fixtureContentHash("minimal");
+        const b = fixtureContentHash("minimal");
+        expect(a).toBe(b);
+        expect(a).toMatch(/^[0-9a-f]{64}$/);
+    });
+    test("computeFixtureContentHash is the same implementation (#250)", () => {
+        // Critical addendum: there must be exactly one fixture-content hash
+        // function. Two diverging hash implementations for the same content
+        // would be a bug.
+        expect(computeFixtureContentHash).toBe(fixtureContentHash);
+        expect(computeFixtureContentHash("minimal")).toBe(fixtureContentHash("minimal"));
+    });
+});
+describe("listFixtures", () => {
+    test("returns all six shipped fixtures, sorted", () => {
+        const names = listFixtures();
+        expect(names).toEqual(["az-cli", "docker-homelab", "minimal", "multi-domain", "noisy", "ranking-baseline"]);
+    });
+});

package/dist/tests/fixtures/stashes/ranking-baseline/scripts/mem0-search.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env bun
+"use strict";
+/**
+ * Search memories stored in mem0 for relevant context.
+ *
+ * @param {string} query - Search query to find relevant memories
+ * @param {number} limit - Maximum number of results to return
+ */
+const query = process.argv[2] ?? "";
+const limit = parseInt(process.argv[3] ?? "10", 10);
+console.log(`Searching mem0 for: ${query} (limit: ${limit})`);
+// mem0 search implementation would go here

package/dist/tests/frontmatter.test.js

@@ -0,0 +1,190 @@
+import { describe, expect, test } from "bun:test";
+import { parseFrontmatter, parseFrontmatterBlock, parseYamlScalar, toStringOrUndefined } from "../src/core/frontmatter";
+// ── parseFrontmatter ────────────────────────────────────────────────────────
+describe("parseFrontmatter", () => {
+    test("parses basic frontmatter with key-value pairs", () => {
+        const raw = "---\ntitle: Hello\ndescription: A test\n---\nBody content\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data.title).toBe("Hello");
+        expect(result.data.description).toBe("A test");
+        expect(result.content).toBe("Body content\n");
+        expect(result.frontmatter).not.toBeNull();
+    });
+    test("returns empty data and full content when no frontmatter", () => {
+        const raw = "Just some text\nNo frontmatter here\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data).toEqual({});
+        expect(result.content).toBe(raw);
+        expect(result.frontmatter).toBeNull();
+        expect(result.bodyStartLine).toBe(1);
+    });
+    test("parses boolean values", () => {
+        const raw = "---\nenabled: true\ndisabled: false\n---\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data.enabled).toBe(true);
+        expect(result.data.disabled).toBe(false);
+    });
+    test("parses numeric values", () => {
+        const raw = "---\ncount: 42\npi: 3.14\n---\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data.count).toBe(42);
+        expect(result.data.pi).toBe(3.14);
+    });
+    test("parses quoted string values", () => {
+        const raw = "---\ntitle: \"Hello World\"\nsingle: 'test'\n---\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data.title).toBe("Hello World");
+        expect(result.data.single).toBe("test");
+    });
+    test("parses nested key-value pairs", () => {
+        const raw = "---\npolicy:\n  allow: Read,Glob\n  deny: Write\n---\nBody\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data.policy).toEqual({ allow: "Read,Glob", deny: "Write" });
+    });
+    test("handles empty frontmatter block", () => {
+        const raw = "---\n\n---\nBody\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data).toEqual({});
+        expect(result.content).toBe("Body\n");
+    });
+    test("handles keys with hyphens", () => {
+        const raw = "---\nmodel-hint: gpt-4\ntool-policy: allow\n---\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data["model-hint"]).toBe("gpt-4");
+        expect(result.data["tool-policy"]).toBe("allow");
+    });
+    test("handles empty value (starts nested object)", () => {
+        const raw = "---\noptions:\n  verbose: true\n---\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data.options).toEqual({ verbose: true });
+    });
+    test("bodyStartLine is correct", () => {
+        const raw = "---\ntitle: X\ndesc: Y\n---\nBody\n";
+        const result = parseFrontmatter(raw);
+        expect(result.bodyStartLine).toBe(5);
+    });
+    test("handles CRLF line endings", () => {
+        const raw = "---\r\ntitle: Test\r\n---\r\nBody\r\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data.title).toBe("Test");
+        expect(result.content).toContain("Body");
+    });
+    // ── List / array support ───────────────────────────────────────────────────
+    test("parses flow array (inline style)", () => {
+        const raw = "---\ntags: [ops, networking, deploy]\n---\nBody\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data.tags).toEqual(["ops", "networking", "deploy"]);
+    });
+    test("parses block-sequence (- item style)", () => {
+        const raw = "---\ntags:\n- ops\n- networking\n- deploy\n---\nBody\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data.tags).toEqual(["ops", "networking", "deploy"]);
+    });
+    test("parses block-sequence with 2-space indent", () => {
+        const raw = "---\ntags:\n  - ops\n  - networking\n---\nBody\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data.tags).toEqual(["ops", "networking"]);
+    });
+    test("parses block-sequence with scalar values (bool, number)", () => {
+        const raw = "---\nvalues:\n- true\n- 42\n- hello\n---\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data.values).toEqual([true, 42, "hello"]);
+    });
+    test("parses empty flow array", () => {
+        const raw = "---\ntags: []\n---\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data.tags).toEqual([]);
+    });
+    test("block sequence followed by another top-level key", () => {
+        const raw = "---\ntags:\n- ops\n- networking\ndescription: A test\n---\nBody\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data.tags).toEqual(["ops", "networking"]);
+        expect(result.data.description).toBe("A test");
+    });
+    test("mixed styles: flow array and block sequence in same document", () => {
+        const raw = "---\ntags: [ops, networking]\naliases:\n- op\n- net\ndescription: test\n---\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data.tags).toEqual(["ops", "networking"]);
+        expect(result.data.aliases).toEqual(["op", "net"]);
+        expect(result.data.description).toBe("test");
+    });
+    test("empty value with no continuation becomes empty string (backward compat)", () => {
+        const raw = "---\ntitle: Hello\nempty:\ndescription: test\n---\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data.title).toBe("Hello");
+        expect(result.data.empty).toBe("");
+        expect(result.data.description).toBe("test");
+    });
+    test("single-item block sequence", () => {
+        const raw = "---\ntags:\n- solo\n---\n";
+        const result = parseFrontmatter(raw);
+        expect(result.data.tags).toEqual(["solo"]);
+    });
+});
+// ── parseFrontmatterBlock ───────────────────────────────────────────────────
+describe("parseFrontmatterBlock", () => {
+    test("returns null for content without frontmatter delimiters", () => {
+        expect(parseFrontmatterBlock("No frontmatter")).toBeNull();
+    });
+    test("returns null for content that doesn't start with ---", () => {
+        expect(parseFrontmatterBlock("text\n---\nfoo\n---\n")).toBeNull();
+    });
+    test("extracts frontmatter and content correctly", () => {
+        const result = parseFrontmatterBlock("---\nkey: val\n---\nbody\n");
+        expect(result).not.toBeNull();
+        expect(result?.frontmatter).toBe("key: val");
+        expect(result?.content).toBe("body\n");
+    });
+    test("handles frontmatter without trailing content", () => {
+        const result = parseFrontmatterBlock("---\nkey: val\n---\n");
+        expect(result).not.toBeNull();
+        expect(result?.frontmatter).toBe("key: val");
+        expect(result?.content).toBe("");
+    });
+});
+// ── parseYamlScalar ─────────────────────────────────────────────────────────
+describe("parseYamlScalar", () => {
+    test("returns empty string for empty input", () => {
+        expect(parseYamlScalar("")).toBe("");
+    });
+    test("returns boolean for true/false", () => {
+        expect(parseYamlScalar("true")).toBe(true);
+        expect(parseYamlScalar("false")).toBe(false);
+    });
+    test("returns number for numeric strings", () => {
+        expect(parseYamlScalar("42")).toBe(42);
+        expect(parseYamlScalar("3.14")).toBe(3.14);
+        expect(parseYamlScalar("0")).toBe(0);
+        expect(parseYamlScalar("-1")).toBe(-1);
+    });
+    test("strips quotes from quoted strings", () => {
+        expect(parseYamlScalar('"hello"')).toBe("hello");
+        expect(parseYamlScalar("'world'")).toBe("world");
+    });
+    test("returns plain string for unquoted non-boolean non-numeric", () => {
+        expect(parseYamlScalar("hello")).toBe("hello");
+        expect(parseYamlScalar("some-value")).toBe("some-value");
+    });
+    test("does not strip mismatched quotes", () => {
+        expect(parseYamlScalar("\"hello'")).toBe("\"hello'");
+    });
+});
+// ── toStringOrUndefined ─────────────────────────────────────────────────────
+describe("toStringOrUndefined", () => {
+    test("returns string for non-empty string", () => {
+        expect(toStringOrUndefined("hello")).toBe("hello");
+    });
+    test("returns undefined for empty string", () => {
+        expect(toStringOrUndefined("")).toBeUndefined();
+    });
+    test("returns undefined for whitespace-only string", () => {
+        expect(toStringOrUndefined("   ")).toBeUndefined();
+    });
+    test("returns undefined for non-string values", () => {
+        expect(toStringOrUndefined(42)).toBeUndefined();
+        expect(toStringOrUndefined(null)).toBeUndefined();
+        expect(toStringOrUndefined(undefined)).toBeUndefined();
+        expect(toStringOrUndefined(true)).toBeUndefined();
+        expect(toStringOrUndefined({})).toBeUndefined();
+    });
+});