skillspub 0.1.0

package/dist/core.js

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+function lexists(p) {
+    try {
+        fs.lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function migrateLegacyConfig(configDir, legacyDir) {
+    if (configDir === legacyDir || !fs.existsSync(legacyDir))
+        return;
+    fs.mkdirSync(configDir, { recursive: true });
+    for (const entry of fs.readdirSync(legacyDir)) {
+        const destination = path.join(configDir, entry);
+        if (!lexists(destination))
+            fs.cpSync(path.join(legacyDir, entry), destination, { recursive: true });
+    }
+}
+export function defaultHome(options = {}) {
+    const configDir = process.env.SKILLSPUB_CONFIG_DIR ??
+        path.join(os.homedir(), '.config', 'skillspub');
+    // Migration-only: legacy data is copied into canonical config, never used directly.
+    if (options.migrate !== false &&
+        (process.env.SKM_CONFIG_DIR || !process.env.SKILLSPUB_CONFIG_DIR))
+        migrateLegacyConfig(configDir, process.env.SKM_CONFIG_DIR ?? path.join(os.homedir(), '.config', 'skm'));
+    return { configDir };
+}

package/dist/explain.js

@@ -0,0 +1,307 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadTargets, normalizeSlotName, scanGlobalInventory, scanProjectInventory, readStateFile, } from "./inventory.js";
+import { inspectHarnesses } from "./harnesses/registry.js";
+export class ExplainError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.code = code;
+        this.details = details;
+    }
+}
+function resolveResource(report, selector) {
+    const matches = selector.startsWith('skill:')
+        ? report.resources.filter(({ realPath }) => realPath === selector.slice('skill:'.length))
+        : report.resources.filter(({ name }) => name === selector);
+    if (matches.length === 0)
+        throw new ExplainError('installed_resource_not_found', `installed Skill resource not found: ${selector}`, { selector });
+    if (matches.length > 1) {
+        const variants = matches.map(({ id, name, realPath }) => ({
+            name,
+            resourceId: id,
+            realPath,
+            selector: `skill:${realPath}`,
+        }));
+        throw new ExplainError('ambiguous_selector', `skill name "${selector}" is ambiguous; use an explicit skill:<realPath> selector`, { name: selector, matches: variants });
+    }
+    return matches[0];
+}
+function canonicalPath(value) {
+    try {
+        return fs.realpathSync(value);
+    }
+    catch {
+        return path.resolve(value);
+    }
+}
+function directRelationship(root, resource) {
+    const entry = path.join(root, normalizeSlotName(resource.name));
+    try {
+        const stat = fs.lstatSync(entry);
+        const realPath = fs.realpathSync(entry);
+        if (!fs.existsSync(path.join(realPath, 'SKILL.md')))
+            return { relationships: [] };
+        return { relationships: [{
+                    resourceId: realPath,
+                    realPath,
+                    slot: normalizeSlotName(resource.name),
+                    activation: 'on',
+                    form: stat.isSymbolicLink() ? 'link' : 'local',
+                    path: entry,
+                    selected: realPath === resource.realPath,
+                }] };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { relationships: [] };
+        return { relationships: [], error: error.message };
+    }
+}
+function explainRoots(report, resource, harness) {
+    return harness.roots.map((root) => {
+        const target = report.targets.find((candidate) => candidate.key === root.targetKey && candidate.scope === root.scope &&
+            canonicalPath(candidate.discoveryRoot) === canonicalPath(root.discoveryRoot));
+        const direct = target ? undefined : directRelationship(root.discoveryRoot, resource);
+        const relationships = target
+            ? report.relationships
+                .filter(({ targetId, slot }) => targetId === target.id && slot === normalizeSlotName(resource.name))
+                .map((relationship) => ({
+                resourceId: relationship.resourceId,
+                realPath: relationship.realPath,
+                slot: relationship.slot,
+                activation: relationship.activation,
+                form: relationship.form,
+                path: relationship.path,
+                selected: relationship.resourceId === resource.id,
+            }))
+            : direct?.relationships ?? [];
+        return {
+            id: target?.id ?? `external:${harness.key}:${root.targetKey}:${root.scope}:${root.discoveryRoot}`,
+            targetKey: root.targetKey,
+            scope: root.scope,
+            kind: root.kind,
+            path: root.discoveryRoot,
+            consumption: direct?.error ? 'unknown' : root.consumption,
+            reason: direct?.error ? `${root.reason} Inspection failed: ${direct.error}` : root.reason,
+            relationships,
+        };
+    });
+}
+function stateFileForTarget(home, report, targetId) {
+    const target = report.targets.find(({ id }) => id === targetId);
+    if (!target || target.scope === 'global')
+        return path.join(home.configDir, 'state.json');
+    if (target.scope === 'project')
+        return report.stateFile;
+    return path.join(target.sourceDirectory ?? '', '.skillspub', 'state.json');
+}
+function presetClaimStatus(home, report, targetId, slot) {
+    const claims = readStateFile(stateFileForTarget(home, report, targetId)).claims;
+    if (claims === undefined)
+        return 'unclaimed';
+    if (!claims || typeof claims !== 'object' || Array.isArray(claims))
+        return 'unknown';
+    const value = claims[`${targetId}\0${slot}`];
+    if (value === undefined)
+        return 'unclaimed';
+    if (!Array.isArray(value) || value.some((claim) => typeof claim !== 'string'))
+        return 'unknown';
+    return value.length > 0 ? 'claimed' : 'unclaimed';
+}
+function planVisibility(home, report, resource, harness, explanation, wanted) {
+    const blockers = [];
+    if (!harness.detected)
+        blockers.push({ code: 'harness_not_detected', message: `${harness.name} is not detected.` });
+    if (harness.support !== 'managed')
+        blockers.push({ code: 'support_incomplete', message: `${harness.name} support is not managed.` });
+    if (explanation.effectiveVisibility === 'unknown')
+        blockers.push({ code: 'visibility_unknown', message: 'Effective visibility is unknown; no safe plan can be produced.' });
+    if (explanation.conflicts.length > 0)
+        blockers.push({ code: 'unresolved_variant', message: 'Resolve same-name Variants before changing visibility.' });
+    if (blockers.length > 0)
+        return { executable: false, steps: [], blockers };
+    if (wanted === 'visible') {
+        if (explanation.effectiveVisibility === 'visible')
+            return { executable: true, steps: [], blockers: [] };
+        const target = report.targets.find((candidate) => candidate.key === harness.key && candidate.writable &&
+            (report.scope === 'global' ? candidate.scope === 'global' : candidate.scope === 'project'));
+        if (!target)
+            return {
+                executable: false,
+                steps: [],
+                blockers: [{ code: 'no_writable_target', message: `No writable ${harness.name} Target exists in this scope.` }],
+            };
+        const slotName = normalizeSlotName(resource.name);
+        const relationships = report.relationships.filter(({ targetId, slot }) => targetId === target.id && slot === slotName);
+        const selected = relationships.find(({ resourceId }) => resourceId === resource.id);
+        if (!selected && relationships.length > 0)
+            return {
+                executable: false,
+                steps: [],
+                blockers: [{ code: 'target_slot_occupied', message: `${target.id}/${resource.name} is occupied by another Variant.` }],
+            };
+        const form = harness.link.supported ? 'link' : harness.mirror?.supported ? 'mirror' : undefined;
+        if (!selected && !form)
+            return {
+                executable: false,
+                steps: [],
+                blockers: [{ code: 'unsupported_resource_form', message: `${harness.name} cannot safely create this Relationship.` }],
+            };
+        let operation = 'activate';
+        if (!selected)
+            operation = form === 'mirror' ? 'create-mirror' : 'create-link';
+        const from = selected?.activation ?? 'missing';
+        const step = {
+            operation,
+            targetId: target.id,
+            targetKey: target.key,
+            slot: slotName,
+            from,
+            to: 'on',
+            preconditions: [
+                { code: 'resource_identity', message: `Resource must remain ${resource.realPath}.` },
+                { code: 'target_slot_state', message: `${target.id}/${slotName} must remain ${from}.` },
+            ],
+        };
+        const stepForm = selected?.form ?? form;
+        if (stepForm)
+            step.form = stepForm;
+        if (selected)
+            step.path = selected.path;
+        return { executable: true, steps: [step], blockers: [] };
+    }
+    if (explanation.effectiveVisibility === 'not-visible')
+        return { executable: true, steps: [], blockers: [] };
+    const steps = [];
+    for (const root of explanation.roots.filter(({ consumption }) => consumption === 'consumed')) {
+        for (const relationship of root.relationships.filter(({ selected, activation }) => selected && activation === 'on')) {
+            if (root.kind !== 'harness') {
+                blockers.push({
+                    code: 'cross_harness_side_effect',
+                    message: `Hiding ${root.path}/${relationship.slot} would affect other consumers of this ${root.kind} root.`,
+                });
+                continue;
+            }
+            const target = report.targets.find(({ id }) => id === root.id);
+            if (!target?.writable) {
+                blockers.push({
+                    code: 'read_only_contributing_root',
+                    message: `${root.path} is inherited and read-only in this scope.`,
+                });
+                continue;
+            }
+            const claimStatus = presetClaimStatus(home, report, root.id, relationship.slot);
+            if (claimStatus === 'unknown') {
+                blockers.push({
+                    code: 'unknown_preset_claims',
+                    message: `Preset claims for ${root.id}/${relationship.slot} cannot be confirmed.`,
+                });
+                continue;
+            }
+            if (claimStatus === 'claimed') {
+                blockers.push({
+                    code: 'active_preset_claim',
+                    message: `An active Preset claims ${root.id}/${relationship.slot} ON.`,
+                });
+                continue;
+            }
+            steps.push({
+                operation: 'deactivate',
+                targetId: root.id,
+                targetKey: root.targetKey,
+                slot: relationship.slot,
+                from: 'on',
+                to: 'off',
+                form: relationship.form,
+                path: relationship.path,
+                preconditions: [
+                    { code: 'resource_identity', message: `Resource must remain ${resource.realPath}.` },
+                    { code: 'target_slot_state', message: `${root.id}/${relationship.slot} must remain on.` },
+                    { code: 'preset_claims_absent', message: `${root.id}/${relationship.slot} must remain free of Preset claims.` },
+                ],
+            });
+        }
+    }
+    return { executable: blockers.length === 0, steps: blockers.length === 0 ? steps : [], blockers };
+}
+function explainHarness(home, report, resource, harness, wanted) {
+    const roots = explainRoots(report, resource, harness);
+    const consumed = roots.filter(({ consumption }) => consumption === 'consumed');
+    const unknownRoots = roots.filter(({ consumption }) => consumption === 'unknown');
+    const conflicts = consumed.flatMap((root) => root.relationships
+        .filter((relationship) => relationship.slot === normalizeSlotName(resource.name) &&
+        relationship.resourceId !== resource.id && relationship.activation === 'on')
+        .map((relationship) => ({
+        code: 'same_name_variant',
+        message: `${relationship.realPath} competes in consumed root ${root.path}.`,
+        resourceId: relationship.resourceId ?? relationship.realPath ?? relationship.path,
+        realPath: relationship.realPath ?? relationship.path,
+    })));
+    const selectedRoots = consumed.filter((root) => root.relationships.some((relationship) => relationship.selected && relationship.activation === 'on'));
+    let effectiveVisibility;
+    if (!harness.detected || harness.support !== 'managed')
+        effectiveVisibility = 'unknown';
+    else if (conflicts.length > 0)
+        effectiveVisibility = 'conflicted';
+    else if (unknownRoots.length > 0)
+        effectiveVisibility = 'unknown';
+    else
+        effectiveVisibility = selectedRoots.length > 0 ? 'visible' : 'not-visible';
+    const reasons = [];
+    if (!harness.detected)
+        reasons.push({ code: 'harness_not_detected', message: `${harness.name} was not detected locally.` });
+    if (harness.support !== 'managed')
+        reasons.push({ code: 'support_incomplete', message: `${harness.name} support is ${harness.support}.` });
+    for (const root of selectedRoots)
+        reasons.push({ code: 'relationship_consumed', message: `Selected resource is ON in ${root.path}.` });
+    for (const root of unknownRoots)
+        reasons.push({ code: 'root_unknown', message: `Consumption cannot be confirmed for ${root.path}.` });
+    if (effectiveVisibility === 'not-visible')
+        reasons.push({ code: 'no_consumed_relationship', message: 'No consumed root has an ON Relationship to the selected resource.' });
+    const explanation = {
+        key: harness.key,
+        name: harness.name,
+        detected: harness.detected,
+        support: harness.support,
+        evidence: harness.evidence,
+        sharedConsumption: harness.sharedConsumption,
+        isolation: harness.isolation,
+        effectiveVisibility,
+        roots,
+        reasons,
+        warnings: harness.detected ? [{
+                code: 'local_version_unknown',
+                message: `Local ${harness.name} version was not confirmed; discovery semantics use the Adapter's verified evidence.`,
+            }] : [],
+        conflicts,
+    };
+    if (wanted)
+        explanation.plan = planVisibility(home, report, resource, harness, explanation, wanted);
+    return explanation;
+}
+export function explainVisibilityFromInventory(home, report, selector, options = {}, inspected = inspectHarnesses(home, report.targets, report.projectPath)) {
+    const resource = resolveResource(report, selector);
+    let harnesses = [...inspected.detected, ...inspected.available];
+    if (options.harness) {
+        harnesses = harnesses.filter(({ key }) => key === options.harness);
+        if (harnesses.length === 0)
+            throw new ExplainError('unknown_harness', `unknown Harness: ${options.harness}`, {
+                harness: options.harness,
+            });
+    }
+    return {
+        resource: { id: resource.id, name: resource.name, realPath: resource.realPath },
+        scope: { kind: report.scope, ...(report.projectPath ? { projectPath: report.projectPath } : {}) },
+        ...(options.want ? { wanted: options.want } : {}),
+        harnesses: harnesses.map((harness) => explainHarness(home, report, resource, harness, options.want)),
+    };
+}
+export function explainVisibility(home, selector, options = {}) {
+    const targets = loadTargets(home);
+    const report = options.projectPath
+        ? scanProjectInventory(home, options.projectPath, targets, { persist: false })
+        : scanGlobalInventory(home, targets, { persist: false });
+    return explainVisibilityFromInventory(home, report, selector, options);
+}

package/dist/harnesses/claude.js

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { resolveHarnessTarget } from "./target.js";
+const EVIDENCE = [
+    {
+        url: 'https://docs.anthropic.com/en/docs/claude-code/skills',
+        verifiedVersion: 'docs-2026-08-12',
+        detail: 'Claude Code discovers personal and project skills in .claude/skills and supports symlinks.',
+    },
+    {
+        url: 'https://docs.anthropic.com/en/docs/claude-code/settings',
+        verifiedVersion: 'docs-2026-08-12',
+        detail: 'Claude Code settings do not add the Shared Agent Skills directory.',
+    },
+];
+export const claudeAdapter = {
+    key: 'claude',
+    name: 'Claude Code',
+    targetDefinition() {
+        const root = path.join(os.homedir(), '.claude');
+        return {
+            key: 'claude',
+            kind: 'harness',
+            discoveryRoot: path.join(root, 'skills'),
+            parkingRoot: path.join(root, '.skillspub-off', 'skills'),
+            projectPath: '.claude/skills',
+            relationship: { support: 'managed', link: 'supported' },
+        };
+    },
+    inspect(_home, targets, projectPath) {
+        const claudeTarget = resolveHarnessTarget(targets, 'claude', () => claudeAdapter.targetDefinition());
+        const sharedTarget = targets.find(({ key }) => key === 'shared');
+        const projectRoot = projectPath ? path.resolve(projectPath) : undefined;
+        const detected = fs.existsSync(claudeTarget.discoveryRoot) ||
+            fs.existsSync(path.dirname(claudeTarget.discoveryRoot)) ||
+            Boolean(projectRoot && fs.existsSync(path.join(projectRoot, '.claude')));
+        return {
+            key: 'claude',
+            name: 'Claude Code',
+            detected,
+            support: 'managed',
+            evidence: EVIDENCE,
+            targets: [
+                { scope: 'global', discoveryRoot: claudeTarget.discoveryRoot },
+                ...(projectRoot ? [{
+                        scope: 'project',
+                        discoveryRoot: path.join(projectRoot, claudeTarget.projectPath),
+                    }] : []),
+            ],
+            roots: [
+                {
+                    kind: 'harness',
+                    targetKey: 'claude',
+                    scope: 'global',
+                    discoveryRoot: claudeTarget.discoveryRoot,
+                    consumption: 'consumed',
+                    reason: 'Claude Code discovers its Global Skill Target.',
+                },
+                ...(projectRoot ? [{
+                        kind: 'harness',
+                        targetKey: 'claude',
+                        scope: 'project',
+                        discoveryRoot: path.join(projectRoot, claudeTarget.projectPath),
+                        consumption: 'consumed',
+                        reason: 'Claude Code discovers the exact Project Skill Target.',
+                    }] : []),
+                ...(sharedTarget ? [{
+                        kind: 'shared',
+                        targetKey: 'shared',
+                        scope: 'global',
+                        discoveryRoot: sharedTarget.discoveryRoot,
+                        consumption: 'excluded',
+                        reason: 'Claude Code does not consume the Shared Agent Skills root.',
+                    }, ...(projectRoot ? [{
+                            kind: 'shared',
+                            targetKey: 'shared',
+                            scope: 'project',
+                            discoveryRoot: path.join(projectRoot, sharedTarget.projectPath),
+                            consumption: 'excluded',
+                            reason: 'Claude Code does not consume the Project Shared Agent Skills root.',
+                        }] : [])] : []),
+            ],
+            sharedConsumption: {
+                status: 'not-consumed',
+                detail: 'Claude Code does not discover the Shared Agent Skills directory.',
+            },
+            isolation: {
+                status: 'not-required',
+                detail: 'No setup or Harness configuration write is required for independent visibility.',
+            },
+            link: { supported: true },
+        };
+    },
+};