akm-cli 0.1.3 → 0.2.1

package/dist/setup.js

@@ -6,8 +6,11 @@
  * Collects all choices and writes config once at the end.
  */
 import * as p from "@clack/prompts";
+import { isHttpUrl } from "./common";
 import { DEFAULT_CONFIG, getConfigPath, loadConfig, saveConfig } from "./config";
+import { closeDatabase, isVecAvailable, openDatabase } from "./db";
 import { detectAgentPlatforms, detectOllama, detectOpenViking } from "./detect";
+import { checkEmbeddingAvailability, DEFAULT_LOCAL_MODEL, isTransformersAvailable } from "./embedder";
 import { akmIndex } from "./indexer";
 import { akmInit } from "./init";
 import { getDefaultStashDir } from "./paths";
@@ -20,6 +23,11 @@ const RECOMMENDED_GITHUB_REPOS = [
         hint: "community knowledge",
     },
 ];
+// Approximate first-download sizes used in the setup note.
+// LOCAL_MODEL_APPROX_SIZE_MB tracks the default local model (DEFAULT_LOCAL_MODEL).
+const LOCAL_MODEL_APPROX_SIZE_MB = 130;
+// SQLITE_VEC_APPROX_SIZE_MB reflects the optional sqlite-vec install footprint.
+const SQLITE_VEC_APPROX_SIZE_MB = 5;
 // ── Helpers ─────────────────────────────────────────────────────────────────
 function bail() {
     p.cancel("Setup cancelled. No changes were saved.");
@@ -70,6 +78,112 @@ async function promptOrBack(fn) {
         return null;
     return result;
 }
+function isRemoteEmbeddingConfig(embedding) {
+    return isHttpUrl(embedding?.endpoint);
+}
+/**
+ * @internal Exported for testing only.
+ */
+export function describeSemanticSearchAssets(embedding) {
+    if (isRemoteEmbeddingConfig(embedding)) {
+        return [
+            `• Embedding endpoint: ${embedding?.provider ?? "custom"} / ${embedding?.model} (no local model download)`,
+            `• sqlite-vec acceleration: optional native extension (~${SQLITE_VEC_APPROX_SIZE_MB} MB when installed separately)`,
+        ];
+    }
+    return [
+        `• Local embedding model: ${embedding?.localModel ?? DEFAULT_LOCAL_MODEL} (~${LOCAL_MODEL_APPROX_SIZE_MB} MB download on first use)`,
+        `• sqlite-vec acceleration: optional native extension (~${SQLITE_VEC_APPROX_SIZE_MB} MB when installed separately)`,
+    ];
+}
+export async function stepSemanticSearch(current, embedding) {
+    const enabled = await prompt(() => p.confirm({
+        message: "Enable semantic search?",
+        initialValue: current.semanticSearch,
+    }));
+    if (!enabled) {
+        return { enabled: false, prepareAssets: false };
+    }
+    p.note(describeSemanticSearchAssets(embedding).join("\n"), "Semantic Search Assets");
+    const prepareAssets = await prompt(() => p.confirm({
+        message: isRemoteEmbeddingConfig(embedding)
+            ? "Check the embedding endpoint and verify semantic search now?"
+            : "Download and verify semantic-search assets now?",
+        initialValue: true,
+    }));
+    return { enabled: true, prepareAssets };
+}
+async function prepareSemanticSearchAssets(config) {
+    const remote = isRemoteEmbeddingConfig(config.embedding);
+    // For local embeddings, ensure the required package is installed first.
+    if (!remote) {
+        if (!(await isTransformersAvailable())) {
+            const spin = p.spinner();
+            spin.start("Installing @huggingface/transformers...");
+            try {
+                const proc = Bun.spawn(["bun", "add", "@huggingface/transformers"], {
+                    stdout: "pipe",
+                    stderr: "pipe",
+                });
+                await proc.exited;
+                if (proc.exitCode !== 0) {
+                    const stderr = await new Response(proc.stderr).text();
+                    throw new Error(stderr || `exit code ${proc.exitCode}`);
+                }
+                spin.stop("@huggingface/transformers installed.");
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                spin.stop("Could not install @huggingface/transformers.");
+                p.log.warn(`Automatic install failed: ${msg}\n` +
+                    "Install it manually with: bun add @huggingface/transformers\n" +
+                    "Then re-run `akm setup` or `akm index --full --verbose`.");
+                return false;
+            }
+        }
+    }
+    const spin = p.spinner();
+    spin.start(remote
+        ? "Checking remote embedding endpoint..."
+        : `Downloading local embedding model (${config.embedding?.localModel ?? DEFAULT_LOCAL_MODEL})...`);
+    const result = await checkEmbeddingAvailability(config.embedding);
+    if (!result.available) {
+        spin.stop("Semantic-search assets could not be prepared.");
+        if (result.reason === "remote-unreachable") {
+            p.log.warn("The remote embedding endpoint is not reachable. Check your endpoint and credentials, then retry `akm index --full --verbose`.");
+        }
+        else if (result.reason === "missing-package") {
+            p.log.warn("@huggingface/transformers is not installed. Install it with: bun add @huggingface/transformers\n" +
+                "Then re-run `akm setup` or `akm index --full --verbose`.");
+        }
+        else {
+            p.log.warn(`The local embedding model could not be downloaded: ${result.message}\n` +
+                "Retry `akm index --full --verbose` after confirming local model downloads are permitted.");
+        }
+        return false;
+    }
+    spin.stop(remote ? "Remote embedding endpoint is ready." : "Local embedding model downloaded and ready.");
+    let db;
+    try {
+        db = openDatabase();
+        if (isVecAvailable(db)) {
+            p.log.info("sqlite-vec is available for fast vector search.");
+        }
+        else {
+            p.log.info("sqlite-vec is not available. Semantic search will use the JS fallback until the optional extension is installed.");
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        p.log.warn(`Could not open the local database or check for sqlite-vec. Semantic search will use the JS fallback. (${message})\n` +
+            "Check file permissions and available disk space in the cache directory, or run `akm index --full --verbose` to diagnose.");
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+    return true;
+}
 // ── Steps ───────────────────────────────────────────────────────────────────
 async function stepStashDir(current) {
     const defaultDir = current.stashDir ?? getDefaultStashDir();
@@ -431,14 +545,17 @@ export async function runSetupWizard() {
     // Step 2: Ollama / Embedding / LLM
     p.log.step("Step 2: Embedding & LLM");
     const { embedding, llm } = await stepOllama(current);
-    // Step 3: Registries
-    p.log.step("Step 3: Registries");
+    // Step 3: Semantic search assets
+    p.log.step("Step 3: Semantic Search");
+    const semanticSearch = await stepSemanticSearch(current, embedding);
+    // Step 4: Registries
+    p.log.step("Step 4: Registries");
     const registries = await stepRegistries(current);
-    // Step 4: Stash sources
-    p.log.step("Step 4: Stash Sources");
+    // Step 5: Stash sources
+    p.log.step("Step 5: Stash Sources");
     const stashes = await stepStashSources(current);
-    // Step 5: Agent platform detection
-    p.log.step("Step 5: Agent Platform Detection");
+    // Step 6: Agent platform detection
+    p.log.step("Step 6: Agent Platform Detection");
     const platformStashes = await stepAgentPlatforms(current);
     // Merge platform stashes into main stashes list
     const allStashes = [...stashes];
@@ -456,7 +573,7 @@ export async function runSetupWizard() {
         registries,
         stashes: allStashes.length > 0 ? allStashes : undefined,
         // Preserve existing fields
-        semanticSearch: current.semanticSearch,
+        semanticSearch: semanticSearch.enabled,
         installed: current.installed,
         output: current.output,
     };
@@ -466,6 +583,7 @@ export async function runSetupWizard() {
         `Stash directory:  ${stashDir}`,
         `Embedding:        ${embedding ? `${embedding.provider ?? "remote"} / ${embedding.model}` : "built-in local"}`,
         `LLM:              ${llm ? `${llm.provider ?? "remote"} / ${llm.model}` : "disabled"}`,
+        `Semantic search:  ${semanticSearch.enabled ? "enabled" : "disabled"}`,
         `Registries:       ${effectiveRegistries.filter((r) => r.enabled !== false).length} enabled`,
         `Stash sources:    ${allStashes.length}`,
     ].join("\n"), "Configuration Summary");
@@ -479,12 +597,38 @@ export async function runSetupWizard() {
     saveConfig(newConfig);
     // Initialize stash directory
     await akmInit({ dir: stashDir });
+    if (semanticSearch.enabled) {
+        if (semanticSearch.prepareAssets) {
+            const ready = await prepareSemanticSearchAssets(newConfig);
+            if (!ready) {
+                // Asset preparation failed: disable semantic search and persist the update.
+                newConfig.semanticSearch = false;
+                saveConfig(newConfig);
+                p.log.warn("Semantic search has been disabled in the saved configuration. Re-run `akm setup` or `akm index --full --verbose` once the issue is resolved.");
+            }
+        }
+        else {
+            p.log.info("Semantic search will be enabled, but asset preparation was skipped. Run `akm index --full --verbose` later to verify it.");
+        }
+    }
     // Build search index
+    p.log.info("Building search index...");
     const spin = p.spinner();
     spin.start("Building search index...");
     try {
         const indexResult = await akmIndex({ stashDir });
         spin.stop(`Indexed ${indexResult.totalEntries} assets.`);
+        if (newConfig.semanticSearch) {
+            if (indexResult.verification.ok) {
+                p.log.success(indexResult.verification.message);
+            }
+            else {
+                p.log.warn(indexResult.verification.message);
+                if (indexResult.verification.guidance) {
+                    p.log.info(indexResult.verification.guidance);
+                }
+            }
+        }
     }
     catch (err) {
         spin.stop("Indexing failed — you can run `akm index` manually later.");

package/dist/stash-clone.js

@@ -98,7 +98,9 @@ export async function akmClone(options) {
     }
     else {
         const resolvedSource = path.resolve(sourcePath);
-        const resolvedDest = path.resolve(path.join(destRoot, typeDir, destName));
+        const sourceExt = path.extname(sourcePath);
+        const effectiveDestName = !path.extname(destName) && sourceExt ? destName + sourceExt : destName;
+        const resolvedDest = path.resolve(path.join(destRoot, typeDir, effectiveDestName));
         if (resolvedSource === resolvedDest) {
             throw new Error(`Source and destination are the same path. Use --name to provide a new name for the clone.`);
         }

package/dist/stash-provider-factory.js

@@ -26,8 +26,6 @@ export function resolveStashProviders(config) {
     for (const entry of config.stashes ?? []) {
         if (entry.enabled === false)
             continue;
-        if (entry.type === "filesystem")
-            continue;
         const factory = registry.resolve(entry.type);
         if (factory) {
             providers.push(factory(entry));

package/dist/stash-providers/filesystem.js

@@ -8,21 +8,20 @@ class FilesystemStashProvider {
     type = "filesystem";
     name;
     stashDir;
-    config;
     constructor(entry) {
-        this.config = loadConfig();
         this.stashDir = entry.path ?? resolveStashDir();
         this.name = entry.name ?? this.stashDir;
     }
     async search(options) {
-        const sources = resolveStashSources(this.stashDir, this.config);
+        const config = loadConfig();
+        const sources = resolveStashSources(this.stashDir, config);
         const result = await searchLocal({
             query: options.query.toLowerCase(),
             searchType: options.type ?? "any",
             limit: options.limit,
             stashDir: this.stashDir,
             sources,
-            config: this.config,
+            config,
         });
         return {
             hits: result.hits,
@@ -35,7 +34,7 @@ class FilesystemStashProvider {
         return showLocal({ ref, view });
     }
     canShow(ref) {
-        return !ref.trim().startsWith("viking://");
+        return !ref.includes("://");
     }
 }
 // ── Self-register ───────────────────────────────────────────────────────────

package/dist/stash-providers/git.js

@@ -0,0 +1,140 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fetchWithRetry } from "../common";
+import { ConfigError } from "../errors";
+import { getRegistryIndexCacheDir } from "../paths";
+import { extractTarGzSecure } from "../registry-install";
+import { registerStashProvider } from "../stash-provider-factory";
+import { isExpired, sanitizeString } from "./provider-utils";
+/** Cache TTL before refreshing the mirrored repo (12 hours). */
+const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
+/** Maximum stale age allowed when refresh fails (7 days). */
+const CACHE_STALE_MS = 7 * 24 * 60 * 60 * 1000;
+class GitStashProvider {
+    type = "git";
+    name;
+    constructor(config) {
+        this.name = config.name ?? "git";
+    }
+    /** Content is indexed through the standard FTS5 pipeline. */
+    async search(_options) {
+        return { hits: [] };
+    }
+    /** Content is local files, shown via showLocal. */
+    async show(_ref, _view) {
+        throw new Error("Git provider content is shown via local index");
+    }
+    /** Content is local; no remote show needed. */
+    canShow(_ref) {
+        return false;
+    }
+}
+// ── Self-register ───────────────────────────────────────────────────────────
+registerStashProvider("git", (config) => new GitStashProvider(config));
+registerStashProvider("context-hub", (config) => new GitStashProvider(config));
+registerStashProvider("github", (config) => new GitStashProvider(config));
+// ── Cache management ────────────────────────────────────────────────────────
+function getCachePaths(repoUrl) {
+    const key = createHash("sha256").update(repoUrl).digest("hex").slice(0, 16);
+    const rootDir = path.join(getRegistryIndexCacheDir(), `context-hub-${key}`);
+    return {
+        rootDir,
+        archivePath: path.join(rootDir, "repo.tar.gz"),
+        repoDir: path.join(rootDir, "repo"),
+        indexPath: path.join(rootDir, "index.json"),
+    };
+}
+async function ensureGitMirror(repo, cachePaths, options) {
+    const requireRepoDir = options?.requireRepoDir === true;
+    // Check if cache is fresh
+    let mtime = 0;
+    try {
+        mtime = fs.statSync(cachePaths.indexPath).mtimeMs;
+    }
+    catch {
+        /* no cached index */
+    }
+    if (mtime && !isExpired(mtime, CACHE_TTL_MS) && (!requireRepoDir || hasExtractedRepo(cachePaths.repoDir))) {
+        return;
+    }
+    try {
+        fs.mkdirSync(cachePaths.rootDir, { recursive: true });
+        await downloadArchive(buildTarballUrl(repo), cachePaths.archivePath);
+        extractTarGzSecure(cachePaths.archivePath, cachePaths.repoDir);
+        // Touch index file to track freshness
+        fs.writeFileSync(cachePaths.indexPath, "[]", { encoding: "utf8", mode: 0o600 });
+    }
+    catch (err) {
+        if (mtime && !isExpired(mtime, CACHE_STALE_MS) && (!requireRepoDir || hasExtractedRepo(cachePaths.repoDir))) {
+            return;
+        }
+        throw err;
+    }
+}
+function hasExtractedRepo(repoDir) {
+    try {
+        return fs.statSync(repoDir).isDirectory() && fs.statSync(path.join(repoDir, "content")).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function downloadArchive(url, destination) {
+    const response = await fetchWithRetry(url, undefined, { timeout: 120_000, retries: 1 });
+    if (!response.ok) {
+        throw new Error(`Failed to download archive (${response.status}) from ${url}`);
+    }
+    const BunRuntime = globalThis.Bun;
+    if (BunRuntime?.write) {
+        await BunRuntime.write(destination, response);
+        return;
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    fs.writeFileSync(destination, Buffer.from(arrayBuffer));
+}
+function buildTarballUrl(repo) {
+    return `https://github.com/${repo.owner}/${repo.repo}/archive/refs/heads/${repo.ref}.tar.gz`;
+}
+function parseGitRepoUrl(rawUrl) {
+    if (!rawUrl) {
+        throw new ConfigError("Git provider requires a GitHub repository URL");
+    }
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        throw new ConfigError(`Git provider URL is not valid: "${rawUrl}"`);
+    }
+    if (parsed.protocol !== "https:") {
+        throw new ConfigError(`Git provider URL must use https://, got "${parsed.protocol}"`);
+    }
+    if (parsed.hostname !== "github.com") {
+        throw new ConfigError(`Git provider only supports github.com URLs, got "${parsed.hostname}"`);
+    }
+    const segments = parsed.pathname.split("/").filter(Boolean);
+    if (segments.length < 2) {
+        throw new ConfigError(`Git provider URL must point to a GitHub repository, got "${rawUrl}"`);
+    }
+    const owner = sanitizeString(segments[0]);
+    const repo = sanitizeString(segments[1].replace(/\.git$/i, ""));
+    let ref = "main";
+    if (segments[2] === "tree" && segments.length >= 4) {
+        ref = sanitizeString(segments.slice(3).join("/"), 255) || "main";
+    }
+    if (!owner || !repo || !/^[A-Za-z0-9_.-]+$/.test(owner) || !/^[A-Za-z0-9_.-]+$/.test(repo)) {
+        throw new ConfigError(`Unsupported repository URL: "${rawUrl}"`);
+    }
+    if (!ref || ref.includes("..") || !/^[A-Za-z0-9._/-]+$/.test(ref)) {
+        throw new ConfigError(`Unsupported branch/ref in URL: "${rawUrl}"`);
+    }
+    return {
+        owner,
+        repo,
+        ref,
+        canonicalUrl: `https://github.com/${owner}/${repo}/tree/${ref}`,
+    };
+}
+// ── Exports ─────────────────────────────────────────────────────────────────
+export { ensureGitMirror, GitStashProvider, getCachePaths, parseGitRepoUrl };

package/dist/stash-providers/index.js

@@ -6,5 +6,5 @@
  * side-effect imports that were duplicated in stash-search.ts and stash-show.ts.
  */
 import "./filesystem";
-import "./context-hub";
+import "./git";
 import "./openviking";

package/dist/stash-providers/openviking.js

@@ -1,16 +1,11 @@
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { fetchWithRetry } from "../common";
 import { ConfigError, NotFoundError } from "../errors";
 import { getRegistryIndexCacheDir } from "../paths";
 import { registerStashProvider } from "../stash-provider-factory";
-/** Strip terminal control characters from untrusted strings. */
-function sanitizeString(value, maxLength = 255) {
-    if (typeof value !== "string")
-        return "";
-    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional — strip control chars from untrusted remote data
-    return value.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, maxLength);
-}
+import { isExpired, sanitizeString } from "./provider-utils";
 /** Per-query cache TTL in milliseconds (5 minutes). */
 const QUERY_CACHE_TTL_MS = 5 * 60 * 1000;
 /** Maximum age before query cache is considered stale but still usable (1 hour). */
@@ -70,7 +65,9 @@ class OpenVikingStashProvider {
         }
     }
     async show(ref, _view) {
-        const uri = ref.trim();
+        const trimmed = ref.trim();
+        // Accept both viking:// URIs (legacy/internal) and type:name refs
+        const uri = trimmed.startsWith("viking://") ? trimmed : refToVikingUri(trimmed);
         const baseUrl = this.baseUrl;
         const headers = this.authHeaders;
         const [statResult, contentResult] = await Promise.all([
@@ -78,10 +75,10 @@ class OpenVikingStashProvider {
             fetchOVJson(`${baseUrl}/api/v1/content/read?uri=${encodeURIComponent(uri)}&offset=0&limit=-1`, headers),
         ]);
         if (statResult == null && contentResult == null) {
-            throw new NotFoundError(`Could not fetch remote asset "${uri}". The OpenViking server at ${baseUrl} may be unreachable or the resource does not exist.`);
+            throw new NotFoundError(`Could not fetch remote asset "${trimmed}". The OpenViking server at ${baseUrl} may be unreachable or the resource does not exist.`);
         }
         if (contentResult == null) {
-            throw new NotFoundError(`Content not found for remote asset "${uri}". The server returned metadata but no content.`);
+            throw new NotFoundError(`Content not found for remote asset "${trimmed}". The server returned metadata but no content.`);
         }
         const stat = (typeof statResult === "object" && statResult !== null ? statResult : {});
         const uriPath = uri.replace(/^viking:\/\//, "");
@@ -91,19 +88,20 @@ class OpenVikingStashProvider {
         const assetType = OV_TYPE_MAP[ovType] ?? "knowledge";
         const content = typeof contentResult === "string" ? contentResult : "";
         const description = sanitizeString(stat.abstract, 1000) || undefined;
+        const assetRef = `${assetType}:${name}`;
         return {
             type: assetType,
             name,
-            path: uri,
-            action: `Remote content from OpenViking — ${uri}`,
+            path: assetRef,
+            action: `Remote content from OpenViking — ${assetRef}`,
             content,
             description,
             editable: false,
             origin: "remote",
         };
     }
-    canShow(ref) {
-        return ref.trim().startsWith("viking://");
+    canShow(_ref) {
+        return !!(this.config.url ?? "").trim();
     }
     get baseUrl() {
         return (this.config.url ?? "").replace(/\/+$/, "");
@@ -162,9 +160,8 @@ class OpenVikingStashProvider {
             const name = sanitizeString(entry.name);
             const abstract = sanitizeString(entry.abstract, 1000);
             const type = sanitizeString(entry.type);
-            const uri = sanitizeString(entry.uri, 2048);
             const assetType = OV_TYPE_MAP[type] ?? "knowledge";
-            const ref = uriToVikingRef(uri);
+            const ref = `${assetType}:${name}`;
             return {
                 type: assetType,
                 name,
@@ -180,7 +177,7 @@ class OpenVikingStashProvider {
     }
     queryCachePath(query, limit) {
         const cacheDir = getRegistryIndexCacheDir();
-        const hasher = new Bun.CryptoHasher("md5");
+        const hasher = createHash("md5");
         hasher.update(this.config.url ?? "");
         hasher.update("\0");
         hasher.update(query.trim().toLowerCase());
@@ -225,11 +222,28 @@ class OpenVikingStashProvider {
 // ── Self-register ───────────────────────────────────────────────────────────
 registerStashProvider("openviking", (config) => new OpenVikingStashProvider(config));
 // ── Helpers ─────────────────────────────────────────────────────────────────
-function uriToVikingRef(uri) {
-    if (uri.startsWith("viking://"))
-        return uri;
-    return `viking://${uri.replace(/^\/+/, "")}`;
+/**
+ * Convert a type:name ref to a viking:// URI for the OpenViking API.
+ * Maps the akm asset type back to the OV plural form (e.g. "skill" -> "skills").
+ */
+function refToVikingUri(ref) {
+    const colon = ref.indexOf(":");
+    if (colon <= 0)
+        return `viking://${ref}`;
+    const name = ref.slice(colon + 1);
+    const type = ref.slice(0, colon);
+    const ovDir = AKM_TO_OV_DIR[type] ?? type;
+    return `viking://${ovDir}/${name}`;
 }
+/** Reverse map: akm asset type → OpenViking directory name (plural). */
+const AKM_TO_OV_DIR = {
+    skill: "skills",
+    memory: "memories",
+    knowledge: "resources",
+    agent: "agents",
+    command: "commands",
+    script: "scripts",
+};
 function parseOVSearchResponse(result) {
     if (Array.isArray(result))
         return result.filter(isValidOVEntry);
@@ -311,9 +325,6 @@ function extractNameFromUri(uri) {
     const last = segments[segments.length - 1] ?? "unknown";
     return last.replace(/\.[^.]+$/, "");
 }
-function isExpired(mtimeMs, ttlMs) {
-    return Date.now() - mtimeMs > ttlMs;
-}
 async function fetchOVJson(url, headers) {
     try {
         const response = await fetchWithRetry(url, { headers }, { timeout: 10_000, retries: 1 });
@@ -334,4 +345,4 @@ function inferTypeFromUri(uri) {
     return OV_TYPE_MAP[firstSegment] ?? "knowledge";
 }
 // ── Exports for testing ─────────────────────────────────────────────────────
-export { OpenVikingStashProvider, uriToVikingRef, parseOVSearchResponse };
+export { OpenVikingStashProvider, parseOVSearchResponse, refToVikingUri };

package/dist/stash-providers/provider-utils.js

@@ -0,0 +1,11 @@
+/** Strip terminal control characters from untrusted strings. */
+export function sanitizeString(value, maxLength = 255) {
+    if (typeof value !== "string")
+        return "";
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional — strip control chars from untrusted remote data
+    return value.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, maxLength);
+}
+/** Check whether a cached timestamp has exceeded its TTL. */
+export function isExpired(mtimeMs, ttlMs) {
+    return Date.now() - mtimeMs > ttlMs;
+}