akm-cli 0.8.0-rc1 → 0.8.0

package/dist/core/asset-spec.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import path from "node:path";
 import { buildWorkflowAction } from "../output/renderers";
 import { registerActionBuilder, registerTypeRenderer } from "./asset-registry";
@@ -63,6 +66,34 @@ const ASSET_SPECS_INTERNAL = {
     },
     script: { stashDir: "scripts", ...scriptSpec },
     memory: { stashDir: "memories", ...markdownSpec },
+    // Environment assets — whole `.env` files sourced/injected wholesale. Replaces
+    // the deprecated `vault` type (see below). Key NAMES + start-of-line comments
+    // are surfaced as metadata; values are never read for indexing.
+    env: {
+        stashDir: "env",
+        isRelevantFile: (fileName) => fileName === ".env" || fileName.endsWith(".env"),
+        toCanonicalName: (typeRoot, filePath) => {
+            const rel = toPosix(path.relative(typeRoot, filePath));
+            const fileName = path.basename(rel);
+            // Treat ".env" as the "default" env; "<name>.env" → "<name>"
+            if (fileName === ".env") {
+                const dir = path.dirname(rel);
+                return dir === "." || dir === "" ? "default" : `${dir}/default`;
+            }
+            const stripped = rel.endsWith(".env") ? rel.slice(0, -4) : rel;
+            return stripped;
+        },
+        toAssetPath: (typeRoot, name) => {
+            if (name === "default")
+                return path.join(typeRoot, ".env");
+            return path.join(typeRoot, name.endsWith(".env") ? name : `${name}.env`);
+        },
+        rendererName: "env-file",
+        actionBuilder: (ref) => `akm show ${ref} -> inspect key names; akm env run ${ref} -- <command> -> run with the whole .env injected (values never reach stdout); akm env export ${ref} --out <file> -> write a sourceable script to a file`,
+    },
+    // DEPRECATED in 0.8.0, removed in 0.9.0 — use `env` instead. Retained so the
+    // frozen `vaults/` copy left by the migration still resolves and so existing
+    // `vault:` refs keep working through the deprecation window.
     vault: {
         stashDir: "vaults",
         isRelevantFile: (fileName) => fileName === ".env" || fileName.endsWith(".env"),
@@ -83,7 +114,23 @@ const ASSET_SPECS_INTERNAL = {
             return path.join(typeRoot, name.endsWith(".env") ? name : `${name}.env`);
         },
         rendererName: "vault-env",
-        actionBuilder: (ref) => `akm show ${ref} -> inspect keys; source "$(akm vault path ${ref})" -> load values; akm vault run ${ref} -- <command> -> run with injected env`,
+        actionBuilder: (ref) => `DEPRECATED (use env): akm show ${ref} -> inspect key names; akm env run ${ref} -- <command> -> run with injected env`,
+    },
+    // Secrets — a single sensitive value used on its own for authentication (a
+    // PEM key, API token, TLS cert). Unlike `env` (a group of related .env
+    // configuration), the ENTIRE file is the one secret value — there is no safe
+    // region to parse, so only the filename is ever surfaced as metadata. The
+    // value reaches a command only via `akm secret run` (injected into a child
+    // env var) or `akm secret path` (Docker `_FILE` convention). A secret is any
+    // regular file under `secrets/` except `.lock`/`.sensitive` sidecars; the
+    // canonical name preserves the natural filename (e.g. `id_rsa`, `team/deploy.key`).
+    secret: {
+        stashDir: "secrets",
+        isRelevantFile: (fileName) => !fileName.endsWith(".lock") && !fileName.endsWith(".sensitive"),
+        toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
+        toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
+        rendererName: "secret-file",
+        actionBuilder: (ref) => `akm show ${ref} -> name only (value never shown); akm secret path ${ref} -> file path; akm secret run ${ref} <VAR> -- <command> -> run with value injected into $VAR`,
     },
     wiki: {
         stashDir: "wikis",
@@ -104,12 +151,21 @@ const ASSET_SPECS_INTERNAL = {
         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.
+    // (workflow ref, prompt, or command) that `akm tasks` registers with the
+    // OS-native scheduler (cron / launchd / schtasks). Stored as pure YAML
+    // under <stash>/tasks/<id>.yml.
     task: {
         stashDir: "tasks",
-        ...markdownSpec,
-        rendererName: "task-md",
+        isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".yml",
+        toCanonicalName: (typeRoot, filePath) => {
+            const rel = toPosix(path.relative(typeRoot, filePath));
+            return rel.endsWith(".yml") ? rel.slice(0, -4) : rel;
+        },
+        toAssetPath: (typeRoot, name) => {
+            const withExt = name.endsWith(".yml") ? name : `${name}.yml`;
+            return path.join(typeRoot, withExt);
+        },
+        rendererName: "task-yaml",
         actionBuilder: buildTaskAction,
     },
 };

package/dist/core/common.js

@@ -1,8 +1,28 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { TYPE_DIRS } from "./asset-spec";
 import { ConfigError } from "./errors";
 import { getConfigPath, getDefaultStashDir } from "./paths";
+// ── Types ───────────────────────────────────────────────────────────────────
+export const ASSET_TYPES = [
+    "skill",
+    "command",
+    "agent",
+    "knowledge",
+    "workflow",
+    "script",
+    "memory",
+    "env",
+    "vault",
+    "secret",
+    "wiki",
+    "lesson",
+];
+export const ASSET_TYPE_SET = new Set(ASSET_TYPES);
 // ── Constants ───────────────────────────────────────────────────────────────
 export const IS_WINDOWS = process.platform === "win32";
 export function isHttpUrl(value) {
@@ -28,6 +48,15 @@ export function filterNonEmptyStrings(value) {
     return value.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
 }
 // ── Validators ──────────────────────────────────────────────────────────────
+/**
+ * Returns true if `type` is a known asset type — either a built-in from
+ * {@link ASSET_TYPES} or one dynamically registered via `registerAssetType`.
+ *
+ * The type guard narrows to `AkmAssetType` for all built-in types. Dynamic
+ * types (e.g. registered by plugins) are also accepted at runtime, but the
+ * type system treats them as `AkmAssetType` via assertion since they are not
+ * part of the static union.
+ */
 export function isAssetType(type) {
     return Object.hasOwn(TYPE_DIRS, type);
 }
@@ -35,14 +64,52 @@ export function isAssetType(type) {
 /**
  * Write content to a file atomically via a temp file + rename.
  * Prevents partial-write corruption on crash.
- * An optional `mode` (e.g. 0o600) is applied with `chmod` after the rename.
+ * The temp file is opened with the target `mode` (default 0o600) from the
+ * start, so it is never world-readable even briefly.
+ *
+ * Durability: fsync'd against the May 2026 config-clobber incident (#472).
+ * On ext4 (data=ordered) and NVMe-with-TRIM, a power-loss inside the kernel
+ * writeback window could leave the renamed file truncated to zero — defeating
+ * the purpose of the atomic rename. We:
+ *   1. fdatasync the temp fd before close, so the data is on disk before the
+ *      rename observes it.
+ *   2. fsync the parent directory after rename, so the directory entry change
+ *      is durable too. Some filesystems (FAT, certain FUSE mounts) don't
+ *      support directory fsync; we ignore EINVAL/ENOTSUP so atomic writes
+ *      don't fail on exotic mounts.
  */
 export function writeFileAtomic(target, content, mode) {
-    const tmp = `${target}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
-    fs.writeFileSync(tmp, content, "utf8");
+    const tmp = `${target}.tmp.${process.pid}.${crypto.randomBytes(8).toString("hex")}`;
+    const fd = fs.openSync(tmp, "w", mode ?? 0o600);
+    try {
+        fs.writeSync(fd, content);
+        try {
+            fs.fdatasyncSync(fd);
+        }
+        catch {
+            // Best-effort: some pseudo-filesystems lack fdatasync. Fall through
+            // to closeSync — the rename below still preserves atomicity even if
+            // the data isn't durable, and the calling code's retry will recover.
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
     fs.renameSync(tmp, target);
-    if (mode !== undefined)
-        fs.chmodSync(target, mode);
+    try {
+        const dirFd = fs.openSync(path.dirname(target), "r");
+        try {
+            fs.fsyncSync(dirFd);
+        }
+        finally {
+            fs.closeSync(dirFd);
+        }
+    }
+    catch {
+        // Directory fsync is unsupported on FAT, some FUSE mounts, and Windows
+        // (where directories cannot be opened for read like POSIX). Silently
+        // ignore so writeFileAtomic remains portable.
+    }
 }
 /**
  * Resolve the stash directory using a three-level fallback chain:
@@ -411,6 +478,27 @@ export function stringArray(value) {
  * Group an array of values by a string key derived from each element.
  * Returns a `Map` so insertion order within each group is preserved.
  */
+/**
+ * Return true if a process with the given PID is currently alive.
+ * Uses `process.kill(pid, 0)` which does not deliver a signal but
+ * throws ESRCH when the process does not exist.
+ */
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Convert a number of days to milliseconds. Consolidates the
+ * `N * 24 * 60 * 60 * 1000` pattern used throughout the cooldown logic.
+ */
+export function daysToMs(days) {
+    return days * 86_400_000;
+}
 export function groupBy(values, keyFn) {
     const groups = new Map();
     for (const value of values) {

package/dist/core/concurrent.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Maps over items concurrently with a pool size limit.
  * Uses Promise.allSettled semantics — one failure does not cancel others.

package/dist/core/config-io.js

@@ -0,0 +1,347 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Pure I/O helpers for AKM config files.
+ *
+ * No knowledge of the AkmConfig shape — these functions just read JSON(C) text
+ * from disk and write JSON text back atomically. Validation and migration live
+ * in `./config.ts` and `./config-migrate.ts`.
+ *
+ * Split out so the load path is testable without touching the filesystem
+ * (`parseConfigText` is pure), and so a single atomic write path serves
+ * `saveConfig`, the migrate command, and the setup wizard (#464.c).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { writeFileAtomic } from "./common";
+import { ConfigError } from "./errors";
+import { probeLock, releaseLock, tryAcquireLockSync } from "./file-lock";
+import { getCacheDir, getConfigDir } from "./paths";
+/**
+ * Read the raw text of a config file. Returns `undefined` when the file does
+ * not exist (legitimate cold-start). Other I/O errors propagate.
+ */
+export function readConfigText(configPath) {
+    try {
+        return fs.readFileSync(configPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+}
+/**
+ * Parse JSON(C) config text into a plain object. Strips `//` and `/* *​/`
+ * comments before parsing.
+ *
+ * Throws {@link ConfigError} when the text is unparseable or when the root is
+ * not a JSON object. Per #458, malformed config text is NOT silently rescued —
+ * the caller must surface the parse error.
+ */
+export function parseConfigText(text, sourcePath) {
+    const stripped = stripJsonComments(text);
+    const where = sourcePath ? ` at ${sourcePath}` : "";
+    let parsed;
+    try {
+        parsed = JSON.parse(stripped);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new ConfigError(`Failed to parse config JSON${where}: ${detail}`, "INVALID_CONFIG_FILE", "Edit the file to fix the JSON syntax error. Comments (// and /* */) are allowed; trailing commas are not.");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new ConfigError(`Config file${where} must contain a JSON object at the root, got ${describeJsonRoot(parsed)}.`, "INVALID_CONFIG_FILE");
+    }
+    return parsed;
+}
+function describeJsonRoot(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    if (typeof value === "string")
+        return "a string";
+    if (typeof value === "number")
+        return "a number";
+    if (typeof value === "boolean")
+        return "a boolean";
+    return typeof value;
+}
+/**
+ * Atomically write a config object to disk as pretty-printed JSON. Routes
+ * through {@link writeFileAtomic} so partial writes can never corrupt the
+ * config file (#464.c).
+ */
+export function writeConfigAtomic(configPath, config) {
+    writeFileAtomic(configPath, `${JSON.stringify(config, null, 2)}\n`);
+}
+/** Maximum number of timestamped config backups to retain (#459). */
+const MAX_CONFIG_BACKUPS = 5;
+/**
+ * Snapshot the current config file to `<cacheDir>/config-backups/`. Writes
+ * both a timestamped copy and a `config.latest.json` pointer, then prunes the
+ * timestamped set to {@link MAX_CONFIG_BACKUPS} most-recent entries.
+ *
+ * No-op when the source file does not exist (cold-start safe).
+ */
+export function backupExistingConfig(configPath) {
+    if (!fs.existsSync(configPath))
+        return;
+    const backupDir = path.join(getCacheDir(), "config-backups");
+    fs.mkdirSync(backupDir, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[.:]/g, "-");
+    fs.copyFileSync(configPath, path.join(backupDir, `config-${timestamp}.json`));
+    fs.copyFileSync(configPath, path.join(backupDir, "config.latest.json"));
+    pruneOldBackups(backupDir);
+}
+function pruneOldBackups(backupDir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(backupDir);
+    }
+    catch {
+        return;
+    }
+    const timestamped = entries
+        .filter((n) => n.startsWith("config-") && n.endsWith(".json") && n !== "config.latest.json")
+        .map((name) => {
+        const full = path.join(backupDir, name);
+        let mtime = 0;
+        try {
+            mtime = fs.statSync(full).mtimeMs;
+        }
+        catch {
+            // Unreadable — sorts to the end via mtime 0.
+        }
+        return { path: full, mtime };
+    })
+        .sort((a, b) => b.mtime - a.mtime);
+    for (const stale of timestamped.slice(MAX_CONFIG_BACKUPS)) {
+        try {
+            fs.unlinkSync(stale.path);
+        }
+        catch {
+            // Best-effort prune; next save will retry.
+        }
+    }
+}
+// ── Config write lock ────────────────────────────────────────────────────────
+/**
+ * Path to the config write sentinel (`config.json.lck` in $CONFIG).
+ *
+ * Placed next to config.json so the lock scope is obvious and the path is
+ * predictable for debugging. Uses $CONFIG (not $DATA) because config.json
+ * itself lives in $CONFIG — they should fail together if the dir is read-only.
+ */
+function getConfigLockPath() {
+    return path.join(getConfigDir(), "config.json.lck");
+}
+const CONFIG_LOCK_MAX_RETRIES = 10;
+const CONFIG_LOCK_RETRY_DELAY_MS = 50;
+/**
+ * Acquire an exclusive sentinel around config writes.
+ *
+ * Returns a release function. Best-effort: when all retries are exhausted the
+ * write proceeds unlocked rather than erroring (same posture as lockfile.ts).
+ */
+export function acquireConfigLock() {
+    const lockPath = getConfigLockPath();
+    try {
+        fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    }
+    catch {
+        // Directory already exists or unwritable — let the write fail naturally.
+    }
+    for (let attempt = 0; attempt < CONFIG_LOCK_MAX_RETRIES; attempt++) {
+        try {
+            if (tryAcquireLockSync(lockPath, String(process.pid))) {
+                return () => releaseLock(lockPath);
+            }
+        }
+        catch {
+            // Non-EEXIST error (permissions, etc.) — bail out and proceed unlocked.
+            break;
+        }
+        if (probeLock(lockPath).state === "stale") {
+            releaseLock(lockPath);
+            continue; // Reclaimed — retry immediately.
+        }
+        if (attempt < CONFIG_LOCK_MAX_RETRIES - 1) {
+            // Busy spin (synchronous) — config writes are fast.
+            const deadline = Date.now() + CONFIG_LOCK_RETRY_DELAY_MS;
+            while (Date.now() < deadline) {
+                // spin
+            }
+        }
+    }
+    // Best-effort: proceed without lock.
+    return () => { };
+}
+/**
+ * Run `fn` inside the config write lock. Always releases the lock.
+ */
+export function withConfigLock(fn) {
+    const release = acquireConfigLock();
+    try {
+        return fn();
+    }
+    finally {
+        release();
+    }
+}
+// ── Unified diff helper ──────────────────────────────────────────────────────
+/**
+ * Produce a minimal unified diff between `before` and `after` text.
+ * Uses LCS-based diff with 2-line context. Returns an empty string when the
+ * inputs are identical. `label` is used as the path in the diff header.
+ *
+ * Designed for config files (typically < 200 lines). O(m*n) in line count.
+ */
+export function unifiedDiff(before, after, label) {
+    if (before === after)
+        return "";
+    const a = before.split("\n");
+    const b = after.split("\n");
+    const eqPairs = lcsLinePairs(a, b);
+    const CONTEXT = 2;
+    const ops = [];
+    let ai = 0;
+    let bi = 0;
+    let pi = 0;
+    while (ai < a.length || bi < b.length) {
+        const eq = eqPairs[pi];
+        if (eq && eq.ai === ai && eq.bi === bi) {
+            ops.push({ type: "eq", line: a[ai], ai, bi });
+            ai++;
+            bi++;
+            pi++;
+        }
+        else if (ai < a.length && (!eq || ai < eq.ai)) {
+            ops.push({ type: "del", line: a[ai], ai, bi });
+            ai++;
+        }
+        else {
+            ops.push({ type: "add", line: b[bi], ai, bi });
+            bi++;
+        }
+    }
+    // Find changed op indices
+    const changed = new Set(ops.map((o, i) => (o.type !== "eq" ? i : -1)).filter((i) => i >= 0));
+    if (changed.size === 0)
+        return "";
+    // Determine which equal lines to include as context
+    const include = new Set();
+    for (const ci of changed) {
+        for (let k = Math.max(0, ci - CONTEXT); k <= Math.min(ops.length - 1, ci + CONTEXT); k++) {
+            include.add(k);
+        }
+    }
+    // Collect hunks
+    const header = [`--- ${label} (before)`, `+++ ${label} (after)`];
+    const out = [];
+    let hunkOps = [];
+    let prevIncluded = false;
+    function flushHunk() {
+        if (hunkOps.length === 0)
+            return;
+        const delStart = hunkOps.find((o) => o.type !== "add")?.ai ?? 0;
+        const addStart = hunkOps.find((o) => o.type !== "del")?.bi ?? 0;
+        const countA = hunkOps.filter((o) => o.type !== "add").length;
+        const countB = hunkOps.filter((o) => o.type !== "del").length;
+        out.push(`@@ -${delStart + 1},${countA} +${addStart + 1},${countB} @@`);
+        for (const op of hunkOps) {
+            const ch = op.type === "eq" ? " " : op.type === "del" ? "-" : "+";
+            out.push(`${ch}${op.line}`);
+        }
+        hunkOps = [];
+    }
+    for (let k = 0; k < ops.length; k++) {
+        if (include.has(k)) {
+            hunkOps.push(ops[k]);
+            prevIncluded = true;
+        }
+        else if (prevIncluded) {
+            flushHunk();
+            prevIncluded = false;
+        }
+    }
+    flushHunk();
+    return out.length > 0 ? [...header, ...out].join("\n") : "";
+}
+function lcsLinePairs(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0 || n === 0)
+        return [];
+    const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] + 1 : Math.max(dp[i - 1][j], dp[i][j - 1]);
+        }
+    }
+    const result = [];
+    let i = m;
+    let j = n;
+    while (i > 0 && j > 0) {
+        if (a[i - 1] === b[j - 1]) {
+            result.unshift({ ai: i - 1, bi: j - 1 });
+            i--;
+            j--;
+        }
+        else if (dp[i - 1][j] > dp[i][j - 1]) {
+            i--;
+        }
+        else {
+            j--;
+        }
+    }
+    return result;
+}
+/**
+ * Strip JavaScript-style comments from a JSON string (JSONC support).
+ * Handles `//` line comments and `/* *​/` block comments while preserving
+ * comment-like sequences inside quoted strings.
+ */
+export function stripJsonComments(text) {
+    let result = "";
+    let i = 0;
+    let inString = false;
+    while (i < text.length) {
+        if (inString) {
+            if (text[i] === "\\") {
+                result += text[i] + (text[i + 1] ?? "");
+                i += 2;
+                continue;
+            }
+            if (text[i] === '"') {
+                inString = false;
+            }
+            result += text[i];
+            i++;
+            continue;
+        }
+        if (text[i] === '"') {
+            inString = true;
+            result += text[i];
+            i++;
+            continue;
+        }
+        if (text[i] === "/" && text[i + 1] === "/") {
+            while (i < text.length && text[i] !== "\n")
+                i++;
+            continue;
+        }
+        if (text[i] === "/" && text[i + 1] === "*") {
+            i += 2;
+            while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
+                i++;
+            i += 2;
+            continue;
+        }
+        result += text[i];
+        i++;
+    }
+    return result;
+}