@pareto4/pp-core 1.5.0

package/pp-core/bin/lib/io.cjs

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * CLI I/O primitives — output(), error(), ERROR_REASON, JSON-error mode,
+ * and the temp-file helpers that output() depends on.
+ *
+ * Extracted from core.cts (ADR-857 rollout phase 1 / issue #859).
+ * The hand-written bodies are preserved byte-for-behaviour; only the module
+ * boundary moved. The core.cjs re-export spine was retired in epic #1267;
+ * callers import I/O primitives from io.cjs directly.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// ─── Temp-file helpers (needed by output()) ──────────────────────────────────
+/**
+ * Dedicated GSD temp directory: path.join(os.tmpdir(), 'gsd').
+ * Created on first use. Keeps GSD temp files isolated from the system
+ * temp directory so reap scans only GSD files (#1975).
+ */
+const GSD_TEMP_DIR = node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd');
+function ensureGsdTempDir() {
+    (0, shell_command_projection_cjs_1.platformEnsureDir)(GSD_TEMP_DIR);
+}
+/**
+ * Remove stale gsd-* temp files/dirs older than maxAgeMs (default: 5 minutes).
+ * Runs opportunistically before each new temp file write to prevent unbounded accumulation.
+ * @param prefix - filename prefix to match (e.g., 'gsd-')
+ * @param opts
+ * @param opts.maxAgeMs - max age in ms before removal (default: 5 min)
+ * @param opts.dirsOnly - if true, only remove directories (default: false)
+ */
+function reapStaleTempFiles(prefix = 'gsd-', { maxAgeMs = 5 * 60 * 1000, dirsOnly = false } = {}) {
+    try {
+        ensureGsdTempDir();
+        const now = Date.now();
+        const entries = node_fs_1.default.readdirSync(GSD_TEMP_DIR);
+        for (const entry of entries) {
+            if (!entry.startsWith(prefix))
+                continue;
+            const fullPath = node_path_1.default.join(GSD_TEMP_DIR, entry);
+            try {
+                const stat = node_fs_1.default.statSync(fullPath);
+                if (now - stat.mtimeMs > maxAgeMs) {
+                    if (stat.isDirectory()) {
+                        node_fs_1.default.rmSync(fullPath, { recursive: true, force: true });
+                    }
+                    else if (!dirsOnly) {
+                        node_fs_1.default.unlinkSync(fullPath);
+                    }
+                }
+            }
+            catch {
+                // File may have been removed between readdir and stat — ignore
+            }
+        }
+    }
+    catch {
+        // Non-critical — don't let cleanup failures break output
+    }
+}
+// ─── Output helpers ───────────────────────────────────────────────────────────
+/**
+ * Transient write errnos. When stdout/stderr is a NON-BLOCKING pipe — as it is
+ * under the parallel `node --test` runner on Linux CI — a full pipe buffer makes
+ * `fs.writeSync` throw EAGAIN, and a signal can interrupt it with EINTR. Both
+ * clear on retry once the reader drains. This is the same transient class the
+ * STATE.md lock path already retries (ACQUIRE_LOCK_RETRY_ERRNOS, #3776); #1008.
+ */
+const WRITE_RETRY_ERRNOS = new Set(['EAGAIN', 'EINTR']);
+// Bounded so a pathological never-draining fd cannot spin forever. Each retry
+// yields the thread for ~1ms via Atomics.wait (the project's sync-sleep idiom —
+// see clock.cts realClock.sleep), so the cap is ~1s of total back-pressure wait.
+const WRITE_MAX_RETRIES = 1000;
+const WRITE_RETRY_BACKOFF_MS = 1;
+// Sleep buffer is lazily allocated on the FIRST back-pressure retry (rare — only
+// when a non-blocking pipe is full) and then reused. Keeping it out of module
+// load costs nothing on the overwhelmingly common no-retry path and avoids
+// perturbing SharedArrayBuffer-allocation accounting in other modules (perf-316).
+let _writeSleepBuf = null;
+function backoffOnce() {
+    if (_writeSleepBuf === null)
+        _writeSleepBuf = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(_writeSleepBuf, 0, 0, WRITE_RETRY_BACKOFF_MS);
+}
+/**
+ * Write the entire payload to `fd`, tolerating non-blocking-pipe back-pressure.
+ *
+ * `fs.writeSync` does NOT block on a non-blocking pipe: a full buffer throws
+ * EAGAIN, and a partially-drained buffer returns a SHORT count (fewer bytes than
+ * requested). The previous bare `fs.writeSync(fd, string)` call assumed it always
+ * blocked until the kernel accepted every byte — false under load, which both
+ * threw spurious errors and risked silently truncating output (#1008).
+ *
+ * This loops on short counts (advancing the offset) and retries EAGAIN/EINTR with
+ * a brief Atomics.wait backoff that yields the thread so the reader can drain.
+ * Non-transient errors (e.g. EPIPE) propagate unchanged.
+ */
+function writeAllSync(fd, data) {
+    const buf = Buffer.from(data, 'utf8');
+    let offset = 0;
+    let retries = 0;
+    while (offset < buf.length) {
+        try {
+            offset += node_fs_1.default.writeSync(fd, buf, offset, buf.length - offset);
+        }
+        catch (err) {
+            const code = err.code ?? '';
+            if (WRITE_RETRY_ERRNOS.has(code) && retries < WRITE_MAX_RETRIES) {
+                retries += 1;
+                backoffOnce();
+                continue;
+            }
+            throw err;
+        }
+    }
+}
+function output(result, raw, rawValue) {
+    let data;
+    if (raw && rawValue !== undefined) {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string
+        data = String(rawValue);
+    }
+    else {
+        const json = JSON.stringify(result, null, 2);
+        // Large payloads exceed Claude Code's Bash tool buffer (~50KB).
+        // Write to tmpfile and output the path prefixed with @file: so callers can detect it.
+        if (json.length > 50000) {
+            reapStaleTempFiles();
+            ensureGsdTempDir();
+            const tmpPath = node_path_1.default.join(GSD_TEMP_DIR, `gsd-${Date.now()}.json`);
+            (0, shell_command_projection_cjs_1.platformWriteSync)(tmpPath, json);
+            data = '@file:' + tmpPath;
+        }
+        else {
+            data = json;
+        }
+    }
+    // process.stdout.write() is async when stdout is a pipe — process.exit()
+    // can tear down the process before the reader consumes the buffer. writeAllSync
+    // pushes every byte synchronously (looping short counts, retrying EAGAIN/EINTR),
+    // and skipping process.exit() lets the event loop drain naturally.
+    writeAllSync(1, data);
+}
+/**
+ * Frozen enum of typed reason codes used by error() for structured errors.
+ * Each subcommand contributes its own codes; the enum exists so tests can
+ * assert against typed values instead of grepping stderr (#2974).
+ *
+ * Adding a new code:
+ *   - Pick a snake_case lowercase value (the JSON wire form)
+ *   - Group by subsystem prefix (CONFIG_*, SDK_*, etc)
+ *   - Pass it to error(msg, ERROR_REASON.NEW_CODE) at the call site
+ */
+const ERROR_REASON = Object.freeze({
+    // config-get / config-set
+    CONFIG_KEY_NOT_FOUND: 'config_key_not_found',
+    CONFIG_NO_FILE: 'config_no_file',
+    CONFIG_PARSE_FAILED: 'config_parse_failed',
+    CONFIG_INVALID_KEY: 'config_invalid_key',
+    // SDK / gsd-tools dispatch
+    SDK_FAIL_FAST: 'sdk_fail_fast',
+    SDK_UNKNOWN_COMMAND: 'sdk_unknown_command',
+    SDK_MISSING_ARG: 'sdk_missing_arg',
+    // workflow / phase
+    PHASE_NOT_FOUND: 'phase_not_found',
+    SUMMARY_NO_PLANNING: 'summary_no_planning',
+    // graphify
+    GRAPHIFY_NO_GRAPH: 'graphify_no_graph',
+    GRAPHIFY_INVALID_QUERY: 'graphify_invalid_query',
+    // hooks
+    HOOKS_OPT_OUT: 'hooks_opt_out',
+    // security-scan
+    SECURITY_SCAN_FAILED: 'security_scan_failed',
+    // generic
+    USAGE: 'usage',
+    UNKNOWN: 'unknown',
+});
+/**
+ * Process-level flag: when true, error() emits structured JSON to stderr
+ * instead of plain "Error: <message>" text. Set by gsd-tools.cjs when the
+ * CLI is invoked with `--json-errors`. Tests opt in to typed-IR error
+ * assertions by passing that flag and parsing the JSON.
+ *
+ * Default off so existing callers and human operators keep their plain-text
+ * diagnostics. The structured form is opt-in for tooling and tests (#2974).
+ */
+let _jsonErrorMode = false;
+function setJsonErrorMode(v) { _jsonErrorMode = !!v; }
+function getJsonErrorMode() { return _jsonErrorMode; }
+/**
+ * Emit an error and exit. When the second argument is provided it must be
+ * a value from ERROR_REASON; tests can assert on `result.reason`. When the
+ * process is in JSON-error mode, stderr receives `{ ok: false, reason,
+ * message }` so callers can parse it; otherwise stderr keeps the plain
+ * text form for human operators.
+ */
+function error(message, reason = ERROR_REASON.UNKNOWN) {
+    if (_jsonErrorMode) {
+        const payload = JSON.stringify({ ok: false, reason, message }) + '\n';
+        writeAllSync(2, payload);
+    }
+    else {
+        writeAllSync(2, 'Error: ' + message + '\n');
+    }
+    process.exit(1);
+}
+module.exports = {
+    GSD_TEMP_DIR,
+    ensureGsdTempDir,
+    reapStaleTempFiles,
+    output,
+    ERROR_REASON,
+    setJsonErrorMode,
+    getJsonErrorMode,
+    error,
+};

package/pp-core/bin/lib/learnings.cjs

@@ -0,0 +1,270 @@
+"use strict";
+/**
+ * Learnings — Global knowledge store with CRUD operations
+ *
+ * Provides a cross-project learnings store at ~/.gsd/knowledge/.
+ * Each learning is stored as an individual JSON file with content-hash
+ * deduplication. Supports write, read, list, query, delete, copy-from-project,
+ * and prune operations.
+ *
+ * Storage format: { id, source_project, date, context, learning, tags, content_hash }
+ * File naming: {id}.json
+ * Deduplication: SHA-256 of learning text + source_project
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/learnings.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only strict types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_os_1 = __importDefault(require("node:os"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const ioMod = require("./io.cjs");
+const { output, error: coreError } = ioMod;
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// ─── Constants ───────────────────────────────────────────────────────────────
+const DEFAULT_STORE_DIR = node_path_1.default.join(node_os_1.default.homedir(), '.gsd', 'knowledge');
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function getStoreDir(opts) {
+    return (opts && opts.storeDir) || DEFAULT_STORE_DIR;
+}
+function ensureStoreDir(dir) {
+    if (!node_fs_1.default.existsSync(dir)) {
+        node_fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+}
+function contentHash(learning, sourceProject) {
+    return node_crypto_1.default.createHash('sha256')
+        .update(learning + '\n' + sourceProject)
+        .digest('hex');
+}
+function generateId() {
+    const ts = Date.now().toString(36);
+    const rand = node_crypto_1.default.randomBytes(4).toString('hex');
+    return `${ts}-${rand}`;
+}
+function readLearningFile(filePath) {
+    try {
+        const content = node_fs_1.default.readFileSync(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (err) {
+        process.stderr.write(`Warning: skipping malformed file ${filePath}: ${err.message}\n`);
+        return null;
+    }
+}
+// ─── CRUD Operations ─────────────────────────────────────────────────────────
+function learningsWrite(entry, opts) {
+    const dir = getStoreDir(opts);
+    ensureStoreDir(dir);
+    const hash = contentHash(entry.learning, entry.source_project);
+    // #306: In bulk-import paths, callers may supply a pre-built dedupeIndex
+    // (Map<content_hash, id>) to avoid the per-write O(N) store scan.
+    if (opts && opts.dedupeIndex) {
+        const dedupeIndex = opts.dedupeIndex;
+        if (dedupeIndex.has(hash)) {
+            return { id: dedupeIndex.get(hash), created: false, content_hash: hash };
+        }
+        const id = generateId();
+        const record = {
+            id,
+            source_project: entry.source_project,
+            date: new Date().toISOString(),
+            context: entry.context || '',
+            learning: entry.learning,
+            tags: entry.tags || [],
+            content_hash: hash,
+        };
+        (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(dir, `${id}.json`), JSON.stringify(record, null, 2));
+        dedupeIndex.set(hash, id);
+        return { id, created: true, content_hash: hash };
+    }
+    // Check for duplicate by scanning existing files (single-write path, unchanged)
+    const files = node_fs_1.default.readdirSync(dir).filter(f => f.endsWith('.json'));
+    for (const file of files) {
+        const existing = readLearningFile(node_path_1.default.join(dir, file));
+        if (existing && existing.content_hash === hash) {
+            return { id: existing.id, created: false, content_hash: hash };
+        }
+    }
+    const id = generateId();
+    const record = {
+        id,
+        source_project: entry.source_project,
+        date: new Date().toISOString(),
+        context: entry.context || '',
+        learning: entry.learning,
+        tags: entry.tags || [],
+        content_hash: hash,
+    };
+    (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(dir, `${id}.json`), JSON.stringify(record, null, 2));
+    return { id, created: true, content_hash: hash };
+}
+function learningsRead(id, opts) {
+    if (!/^[a-z0-9]+-[a-f0-9]+$/.test(id))
+        return null;
+    const dir = getStoreDir(opts);
+    const filePath = node_path_1.default.join(dir, `${id}.json`);
+    if (!node_fs_1.default.existsSync(filePath))
+        return null;
+    return readLearningFile(filePath);
+}
+function learningsList(opts) {
+    const dir = getStoreDir(opts);
+    if (!node_fs_1.default.existsSync(dir))
+        return [];
+    const files = node_fs_1.default.readdirSync(dir).filter(f => f.endsWith('.json'));
+    const results = [];
+    for (const file of files) {
+        const record = readLearningFile(node_path_1.default.join(dir, file));
+        if (record)
+            results.push(record);
+    }
+    // Sort by date descending (newest first)
+    results.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
+    return results;
+}
+function learningsQuery(query, opts) {
+    const all = learningsList(opts);
+    if (query && query.tag) {
+        return all.filter(r => r.tags && r.tags.includes(query.tag));
+    }
+    return all;
+}
+function learningsDelete(id, opts) {
+    if (!/^[a-z0-9]+-[a-f0-9]+$/.test(id))
+        return false;
+    const dir = getStoreDir(opts);
+    const filePath = node_path_1.default.join(dir, `${id}.json`);
+    if (!node_fs_1.default.existsSync(filePath))
+        return false;
+    node_fs_1.default.unlinkSync(filePath);
+    return true;
+}
+function learningsCopyFromProject(planningDir, opts) {
+    const learningsPath = node_path_1.default.join(planningDir, 'LEARNINGS.md');
+    if (!node_fs_1.default.existsSync(learningsPath)) {
+        return { total: 0, created: 0, skipped: 0 };
+    }
+    const content = node_fs_1.default.readFileSync(learningsPath, 'utf-8');
+    const sourceProject = (opts && opts.sourceProject) || node_path_1.default.basename(node_path_1.default.resolve(planningDir, '..'));
+    // #306: Build the content_hash -> id dedupe index once before the loop so
+    // that learningsWrite does not re-scan the entire store on every call —
+    // O(K*N) -> O(N+K).
+    const dir = getStoreDir(opts);
+    ensureStoreDir(dir);
+    const dedupeIndex = new Map();
+    for (const file of node_fs_1.default.readdirSync(dir).filter(f => f.endsWith('.json'))) {
+        const existing = readLearningFile(node_path_1.default.join(dir, file));
+        // First-seen-wins, matching the legacy scan path's first-match return so the
+        // dedupe-hit `id` is identical on both paths even if the store already holds
+        // duplicate content_hashes. (#306)
+        if (existing && existing.content_hash && !dedupeIndex.has(existing.content_hash)) {
+            dedupeIndex.set(existing.content_hash, existing.id);
+        }
+    }
+    // Parse markdown: split on ## headings
+    const sections = content.split(/^## /m).slice(1); // skip preamble before first ##
+    let created = 0;
+    let skipped = 0;
+    for (const section of sections) {
+        const lines = section.trim().split('\n');
+        const title = lines[0].trim();
+        const body = lines.slice(1).join('\n').trim();
+        if (!body)
+            continue;
+        // Extract tags from title (simple: use words as tags)
+        const tags = title.toLowerCase().split(/\s+/).filter(w => w.length > 2);
+        const result = learningsWrite({
+            source_project: sourceProject,
+            learning: body,
+            context: title,
+            tags,
+        }, { ...opts, dedupeIndex });
+        if (result.created) {
+            created++;
+        }
+        else {
+            skipped++;
+        }
+    }
+    return { total: created + skipped, created, skipped };
+}
+function learningsPrune(olderThan, opts) {
+    const match = /^(\d+)d$/.exec(olderThan);
+    if (!match) {
+        throw new Error(`Invalid duration format: "${olderThan}" — expected format like "90d"`);
+    }
+    const days = parseInt(match[1], 10);
+    const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+    const dir = getStoreDir(opts);
+    if (!node_fs_1.default.existsSync(dir))
+        return { removed: 0, kept: 0 };
+    const files = node_fs_1.default.readdirSync(dir).filter(f => f.endsWith('.json'));
+    let removed = 0;
+    let kept = 0;
+    for (const file of files) {
+        const filePath = node_path_1.default.join(dir, file);
+        const record = readLearningFile(filePath);
+        if (!record)
+            continue;
+        const recordDate = new Date(record.date);
+        if (recordDate < cutoff) {
+            node_fs_1.default.unlinkSync(filePath);
+            removed++;
+        }
+        else {
+            kept++;
+        }
+    }
+    return { removed, kept };
+}
+// ─── CLI Command Handlers ────────────────────────────────────────────────────
+function cmdLearningsList(raw) {
+    const results = learningsList();
+    output({ learnings: results, count: results.length }, raw, undefined);
+}
+function cmdLearningsQuery(tag, raw) {
+    const results = learningsQuery({ tag });
+    output({ learnings: results, count: results.length, tag }, raw, undefined);
+}
+function cmdLearningsCopy(cwd, raw) {
+    const planDir = node_path_1.default.join(cwd, '.planning');
+    const result = learningsCopyFromProject(planDir);
+    output(result, raw, undefined);
+}
+function cmdLearningsPrune(olderThan, raw) {
+    try {
+        const result = learningsPrune(olderThan);
+        output(result, raw, undefined);
+    }
+    catch (err) {
+        coreError(err.message);
+    }
+}
+function cmdLearningsDelete(id, raw) {
+    if (!/^[a-z0-9]+-[a-f0-9]+$/.test(id)) {
+        coreError(`Invalid learning ID: "${id}"`);
+    }
+    const deleted = learningsDelete(id);
+    output({ id, deleted }, raw, undefined);
+}
+module.exports = {
+    learningsWrite,
+    learningsRead,
+    learningsList,
+    learningsQuery,
+    learningsDelete,
+    learningsCopyFromProject,
+    learningsPrune,
+    cmdLearningsList,
+    cmdLearningsQuery,
+    cmdLearningsCopy,
+    cmdLearningsPrune,
+    cmdLearningsDelete,
+    DEFAULT_STORE_DIR,
+};