@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.10

package/dist/core/prompts/registry.js

@@ -1,364 +0,0 @@
-/**
- * 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

package/dist/core/pugi-gitignore.js

@@ -1,52 +0,0 @@
-/**
- * Ensure `.gitignore` covers Pugi's local persistence directories.
- *
- * Triple-review P1 (2026-06-04, ): commands that write under
- * `.pugi/` must guarantee a `.gitignore` entry exists BEFORE the first
- * write. Otherwise the first customer run of e.g. `pugi retro` in a
- * fresh repo leaves `.pugi/retros/` and any future `.pugi/settings.json`
- * (secret store) tracked by git on the next `git add -A`.
- *
- * Extracted from `runtime/cli.ts` so any command that mutates `.pugi/`
- * can share the same guarantee without depending on the heavy cli.ts
- * module graph.
- */
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-export const DEFAULT_PUGI_GITIGNORE_MARKERS = [
-    '.pugi/',
-    '.claude/worktrees/',
-];
-const EQUIVALENTS = {
-    '.pugi/': ['.pugi/', '/.pugi/', '.pugi'],
-    '.claude/worktrees/': ['.claude/worktrees/', '/.claude/worktrees/', '.claude/worktrees'],
-};
-export function ensurePugiGitIgnore(cwd, created, skipped, markers = DEFAULT_PUGI_GITIGNORE_MARKERS) {
-    const gitignorePath = resolve(cwd, '.gitignore');
-    if (!existsSync(gitignorePath)) {
-        writeFileSync(gitignorePath, `${markers.join('\n')}\n`, {
-            encoding: 'utf8',
-            mode: 0o600,
-        });
-        created.push(gitignorePath);
-        return;
-    }
-    const current = readFileSync(gitignorePath, 'utf8');
-    const lines = current.split('\n').map((line) => line.trim());
-    const toAppend = [];
-    for (const marker of markers) {
-        const variants = EQUIVALENTS[marker] ?? [marker];
-        const present = variants.some((variant) => lines.includes(variant));
-        if (!present)
-            toAppend.push(marker);
-    }
-    if (toAppend.length === 0) {
-        skipped.push(gitignorePath);
-        return;
-    }
-    const trailing = current.endsWith('\n') ? '' : '\n';
-    const next = `${current}${trailing}${toAppend.join('\n')}\n`;
-    writeFileSync(gitignorePath, next, { encoding: 'utf8' });
-    created.push(`${gitignorePath} (+${toAppend.join(', ')})`);
-}
-//# sourceMappingURL=pugi-gitignore.js.map