akm-cli 0.6.1 → 0.7.0

package/dist/tests/contracts/v1-spec-section-4-2-quality-rules.test.js

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { extractSection, readDoc, SPEC_PATH } from "./spec-helpers";
+// Pins v1 spec §4.2 — Asset quality rules (open set, default-filtered).
+//
+// The freeze rule is:
+//   * `generated` and `curated` are well-known and included in default search.
+//   * `proposed` is well-known and excluded from default search; surfaced via
+//     `--include-proposed` or `akm proposal *`.
+//   * Unknown values parse, warn, and remain searchable.
+describe("v1 spec §4.2 — asset quality rules", () => {
+    const spec = readDoc(SPEC_PATH);
+    const section = extractSection(spec, "### 4.2 Asset quality rules");
+    test("§4.2 exists in the spec", () => {
+        expect(section).not.toBe("");
+    });
+    test("§4.2 names the three well-known quality values", () => {
+        expect(section).toContain('"generated"');
+        expect(section).toContain('"curated"');
+        expect(section).toContain('"proposed"');
+    });
+    test("§4.2 declares `proposed` is excluded from default search", () => {
+        // Either phrasing is fine; we want both pieces of the rule present.
+        expect(section).toMatch(/Excluded from default search/i);
+        expect(section).toMatch(/--include-proposed|akm proposal/);
+    });
+    test("§4.2 names the `--include-proposed` opt-in flag explicitly", () => {
+        // Locked CLI surface — this flag is the single way to surface
+        // `proposed`-quality rows from `akm search` without going through
+        // `akm proposal *`. Renaming is a major bump.
+        expect(section).toContain("--include-proposed");
+    });
+    test("§4.2 declares unknown quality values parse-warn-include", () => {
+        expect(section).toMatch(/Unknown quality values/i);
+        expect(section).toMatch(/parse,?\s*warn/i);
+    });
+    test("§4.2 declares the legacy registry `curated` boolean is removed", () => {
+        expect(section).toMatch(/legacy registry boolean `curated`/i);
+        expect(section).toMatch(/parses and ignores/i);
+    });
+    test("§4.2 names the new optional SearchHit fields", () => {
+        expect(section).toContain("quality?");
+        expect(section).toContain("warnings?");
+    });
+});

package/dist/tests/contracts/v1-spec-section-5-configuration.test.js

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "bun:test";
+import { extractSection, readDoc, SPEC_PATH } from "./spec-helpers";
+// Pins v1 spec §5 — Configuration.
+//
+// The freeze rule:
+//   * The JSON schema names `sources[]`, `registries[]`, `embedder`, `scorer`,
+//     `agent` (Planned), `llm` + `llm.features` (Planned), and
+//     `defaultWriteTarget`.
+//   * Value forms: literal or `{ env: "VAR" }`.
+//   * `writable: true` is rejected on `website` / `npm`.
+//   * Per-provider option schemas validate at config-load time.
+describe("v1 spec §5 — configuration", () => {
+    const spec = readDoc(SPEC_PATH);
+    const section = extractSection(spec, "## 5. Configuration");
+    test("§5 exists in the spec", () => {
+        expect(section).not.toBe("");
+    });
+    test("§5.1 names every locked top-level config key", () => {
+        expect(section).toContain('"sources"');
+        expect(section).toContain('"registries"');
+        expect(section).toContain('"embedder"');
+        expect(section).toContain('"scorer"');
+        expect(section).toContain('"agent"');
+        expect(section).toContain('"llm"');
+        expect(section).toContain('"features"');
+        expect(section).toContain('"defaultWriteTarget"');
+    });
+    test("§5.2 declares the literal-or-env value form", () => {
+        expect(section).toMatch(/literal/i);
+        expect(section).toMatch(/\{\s*"env":\s*"VAR_NAME"\s*\}/);
+        expect(section).toMatch(/Missing required env vars produce `ConfigError`/i);
+    });
+    test("§5.3 declares per-provider option JSON schemas validated at load", () => {
+        expect(section).toMatch(/JSON Schema/);
+        expect(section).toMatch(/Missing required fields fail at load/i);
+    });
+    test("§5.4 declares the `writable` defaults and rejection rule", () => {
+        expect(section).toMatch(/`true`\s*for\s*`filesystem`/);
+        expect(section).toMatch(/`false`\s*for everything else/);
+        expect(section).toMatch(/rejected at config load.*for `website` and `npm`/s);
+        expect(section).toContain("ConfigError");
+    });
+    test("§5 stops before §6 (helper boundary check)", () => {
+        expect(section).not.toContain("## 6.");
+        expect(section).not.toContain("## 7.");
+    });
+});

package/dist/tests/contracts/v1-spec-section-6-orchestration.test.js

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+import { extractSection, readDoc, SPEC_PATH } from "./spec-helpers";
+// Pins v1 spec §6 — Orchestration.
+//
+// The freeze rule:
+//   * search → indexer.search(q); registry hits never merge into source hits.
+//   * show → indexer.lookup(ref) then read file from disk.
+//   * remember/import target resolution: --target → defaultWriteTarget →
+//     working stash → ConfigError.
+//   * `index.db` is ephemeral; `usage_events` is preserved across schema bumps.
+describe("v1 spec §6 — orchestration", () => {
+    const spec = readDoc(SPEC_PATH);
+    const section = extractSection(spec, "## 6. Orchestration");
+    test("§6 exists in the spec", () => {
+        expect(section).not.toBe("");
+    });
+    test("§6.1 says search uses indexer.search and registry hits stay separate", () => {
+        expect(section).toMatch(/indexer\.search/);
+        expect(section).toMatch(/--include-registry/);
+        expect(section).toMatch(/never merge into source hits/i);
+    });
+    test("§6.2 says show uses indexer.lookup and reads the file from disk", () => {
+        expect(section).toMatch(/indexer\.lookup/);
+        expect(section).toMatch(/readFile/);
+    });
+    test("§6.5 declares the write-target resolution order", () => {
+        const flat = section.replace(/\s+/g, " ");
+        expect(flat).toMatch(/--target.*defaultWriteTarget.*working stash.*ConfigError/);
+        expect(section).toMatch(/akm init/);
+    });
+    test("§6.7 declares index.db is ephemeral and usage_events is preserved", () => {
+        expect(section).toMatch(/index\.db.*ephemeral/i);
+        expect(section).toMatch(/preserving `usage_events`/);
+        expect(section).toMatch(/workflow\.db.*never\s*touched/i);
+    });
+    test("§6 stops before §7 (helper boundary check)", () => {
+        expect(section).not.toContain("## 7.");
+        expect(section).not.toContain("## 8.");
+    });
+});

package/dist/tests/contracts/v1-spec-section-7-module-layout.test.js

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import path from "node:path";
+import { extractSection, readDoc, SPEC_PATH } from "./spec-helpers";
+// Pins v1 spec §7 — Module layout.
+//
+// We don't enforce the literal tree the spec sketches (the spec uses a
+// schematic, the actual tree has more files). We DO enforce the named
+// anchor modules — moving or renaming any of these is a contract change.
+// The spec's §7 schematic uses idealized names (`refs.ts`, `types.ts`); the
+// shipped tree has slightly different file names but the same concepts. We
+// pin the actually-shipped anchors — moving any of these is a real
+// contract change, not a rename of a doc-only schematic.
+const REQUIRED_FILES = [
+    "src/cli.ts",
+    "src/core/asset-ref.ts",
+    "src/core/errors.ts",
+    "src/core/config.ts",
+    "src/core/write-source.ts",
+];
+const REQUIRED_DIRS = ["src/commands", "src/sources", "src/registry", "src/indexer", "src/output"];
+const repoRoot = path.resolve(import.meta.dir, "..", "..");
+describe("v1 spec §7 — module layout", () => {
+    const spec = readDoc(SPEC_PATH);
+    const section = extractSection(spec, "## 7. Module layout");
+    test("§7 exists in the spec", () => {
+        expect(section).not.toBe("");
+    });
+    test("§7 names the locked anchor modules in the schematic", () => {
+        // The schematic in the spec uses these names; renaming requires a major
+        // bump. (Some files ship under slightly different names; see the
+        // on-disk anchor check below.)
+        expect(section).toContain("write-source.ts");
+        expect(section).toContain("config.ts");
+        expect(section).toContain("errors.ts");
+        expect(section).toContain("cli.ts");
+    });
+    test("locked anchor files exist on disk", () => {
+        for (const rel of REQUIRED_FILES) {
+            expect(fs.existsSync(path.join(repoRoot, rel))).toBe(true);
+        }
+    });
+    test("locked anchor directories exist on disk", () => {
+        for (const rel of REQUIRED_DIRS) {
+            const stat = fs.statSync(path.join(repoRoot, rel));
+            expect(stat.isDirectory()).toBe(true);
+        }
+    });
+    test("§7 lists what was removed from 0.6.0", () => {
+        expect(section).toMatch(/Removed from 0\.6\.0/);
+        expect(section).toMatch(/openviking/i);
+        expect(section).toMatch(/stash-search\.ts|stash-show\.ts/);
+    });
+    test("§7 stops before §8 (helper boundary check)", () => {
+        expect(section).not.toContain("## 8.");
+        expect(section).not.toContain("## 9.");
+    });
+});

package/dist/tests/contracts/v1-spec-section-8-extension-points.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import { extractSection, readDoc, SPEC_PATH } from "./spec-helpers";
+// Pins v1 spec §8 — Extension points.
+//
+// The freeze rule: six surfaces are pluggable at v1; four are deliberately
+// not. Removing or adding a surface to either list after v1.0 is a major
+// bump.
+const PLUGGABLE = ["SourceProvider", "RegistryProvider", "Asset type", "Embedder", "Renderer", "Ingest transformer"];
+const NOT_EXTENSIBLE = ["API-backed sources", "Vault", "Scorer algorithm", "Output format"];
+describe("v1 spec §8 — extension points", () => {
+    const spec = readDoc(SPEC_PATH);
+    const section = extractSection(spec, "## 8. Extension points");
+    test("§8 exists in the spec", () => {
+        expect(section).not.toBe("");
+    });
+    test("§8 names every pluggable surface at v1", () => {
+        for (const surface of PLUGGABLE) {
+            expect(section).toContain(surface);
+        }
+    });
+    test("§8 names every surface deliberately not extensible at v1", () => {
+        for (const surface of NOT_EXTENSIBLE) {
+            expect(section).toContain(surface);
+        }
+    });
+    test("§8 declares output format is text/json only", () => {
+        expect(section).toMatch(/`text` and `json` only/);
+        expect(section).toMatch(/ndjson.*tsv.*mcp/);
+    });
+    test("§8 stops before §9 (helper boundary check)", () => {
+        expect(section).not.toContain("## 9.");
+        expect(section).not.toContain("## 10.");
+    });
+});

package/dist/tests/contracts/v1-spec-section-9-4-cli-surface.test.js

@@ -0,0 +1,75 @@
+import { describe, expect, test } from "bun:test";
+import { CLI_DOC_PATH, extractSection, readDoc, SPEC_PATH } from "./spec-helpers";
+// Pins v1 spec §9.4 — CLI command surface.
+//
+// The locked surface is exhaustive. The shipped pre-release set and the
+// planned-for-v1 additions together form the v1.0 freeze. Renaming or
+// removing any command after v1.0 is a major version bump.
+const SHIPPED_COMMANDS = [
+    "add",
+    "remove",
+    "list",
+    "update",
+    "search",
+    "show",
+    "clone",
+    "index",
+    "setup",
+    "remember",
+    "import",
+    "feedback",
+    "info",
+    "curate",
+    "workflow",
+    "vault",
+    "wiki",
+    "enable",
+    "disable",
+    "completions",
+    "upgrade",
+    "save",
+    "help",
+    "hints",
+    "config",
+];
+const PLANNED_FOR_V1 = ["agent", "reflect", "propose", "proposal", "distill"];
+describe("v1 spec §9.4 — CLI command surface", () => {
+    const spec = readDoc(SPEC_PATH);
+    const section = extractSection(spec, "### 9.4 CLI command surface");
+    test("§9.4 exists in the spec", () => {
+        expect(section).not.toBe("");
+    });
+    test("§9.4 lists every shipped pre-release command", () => {
+        // The shipped set is rendered as a pipe-joined inline-code block; tokens
+        // appear as standalone words. We assert each command word appears in
+        // the section text without caring about its surrounding backticks.
+        for (const cmd of SHIPPED_COMMANDS) {
+            const re = new RegExp(`\\b${cmd}\\b`);
+            expect(re.test(section)).toBe(true);
+        }
+        expect(section).toMatch(/\bregistry\b/);
+    });
+    test("§9.4 declares each planned-for-v1 command", () => {
+        for (const cmd of PLANNED_FOR_V1) {
+            // accept either `cmd` or `cmd <args>` patterns
+            const re = new RegExp(`\`${cmd}\\b`);
+            expect(re.test(section)).toBe(true);
+        }
+    });
+    test("§9.4 explicitly says renaming or removing is major", () => {
+        expect(section).toMatch(/major version bump/i);
+    });
+});
+describe("v1 spec §9.4 — cli.md mirrors the surface", () => {
+    const cli = readDoc(CLI_DOC_PATH);
+    test("cli.md has an Available-since-0.7.0 section listing the 0.7.0 commands", () => {
+        const planned = extractSection(cli, "## Agent reflection and proposal queue (0.7.0+)");
+        expect(planned).not.toBe("");
+        for (const cmd of PLANNED_FOR_V1) {
+            expect(planned).toContain(`### ${cmd}`);
+        }
+    });
+    test("cli.md uses the documented status legend", () => {
+        expect(cli).toMatch(/Available since 0\.7\.0/);
+    });
+});

package/dist/tests/contracts/v1-spec-section-9-7-llm-agent-boundary.test.js

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { extractSection, readDoc, SPEC_PATH } from "./spec-helpers";
+// Pins v1 spec §9.7 — LLM/agent boundary.
+//
+// Two locked invariants:
+//   * In-tree LLM helpers are bounded, single-shot, stateless — no shells,
+//     no long-running processes, no caches keyed on prior responses.
+//   * External agents are invoked via CLI shell-out only. akm never imports
+//     a vendor SDK.
+describe("v1 spec §9.7 — LLM/agent boundary", () => {
+    const spec = readDoc(SPEC_PATH);
+    const section = extractSection(spec, "### 9.7 LLM/agent boundary");
+    test("§9.7 exists in the spec", () => {
+        expect(section).not.toBe("");
+    });
+    test("§9.7 declares in-tree LLM is bounded, single-shot, stateless", () => {
+        expect(section).toMatch(/bounded/i);
+        expect(section).toMatch(/single-shot/i);
+        expect(section).toMatch(/stateless/i);
+    });
+    test("§9.7 declares external agents are CLI shell-out only", () => {
+        // Tolerate markdown line-wrapping by collapsing whitespace + emphasis
+        // markers when matching.
+        const flat = section.replace(/[*\s]+/g, " ");
+        expect(flat).toMatch(/CLI shell-out only/i);
+        expect(flat).toMatch(/never imports vendor SDKs/i);
+    });
+    test("§9.7 names a `llm.features.*` per-call-site gate", () => {
+        expect(section).toMatch(/llm\.features\.\*/);
+        expect(section).toMatch(/exactly one/i);
+    });
+    test("§9.7 says crossing the boundary is a contract violation", () => {
+        const flat = section.replace(/\s+/g, " ");
+        expect(flat).toMatch(/contract violation/i);
+    });
+});