skillspub 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AlligatorT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# SkillsPub
+
+SkillsPub switches Agent Skills on and off across AI coding harnesses — Pi, Claude Code, and Grok Build — from one place. It reads the disk as the source of truth, shows what each harness will pick up on its next load, and prints an immutable preview before any change is written.
+
+## Requirements
+
+- Node.js 22.20 or newer
+
+## Compatibility
+
+Remote Source operations go through one pinned Vercel `skills` release (`skills@1.5.21`), so release behavior does not drift with upstream `latest`.
+
+Harness support levels are enforced by `npm run audit:release`. The verified-version evidence each adapter was accepted against:
+
+| Harness | Support | Verified against |
+| --- | --- | --- |
+| Pi | `managed` | v0.85.1 |
+| Claude Code | `managed` | docs snapshot 2026-08-12 |
+| Grok Build | `managed/excluded` | settings reference @ `19d42e35` |
+
+`discoverable` candidates (Codex, OpenCode, Kimi Code, TraeCode) are observed only and carry no verified-version claim.
+
+## Install
+
+```sh
+npm install --global skillspub
+```
+
+Or without a global install: `npx skillspub targets`.
+
+## First run
+
+There is no setup step. SkillsPub discovers installed skills and harnesses by scanning the disk, so open the TUI and everything is already there:
+
+```sh
+skillspub
+```
+
+All browsing is read-only; nothing changes without an explicit confirmed plan. One optional configuration exists: Pi's Shared-skills isolation, applied only when you ask for it:
+
+```sh
+skillspub harnesses pi setup   # prints a preview; rerun with --yes to apply
+```
+
+Claude Code and Grok Build need no setup.
+
+## TUI
+
+`skillspub` in a terminal opens the full-screen browser (same as `skillspub tui`; add `--project [path]` for a project-scope view). It is keyboard-driven: browse the skill × Target matrix, toggle skills, manage Tags, Bundles, and Presets, and run the Source lifecycle (find, add, update, remove) with preview → confirm → verify for every mutation.
+
+## CLI
+
+Everything the TUI does is also a scriptable command:
+
+| Group | Commands |
+| --- | --- |
+| Inspect | `scan` · `ls` · `status <skill>` · `explain <skill>` · `targets` · `doctor` |
+| Toggle | `on\|off <selector> <target...> [--yes]` |
+| Organize | `tag` · `bundle` · `preset` (persistent always-on policy) |
+| Sources | `shared find\|describe\|refresh\|outdated\|add\|update\|remove` |
+| Harnesses | `harnesses [name inspect\|setup\|reconcile [--yes]]` |
+| Project scope | prefix any of the above with `project <exact-path>` |
+
+Every mutation prints its plan first and applies only with `--yes`.
+
+## Development
+
+```sh
+npm ci
+npm run typecheck
+npm test
+npm run build
+npm run audit:release
+npm run check:package
+npm pack --ignore-scripts
+npm run check:package -- ./skillspub-0.1.0.tgz
+npm pack --dry-run --ignore-scripts
+```
+
+`check:package` packs twice, verifies byte-for-byte deterministic tarballs and the exact file allowlist, installs one tarball into a clean temporary prefix, then runs the installed CLI and a read-only JSON command. Pass a candidate tarball path to require a byte-for-byte match with the verified package.
+
+Release prerequisites and the cutover checklist are in [`docs/releasing.md`](docs/releasing.md).
+
+## License
+
+MIT © 2026 AlligatorT

package/dist/catalog.js

@@ -0,0 +1,352 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readStateFile, writeStateFile, } from "./inventory.js";
+export function statePath(home) {
+    return path.join(home.configDir, 'state.json');
+}
+export function readState(home) {
+    return readStateFile(statePath(home));
+}
+export function writeState(home, state) {
+    writeStateFile(statePath(home), state);
+}
+export function readBundles(state) {
+    const value = state.bundles ?? {};
+    if (!value || typeof value !== 'object' || Array.isArray(value) ||
+        Object.values(value).some((members) => !Array.isArray(members) || members.some((member) => typeof member !== 'string')))
+        throw new Error('invalid state bundles');
+    return value;
+}
+export function readTags(state) {
+    const value = state.tags ?? {};
+    if (!value || typeof value !== 'object' || Array.isArray(value) ||
+        Object.values(value).some((tags) => !Array.isArray(tags) || tags.some((tag) => typeof tag !== 'string')))
+        throw new Error('invalid state tags');
+    return value;
+}
+function resources(state) {
+    return state.targetInventory?.resources ?? {};
+}
+function assertManualBundle(name) {
+    if (!name || name.startsWith('repo:'))
+        throw new Error('manual bundle names must be non-empty and cannot start with repo:');
+}
+function resourceId(selector, state, existingMembers = []) {
+    const value = selector.startsWith('skill:') ? selector.slice('skill:'.length) : selector;
+    if (!value)
+        throw new Error(`invalid skill selector: ${selector}`);
+    if (existingMembers.includes(value))
+        return value;
+    const entries = Object.entries(resources(state));
+    if (resources(state)[value])
+        return value;
+    const matches = entries.filter(([, metadata]) => metadata.name === value);
+    if (matches.length === 1)
+        return matches[0][0];
+    if (matches.length > 1) {
+        throw new Error(`skill name "${value}" is ambiguous:\n${matches
+            .map(([id, metadata]) => `  - ${metadata.name}: skill:${id}`)
+            .join('\n')}\nUse one of the explicit selectors above.`);
+    }
+    throw new Error(`skill not found: ${selector}; run skillspub scan first`);
+}
+export function listBundles(home) {
+    const bundles = readBundles(readState(home));
+    return Object.entries(bundles)
+        .map(([name, members]) => ({ name, members: members.length }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+export function showBundle(home, name) {
+    const state = readState(home);
+    const members = readBundles(state)[name];
+    if (!members)
+        throw new Error(`unknown bundle: ${name}`);
+    const current = resources(state);
+    return members.map((id) => ({
+        id,
+        name: current[id]?.name,
+        stale: current[id] === undefined || !fs.existsSync(id),
+    }));
+}
+export function createBundle(home, name, selectors) {
+    const plan = planCatalogMutation(home, undefined, {
+        operation: 'bundle.create', name, selectors,
+    });
+    applyCatalogMutation(home, plan);
+    return plan.changed;
+}
+export function addBundleMembers(home, name, selectors) {
+    const plan = planCatalogMutation(home, undefined, {
+        operation: 'bundle.add', name, selectors,
+    });
+    applyCatalogMutation(home, plan);
+    return plan.changed;
+}
+export function removeBundleMembers(home, name, selectors) {
+    const plan = planCatalogMutation(home, undefined, {
+        operation: 'bundle.rm', name, selectors: selectors ?? [],
+    });
+    applyCatalogMutation(home, plan);
+    return selectors?.length ? plan.changed : undefined;
+}
+function assertTagNames(tags) {
+    if (tags.length === 0 || tags.some((tag) => !tag))
+        throw new Error('at least one non-empty tag is required');
+}
+export function addResourceTags(home, selector, names) {
+    const plan = planCatalogMutation(home, undefined, {
+        operation: 'tag.add', resource: selector, names,
+    });
+    applyCatalogMutation(home, plan);
+    return plan.changed;
+}
+export function removeResourceTags(home, selector, names) {
+    const plan = planCatalogMutation(home, undefined, {
+        operation: 'tag.rm', resource: selector, names: names ?? [],
+    });
+    applyCatalogMutation(home, plan);
+    return plan.changed;
+}
+export function listTags(home) {
+    const counts = new Map();
+    for (const names of Object.values(readTags(readState(home))))
+        for (const name of names)
+            counts.set(name, (counts.get(name) ?? 0) + 1);
+    return [...counts].map(([name, resources]) => ({ name, resources }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+export function tagsForResource(home, selector) {
+    const state = readState(home);
+    const tags = readTags(state);
+    const id = resourceId(selector, state, Object.keys(tags));
+    return {
+        id,
+        name: resources(state)[id]?.name,
+        tags: tags[id] ?? [],
+        stale: resources(state)[id] === undefined,
+    };
+}
+export function readPresets(state) {
+    const value = state.presets ?? {};
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('invalid state presets');
+    for (const preset of Object.values(value)) {
+        if (!preset || typeof preset !== 'object' || Array.isArray(preset) ||
+            !Array.isArray(preset.selectors) ||
+            preset.selectors.some((selector) => typeof selector !== 'string'))
+            throw new Error('invalid state presets');
+    }
+    return value;
+}
+export function assertPresetName(name) {
+    if (!name)
+        throw new Error('preset name must be non-empty');
+}
+function normalizePresetSelector(selector, state) {
+    if (selector.startsWith('bundle:') || selector.startsWith('tag:'))
+        return selector;
+    if (selector.startsWith('skill:') || !selector.includes(':'))
+        return `skill:${resourceId(selector, state)}`;
+    throw new Error(`invalid Preset selector: ${selector}`);
+}
+export function listPresets(home) {
+    return Object.entries(readPresets(readState(home)))
+        .map(([name, preset]) => ({ name, selectors: preset.selectors.length }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+export function showPreset(home, name) {
+    const preset = readPresets(readState(home))[name];
+    if (!preset)
+        throw new Error(`unknown preset: ${name}`);
+    return preset.selectors.map((selector) => ({ selector }));
+}
+export function createPreset(home, name, selectors) {
+    const plan = planCatalogMutation(home, undefined, {
+        operation: 'preset.create', name, selectors,
+    });
+    applyCatalogMutation(home, plan);
+    return plan.changed;
+}
+export function addPresetSelectors(home, name, selectors) {
+    const plan = planCatalogMutation(home, undefined, {
+        operation: 'preset.add', name, selectors,
+    });
+    applyCatalogMutation(home, plan);
+    return plan.changed;
+}
+export function removePresetSelectors(home, name, selectors) {
+    const plan = planCatalogMutation(home, undefined, {
+        operation: 'preset.rm', name, selectors: selectors ?? [],
+    });
+    applyCatalogMutation(home, plan);
+    return plan.changed;
+}
+function catalogPlanningState(home, report) {
+    const state = readState(home);
+    if (!report)
+        return state;
+    return {
+        ...state,
+        targetInventory: {
+            resources: Object.fromEntries(report.resources.map(({ id, name }) => [id, { name }])),
+        },
+    };
+}
+export function planCatalogMutation(home, report, mutation) {
+    const state = catalogPlanningState(home, report);
+    if (mutation.operation === 'bundle.create' ||
+        mutation.operation === 'bundle.add' || mutation.operation === 'bundle.rm') {
+        assertManualBundle(mutation.name);
+        const expected = readBundles(state);
+        const current = expected[mutation.name];
+        let members;
+        if (mutation.operation === 'bundle.create') {
+            if (current)
+                throw new Error(`bundle already exists: ${mutation.name}`);
+            members = [...new Set(mutation.selectors.map((selector) => resourceId(selector, state)))]
+                .sort((a, b) => a.localeCompare(b));
+        }
+        else {
+            if (!current)
+                throw new Error(`unknown bundle: ${mutation.name}`);
+            if (mutation.operation === 'bundle.add') {
+                if (mutation.selectors.length === 0)
+                    throw new Error('bundle add requires at least one skill selector');
+                members = [...new Set([
+                        ...current,
+                        ...mutation.selectors.map((selector) => resourceId(selector, state)),
+                    ])].sort((a, b) => a.localeCompare(b));
+            }
+            else if (mutation.selectors.length > 0) {
+                const removed = new Set(mutation.selectors.map((selector) => resourceId(selector, state, current)));
+                members = current.filter((member) => !removed.has(member));
+            }
+        }
+        const { [mutation.name]: _, ...remaining } = expected;
+        const next = members === undefined
+            ? remaining
+            : { ...expected, [mutation.name]: members };
+        return {
+            operation: mutation.operation,
+            collection: 'bundles',
+            expected,
+            next,
+            changed: current ? Math.abs(current.length - (members?.length ?? 0)) : members?.length ?? 0,
+        };
+    }
+    if (mutation.operation === 'tag.add' || mutation.operation === 'tag.rm') {
+        if (mutation.operation === 'tag.add')
+            assertTagNames(mutation.names);
+        else if (mutation.names.some((name) => !name))
+            throw new Error('tags must be non-empty');
+        const expected = readTags(state);
+        const id = resourceId(mutation.resource, state, Object.keys(expected));
+        const current = expected[id] ?? [];
+        const names = mutation.operation === 'tag.add'
+            ? [...new Set([...current, ...mutation.names])].sort((a, b) => a.localeCompare(b))
+            : current.filter((name) => !(mutation.names.length > 0
+                ? new Set(mutation.names)
+                : new Set(current)).has(name));
+        const { [id]: _, ...remaining } = expected;
+        const next = names.length > 0 ? { ...remaining, [id]: names } : remaining;
+        return {
+            operation: mutation.operation,
+            collection: 'tags',
+            expected,
+            next,
+            changed: Math.abs(current.length - names.length),
+        };
+    }
+    assertPresetName(mutation.name);
+    const expected = readPresets(state);
+    const current = expected[mutation.name];
+    let selectors;
+    if (mutation.operation === 'preset.create') {
+        if (current)
+            throw new Error(`preset already exists: ${mutation.name}`);
+        selectors = [...new Set(mutation.selectors.map((selector) => normalizePresetSelector(selector, state)))].sort((a, b) => a.localeCompare(b));
+    }
+    else {
+        if (!current)
+            throw new Error(`unknown preset: ${mutation.name}`);
+        if (mutation.operation === 'preset.add') {
+            if (mutation.selectors.length === 0)
+                throw new Error('preset add requires at least one selector');
+            selectors = [...new Set([
+                    ...current.selectors,
+                    ...mutation.selectors.map((selector) => normalizePresetSelector(selector, state)),
+                ])].sort((a, b) => a.localeCompare(b));
+        }
+        else {
+            if (mutation.selectors.length === 0)
+                throw new Error('removing a Preset definition requires: skillspub preset delete <name> [--yes]');
+            const removed = new Set(mutation.selectors.map((selector) => {
+                try {
+                    return normalizePresetSelector(selector, state);
+                }
+                catch {
+                    return selector;
+                }
+            }));
+            selectors = current.selectors.filter((selector) => !removed.has(selector));
+        }
+    }
+    const next = { ...expected, [mutation.name]: { selectors } };
+    return {
+        operation: mutation.operation,
+        collection: 'presets',
+        expected,
+        next,
+        changed: current ? Math.abs(current.selectors.length - selectors.length) : selectors.length,
+    };
+}
+export function applyCatalogMutation(home, plan) {
+    const state = readState(home);
+    const current = plan.collection === 'bundles'
+        ? readBundles(state)
+        : plan.collection === 'tags'
+            ? readTags(state)
+            : readPresets(state);
+    if (JSON.stringify(current) !== JSON.stringify(plan.expected))
+        throw Object.assign(new Error(`${plan.collection} changed after preview; preview again`), { code: 'concurrent_modification' });
+    if (plan.collection === 'bundles')
+        state.bundles = plan.next;
+    else if (plan.collection === 'tags')
+        state.tags = plan.next;
+    else
+        state.presets = plan.next;
+    writeState(home, state);
+    const written = readState(home)[plan.collection] ?? {};
+    if (JSON.stringify(written) !== JSON.stringify(plan.next))
+        throw Object.assign(new Error(`${plan.collection} verification failed`), { code: 'apply_failed', details: { partialEffects: 'unknown' } });
+    return { changed: plan.changed };
+}
+export function expandSelector(home, selector, report) {
+    const state = readState(home);
+    let resourceIds;
+    if (selector.startsWith('bundle:')) {
+        const name = selector.slice('bundle:'.length);
+        const members = readBundles(state)[name];
+        if (!members)
+            throw new Error(`unknown bundle: ${name}`);
+        resourceIds = members;
+    }
+    else if (selector.startsWith('tag:')) {
+        const name = selector.slice('tag:'.length);
+        if (!name)
+            throw new Error(`invalid Tag selector: ${selector}`);
+        resourceIds = Object.entries(readTags(state))
+            .filter(([, tags]) => tags.includes(name))
+            .map(([id]) => id);
+        if (resourceIds.length === 0)
+            throw new Error(`unknown Tag: ${name}`);
+    }
+    else {
+        resourceIds = [resourceId(selector, state)];
+    }
+    const live = new Set(report.resources.map(({ id }) => id));
+    return {
+        resourceIds: [...new Set(resourceIds)],
+        staleResourceIds: resourceIds.filter((id) => !live.has(id)),
+    };
+}