akm-cli 0.7.4 → 0.8.0-rc.3

package/dist/commands/vault.js

@@ -5,13 +5,9 @@
  * the indexer, the `akm show` renderer, or any structured output channel.
  * The supported load paths are:
  *
- *   - `eval "$(akm vault load vault:<name>)"` — `vault load` parses the vault
- *     with dotenv (no shell expansion, no code execution), writes a safely
- *     single-quote-escaped `export KEY='value'` script to a mode-0600 temp
- *     file, and emits `. <tmp>; rm -f <tmp>` on stdout. Values reach bash
- *     only via the temp file, never via akm's stdout.
- *   - `injectIntoEnv(vaultPath, target)` — programmatic API for modules that
- *     need values in a process environment.
+ *   - `source "$(akm vault path vault:<name>)"` — direct shell loading path.
+ *   - `injectIntoEnv(vaultPath, target)` / `loadEnv(vaultPath)` — programmatic
+ *     APIs for modules that need values in process memory.
  *
  * Value parsing is delegated to the `dotenv` package — we deliberately do not
  * implement our own quoting/escaping rules for security-sensitive content.
@@ -19,6 +15,98 @@
 import fs from "node:fs";
 import path from "node:path";
 import dotenv from "dotenv";
+import { writeFileAtomic } from "../core/common";
+// ── Write-lock helper ─────────────────────────────────────────────────────────
+/**
+ * Acquire an exclusive lock file for the given vault path, execute `fn`, then
+ * release the lock.  Uses O_EXCL creation so two concurrent writers cannot
+ * both acquire the lock simultaneously (POSIX atomic guarantee).
+ *
+ * Retry strategy: if the lock is held we spin for up to 5 s, yielding via
+ * `Bun.sleepSync` when available (avoids burning 100 % CPU), otherwise falling
+ * back to a busy-wait counter.  After the deadline we throw rather than
+ * silently proceeding — a timeout here is always a programming error or a
+ * stale lock left by a crashed process.
+ *
+ * Stale lock detection: the current PID is written into the lock file on
+ * acquisition.  When a lock-acquire attempt fails, the PID stored in the
+ * existing lock file is read and tested with `process.kill(pid, 0)`.  If the
+ * signal call throws (ESRCH — no such process), the lock is stale and is
+ * deleted immediately so the next loop iteration can acquire it.  If the
+ * process is still alive the retry loop continues normally.
+ */
+function withVaultLock(vaultPath, fn) {
+    const lockPath = `${vaultPath}.lock`;
+    const deadline = Date.now() + 5000;
+    let fd = -1;
+    while (true) {
+        try {
+            fd = fs.openSync(lockPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o600);
+            // Write our PID so staleness can be detected by other waiters
+            fs.writeSync(fd, String(process.pid));
+            break;
+        }
+        catch {
+            if (Date.now() > deadline) {
+                throw new Error(`Could not acquire vault lock for ${vaultPath} after 5s. Is another process holding it?`);
+            }
+            // Check for stale lock: read PID and test if that process is alive
+            try {
+                const rawPid = fs.readFileSync(lockPath, "utf8").trim();
+                const pid = Number.parseInt(rawPid, 10);
+                if (!Number.isNaN(pid) && pid > 0) {
+                    try {
+                        process.kill(pid, 0); // throws ESRCH if process doesn't exist
+                        // PID is alive — legitimate holder, wait
+                    }
+                    catch {
+                        // Process is dead — stale lock, remove and retry immediately
+                        try {
+                            fs.unlinkSync(lockPath);
+                        }
+                        catch {
+                            /* ignore */
+                        }
+                        continue;
+                    }
+                }
+            }
+            catch {
+                /* lock file unreadable, keep waiting */
+            }
+            // Yield before next attempt
+            if (typeof globalThis.Bun
+                ?.sleepSync === "function") {
+                globalThis.Bun.sleepSync(10);
+            }
+            else {
+                let spin = 0;
+                while (spin++ < 100_000) {
+                    /* yield */
+                }
+            }
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        if (fd !== -1) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        try {
+            fs.unlinkSync(lockPath);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
 /** Matches a KEY=value assignment line, capturing only the key. */
 const ASSIGN_RE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
 /** Scan lines and return KEY names in file order, without duplicates. */
@@ -144,8 +232,7 @@ export function injectIntoEnv(vaultPath, target = process.env) {
  * non-assignment content, so sourcing the output is safe regardless of what
  * the vault file contains.
  *
- * Intended for use by `akm vault load`, which writes this to a mode-0600
- * temp file and emits only the path (never values) on stdout.
+ * Retained for programmatic callers/tests that need a literal export script.
  */
 export function buildShellExportScript(vaultPath) {
     const env = loadEnv(vaultPath);
@@ -180,91 +267,112 @@ export function buildShellExportScript(vaultPath) {
  */
 export function setKey(vaultPath, key, value, comment) {
     validateKeyName(key);
+    if (comment !== undefined && /[\r\n]/.test(comment)) {
+        throw new Error("Vault key comment cannot contain newline characters.");
+    }
     ensureParentDir(vaultPath);
-    const existing = fs.existsSync(vaultPath) ? fs.readFileSync(vaultPath, "utf8") : "";
-    const lines = existing.length > 0 ? existing.split(/\r?\n/) : [];
-    const formatted = `${key}=${quoteValue(value)}`;
-    let replaced = false;
-    for (let i = 0; i < lines.length; i++) {
-        const m = lines[i].match(ASSIGN_RE);
-        if (m && m[1] === key) {
-            lines[i] = formatted;
-            replaced = true;
+    withVaultLock(vaultPath, () => {
+        const existing = fs.existsSync(vaultPath) ? fs.readFileSync(vaultPath, "utf8") : "";
+        const lines = existing.length > 0 ? existing.split(/\r?\n/) : [];
+        const formatted = `${key}=${quoteValue(value)}`;
+        let replaced = false;
+        for (let i = 0; i < lines.length; i++) {
+            const m = lines[i].match(ASSIGN_RE);
+            if (m && m[1] === key) {
+                lines[i] = formatted;
+                replaced = true;
+                if (comment !== undefined) {
+                    const commentLine = `# ${comment}`;
+                    const prevIsComment = i > 0 && lines[i - 1].trimStart().startsWith("#");
+                    if (prevIsComment) {
+                        lines[i - 1] = commentLine;
+                    }
+                    else {
+                        lines.splice(i, 0, commentLine);
+                    }
+                }
+                break;
+            }
+        }
+        if (!replaced) {
             if (comment !== undefined) {
                 const commentLine = `# ${comment}`;
-                const prevIsComment = i > 0 && lines[i - 1].trimStart().startsWith("#");
-                if (prevIsComment) {
-                    lines[i - 1] = commentLine;
+                if (lines.length > 0 && lines[lines.length - 1] === "") {
+                    lines[lines.length - 1] = commentLine;
+                    lines.push(formatted);
+                    lines.push("");
                 }
                 else {
-                    lines.splice(i, 0, commentLine);
+                    lines.push(commentLine);
+                    lines.push(formatted);
                 }
             }
-            break;
-        }
-    }
-    if (!replaced) {
-        if (comment !== undefined) {
-            const commentLine = `# ${comment}`;
-            if (lines.length > 0 && lines[lines.length - 1] === "") {
-                lines[lines.length - 1] = commentLine;
-                lines.push(formatted);
+            else if (lines.length > 0 && lines[lines.length - 1] === "") {
+                lines[lines.length - 1] = formatted;
                 lines.push("");
             }
             else {
-                lines.push(commentLine);
                 lines.push(formatted);
             }
         }
-        else if (lines.length > 0 && lines[lines.length - 1] === "") {
-            lines[lines.length - 1] = formatted;
-            lines.push("");
-        }
-        else {
-            lines.push(formatted);
-        }
-    }
-    let out = lines.join("\n");
-    if (!out.endsWith("\n"))
-        out += "\n";
-    writeFileAtomic(vaultPath, out);
+        let out = lines.join("\n");
+        if (!out.endsWith("\n"))
+            out += "\n";
+        writeFileAtomic(vaultPath, out, 0o600);
+    });
 }
 /** Remove a key from the vault file. Returns true if the key was present. */
 export function unsetKey(vaultPath, key) {
     if (!fs.existsSync(vaultPath))
         return false;
-    const text = fs.readFileSync(vaultPath, "utf8");
-    const lines = text.split(/\r?\n/);
-    const kept = [];
-    let removed = false;
-    for (const line of lines) {
-        const m = line.match(ASSIGN_RE);
-        if (m && m[1] === key) {
-            removed = true;
-            continue;
+    return withVaultLock(vaultPath, () => {
+        const text = fs.readFileSync(vaultPath, "utf8");
+        const lines = text.split(/\r?\n/);
+        let keyLineIdx = -1;
+        for (let i = 0; i < lines.length; i++) {
+            const m = lines[i].match(ASSIGN_RE);
+            if (m && m[1] === key) {
+                keyLineIdx = i;
+                break;
+            }
         }
-        kept.push(line);
-    }
-    if (!removed)
-        return false;
-    let out = kept.join("\n");
-    if (out.length > 0 && !out.endsWith("\n"))
-        out += "\n";
-    writeFileAtomic(vaultPath, out);
-    return true;
+        if (keyLineIdx === -1)
+            return false;
+        // Determine how many consecutive comment lines immediately precede the key.
+        // We walk backwards, skipping only comment lines (lines matching /^\s*#/).
+        // A blank line between a comment and the key breaks the association — we
+        // stop at the first non-comment, non-assignment line (including blank lines).
+        let commentStart = keyLineIdx;
+        for (let i = keyLineIdx - 1; i >= 0; i--) {
+            if (/^\s*#/.test(lines[i])) {
+                commentStart = i;
+            }
+            else {
+                // Stop at the first non-comment line (blank or assignment)
+                break;
+            }
+        }
+        // Remove from commentStart through keyLineIdx (inclusive).
+        lines.splice(commentStart, keyLineIdx - commentStart + 1);
+        let out = lines.join("\n");
+        if (out.length > 0 && !out.endsWith("\n"))
+            out += "\n";
+        writeFileAtomic(vaultPath, out, 0o600);
+        return true;
+    });
 }
 /** Create an empty vault file (does nothing if it already exists). */
 export function createVault(vaultPath) {
     ensureParentDir(vaultPath);
     if (fs.existsSync(vaultPath))
         return;
-    writeFileAtomic(vaultPath, "");
+    writeFileAtomic(vaultPath, "", 0o600);
 }
 /**
  * Characters that are safe in an UNquoted dotenv value AND are not
  * metacharacters in POSIX shells. Anything outside this set forces quoting,
  * which is defense-in-depth for any caller that might ever `source` the
- * vault file directly instead of going through `akm vault load`.
+ * vault file directly instead of going through `akm vault path`.
  */
 const UNQUOTED_SAFE_RE = /^[A-Za-z0-9_.:/@%+,-]+$/;
 /**
@@ -307,27 +415,5 @@ function validateKeyName(key) {
 function ensureParentDir(filePath) {
     const dir = path.dirname(filePath);
     if (!fs.existsSync(dir))
-        fs.mkdirSync(dir, { recursive: true });
-}
-function writeFileAtomic(filePath, content) {
-    const tmp = `${filePath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
-    try {
-        fs.writeFileSync(tmp, content, { encoding: "utf8", mode: 0o600 });
-        fs.renameSync(tmp, filePath);
-        try {
-            fs.chmodSync(filePath, 0o600);
-        }
-        catch {
-            /* best-effort on platforms without chmod */
-        }
-    }
-    catch (err) {
-        try {
-            fs.unlinkSync(tmp);
-        }
-        catch {
-            /* ignore cleanup failure */
-        }
-        throw err;
-    }
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
 }

package/dist/core/action-contributors.js

@@ -0,0 +1,25 @@
+import { defaultRendererRegistry } from "./asset-registry";
+function registryActionContributor(registry) {
+    return {
+        name: "registry-action-contributor",
+        appliesTo(ctx) {
+            return registry.actionBuilderFor(ctx.type) !== undefined;
+        },
+        buildAction(ctx) {
+            return registry.actionBuilderFor(ctx.type)?.(ctx.ref);
+        },
+    };
+}
+export function defaultActionContributors(registry = defaultRendererRegistry) {
+    return [registryActionContributor(registry)];
+}
+export function buildActionFromContributors(ctx, contributors = defaultActionContributors()) {
+    for (const contributor of contributors) {
+        if (!contributor.appliesTo(ctx))
+            continue;
+        const action = contributor.buildAction(ctx);
+        if (action !== undefined)
+            return action;
+    }
+    return undefined;
+}

package/dist/core/asset-ref.js

@@ -67,6 +67,10 @@ function validateName(name) {
     if (normalized === ".." || normalized.startsWith("../")) {
         throw new UsageError("Path traversal in asset name.", "MISSING_REQUIRED_ARGUMENT");
     }
+    const segments = normalized.split("/");
+    if (segments.some((seg) => seg === "." || seg === "..")) {
+        throw new UsageError("Asset name cannot contain relative path segments.", "MISSING_REQUIRED_ARGUMENT");
+    }
 }
 function normalizeName(name) {
     return path.posix.normalize(name.replace(/\\/g, "/"));

package/dist/core/asset-registry.js

@@ -18,10 +18,12 @@ export const TYPE_TO_RENDERER = {
     command: "command-md",
     agent: "agent-md",
     knowledge: "knowledge-md",
+    lesson: "lesson-md",
     memory: "memory-md",
     workflow: "workflow-md",
     vault: "vault-env",
     wiki: "wiki-md",
+    task: "task-md",
 };
 /** Map asset types to action builder functions for search results. */
 export const ACTION_BUILDERS = {
@@ -30,10 +32,12 @@ export const ACTION_BUILDERS = {
     command: (ref) => `akm show ${ref} -> fill placeholders and dispatch`,
     agent: (ref) => `akm show ${ref} -> dispatch with full prompt`,
     knowledge: (ref) => `akm show ${ref} -> read reference material`,
+    lesson: (ref) => `akm show ${ref} -> read the lesson and apply when_to_use`,
     memory: (ref) => `akm show ${ref} -> recall context`,
     workflow: (ref) => buildWorkflowAction(ref),
-    vault: (ref) => `akm vault list ${ref} -> see key names; eval "$(akm vault load ${ref})" -> load values into the current shell (values never echoed)`,
+    vault: (ref) => `akm show ${ref} -> inspect keys; source "$(akm vault path ${ref})" -> load values; akm vault run ${ref} -- <command> -> run with injected env`,
     wiki: (ref) => `akm show ${ref} -> read the wiki page`,
+    task: (ref) => `akm tasks show ${ref.replace(/^task:/, "")} -> inspect; akm tasks run <id> -> run now; akm tasks remove <id> -> unschedule`,
 };
 /**
  * Register a type-to-renderer mapping.
@@ -61,19 +65,3 @@ export const defaultRendererRegistry = {
         return ACTION_BUILDERS[type];
     },
 };
-/**
- * Build a registry from explicit maps. Useful for tests that need to assert
- * rendering behavior without touching the global singletons.
- */
-export function createRendererRegistry(maps) {
-    const renderers = maps.renderers ?? {};
-    const actionBuilders = maps.actionBuilders ?? {};
-    return {
-        rendererNameFor(type) {
-            return renderers[type];
-        },
-        actionBuilderFor(type) {
-            return actionBuilders[type];
-        },
-    };
-}

package/dist/core/asset-spec.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { buildWorkflowAction } from "../output/renderers";
 import { registerActionBuilder, registerTypeRenderer } from "./asset-registry";
 import { toPosix } from "./common";
+const buildTaskAction = (ref) => `akm tasks show ${ref.replace(/^task:/, "")} -> inspect; akm tasks run <id> -> run now; akm tasks remove <id> -> unschedule`;
 const markdownSpec = {
     isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
     toCanonicalName: (typeRoot, filePath) => {
@@ -82,7 +83,7 @@ const ASSET_SPECS_INTERNAL = {
             return path.join(typeRoot, name.endsWith(".env") ? name : `${name}.env`);
         },
         rendererName: "vault-env",
-        actionBuilder: (ref) => `akm vault list ${ref} -> see key names; eval "$(akm vault load ${ref})" -> load values into the current shell (values never echoed)`,
+        actionBuilder: (ref) => `akm show ${ref} -> inspect keys; source "$(akm vault path ${ref})" -> load values; akm vault run ${ref} -- <command> -> run with injected env`,
     },
     wiki: {
         stashDir: "wikis",
@@ -102,6 +103,15 @@ const ASSET_SPECS_INTERNAL = {
         rendererName: "lesson-md",
         actionBuilder: (ref) => `akm show ${ref} -> read the lesson and apply when_to_use`,
     },
+    // Scheduled tasks. A task file pairs a cron-style schedule with a target
+    // (workflow ref or prompt) that `akm tasks` registers with the OS-native
+    // scheduler (cron / launchd / schtasks). Stored under <stash>/tasks/<id>.md.
+    task: {
+        stashDir: "tasks",
+        ...markdownSpec,
+        rendererName: "task-md",
+        actionBuilder: buildTaskAction,
+    },
 };
 export const ASSET_SPECS = ASSET_SPECS_INTERNAL;
 /**

package/dist/core/common.js

@@ -1,3 +1,4 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { TYPE_DIRS } from "./asset-spec";
@@ -8,6 +9,20 @@ export const IS_WINDOWS = process.platform === "win32";
 export function isHttpUrl(value) {
     return !!value && /^https?:\/\//.test(value);
 }
+/**
+ * Returns `true` when `value` looks like a remote URL that a VCS or HTTP
+ * fetch can access. Covers http/https, git@, ssh://, and git:// schemes.
+ * Consolidates the repeated inline URL-detection pattern in source-manage.ts.
+ */
+export function isRemoteUrl(value) {
+    if (!value)
+        return false;
+    return (value.startsWith("http://") ||
+        value.startsWith("https://") ||
+        value.startsWith("git@") ||
+        value.startsWith("ssh://") ||
+        value.startsWith("git://"));
+}
 export function filterNonEmptyStrings(value) {
     if (!Array.isArray(value))
         return undefined;
@@ -18,6 +33,23 @@ export function isAssetType(type) {
     return Object.hasOwn(TYPE_DIRS, type);
 }
 // ── Utilities ───────────────────────────────────────────────────────────────
+/**
+ * Write content to a file atomically via a temp file + rename.
+ * Prevents partial-write corruption on crash.
+ * The temp file is opened with the target `mode` (default 0o600) from the
+ * start, so it is never world-readable even briefly.
+ */
+export function writeFileAtomic(target, content, mode) {
+    const tmp = `${target}.tmp.${process.pid}.${crypto.randomBytes(8).toString("hex")}`;
+    const fd = fs.openSync(tmp, "w", mode ?? 0o600);
+    try {
+        fs.writeSync(fd, content);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.renameSync(tmp, target);
+}
 /**
  * Resolve the stash directory using a three-level fallback chain:
  *   1. AKM_STASH_DIR environment variable (override for CI/scripts)
@@ -329,3 +361,71 @@ function parseRetryAfter(response) {
 export function toErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+// ── Date / timestamp utilities ───────────────────────────────────────────────
+/**
+ * Return today's date in ISO-8601 format (`YYYY-MM-DD`).
+ * Consolidates the `new Date().toISOString().slice(0, 10)` pattern that
+ * appears at multiple call sites.
+ */
+export function todayIso() {
+    return new Date().toISOString().slice(0, 10);
+}
+/**
+ * Return a filesystem-safe timestamp string derived from the current instant.
+ * Colons and dots are replaced with hyphens so the result is safe as a
+ * filename component on all platforms (e.g. `2024-01-15T10-30-00-000Z`).
+ */
+export function timestampForFilename() {
+    return new Date().toISOString().replace(/[:.]/g, "-");
+}
+// ── String coercion ──────────────────────────────────────────────────────────
+/**
+ * Return the trimmed string value if non-empty, otherwise `undefined`.
+ * Consolidates `toStringOrUndefined` (frontmatter.ts), `asNonEmptyString`
+ * (config.ts), and `firstString` (memory-improve.ts) — all had the same
+ * "return a string or undefined" contract with minor semantic differences.
+ */
+export function asNonEmptyString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+// ── Generic data utilities ───────────────────────────────────────────────────
+/**
+ * Return the trimmed string if non-empty, otherwise `undefined`.
+ * Equivalent to `firstString` previously defined in `memory-improve.ts`.
+ */
+export function firstString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+/**
+ * Coerce an unknown value to a filtered, trimmed string array.
+ * Non-strings and empty/whitespace-only entries are dropped.
+ */
+export function stringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const item of value) {
+        if (typeof item === "string" && item.trim().length > 0)
+            out.push(item.trim());
+    }
+    return out;
+}
+/**
+ * Group an array of values by a string key derived from each element.
+ * Returns a `Map` so insertion order within each group is preserved.
+ */
+export function groupBy(values, keyFn) {
+    const groups = new Map();
+    for (const value of values) {
+        const key = keyFn(value);
+        const existing = groups.get(key);
+        if (existing)
+            existing.push(value);
+        else
+            groups.set(key, [value]);
+    }
+    return groups;
+}

package/dist/core/concurrent.js

@@ -0,0 +1,22 @@
+/**
+ * Maps over items concurrently with a pool size limit.
+ * Uses Promise.allSettled semantics — one failure does not cancel others.
+ */
+export async function concurrentMap(items, fn, concurrency = 1) {
+    const results = new Array(items.length).fill(undefined);
+    let nextIndex = 0;
+    async function worker() {
+        while (nextIndex < items.length) {
+            const i = nextIndex++;
+            try {
+                results[i] = await fn(items[i], i);
+            }
+            catch {
+                // individual failure: leave undefined, caller checks
+            }
+        }
+    }
+    const workers = Array.from({ length: Math.min(concurrency, items.length) }, worker);
+    await Promise.all(workers);
+    return results;
+}