@goodboyjs/cli 0.1.0

package/dist/commands/search.js

@@ -0,0 +1,49 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { createRegistryAdapter } from '../lib/registry-adapter.js';
+import { logger } from '../lib/logger.js';
+function highlight(text, query) {
+    if (!query)
+        return text;
+    const re = new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi');
+    return text.replace(re, (m) => chalk.bgYellow.black(m));
+}
+function renderSkill(skill, query) {
+    const name = highlight(skill.name, query);
+    const desc = highlight(skill.description, query);
+    const version = chalk.gray(`v${skill.version}`);
+    const category = skill.category !== undefined ? chalk.cyan(` [${skill.category}]`) : '';
+    process.stdout.write(`  ${chalk.bold(name)} ${version}${category}\n`);
+    process.stdout.write(`    ${desc}\n`);
+    if (Array.isArray(skill.keywords) && skill.keywords.length > 0) {
+        const kws = skill.keywords
+            .map((kw) => highlight(kw, query))
+            .join(chalk.gray(', '));
+        process.stdout.write(`    ${chalk.gray('keywords:')} ${kws}\n`);
+    }
+    process.stdout.write('\n');
+}
+async function run(query) {
+    const registry = createRegistryAdapter();
+    const results = await registry.search(query);
+    if (results.length === 0) {
+        logger.info(`No skills in the registry match "${query}".`);
+        return;
+    }
+    for (const skill of results) {
+        renderSkill(skill, query);
+    }
+    logger.info(`${results.length} skill${results.length === 1 ? '' : 's'} matched`);
+}
+export const searchCommand = new Command('search')
+    .description('Search available skills in the registry by name, description, or keyword')
+    .argument('<query>', 'Search query')
+    .action(async (query) => {
+    try {
+        await run(query);
+    }
+    catch (err) {
+        logger.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});

package/dist/commands/skill-create.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerSkillCreate(program: Command): void;

package/dist/commands/skill-create.js

@@ -0,0 +1,143 @@
+import { input, select } from '@inquirer/prompts';
+import ora from 'ora';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeManifest } from '../lib/manifest.js';
+import { logger } from '../lib/logger.js';
+import { SKILL_NAME_RE } from '../lib/validation.js';
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+// Schema enforces maxLength: 64 on name and maxLength: 1024 on description.
+// These limits must stay in sync with manifest.schema.json.
+const MAX_NAME_LENGTH = 64;
+const MAX_DESCRIPTION_LENGTH = 1024;
+function buildSkillMd(name, description) {
+    return `---
+name: ${name}
+description: ${description}
+---
+
+# ${name}
+
+## Instructions
+
+Describe when and how this skill should be used, and provide the
+assistant with step-by-step guidance for completing the task.
+`;
+}
+async function run() {
+    const name = await input({
+        message: 'Skill name:',
+        validate: (v) => {
+            const t = v.trim();
+            if (!SKILL_NAME_RE.test(t)) {
+                return 'Must match ^[a-z0-9-]+ (lowercase letters, numbers, hyphens only)';
+            }
+            if (t.length > MAX_NAME_LENGTH) {
+                return `Name must be ${MAX_NAME_LENGTH} characters or fewer`;
+            }
+            return true;
+        },
+    });
+    const skillDir = join(process.cwd(), name.trim());
+    if (existsSync(skillDir)) {
+        throw new Error(`Directory "${name.trim()}" already exists in the current directory. ` +
+            `Choose a different skill name or remove the existing directory.`);
+    }
+    const description = await input({
+        message: 'Description:',
+        validate: (v) => {
+            const t = v.trim();
+            if (t.length === 0)
+                return 'Description is required';
+            if (t.length > MAX_DESCRIPTION_LENGTH) {
+                return `Description must be ${MAX_DESCRIPTION_LENGTH} characters or fewer`;
+            }
+            return true;
+        },
+    });
+    const authorName = await input({
+        message: 'Author name:',
+        validate: (v) => (v.trim().length > 0 ? true : 'Author name is required'),
+    });
+    const authorEmail = await input({
+        message: 'Author email (optional):',
+        validate: (v) => {
+            const t = v.trim();
+            if (t.length === 0)
+                return true;
+            return EMAIL_RE.test(t) ? true : `"${t}" is not a valid email address`;
+        },
+    });
+    const category = (await select({
+        message: 'Category:',
+        choices: [
+            { value: 'code', name: 'Code' },
+            { value: 'writing', name: 'Writing' },
+            { value: 'data', name: 'Data' },
+            { value: 'devops', name: 'DevOps' },
+            { value: 'testing', name: 'Testing' },
+            { value: 'documentation', name: 'Documentation' },
+            { value: 'productivity', name: 'Productivity' },
+            { value: 'security', name: 'Security' },
+            { value: 'research', name: 'Research' },
+            { value: 'other', name: 'Other' },
+        ],
+    }));
+    const license = await input({ message: 'License:', default: 'MIT' });
+    const manifest = {
+        name: name.trim(),
+        version: '0.1.0',
+        description: description.trim(),
+        author: {
+            name: authorName.trim(),
+            ...(authorEmail.trim() ? { email: authorEmail.trim() } : {}),
+        },
+        license: license.trim() || 'MIT',
+        category,
+        schema_version: '1.0.0',
+        status: 'experimental',
+        visibility: 'private',
+    };
+    const manifestPath = join(skillDir, 'manifest.json');
+    const skillMdPath = join(skillDir, 'SKILL.md');
+    const spinner = ora('Creating skill scaffold…').start();
+    try {
+        mkdirSync(skillDir, { recursive: true });
+        for (const sub of ['scripts', 'references', 'assets']) {
+            mkdirSync(join(skillDir, sub), { recursive: true });
+        }
+        await writeManifest(manifestPath, manifest);
+        writeFileSync(skillMdPath, buildSkillMd(manifest.name, manifest.description), 'utf-8');
+        spinner.succeed('Created skill scaffold');
+    }
+    catch (err) {
+        spinner.fail('Failed to create skill scaffold');
+        throw err;
+    }
+    logger.info('');
+    logger.info(`  Name:    ${manifest.name}`);
+    logger.info(`  Version: ${manifest.version}`);
+    logger.info(`  Path:    ${skillDir}`);
+    logger.info('  Created: manifest.json, SKILL.md, scripts/, references/, assets/');
+    logger.info('');
+    logger.info(`  Run 'goodboy add ./${manifest.name}' to add this skill to your local registry.`);
+    logger.info(`  Run 'goodboy install ${manifest.name}' to install it.`);
+    logger.success('Skill scaffold created');
+}
+export function registerSkillCreate(program) {
+    program
+        .command('create')
+        .description('Create a new skill with SKILL.md and manifest.json')
+        .action(async () => {
+        try {
+            await run();
+        }
+        catch (err) {
+            if (err instanceof Error && /force closed|force-closed/i.test(err.message)) {
+                process.exit(0);
+            }
+            logger.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/skill-diff.d.ts

@@ -0,0 +1,8 @@
+import { Command } from 'commander';
+/**
+ * Naive LCS-based line diff. oldLabel/newLabel are accepted for signature
+ * symmetry with the caller's own header lines but aren't embedded in the
+ * returned lines — the caller prints "---"/"+++ " headers separately.
+ */
+export declare function computeDiff(oldContent: string, newContent: string, _oldLabel: string, _newLabel: string): string[];
+export declare function registerSkillDiff(program: Command): void;

package/dist/commands/skill-diff.js

@@ -0,0 +1,120 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
+import chalk from 'chalk';
+import { getRegistryPath } from '../lib/registry.js';
+import { readRegistryEntry, resolveLatestVersion, resolveVersionPath } from '../lib/registry-entry.js';
+import { SKILL_NAME_RE } from '../lib/validation.js';
+import { logger, sanitiseError } from '../lib/logger.js';
+function assertWithin(target, base, label) {
+    const resolvedTarget = resolve(target);
+    const resolvedBase = resolve(base);
+    if (!resolvedTarget.startsWith(resolvedBase + sep)) {
+        throw new Error(`Refused: ${label} escapes the expected directory`);
+    }
+}
+/**
+ * Naive LCS-based line diff. oldLabel/newLabel are accepted for signature
+ * symmetry with the caller's own header lines but aren't embedded in the
+ * returned lines — the caller prints "---"/"+++ " headers separately.
+ */
+export function computeDiff(oldContent, newContent, _oldLabel, _newLabel) {
+    if (oldContent === newContent)
+        return [];
+    const oldLines = oldContent.length > 0 ? oldContent.split('\n') : [];
+    const newLines = newContent.length > 0 ? newContent.split('\n') : [];
+    const m = oldLines.length;
+    const n = newLines.length;
+    const lcs = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = m - 1; i >= 0; i--) {
+        for (let j = n - 1; j >= 0; j--) {
+            lcs[i][j] =
+                oldLines[i] === newLines[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const result = [];
+    let i = 0;
+    let j = 0;
+    while (i < m && j < n) {
+        if (oldLines[i] === newLines[j]) {
+            result.push(`  ${oldLines[i]}`);
+            i++;
+            j++;
+        }
+        else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+            result.push(chalk.red(`- ${oldLines[i]}`));
+            i++;
+        }
+        else {
+            result.push(chalk.green(`+ ${newLines[j]}`));
+            j++;
+        }
+    }
+    while (i < m) {
+        result.push(chalk.red(`- ${oldLines[i]}`));
+        i++;
+    }
+    while (j < n) {
+        result.push(chalk.green(`+ ${newLines[j]}`));
+        j++;
+    }
+    return result;
+}
+export function registerSkillDiff(program) {
+    program
+        .command('diff <skill-name>')
+        .description('Show diff between installed skill and registry latest')
+        .option('-g, --global', 'Diff against globally installed skill')
+        .action(async (skillName, options) => {
+        try {
+            if (!SKILL_NAME_RE.test(skillName)) {
+                throw new Error(`Invalid skill name "${skillName}": must match ^[a-z0-9-]+$`);
+            }
+            const installedBase = options.global
+                ? join(homedir(), '.goodboy', 'skills')
+                : join(process.cwd(), '.claude', 'skills');
+            const installedPath = join(installedBase, skillName, 'SKILL.md');
+            assertWithin(installedPath, installedBase, 'installed skill path');
+            const registryBase = getRegistryPath();
+            const skillDir = join(registryBase, skillName);
+            assertWithin(skillDir, registryBase, 'skill path');
+            const entry = await readRegistryEntry(skillDir);
+            if (!entry) {
+                throw new Error(`Skill "${skillName}" not found in registry`);
+            }
+            const latest = resolveLatestVersion(entry);
+            if (!latest) {
+                throw new Error(`Skill "${skillName}" has no available versions`);
+            }
+            const versionDir = resolveVersionPath(entry, latest, skillDir);
+            const registrySkillMdPath = join(versionDir, 'SKILL.md');
+            assertWithin(registrySkillMdPath, versionDir, 'registry SKILL.md path');
+            if (!existsSync(installedPath)) {
+                logger.warn(`${skillName} is not installed in this scope.`);
+                logger.info(`Run 'goodboy install ${skillName}' to install it.`);
+                return;
+            }
+            const installedContent = readFileSync(installedPath, 'utf-8');
+            const registryContent = readFileSync(registrySkillMdPath, 'utf-8');
+            if (installedContent === registryContent) {
+                logger.success(`${skillName} — installed copy matches registry@${latest}`);
+                return;
+            }
+            logger.warn(`${skillName} — installed copy differs from registry@${latest}`);
+            logger.info(`--- installed (.claude/skills/${skillName}/SKILL.md)`);
+            logger.info(`+++ registry  (${registrySkillMdPath})`);
+            logger.info('');
+            const diffLines = computeDiff(installedContent, registryContent, installedPath, registrySkillMdPath);
+            for (const line of diffLines) {
+                logger.info(line);
+            }
+            logger.warn("Changes in .claude/skills/ will be lost on 'goodboy upgrade'.");
+            logger.info('To preserve changes: copy them to the registry version first,');
+            logger.info(`then run 'goodboy skill version ${skillName} --bump patch' to create a new version.`);
+        }
+        catch (err) {
+            logger.error(sanitiseError(err));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/skill-open.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function resolveEditor(): string;
+export declare function registerSkillOpen(program: Command): void;

package/dist/commands/skill-open.js

@@ -0,0 +1,82 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join, resolve, sep, basename } from 'node:path';
+import { getRegistryPath } from '../lib/registry.js';
+import { readRegistryEntry, resolveLatestVersion, resolveVersionPath } from '../lib/registry-entry.js';
+import { SKILL_NAME_RE } from '../lib/validation.js';
+import { logger, sanitiseError } from '../lib/logger.js';
+const EDITOR_CANDIDATES = ['code', 'cursor', 'nano', 'vim', 'vi'];
+function assertWithin(target, base, label) {
+    const resolvedTarget = resolve(target);
+    const resolvedBase = resolve(base);
+    if (!resolvedTarget.startsWith(resolvedBase + sep)) {
+        throw new Error(`Refused: ${label} escapes the expected directory`);
+    }
+}
+export function resolveEditor() {
+    const envEditor = process.env['EDITOR'];
+    if (envEditor && envEditor.trim().length > 0) {
+        return envEditor;
+    }
+    for (const candidate of EDITOR_CANDIDATES) {
+        const result = spawnSync(candidate, ['--version'], { stdio: 'ignore', timeout: 2000 });
+        if (result.status === 0) {
+            return candidate;
+        }
+    }
+    throw new Error('No editor found. Set the EDITOR environment variable:\n' +
+        '  export EDITOR=nano\n' +
+        '  export EDITOR=code');
+}
+export function registerSkillOpen(program) {
+    program
+        .command('open <skill-name>')
+        .description('Open the latest registry version of a skill in your editor')
+        .option('--version <version>', 'Open a specific version instead of latest')
+        .action(async (skillName, options) => {
+        try {
+            if (!SKILL_NAME_RE.test(skillName)) {
+                throw new Error(`Invalid skill name "${skillName}": must match ^[a-z0-9-]+$`);
+            }
+            const registryPath = getRegistryPath();
+            const skillDir = join(registryPath, skillName);
+            assertWithin(skillDir, registryPath, 'skill path');
+            const entry = await readRegistryEntry(skillDir);
+            if (!entry) {
+                throw new Error(`Skill "${skillName}" not found in registry`);
+            }
+            const version = options.version ?? resolveLatestVersion(entry);
+            if (!version) {
+                throw new Error(`Skill "${skillName}" has no available versions`);
+            }
+            const versionDir = resolveVersionPath(entry, version, skillDir);
+            const skillMdPath = join(versionDir, 'SKILL.md');
+            assertWithin(skillMdPath, versionDir, 'SKILL.md path');
+            if (!existsSync(skillMdPath)) {
+                throw new Error(`SKILL.md not found for "${skillName}@${version}"`);
+            }
+            const editor = resolveEditor();
+            logger.info(`Opening ${skillName}@${version} in ${basename(editor)}...`);
+            logger.info(`File: ${skillMdPath}`);
+            logger.warn('⚠  Edit the registry copy only. Changes to .claude/skills/ will be overwritten by upgrade.');
+            const proc = spawn(editor, [skillMdPath], { stdio: 'inherit' });
+            await new Promise((resolvePromise, reject) => {
+                proc.on('close', (code) => {
+                    if (code === 0 || code === null)
+                        resolvePromise();
+                    else
+                        reject(new Error(`${editor} exited with code ${code}`));
+                });
+                proc.on('error', reject);
+            });
+            logger.info('');
+            logger.success(`Done editing ${skillName}@${version}`);
+            logger.info(`Run 'goodboy upgrade ${skillName}' to install the updated version.`);
+            logger.info(`Run 'goodboy skill diff ${skillName}' to see what changed.`);
+        }
+        catch (err) {
+            logger.error(sanitiseError(err));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/skill-status.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerSkillStatus(program: Command): void;

package/dist/commands/skill-status.js

@@ -0,0 +1,136 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
+import Table from 'cli-table3';
+import chalk from 'chalk';
+import { readGoodBoyJson, getLockedVersion } from '../lib/goodboy-file.js';
+import { getRegistryPath } from '../lib/registry.js';
+import { readRegistryEntry, resolveLatestVersion, resolveVersionPath } from '../lib/registry-entry.js';
+import { readManifest, validateManifest } from '../lib/manifest.js';
+import { SKILL_NAME_RE } from '../lib/validation.js';
+import { logger, sanitiseError } from '../lib/logger.js';
+function assertWithin(target, base, label) {
+    const resolvedTarget = resolve(target);
+    const resolvedBase = resolve(base);
+    if (!resolvedTarget.startsWith(resolvedBase + sep)) {
+        throw new Error(`Refused: ${label} escapes the expected directory`);
+    }
+}
+function stateColor(state) {
+    switch (state) {
+        case 'up to date': return chalk.green(state);
+        case 'upgrade available': return chalk.cyan(state);
+        case 'modified': return chalk.yellow(state);
+        case 'not installed': return chalk.red(state);
+    }
+}
+async function getInstalledVersion(skillsBase, skillName) {
+    const manifestPath = join(skillsBase, skillName, 'manifest.json');
+    if (!existsSync(manifestPath))
+        return null;
+    try {
+        const raw = await readManifest(manifestPath);
+        const manifest = validateManifest(raw);
+        return manifest.version;
+    }
+    catch {
+        return null;
+    }
+}
+async function computeRow(skillName, skillsBase, manifestDir) {
+    const installedVersion = await getInstalledVersion(skillsBase, skillName);
+    const lockedVersion = await getLockedVersion(manifestDir, skillName);
+    const registryPath = getRegistryPath();
+    const skillDir = join(registryPath, skillName);
+    const entry = await readRegistryEntry(skillDir);
+    const registryLatest = entry ? resolveLatestVersion(entry) : null;
+    let drifted = false;
+    if (installedVersion !== null && entry && registryLatest !== null) {
+        const installedSkillMdPath = join(skillsBase, skillName, 'SKILL.md');
+        if (existsSync(installedSkillMdPath)) {
+            const versionDir = resolveVersionPath(entry, registryLatest, skillDir);
+            const registrySkillMdPath = join(versionDir, 'SKILL.md');
+            if (existsSync(registrySkillMdPath)) {
+                const installedContent = readFileSync(installedSkillMdPath, 'utf-8');
+                const registryContent = readFileSync(registrySkillMdPath, 'utf-8');
+                drifted = installedContent !== registryContent;
+            }
+        }
+    }
+    let state;
+    if (installedVersion === null) {
+        state = 'not installed';
+    }
+    else if (registryLatest !== null && installedVersion !== registryLatest) {
+        state = 'upgrade available';
+    }
+    else if (drifted) {
+        state = 'modified';
+    }
+    else {
+        state = 'up to date';
+    }
+    return { name: skillName, installedVersion, registryLatest, lockedVersion, state };
+}
+async function run(options) {
+    const skillsBase = options.global
+        ? join(homedir(), '.goodboy', 'skills')
+        : join(process.cwd(), '.claude', 'skills');
+    const manifestDir = options.global ? join(homedir(), '.goodboy') : process.cwd();
+    const goodboy = await readGoodBoyJson(manifestDir);
+    if (!goodboy) {
+        logger.warn("No goodboy.json found. Run 'goodboy init' to initialise GoodBoy.");
+        return;
+    }
+    const skillNames = Object.keys(goodboy.skills);
+    if (skillNames.length === 0) {
+        logger.info('No skills listed in goodboy.json.');
+        return;
+    }
+    const rows = [];
+    for (const name of skillNames) {
+        if (!SKILL_NAME_RE.test(name)) {
+            logger.warn(`Skipping invalid skill name in goodboy.json: "${name}"`);
+            continue;
+        }
+        const skillDir = join(skillsBase, name);
+        assertWithin(skillDir, skillsBase, 'skill path');
+        rows.push(await computeRow(name, skillsBase, manifestDir));
+    }
+    const table = new Table({
+        head: ['Skill', 'Installed', 'Registry', 'Locked', 'State'].map((h) => chalk.bold(h)),
+        style: { head: [], border: [] },
+    });
+    for (const row of rows) {
+        table.push([
+            row.name,
+            row.installedVersion ?? '—',
+            row.registryLatest ?? '—',
+            row.lockedVersion ?? '—',
+            stateColor(row.state),
+        ]);
+    }
+    process.stdout.write(table.toString() + '\n');
+    if (rows.some((r) => r.state === 'modified')) {
+        logger.warn("\n⚠  Modified skills will lose changes on 'goodboy upgrade'.");
+        logger.info("Run 'goodboy skill diff <name>' to see what changed.");
+    }
+    if (rows.some((r) => r.state === 'upgrade available')) {
+        logger.info("\nRun 'goodboy upgrade' to install latest versions.");
+    }
+}
+export function registerSkillStatus(program) {
+    program
+        .command('status')
+        .description('Show installed skills with version and drift state')
+        .option('-g, --global', 'Show global skills status')
+        .action(async (options) => {
+        try {
+            await run(options);
+        }
+        catch (err) {
+            logger.error(sanitiseError(err));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/skill-version.d.ts

@@ -0,0 +1,6 @@
+import { Command } from 'commander';
+declare const BUMP_LEVELS: readonly ["patch", "minor", "major"];
+type BumpLevel = (typeof BUMP_LEVELS)[number];
+export declare function bumpVersion(version: string, level: BumpLevel): string;
+export declare function registerSkillVersion(program: Command): void;
+export {};