@therocketcode/gsd-core 1.4.0

package/gsd-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 core = require("./core.cjs");
+const { output, error: coreError } = core;
+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,
+};

package/gsd-core/bin/lib/legacy-cleanup.cjs

@@ -0,0 +1,253 @@
+'use strict';
+
+/**
+ * legacy-cleanup.cjs — detect and remove leftover artifacts from the old package.
+ *
+ * Provides a pure-ish scan phase (planLegacyCleanup) and a thin IO applier
+ * (applyLegacyCleanup) that together root out stale files from the old
+ * package across every GSD-managed runtime config directory.
+ *
+ * Issue: #607
+ *
+ * House style: CommonJS, 'use strict', pure functions + thin IO appliers.
+ * Seams (opts.fs, opts.logger) allow full unit-test coverage without touching
+ * the real filesystem except in the apply phase.
+ */
+
+const os   = require('os');
+const path = require('path');
+const fs   = require('fs');
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+/**
+ * Substring that identifies a file as belonging to the old package.
+ * Assembled from parts so this source file itself never contains the literal
+ * as a plain substring (avoids self-flagging if the content scan were ever
+ * widened back to include this subtree).
+ */
+const OLD_PACKAGE_SIGNAL = 'gsd-core' + '-cc';
+
+/**
+ * Subtrees within a configDir that GSD actively scans for old-package content.
+ * Deliberately excludes 'gsd-core' — the current package's own infra and
+ * docs live there (CHANGELOG.md, this file, etc.) and are overwritten by
+ * install anyway. Poisoning hooks from the old package live in 'hooks/', which
+ * IS scanned.
+ */
+const GSD_MANAGED_SUBTREES = ['hooks', 'commands'];
+
+/**
+ * Extensions eligible for the content-reference scan.
+ *
+ * WHY: The current @therocketcode/gsd-core package ships ZERO references to the old
+ * package name in any code file (.js/.cjs/.mjs/.sh). Therefore a code file
+ * that still contains that string is genuinely a leftover from the old package
+ * and is safe to flag.
+ *
+ * Markdown, JSON, TOML, YAML, and other doc/config files, however,
+ * legitimately cite the old name in historical or reference context
+ * (e.g. CHANGELOG.md, workflow .md files). Scanning them caused the
+ * installer to delete the freshly-installed gsd-core/CHANGELOG.md,
+ * breaking installs. Fix: restrict the content scan to code extensions only.
+ */
+const CODE_EXTENSIONS = new Set(['.js', '.cjs', '.mjs', '.sh']);
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Return true if any segment of the absolute file path is `dev-preferences`
+ * or the file is named `dev-preferences.md`. These are always user artifacts.
+ *
+ * @param {string} absPath
+ * @returns {boolean}
+ */
+function isDevPreferencesPath(absPath) {
+  const parts = absPath.split(path.sep);
+  return parts.some(
+    (seg) => seg === 'dev-preferences' || seg === 'dev-preferences.md'
+  );
+}
+
+/**
+ * Recursively collect all file paths under `dir` (bounded; skips
+ * unreadable entries silently).
+ *
+ * @param {string} dir
+ * @param {object} fsMod - injectable fs module
+ * @returns {string[]} absolute file paths
+ */
+function collectFilesUnder(dir, fsMod) {
+  const results = [];
+  let entries;
+  try {
+    entries = fsMod.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectFilesUnder(full, fsMod));
+    } else if (entry.isFile()) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * Return true if the file at `absPath` contains the old-package substring.
+ * Skips unreadable files (returns false on any error).
+ *
+ * @param {string} absPath
+ * @param {object} fsMod
+ * @returns {boolean}
+ */
+function fileContainsOldPackageSignal(absPath, fsMod) {
+  try {
+    const content = fsMod.readFileSync(absPath, 'utf8');
+    return content.includes(OLD_PACKAGE_SIGNAL);
+  } catch {
+    return false;
+  }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Scan `configDirs` for leftover old-package artifacts and the legacy
+ * shared cache, returning an ordered array of removal candidates.
+ *
+ * Possible reasons in returned entries:
+ *   - 'content-references-old-package': a code file whose content contains
+ *     the old package name signal (hooks/ and commands/ subtrees only).
+ *   - 'legacy-shared-cache': the old package's shared update-check cache file.
+ *
+ * @param {string[]} configDirs - absolute paths to runtime config dirs to scan
+ * @param {object}  [opts]
+ * @param {string}  [opts.homeDir]  - home directory (default: os.homedir())
+ * @param {object}  [opts.fs]       - injectable fs module (default: require('node:fs'))
+ * @returns {{ path: string, reason: string }[]}
+ */
+function planLegacyCleanup(configDirs, opts = {}) {
+  const homeDir  = opts.homeDir || os.homedir();
+  const fsMod    = opts.fs || fs;
+
+  /** @type {Map<string, string>} path → reason (de-dup by path) */
+  const candidates = new Map();
+
+  const addCandidate = (absPath, reason) => {
+    if (!candidates.has(absPath)) {
+      candidates.set(absPath, reason);
+    }
+  };
+
+  for (const configDir of configDirs) {
+    for (const subtree of GSD_MANAGED_SUBTREES) {
+      const subtreeDir = path.join(configDir, subtree);
+
+      // Collect all files under this subtree (skip if absent)
+      const files = collectFilesUnder(subtreeDir, fsMod);
+
+      for (const absPath of files) {
+        // Never flag user-authored dev-preferences artifacts
+        if (isDevPreferencesPath(absPath)) continue;
+
+        // Content signal: code files referencing the old package name.
+        // Only scan files with code extensions — docs/config files (.md, .json,
+        // .yml, etc.) legitimately cite the old name in historical context and
+        // must never be deleted (see CODE_EXTENSIONS declaration above).
+        const ext = path.extname(absPath).toLowerCase();
+        if (CODE_EXTENSIONS.has(ext) && fileContainsOldPackageSignal(absPath, fsMod)) {
+          addCandidate(absPath, 'content-references-old-package');
+        }
+      }
+    }
+  }
+
+  // Legacy shared cache (fixed name from the old package)
+  const legacyCachePath = path.join(homeDir, '.cache', 'gsd', 'gsd-update-check.json');
+  try {
+    const stat = fsMod.statSync(legacyCachePath);
+    if (stat.isFile()) {
+      addCandidate(legacyCachePath, 'legacy-shared-cache');
+    }
+  } catch {
+    // absent — skip
+  }
+
+  // Sort deterministically by path
+  const sorted = [...candidates.entries()]
+    .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+    .map(([p, reason]) => ({ path: p, reason }));
+
+  return sorted;
+}
+
+/**
+ * Execute the plan returned by `planLegacyCleanup`.
+ *
+ * @param {{ path: string, reason: string }[]} plan
+ * @param {object}  [opts]
+ * @param {boolean} [opts.dryRun=false] - when true, log but do not remove
+ * @param {object}  [opts.fs]           - injectable fs module
+ * @param {object}  [opts.logger]       - injectable logger (default: console)
+ * @returns {{ removed: string[], skipped: string[], errors: Array<{path:string,error:string}>, dryRun: boolean }}
+ */
+function applyLegacyCleanup(plan, opts = {}) {
+  const dryRun  = opts.dryRun === true;
+  const fsMod   = opts.fs || fs;
+  const logger  = opts.logger || console;
+
+  if (dryRun) {
+    for (const item of plan) {
+      logger.log('[dry-run] would remove: ' + item.path + '  (' + item.reason + ')');
+    }
+    return {
+      removed: [],
+      skipped: plan.map((item) => item.path),
+      errors: [],
+      dryRun: true,
+    };
+  }
+
+  const removed = [];
+  const errors  = [];
+
+  for (const item of plan) {
+    let lastErr;
+    const maxAttempts = process.platform === 'win32' ? 3 : 1;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      try {
+        if (attempt > 0) {
+          // Synchronous 100ms delay before retry (win32 EBUSY/EPERM from Defender)
+          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+        }
+        fsMod.rmSync(item.path, { force: true });
+        lastErr = undefined;
+        break;
+      } catch (err) {
+        lastErr = err;
+        if (process.platform !== 'win32' ||
+            (err.code !== 'EBUSY' && err.code !== 'EPERM')) {
+          break; // non-retryable error; stop immediately
+        }
+      }
+    }
+    if (lastErr) {
+      errors.push({ path: item.path, error: lastErr.message });
+    } else {
+      removed.push(item.path);
+    }
+  }
+
+  return { removed, skipped: [], errors, dryRun: false };
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  planLegacyCleanup,
+  applyLegacyCleanup,
+};