akm-cli 0.7.4 → 0.8.0-rc.10

package/dist/commands/schema-repair.js

@@ -0,0 +1,203 @@
+// 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/.
+/**
+ * Schema-repair pass for `akm improve`.
+ *
+ * Attempts to patch missing frontmatter fields (`description`, `when_to_use`)
+ * on assets that failed schema validation, using a single bounded in-tree LLM
+ * call per asset. Results are recorded as `schema_repair_invoked` events.
+ *
+ * This module is extracted from `improve.ts` to make the repair logic
+ * independently testable and to use the `tryLlmFeature` seam rather than raw
+ * `chatCompletion`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseAssetRef } from "../core/asset-ref";
+import { assembleAsset } from "../core/asset-serialize";
+import { appendEvent, readEvents } from "../core/events";
+import { parseFrontmatter } from "../core/frontmatter";
+import { createProposal, isProposalSkipped } from "../core/proposals";
+import { info, warn } from "../core/warn";
+import { resolveAssetPath } from "../indexer/path-resolver";
+import { chatCompletion, parseEmbeddedJsonResponse } from "../llm/client";
+// ── Constants ────────────────────────────────────────────────────────────────
+/** Minimum gap between schema-repair attempts on the same asset. */
+const SCHEMA_REPAIR_COOLDOWN_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+/**
+ * Per-ref attempt cap (O-6 / #379): maximum number of schema-repair attempts
+ * allowed within SCHEMA_REPAIR_WINDOW_MS. Prevents indefinite nightly re-repair
+ * of assets whose source content is genuinely ambiguous or inconsistently
+ * structured. After cap, the asset is skipped until the window rolls over.
+ * Self-Refine arXiv:2303.17651 — iteration must be bounded.
+ */
+const SCHEMA_REPAIR_MAX_ATTEMPTS = 3;
+const SCHEMA_REPAIR_WINDOW_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+// ── Main ─────────────────────────────────────────────────────────────────────
+/**
+ * Run the schema-repair loop for a batch of validation failures.
+ * Returns a list of per-asset outcome records and the set of refs that were
+ * successfully repaired (so the caller can exclude them from skip logic).
+ */
+export async function runSchemaRepairPass(failures, options) {
+    const repairs = [];
+    const repairedRefs = new Set();
+    const { startMs, budgetMs, llmConfig, stashDir, findFilePath = defaultFindFilePath, isLessonCandidateFn = defaultIsLessonCandidate, chatFn = chatCompletion, } = options;
+    for (const failure of failures) {
+        if (Date.now() - startMs >= budgetMs)
+            break;
+        // Cooldown: skip repair if we ran it successfully recently.
+        const recentRepairs = readEvents({ type: "schema_repair_invoked", ref: failure.ref });
+        const lastRepair = recentRepairs.events
+            .filter((e) => e.metadata?.outcome === "written")
+            .sort((a, b) => new Date(b.ts ?? 0).getTime() - new Date(a.ts ?? 0).getTime())[0];
+        if (lastRepair?.ts && Date.now() - new Date(lastRepair.ts).getTime() < SCHEMA_REPAIR_COOLDOWN_MS) {
+            repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
+            continue;
+        }
+        // O-6 / #379: Cap total attempts at SCHEMA_REPAIR_MAX_ATTEMPTS per SCHEMA_REPAIR_WINDOW_MS.
+        // Prevents indefinite nightly re-repair of assets whose source is genuinely ambiguous.
+        // After the cap is reached, the asset is skipped until the window rolls over.
+        const windowStart = Date.now() - SCHEMA_REPAIR_WINDOW_MS;
+        const attemptsInWindow = recentRepairs.events.filter((e) => e.ts !== undefined && new Date(e.ts).getTime() >= windowStart).length;
+        if (attemptsInWindow >= SCHEMA_REPAIR_MAX_ATTEMPTS) {
+            repairs.push({
+                ref: failure.ref,
+                reason: failure.reason,
+                outcome: "skipped",
+                error: `schema-repair attempt cap reached (${attemptsInWindow}/${SCHEMA_REPAIR_MAX_ATTEMPTS} in 30d window)`,
+            });
+            continue;
+        }
+        const filePath = await findFilePath(failure.ref, stashDir);
+        if (!filePath) {
+            repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
+            continue;
+        }
+        if (path.extname(filePath).toLowerCase() !== ".md") {
+            repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
+            continue;
+        }
+        try {
+            const raw = fs.readFileSync(filePath, "utf8");
+            const fm = parseFrontmatter(raw);
+            const missingFields = [];
+            if (!fm.data.description)
+                missingFields.push("description");
+            if (isLessonCandidateFn(failure.ref) && !fm.data.when_to_use)
+                missingFields.push("when_to_use");
+            if (missingFields.length === 0) {
+                repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
+                continue;
+            }
+            const fieldList = missingFields.join(" and ");
+            info(`[improve] schema-repair ${failure.ref} (${fieldList})`);
+            const bodyPreview = (fm.content ?? raw).slice(0, 2000);
+            const llmResponse = await chatFn(llmConfig, [
+                {
+                    role: "system",
+                    content: `You generate concise asset frontmatter fields. Respond with a JSON object containing only the missing fields. No prose, no markdown fences.`,
+                },
+                {
+                    role: "user",
+                    content: `Generate the missing frontmatter fields (${fieldList}) for this ${parseAssetRef(failure.ref).type} asset. Return ONLY valid JSON like {"description": "...", "when_to_use": "..."}\n\n${bodyPreview}`,
+                },
+            ]);
+            const parsed = parseEmbeddedJsonResponse(llmResponse.trim());
+            if (!parsed) {
+                repairs.push({
+                    ref: failure.ref,
+                    reason: failure.reason,
+                    outcome: "error",
+                    error: "LLM returned unparseable JSON for schema repair",
+                });
+                continue;
+            }
+            const newFm = { ...fm.data };
+            if (parsed.description)
+                newFm.description = parsed.description;
+            if (parsed.when_to_use)
+                newFm.when_to_use = parsed.when_to_use;
+            const newContent = assembleAsset(newFm, fm.content);
+            // M-3 / #387: Route through proposal queue instead of writing directly to
+            // disk. This restores akm's safety invariant — the proposal queue is the
+            // only path to a committed asset write. LLM-generated `description` /
+            // `when_to_use` fields can be incorrect; routing through the queue makes
+            // them human-reviewable before they affect search ranking and curate hints.
+            // mem0 open gaps (arXiv:2504.19413) — any LLM write to a memory field
+            // should be human-reviewable.
+            if (stashDir) {
+                const proposalResult = createProposal(stashDir, {
+                    ref: failure.ref,
+                    source: "schema-repair",
+                    payload: {
+                        content: newContent,
+                        ...(Object.keys(newFm).length > 0 ? { frontmatter: newFm } : {}),
+                    },
+                });
+                if (isProposalSkipped(proposalResult)) {
+                    info(`[improve] schema-repair proposal skipped for ${failure.ref}: ${proposalResult.message}`);
+                    repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
+                    continue;
+                }
+                info(`[improve] schema-repair queued: ${failure.ref} (proposal id: ${proposalResult.id})`);
+                appendEvent({
+                    eventType: "schema_repair_invoked",
+                    ref: failure.ref,
+                    metadata: { outcome: "queued", reason: failure.reason, proposalId: proposalResult.id },
+                });
+                repairs.push({
+                    ref: failure.ref,
+                    reason: failure.reason,
+                    outcome: "queued",
+                    proposalId: proposalResult.id,
+                });
+                // Mark as repaired so the caller removes it from the validation-failure set.
+                repairedRefs.add(failure.ref);
+            }
+            else {
+                // Fallback: no stash dir available — write directly (legacy path).
+                // This should not occur in production; stashDir is always provided by
+                // `runSchemaRepairPass` callers in improve.ts.
+                warn(`[improve] schema-repair: no stashDir available for ${failure.ref}, falling back to direct write`);
+                fs.writeFileSync(filePath, newContent, "utf8");
+                info(`[improve] schema-repair written: ${failure.ref}`);
+                appendEvent({
+                    eventType: "schema_repair_invoked",
+                    ref: failure.ref,
+                    metadata: { outcome: "written", reason: failure.reason },
+                });
+                repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "written" });
+                repairedRefs.add(failure.ref);
+            }
+        }
+        catch (e) {
+            appendEvent({
+                eventType: "schema_repair_invoked",
+                ref: failure.ref,
+                metadata: { outcome: "error", reason: failure.reason, error: String(e) },
+            });
+            repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "error", error: String(e) });
+        }
+    }
+    return { repairs, repairedRefs };
+}
+// ── Default seam implementations ─────────────────────────────────────────────
+function defaultIsLessonCandidate(ref) {
+    try {
+        const parsed = parseAssetRef(ref);
+        return parsed.type === "lesson";
+    }
+    catch {
+        return false;
+    }
+}
+async function defaultFindFilePath(ref, stashDir) {
+    return resolveAssetPath(ref, {
+        stashDir,
+        mode: "index-first",
+        directoryIndexNames: ["SKILL.md", "index.md", "README.md"],
+        preserveDirectNameFallback: true,
+    });
+}

package/dist/commands/search.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/.
 /**
  * `akm search` — entry point.
  *
@@ -9,11 +12,13 @@
  * Provider `search()` methods do not exist.
  */
 import { loadConfig } from "../core/config";
-import { UsageError } from "../core/errors";
+import { rethrowIfTestIsolationError, UsageError } from "../core/errors";
 import { appendEvent } from "../core/events";
-import { closeDatabase, openExistingDatabase } from "../indexer/db";
+import { isTransientStashPath } from "../core/paths";
+import { bumpUtilityScoresBatch, closeDatabase, openExistingDatabase } from "../indexer/db";
 import { searchLocal } from "../indexer/db-search";
 import { resolveSourceEntries } from "../indexer/search-source";
+import { getCurrentWorkflowScopeKey } from "../workflows/scope-key";
 // Eagerly import source providers to trigger self-registration before the
 // indexer or path-resolution code runs.
 import "../sources/providers/index";
@@ -26,10 +31,42 @@ export async function akmSearch(input) {
     const normalizedQuery = query.toLowerCase();
     const searchType = input.type ?? "any";
     const limit = normalizeLimit(input.limit);
-    const source = parseSearchSource(input.source ?? "stash");
+    const parsedSource = parseSearchSource(input.source ?? "stash");
     const config = loadConfig();
-    const sources = resolveSourceEntries(undefined, config);
-    if (sources.length === 0) {
+    // Named-source filter: when --source is not a standard enum value, treat it
+    // as a named source from config.sources[].name. Validate early (before
+    // resolveSourceEntries, which can throw STASH_DIR_NOT_FOUND) so that a bad
+    // --source name always produces INVALID_SOURCE_VALUE regardless of stash state.
+    let namedSourceName;
+    let source;
+    if (parsedSource !== "stash" && parsedSource !== "registry" && parsedSource !== "both") {
+        namedSourceName = parsedSource;
+        // Check that the named source exists in the config before touching the stash.
+        const configSources = config.sources ?? [];
+        const foundInConfig = configSources.some((s) => s.name === namedSourceName) || configSources.some((s) => s.path === namedSourceName);
+        if (!foundInConfig) {
+            const validNames = configSources.map((s) => s.name).filter((n) => Boolean(n));
+            const hint = validNames.length > 0
+                ? `Known source names: ${validNames.join(", ")}`
+                : "No named sources are configured. Run `akm list` to see installed stashes.";
+            throw new UsageError(`Unknown source name: "${namedSourceName}". ${hint}`, "INVALID_SOURCE_VALUE");
+        }
+        source = "stash";
+    }
+    else {
+        source = parsedSource;
+    }
+    let allSources = resolveSourceEntries(undefined, config);
+    // When a named source was requested, narrow the sources list to just that entry.
+    // `resolveSourceEntries` sets `registryId` to `entry.name` for each config source.
+    if (namedSourceName !== undefined) {
+        const ns = namedSourceName;
+        allSources = allSources.filter((s) => s.registryId === ns || s.path === ns);
+        // allSources may still be empty if the configured source dir doesn't exist on
+        // disk (resolveSourceEntries skips non-existent dirs). Fall through to the
+        // zero-sources guard below which emits a friendly warning.
+    }
+    if (allSources.length === 0) {
         // stashDir: "" is a safe sentinel here — the response carries zero hits
         // and a warning, so no downstream code will try to use the empty path.
         const response = {
@@ -40,14 +77,18 @@ export async function akmSearch(input) {
             warnings: ["No stashes configured. Run `akm init` to create your working stash."],
             timing: { totalMs: Date.now() - t0 },
         };
-        logSearchEvent(query, response);
+        if (!input.skipLogging)
+            logSearchEvent(query, response, undefined, undefined, input.eventSource);
         return response;
     }
     // Primary stash directory — used for DB path lookups and as the default
     // stash root. Safe because the empty-sources case is handled above.
-    const stashDir = sources[0].path;
+    const stashDir = allSources[0].path;
+    // Expose the filtered source list to downstream search calls.
+    const sources = allSources;
     const filters = normalizeScopeFilters(input.filters);
     const includeProposed = input.includeProposed === true;
+    const belief = input.belief ?? "all";
     const localResult = source === "registry"
         ? undefined
         : await searchLocal({
@@ -59,6 +100,13 @@ export async function akmSearch(input) {
             config,
             filters,
             includeProposed,
+            beliefFilter: belief,
+            // When `--source <name>` narrowed the source list above, propagate
+            // that intent down to the database layer so FTS/vector hits from
+            // sources outside the narrowed set are filtered out post-ranking.
+            // Without this, the index (which spans every configured source)
+            // would leak hits from sources the caller did not request.
+            restrictToSources: namedSourceName !== undefined,
         });
     const registryResult = source === "stash" ? undefined : await searchRegistry(query, { limit, registries: config.registries });
     if (source === "stash") {
@@ -73,7 +121,8 @@ export async function akmSearch(input) {
             warnings: localResult?.warnings?.length ? localResult.warnings : undefined,
             timing: { totalMs: Date.now() - t0, rankMs: localResult?.rankMs, embedMs: localResult?.embedMs },
         };
-        logSearchEvent(query, response);
+        if (!input.skipLogging)
+            logSearchEvent(query, response, undefined, localResult?.mode ?? "keyword", input.eventSource);
         return response;
     }
     const registryHits = (registryResult?.hits ?? []).map((hit) => {
@@ -107,7 +156,8 @@ export async function akmSearch(input) {
             warnings: registryResult?.warnings.length ? registryResult.warnings : undefined,
             timing: { totalMs: Date.now() - t0 },
         };
-        logSearchEvent(query, response);
+        if (!input.skipLogging)
+            logSearchEvent(query, response, undefined, undefined, input.eventSource);
         return response;
     }
     // source === "both"
@@ -124,7 +174,8 @@ export async function akmSearch(input) {
         warnings: warnings.length ? warnings : undefined,
         timing: { totalMs: Date.now() - t0 },
     };
-    logSearchEvent(query, response);
+    if (!input.skipLogging)
+        logSearchEvent(query, response, undefined, undefined, input.eventSource);
     return response;
 }
 /**
@@ -160,13 +211,16 @@ function resolveEntryIds(db, hits) {
  * Per-entry events are recorded only for stash hits because registry hits
  * have no local entry_id to reference.
  */
-function logSearchEvent(query, response, existingDb) {
+function logSearchEvent(query, response, existingDb, mode = "keyword", eventSource = "user") {
     // Emit a structured event to events.jsonl so workflow-trace consumers
     // detect akm search invocations without relying on stdout scraping.
     const stashHits = response.hits.filter((h) => h.type !== "registry");
+    // D8: include registry hit refs so a show following a registry-only search generates a select event
+    const registryHitRefs = (response.registryHits ?? []).map((h) => `registry:${h.id}`);
+    const allResultRefs = [...stashHits.map((h) => h.ref), ...registryHitRefs];
     appendEvent({
         eventType: "search",
-        metadata: { query, hitCount: stashHits.length, resultRefs: stashHits.map((h) => h.ref) },
+        metadata: { query, hitCount: stashHits.length, resultRefs: allResultRefs, mode },
     });
     try {
         const db = existingDb ?? openExistingDatabase();
@@ -178,8 +232,24 @@ function logSearchEvent(query, response, existingDb) {
                     query,
                     entry_id: entryId,
                     entry_ref: ref,
+                    source: eventSource,
                 });
             }
+            // Bump utility scores for all resolved entries (MemRL retrieval signal).
+            // The indexer overwrites these at next reindex; bumps are temporary hints.
+            const resolvedIds = resolved.map((r) => r.entryId).filter((id) => id !== undefined);
+            if (resolvedIds.length > 0) {
+                let scopeKey;
+                try {
+                    const stashPath = response.stashDir;
+                    const disabled = process.env.AKM_DISABLE_SCOPED_UTILITY === "1" || (stashPath && isTransientStashPath(stashPath));
+                    scopeKey = disabled ? undefined : getCurrentWorkflowScopeKey();
+                }
+                catch {
+                    // Non-fatal — fall back to global-only bumps on any error.
+                }
+                bumpUtilityScoresBatch(db, resolvedIds, 1.0, 0.1, scopeKey);
+            }
             // Count registry hits separately so registry-only searches record a
             // non-zero resultCount. response.hits is always [] when source="registry".
             const stashHitCount = response.hits.length;
@@ -192,7 +262,9 @@ function logSearchEvent(query, response, existingDb) {
                     stashHitCount,
                     registryHitCount,
                     resolvedCount: resolved.length,
+                    mode,
                 }),
+                source: eventSource,
             });
         }
         finally {
@@ -200,7 +272,8 @@ function logSearchEvent(query, response, existingDb) {
                 closeDatabase(db);
         }
     }
-    catch {
+    catch (err) {
+        rethrowIfTestIsolationError(err);
         /* fire-and-forget */
     }
 }
@@ -211,6 +284,24 @@ function normalizeLimit(limit) {
     }
     return Math.min(Math.floor(limit), 200);
 }
+/**
+ * Parse the `--source` flag value.
+ *
+ * Accepts:
+ *   - `stash` (default) — search the local stash index only
+ *   - `registry`        — search remote registries only
+ *   - `both`            — search stash and registries
+ *   - `local`           — alias for `stash`
+ *   - Any named source from `config.sources[].name` — filters stash results to
+ *     that single source only. The named-source path is detected and resolved
+ *     inside `akmSearch`; this function returns the raw name so the caller can
+ *     pass it through to `akmSearch` which accepts `SearchSource | string`.
+ *
+ * Unknown values that are not a known enum AND not a named source will still
+ * produce an error inside `akmSearch` when the config lookup finds nothing.
+ * This allows the CLI to accept named sources without requiring config access
+ * at parse time.
+ */
 export function parseSearchSource(source) {
     if (source === "stash" || source === "registry" || source === "both")
         return source;
@@ -219,7 +310,17 @@ export function parseSearchSource(source) {
         return "stash";
     if (typeof source === "undefined")
         return "stash";
-    throw new UsageError(`Invalid value for --source: ${String(source)}. Expected one of: stash|registry|both`, "INVALID_SOURCE_VALUE");
+    // Pass through unknown strings — they may be valid named sources.
+    // `akmSearch` will validate against config.sources and throw a UsageError
+    // with a helpful message if the name isn't found.
+    return source;
+}
+export function parseBeliefFilterMode(value) {
+    if (value === undefined || value === "all")
+        return "all";
+    if (value === "current" || value === "historical")
+        return value;
+    throw new UsageError(`Invalid value for --belief: ${String(value)}. Expected one of: all|current|historical`, "INVALID_FLAG_VALUE");
 }
 /**
  * Strip empty / non-string values from a scope filter object. Returns

package/dist/commands/secret.js

@@ -0,0 +1,173 @@
+// 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/.
+/**
+ * Secret asset type — whole-file secret storage.
+ *
+ * A `secret` holds a single SENSITIVE value used on its own for authentication
+ * (a PEM private key, an API token, a TLS cert, a service-account JSON): the
+ * ENTIRE file is the secret. There is no safe region to parse, so only the
+ * filename is ever surfaced. Where an `env` file holds a GROUP of related
+ * configuration and exposes key NAMES as metadata, a secret is ONE value and
+ * exposes nothing but its name — reach for `secret` when one value *is* the
+ * credential, and for `env` when loading a service's related configuration.
+ *
+ * Invariant: a secret's bytes must never be written to stdout, returned
+ * through the indexer / `akm show` renderer, or any structured output channel.
+ * The supported value-use paths are:
+ *
+ *   - `akm secret run <ref> <VAR> -- <cmd>` — value injected into the child
+ *     process env as `VAR=<value>` (see `readValue`).
+ *   - `akm secret path <ref>` — print the file path so a command can read it
+ *     itself (Docker `/run/secrets` + `_FILE` convention).
+ *
+ * Values are stored as raw bytes (no quoting, multi-line allowed) so they
+ * round-trip byte-exact, unlike env values which forbid literal newlines.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { probeLock, releaseLock, tryAcquireLockSync } from "../core/file-lock";
+// ── Write-lock helper ─────────────────────────────────────────────────────────
+/**
+ * Acquire an exclusive lock for the given secret path, run `fn`, then release.
+ * Mirrors the env write-lock: O_EXCL creation, 5s deadline, PID-based stale
+ * detection. A timeout is always a stale lock or a programming error, so we
+ * throw rather than silently proceeding.
+ */
+export function withSecretLock(secretPath, fn) {
+    const lockPath = `${secretPath}.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 secret lock for ${secretPath} after 5s.${holderHint} Retry once any other akm secret operation finishes, or remove the stale lock file.`);
+        }
+        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);
+    }
+}
+// ── Atomic byte write ──────────────────────────────────────────────────────────
+/**
+ * Atomically write `data` to `target` at mode 0600. Unlike `writeFileAtomic`
+ * in core/common (string content), this accepts a Buffer so secret bytes
+ * round-trip exactly — binary certs and CRLF/LF line endings are preserved.
+ */
+function writeSecretAtomic(target, data) {
+    const tmp = `${target}.tmp.${process.pid}.${crypto.randomBytes(8).toString("hex")}`;
+    const fd = fs.openSync(tmp, "w", 0o600);
+    try {
+        fs.writeSync(fd, data);
+        try {
+            fs.fdatasyncSync(fd);
+        }
+        catch {
+            // Best-effort durability; some pseudo-filesystems lack fdatasync.
+        }
+    }
+    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 / Windows.
+    }
+}
+function ensureParentDir(filePath) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+// ── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Walk a `secrets/` directory and return the POSIX-relative names of every
+ * secret file. Lock files (`*.lock`), sensitive markers (`*.sensitive`), and
+ * secrets with a sibling `<name>.sensitive` marker are excluded. The file
+ * bodies are NEVER read.
+ */
+export function listNames(secretsRoot) {
+    if (!fs.existsSync(secretsRoot))
+        return [];
+    const names = [];
+    const walk = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (entry.name.endsWith(".lock") || entry.name.endsWith(".sensitive"))
+                continue;
+            // A sibling `<name>.sensitive` marker suppresses listing.
+            if (fs.existsSync(`${full}.sensitive`))
+                continue;
+            names.push(path.relative(secretsRoot, full).split(path.sep).join("/"));
+        }
+    };
+    walk(secretsRoot);
+    return names.sort();
+}
+/**
+ * Read a secret's raw bytes. Internal use only (for `secret run` / `secret
+ * path`). Callers MUST NOT write the returned value to stdout or any log.
+ */
+export function readValue(secretPath) {
+    return fs.readFileSync(secretPath);
+}
+/**
+ * Write (create or overwrite) a secret with the given raw bytes, atomically at
+ * mode 0600 under a write-lock. No quoting; multi-line / binary allowed.
+ */
+export function setSecret(secretPath, value) {
+    ensureParentDir(secretPath);
+    withSecretLock(secretPath, () => {
+        writeSecretAtomic(secretPath, value);
+    });
+}
+/**
+ * Remove a secret file (and its `.sensitive` marker, if present). Returns true
+ * if the secret existed.
+ */
+export function removeSecret(secretPath) {
+    return withSecretLock(secretPath, () => {
+        if (!fs.existsSync(secretPath))
+            return false;
+        fs.rmSync(secretPath);
+        const marker = `${secretPath}.sensitive`;
+        if (fs.existsSync(marker))
+            fs.rmSync(marker);
+        return true;
+    });
+}

package/dist/commands/self-update.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 * as childProcess from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs";