@pugi/cli 0.1.0-beta.7 → 0.1.0-beta.87

package/dist/core/prompts/registry.js

@@ -0,0 +1,364 @@
+/**
+ * Prompt registry primitive — versioned storage + hot-swap + rollback.
+ *
+ * Gap-analysis primitive #5 (final) from
+ * docs/research/2026-05-31-9-layer-rag-architecture-.md.
+ *
+ * Layout on disk (per slug):
+ *
+ *  <baseDir>/
+ *    <slug>/
+ *      0.1.0.md           // semver-named version files
+ *      0.2.0.md
+ *      1.0.0.md
+ *      current.md         // POSIX symlink (or copy on win32) -> active version
+ *      .history.jsonl     // append-only audit log: { ts, action, version, prev? }
+ *
+ * Operations:
+ *
+ *  loadPrompt           — load a specific version or the active one
+ *  listVersions        — enumerate version files, sorted semver desc
+ *  getCurrentVersion  — read the active version (null when uninitialised)
+ *  activateVersion   — atomic hot-swap of `current.md` to a new version,
+ *                       append a history entry, never leave a gap
+ *  rollbackPrompt   — restore the previous active version from .history.jsonl
+ *
+ * Atomic-write contract: every `current.md` mutation lands via tmp + rename
+ * on the same filesystem so a concurrent reader never observes a torn state.
+ * Mirrors the agent-progress writer pattern (see
+ * apps/pugi-cli/src/core/agent-progress/writer.ts).
+ *
+ * Out of scope (separate PRs):
+ *  - admin-api consumer wire-up
+ *  - A/B tenant-subset pinning
+ *  - cache invalidation hook on activate
+ *  - migration of existing PUGI.md to versioned format
+ */
+import { appendFile, copyFile, lstat, mkdir, readFile, readdir, readlink, rename, rm, stat, symlink, writeFile, } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import semver from 'semver';
+/* ---------------------------------------------------------------------- */
+/* Helpers                                                                 */
+/* ---------------------------------------------------------------------- */
+const CURRENT_FILENAME = 'current.md';
+const HISTORY_FILENAME = '.history.jsonl';
+const IS_WINDOWS = process.platform === 'win32';
+let writeSeq = 0;
+function slugDir(baseDir, slug) {
+    if (!slug || typeof slug !== 'string') {
+        throw new TypeError(`prompt-registry: slug must be a non-empty string`);
+    }
+    return join(baseDir, slug);
+}
+function versionFile(baseDir, slug, version) {
+    return join(slugDir(baseDir, slug), `${version}.md`);
+}
+function currentFile(baseDir, slug) {
+    return join(slugDir(baseDir, slug), CURRENT_FILENAME);
+}
+function historyFile(baseDir, slug) {
+    return join(slugDir(baseDir, slug), HISTORY_FILENAME);
+}
+async function pathExists(p) {
+    try {
+        await lstat(p);
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+}
+function nextTmpName(target) {
+    writeSeq += 1;
+    return `${target}.tmp-${process.pid}-${writeSeq}-${Date.now()}`;
+}
+/**
+ * Atomically write/replace `current.md` to point at `<version>.md`.
+ *
+ * POSIX path: write a symlink to a tmp name, then rename(tmp, current) so the
+ * swap is atomic — no reader ever observes the file missing.
+ *
+ * Windows path: symlinks require elevated privileges, so we copy the version
+ * bytes to a tmp file and rename. Still atomic on the same volume; the only
+ * cost is duplicated bytes.
+ */
+async function writeCurrentAtomically(dir, version) {
+    const finalPath = join(dir, CURRENT_FILENAME);
+    const tmp = nextTmpName(finalPath);
+    const targetVersionFile = `${version}.md`;
+    try {
+        if (IS_WINDOWS) {
+            await copyFile(join(dir, targetVersionFile), tmp);
+        }
+        else {
+            // Relative symlink — survives moving the slug directory as long as
+            // the version siblings come along.
+            await symlink(targetVersionFile, tmp);
+        }
+        // Replace any existing current.md. rename() is atomic on the same fs.
+        await rename(tmp, finalPath);
+    }
+    catch (err) {
+        try {
+            await rm(tmp, { force: true });
+        }
+        catch {
+            // best-effort
+        }
+        throw err;
+    }
+}
+async function appendHistory(baseDir, slug, entry) {
+    const line = `${JSON.stringify(entry)}\n`;
+    await appendFile(historyFile(baseDir, slug), line, 'utf8');
+}
+async function readHistory(baseDir, slug) {
+    const path = historyFile(baseDir, slug);
+    try {
+        const raw = await readFile(path, 'utf8');
+        const out = [];
+        for (const line of raw.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                out.push(JSON.parse(trimmed));
+            }
+            catch {
+                // Skip malformed lines — append-only log should never have them, but
+                // tolerate corruption rather than poisoning the whole registry.
+            }
+        }
+        return out;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+}
+/**
+ * Resolve the active version slug by inspecting `current.md`.
+ *
+ * On POSIX we read the symlink target (e.g. `1.2.0.md` -> `1.2.0`).
+ * On Windows we have to fall back to the most recent activate entry in
+ * .history.jsonl because the file is a content copy, not a link.
+ */
+async function resolveActiveVersion(baseDir, slug) {
+    const path = currentFile(baseDir, slug);
+    if (!(await pathExists(path)))
+        return null;
+    if (!IS_WINDOWS) {
+        try {
+            const target = await readlink(path);
+            // Strip directory (defensive — we always write relative names) + `.md`.
+            const base = target.split(/[\\/]/).pop() ?? target;
+            return base.endsWith('.md') ? base.slice(0, -3) : base;
+        }
+        catch {
+            // Fall through to history lookup if current.md is a regular file
+            // (e.g. a manual operator override on POSIX).
+        }
+    }
+    const history = await readHistory(baseDir, slug);
+    for (let i = history.length - 1; i >= 0; i -= 1) {
+        const entry = history[i];
+        if (entry && (entry.action === 'activate' || entry.action === 'rollback')) {
+            return entry.version;
+        }
+    }
+    return null;
+}
+/* ---------------------------------------------------------------------- */
+/* Public API                                                              */
+/* ---------------------------------------------------------------------- */
+/**
+ * Load a prompt body + metadata.
+ *
+ * Resolution rules:
+ *  - `version` set       → read `<slug>/<version>.md` directly
+ *  - `version` omitted  → read `<slug>/current.md` (follows symlink on POSIX,
+ *                           or reads the copied content on Windows)
+ *
+ * Throws:
+ *  - TypeError when the slug directory does not exist
+ *  - RangeError when the requested version file or `current.md` is missing
+ */
+export async function loadPrompt(opts) {
+    const dir = slugDir(opts.baseDir, opts.slug);
+    if (!(await pathExists(dir))) {
+        throw new TypeError(`prompt-registry: slug directory not found: ${opts.slug} (looked in ${opts.baseDir})`);
+    }
+    let resolvedVersion = opts.version;
+    let path;
+    if (resolvedVersion) {
+        path = versionFile(opts.baseDir, opts.slug, resolvedVersion);
+        if (!(await pathExists(path))) {
+            throw new RangeError(`prompt-registry: version not found: ${opts.slug}@${resolvedVersion}`);
+        }
+    }
+    else {
+        path = currentFile(opts.baseDir, opts.slug);
+        if (!(await pathExists(path))) {
+            throw new RangeError(`prompt-registry: no current version set for slug: ${opts.slug}`);
+        }
+        const active = await resolveActiveVersion(opts.baseDir, opts.slug);
+        if (!active) {
+            throw new RangeError(`prompt-registry: current.md exists but version cannot be resolved for slug: ${opts.slug}`);
+        }
+        resolvedVersion = active;
+    }
+    const body = await readFile(path, 'utf8');
+    return {
+        slug: opts.slug,
+        version: resolvedVersion,
+        body,
+    };
+}
+/**
+ * List all version files for a slug, sorted semver descending.
+ * Excludes `current.md` and `.history.jsonl`. Returns `[]` for slugs
+ * that have no version files yet (and for slugs that do not exist).
+ */
+export async function listVersions(opts) {
+    const dir = slugDir(opts.baseDir, opts.slug);
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const versions = [];
+    for (const name of entries) {
+        if (name === CURRENT_FILENAME || name === HISTORY_FILENAME)
+            continue;
+        if (!name.endsWith('.md'))
+            continue;
+        const v = name.slice(0, -3);
+        if (semver.valid(v))
+            versions.push(v);
+    }
+    versions.sort((a, b) => semver.rcompare(a, b));
+    const out = [];
+    for (const v of versions) {
+        const body = await readFile(versionFile(opts.baseDir, opts.slug, v), 'utf8');
+        out.push({ slug: opts.slug, version: v, body });
+    }
+    return out;
+}
+/**
+ * Return the active version slug, or `null` when no `current.md` is set
+ * (or when the slug/baseDir does not exist).
+ */
+export async function getCurrentVersion(opts) {
+    if (!(await pathExists(opts.baseDir)))
+        return null;
+    if (!(await pathExists(slugDir(opts.baseDir, opts.slug))))
+        return null;
+    return resolveActiveVersion(opts.baseDir, opts.slug);
+}
+/**
+ * Promote `version` to be the active version. Writes `current.md` atomically
+ * (symlink+rename on POSIX, copy+rename on Windows) and appends an audit
+ * entry to `.history.jsonl`.
+ *
+ * Throws:
+ *  - RangeError when `version` is not valid semver
+ *  - RangeError when `<version>.md` does not exist on disk
+ */
+export async function activateVersion(opts) {
+    if (!semver.valid(opts.version)) {
+        throw new RangeError(`prompt-registry: version must be valid semver, got: ${opts.version}`);
+    }
+    const dir = slugDir(opts.baseDir, opts.slug);
+    const target = versionFile(opts.baseDir, opts.slug, opts.version);
+    if (!(await pathExists(target))) {
+        throw new RangeError(`prompt-registry: version file does not exist: ${opts.slug}@${opts.version}`);
+    }
+    // Capture prior active version BEFORE swapping so the history entry is
+    // complete even if a concurrent activate races us.
+    const prev = (await resolveActiveVersion(opts.baseDir, opts.slug)) ?? undefined;
+    if (!(await pathExists(dir))) {
+        await mkdir(dir, { recursive: true });
+    }
+    await writeCurrentAtomically(dir, opts.version);
+    const entry = {
+        ts: new Date().toISOString(),
+        action: 'activate',
+        version: opts.version,
+        ...(prev !== undefined ? { prev } : {}),
+    };
+    await appendHistory(opts.baseDir, opts.slug, entry);
+}
+/**
+ * Restore the previous active version from `.history.jsonl`. Idempotent
+ * across repeated calls: each call walks one step further back through the
+ * history to find a non-current target.
+ *
+ * Throws RangeError when there is no prior version to restore.
+ */
+export async function rollbackPrompt(opts) {
+    const history = await readHistory(opts.baseDir, opts.slug);
+    if (history.length === 0) {
+        throw new RangeError(`prompt-registry: no history to roll back for slug: ${opts.slug}`);
+    }
+    // Find the most recent entry that has a `prev` field — that's the version
+    // we want to restore. Entries without `prev` were the first activate, so
+    // there's nothing prior to fall back to from them.
+    let target;
+    for (let i = history.length - 1; i >= 0; i -= 1) {
+        const entry = history[i];
+        if (entry && entry.prev) {
+            target = entry.prev;
+            break;
+        }
+    }
+    if (!target) {
+        throw new RangeError(`prompt-registry: no prior version recorded in history for slug: ${opts.slug}`);
+    }
+    const dir = slugDir(opts.baseDir, opts.slug);
+    const file = versionFile(opts.baseDir, opts.slug, target);
+    if (!(await pathExists(file))) {
+        throw new RangeError(`prompt-registry: prior version file missing on disk: ${opts.slug}@${target}`);
+    }
+    const prev = (await resolveActiveVersion(opts.baseDir, opts.slug)) ?? undefined;
+    await writeCurrentAtomically(dir, target);
+    const entry = {
+        ts: new Date().toISOString(),
+        action: 'rollback',
+        version: target,
+        ...(prev !== undefined ? { prev } : {}),
+    };
+    await appendHistory(opts.baseDir, opts.slug, entry);
+    const body = await readFile(file, 'utf8');
+    return { slug: opts.slug, version: target, body };
+}
+/**
+ * Convenience helper for callers that need an OS-level temp dir for tests
+ * or scratch operations. Exported so the spec file can share the same
+ * idiom as the implementation without duplicating logic.
+ */
+export function defaultTmpRoot(prefix = 'pugi-prompts-') {
+    return join(tmpdir(), prefix);
+}
+// Re-export the path helpers under a namespace for tests + downstream
+// consumers that want to introspect the layout without re-deriving paths.
+export const paths = {
+    slugDir,
+    versionFile,
+    currentFile,
+    historyFile,
+};
+// Silence "stat is unused" — kept in the import list because future
+// consumers (cache-invalidation hook, follow-up PR) will need it and the
+// import block is the single canonical place for fs/promises pulls.
+void stat;
+void dirname;
+void writeFile;
+//# sourceMappingURL=registry.js.map