@therocketcode/gsd-core 1.4.0

package/gsd-core/bin/lib/observability/logger.cjs

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * DispatchLogger interface + default implementation — issue #177 (ADR-0174 P1.3).
+ *
+ * Interface:
+ *   { onEvent(event: DispatchEvent): void }
+ *
+ * Default behaviour (createDefaultLogger):
+ *   1. Silent on success — no stdout/stderr when result.kind === 'ok'.
+ *   2. Structured JSON to stderr on error — one line per dispatch error.
+ *   3. Opt-in audit file — when GSD_AUDIT=1 OR config.audit.enabled===true,
+ *      appends every event (success + error) as one JSON line to
+ *      .planning/.gsd-trace.jsonl relative to `cwd`. Creates .planning/ if absent.
+ *   4. Args redaction — args omitted by default; included when GSD_AUDIT_ARGS=1.
+ *
+ * No-op logger (createNoOpLogger):
+ *   Silent on all events. Used as the Hub default when no logger is injected.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/observability/logger.cjs
+ * collapsed to a TypeScript source of truth. Behaviour is preserved
+ * byte-for-behaviour from the prior hand-written .cjs; only 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 redaction_cjs_1 = require("./redaction.cjs");
+const AUDIT_FILE_NAME = '.gsd-trace.jsonl';
+const PLANNING_DIR = '.planning';
+// ─── helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Safely serialise a value to JSON, falling back to a placeholder on circular refs.
+ */
+function _safeStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return JSON.stringify({ _serializationError: true });
+    }
+}
+/**
+ * Determine whether the audit file should be written to.
+ */
+function _isAuditEnabled(config) {
+    if (process.env['GSD_AUDIT'] === '1')
+        return true;
+    if (config && config.audit && config.audit.enabled === true)
+        return true;
+    return false;
+}
+/**
+ * Build the redacted plain object for the audit file.
+ * Preserves the full DispatchEvent structure.
+ */
+function _toAuditRecord(event) {
+    return (0, redaction_cjs_1.redactEvent)(event);
+}
+/**
+ * Build the flattened stderr error line.
+ *
+ * Per ADR-0174 P1.3 contract: { "kind": "<variant>", "traceId": "<uuid>", ...typedPayload }
+ * The result's kind is promoted to top-level and the typed payload fields are spread in.
+ * The `result` wrapper is removed.
+ */
+function _toStderrRecord(event) {
+    const redacted = (0, redaction_cjs_1.redactEvent)(event);
+    const { result, ...eventWithoutResult } = redacted;
+    // Flatten: top-level gets kind + typed payload fields from result
+    const resultObj = result;
+    const { kind, ...typedPayload } = resultObj;
+    return Object.assign({}, eventWithoutResult, { kind }, typedPayload);
+}
+/**
+ * Append one JSON line to the audit file.
+ * Creates .planning/ directory if it does not exist.
+ *
+ * Uses synchronous fs API (crash-safe for v1 — dispatch is synchronous).
+ */
+function _appendAuditLine(cwd, event) {
+    const planningDir = node_path_1.default.join(cwd, PLANNING_DIR);
+    // Ensure the directory exists
+    if (!node_fs_1.default.existsSync(planningDir)) {
+        node_fs_1.default.mkdirSync(planningDir, { recursive: true });
+    }
+    const auditPath = node_path_1.default.join(planningDir, AUDIT_FILE_NAME);
+    node_fs_1.default.appendFileSync(auditPath, _safeStringify(event) + '\n', 'utf8');
+}
+/**
+ * Create a no-op logger. All events are silently dropped.
+ * This is the Hub's default when no logger is injected by the caller.
+ */
+function createNoOpLogger() {
+    return {
+        onEvent(_event) {
+            // intentionally empty
+        },
+    };
+}
+/**
+ * Create the default DispatchLogger.
+ */
+function createDefaultLogger({ cwd = process.cwd(), config } = {}) {
+    return {
+        /**
+         * @param event - A DispatchEvent from the Hub.
+         */
+        onEvent(event) {
+            const resultObj = event && event['result'];
+            const isOk = resultObj && resultObj['kind'] === 'ok';
+            // ── Audit file (both ok and error) ────────────────────────────────────
+            if (_isAuditEnabled(config)) {
+                try {
+                    const auditRecord = _toAuditRecord(event);
+                    _appendAuditLine(cwd, auditRecord);
+                }
+                catch (auditErr) {
+                    // Audit errors must not surface to callers
+                    process.stderr.write(_safeStringify({
+                        level: 'warn',
+                        source: 'DispatchLogger',
+                        message: 'audit file write failed: ' + String(auditErr?.message ?? auditErr),
+                    }) + '\n');
+                }
+            }
+            // ── Stderr on error ───────────────────────────────────────────────────
+            if (!isOk) {
+                try {
+                    const stderrRecord = _toStderrRecord(event);
+                    process.stderr.write(_safeStringify(stderrRecord) + '\n');
+                }
+                catch (stderrErr) {
+                    // Last-resort: we cannot throw from the logger
+                    process.stderr.write(_safeStringify({
+                        level: 'warn',
+                        source: 'DispatchLogger',
+                        message: 'stderr emit failed: ' + String(stderrErr?.message ?? stderrErr),
+                    }) + '\n');
+                }
+            }
+            // ── Silent on success (no else branch needed) ─────────────────────────
+        },
+    };
+}
+module.exports = { createDefaultLogger, createNoOpLogger };

package/gsd-core/bin/lib/observability/redaction.cjs

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Arg redaction policy — issue #177 (ADR-457 build-at-publish: the
+ * hand-written bin/lib/observability/redaction.cjs collapsed to a TypeScript
+ * source of truth). Behaviour is preserved byte-for-behaviour from the prior
+ * hand-written .cjs; only types are added.
+ *
+ * Privacy default: args are OMITTED from every emitted event (both stderr
+ * and file audit). Opt-in: set GSD_AUDIT_ARGS=1 to include args verbatim.
+ *
+ * This module is deliberately simple and has no side effects — redaction
+ * decisions are stateless reads of process.env at call time so that tests
+ * can toggle the env var without module-level caching issues.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldIncludeArgs = shouldIncludeArgs;
+exports.redactEvent = redactEvent;
+/**
+ * Returns true when the caller has opted in to including args in events.
+ * Only GSD_AUDIT_ARGS === '1' enables inclusion; any other value (including
+ * empty string, 'true', 'yes') keeps the default of omitting args.
+ */
+function shouldIncludeArgs() {
+    return process.env.GSD_AUDIT_ARGS === '1';
+}
+/**
+ * Return a redacted copy of a DispatchEvent.
+ *
+ * If args should be omitted (default), strips the `args` field entirely.
+ * If args should be included (GSD_AUDIT_ARGS=1), passes the event through
+ * unchanged (args were already set by makeDispatchEvent with includeArgs:true,
+ * or absent — in which case they stay absent).
+ *
+ * The original event object is never mutated (it is frozen by makeDispatchEvent).
+ *
+ * @param event - A DispatchEvent (frozen or plain).
+ * @returns A new plain object with the same fields, minus args when redacted.
+ */
+function redactEvent(event) {
+    if (shouldIncludeArgs()) {
+        // Include path: return a shallow copy with args preserved if present
+        const copy = Object.assign({}, event);
+        return copy;
+    }
+    // Exclude path: build a copy omitting `args`
+    const { args: _dropped, ...rest } = event;
+    return rest;
+}

package/gsd-core/bin/lib/package-identity.cjs

@@ -0,0 +1,35 @@
+// @generated by scripts/generate-package-identity.cjs from package.json — DO NOT EDIT.
+// Single source for GSD package coordinates (issue #498). Regenerate with:
+//   node scripts/generate-package-identity.cjs
+'use strict';
+
+const packageName = "@therocketcode/gsd-core";
+const binName = "gsd-core";
+const repoSlug = "TheRocketCodeMX/gsd-core";
+const repoUrl = "https://github.com/TheRocketCodeMX/gsd-core";
+const changelogRawUrl = "https://raw.githubusercontent.com/TheRocketCodeMX/gsd-core/main/CHANGELOG.md";
+const cacheSlug = "therocketcode-gsd-core";
+const updateCacheFileName = "gsd-update-check-therocketcode-gsd-core.json";
+
+function formatManualInstall({ packageName, binName, scope, runtime } = {}) {
+  const runtimeFlag = runtime ? ` --${runtime}` : '';
+  return `npx -y --package=${packageName}@latest -- ${binName}${runtimeFlag} --${scope}`;
+}
+
+function manualInstallCommand(opts = {}) {
+  return formatManualInstall({ packageName, binName, scope: opts.scope, runtime: opts.runtime });
+}
+
+module.exports = Object.freeze({
+  packageName,
+  // PACKAGE_NAME: back-compat alias for #516-era consumers. Baked here, so it
+  // survives the installed tree's synthetic package.json (fixes the #378 undefined).
+  PACKAGE_NAME: packageName,
+  binName,
+  repoSlug,
+  repoUrl,
+  changelogRawUrl,
+  cacheSlug,
+  updateCacheFileName,
+  manualInstallCommand,
+});

package/gsd-core/bin/lib/package-legitimacy.cjs

@@ -0,0 +1,368 @@
+"use strict";
+/**
+ * Package Legitimacy Module
+ *
+ * Replaces the bolt-on prose slopcheck gate (which pip-installed `slopcheck`
+ * and degraded ALL packages to [ASSUMED] when pip failed) with registry-API
+ * verdicts computed in code.
+ *
+ * Public interface:
+ *   DEFAULT_THRESHOLDS  — baseline thresholds
+ *   classifyPackage     — pure function: signals → { verdict, reasons }
+ *   checkPackages       — async: resolves registry signals and classifies
+ *   _setHttpGet         — test seam: override the HTTP transport (pass null to restore)
+ *
+ * All network IO is injected via a `registry` client option so that tests
+ * never touch the real network (same seam pattern as clock injection).
+ *
+ * ADR-457 build-at-publish: authored as TypeScript .cts → emits .cjs via tsc.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+const https = __importStar(require("node:https"));
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_THRESHOLDS = {
+    minAgeDays: 30,
+    minWeeklyDownloads: 1000,
+    requireRepo: true,
+};
+// Matches common dangerous postinstall execution patterns.
+// Deliberately EXCLUDES bare https?:// (over-fires on legit packages like
+// esbuild/sharp/node-gyp that reference download URLs without executing them).
+// Shell-execution / download-and-exec signatures only:
+const SUSPICIOUS_POSTINSTALL_RE = /(curl |wget |\|\s*(ba)?sh|bash -c|sh -c|node -e|eval|base64 -d|\/etc\/|\.\.\/|~\/|nc |>\s*\/)/i;
+// ---------------------------------------------------------------------------
+// Severity ordering for verdict merging (SLOP > SUS > OK)
+// ---------------------------------------------------------------------------
+const SEVERITY = { OK: 0, SUS: 1, SLOP: 2 };
+function moreSevereVerdict(a, b) {
+    return SEVERITY[a] >= SEVERITY[b] ? a : b;
+}
+// ---------------------------------------------------------------------------
+// classifyPackage — pure, no IO
+// ---------------------------------------------------------------------------
+function classifyPackage(signals, { thresholds = DEFAULT_THRESHOLDS, clock = Date } = {}) {
+    const reasons = [];
+    // Terminal: package does not exist
+    if (signals.exists === false) {
+        return { verdict: 'SLOP', reasons: ['does-not-exist'] };
+    }
+    // Age check
+    if (signals.publishedAt == null) {
+        reasons.push('unknown-age');
+    }
+    else {
+        const parsed = Date.parse(String(signals.publishedAt));
+        if (!Number.isFinite(parsed)) {
+            // Unparseable date — treat as unknown
+            reasons.push('unknown-age');
+        }
+        else {
+            const ageDays = Math.floor((clock.now() - parsed) / 86_400_000);
+            if (ageDays < thresholds.minAgeDays) {
+                reasons.push('too-new');
+            }
+        }
+    }
+    // Downloads check
+    const downloads = signals.weeklyDownloads;
+    if (downloads == null) {
+        reasons.push('unknown-downloads');
+    }
+    else if (typeof downloads !== 'number' || !Number.isFinite(downloads)) {
+        // Odd type / NaN — treat as unknown
+        reasons.push('unknown-downloads');
+    }
+    else if (downloads < thresholds.minWeeklyDownloads) {
+        reasons.push('low-downloads');
+    }
+    // Repository check
+    if (thresholds.requireRepo && !signals.repoUrl) {
+        reasons.push('no-repository');
+    }
+    // Deprecated check
+    if (signals.deprecated === true) {
+        reasons.push('deprecated');
+    }
+    // Suspicious postinstall (npm only — but apply whenever postinstall is present)
+    if (signals.postinstall != null && typeof signals.postinstall === 'string') {
+        if (SUSPICIOUS_POSTINSTALL_RE.test(signals.postinstall)) {
+            reasons.push('suspicious-postinstall');
+        }
+    }
+    // Terminal: suspicious postinstall is a slopsquatting execution risk
+    if (reasons.includes('suspicious-postinstall')) {
+        return { verdict: 'SLOP', reasons };
+    }
+    const verdict = reasons.length > 0 ? 'SUS' : 'OK';
+    return { verdict, reasons };
+}
+// ---------------------------------------------------------------------------
+// Injectable HTTP transport (test seam — W1)
+// ---------------------------------------------------------------------------
+/** The real HTTPS transport — resolves { statusCode, body } */
+function realHttpsGet(url, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const req = https.get(url, { headers: { 'User-Agent': 'gsd-core-package-legitimacy/1.0' } }, (res) => {
+            const chunks = [];
+            res.on('data', (c) => chunks.push(c));
+            res.on('end', () => resolve({
+                statusCode: res.statusCode ?? 0,
+                body: Buffer.concat(chunks).toString('utf8'),
+            }));
+            res.on('error', reject);
+        });
+        req.setTimeout(timeoutMs, () => {
+            req.destroy(new Error(`timeout after ${timeoutMs}ms`));
+        });
+        req.on('error', reject);
+    });
+}
+/** Module-level transport pointer — overrideable via _setHttpGet for tests */
+let httpsGet = realHttpsGet;
+/**
+ * Test seam: replace the HTTP transport. Pass null to restore the real transport.
+ * Tests call this before exercising a real-adapter code path; always restore in finally.
+ */
+function _setHttpGet(fn) {
+    httpsGet = fn ?? realHttpsGet;
+}
+// ---------------------------------------------------------------------------
+// Real registry adapters (not exercised by tests — tests inject fakes)
+// ---------------------------------------------------------------------------
+function degradedSignals() {
+    return {
+        exists: null,
+        publishedAt: null,
+        weeklyDownloads: null,
+        repoUrl: null,
+        deprecated: false,
+        postinstall: null,
+    };
+}
+async function lookupNpm(name, version) {
+    try {
+        const resp = await httpsGet(`https://registry.npmjs.org/${encodeURIComponent(name)}`, 5000);
+        if (resp.statusCode === 404)
+            return { ...degradedSignals(), exists: false };
+        if (resp.statusCode < 200 || resp.statusCode >= 300)
+            return degradedSignals();
+        const data = JSON.parse(resp.body);
+        if (data.error)
+            return { ...degradedSignals(), exists: false };
+        const time = data.time ?? {};
+        const allVersions = data.versions ?? {};
+        // I3: when a specific version is requested, verify it exists
+        if (version !== undefined) {
+            if (!(version in allVersions)) {
+                return { ...degradedSignals(), exists: false };
+            }
+        }
+        const latestVersion = data['dist-tags']?.latest ?? '';
+        const resolvedVersion = version !== undefined ? version : latestVersion;
+        const versionMeta = allVersions[resolvedVersion] ?? {};
+        const scripts = versionMeta.scripts ??
+            {};
+        const postinstall = scripts.postinstall ?? null;
+        const repoField = versionMeta.repository;
+        let repoUrl = null;
+        if (typeof repoField === 'string')
+            repoUrl = repoField;
+        else if (repoField && typeof repoField.url === 'string') {
+            repoUrl = repoField.url;
+        }
+        const deprecated = typeof versionMeta.deprecated === 'string' ? true : false;
+        // Fetch weekly download count from the npm downloads API
+        let weeklyDownloads = null;
+        try {
+            const dlResp = await httpsGet(`https://api.npmjs.org/downloads/point/last-week/${encodeURIComponent(name)}`, 5000);
+            if (dlResp.statusCode >= 200 && dlResp.statusCode < 300) {
+                const dlData = JSON.parse(dlResp.body);
+                if (typeof dlData.downloads === 'number') {
+                    weeklyDownloads = dlData.downloads;
+                }
+            }
+        }
+        catch {
+            // Degraded: leave weeklyDownloads as null, never throw
+        }
+        return {
+            exists: true,
+            publishedAt: time[resolvedVersion] ?? time.created ?? null,
+            weeklyDownloads,
+            repoUrl,
+            deprecated,
+            postinstall,
+            ecosystem: 'npm',
+        };
+    }
+    catch {
+        return degradedSignals();
+    }
+}
+async function lookupPypi(name, version) {
+    try {
+        const resp = await httpsGet(`https://pypi.org/pypi/${encodeURIComponent(name)}/json`, 5000);
+        if (resp.statusCode === 404)
+            return { ...degradedSignals(), exists: false };
+        if (resp.statusCode < 200 || resp.statusCode >= 300)
+            return degradedSignals();
+        const data = JSON.parse(resp.body);
+        const info = data.info ?? {};
+        // I3: when a specific version is requested, verify it exists in releases
+        const releases = data.releases ?? {};
+        if (version !== undefined) {
+            if (!(version in releases)) {
+                return { ...degradedSignals(), exists: false };
+            }
+        }
+        // Finding 2: when version is provided, derive publishedAt from the
+        // version-specific release record rather than the package-level urls[] array
+        // (which reflects the latest release, not the requested version).
+        let uploadTime = null;
+        if (version !== undefined) {
+            const versionFiles = releases[version] ?? [];
+            uploadTime =
+                versionFiles.length > 0
+                    ? versionFiles[0].upload_time_iso_8601 ?? null
+                    : null;
+        }
+        else {
+            const urls = data.urls ?? [];
+            uploadTime =
+                urls.length > 0 ? urls[0].upload_time_iso_8601 ?? null : null;
+        }
+        const projectUrls = info.project_urls;
+        const repoUrl = projectUrls?.['Source'] ??
+            projectUrls?.['Homepage'] ??
+            info.home_page ??
+            null;
+        return {
+            exists: true,
+            publishedAt: uploadTime,
+            weeklyDownloads: null, // PyPI weekly downloads require a separate API
+            repoUrl: repoUrl || null,
+            deprecated: false, // PyPI doesn't have a first-class deprecated field
+            postinstall: null, // Not applicable for PyPI
+            ecosystem: 'pypi',
+        };
+    }
+    catch {
+        return degradedSignals();
+    }
+}
+async function lookupCrates(name, version) {
+    try {
+        const resp = await httpsGet(`https://crates.io/api/v1/crates/${encodeURIComponent(name)}`, 5000);
+        if (resp.statusCode === 404)
+            return { ...degradedSignals(), exists: false };
+        if (resp.statusCode < 200 || resp.statusCode >= 300)
+            return degradedSignals();
+        const data = JSON.parse(resp.body);
+        const krate = data.crate ?? {};
+        // I3: when a specific version is requested, verify it exists in versions list
+        const versions = data.versions ?? [];
+        if (version !== undefined) {
+            const found = versions.some((v) => v.num === version);
+            if (!found) {
+                return { ...degradedSignals(), exists: false };
+            }
+        }
+        const repoUrl = krate.repository ?? null;
+        // Finding 2: when version is provided, use the version-specific created_at
+        // rather than the package-level crate.created_at (first-ever publish date).
+        let created;
+        if (version !== undefined) {
+            const versionObj = versions.find((v) => v.num === version);
+            created = versionObj?.created_at ?? null;
+        }
+        else {
+            created = krate.created_at ?? null;
+        }
+        // recent_downloads is a 90-day count; normalize to a weekly figure for comparison
+        // against minWeeklyDownloads (which is a weekly threshold).
+        const rawDownloads = krate.recent_downloads;
+        const downloads = (rawDownloads != null && typeof Number(rawDownloads) === 'number' && !isNaN(Number(rawDownloads)))
+            ? Math.round(Number(rawDownloads) * 7 / 90)
+            : null;
+        return {
+            exists: true,
+            publishedAt: created,
+            weeklyDownloads: downloads,
+            repoUrl,
+            deprecated: false,
+            postinstall: null,
+            ecosystem: 'crates',
+        };
+    }
+    catch {
+        return degradedSignals();
+    }
+}
+const realRegistry = {
+    async lookup(ecosystem, name, version) {
+        switch (ecosystem) {
+            case 'npm':
+                return lookupNpm(name, version);
+            case 'pypi':
+                return lookupPypi(name, version);
+            case 'crates':
+                return lookupCrates(name, version);
+            default:
+                return degradedSignals();
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// checkPackages — orchestrates lookup + classify + slopcheck merge
+// ---------------------------------------------------------------------------
+async function checkPackages({ ecosystem, packages, version }, { registry = realRegistry, clock = Date, thresholds = DEFAULT_THRESHOLDS, slopcheck = null, } = {}) {
+    const results = [];
+    for (const name of packages) {
+        const signals = await registry.lookup(ecosystem, name, version);
+        const { verdict: registryVerdict, reasons } = classifyPackage(signals, { thresholds, clock });
+        let finalVerdict = registryVerdict;
+        if (slopcheck != null) {
+            const slopVerdict = await slopcheck.check(ecosystem, name);
+            if (slopVerdict != null) {
+                finalVerdict = moreSevereVerdict(finalVerdict, slopVerdict);
+            }
+        }
+        results.push({ name, verdict: finalVerdict, signals, reasons });
+    }
+    return results;
+}
+module.exports = { DEFAULT_THRESHOLDS, classifyPackage, checkPackages, _setHttpGet };