@skillsmith/core 0.8.0 → 0.8.2

package/dist/src/provenance/SourceRecoveryService.js

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview Tiered source-recovery orchestrator.
+ * @module @skillsmith/core/provenance/SourceRecoveryService
+ * @see SMI-5407
+ *
+ * Resolves the canonical GitHub source of each locally-installed skill by
+ * trying tiers in confidence order and short-circuiting on the first hit:
+ *   git remote (exact) -> plugin manifest (high) -> registry name
+ *   (medium/low, review-only) -> embedding (opt-in) -> hints (opt-in) -> unknown.
+ *
+ * The git and plugin tiers are local file reads: they resolve the SOURCE
+ * before any injected dependency is invoked. They then make a best-effort,
+ * OFFLINE call to the optional `findRegistryIdByRepoUrl` (local catalog lookup)
+ * to enrich the manifest id with a registry UUID (SMI-5411) -- never network,
+ * never throws. An offline run never touches the network.
+ */
+import * as os from 'os';
+import * as path from 'path';
+import { SkillParser } from '../indexer/SkillParser.js';
+import { parseGitConfigRemote, normalizeGitHubRemote } from './git-config.js';
+import { parsePluginManifestRepository } from './plugin-manifest.js';
+import { scanLocalSkills } from './local-skill-scan.js';
+const frontmatterParser = new SkillParser({ requireName: false });
+/** Default install root for locally-installed skills. */
+export function defaultSkillsRoot() {
+    return path.join(os.homedir(), '.claude', 'skills');
+}
+function candidateSource(candidate) {
+    return { owner: candidate.owner, repo: candidate.repo, url: candidate.url };
+}
+function resolvedResult(skillName, installPath, source, method, confidence, registryId, candidates = []) {
+    return {
+        skillName,
+        installPath,
+        recoveredSource: source,
+        registryId,
+        method,
+        confidence,
+        candidates,
+        status: 'recovered',
+    };
+}
+function unknownResult(skillName, installPath) {
+    return {
+        skillName,
+        installPath,
+        recoveredSource: null,
+        registryId: null,
+        method: null,
+        confidence: 'unknown',
+        candidates: [],
+        status: 'unknown',
+    };
+}
+function backupResult(skillName, installPath) {
+    return {
+        skillName,
+        installPath,
+        recoveredSource: null,
+        registryId: null,
+        method: null,
+        confidence: 'unknown',
+        candidates: [],
+        status: 'skipped_backup',
+    };
+}
+/** GitHub usernames: 1-39 chars, alphanumeric or hyphen, no leading/trailing hyphen. */
+function isPlausibleOwner(value) {
+    return /^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,37}[a-zA-Z0-9])?$/.test(value);
+}
+function computeSummary(skills) {
+    const summary = {
+        total: skills.length,
+        recovered: 0,
+        already_tracked: 0,
+        unknown: 0,
+        skipped_backup: 0,
+    };
+    for (const skill of skills) {
+        summary[skill.status] += 1;
+    }
+    return summary;
+}
+export class SourceRecoveryService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Best-effort OFFLINE registry-UUID enrichment for a git/plugin source URL.
+     * Returns the catalog UUID for `url`'s repo when the optional dep is wired and
+     * a match exists; null otherwise. NEVER throws -- a missing dep, a no-match, or
+     * a dep failure all degrade to null so the already-resolved (exact/high) source
+     * is never lost. SMI-5411.
+     */
+    async enrichRegistryId(url) {
+        if (!this.deps.findRegistryIdByRepoUrl)
+            return null;
+        try {
+            return await this.deps.findRegistryIdByRepoUrl(url);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Scan `skillsRoot` and resolve every (non-filtered) skill's source. */
+    async recoverSources(opts = {}) {
+        const skillsRoot = opts.skillsRoot ?? defaultSkillsRoot();
+        const entries = await scanLocalSkills(skillsRoot);
+        const only = opts.only;
+        const filtered = only && only.length > 0 ? entries.filter((e) => only.includes(e.skillName)) : entries;
+        const skills = [];
+        for (const entry of filtered) {
+            if (entry.isBackup) {
+                skills.push(backupResult(entry.skillName, entry.dir));
+                continue;
+            }
+            skills.push(await this.recoverOne(entry.dir, entry.skillName, entry.skillMd, {
+                enableEmbedding: opts.enableEmbedding,
+                enableCatalogHint: opts.enableCatalogHint,
+            }));
+        }
+        return { skills, summary: computeSummary(skills) };
+    }
+    /**
+     * Resolve a single skill directory. Tiers short-circuit on the first hit; the
+     * git and plugin tiers resolve the source before any dependency call, then
+     * best-effort enrich the manifest id with a registry UUID via the optional,
+     * OFFLINE `findRegistryIdByRepoUrl`.
+     */
+    async recoverOne(dir, skillName, skillMd, opts = {}) {
+        // Tier 1: git remote (exact) -- source is offline; the id enrichment is a
+        // best-effort offline catalog lookup (SMI-5411).
+        const git = parseGitConfigRemote(dir);
+        if (git) {
+            const registryId = await this.enrichRegistryId(git.url);
+            return resolvedResult(skillName, dir, git, 'git-remote', 'exact', registryId);
+        }
+        // Tier 2: plugin manifest (high) -- same offline id enrichment.
+        const plugin = parsePluginManifestRepository(dir);
+        if (plugin) {
+            const registryId = await this.enrichRegistryId(plugin.url);
+            return resolvedResult(skillName, dir, plugin, 'plugin-json', 'high', registryId);
+        }
+        // Tier 3: registry name match (medium/low) -- REVIEW ONLY.
+        const candidates = await this.deps.findCandidatesByName(skillName);
+        if (candidates.length === 1) {
+            const candidate = candidates[0];
+            return resolvedResult(skillName, dir, candidateSource(candidate), 'registry-name', 'medium', candidate.id);
+        }
+        if (candidates.length > 1) {
+            return this.resolveAmbiguous(dir, skillName, skillMd, candidates, opts);
+        }
+        // Tier 5: hints (opt-in, low).
+        if (opts.enableCatalogHint) {
+            const hint = await this.resolveHint(dir, skillName, skillMd);
+            if (hint)
+                return hint;
+        }
+        // Tier 6: unknown.
+        return unknownResult(skillName, dir);
+    }
+    /** Tier 4: embedding tiebreak over an ambiguous candidate set (opt-in). */
+    async resolveAmbiguous(dir, skillName, skillMd, candidates, opts) {
+        if (opts.enableEmbedding && this.deps.rankByEmbedding && skillMd) {
+            const ranked = await this.deps.rankByEmbedding(skillName, skillMd, candidates);
+            if (ranked.length > 0) {
+                const top = ranked[0];
+                return resolvedResult(skillName, dir, candidateSource(top), 'registry-embedding', 'low', top.id, ranked);
+            }
+        }
+        // Ambiguous and unresolved: surface the candidates for review.
+        return {
+            skillName,
+            installPath: dir,
+            recoveredSource: null,
+            registryId: null,
+            method: 'registry-name',
+            confidence: 'low',
+            candidates,
+            status: 'unknown',
+        };
+    }
+    /** Tier 5 helper: catalog repo_url then a speculative frontmatter author. */
+    async resolveHint(dir, skillName, skillMd) {
+        if (this.deps.lookupCatalogRepoUrl) {
+            const url = await this.deps.lookupCatalogRepoUrl(skillName);
+            if (url) {
+                const source = normalizeGitHubRemote(url);
+                if (source)
+                    return resolvedResult(skillName, dir, source, 'catalog-db', 'low', null);
+            }
+        }
+        if (skillMd) {
+            const fm = frontmatterParser.extractFrontmatter(skillMd);
+            const author = typeof fm?.author === 'string' ? fm.author.trim() : '';
+            if (author && isPlausibleOwner(author)) {
+                const source = {
+                    owner: author,
+                    repo: skillName,
+                    url: `https://github.com/${author}/${skillName}`,
+                };
+                return resolvedResult(skillName, dir, source, 'author-hint', 'low', null);
+            }
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=SourceRecoveryService.js.map

package/dist/src/provenance/SourceRecoveryService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SourceRecoveryService.js","sourceRoot":"","sources":["../../../src/provenance/SourceRecoveryService.ts"],"names":[],"mappings":"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"}

package/dist/src/provenance/backfill.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Backfill recovered sources into the skill manifest.
+ * @module @skillsmith/core/provenance/backfill
+ * @see SMI-5407
+ *
+ * Plans manifest entries from a {@link RecoveryReport} and (when `apply`)
+ * writes them via a single `ManifestManager.updateSafely` merge that ADDs or
+ * fills-missing `source`/`id` but NEVER clobbers a healthy existing entry --
+ * even when the recovered value differs. Idempotent: a second run is a no-op.
+ *
+ * Backfill keys (load-bearing, per plan-review):
+ *   - `id`     = registry UUID when a registry tier resolved it, else `owner/skill-name`.
+ *   - `source` = `https://github.com/<owner>/<repo>` (the form buildRawUrl accepts).
+ */
+import type { SkillManifestEntry } from '../services/skill-installation.types.js';
+import type { RecoveryConfidence, RecoveryReport } from './types.js';
+/** Options controlling a backfill run. */
+export interface BackfillOptions {
+    /** Manifest path. Defaults to `~/.skillsmith/manifest.json`. */
+    manifestPath?: string;
+    /** Minimum confidence to auto-qualify (default `high`). */
+    minConfidence?: RecoveryConfidence;
+    /** Write changes. When false (default), the run is a dry-run plan only. */
+    apply?: boolean;
+    /** Opt-in: write `repository:` into non-git skills' SKILL.md frontmatter. */
+    writeFrontmatter?: boolean;
+    /** Explicit `<dirName> -> 'owner/repo'` overrides (resolved user-specified). */
+    setOverrides?: Record<string, string>;
+    /** Injected `lastUpdated` ISO timestamp for deterministic tests. */
+    now?: string;
+    /** Injected content hasher (defaults to the shared `hashContent`). */
+    hashContent?: (content: string) => string;
+}
+/** Outcome of a backfill run. */
+export interface BackfillOutcome {
+    /** Entries planned for write (all that qualify), regardless of `apply`. */
+    planned: SkillManifestEntry[];
+    /** Skill names actually written (apply only). */
+    written: string[];
+    /** Skill names skipped (unqualified, bad override, or healthy/clobber-protected). */
+    skipped: string[];
+}
+/**
+ * Plan and (optionally) apply manifest backfill for recovered sources.
+ */
+export declare function backfillManifest(report: RecoveryReport, opts?: BackfillOptions): Promise<BackfillOutcome>;
+//# sourceMappingURL=backfill.d.ts.map

package/dist/src/provenance/backfill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backfill.d.ts","sourceRoot":"","sources":["../../../src/provenance/backfill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAA;AAEjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAuB,MAAM,YAAY,CAAA;AAEzF,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,2DAA2D;IAC3D,aAAa,CAAC,EAAE,kBAAkB,CAAA;IAClC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACrC,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,sEAAsE;IACtE,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;CAC1C;AAED,iCAAiC;AACjC,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,OAAO,EAAE,kBAAkB,EAAE,CAAA;IAC7B,iDAAiD;IACjD,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,qFAAqF;IACrF,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAkKD;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,cAAc,EACtB,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,eAAe,CAAC,CAmD1B"}

package/dist/src/provenance/backfill.js

@@ -0,0 +1,206 @@
+/**
+ * @fileoverview Backfill recovered sources into the skill manifest.
+ * @module @skillsmith/core/provenance/backfill
+ * @see SMI-5407
+ *
+ * Plans manifest entries from a {@link RecoveryReport} and (when `apply`)
+ * writes them via a single `ManifestManager.updateSafely` merge that ADDs or
+ * fills-missing `source`/`id` but NEVER clobbers a healthy existing entry --
+ * even when the recovered value differs. Idempotent: a second run is a no-op.
+ *
+ * Backfill keys (load-bearing, per plan-review):
+ *   - `id`     = registry UUID when a registry tier resolved it, else `owner/skill-name`.
+ *   - `source` = `https://github.com/<owner>/<repo>` (the form buildRawUrl accepts).
+ */
+import { existsSync } from 'fs';
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { ManifestManager } from '../services/skill-manifest.js';
+import { hashContent as defaultHashContent } from '../services/skill-installation.helpers.js';
+const CONFIDENCE_RANK = {
+    unknown: 0,
+    low: 1,
+    medium: 2,
+    high: 3,
+    exact: 4,
+    'user-specified': 5,
+};
+function defaultManifestPath() {
+    return path.join(os.homedir(), '.skillsmith', 'manifest.json');
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/** A manifest entry is "healthy" once it carries both a non-empty source and id. */
+function isHealthy(entry) {
+    return nonEmpty(entry.source) && nonEmpty(entry.id);
+}
+/**
+ * Does a result qualify for backfill? The `minConfidence` floor IS the gate
+ * (default `high` -> only exact/high auto-write). Lowering it to `medium`
+ * admits a single registry-name match (which carries the registry UUID, so
+ * `skill_outdated` can resolve it); ambiguous multi-candidate results never
+ * qualify because their `recoveredSource` is null (planResult drops them).
+ * `unknown` never qualifies. SMI-5407.
+ */
+function qualifies(confidence, minConfidence) {
+    if (confidence === 'unknown')
+        return false;
+    return CONFIDENCE_RANK[confidence] >= CONFIDENCE_RANK[minConfidence];
+}
+/** Parse an `owner/repo` override spec. */
+function parseOwnerRepo(spec) {
+    const parts = spec.split('/').filter(Boolean);
+    if (parts.length !== 2)
+        return null;
+    return { owner: parts[0], repo: parts[1] };
+}
+/** Build a complete manifest entry, deriving installedAt/hash from SKILL.md. */
+async function buildEntry(params) {
+    const { installPath, skillName, owner, sourceUrl, registryId, now, hash } = params;
+    const skillMdPath = path.join(installPath, 'SKILL.md');
+    let installedAt = now;
+    let originalContentHash;
+    try {
+        const stat = await fs.stat(skillMdPath);
+        installedAt = stat.mtime.toISOString();
+        const content = await fs.readFile(skillMdPath, 'utf-8');
+        originalContentHash = hash(content);
+    }
+    catch {
+        // SKILL.md unreadable -- fall back to `now` and leave hash undefined.
+    }
+    const id = nonEmpty(registryId ?? undefined) ? registryId : `${owner}/${skillName}`;
+    return {
+        id,
+        name: skillName,
+        version: '1.0.0',
+        source: sourceUrl,
+        installPath,
+        installedAt,
+        lastUpdated: now,
+        originalContentHash,
+    };
+}
+/** Plan one entry from a result; returns null when it does not qualify. */
+async function planResult(result, overrides, minConfidence, now, hash) {
+    const override = overrides[result.skillName];
+    if (override) {
+        const ownerRepo = parseOwnerRepo(override);
+        if (!ownerRepo)
+            return null;
+        return buildEntry({
+            installPath: result.installPath,
+            skillName: result.skillName,
+            owner: ownerRepo.owner,
+            sourceUrl: `https://github.com/${ownerRepo.owner}/${ownerRepo.repo}`,
+            registryId: null,
+            now,
+            hash,
+        });
+    }
+    if (!qualifies(result.confidence, minConfidence) || !result.recoveredSource)
+        return null;
+    return buildEntry({
+        installPath: result.installPath,
+        skillName: result.skillName,
+        owner: result.recoveredSource.owner,
+        sourceUrl: result.recoveredSource.url,
+        registryId: result.registryId,
+        now,
+        hash,
+    });
+}
+/** Fill missing fields from `planned` onto an unhealthy `existing` entry. */
+function mergeEntry(existing, planned) {
+    return {
+        ...existing,
+        id: nonEmpty(existing.id) ? existing.id : planned.id,
+        name: nonEmpty(existing.name) ? existing.name : planned.name,
+        version: nonEmpty(existing.version) ? existing.version : planned.version,
+        source: planned.source, // existing is unhealthy (no source) -- fill it
+        installPath: nonEmpty(existing.installPath) ? existing.installPath : planned.installPath,
+        installedAt: nonEmpty(existing.installedAt) ? existing.installedAt : planned.installedAt,
+        lastUpdated: planned.lastUpdated,
+        originalContentHash: existing.originalContentHash ?? planned.originalContentHash,
+    };
+}
+/**
+ * Write `repository: <url>` into a non-git skill's SKILL.md frontmatter.
+ * Skips git checkouts and skills that already declare a `repository:`.
+ */
+async function maybeWriteFrontmatter(dir, sourceUrl) {
+    if (existsSync(path.join(dir, '.git', 'config')))
+        return false;
+    const skillMdPath = path.join(dir, 'SKILL.md');
+    let content;
+    try {
+        content = await fs.readFile(skillMdPath, 'utf-8');
+    }
+    catch {
+        return false;
+    }
+    if (!content.startsWith('---'))
+        return false;
+    const endIndex = content.indexOf('\n---', 3);
+    if (endIndex === -1)
+        return false;
+    const block = content.slice(0, endIndex);
+    if (/^repository\s*:/m.test(block))
+        return false;
+    const updated = block + `\nrepository: ${sourceUrl}` + content.slice(endIndex);
+    await fs.writeFile(skillMdPath, updated, 'utf-8');
+    return true;
+}
+/**
+ * Plan and (optionally) apply manifest backfill for recovered sources.
+ */
+export async function backfillManifest(report, opts = {}) {
+    const manifestPath = opts.manifestPath ?? defaultManifestPath();
+    const minConfidence = opts.minConfidence ?? 'high';
+    const apply = opts.apply ?? false;
+    const now = opts.now ?? new Date().toISOString();
+    const hash = opts.hashContent ?? defaultHashContent;
+    const overrides = opts.setOverrides ?? {};
+    const planned = [];
+    const plannedByName = new Map();
+    const skipped = [];
+    for (const result of report.skills) {
+        const entry = await planResult(result, overrides, minConfidence, now, hash);
+        if (!entry) {
+            skipped.push(result.skillName);
+            continue;
+        }
+        planned.push(entry);
+        plannedByName.set(result.skillName, entry);
+    }
+    // Dry-run, or nothing qualified: never touch the manifest.
+    if (!apply || plannedByName.size === 0) {
+        return { planned, written: [], skipped };
+    }
+    const written = [];
+    const manager = new ManifestManager(manifestPath);
+    await manager.updateSafely((manifest) => {
+        const installed = { ...manifest.installedSkills };
+        for (const [name, entry] of plannedByName) {
+            const existing = installed[name];
+            if (existing && isHealthy(existing)) {
+                skipped.push(name); // never clobber a healthy entry
+                continue;
+            }
+            installed[name] = existing ? mergeEntry(existing, entry) : entry;
+            written.push(name);
+        }
+        return { ...manifest, installedSkills: installed };
+    });
+    if (opts.writeFrontmatter) {
+        for (const name of written) {
+            const entry = plannedByName.get(name);
+            if (entry)
+                await maybeWriteFrontmatter(entry.installPath, entry.source);
+        }
+    }
+    return { planned, written, skipped };
+}
+//# sourceMappingURL=backfill.js.map

package/dist/src/provenance/backfill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backfill.js","sourceRoot":"","sources":["../../../src/provenance/backfill.ts"],"names":[],"mappings":"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"}

package/dist/src/provenance/git-config.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Recover a skill's GitHub source from its `.git/config` origin.
+ * @module @skillsmith/core/provenance/git-config
+ * @see SMI-5407
+ *
+ * Offline only. No git binary, no network: we parse the INI-style config file
+ * directly. Normalizes both scp-like (`git@github.com:owner/repo.git`) and URL
+ * (`https://github.com/owner/repo.git`) remotes. Non-github hosts return null.
+ */
+import type { RecoveredSource } from './types.js';
+/**
+ * Normalize a raw git remote URL into a canonical {@link RecoveredSource}.
+ * Returns null for non-github hosts or unparseable shapes.
+ */
+export declare function normalizeGitHubRemote(rawUrl: string): RecoveredSource | null;
+/**
+ * Read `<skillDir>/.git/config` and recover the origin remote's GitHub source.
+ * Returns null when the file is missing, has no origin url, or the remote is
+ * not a github.com repository.
+ */
+export declare function parseGitConfigRemote(skillDir: string): RecoveredSource | null;
+//# sourceMappingURL=git-config.d.ts.map

package/dist/src/provenance/git-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-config.d.ts","sourceRoot":"","sources":["../../../src/provenance/git-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AA6BjD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAgC5E;AAoBD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAW7E"}

package/dist/src/provenance/git-config.js

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview Recover a skill's GitHub source from its `.git/config` origin.
+ * @module @skillsmith/core/provenance/git-config
+ * @see SMI-5407
+ *
+ * Offline only. No git binary, no network: we parse the INI-style config file
+ * directly. Normalizes both scp-like (`git@github.com:owner/repo.git`) and URL
+ * (`https://github.com/owner/repo.git`) remotes. Non-github hosts return null.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+const GITHUB_HOSTS = new Set(['github.com', 'www.github.com']);
+/**
+ * Strip a trailing `.git` and any trailing slashes from a repo segment.
+ * Uses string iteration rather than a `/\/+$/`-style regex to avoid CodeQL
+ * `js/polynomial-redos` on the user-controlled `.git/config` content. SMI-5407.
+ */
+function stripGitSuffix(repo) {
+    let end = repo.length;
+    while (end > 0 && repo[end - 1] === '/')
+        end--;
+    const trimmed = repo.slice(0, end);
+    if (trimmed.length >= 4 && trimmed.slice(-4).toLowerCase() === '.git') {
+        return trimmed.slice(0, -4);
+    }
+    return trimmed;
+}
+/**
+ * A safe GitHub owner/repo segment: ASCII alphanumeric plus `.`/`_`/`-`, and
+ * never `.`/`..`. Without this, a crafted `.git/config`
+ * `url = git@github.com:../evil` yields owner `..`, corrupting the stored
+ * `owner/repo` id + URL. SMI-5407 governance.
+ */
+function isSafeSegment(s) {
+    return /^[A-Za-z0-9._-]+$/.test(s) && s !== '.' && s !== '..';
+}
+/**
+ * Normalize a raw git remote URL into a canonical {@link RecoveredSource}.
+ * Returns null for non-github hosts or unparseable shapes.
+ */
+export function normalizeGitHubRemote(rawUrl) {
+    const trimmed = rawUrl.trim();
+    if (!trimmed)
+        return null;
+    let owner;
+    let repo;
+    // scp-like syntax: git@github.com:owner/repo(.git)
+    const scp = /^[^@]+@([^:]+):(.+)$/.exec(trimmed);
+    if (scp && !trimmed.includes('://')) {
+        if (!GITHUB_HOSTS.has(scp[1].toLowerCase()))
+            return null;
+        const segments = scp[2].split('/').filter(Boolean);
+        if (segments.length < 2)
+            return null;
+        owner = segments[0];
+        repo = stripGitSuffix(segments[1]);
+    }
+    else {
+        let parsed;
+        try {
+            parsed = new URL(trimmed);
+        }
+        catch {
+            return null;
+        }
+        if (!GITHUB_HOSTS.has(parsed.hostname.toLowerCase()))
+            return null;
+        const segments = parsed.pathname.split('/').filter(Boolean);
+        if (segments.length < 2)
+            return null;
+        owner = segments[0];
+        repo = stripGitSuffix(segments[1]);
+    }
+    if (!owner || !repo)
+        return null;
+    if (!isSafeSegment(owner) || !isSafeSegment(repo))
+        return null;
+    return { owner, repo, url: `https://github.com/${owner}/${repo}` };
+}
+/** Extract the `url` of the `[remote "origin"]` section from a git config. */
+function extractOriginUrl(config) {
+    let inOrigin = false;
+    for (const line of config.split('\n')) {
+        const trimmed = line.trim();
+        const section = /^\[(.+)\]$/.exec(trimmed);
+        if (section) {
+            inOrigin = /^remote\s+"origin"$/.test(section[1].trim());
+            continue;
+        }
+        if (inOrigin) {
+            const match = /^url\s*=\s*(.+)$/.exec(trimmed);
+            if (match)
+                return match[1].trim();
+        }
+    }
+    return null;
+}
+/**
+ * Read `<skillDir>/.git/config` and recover the origin remote's GitHub source.
+ * Returns null when the file is missing, has no origin url, or the remote is
+ * not a github.com repository.
+ */
+export function parseGitConfigRemote(skillDir) {
+    const configPath = path.join(skillDir, '.git', 'config');
+    let content;
+    try {
+        content = fs.readFileSync(configPath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    const url = extractOriginUrl(content);
+    if (!url)
+        return null;
+    return normalizeGitHubRemote(url);
+}
+//# sourceMappingURL=git-config.js.map

package/dist/src/provenance/git-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-config.js","sourceRoot":"","sources":["../../../src/provenance/git-config.ts"],"names":[],"mappings":"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"}

package/dist/src/provenance/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Public surface of the skill source provenance recovery module.
+ * @module @skillsmith/core/provenance
+ * @see SMI-5407
+ */
+export { parseGitConfigRemote, normalizeGitHubRemote } from './git-config.js';
+export { parsePluginManifestRepository } from './plugin-manifest.js';
+export { scanLocalSkills, type LocalSkillEntry } from './local-skill-scan.js';
+export { SourceRecoveryService, defaultSkillsRoot, type RecoverSourcesOptions, type RecoverOneOptions, } from './SourceRecoveryService.js';
+export { backfillManifest, type BackfillOptions, type BackfillOutcome } from './backfill.js';
+export { normalizeSkillName, skillNameVariants } from './name-variants.js';
+export { METHOD_LABELS, type RecoveryMethod, type RecoveryConfidence, type RecoveredSource, type RecoveryCandidate, type SkillRecoveryStatus, type SkillRecoveryResult, type RecoverySummary, type RecoveryReport, type RecoveryDeps, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/provenance/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/provenance/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AAC7E,OAAO,EAAE,6BAA6B,EAAE,MAAM,sBAAsB,CAAA;AACpE,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC7E,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,GACvB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EAAE,gBAAgB,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAC5F,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC1E,OAAO,EACL,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAA"}