akm-cli 0.7.5 → 0.8.0-rc1

package/dist/core/parse.js

@@ -0,0 +1,155 @@
+/**
+ * Shared JSON parsing utilities for LLM and agent output.
+ *
+ * Lives in `src/core/` so that both `src/llm/` and `src/integrations/agent/`
+ * can import without crossing the one-way boundary defined by v1 spec §9.7
+ * (agent/ must not import from llm/).
+ *
+ * The canonical implementation is ported from `src/llm/client.ts` (most
+ * complete version):
+ *   - Strips `<think>…</think>` reasoning blocks.
+ *   - Strips markdown code fences (``` or ~~~, optional language tag, with
+ *     trailing spaces on the fence line).
+ *   - Escapes unescaped control characters (actual \n, \r, \t bytes) inside
+ *     JSON string values so `JSON.parse` succeeds on outputs from local LLMs.
+ *   - Balanced-brace scanner handles both `{…}` and `[…]` top-level
+ *     structures (spawn.ts v0 only handled `{…}` — that was a bug).
+ */
+/**
+ * Strips `<think>…</think>` blocks from LLM output (for reasoning-capable
+ * models). Also strips leading/trailing whitespace.
+ */
+export function stripThinkBlocks(raw) {
+    return raw.replace(/<think>[\s\S]*?<\/think>/gi, "").trim();
+}
+/**
+ * Strips markdown code fences (``` or ~~~, with optional language tag).
+ * Handles fences with trailing spaces. Returns trimmed content.
+ */
+export function stripCodeFences(raw) {
+    return raw
+        .trim()
+        .replace(/^```(?:json)?\s*\n?/i, "")
+        .replace(/\n?```\s*$/i, "")
+        .trim();
+}
+/**
+ * Escapes unescaped control characters (actual \n, \r, \t bytes) inside JSON
+ * string values. Prevents `JSON.parse` failures from embedded newlines in
+ * local-LLM output.
+ */
+export function escapeJsonStringControls(raw) {
+    let out = "";
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < raw.length; i++) {
+        const ch = raw[i];
+        if (escaped) {
+            out += ch;
+            escaped = false;
+            continue;
+        }
+        if (ch === "\\" && inString) {
+            out += ch;
+            escaped = true;
+            continue;
+        }
+        if (ch === '"') {
+            inString = !inString;
+            out += ch;
+            continue;
+        }
+        if (inString) {
+            if (ch === "\n") {
+                out += "\\n";
+                continue;
+            }
+            if (ch === "\r") {
+                out += "\\r";
+                continue;
+            }
+            if (ch === "\t") {
+                out += "\\t";
+                continue;
+            }
+        }
+        out += ch;
+    }
+    return out;
+}
+/**
+ * Full pipeline: stripThinkBlocks → stripCodeFences → escapeJsonStringControls
+ * → JSON.parse. Returns `undefined` on parse failure.
+ */
+export function parseJsonResponse(raw) {
+    try {
+        const cleaned = escapeJsonStringControls(stripCodeFences(stripThinkBlocks(raw)));
+        return JSON.parse(cleaned);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Attempts `parseJsonResponse` first. On failure, scans for the first
+ * balanced `{ }` or `[ ]` structure in the text and attempts to parse that
+ * substring. Returns `undefined` if no valid JSON structure is found.
+ *
+ * Non-array results are preferred: if a `{…}` object is found first, it is
+ * returned immediately. Arrays (`[…]`) are captured as a fallback and
+ * returned only when no object was found.
+ */
+export function parseEmbeddedJsonResponse(raw) {
+    const direct = parseJsonResponse(raw);
+    if (direct !== undefined)
+        return direct;
+    const text = escapeJsonStringControls(stripCodeFences(stripThinkBlocks(raw)));
+    let arrayFallback;
+    for (let start = 0; start < text.length; start++) {
+        const opener = text[start];
+        if (opener !== "{" && opener !== "[")
+            continue;
+        const closer = opener === "{" ? "}" : "]";
+        let depth = 0;
+        let inString = false;
+        let escaped = false;
+        for (let i = start; i < text.length; i++) {
+            const ch = text[i];
+            if (inString) {
+                if (escaped) {
+                    escaped = false;
+                }
+                else if (ch === "\\") {
+                    escaped = true;
+                }
+                else if (ch === '"') {
+                    inString = false;
+                }
+                continue;
+            }
+            if (ch === '"') {
+                inString = true;
+                continue;
+            }
+            if (ch === opener)
+                depth += 1;
+            if (ch === closer) {
+                depth -= 1;
+                if (depth === 0) {
+                    try {
+                        const parsed = JSON.parse(text.slice(start, i + 1));
+                        if (!Array.isArray(parsed)) {
+                            return parsed;
+                        }
+                        arrayFallback ??= parsed;
+                        break;
+                    }
+                    catch {
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    return arrayFallback;
+}

package/dist/core/paths.js

@@ -6,8 +6,8 @@
  * on Windows.
  */
 import path from "node:path";
+import { IS_WINDOWS } from "./common";
 import { ConfigError } from "./errors";
-const IS_WINDOWS = process.platform === "win32";
 // ── Config directory ─────────────────────────────────────────────────────────
 export function getConfigDir(env = process.env, platform = process.platform) {
     const override = env.AKM_CONFIG_DIR?.trim();
@@ -65,11 +65,102 @@ export function getCacheDir() {
         return path.join("/tmp", "akm-cache");
     return path.join(home, ".cache", "akm");
 }
+// ── Data directory ───────────────────────────────────────────────────────────
+/**
+ * Returns the XDG data directory for akm (`~/.local/share/akm` on Linux/macOS,
+ * `%LOCALAPPDATA%\akm\data` on Windows).
+ *
+ * Holds durable, non-regenerable application data: SQLite databases
+ * (index.db, workflow.db, state.db), akm.lock, and config-backups.
+ * Losing this directory loses history and installed state.
+ *
+ * Env overrides (in priority order):
+ *   AKM_DATA_DIR   — point to any directory
+ *   XDG_DATA_HOME  — (Linux/macOS) override the XDG base; akm subdir is appended
+ */
+export function getDataDir(env = process.env, platform = process.platform) {
+    const override = env.AKM_DATA_DIR?.trim();
+    if (override)
+        return override;
+    if (platform === "win32") {
+        const localAppData = env.LOCALAPPDATA?.trim();
+        if (localAppData)
+            return path.join(localAppData, "akm", "data");
+        const userProfile = env.USERPROFILE?.trim();
+        if (userProfile)
+            return path.join(userProfile, "AppData", "Local", "akm", "data");
+        const appData = env.APPDATA?.trim();
+        if (!appData) {
+            throw new ConfigError("Unable to determine data directory. Set LOCALAPPDATA, USERPROFILE, or APPDATA.", "CONFIG_DIR_UNRESOLVABLE");
+        }
+        return path.join(appData, "..", "Local", "akm", "data");
+    }
+    const xdgDataHome = env.XDG_DATA_HOME?.trim();
+    if (xdgDataHome)
+        return path.join(xdgDataHome, "akm");
+    const home = env.HOME?.trim();
+    if (!home)
+        return path.join("/tmp", "akm-data");
+    return path.join(home, ".local", "share", "akm");
+}
+// ── State directory ──────────────────────────────────────────────────────────
+/**
+ * Returns the XDG state directory for akm (`~/.local/state/akm` on Linux/macOS,
+ * `%LOCALAPPDATA%\akm\state` on Windows).
+ *
+ * Holds runtime state and log-like files that persist across reboots but are
+ * less precious than $DATA: task history JSONL files, akm.lock.lck sentinel.
+ *
+ * Env overrides (in priority order):
+ *   AKM_STATE_DIR   — point to any directory
+ *   XDG_STATE_HOME  — (Linux/macOS) override the XDG base; akm subdir is appended
+ */
+export function getStateDir(env = process.env, platform = process.platform) {
+    const override = env.AKM_STATE_DIR?.trim();
+    if (override)
+        return override;
+    if (platform === "win32") {
+        const localAppData = env.LOCALAPPDATA?.trim();
+        if (localAppData)
+            return path.join(localAppData, "akm", "state");
+        const userProfile = env.USERPROFILE?.trim();
+        if (userProfile)
+            return path.join(userProfile, "AppData", "Local", "akm", "state");
+        const appData = env.APPDATA?.trim();
+        if (!appData) {
+            throw new ConfigError("Unable to determine state directory. Set LOCALAPPDATA, USERPROFILE, or APPDATA.", "CONFIG_DIR_UNRESOLVABLE");
+        }
+        return path.join(appData, "..", "Local", "akm", "state");
+    }
+    const xdgStateHome = env.XDG_STATE_HOME?.trim();
+    if (xdgStateHome)
+        return path.join(xdgStateHome, "akm");
+    const home = env.HOME?.trim();
+    if (!home)
+        return path.join("/tmp", "akm-state");
+    return path.join(home, ".local", "state", "akm");
+}
 export function getDbPath() {
-    return path.join(getCacheDir(), "index.db");
+    return path.join(getDataDir(), "index.db");
 }
 export function getWorkflowDbPath() {
-    return path.join(getCacheDir(), "workflow.db");
+    return path.join(getDataDir(), "workflow.db");
+}
+/** Path to the state.db file in $DATA. */
+export function getStateDbPathInDataDir() {
+    return path.join(getDataDir(), "state.db");
+}
+/** Path for the task history directory in $STATE (v2 location). */
+export function getTaskHistoryStateDir() {
+    return path.join(getStateDir(), "tasks", "history");
+}
+/** Path to the akm.lock file in $DATA. */
+export function getLockfilePath() {
+    return path.join(getDataDir(), "akm.lock");
+}
+/** Path to the akm.lock.lck write-sentinel in $DATA. */
+export function getLockfileLockPath() {
+    return path.join(getDataDir(), "akm.lock.lck");
 }
 export function getSemanticStatusPath() {
     return path.join(getCacheDir(), "semantic-status.json");
@@ -83,6 +174,13 @@ export function getRegistryIndexCacheDir() {
 export function getBinDir() {
     return path.join(getCacheDir(), "bin");
 }
+// ── Scheduled-task runtime directories (logs + history) ──────────────────────
+export function getTaskLogDir() {
+    return path.join(getCacheDir(), "tasks", "logs");
+}
+export function getTaskHistoryDir() {
+    return path.join(getCacheDir(), "tasks", "history");
+}
 // ── Default stash directory ──────────────────────────────────────────────────
 export function getDefaultStashDir() {
     const override = process.env.AKM_STASH_DIR?.trim();

package/dist/core/proposal-validators.js

@@ -0,0 +1,61 @@
+import { parseAssetRef } from "./asset-ref";
+import { parseFrontmatter } from "./frontmatter";
+import { lintLessonContent } from "./lesson-lint";
+const genericProposalValidator = {
+    name: "generic-proposal-validator",
+    appliesTo: () => true,
+    validate(proposal, ctx) {
+        const findings = [];
+        if (!proposal.payload || typeof proposal.payload.content !== "string" || proposal.payload.content.trim() === "") {
+            findings.push({ kind: "empty-content", message: `Proposal ${proposal.id} has empty content.` });
+        }
+        try {
+            ctx.parsedRef = parseAssetRef(proposal.ref);
+        }
+        catch (err) {
+            findings.push({
+                kind: "invalid-ref",
+                message: `Proposal ${proposal.id} has invalid ref "${proposal.ref}": ${err.message}`,
+            });
+            ctx.stop = true;
+            return findings;
+        }
+        if (proposal.payload.content.startsWith("---")) {
+            try {
+                parseFrontmatter(proposal.payload.content);
+            }
+            catch (err) {
+                findings.push({
+                    kind: "invalid-frontmatter",
+                    message: `Proposal ${proposal.id} frontmatter could not be parsed: ${err.message}`,
+                });
+            }
+        }
+        return findings;
+    },
+};
+const lessonProposalValidator = {
+    name: "lesson-proposal-validator",
+    appliesTo(_proposal, ctx) {
+        return ctx.parsedRef?.type === "lesson";
+    },
+    validate(proposal) {
+        return lintLessonContent(proposal.payload.content, `proposal:${proposal.id}`).findings.map((finding) => ({
+            kind: finding.kind,
+            message: finding.message,
+        }));
+    },
+};
+export const defaultProposalValidators = [genericProposalValidator, lessonProposalValidator];
+export function runProposalValidators(proposal, validators = defaultProposalValidators) {
+    const findings = [];
+    const ctx = {};
+    for (const validator of validators) {
+        if (!validator.appliesTo(proposal, ctx))
+            continue;
+        findings.push(...validator.validate(proposal, ctx));
+        if (ctx.stop)
+            break;
+    }
+    return { ok: findings.length === 0, findings };
+}

package/dist/core/proposals.js

@@ -39,8 +39,7 @@ import path from "node:path";
 import { makeAssetRef, parseAssetRef } from "./asset-ref";
 import { resolveAssetPathFromName, TYPE_DIRS } from "./asset-spec";
 import { NotFoundError, UsageError } from "./errors";
-import { parseFrontmatter } from "./frontmatter";
-import { lintLessonContent } from "./lesson-lint";
+import { runProposalValidators } from "./proposal-validators";
 import { resolveWriteTarget, writeAssetToSource } from "./write-source";
 // ── Path helpers ────────────────────────────────────────────────────────────
 /**
@@ -190,6 +189,53 @@ export function getProposal(stashDir, id) {
         return readProposalFile(archivedPath);
     throw new NotFoundError(`Proposal "${id}" not found.`, "FILE_NOT_FOUND");
 }
+/**
+ * Resolve a proposal by full UUID, UUID prefix, or asset ref.
+ *
+ * Resolution order:
+ *   1. Exact UUID match (existing behaviour).
+ *   2. Asset ref (contains `:`) — finds the most-recent pending proposal for
+ *      that ref; falls back to archived if nothing is pending.
+ *   3. UUID prefix — matches any live proposal directory whose name starts
+ *      with the given string; throws if ambiguous.
+ */
+export function resolveProposalId(stashDir, idOrRef) {
+    // 1. Exact UUID.
+    try {
+        return getProposal(stashDir, idOrRef);
+    }
+    catch (e) {
+        if (!(e instanceof NotFoundError))
+            throw e;
+    }
+    // 2. Asset ref (e.g. "skill:akm-dream").
+    if (idOrRef.includes(":")) {
+        const pending = listProposals(stashDir, { ref: idOrRef });
+        if (pending.length > 0) {
+            return pending.sort((a, b) => new Date(b.createdAt ?? 0).getTime() - new Date(a.createdAt ?? 0).getTime())[0];
+        }
+        const archived = listProposals(stashDir, { ref: idOrRef, includeArchive: true });
+        if (archived.length > 0) {
+            return archived.sort((a, b) => new Date(b.createdAt ?? 0).getTime() - new Date(a.createdAt ?? 0).getTime())[0];
+        }
+        throw new NotFoundError(`No proposal found for ref "${idOrRef}".`, "FILE_NOT_FOUND");
+    }
+    // 3. UUID prefix.
+    const liveDir = getProposalsRoot(stashDir, false);
+    let prefixMatches = [];
+    try {
+        prefixMatches = fs.readdirSync(liveDir).filter((name) => name.startsWith(idOrRef));
+    }
+    catch {
+        /* live dir may not exist yet */
+    }
+    if (prefixMatches.length === 1)
+        return getProposal(stashDir, prefixMatches[0]);
+    if (prefixMatches.length > 1) {
+        throw new UsageError(`Ambiguous prefix "${idOrRef}" — matches: ${prefixMatches.join(", ")}`, "INVALID_FLAG_VALUE");
+    }
+    throw new NotFoundError(`Proposal "${idOrRef}" not found.`, "FILE_NOT_FOUND");
+}
 /**
  * Whether a proposal currently lives in the archive (used by callers that
  * need to know whether to look in the archive root for files / paths).
@@ -248,42 +294,7 @@ export function archiveProposal(stashDir, id, status, reason, ctx) {
  * here in the future without changing call sites.
  */
 export function validateProposal(proposal) {
-    const findings = [];
-    if (!proposal.payload || typeof proposal.payload.content !== "string" || proposal.payload.content.trim() === "") {
-        findings.push({ kind: "empty-content", message: `Proposal ${proposal.id} has empty content.` });
-    }
-    let ref;
-    try {
-        ref = parseAssetRef(proposal.ref);
-    }
-    catch (err) {
-        findings.push({
-            kind: "invalid-ref",
-            message: `Proposal ${proposal.id} has invalid ref "${proposal.ref}": ${err.message}`,
-        });
-        return { ok: false, findings };
-    }
-    // Generic frontmatter parse check for markdown-y types. If the content
-    // *looks* like it has frontmatter (`---\n…\n---`) we ensure it parses.
-    if (proposal.payload.content.startsWith("---")) {
-        try {
-            parseFrontmatter(proposal.payload.content);
-        }
-        catch (err) {
-            findings.push({
-                kind: "invalid-frontmatter",
-                message: `Proposal ${proposal.id} frontmatter could not be parsed: ${err.message}`,
-            });
-        }
-    }
-    // Type-specific validators.
-    if (ref.type === "lesson") {
-        const lessonReport = lintLessonContent(proposal.payload.content, `proposal:${proposal.id}`);
-        for (const finding of lessonReport.findings) {
-            findings.push({ kind: finding.kind, message: finding.message });
-        }
-    }
-    return { ok: findings.length === 0, findings };
+    return runProposalValidators(proposal);
 }
 /**
  * Validate a proposal, then promote it through the canonical