@opengsd/gsd-core 1.3.0 → 1.4.0-rc.1

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 };

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

@@ -550,7 +550,7 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
         let _newPhaseId;
         let _dirName;
         if (customId || config.phase_naming === 'custom') {
-            _newPhaseId = customId || slug.toUpperCase().replace(/-/g, '-');
+            _newPhaseId = customId || slug.toUpperCase();
             if (!_newPhaseId)
                 error('--id required when phase_naming is "custom"');
             _dirName = `${prefix}${_newPhaseId}-${slug}`;
@@ -658,7 +658,7 @@ function cmdPhaseAddBatch(cwd, descriptions, raw) {
             let newPhaseId;
             let dirName;
             if (config.phase_naming === 'custom') {
-                newPhaseId = slug.toUpperCase().replace(/-/g, '-');
+                newPhaseId = slug.toUpperCase();
                 dirName = `${prefix}${newPhaseId}-${slug}`;
             }
             else {
@@ -913,7 +913,7 @@ function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, rem
             content = content.replace(/(#{2,4}\s*Phase\s+)(\d+(?:\.\d+)?)(\s*:)/gi, (_match, prefix, num, suffix) => `${prefix}${decrementRoadmapPhaseToken(num, removedInt)}${suffix}`);
             content = content.replace(/(-\s*\[[ x]\]\s*.*?Phase\s+)(\d+)(\s*:|\s+)/gi, (_match, prefix, num, suffix) => `${prefix}${decrementRoadmapPhaseNumber(num, removedInt)}${suffix}`);
             content = content.replace(/(\|\s*)(\d+)(\.\s)/g, (_match, prefix, num, suffix) => `${prefix}${decrementRoadmapPhaseNumber(num, removedInt)}${suffix}`);
-            content = content.replace(/(?<![0-9-])(\d{2})-(\d{2})(?=(?:(?:-[A-Za-z][A-Za-z0-9-]*)*-(?:PLAN|SUMMARY)\.md)|(?![0-9-]))/g, (_match, phaseNum, planNum) => `${decrementRoadmapPaddedPhaseNumber(phaseNum, removedInt)}-${planNum}`);
+            content = content.replace(/(?<![0-9-])(\d{2})-(\d{2})(?=(?:(?:-[A-Za-z][A-Za-z0-9-]*)?-(?:PLAN|SUMMARY)\.md)|(?![0-9-]))/g, (_match, phaseNum, planNum) => `${decrementRoadmapPaddedPhaseNumber(phaseNum, removedInt)}-${planNum}`);
             content = content.replace(/(\*\*Depends on\*\*\s*:\s*Phase\s+)(\d+(?:\.\d+)?)\b/gi, (_match, prefix, num) => `${prefix}${decrementRoadmapPhaseToken(num, removedInt)}`);
             content = content.replace(/(Depends on:\*\*\s*Phase\s+)(\d+(?:\.\d+)?)\b/gi, (_match, prefix, num) => `${prefix}${decrementRoadmapPhaseToken(num, removedInt)}`);
         }

package/gsd-core/bin/lib/research-provider.cjs

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * Research Provider Module
+ *
+ * Encodes the Balanced-set provider decision: PROVIDER_WATERFALL constant,
+ * classifyConfidence, providerAvailability, and planResearch (with injectable
+ * store for testability).
+ *
+ * ADR-457 build-at-publish: authored as TypeScript .cts → emits .cjs via tsc.
+ */
+// ---------------------------------------------------------------------------
+// Cycle 1 / Cycle 6: PROVIDER_WATERFALL (Balanced-set decision)
+// firecrawl appears ONLY in scrape — demoted to known-URL scrape, NOT in docs/web
+// ---------------------------------------------------------------------------
+const PROVIDER_WATERFALL = {
+    docs: ['context7', 'ref', 'jina', 'websearch'],
+    web: ['exa', 'tavily', 'perplexity', 'brave', 'websearch'],
+    scrape: ['firecrawl', 'jina'],
+};
+function authorityOf(provider) {
+    switch (provider) {
+        case 'context7':
+        case 'ref':
+            return 'official';
+        case 'jina':
+        case 'firecrawl':
+            return 'scrape';
+        case 'exa':
+        case 'tavily':
+        case 'perplexity':
+        case 'brave':
+        case 'websearch':
+            return 'web';
+        default:
+            return 'none';
+    }
+}
+function normalizeLegitimacyVerdict(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const upper = raw.toUpperCase();
+    if (upper === 'OK' || upper === 'SUS' || upper === 'SLOP')
+        return upper;
+    return null;
+}
+function classifyConfidence(input) {
+    try {
+        const { provider, verifiedAgainstOfficial, legitimacyVerdict } = input;
+        const authority = authorityOf(provider);
+        const verdict = normalizeLegitimacyVerdict(legitimacyVerdict);
+        const groundTruth = verdict === 'OK';
+        // SLOP caps everything — checked first
+        if (verdict === 'SLOP')
+            return 'LOW';
+        // Ground-truth corroboration + known authority → HIGH
+        if (groundTruth && authority !== 'none')
+            return 'HIGH';
+        // Official or scrape provider (authority alone) → MEDIUM
+        if (authority === 'official' || authority === 'scrape')
+            return 'MEDIUM';
+        // Ground-truth but unknown provider → MEDIUM
+        if (groundTruth)
+            return 'MEDIUM';
+        // Web provider with self-reported verification → MEDIUM
+        if (authority === 'web' && verifiedAgainstOfficial === true)
+            return 'MEDIUM';
+        return 'LOW';
+    }
+    catch {
+        return 'LOW';
+    }
+}
+// ---------------------------------------------------------------------------
+// Cycle 5: providerAvailability
+// ---------------------------------------------------------------------------
+function providerAvailability(config) {
+    const cfg = config ?? {};
+    return {
+        context7: true,
+        jina: cfg.jina !== undefined ? Boolean(cfg.jina) : true,
+        websearch: true,
+        exa: Boolean(cfg.exa_search),
+        tavily: Boolean(cfg.tavily_search),
+        brave: Boolean(cfg.brave_search),
+        firecrawl: Boolean(cfg.firecrawl),
+        ref: Boolean(cfg.ref_search),
+        perplexity: Boolean(cfg.perplexity),
+    };
+}
+// ---------------------------------------------------------------------------
+// Lazy-load default store (avoids circular require at module eval time)
+// ---------------------------------------------------------------------------
+let _defaultStore;
+function getDefaultStore() {
+    if (!_defaultStore) {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports -- lazy default store; tests inject their own
+        _defaultStore = require('./research-store.cjs');
+    }
+    return _defaultStore;
+}
+// ---------------------------------------------------------------------------
+// Cycle 1–3, 5, 7: planResearch
+// ---------------------------------------------------------------------------
+function planResearch(options) {
+    const { questions, ecosystem = '', cwd, config, clock = Date, homeDir, store = getDefaultStore(), } = options;
+    const availability = providerAvailability(config);
+    const items = questions.flatMap((q) => {
+        const { text, kind, library, version } = q;
+        // Skip questions without a non-empty string text — emitting an item with
+        // question:undefined / fetch.query:undefined would produce corrupt output.
+        if (typeof text !== 'string' || text.length === 0) {
+            return [];
+        }
+        const key = store.researchKey({ ecosystem, library, version, query: text, kind });
+        const res = store.getResearch(cwd, key, { clock, homeDir, kind });
+        // Fresh cache hit — no fetch needed
+        if (res.hit && !res.stale) {
+            return { question: text, key, cache: { hit: true, stale: false } };
+        }
+        // Determine which waterfall to use
+        const waterfall = PROVIDER_WATERFALL[kind] ?? PROVIDER_WATERFALL.web;
+        // Pick first available provider
+        const provider = waterfall.find((p) => availability[p] === true) ?? 'websearch';
+        const item = {
+            question: text,
+            key,
+            fetch: { provider, query: text },
+        };
+        // Stale hit: include cache info
+        if (res.hit) {
+            item.cache = { hit: true, stale: true };
+        }
+        return item;
+    });
+    return { items };
+}
+module.exports = { PROVIDER_WATERFALL, classifyConfidence, providerAvailability, planResearch };