@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

package/dist/src/rlm/cache/cli.js

@@ -0,0 +1,162 @@
+/**
+ * `aiwg rlm-cache` subcommand router.
+ *
+ * Subcommands:
+ *   list                          — show all cached entries
+ *   stats                         — aggregate statistics
+ *   evict <hash>                  — remove one entry
+ *   evict --older-than <Nd|Nh>    — remove old entries
+ *   clear --yes                   — wipe everything (requires --yes)
+ *
+ * @implements #1203
+ */
+import { clear, evict, list, resolveCacheRoot, stats } from './store.js';
+export async function main(args) {
+    const sub = args[0];
+    const rest = args.slice(1);
+    switch (sub) {
+        case 'list':
+            handleList(rest);
+            break;
+        case 'stats':
+            handleStats(rest);
+            break;
+        case 'evict':
+            handleEvict(rest);
+            break;
+        case 'clear':
+            handleClear(rest);
+            break;
+        default:
+            printUsage();
+            if (sub)
+                throw new Error(`Unknown rlm-cache subcommand: ${sub}`);
+    }
+}
+function asJson(args) {
+    return args.includes('--json');
+}
+function handleList(args) {
+    const root = resolveCacheRoot();
+    const entries = list(root);
+    if (asJson(args)) {
+        console.log(JSON.stringify(entries, null, 2));
+        return;
+    }
+    if (entries.length === 0) {
+        console.log('No cached RLM results.');
+        console.log(`Cache root: ${root}`);
+        return;
+    }
+    console.log(`hash      age   model                inputs  cost($)  query`);
+    console.log(`────────  ────  ───────────────────  ──────  ───────  ─────`);
+    for (const e of entries) {
+        console.log(`${e.hash.slice(0, 8)}  ${String(e.ageDays).padStart(3)}d  ` +
+            `${e.model.padEnd(19).slice(0, 19)}  ${String(e.inputCount).padStart(6)}  ` +
+            `${e.costUsd === null ? '   —   ' : e.costUsd.toFixed(4).padStart(7)}  ${e.query}`);
+    }
+    console.log(`\n${entries.length} cached entries at ${root}`);
+}
+function handleStats(args) {
+    const root = resolveCacheRoot();
+    const s = stats(root);
+    if (asJson(args)) {
+        console.log(JSON.stringify(s, null, 2));
+        return;
+    }
+    if (s.totalEntries === 0) {
+        console.log('Cache is empty.');
+        console.log(`Cache root: ${root}`);
+        return;
+    }
+    console.log(`Cache root:        ${root}`);
+    console.log(`Total entries:     ${s.totalEntries}`);
+    console.log(`Total size:        ${s.totalSizeKb} KiB`);
+    console.log(`Oldest entry:      ${s.oldestAgeDays}d`);
+    console.log(`Newest entry:      ${s.newestAgeDays}d`);
+    console.log(`Total cached cost: $${s.totalCostUsd.toFixed(4)}`);
+}
+function parseDuration(spec) {
+    // Accepts 30d, 2h, 14 (days)
+    const m = spec.match(/^(\d+)\s*([dh])?$/i);
+    if (!m)
+        throw new Error(`Invalid duration: ${spec} (use Nd or Nh)`);
+    const n = parseInt(m[1] ?? '', 10);
+    const unit = (m[2] ?? 'd').toLowerCase();
+    return unit === 'h' ? n / 24 : n;
+}
+function handleEvict(args) {
+    const root = resolveCacheRoot();
+    const olderIdx = args.indexOf('--older-than');
+    if (olderIdx !== -1 && args[olderIdx + 1]) {
+        const days = parseDuration(args[olderIdx + 1]);
+        const r = evict(root, { olderThanDays: days });
+        if (asJson(args)) {
+            console.log(JSON.stringify(r, null, 2));
+        }
+        else {
+            console.log(`Evicted ${r.evictedCount} entries (${Math.round(r.evictedBytes / 1024)} KiB) older than ${days}d.`);
+        }
+        return;
+    }
+    const hash = args.find((a) => /^[0-9a-f]{8,64}$/.test(a));
+    if (!hash) {
+        console.error('Usage: aiwg rlm-cache evict <hash> | --older-than <Nd|Nh>');
+        process.exitCode = 1;
+        return;
+    }
+    // Resolve short hash → full hash
+    const full = resolveHashPrefix(root, hash);
+    if (!full) {
+        console.error(`No cache entry matching: ${hash}`);
+        process.exitCode = 1;
+        return;
+    }
+    const r = evict(root, { hash: full });
+    if (asJson(args)) {
+        console.log(JSON.stringify(r, null, 2));
+    }
+    else if (r.evictedCount === 0) {
+        console.log(`No entry: ${full}`);
+    }
+    else {
+        console.log(`Evicted ${full} (${Math.round(r.evictedBytes / 1024)} KiB).`);
+    }
+}
+function resolveHashPrefix(root, prefix) {
+    const all = list(root);
+    const matches = all.filter((e) => e.hash.startsWith(prefix));
+    if (matches.length === 1 && matches[0])
+        return matches[0].hash;
+    if (matches.length > 1) {
+        console.error(`Ambiguous prefix '${prefix}' matches ${matches.length} entries.`);
+        return null;
+    }
+    return null;
+}
+function handleClear(args) {
+    if (!args.includes('--yes')) {
+        console.error('Refusing to clear cache without --yes confirmation.');
+        process.exitCode = 1;
+        return;
+    }
+    const root = resolveCacheRoot();
+    const r = clear(root);
+    if (asJson(args)) {
+        console.log(JSON.stringify(r, null, 2));
+    }
+    else {
+        console.log(`Cleared ${r.evictedCount} entries (${Math.round(r.evictedBytes / 1024)} KiB).`);
+    }
+}
+function printUsage() {
+    console.log('aiwg rlm-cache <subcommand>');
+    console.log('');
+    console.log('Subcommands:');
+    console.log('  list [--json]                       List all cached RLM results');
+    console.log('  stats [--json]                      Aggregate cache statistics');
+    console.log('  evict <hash>                        Remove a single entry by hash (prefix ok)');
+    console.log('  evict --older-than <Nd|Nh>          Remove entries older than N days/hours');
+    console.log('  clear --yes                         Wipe entire cache (requires --yes)');
+}
+//# sourceMappingURL=cli.js.map

package/dist/src/rlm/cache/hash.js

@@ -0,0 +1,35 @@
+/**
+ * Deterministic cache key composition.
+ *
+ * The hash includes content hashes (not just artifact IDs) so file edits
+ * invalidate the cache cleanly. Inputs are sorted by artifactId so caller
+ * order does not affect the resulting hash.
+ *
+ * @implements #1203
+ * @see .aiwg/architecture/adr-rlm-index-features-impl-plan.md
+ */
+import { createHash } from 'node:crypto';
+/** Compute a stable sha256 hex hash for a cache key. */
+export function computeHash(key) {
+    const sortedInputs = [...key.inputs].sort((a, b) => a.artifactId.localeCompare(b.artifactId));
+    const canonical = JSON.stringify({
+        inputs: sortedInputs,
+        query: key.query,
+        subPrompt: key.subPrompt,
+        model: key.model,
+        aggregateStrategy: key.aggregateStrategy,
+    });
+    return createHash('sha256').update(canonical).digest('hex');
+}
+/** Validate a cache key has the minimum required fields. */
+export function isCacheKey(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const k = value;
+    return (Array.isArray(k['inputs']) &&
+        typeof k['query'] === 'string' &&
+        typeof k['subPrompt'] === 'string' &&
+        typeof k['model'] === 'string' &&
+        typeof k['aggregateStrategy'] === 'string');
+}
+//# sourceMappingURL=hash.js.map

package/dist/src/rlm/cache/store.js

@@ -0,0 +1,170 @@
+/**
+ * RLM result cache filesystem store.
+ *
+ * Layout:
+ *   .aiwg/working/rlm-cache/{hash}/
+ *     ├── result.json
+ *     ├── manifest.json
+ *     └── metadata.json
+ *
+ * @implements #1203
+ * @see .aiwg/architecture/adr-rlm-index-features-impl-plan.md
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+const CACHE_ROOT_DEFAULT = '.aiwg/working/rlm-cache';
+const HASH_RE = /^[0-9a-f]{64}$/;
+/** Resolve cache root, allowing tests to override. */
+export function resolveCacheRoot(cwd = process.cwd()) {
+    return join(cwd, CACHE_ROOT_DEFAULT);
+}
+/** Compute the directory for a single entry. */
+function entryDir(root, hash) {
+    if (!HASH_RE.test(hash)) {
+        throw new Error(`Invalid cache hash: ${hash}`);
+    }
+    return join(root, hash);
+}
+/** Check whether a cache entry exists. */
+export function has(root, hash) {
+    return existsSync(join(entryDir(root, hash), 'result.json'));
+}
+/** Read a full entry from disk. Throws on missing. */
+export function get(root, hash) {
+    const dir = entryDir(root, hash);
+    if (!existsSync(dir)) {
+        throw new Error(`Cache miss: ${hash}`);
+    }
+    const result = JSON.parse(readFileSync(join(dir, 'result.json'), 'utf-8'));
+    const manifest = JSON.parse(readFileSync(join(dir, 'manifest.json'), 'utf-8'));
+    const metadata = JSON.parse(readFileSync(join(dir, 'metadata.json'), 'utf-8'));
+    return { hash, result, manifest, metadata };
+}
+/** Write an entry, atomically per-file. Returns the entry directory. */
+export function put(root, entry) {
+    const dir = entryDir(root, entry.hash);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'result.json'), JSON.stringify(entry.result, null, 2), 'utf-8');
+    writeFileSync(join(dir, 'manifest.json'), JSON.stringify(entry.manifest, null, 2), 'utf-8');
+    writeFileSync(join(dir, 'metadata.json'), JSON.stringify(entry.metadata, null, 2), 'utf-8');
+    return dir;
+}
+/** List all entries (compact summary form). */
+export function list(root, now = new Date()) {
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    for (const name of readdirSync(root)) {
+        if (!HASH_RE.test(name))
+            continue;
+        const metaPath = join(root, name, 'metadata.json');
+        if (!existsSync(metaPath))
+            continue;
+        let meta;
+        try {
+            meta = JSON.parse(readFileSync(metaPath, 'utf-8'));
+        }
+        catch {
+            continue;
+        }
+        const manifestPath = join(root, name, 'manifest.json');
+        let inputCount = 0;
+        if (existsSync(manifestPath)) {
+            try {
+                const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+                inputCount = manifest.inputs.length;
+            }
+            catch { /* ignore */ }
+        }
+        const ageMs = now.getTime() - new Date(meta.createdAt).getTime();
+        const ageDays = Math.max(0, Math.floor(ageMs / 86_400_000));
+        out.push({
+            hash: name,
+            model: meta.model,
+            query: meta.query.length > 80 ? meta.query.slice(0, 77) + '...' : meta.query,
+            createdAt: meta.createdAt,
+            ageDays,
+            inputCount,
+            costUsd: typeof meta.costUsd === 'number' ? meta.costUsd : null,
+        });
+    }
+    return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+/** Aggregate statistics. */
+export function stats(root, now = new Date()) {
+    const entries = list(root, now);
+    if (entries.length === 0) {
+        return { totalEntries: 0, totalSizeKb: 0, oldestAgeDays: null, newestAgeDays: null, totalCostUsd: 0 };
+    }
+    let totalBytes = 0;
+    for (const e of entries) {
+        const dir = entryDir(root, e.hash);
+        for (const f of ['result.json', 'manifest.json', 'metadata.json']) {
+            const p = join(dir, f);
+            if (existsSync(p))
+                totalBytes += statSync(p).size;
+        }
+    }
+    const ages = entries.map((e) => e.ageDays);
+    const totalCostUsd = entries.reduce((sum, e) => sum + (e.costUsd ?? 0), 0);
+    return {
+        totalEntries: entries.length,
+        totalSizeKb: Math.round(totalBytes / 1024),
+        oldestAgeDays: Math.max(...ages),
+        newestAgeDays: Math.min(...ages),
+        totalCostUsd,
+    };
+}
+/** Remove entries matching the given options. */
+export function evict(root, opts, now = new Date()) {
+    if (!existsSync(root)) {
+        return { evictedCount: 0, evictedBytes: 0, hashes: [] };
+    }
+    const targets = [];
+    if (opts.hash) {
+        if (existsSync(entryDir(root, opts.hash)))
+            targets.push(opts.hash);
+    }
+    else if (typeof opts.olderThanDays === 'number') {
+        const cutoff = now.getTime() - opts.olderThanDays * 86_400_000;
+        for (const e of list(root, now)) {
+            if (new Date(e.createdAt).getTime() < cutoff)
+                targets.push(e.hash);
+        }
+    }
+    else {
+        throw new Error('evict() requires either {hash} or {olderThanDays}');
+    }
+    let evictedBytes = 0;
+    for (const h of targets) {
+        const dir = entryDir(root, h);
+        if (existsSync(dir)) {
+            for (const f of ['result.json', 'manifest.json', 'metadata.json']) {
+                const p = join(dir, f);
+                if (existsSync(p))
+                    evictedBytes += statSync(p).size;
+            }
+            rmSync(dir, { recursive: true, force: true });
+        }
+    }
+    return { evictedCount: targets.length, evictedBytes, hashes: targets };
+}
+/** Wipe the entire cache. Caller is responsible for confirmation. */
+export function clear(root) {
+    if (!existsSync(root)) {
+        return { evictedCount: 0, evictedBytes: 0, hashes: [] };
+    }
+    const before = list(root);
+    let evictedBytes = 0;
+    for (const e of before) {
+        const dir = entryDir(root, e.hash);
+        for (const f of ['result.json', 'manifest.json', 'metadata.json']) {
+            const p = join(dir, f);
+            if (existsSync(p))
+                evictedBytes += statSync(p).size;
+        }
+    }
+    rmSync(root, { recursive: true, force: true });
+    return { evictedCount: before.length, evictedBytes, hashes: before.map((e) => e.hash) };
+}
+//# sourceMappingURL=store.js.map

package/dist/src/rlm/cache/types.js

@@ -0,0 +1,8 @@
+/**
+ * RLM Result Cache — Type Definitions
+ *
+ * @implements #1203
+ * @see .aiwg/architecture/adr-rlm-index-features-impl-plan.md
+ */
+export {};
+//# sourceMappingURL=types.js.map