skillmaxxing 0.1.0

package/dist/util/git.js

@@ -0,0 +1,35 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as fs from 'node:fs';
+const execFileAsync = promisify(execFile);
+export async function gitClone(url, dest, ref) {
+    const args = ['clone', '--depth', '1'];
+    if (ref)
+        args.push('--branch', ref);
+    args.push(url, dest);
+    await execFileAsync('git', args, {
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_LFS_SKIP_SMUDGE: '1' },
+        timeout: 60_000,
+    });
+}
+export async function gitGetHeadSha(dir) {
+    const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: dir });
+    return stdout.trim();
+}
+export function makeTempDir(prefix) {
+    return fs.mkdtempSync(path.join(os.tmpdir(), `skillmax-${prefix}-`));
+}
+export function cleanTempDir(dir) {
+    const resolved = path.resolve(dir);
+    const tmpdir = path.resolve(os.tmpdir());
+    if (!resolved.startsWith(tmpdir + path.sep))
+        return;
+    try {
+        fs.rmSync(resolved, { recursive: true });
+    }
+    catch {
+        // best-effort cleanup
+    }
+}

package/dist/util/log.js

@@ -0,0 +1,33 @@
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const CYAN = '\x1b[36m';
+export function info(msg) {
+    console.log(`${CYAN}i${RESET} ${msg}`);
+}
+export function success(msg) {
+    console.log(`${GREEN}✓${RESET} ${msg}`);
+}
+export function warn(msg) {
+    console.log(`${YELLOW}!${RESET} ${msg}`);
+}
+export function error(msg) {
+    console.error(`${RED}✗${RESET} ${msg}`);
+}
+export function heading(msg) {
+    console.log(`\n${BOLD}${msg}${RESET}`);
+}
+export function dim(msg) {
+    console.log(`${DIM}${msg}${RESET}`);
+}
+export function table(rows) {
+    if (rows.length === 0)
+        return;
+    const widths = rows[0].map((_, i) => Math.max(...rows.map(r => (r[i] ?? '').length)));
+    for (const row of rows) {
+        console.log(row.map((cell, i) => cell.padEnd(widths[i])).join('  '));
+    }
+}

package/dist/util/sanitize.js

@@ -0,0 +1,36 @@
+import * as path from 'node:path';
+const NAME_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const MAX_NAME_LEN = 64;
+export function sanitizeName(raw) {
+    return raw
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .substring(0, MAX_NAME_LEN) || 'unnamed-skill';
+}
+export function validateName(name) {
+    if (!name)
+        return 'name is required';
+    if (name.length > MAX_NAME_LEN)
+        return `name exceeds ${MAX_NAME_LEN} characters`;
+    if (!NAME_RE.test(name))
+        return 'name must be lowercase alphanumeric with single hyphens, starting with a letter';
+    return null;
+}
+export function isPathSafe(basePath, targetPath) {
+    const resolvedBase = path.resolve(basePath);
+    const resolvedTarget = path.resolve(targetPath);
+    return resolvedTarget.startsWith(resolvedBase + path.sep) || resolvedTarget === resolvedBase;
+}
+export function sanitizeSubpath(subpath) {
+    const segments = subpath.split(/[/\\]/);
+    if (segments.some(s => s === '..'))
+        return null;
+    return segments.filter(s => s && s !== '.').join('/');
+}
+export function stripTerminalEscapes(str) {
+    return str
+        .replace(/\x1b\[[0-9;]*[A-Za-z]/g, '') // CSI sequences
+        .replace(/\x1b\][^\x07]*\x07/g, '') // OSC sequences
+        .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, ''); // control chars (keep \t \n \r)
+}

package/dist/util/similarity.js

@@ -0,0 +1,27 @@
+/**
+ * Shared text similarity helpers used by discovery ranking, the prefer-update
+ * matcher, and in-session reflection. Single source of truth so tokenization
+ * stays consistent across all three (and future changes — stemming, stopwords —
+ * land in one place).
+ */
+/** Lowercase, split on non-alphanumeric runs, drop empties. */
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+/** Token set of a string. */
+export function tokenSet(text) {
+    return new Set(tokenize(text));
+}
+/** Jaccard similarity of two sets (0 when either is empty). */
+export function jaccard(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let inter = 0;
+    for (const t of a)
+        if (b.has(t))
+            inter++;
+    return inter / (a.size + b.size - inter);
+}

package/dist/util/versions.js

@@ -0,0 +1,104 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { ensureDir, copyDir, removeDir } from './fs.js';
+const VERSIONS_ROOT = path.join(os.homedir(), '.skillmax', 'versions');
+/** Default number of prior versions retained per skill (review SG5: bound growth). */
+export const MAX_RETAINED_VERSIONS = 5;
+function skillVersionsDir(id) {
+    return path.join(VERSIONS_ROOT, id);
+}
+/**
+ * Atomically replace `target`'s contents with a copy of `source`.
+ *
+ * Crash-safety (review C4): `source` is first copied into a sibling staged dir on
+ * the SAME filesystem as `target`, so the two renames below are intra-filesystem
+ * and atomic (sidesteps the cross-device EXDEV concern, review F5). If the swap
+ * rename fails, the prior `target` is rolled back from its backup — a failed swap
+ * never destroys the previous version.
+ */
+export function atomicReplaceDir(target, source) {
+    if (!fs.existsSync(source)) {
+        throw new Error(`source directory not found: ${source}`);
+    }
+    // Refuse to replace a symlink: renaming the link (not its target) would leave
+    // the real upstream skill untouched and silently break the install topology
+    // (review: optimize/promote against a symlinked install dir). The caller must
+    // pass the resolved managed-copy directory.
+    if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink()) {
+        throw new Error(`refusing to replace a symlink: ${target} (pass the resolved skill directory)`);
+    }
+    const parent = path.dirname(target);
+    ensureDir(parent);
+    const base = path.basename(target);
+    const staged = path.join(parent, `.${base}.staged-${process.pid}`);
+    const backup = path.join(parent, `.${base}.old-${process.pid}`);
+    removeDir(staged);
+    copyDir(source, staged);
+    removeDir(backup);
+    let backedUp = false;
+    if (fs.existsSync(target)) {
+        fs.renameSync(target, backup);
+        backedUp = true;
+    }
+    try {
+        fs.renameSync(staged, target);
+    }
+    catch (err) {
+        if (backedUp)
+            fs.renameSync(backup, target); // roll back
+        removeDir(staged);
+        throw err;
+    }
+    if (backedUp)
+        removeDir(backup);
+}
+/** Copy a skill dir into the retained-versions store under <id>/<version>/. */
+export function snapshot(id, version, srcDir) {
+    const dir = path.join(skillVersionsDir(id), version);
+    removeDir(dir);
+    copyDir(srcDir, dir);
+    pruneVersions(id);
+    return dir;
+}
+/** Retained version names for a skill, newest first. */
+export function listVersions(id) {
+    const dir = skillVersionsDir(id);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isDirectory())
+        .map((e) => ({ name: e.name, mtime: fs.statSync(path.join(dir, e.name)).mtimeMs }))
+        .sort((a, b) => b.mtime - a.mtime)
+        .map((e) => e.name);
+}
+/** Remove the oldest retained versions beyond MAX_RETAINED_VERSIONS. */
+export function pruneVersions(id, keep = MAX_RETAINED_VERSIONS) {
+    const versions = listVersions(id); // newest first
+    for (const stale of versions.slice(keep)) {
+        removeDir(path.join(skillVersionsDir(id), stale));
+    }
+}
+/**
+ * Promote a candidate into the live location: retain the current live version,
+ * then atomically swap in the candidate. Reversible via `revert`.
+ */
+export function promote(params) {
+    if (fs.existsSync(params.liveDir)) {
+        snapshot(params.id, params.priorVersion, params.liveDir);
+    }
+    atomicReplaceDir(params.liveDir, params.candidateDir);
+}
+/** Restore a retained version into the live location atomically. */
+export function revert(id, version, liveDir) {
+    const vdir = path.join(skillVersionsDir(id), version);
+    if (!fs.existsSync(vdir)) {
+        throw new Error(`version not retained: ${id}@${version}`);
+    }
+    atomicReplaceDir(liveDir, vdir);
+}

package/dist/workspace/channels.js

@@ -0,0 +1,14 @@
+/** Release channels in promotion order: dev → beta → stable. */
+export const CHANNELS = ['dev', 'beta', 'stable'];
+export function isValidChannel(value) {
+    return CHANNELS.includes(value);
+}
+/** Ordinal position of a channel (dev=0, beta=1, stable=2). */
+export function channelRank(channel) {
+    return CHANNELS.indexOf(channel);
+}
+/** The next channel up the promotion ladder, or null if already at stable. */
+export function nextChannel(channel) {
+    const i = CHANNELS.indexOf(channel);
+    return i >= 0 && i < CHANNELS.length - 1 ? CHANNELS[i + 1] : null;
+}

package/dist/workspace/collab.js

@@ -0,0 +1,103 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ensureDir, removeDir, copyDir, fileExists } from '../util/fs.js';
+import { ensureValidName } from '../util/collision.js';
+import { readRegistry, writeRegistry } from './registry.js';
+/**
+ * Collaborative optimization + review/promote for the shared registry (U15).
+ *
+ * - Pooled evals are append-only JSONL (merge-friendly across contributors).
+ * - Promotion to a higher channel REQUIRES explicit review/approval (review S2):
+ *   the gate refuses without `approve` + an `approver`, and records a receipt.
+ * - Divergent versions of the same skill in the target channel are surfaced as a
+ *   CONFLICT, never silently merged (review R22/SG7: detection, not auto-resolve).
+ */
+function appendJsonl(file, record) {
+    ensureDir(path.dirname(file));
+    fs.appendFileSync(file, JSON.stringify(record) + '\n');
+}
+function readJsonl(file) {
+    try {
+        return fs
+            .readFileSync(file, 'utf-8')
+            .split('\n')
+            .filter((l) => l.trim())
+            .map((l) => JSON.parse(l));
+    }
+    catch {
+        return [];
+    }
+}
+export function poolEval(registryDir, entry) {
+    appendJsonl(path.join(registryDir, 'evals', `${entry.skill}.jsonl`), entry);
+}
+export function pooledScores(registryDir, skill) {
+    return readJsonl(path.join(registryDir, 'evals', `${skill}.jsonl`));
+}
+export function reviewPromote(registryDir, params) {
+    if (!params.approve) {
+        return {
+            ok: false,
+            reason: `promotion to ${params.toChannel} requires review and approval (pass approve + an approver)`,
+        };
+    }
+    if (!params.approver) {
+        return { ok: false, reason: 'an approver is required for promotion' };
+    }
+    // Validate the skill name before it is joined into filesystem paths (review:
+    // path traversal via params.skill).
+    const nameCheck = ensureValidName(params.skill);
+    if (!nameCheck.ok) {
+        return { ok: false, reason: nameCheck.reason };
+    }
+    const idx = readRegistry(registryDir);
+    const candidates = idx.skills.filter((e) => e.name === params.skill);
+    if (candidates.length === 0) {
+        return { ok: false, reason: `"${params.skill}" is not in the registry` };
+    }
+    // Source = the entry being promoted INTO the target: the highest-versioned
+    // entry NOT already in the target channel (falls back to the target's own
+    // entry if it only exists there — a harmless no-op promote).
+    const promotable = candidates.filter((e) => e.channel !== params.toChannel);
+    const source = [...(promotable.length > 0 ? promotable : candidates)].sort((a, b) => b.version.localeCompare(a.version, undefined, { numeric: true }))[0];
+    // Conflict detection: a different version already occupies the target channel.
+    const targetExisting = candidates.find((e) => e.channel === params.toChannel);
+    if (targetExisting && targetExisting.version !== source.version) {
+        return {
+            ok: false,
+            reason: `conflict: ${params.skill} is already ${targetExisting.version} in ${params.toChannel} (source ${source.version}); resolve manually`,
+        };
+    }
+    // Already in the target channel (only a target-channel entry exists): nothing
+    // to copy. Short-circuit BEFORE any removeDir/copyDir — otherwise src === dst
+    // and removeDir(dst) would delete the only copy (review: self-channel data loss).
+    if (source.channel === params.toChannel) {
+        return { ok: true };
+    }
+    const srcDir = path.join(registryDir, 'skills', source.channel, params.skill);
+    if (!fileExists(path.join(srcDir, 'SKILL.md'))) {
+        return { ok: false, reason: `registry files missing for ${params.skill} in ${source.channel}` };
+    }
+    const dstDir = path.join(registryDir, 'skills', params.toChannel, params.skill);
+    removeDir(dstDir);
+    ensureDir(path.dirname(dstDir));
+    copyDir(srcDir, dstDir);
+    idx.skills = idx.skills.filter((e) => !(e.name === params.skill && e.channel === params.toChannel));
+    idx.skills.push({
+        name: params.skill,
+        channel: params.toChannel,
+        version: source.version,
+        publishedBy: source.publishedBy,
+        publishedAt: source.publishedAt,
+    });
+    writeRegistry(registryDir, idx);
+    // Append-only approval receipt (auditability; review S10 notes signing as a follow-up).
+    appendJsonl(path.join(registryDir, 'approvals.jsonl'), {
+        skill: params.skill,
+        toChannel: params.toChannel,
+        version: source.version,
+        approver: params.approver,
+        at: params.at,
+    });
+    return { ok: true };
+}

package/dist/workspace/registry.js

@@ -0,0 +1,113 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { ensureDir, copyDir, fileExists, removeDir } from '../util/fs.js';
+import { readSkillMeta } from '../util/frontmatter.js';
+import { ensureValidName, namespacedName } from '../util/collision.js';
+import { isPathSafe } from '../util/sanitize.js';
+import { isValidChannel } from './channels.js';
+import { ensureState, loadState, saveState } from '../state/store.js';
+const WORKSPACE_DIR = path.join(os.homedir(), '.skillmax', 'workspace');
+function indexPath(registryDir) {
+    return path.join(registryDir, 'registry.json');
+}
+export function readRegistry(registryDir) {
+    try {
+        const data = JSON.parse(fs.readFileSync(indexPath(registryDir), 'utf-8'));
+        if (!data || !Array.isArray(data.skills))
+            return { version: 1, skills: [] };
+        // registry.json is an UNTRUSTED shared file. Drop entries whose name or
+        // channel is invalid before any entry value is joined into a filesystem path
+        // (review: path traversal via crafted entry.name / entry.channel in sync()).
+        const skills = data.skills.filter((e) => e &&
+            typeof e.name === 'string' &&
+            ensureValidName(e.name).ok &&
+            typeof e.channel === 'string' &&
+            isValidChannel(e.channel));
+        return { version: 1, skills };
+    }
+    catch {
+        return { version: 1, skills: [] };
+    }
+}
+export function writeRegistry(registryDir, idx) {
+    ensureDir(registryDir);
+    // Sort entries for merge-friendliness (review C5).
+    const sorted = [...idx.skills].sort((a, b) => a.name.localeCompare(b.name) || a.channel.localeCompare(b.channel));
+    const out = { version: 1, skills: sorted };
+    const p = indexPath(registryDir);
+    const tmp = p + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(out, null, 2) + '\n');
+    fs.renameSync(tmp, p);
+}
+function skillStorePath(registryDir, channel, name) {
+    return path.join(registryDir, 'skills', channel, name);
+}
+/** Publish a local skill directory into the registry under a channel. */
+export function publish(skillDir, registryDir, opts) {
+    const skillMd = path.join(skillDir, 'SKILL.md');
+    if (!fileExists(skillMd))
+        throw new Error(`no SKILL.md in ${skillDir}`);
+    const meta = readSkillMeta(fs.readFileSync(skillMd, 'utf-8'));
+    if (!meta)
+        throw new Error(`invalid SKILL.md in ${skillDir}`);
+    const nameCheck = ensureValidName(meta.name);
+    if (!nameCheck.ok)
+        throw new Error(nameCheck.reason);
+    const dest = skillStorePath(registryDir, opts.channel, meta.name);
+    removeDir(dest);
+    ensureDir(path.dirname(dest));
+    copyDir(skillDir, dest);
+    const entry = {
+        name: meta.name,
+        channel: opts.channel,
+        version: opts.version ?? (typeof meta.version === 'string' ? meta.version : '1.0.0'),
+        publishedBy: opts.publishedBy,
+        publishedAt: opts.at,
+    };
+    const idx = readRegistry(registryDir);
+    idx.skills = idx.skills.filter((e) => !(e.name === entry.name && e.channel === entry.channel));
+    idx.skills.push(entry);
+    writeRegistry(registryDir, idx);
+    return entry;
+}
+/** List registry entries, optionally filtered by channel. */
+export function listRegistry(registryDir, channel) {
+    const entries = readRegistry(registryDir).skills;
+    return channel ? entries.filter((e) => e.channel === channel) : entries;
+}
+/**
+ * Materialize registry skills into the local managed workspace area and record
+ * their state (origin: workspace, trusted: false). Synced skills are keyed by an
+ * origin-namespaced id when they collide with an existing local skill, so the
+ * local skill's state and history are never overwritten (review A5/AE2).
+ */
+export function sync(registryDir, opts) {
+    const registryId = opts.registryId ?? path.basename(path.resolve(registryDir));
+    const entries = listRegistry(registryDir, opts.channel);
+    const synced = [];
+    for (const entry of entries) {
+        const src = skillStorePath(registryDir, entry.channel, entry.name);
+        if (!fileExists(path.join(src, 'SKILL.md')))
+            continue;
+        const existing = loadState(entry.name);
+        const collided = !!existing && existing.origin !== 'workspace';
+        const id = collided ? namespacedName(registryId, entry.name) : entry.name;
+        const dir = path.join(WORKSPACE_DIR, registryId, entry.name);
+        // Defense-in-depth: never remove/write outside the managed workspace area.
+        if (!isPathSafe(WORKSPACE_DIR, dir))
+            continue;
+        removeDir(dir);
+        ensureDir(path.dirname(dir));
+        copyDir(src, dir);
+        const state = ensureState({ name: entry.name, id, origin: 'workspace', version: entry.version, source: registryId }, opts.at);
+        state.origin = 'workspace';
+        state.channel = entry.channel;
+        state.version = entry.version;
+        state.source = registryId;
+        state.updatedAt = opts.at;
+        saveState(state);
+        synced.push({ name: entry.name, id, channel: entry.channel, dir, collided });
+    }
+    return synced;
+}

package/hooks/hooks.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "npx -y skillmaxxing plugin guidance" }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          { "type": "command", "command": "npx -y skillmaxxing plugin on-tool" }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "npx -y skillmaxxing plugin on-stop --agent claude --mode auto --threshold 10" }
+        ]
+      }
+    ]
+  }
+}

package/index/index.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "_note": "Starter seed for the curated skill index. Populate with verified public skills after auditing the ecosystem (plan open item; review P5f/A9). The discover command degrades to local + explicit repo sources when this is empty.",
+  "skills": []
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "skillmaxxing",
+  "version": "0.1.0",
+  "description": "Self-evolving skills for your coding agent — auto-create and auto-improve skills as you work, no trigger needed.",
+  "type": "module",
+  "bin": {
+    "skillmaxxing": "./dist/cli.js",
+    "skill-maxing": "./dist/cli.js",
+    "skillmax": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "check": "tsc --noEmit",
+    "test": "tsx --test test/**/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "index",
+    "hooks",
+    ".claude-plugin",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bennyoooo/skillmaxxing.git"
+  },
+  "homepage": "https://github.com/Bennyoooo/skillmaxxing#readme",
+  "bugs": "https://github.com/Bennyoooo/skillmaxxing/issues",
+  "keywords": [
+    "ai",
+    "agents",
+    "agent-skills",
+    "skills",
+    "skill-management",
+    "self-improving-agents"
+  ],
+  "author": "Benny Jiang",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.8.0"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  }
+}