skillmaxxing 0.1.0

package/dist/commands/remove.js

@@ -0,0 +1,48 @@
+import * as path from 'node:path';
+import { ALL_AGENTS, getAgentOrThrow } from '../agents/registry.js';
+import { removeDir, fileExists } from '../util/fs.js';
+import { removeGlobalLockEntry } from '../lock/global.js';
+import { removeProjectLockEntry } from '../lock/project.js';
+import * as log from '../util/log.js';
+export async function remove(args) {
+    if (args.names.length === 0) {
+        log.error('Specify at least one skill name to remove.');
+        return;
+    }
+    const agents = args.agent
+        ? [getAgentOrThrow(args.agent)]
+        : ALL_AGENTS;
+    const projectDir = process.cwd();
+    let removed = 0;
+    for (const name of args.names) {
+        let found = false;
+        for (const agent of agents) {
+            const dirs = [];
+            if (!args.scope || args.scope === 'global') {
+                dirs.push({ path: path.join(agent.globalSkillsDir, name), scope: 'global' });
+            }
+            if (!args.scope || args.scope === 'project') {
+                dirs.push({ path: path.join(projectDir, agent.projectSkillsDir, name), scope: 'project' });
+            }
+            for (const d of dirs) {
+                if (fileExists(d.path) && removeDir(d.path)) {
+                    log.success(`Removed ${name} from ${agent.displayName} (${d.scope})`);
+                    found = true;
+                }
+            }
+        }
+        if (found) {
+            removed++;
+            if (!args.scope || args.scope === 'global')
+                removeGlobalLockEntry(name);
+            if (!args.scope || args.scope === 'project')
+                removeProjectLockEntry(projectDir, name);
+        }
+        else {
+            log.warn(`Skill '${name}' not found in any agent.`);
+        }
+    }
+    if (removed > 0) {
+        log.success(`Removed ${removed} skill(s)`);
+    }
+}

package/dist/commands/skillify.js

@@ -0,0 +1,74 @@
+import * as fs from 'node:fs';
+import { stageDraft, commitDraft, listDrafts, discardDraft, } from '../create/skillify.js';
+import { findUpdateTarget } from '../create/match.js';
+import { scanLocalSkills } from '../discover/local.js';
+import { loadCuratedIndex } from '../discover/index.js';
+import * as log from '../util/log.js';
+function readDraft(p) {
+    const d = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    if (!d ||
+        typeof d.name !== 'string' ||
+        typeof d.description !== 'string' ||
+        typeof d.body !== 'string') {
+        throw new Error('draft must include string name, description, and body');
+    }
+    return d;
+}
+export async function skillify(args) {
+    if (args.listDrafts) {
+        const drafts = listDrafts();
+        if (drafts.length === 0)
+            log.info('No staged drafts.');
+        else {
+            log.heading('Staged drafts');
+            for (const d of drafts)
+                log.info(`  ${d}`);
+        }
+        return;
+    }
+    if (args.discard) {
+        discardDraft(args.discard);
+        log.success(`Discarded draft "${args.discard}".`);
+        return;
+    }
+    if (args.commit) {
+        await commitDraft(args.commit, {
+            scope: args.scope,
+            agents: args.agents,
+            copy: args.copy,
+            force: args.force,
+        });
+        log.success(`Committed "${args.commit}" (trusted: false).`);
+        return;
+    }
+    if (!args.draftPath) {
+        log.error('Usage: skill-maxing skillify --draft <draft.json> | --commit <name> | --list-drafts');
+        process.exitCode = 1;
+        return;
+    }
+    const draft = readDraft(args.draftPath);
+    if (!args.forceNew) {
+        const existing = [...scanLocalSkills(), ...loadCuratedIndex()];
+        const m = findUpdateTarget(draft.name, draft.description, existing);
+        if (m.target) {
+            log.warn(`Prefer-update: ${m.reason}.`);
+            log.info(`Update/optimize "${m.target.name}" instead, or pass --new to create anyway.`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const res = await stageDraft(draft, { allowExec: args.allowExec });
+    if (!res.ok) {
+        log.error(`Staging failed: ${res.detail}`);
+        process.exitCode = 1;
+        return;
+    }
+    log.success(`Staged "${draft.name}" at ${res.dir}`);
+    if (res.smokePassed === true)
+        log.success('Smoke test passed.');
+    else if (res.smokePassed === false)
+        log.warn('Smoke test failed.');
+    else if (res.detail)
+        log.info(res.detail);
+    log.info(`Review it, then commit: skill-maxing skillify --commit ${draft.name}`);
+}

package/dist/commands/update.js

@@ -0,0 +1,52 @@
+import { readGlobalLock } from '../lock/global.js';
+import { readProjectLock } from '../lock/project.js';
+import { install } from './install.js';
+import * as log from '../util/log.js';
+export async function update(args) {
+    const projectDir = process.cwd();
+    if (!args.scope || args.scope === 'global') {
+        const lock = readGlobalLock();
+        const entries = Object.entries(lock.skills);
+        const filtered = args.names
+            ? entries.filter(([name]) => args.names.includes(name))
+            : entries;
+        if (filtered.length === 0 && (!args.scope || args.scope === 'global')) {
+            log.info('No global skills to update.');
+        }
+        for (const [name, entry] of filtered) {
+            log.info(`Updating ${name} from ${entry.source}...`);
+            try {
+                await install({
+                    source: entry.source,
+                    agents: entry.agents,
+                    scope: 'global',
+                });
+            }
+            catch (err) {
+                log.error(`Failed to update ${name}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    if (!args.scope || args.scope === 'project') {
+        const lock = readProjectLock(projectDir);
+        const entries = Object.entries(lock.skills);
+        const filtered = args.names
+            ? entries.filter(([name]) => args.names.includes(name))
+            : entries;
+        if (filtered.length === 0 && args.scope === 'project') {
+            log.info('No project skills to update.');
+        }
+        for (const [name, entry] of filtered) {
+            log.info(`Updating ${name} from ${entry.source}...`);
+            try {
+                await install({
+                    source: entry.source,
+                    scope: 'project',
+                });
+            }
+            catch (err) {
+                log.error(`Failed to update ${name}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+}

package/dist/commands/workspace.js

@@ -0,0 +1,117 @@
+import { publish, sync, listRegistry } from '../workspace/registry.js';
+import { reviewPromote, poolEval } from '../workspace/collab.js';
+import { isValidChannel } from '../workspace/channels.js';
+import { stripTerminalEscapes } from '../util/sanitize.js';
+import * as log from '../util/log.js';
+/** Untrusted registry fields are sanitized before display (review: ANSI injection). */
+const clean = stripTerminalEscapes;
+function channelOf(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!isValidChannel(value))
+        throw new Error(`invalid channel "${value}" (dev|beta|stable)`);
+    return value;
+}
+export async function workspace(args) {
+    if (!args.registryDir) {
+        log.error('Usage: skill-maxing workspace <action> --registry <dir> [options]');
+        process.exitCode = 1;
+        return;
+    }
+    const now = new Date().toISOString();
+    switch (args.action) {
+        case 'publish': {
+            if (!args.skillDir) {
+                log.error('Usage: workspace publish --registry <dir> --skill-dir <dir> --channel dev');
+                process.exitCode = 1;
+                return;
+            }
+            const entry = publish(args.skillDir, args.registryDir, {
+                channel: channelOf(args.channel, 'dev'),
+                publishedBy: args.by ?? 'unknown',
+                at: now,
+            });
+            log.success(`Published ${entry.name}@${entry.version} to ${entry.channel}.`);
+            log.info('Commit and push the registry repo to share with your team.');
+            return;
+        }
+        case 'sync': {
+            const synced = sync(args.registryDir, { channel: channelOf(args.channel), at: now });
+            if (args.json) {
+                console.log(JSON.stringify(synced, null, 2));
+                return;
+            }
+            if (synced.length === 0) {
+                log.warn('Nothing to sync.');
+                return;
+            }
+            log.heading(`Synced ${synced.length} skill(s)`);
+            for (const s of synced) {
+                log.info(`  ${clean(s.name)} [${clean(s.channel)}]${s.collided ? ` (namespaced as ${clean(s.id)} -- local skill preserved)` : ''}`);
+            }
+            log.info('Synced skills are trusted:false and live under ~/.skillmax/workspace; install or optimize from there.');
+            return;
+        }
+        case 'list': {
+            const entries = listRegistry(args.registryDir, channelOf(args.channel));
+            if (args.json) {
+                console.log(JSON.stringify(entries, null, 2));
+                return;
+            }
+            if (entries.length === 0) {
+                log.info('Registry is empty.');
+                return;
+            }
+            log.table([
+                ['name', 'channel', 'version', 'by'],
+                ...entries.map((e) => [clean(e.name), clean(e.channel), clean(e.version), clean(e.publishedBy)]),
+            ]);
+            return;
+        }
+        case 'pool': {
+            if (!args.skillName || args.score === undefined) {
+                log.error('Usage: workspace pool --registry <dir> --skill <name> --score <0..1> [--by <who>]');
+                process.exitCode = 1;
+                return;
+            }
+            poolEval(args.registryDir, {
+                skill: args.skillName,
+                score: args.score,
+                by: args.by ?? 'unknown',
+                at: now,
+            });
+            log.success(`Pooled eval result for ${args.skillName} (${args.score}).`);
+            return;
+        }
+        case 'promote': {
+            if (!args.skillName) {
+                log.error('Usage: workspace promote --registry <dir> --skill <name> --channel <beta|stable> --approve --approver <who>');
+                process.exitCode = 1;
+                return;
+            }
+            const target = channelOf(args.channel);
+            if (!target) {
+                log.error('promote requires --channel <beta|stable>');
+                process.exitCode = 1;
+                return;
+            }
+            const res = reviewPromote(args.registryDir, {
+                skill: args.skillName,
+                toChannel: target,
+                approve: args.approve ?? false,
+                approver: args.approver,
+                at: now,
+            });
+            if (!res.ok) {
+                log.error(res.reason);
+                process.exitCode = 1;
+                return;
+            }
+            log.success(`Promoted ${args.skillName} to ${target} (approved by ${args.approver}).`);
+            return;
+        }
+        default:
+            log.error(`Unknown workspace action: ${args.action}`);
+            process.exitCode = 1;
+    }
+}

package/dist/create/match.js

@@ -0,0 +1,23 @@
+import { tokenSet, jaccard } from '../util/similarity.js';
+export const DEFAULT_SIMILARITY_THRESHOLD = 0.6;
+export function findUpdateTarget(name, description, existing, threshold = DEFAULT_SIMILARITY_THRESHOLD) {
+    const lower = name.toLowerCase();
+    const exact = existing.find((e) => e.name.toLowerCase() === lower);
+    if (exact)
+        return { target: exact, reason: `a skill named "${exact.name}" already exists`, similarity: 1 };
+    const descTokens = tokenSet(description);
+    let best = null;
+    for (const e of existing) {
+        const sim = jaccard(descTokens, tokenSet(e.description));
+        if (!best || sim > best.sim)
+            best = { c: e, sim };
+    }
+    if (best && best.sim >= threshold) {
+        return {
+            target: best.c,
+            reason: `"${best.c.name}" is ${(best.sim * 100).toFixed(0)}% similar — consider updating/optimizing it`,
+            similarity: best.sim,
+        };
+    }
+    return { target: null, reason: 'no sufficiently similar existing skill', similarity: best?.sim ?? 0 };
+}

package/dist/create/reflect.js

@@ -0,0 +1,49 @@
+/**
+ * Deterministic helpers for the in-session reflection loop (Hermes-style). The
+ * CLI/library does NOT decide whether to crystallize a skill — that judgment is
+ * the host agent's, gated by the user. These helpers only surface the signal:
+ * "this workflow shape has repeated", so the agent can propose (sparingly — review
+ * P7f) turning it into a skill via the prefer-update-over-create path.
+ */
+import { jaccard } from '../util/similarity.js';
+function normalizeStep(s) {
+    return s.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+/** A stable signature for a workflow's ordered steps. */
+export function workflowSignature(steps) {
+    return steps.map(normalizeStep).join(' > ');
+}
+function stepSet(steps) {
+    return new Set(steps.map(normalizeStep));
+}
+/** Jaccard similarity of two workflows' step sets (order-insensitive). */
+export function similarity(a, b) {
+    return jaccard(stepSet(a.steps), stepSet(b.steps));
+}
+/**
+ * Cluster records by approximate similarity and return clusters that recur at
+ * least `minRepeat` times — the "this is reusable" signal. Deterministic:
+ * processes records in order, greedily assigning each to the first cluster it
+ * matches above `threshold`.
+ */
+export function repeatedWorkflows(records, opts = {}) {
+    const minRepeat = opts.minRepeat ?? 2;
+    const threshold = opts.threshold ?? 0.7;
+    const clusters = [];
+    for (let i = 0; i < records.length; i++) {
+        const rec = records[i];
+        const existing = clusters.find((c) => similarity(c.representative, rec) >= threshold);
+        if (existing) {
+            existing.count++;
+            existing.indices.push(i);
+        }
+        else {
+            clusters.push({ representative: rec, count: 1, indices: [i] });
+        }
+    }
+    return clusters.filter((c) => c.count >= minRepeat);
+}
+/** True when any workflow shape has repeated enough to be worth crystallizing. */
+export function hasRepeatedWorkflow(records, opts) {
+    return repeatedWorkflows(records, opts).length > 0;
+}

package/dist/create/skillify.js

@@ -0,0 +1,117 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { stringify as stringifyYaml } from 'yaml';
+import { validateManifest } from '../eval/schema.js';
+import { writeSkillFile } from '../util/frontmatter.js';
+import { ensureValidName } from '../util/collision.js';
+import { sanitizeSubpath } from '../util/sanitize.js';
+import { ensureDir, removeDir, fileExists } from '../util/fs.js';
+import { runSandboxed } from '../util/exec.js';
+import { ensureState, setLifecycle } from '../state/store.js';
+import { install } from '../commands/install.js';
+const DRAFTS_DIR = path.join(os.homedir(), '.skillmax', 'drafts');
+export function draftDir(name) {
+    return path.join(DRAFTS_DIR, name);
+}
+/**
+ * Stage a draft to a persistent draft dir (resumable across sessions — review I5)
+ * and optionally run its smoke test in the sandbox. Smoke tests require explicit
+ * allowExec: a freshly-synthesized skill is `trusted:false`, so running its code
+ * is a deliberate, user-authorized step (review A7), not an automatic one.
+ */
+export async function stageDraft(draft, opts = {}) {
+    const nameCheck = ensureValidName(draft.name);
+    if (!nameCheck.ok)
+        return { ok: false, dir: '', smokePassed: null, detail: nameCheck.reason };
+    if (draft.eval) {
+        const err = validateManifest(draft.eval);
+        if (err)
+            return { ok: false, dir: '', smokePassed: null, detail: `eval scaffold invalid: ${err}` };
+    }
+    const dir = draftDir(draft.name);
+    removeDir(dir);
+    ensureDir(dir);
+    writeSkillFile(path.join(dir, 'SKILL.md'), {
+        name: draft.name,
+        description: draft.description,
+        version: '1.0.0',
+        ...(draft.tools ? { tools: draft.tools } : {}),
+        ...(draft.triggers ? { triggers: draft.triggers } : {}),
+    }, draft.body);
+    for (const s of draft.scripts ?? []) {
+        const safe = sanitizeSubpath(s.path);
+        if (!safe)
+            continue; // reject traversal in script paths
+        const p = path.join(dir, safe);
+        ensureDir(path.dirname(p));
+        fs.writeFileSync(p, s.content);
+    }
+    if (draft.eval) {
+        fs.writeFileSync(path.join(dir, 'eval.yaml'), stringifyYaml(draft.eval));
+    }
+    const now = new Date().toISOString();
+    ensureState({ name: draft.name, origin: 'created', lifecycle: 'staged' }, now);
+    setLifecycle(draft.name, 'staged', now);
+    let smokePassed = null;
+    if (draft.smokeTest && draft.smokeTest.length > 0) {
+        if (!opts.allowExec) {
+            return {
+                ok: true,
+                dir,
+                smokePassed: null,
+                detail: 'smoke test skipped: review the generated scripts, then re-run with allowExec to execute it',
+            };
+        }
+        const [cmd, ...args] = draft.smokeTest;
+        const res = await runSandboxed(cmd, args, {
+            cwd: dir,
+            skillId: draft.name,
+            allowExec: true,
+            timeoutMs: 30_000,
+        });
+        smokePassed = res.ok;
+        if (!res.ok) {
+            return { ok: false, dir, smokePassed, detail: `smoke test failed: exit ${res.code}` };
+        }
+    }
+    return { ok: true, dir, smokePassed };
+}
+/**
+ * Commit a staged draft: install it from its draft dir (reusing the hardened
+ * install path + collision gate) and mark its state committed (origin: created,
+ * trusted: false). The draft dir is removed after a successful commit.
+ */
+export async function commitDraft(name, opts) {
+    const dir = draftDir(name);
+    if (!fileExists(path.join(dir, 'SKILL.md'))) {
+        throw new Error(`no staged draft for "${name}" (stage it first)`);
+    }
+    await install({
+        source: dir,
+        scope: opts.scope,
+        agents: opts.agents,
+        copy: opts.copy ?? true, // created skills default to copy (draft edits stay isolated)
+        force: opts.force,
+    });
+    const now = new Date().toISOString();
+    ensureState({ name, origin: 'created', lifecycle: 'committed' }, now);
+    setLifecycle(name, 'committed', now);
+    removeDir(dir);
+}
+/** List names of drafts staged but not yet committed. */
+export function listDrafts() {
+    try {
+        return fs
+            .readdirSync(DRAFTS_DIR, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && fileExists(path.join(DRAFTS_DIR, e.name, 'SKILL.md')))
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/** Discard a staged draft. Returns true if removed. */
+export function discardDraft(name) {
+    return removeDir(draftDir(name));
+}

package/dist/discover/collect.js

@@ -0,0 +1,40 @@
+import { loadCuratedIndex } from './index.js';
+import { scanLocalSkills } from './local.js';
+import { discoverFromRepo } from './github.js';
+function msg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/**
+ * Gather candidates from all enabled sources with per-source isolation: a
+ * failure in one source (bad repo, rate limit, unreadable index) yields partial
+ * results plus a recorded error, never a total abort (review I7).
+ */
+export async function collectSources(opts = {}) {
+    const candidates = [];
+    const errors = [];
+    if (opts.index !== false) {
+        try {
+            candidates.push(...loadCuratedIndex(opts.indexPath));
+        }
+        catch (e) {
+            errors.push({ source: 'index', message: msg(e) });
+        }
+    }
+    if (opts.local !== false) {
+        try {
+            candidates.push(...scanLocalSkills(opts.projectDir));
+        }
+        catch (e) {
+            errors.push({ source: 'local', message: msg(e) });
+        }
+    }
+    for (const repo of opts.repos ?? []) {
+        try {
+            candidates.push(...(await discoverFromRepo(repo)));
+        }
+        catch (e) {
+            errors.push({ source: repo, message: msg(e) });
+        }
+    }
+    return { candidates, errors };
+}

package/dist/discover/github.js

@@ -0,0 +1,27 @@
+import { parseSource } from '../source/parser.js';
+import { resolveSource, cleanupResolved } from '../source/resolver.js';
+/**
+ * Clone-and-scan a repo (or local path) source into discovery candidates.
+ *
+ * This is the always-works baseline (KTD10): it reuses the hardened
+ * parseSource/resolveSource path (depth-1 clone, one-level scan, entry-name
+ * validation). An optional GitHub Trees/Search API fast path (when GITHUB_TOKEN
+ * is set) is deferred per the plan; clone-scan needs no token. The pinned
+ * commitSha is carried so a later install can avoid re-resolving (review F1/F2).
+ */
+export async function discoverFromRepo(source) {
+    const parsed = parseSource(source);
+    const resolved = await resolveSource(parsed);
+    const origin = parsed.type === 'local' ? 'local' : 'github';
+    const candidates = resolved.map((s) => ({
+        name: s.name,
+        description: s.meta.description,
+        source,
+        origin,
+        tags: Array.isArray(s.meta.tags) ? s.meta.tags : [],
+        commitSha: s.commitSha,
+        installed: false,
+    }));
+    cleanupResolved(resolved);
+    return candidates;
+}

package/dist/discover/index.js

@@ -0,0 +1,39 @@
+import * as fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+/** Path to the shipped curated index (index/index.json at the package root). */
+export function defaultIndexPath() {
+    return fileURLToPath(new URL('../../index/index.json', import.meta.url));
+}
+/**
+ * Load the curated index into candidates. Returns [] on a missing/corrupt/empty
+ * index so discovery degrades gracefully to other sources (review: empty index
+ * must not break discovery).
+ */
+export function loadCuratedIndex(indexPath = defaultIndexPath()) {
+    let raw;
+    try {
+        raw = fs.readFileSync(indexPath, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!data || !Array.isArray(data.skills))
+        return [];
+    return data.skills
+        .filter((e) => e && typeof e.name === 'string' && typeof e.source === 'string')
+        .map((e) => ({
+        name: e.name,
+        description: e.description ?? '',
+        source: e.source,
+        origin: 'index',
+        tags: Array.isArray(e.tags) ? e.tags : [],
+        installed: false,
+    }));
+}

package/dist/discover/local.js

@@ -0,0 +1,55 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ALL_AGENTS } from '../agents/registry.js';
+import { readSkillMeta } from '../util/frontmatter.js';
+import { fileExists } from '../util/fs.js';
+import { isSafeEntryName } from '../source/resolver.js';
+/**
+ * Scan every agent's global and project skill dirs for installed skills,
+ * de-duplicated by name. Best-effort: unreadable dirs and malformed SKILL.md
+ * files are skipped, never fatal.
+ */
+export function scanLocalSkills(projectDir = process.cwd()) {
+    const seen = new Set();
+    const out = [];
+    for (const agent of ALL_AGENTS) {
+        const dirs = [agent.globalSkillsDir, path.join(projectDir, agent.projectSkillsDir)];
+        for (const dir of dirs) {
+            let entries;
+            try {
+                entries = fs.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (!entry.isDirectory() && !entry.isSymbolicLink())
+                    continue;
+                if (!isSafeEntryName(entry.name))
+                    continue;
+                const skillMd = path.join(dir, entry.name, 'SKILL.md');
+                if (!fileExists(skillMd))
+                    continue;
+                let meta;
+                try {
+                    meta = readSkillMeta(fs.readFileSync(skillMd, 'utf-8'));
+                }
+                catch {
+                    continue;
+                }
+                if (!meta || seen.has(meta.name))
+                    continue;
+                seen.add(meta.name);
+                out.push({
+                    name: meta.name,
+                    description: meta.description,
+                    source: '',
+                    origin: 'local',
+                    tags: Array.isArray(meta.tags) ? meta.tags : [],
+                    installed: true,
+                });
+            }
+        }
+    }
+    return out;
+}