akm-cli 0.7.5 → 0.8.0-rc1

package/dist/commands/tasks.js

@@ -0,0 +1,385 @@
+/**
+ * `akm tasks` — register, inspect, run, and remove scheduled task assets.
+ *
+ * Each handler exported here is a pure function that performs the real work;
+ * `src/cli.ts` wraps these in citty `defineCommand`s and shapes their return
+ * values via `output()`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseAssetRef } from "../core/asset-ref";
+import { resolveAssetPathFromName } from "../core/asset-spec";
+import { isWithin, resolveStashDir } from "../core/common";
+import { loadConfig } from "../core/config";
+import { ConfigError, NotFoundError, UsageError } from "../core/errors";
+import { getTaskHistoryDir, getTaskLogDir } from "../core/paths";
+import { listAgentProfileNames } from "../integrations/agent";
+import { resolveAssetPath } from "../sources/resolve";
+import { backendNameForPlatform, selectBackend } from "../tasks/backends";
+import { parseTaskDocument } from "../tasks/parser";
+import { resolveAkmInvocation } from "../tasks/resolveAkmBin";
+import { exitCodeForStatus, readTaskHistory, runTask } from "../tasks/runner";
+import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT, translateToCron } from "../tasks/schedule";
+import { validateTaskDocument } from "../tasks/validator";
+export async function akmTasksAdd(input) {
+    const id = normaliseTaskId(input.id);
+    if ((input.workflow && input.prompt) || (!input.workflow && !input.prompt)) {
+        throw new UsageError("Pass exactly one of --workflow <ref> or --prompt <inline|asset-ref|./file.md>.", "INVALID_FLAG_VALUE");
+    }
+    // Validate the schedule for the active backend before writing anything.
+    const backend = backendNameForPlatform();
+    parseSchedule(input.schedule, backend);
+    const stashDir = resolveStashDir();
+    const typeRoot = path.join(stashDir, "tasks");
+    fs.mkdirSync(typeRoot, { recursive: true });
+    const assetPath = resolveAssetPathFromName("task", typeRoot, id);
+    if (!isWithin(assetPath, typeRoot)) {
+        throw new UsageError(`Resolved task path escapes the stash: "${id}".`, "PATH_ESCAPE_VIOLATION");
+    }
+    if (fs.existsSync(assetPath) && !input.force) {
+        throw new UsageError(`Task "${id}" already exists. Pass --force to overwrite, or use \`akm tasks remove ${id}\` first.`, "RESOURCE_ALREADY_EXISTS");
+    }
+    const markdown = renderTaskMarkdown({
+        id,
+        schedule: input.schedule,
+        workflow: input.workflow,
+        prompt: input.prompt,
+        profile: input.profile,
+        params: input.params,
+        description: input.description,
+        tags: input.tags,
+        enabled: input.disabled !== true,
+    });
+    const task = parseTaskDocument({ markdown, filePath: assetPath, id });
+    await validateTaskDocument(task, { backend, stashDir });
+    fs.writeFileSync(assetPath, markdown.endsWith("\n") ? markdown : `${markdown}\n`, "utf8");
+    // Install in the OS scheduler. If install fails after the file was written,
+    // delete the file so the on-disk state never claims a task is registered
+    // when it isn't.
+    try {
+        const sched = selectBackend();
+        await sched.install(task);
+    }
+    catch (err) {
+        try {
+            fs.rmSync(assetPath, { force: true });
+        }
+        catch {
+            /* ignore */
+        }
+        throw err;
+    }
+    return {
+        id,
+        ref: `task:${id}`,
+        path: assetPath,
+        stashDir,
+        schedule: task.schedule,
+        enabled: task.enabled,
+        backend,
+        target: task.target,
+    };
+}
+export async function akmTasksList() {
+    const stashDir = resolveStashDir();
+    const typeRoot = path.join(stashDir, "tasks");
+    if (!fs.existsSync(typeRoot))
+        return { tasks: [] };
+    const files = fs.readdirSync(typeRoot).filter((f) => f.endsWith(".md"));
+    const tasks = [];
+    for (const file of files) {
+        const id = file.slice(0, -3);
+        const filePath = path.join(typeRoot, file);
+        let task;
+        try {
+            task = parseTaskDocument({ markdown: fs.readFileSync(filePath, "utf8"), filePath, id });
+        }
+        catch {
+            continue; // skip malformed files; `akm tasks show <id>` will surface the error
+        }
+        tasks.push({
+            id: task.id,
+            ref: `task:${task.id}`,
+            path: filePath,
+            schedule: task.schedule,
+            enabled: task.enabled,
+            target: task.target,
+            description: task.description,
+            tags: task.tags,
+        });
+    }
+    return { tasks };
+}
+export async function akmTasksShow(id) {
+    const normalised = normaliseTaskId(id);
+    const stashDir = resolveStashDir();
+    const filePath = await resolveAssetPath(stashDir, "task", normalised);
+    const task = parseTaskDocument({
+        markdown: fs.readFileSync(filePath, "utf8"),
+        filePath,
+        id: normalised,
+    });
+    const spec = parseSchedule(task.schedule, backendNameForPlatform());
+    return {
+        id: task.id,
+        ref: `task:${task.id}`,
+        path: filePath,
+        schedule: task.schedule,
+        cron: translateToCron(spec),
+        enabled: task.enabled,
+        target: task.target,
+        description: task.description,
+        tags: task.tags,
+    };
+}
+export async function akmTasksRemove(id) {
+    const normalised = normaliseTaskId(id);
+    const stashDir = resolveStashDir();
+    const filePath = await resolveAssetPath(stashDir, "task", normalised);
+    const sched = selectBackend();
+    try {
+        await sched.uninstall(normalised);
+    }
+    finally {
+        fs.rmSync(filePath, { force: true });
+    }
+    return { id: normalised, removed: true, backend: sched.name };
+}
+export async function akmTasksSetEnabled(id, enabled) {
+    const normalised = normaliseTaskId(id);
+    const stashDir = resolveStashDir();
+    const filePath = await resolveAssetPath(stashDir, "task", normalised);
+    const markdown = fs.readFileSync(filePath, "utf8");
+    const updated = setEnabledInMarkdown(markdown, enabled);
+    fs.writeFileSync(filePath, updated, "utf8");
+    const sched = selectBackend();
+    try {
+        await sched.setEnabled(normalised, enabled);
+    }
+    catch (err) {
+        // Roll the file back so the markdown source-of-truth and the OS
+        // scheduler don't diverge silently when the backend call fails.
+        fs.writeFileSync(filePath, markdown, "utf8");
+        throw err;
+    }
+    return { id: normalised, enabled, backend: sched.name };
+}
+export async function akmTasksRun(id) {
+    const normalised = normaliseTaskId(id);
+    const result = await runTask(normalised);
+    return {
+        ok: result.status === "completed" || result.status === "disabled",
+        result,
+        exitCode: exitCodeForStatus(result.status),
+    };
+}
+export async function akmTasksHistory(input) {
+    const limit = input.limit !== undefined && input.limit > 0 ? input.limit : 50;
+    const id = input.id ? normaliseTaskId(input.id) : undefined;
+    return { rows: readTaskHistory({ id, limit }) };
+}
+/**
+ * Reconcile the on-disk task files with the OS scheduler.
+ *   • install missing tasks (after validating them — invalid files are
+ *     skipped with a per-task reason rather than aborting the whole sync)
+ *   • remove orphan scheduler entries that no longer have a backing file
+ */
+export async function akmTasksSync() {
+    const stashDir = resolveStashDir();
+    const typeRoot = path.join(stashDir, "tasks");
+    const fileIds = fs.existsSync(typeRoot)
+        ? fs
+            .readdirSync(typeRoot)
+            .filter((f) => f.endsWith(".md"))
+            .map((f) => f.slice(0, -3))
+        : [];
+    const sched = selectBackend();
+    const backend = backendNameForPlatform();
+    const present = new Set((await sched.list()).map((t) => t.id));
+    const installed = [];
+    const unchanged = [];
+    const skipped = [];
+    for (const id of fileIds) {
+        const filePath = path.join(typeRoot, `${id}.md`);
+        let task;
+        try {
+            task = parseTaskDocument({ markdown: fs.readFileSync(filePath, "utf8"), filePath, id });
+        }
+        catch (err) {
+            skipped.push({ id, reason: err instanceof Error ? err.message : String(err) });
+            continue;
+        }
+        try {
+            await validateTaskDocument(task, { backend, stashDir });
+        }
+        catch (err) {
+            skipped.push({ id, reason: err instanceof Error ? err.message : String(err) });
+            continue;
+        }
+        if (present.has(id)) {
+            unchanged.push(id);
+        }
+        else {
+            await sched.install(task);
+            installed.push(id);
+        }
+    }
+    const removed = [];
+    for (const installedId of present) {
+        if (!fileIds.includes(installedId)) {
+            await sched.uninstall(installedId);
+            removed.push(installedId);
+        }
+    }
+    return { installed, removed, unchanged, skipped, backend: sched.name };
+}
+export async function akmTasksDoctor() {
+    const warnings = [];
+    let invocation = { argv: [], via: "unresolved" };
+    try {
+        const r = resolveAkmInvocation();
+        invocation = { argv: r.argv, via: r.via };
+    }
+    catch (err) {
+        warnings.push(err instanceof Error ? err.message : String(err));
+    }
+    const backend = backendNameForPlatform();
+    const config = loadConfig();
+    const defaultProfile = config.agent?.default;
+    const profiles = listAgentProfileNames(config.agent);
+    return {
+        backend,
+        akm: invocation,
+        logDir: getTaskLogDir(),
+        historyDir: getTaskHistoryDir(),
+        agent: { defaultProfile, available: profiles },
+        scheduleSubset: SCHEDULE_SUPPORTED_SUBSET_HINT,
+        warnings,
+    };
+}
+// ── helpers ─────────────────────────────────────────────────────────────────
+const VALID_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function normaliseTaskId(raw) {
+    const id = raw.trim().replace(/\.md$/, "");
+    if (!id) {
+        throw new UsageError("Task id must be non-empty.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    if (!VALID_ID_RE.test(id)) {
+        throw new UsageError(`Task id "${id}" is invalid. Use letters, digits, dots, underscores, and dashes only.`, "INVALID_FLAG_VALUE");
+    }
+    return id;
+}
+function renderTaskMarkdown(input) {
+    const lines = ["---"];
+    lines.push(`schedule: ${yamlQuote(input.schedule)}`);
+    if (input.workflow) {
+        lines.push(`workflow: ${yamlQuote(input.workflow)}`);
+        if (input.params) {
+            const parsed = parseJsonObjectArg(input.params);
+            lines.push("params:");
+            for (const [k, v] of Object.entries(parsed)) {
+                lines.push(`  ${k}: ${yamlScalarValue(v)}`);
+            }
+        }
+    }
+    else if (input.prompt) {
+        if (looksLikeAssetRef(input.prompt) || isFilePath(input.prompt) || input.prompt === "inline") {
+            lines.push(`prompt: ${yamlQuote(input.prompt)}`);
+        }
+        else {
+            lines.push(`prompt: inline`);
+        }
+        if (input.profile)
+            lines.push(`profile: ${yamlQuote(input.profile)}`);
+    }
+    lines.push(`enabled: ${input.enabled}`);
+    if (input.description)
+        lines.push(`description: ${yamlQuote(input.description)}`);
+    if (input.tags && input.tags.length > 0) {
+        lines.push(`tags: [${input.tags.map((t) => yamlQuote(t)).join(", ")}]`);
+    }
+    lines.push("---", "");
+    if (input.workflow) {
+        lines.push(`# Task: ${humanise(input.id)}`, "");
+    }
+    else if (input.prompt) {
+        if (looksLikeAssetRef(input.prompt) || isFilePath(input.prompt) || input.prompt === "inline") {
+            lines.push(`# Task: ${humanise(input.id)}`, "");
+        }
+        else {
+            // Raw inline prompt — use the body itself.
+            lines.push(input.prompt.trim(), "");
+        }
+    }
+    return lines.join("\n");
+}
+function yamlQuote(value) {
+    if (/^[A-Za-z_][A-Za-z0-9_.\-/:]*$/.test(value))
+        return value;
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function yamlScalarValue(v) {
+    if (typeof v === "string")
+        return yamlQuote(v);
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    if (v === null)
+        return "null";
+    return JSON.stringify(v);
+}
+function parseJsonObjectArg(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new UsageError("--params must be valid JSON.", "INVALID_JSON_ARGUMENT");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new UsageError("--params must be a JSON object.", "INVALID_JSON_ARGUMENT");
+    }
+    return parsed;
+}
+function looksLikeAssetRef(s) {
+    return /^[a-z][a-z0-9_-]*:[^\s]/i.test(s) && !s.startsWith("./") && !s.startsWith("/");
+}
+function isFilePath(s) {
+    return s.startsWith("./") || s.startsWith("../") || path.isAbsolute(s);
+}
+function humanise(id) {
+    return id.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+/**
+ * Toggle the `enabled:` value in a task markdown's frontmatter without doing
+ * a round-trip through the parser+renderer (which would lose comments and
+ * formatting choices). Inserts the key right before the closing `---` if
+ * absent.
+ */
+export function setEnabledInMarkdown(markdown, enabled) {
+    const m = markdown.match(/^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r\n|\r|\n|$))([\s\S]*)$/);
+    if (!m) {
+        throw new UsageError("Task markdown is missing frontmatter; cannot toggle enabled.", "INVALID_FLAG_VALUE");
+    }
+    const [, openFence, fmBody, closeFence, body] = m;
+    const replaced = fmBody.match(/(^|\r?\n)enabled:\s*[^\r\n]*/i)
+        ? fmBody.replace(/(^|\r?\n)enabled:\s*[^\r\n]*/i, `$1enabled: ${enabled}`)
+        : `${fmBody}\nenabled: ${enabled}`;
+    return `${openFence}${replaced}${closeFence}${body}`;
+}
+// Re-exported so tests can verify the validator path directly.
+// Re-export error classes consumed by callers that want to instanceof-check.
+// Re-export this so the CLI can decide what process exit code to use after
+// `akm tasks run` completes.
+export { ConfigError, exitCodeForStatus, NotFoundError, parseTaskDocument, UsageError };
+// Helper: ensure the asset-spec resolver agrees with our id rules. If the
+// user passes a ref, we accept the bare name part too.
+export function parseTaskRef(input) {
+    if (input.includes(":")) {
+        const ref = parseAssetRef(input);
+        if (ref.type !== "task") {
+            throw new UsageError(`Expected a task id or task:<id> ref, got "${input}".`, "INVALID_FLAG_VALUE");
+        }
+        return { id: normaliseTaskId(ref.name) };
+    }
+    return { id: normaliseTaskId(input) };
+}

package/dist/commands/url-checker.js

@@ -0,0 +1,39 @@
+const URL_RE = /https?:\/\/[^\s"'<>)\]]+/g;
+const TIMEOUT_MS = 5000;
+const MAX_URLS = 20;
+export async function checkDeadUrls(_stashDir, entries) {
+    const urlsToCheck = [];
+    for (const entry of entries) {
+        if (urlsToCheck.length >= MAX_URLS)
+            break;
+        const matches = entry.body.match(URL_RE) ?? [];
+        for (const url of matches.slice(0, 3)) {
+            urlsToCheck.push({ ref: entry.ref, url });
+            if (urlsToCheck.length >= MAX_URLS)
+                break;
+        }
+    }
+    const results = [];
+    await Promise.allSettled(urlsToCheck.map(async ({ ref, url }) => {
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+            const res = await fetch(url, {
+                method: "HEAD",
+                signal: controller.signal,
+                redirect: "follow",
+            });
+            clearTimeout(timer);
+            if (res.status >= 400) {
+                results.push({ ref, url, status: res.status });
+            }
+        }
+        catch (e) {
+            if (e.name === "AbortError") {
+                results.push({ ref, url, status: "timeout" });
+            }
+            // network errors (ENOTFOUND etc.) — skip, don't report as dead
+        }
+    }));
+    return results;
+}

package/dist/commands/vault.js

@@ -15,6 +15,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import dotenv from "dotenv";
+import { writeFileAtomic } from "../core/common";
 /** 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. */
@@ -222,7 +223,7 @@ export function setKey(vaultPath, key, value, comment) {
     let out = lines.join("\n");
     if (!out.endsWith("\n"))
         out += "\n";
-    writeFileAtomic(vaultPath, out);
+    writeFileAtomic(vaultPath, out, 0o600);
 }
 /** Remove a key from the vault file. Returns true if the key was present. */
 export function unsetKey(vaultPath, key) {
@@ -304,25 +305,3 @@ function ensureParentDir(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;
-    }
-}

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-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 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) => {
@@ -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

@@ -8,6 +8,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 +32,18 @@ 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.
+ * An optional `mode` (e.g. 0o600) is applied with `chmod` after the rename.
+ */
+export function writeFileAtomic(target, content, mode) {
+    const tmp = `${target}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+    fs.writeFileSync(tmp, content, "utf8");
+    fs.renameSync(tmp, target);
+    if (mode !== undefined)
+        fs.chmodSync(target, mode);
+}
 /**
  * Resolve the stash directory using a three-level fallback chain:
  *   1. AKM_STASH_DIR environment variable (override for CI/scripts)
@@ -329,3 +355,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;
+}