akm-cli 0.7.5 → 0.8.0-rc.6

package/dist/commands/vault.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/.
 /**
  * Vault asset type — secret storage backed by `.env` files.
  *
@@ -15,6 +18,57 @@
 import fs from "node:fs";
 import path from "node:path";
 import dotenv from "dotenv";
+import { writeFileAtomic } from "../core/common";
+import { probeLock, releaseLock, tryAcquireLockSync } from "../core/file-lock";
+// ── 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: PID is written into the lock file on acquisition
+ * and inspected via `probeLock` when a lock-acquire attempt fails.
+ */
+function withVaultLock(vaultPath, fn) {
+    const lockPath = `${vaultPath}.lock`;
+    const deadline = Date.now() + 5000;
+    while (!tryAcquireLockSync(lockPath, String(process.pid))) {
+        const probe = probeLock(lockPath);
+        if (probe.state === "stale") {
+            releaseLock(lockPath);
+            continue;
+        }
+        if (Date.now() > deadline) {
+            const holderHint = probe.state === "held"
+                ? ` Lock file ${lockPath} is held by live PID ${probe.holderPid}.`
+                : ` Lock file ${lockPath} could not be inspected.`;
+            throw new Error(`Could not acquire vault lock for ${vaultPath} after 5s.${holderHint} Retry once any other akm vault operation finishes, or remove the stale lock file.`);
+        }
+        // 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 {
+        releaseLock(lockPath);
+    }
+}
 /** 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. */
@@ -175,85 +229,106 @@ 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
@@ -302,27 +377,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,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 { 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

@@ -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 { isAssetType } from "./common";
 import { UsageError } from "./errors";
@@ -67,6 +70,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

@@ -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/.
 /**
  * Central registry for asset type renderer and action builder maps.
  *
@@ -18,10 +21,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-yaml",
 };
 /** Map asset types to action builder functions for search results. */
 export const ACTION_BUILDERS = {
@@ -30,10 +35,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 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 +68,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-serialize.js

@@ -0,0 +1,88 @@
+// 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/.
+/**
+ * Canonical asset-on-disk serialization.
+ *
+ * Before this module, 9+ call sites across `src/` independently reimplemented
+ * `yamlStringify(fm).trimEnd() + "---\n…\n---\n\n${body}"` to assemble a
+ * Markdown asset. The reimplementations drifted (different body normalization,
+ * different separator newlines, different trailing-newline policy), which is
+ * exactly the kind of silent format-shift the proposal-quality validators end
+ * up chasing downstream. This file is the single point of truth for
+ * "what does a well-formed AKM asset look like on disk".
+ *
+ * Two helpers are exported:
+ *   - `serializeFrontmatter(fm)` — YAML for the frontmatter block only, with
+ *     no `---` fences and no trailing newline. Single home for quoting style,
+ *     field-order policy, and trailing-whitespace rules.
+ *   - `assembleAsset(fm, body)` — frontmatter wrapped in `---` fences with a
+ *     blank line between the closing fence and the body, and exactly one
+ *     trailing `\n`. Single home for body normalization and the file-shape
+ *     contract.
+ *
+ * Contract (must hold for the dedup to be safe):
+ *   - Idempotent: `parseFrontmatter(assembleAsset(fm, body))` re-assembled
+ *     reproduces the same bytes.
+ *   - Field order: insertion order of `fm` is preserved (the caller controls
+ *     ordering; the helper never reorders).
+ *   - Quoting: `yaml.stringify` defaults — no custom quoting logic.
+ *   - Trailing newline: exactly one `\n` at end of output.
+ *   - Body normalization: leading newlines are stripped (`/^\n+/`). This
+ *     collapses the assorted `body.replace(/^\n+/, "")` /
+ *     `body.startsWith("\n") ? "" : "\n" + body` / bare `${body}` patterns
+ *     onto the most aggressive existing normalizer.
+ */
+import { stringify as yamlStringify } from "yaml";
+/**
+ * Serialize a frontmatter object to its on-disk YAML form, without `---`
+ * fences and without a trailing newline.
+ *
+ * Two calls with the same input produce byte-identical output. Field order is
+ * preserved from the input object's insertion order — callers control
+ * ordering, the helper never reorders.
+ */
+export function serializeFrontmatter(frontmatter) {
+    return yamlStringify(frontmatter).trimEnd();
+}
+/**
+ * Assemble a complete asset file string from a frontmatter object and a body.
+ *
+ * Output shape: `---\n<yaml>\n---\n\n<body>\n` where:
+ *   - `<yaml>` is `serializeFrontmatter(frontmatter)`.
+ *   - `<body>` has any leading `\n` characters stripped.
+ *   - Exactly one `\n` terminates the file.
+ *
+ * Idempotent under round-trip through the project's `parseFrontmatter`.
+ */
+export function assembleAsset(frontmatter, body) {
+    return assembleAssetFromString(serializeFrontmatter(frontmatter), body);
+}
+/**
+ * Same fence/body assembly as `assembleAsset` but takes a pre-serialized
+ * frontmatter string. Use this when a caller needs its own frontmatter
+ * serializer (e.g. defensive single-line flattening for untrusted LLM
+ * output, or JSON.stringify-per-value for guaranteed-quoted scalars) while
+ * still sharing the canonical fence-and-body template.
+ *
+ * The `serializedFm` argument must already match `serializeFrontmatter`'s
+ * contract: no `---` fences, no trailing newline. Trailing whitespace is
+ * trimmed defensively.
+ *
+ * Output contract — identical to `assembleAsset`:
+ *   - `---\n<serializedFm>\n---\n\n<body>\n`
+ *   - body has leading `\n` characters stripped
+ *   - exactly one `\n` terminates the file
+ *
+ * This helper is the single point of truth for the fence-and-body template.
+ * Three command surfaces (`reflect`, `distill`, `consolidate`) call it
+ * directly because their inputs are pre-validated LLM payloads where the
+ * full `yamlStringify` may emit shapes (`|`-block scalars, anchors) that
+ * the project's hand-rolled `parseFrontmatter` subset parser cannot read.
+ */
+export function assembleAssetFromString(serializedFm, body) {
+    const yaml = serializedFm.replace(/\s+$/, "");
+    const normalizedBody = body.replace(/^\n+/, "");
+    const withTrailingNewline = normalizedBody.endsWith("\n") ? normalizedBody : `${normalizedBody}\n`;
+    return `---\n${yaml}\n---\n\n${withTrailingNewline}`;
+}

package/dist/core/asset-spec.js

@@ -1,7 +1,11 @@
+// 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";
 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) => {
@@ -102,6 +106,24 @@ 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, 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",
+        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,
+    },
 };
 export const ASSET_SPECS = ASSET_SPECS_INTERNAL;
 /**

package/dist/core/common.js

@@ -1,3 +1,7 @@
+// 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";
@@ -8,6 +12,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 +36,56 @@ 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.
+ *
+ * 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}.${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);
+    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:
  *   1. AKM_STASH_DIR environment variable (override for CI/scripts)
@@ -329,3 +397,92 @@ 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.
+ */
+/**
+ * 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) {
+        const key = keyFn(value);
+        const existing = groups.get(key);
+        if (existing)
+            existing.push(value);
+        else
+            groups.set(key, [value]);
+    }
+    return groups;
+}