@crouton-kit/crouter 0.1.1 → 0.1.3

package/dist/commands/skill.js

@@ -0,0 +1,405 @@
+import { join } from 'node:path';
+import { writeFileSync } from 'node:fs';
+import { SKILL_ENTRY_FILE, SKILLS_DIR, } from '../types.js';
+import { skillConfigKey } from '../types.js';
+import { notFound, usage, general } from '../core/errors.js';
+import { out, hint, info, jsonOut, handleError, } from '../core/output.js';
+import { listScopes, requireScopeRoot, resolveScopeArg, projectScopeRoot, } from '../core/scope.js';
+import { resolveSkill, listAllSkills, listInstalledPlugins, findPluginByName, parseSkillQualifier, } from '../core/resolver.js';
+import { updateConfig, ensureScopeInitialized } from '../core/config.js';
+import { parseFrontmatter, serializeFrontmatter } from '../core/frontmatter.js';
+import { ensureDir, pathExists, readText, walkFiles } from '../core/fs-utils.js';
+import { skillPrompt } from '../prompts/skill.js';
+const KNOWN_VERBS = new Set([
+    'list',
+    'show',
+    'path',
+    'grep',
+    'new',
+    'where',
+    'enable',
+    'disable',
+    'search',
+]);
+const AUTHORING_GUIDE_SKILL = 'authoring-skills';
+function buildShowFooter(skillPath) {
+    return (`crtr: edit this skill directly at ${skillPath} — ` +
+        `for SKILL.md authoring guidance run \`crtr skill ${AUTHORING_GUIDE_SKILL}\``);
+}
+function wrapSkill(name, path, content) {
+    return `<skill name="${name}" path="${path}">\n${content.endsWith('\n') ? content : content + '\n'}</skill>`;
+}
+export function registerSkillCommands(program) {
+    const skill = program
+        .command('skill [nameOrVerb] [rest...]')
+        .description('manage and inspect skills')
+        .option('--frontmatter', 'include YAML frontmatter in the printed body')
+        .action(async (nameOrVerb, _rest, opts) => {
+        if (nameOrVerb === undefined) {
+            out(skillPrompt());
+            return;
+        }
+        if (!KNOWN_VERBS.has(nameOrVerb)) {
+            try {
+                const skillObj = resolveSkill(nameOrVerb);
+                const content = readText(skillObj.path);
+                const body = opts.frontmatter ? content : parseFrontmatter(content).body;
+                out(wrapSkill(skillObj.name, skillObj.path, body));
+                hint(buildShowFooter(skillObj.path));
+            }
+            catch (e) {
+                handleError(e);
+            }
+        }
+    });
+    // list
+    skill
+        .command('list')
+        .description('list installed skills (disabled hidden unless -a)')
+        .option('--scope <scope>', 'user|project|all (default: all)')
+        .option('--plugin <name>', 'filter by plugin name')
+        .option('-a, --all', 'include disabled skills')
+        .option('--json', 'emit JSON')
+        .action(async (opts) => {
+        try {
+            const scopes = listScopes(opts.scope);
+            const skills = scopes
+                .flatMap((s) => listAllSkills(s))
+                .filter((sk) => {
+                if (opts.plugin !== undefined && sk.plugin !== opts.plugin)
+                    return false;
+                if (!opts.all && !sk.enabled)
+                    return false;
+                return true;
+            });
+            if (opts.json) {
+                jsonOut({
+                    skills: skills.map((sk) => ({
+                        name: sk.name,
+                        plugin: sk.plugin,
+                        scope: sk.scope,
+                        path: sk.path,
+                        description: sk.frontmatter.description,
+                        enabled: sk.enabled,
+                        disabled_in: sk.disabledIn,
+                    })),
+                });
+                return;
+            }
+            for (const sk of skills) {
+                const desc = sk.frontmatter.description !== undefined ? sk.frontmatter.description : '';
+                const marker = sk.enabled ? '' : ` [disabled${sk.disabledIn ? `@${sk.disabledIn}` : ''}]`;
+                const line = `${sk.scope}:${sk.plugin}/${sk.name}${marker}${desc ? `  — ${desc}` : ''}`;
+                out(line);
+            }
+        }
+        catch (e) {
+            handleError(e, { json: opts.json });
+        }
+    });
+    // show
+    skill
+        .command('show <name>')
+        .description('print SKILL.md body to stdout (default verb)')
+        .option('--scope <scope>', 'user|project')
+        .option('--plugin <name>', 'filter by plugin name')
+        .option('--frontmatter', 'include YAML frontmatter in the printed body')
+        .option('--json', 'emit JSON')
+        .action(async (name, opts) => {
+        try {
+            const scopeArg = resolveScopeArg(opts.scope);
+            const resolveOpts = scopeArg !== 'all' ? { scope: scopeArg } : {};
+            if (opts.plugin !== undefined) {
+                Object.assign(resolveOpts, { pluginFilter: opts.plugin });
+            }
+            const skillObj = resolveSkill(name, resolveOpts);
+            const content = readText(skillObj.path);
+            const body = opts.frontmatter ? content : parseFrontmatter(content).body;
+            if (opts.json) {
+                jsonOut({
+                    name: skillObj.name,
+                    plugin: skillObj.plugin,
+                    scope: skillObj.scope,
+                    path: skillObj.path,
+                    content,
+                    authoring_guide_command: `crtr skill ${AUTHORING_GUIDE_SKILL}`,
+                });
+                return;
+            }
+            out(wrapSkill(skillObj.name, skillObj.path, body));
+            hint(buildShowFooter(skillObj.path));
+        }
+        catch (e) {
+            handleError(e, { json: opts.json });
+        }
+    });
+    // path
+    skill
+        .command('path <name>')
+        .description('print absolute path to SKILL.md')
+        .option('--scope <scope>', 'user|project')
+        .option('--plugin <name>', 'filter by plugin name')
+        .action(async (name, opts) => {
+        try {
+            const scopeArg = resolveScopeArg(opts.scope);
+            const resolveOpts = scopeArg !== 'all' ? { scope: scopeArg } : {};
+            if (opts.plugin !== undefined) {
+                Object.assign(resolveOpts, { pluginFilter: opts.plugin });
+            }
+            const skillObj = resolveSkill(name, resolveOpts);
+            out(skillObj.path);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // grep
+    skill
+        .command('grep <pattern>')
+        .description('search skill file contents for a regex pattern')
+        .option('--scope <scope>', 'user|project|all')
+        .option('--plugin <name>', 'filter by plugin name')
+        .option('--json', 'emit JSON')
+        .action(async (pattern, opts) => {
+        try {
+            let regex;
+            try {
+                regex = new RegExp(pattern);
+            }
+            catch {
+                throw usage(`invalid regex pattern: ${pattern}`);
+            }
+            const scopes = listScopes(opts.scope);
+            const pluginSkillsDirs = [];
+            for (const s of scopes) {
+                for (const plugin of listInstalledPlugins(s)) {
+                    if (!plugin.enabled)
+                        continue;
+                    if (opts.plugin !== undefined && plugin.name !== opts.plugin)
+                        continue;
+                    pluginSkillsDirs.push(join(plugin.root, SKILLS_DIR));
+                }
+            }
+            const matchLines = [];
+            for (const skillsDir of pluginSkillsDirs) {
+                const files = walkFiles(skillsDir);
+                for (const file of files) {
+                    const content = readText(file);
+                    const lines = content.split('\n');
+                    lines.forEach((lineText, idx) => {
+                        if (regex.test(lineText)) {
+                            matchLines.push({ path: file, line: idx + 1, text: lineText });
+                        }
+                    });
+                }
+            }
+            if (opts.json) {
+                jsonOut({ matches: matchLines });
+                return;
+            }
+            for (const m of matchLines) {
+                out(`${m.path}:${m.line}: ${m.text}`);
+            }
+        }
+        catch (e) {
+            handleError(e, { json: opts.json });
+        }
+    });
+    // new
+    skill
+        .command('new <qualifier>')
+        .description('scaffold a new skill as <plugin>:<name>')
+        .option('--scope <scope>', 'user|project (default: project then user)')
+        .option('--description <text>', 'skill description for frontmatter')
+        .action(async (qualifier, opts) => {
+        try {
+            if (!qualifier.includes(':')) {
+                throw usage('qualifier must be in the form <plugin>:<name> (e.g. authoring:my-skill)');
+            }
+            const { plugin: pluginName, name: skillName } = parseSkillQualifier(qualifier);
+            if (!pluginName) {
+                throw usage('qualifier must be in the form <plugin>:<name>');
+            }
+            const scopeArg = opts.scope !== undefined ? resolveScopeArg(opts.scope) : undefined;
+            let plugin;
+            if (scopeArg !== undefined && scopeArg !== 'all') {
+                plugin = findPluginByName(pluginName, scopeArg);
+            }
+            else {
+                plugin = findPluginByName(pluginName);
+            }
+            if (!plugin) {
+                throw notFound(`plugin not found: ${pluginName}`);
+            }
+            const skillDir = join(plugin.root, SKILLS_DIR, ...skillName.split('/'));
+            const skillFile = join(skillDir, SKILL_ENTRY_FILE);
+            if (pathExists(skillFile)) {
+                throw general(`skill already exists: ${skillFile}`);
+            }
+            ensureDir(skillDir);
+            const fm = serializeFrontmatter({
+                name: skillName,
+                description: opts.description,
+            });
+            writeFileSync(skillFile, fm, 'utf8');
+            out(skillFile);
+            hint(`crtr: scaffolded ${skillFile} — edit directly, then ` +
+                `\`crtr skill ${AUTHORING_GUIDE_SKILL}\` for SKILL.md authoring guidance`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // where
+    skill
+        .command('where <name>')
+        .description('show resolution info as JSON')
+        .option('--scope <scope>', 'user|project')
+        .option('--plugin <name>', 'filter by plugin name')
+        .action(async (name, opts) => {
+        try {
+            const scopeArg = resolveScopeArg(opts.scope);
+            const resolveOpts = scopeArg !== 'all' ? { scope: scopeArg } : {};
+            if (opts.plugin !== undefined) {
+                Object.assign(resolveOpts, { pluginFilter: opts.plugin });
+            }
+            const skillObj = resolveSkill(name, resolveOpts);
+            jsonOut({
+                name: skillObj.name,
+                plugin: skillObj.plugin,
+                scope: skillObj.scope,
+                path: skillObj.path,
+            });
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // enable
+    skill
+        .command('enable <name>')
+        .description('enable a skill (clears any disable in the chosen scope)')
+        .option('--scope <scope>', 'user|project (default: project if available, else user)')
+        .action(async (name, opts) => {
+        try {
+            await toggleSkill(name, true, opts.scope);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // disable
+    skill
+        .command('disable <name>')
+        .description('disable a skill (hides from list and agent discovery)')
+        .option('--scope <scope>', 'user|project (default: project if available, else user)')
+        .action(async (name, opts) => {
+        try {
+            await toggleSkill(name, false, opts.scope);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // search
+    skill
+        .command('search <query>')
+        .description('search skills by name, description, and keywords')
+        .option('--scope <scope>', 'user|project|all (default: all)')
+        .option('--plugin <name>', 'filter by plugin name')
+        .option('-a, --all', 'include disabled skills')
+        .option('--body', 'also search SKILL.md body')
+        .option('--json', 'emit JSON')
+        .action(async (query, opts) => {
+        try {
+            const needle = query.toLowerCase();
+            const scopes = listScopes(opts.scope);
+            const candidates = scopes
+                .flatMap((s) => listAllSkills(s))
+                .filter((sk) => {
+                if (opts.plugin !== undefined && sk.plugin !== opts.plugin)
+                    return false;
+                if (!opts.all && !sk.enabled)
+                    return false;
+                return true;
+            });
+            const hits = [];
+            for (const sk of candidates) {
+                const matched = [];
+                let score = 0;
+                if (sk.name.toLowerCase().includes(needle)) {
+                    score += 10;
+                    matched.push('name');
+                }
+                const desc = sk.frontmatter.description;
+                if (desc !== undefined && desc.toLowerCase().includes(needle)) {
+                    score += 4;
+                    matched.push('description');
+                }
+                const kws = sk.frontmatter.keywords;
+                if (kws && kws.some((k) => k.toLowerCase().includes(needle))) {
+                    score += 6;
+                    matched.push('keywords');
+                }
+                if (opts.body) {
+                    const text = readText(sk.path).toLowerCase();
+                    if (text.includes(needle)) {
+                        score += 1;
+                        matched.push('body');
+                    }
+                }
+                if (score > 0)
+                    hits.push({ skill: sk, score, matched });
+            }
+            hits.sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name));
+            if (opts.json) {
+                jsonOut({
+                    query,
+                    hits: hits.map((h) => ({
+                        name: h.skill.name,
+                        plugin: h.skill.plugin,
+                        scope: h.skill.scope,
+                        path: h.skill.path,
+                        description: h.skill.frontmatter.description,
+                        keywords: h.skill.frontmatter.keywords,
+                        enabled: h.skill.enabled,
+                        score: h.score,
+                        matched: h.matched,
+                    })),
+                });
+                return;
+            }
+            for (const h of hits) {
+                const desc = h.skill.frontmatter.description !== undefined
+                    ? h.skill.frontmatter.description
+                    : '';
+                const marker = h.skill.enabled ? '' : ' [disabled]';
+                const line = `${h.skill.scope}:${h.skill.plugin}/${h.skill.name}${marker}\t${h.matched.join(',')}\t${desc}`;
+                out(line);
+            }
+        }
+        catch (e) {
+            handleError(e, { json: opts.json });
+        }
+    });
+}
+async function toggleSkill(name, enabled, scopeArgRaw) {
+    let scope;
+    if (scopeArgRaw !== undefined) {
+        const resolved = resolveScopeArg(scopeArgRaw);
+        if (resolved === 'all')
+            throw usage('--scope must be user or project for enable/disable');
+        scope = resolved;
+    }
+    else {
+        scope = projectScopeRoot() !== null ? 'project' : 'user';
+    }
+    const skillObj = resolveSkill(name);
+    const key = skillConfigKey(skillObj.plugin, skillObj.name);
+    const scopeRootPath = requireScopeRoot(scope);
+    ensureScopeInitialized(scope, scopeRootPath);
+    updateConfig(scope, (cfg) => {
+        cfg.skills[key] = { enabled };
+    });
+    info(`${enabled ? 'enabled' : 'disabled'} ${skillObj.plugin}:${skillObj.name} in ${scope} scope`);
+}

package/dist/commands/spec.d.ts

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

package/dist/commands/spec.js

@@ -0,0 +1,9 @@
+import { registerArtifactCommand } from '../core/artifact.js';
+import { specPrompt } from '../prompts/spec.js';
+export function registerSpecCommand(program) {
+    registerArtifactCommand(program, {
+        command: 'spec',
+        kind: 'specs',
+        promptFn: specPrompt,
+    });
+}

package/dist/commands/update.d.ts

@@ -0,0 +1,4 @@
+import { Command } from 'commander';
+export declare function selfCheck(): void;
+export declare function contentCheck(): void;
+export declare function registerUpdateCommand(program: Command): void;

package/dist/commands/update.js

@@ -0,0 +1,140 @@
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { join, dirname } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { err, warn, handleError } from '../core/output.js';
+import { projectScopeRoot } from '../core/scope.js';
+import { updateState } from '../core/config.js';
+import { listAllPlugins, listAllMarketplaces } from '../core/resolver.js';
+import { pull, fetch, currentSha, remoteSha } from '../core/git.js';
+import { nowIso } from '../core/fs-utils.js';
+import { network, general } from '../core/errors.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PKG_ROOT = join(__dirname, '..', '..', '..');
+const PACKAGE_JSON_PATH = join(PKG_ROOT, 'package.json');
+function currentVersion() {
+    const raw = readFileSync(PACKAGE_JSON_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed.version;
+}
+function selfUpdate() {
+    const res = spawnSync('npm', ['i', '-g', '@crouton-kit/crtr@latest'], { stdio: 'inherit' });
+    if (res.status !== 0) {
+        throw general('npm install failed');
+    }
+}
+export function selfCheck() {
+    const res = spawnSync('npm', ['view', '@crouton-kit/crtr', 'version'], { encoding: 'utf8' });
+    if (res.status !== 0) {
+        warn('could not check for crtr updates (network unavailable)');
+        return;
+    }
+    const latest = res.stdout.trim();
+    const current = currentVersion();
+    if (latest !== current) {
+        err(`crtr: v${latest} available (current ${current}) — run \`crtr update --self\``);
+    }
+}
+function contentUpdate() {
+    const marketplaces = listAllMarketplaces();
+    for (const mkt of marketplaces) {
+        const res = pull(mkt.root);
+        if (res.status !== 0) {
+            throw network(`git pull failed for marketplace ${mkt.name}: ${res.stderr.trim()}`);
+        }
+        updateState(mkt.scope, (s) => {
+            if (!s.marketplaces[mkt.name])
+                s.marketplaces[mkt.name] = {};
+            s.marketplaces[mkt.name].last_updated = nowIso();
+        });
+    }
+    const plugins = listAllPlugins();
+    for (const plugin of plugins) {
+        if (!plugin.enabled)
+            continue;
+        if (plugin.sourceMarketplace)
+            continue;
+        const res = pull(plugin.root);
+        if (res.status !== 0) {
+            throw network(`git pull failed for plugin ${plugin.name}: ${res.stderr.trim()}`);
+        }
+        updateState(plugin.scope, (s) => {
+            if (!s.plugins[plugin.name])
+                s.plugins[plugin.name] = {};
+            s.plugins[plugin.name].last_updated = nowIso();
+        });
+    }
+}
+export function contentCheck() {
+    const marketplaces = listAllMarketplaces();
+    for (const mkt of marketplaces) {
+        const fetchRes = fetch(mkt.root, mkt.ref);
+        if (fetchRes.status !== 0) {
+            warn(`could not fetch ${mkt.name} (network unavailable)`);
+            continue;
+        }
+        const head = currentSha(mkt.root);
+        const remote = remoteSha(mkt.root, mkt.ref);
+        if (head !== null && remote !== null && head !== remote) {
+            err(`crtr: marketplace ${mkt.name} has updates available — run \`crtr update --content\``);
+        }
+    }
+    const plugins = listAllPlugins();
+    for (const plugin of plugins) {
+        if (!plugin.enabled)
+            continue;
+        if (plugin.sourceMarketplace)
+            continue;
+        const ref = 'main';
+        const fetchRes = fetch(plugin.root, ref);
+        if (fetchRes.status !== 0) {
+            warn(`could not fetch ${plugin.name} (network unavailable)`);
+            continue;
+        }
+        const head = currentSha(plugin.root);
+        const remote = remoteSha(plugin.root, ref);
+        if (head !== null && remote !== null && head !== remote) {
+            err(`crtr: plugin ${plugin.name} has updates available — run \`crtr plugin update ${plugin.name}\``);
+        }
+    }
+}
+export function registerUpdateCommand(program) {
+    program
+        .command('update')
+        .description('update crtr itself and/or installed plugins and marketplaces')
+        .option('--self', 'update crtr binary via npm')
+        .option('--content', 'pull updates for all installed plugins and marketplaces')
+        .option('--check', 'check for updates without applying them')
+        .action(async (opts) => {
+        try {
+            const runSelf = opts.self === true;
+            const runContent = opts.content === true;
+            const runBoth = !runSelf && !runContent;
+            if (opts.check) {
+                if (runSelf || runBoth)
+                    selfCheck();
+                if (runContent || runBoth)
+                    contentCheck();
+                return;
+            }
+            if (runSelf || runBoth) {
+                selfUpdate();
+                const scopes = ['user'];
+                if (projectScopeRoot())
+                    scopes.unshift('project');
+                for (const scope of scopes) {
+                    updateState(scope, (s) => {
+                        s.last_self_check = nowIso();
+                    });
+                }
+            }
+            if (runContent || runBoth) {
+                contentUpdate();
+            }
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+}

package/dist/core/artifact.d.ts

@@ -0,0 +1,14 @@
+import { Command } from 'commander';
+export type ArtifactKind = 'plans' | 'specs';
+export declare function mangleCwd(cwd?: string): string;
+export declare function artifactsRoot(kind: ArtifactKind, cwd?: string): string;
+export declare function sanitizeName(raw: string): string;
+export declare function artifactPath(kind: ArtifactKind, name: string, cwd?: string): string;
+export declare function inTmux(): boolean;
+export declare function openInTmuxPane(path: string): void;
+export interface RegisterArtifactOptions {
+    command: 'plan' | 'spec';
+    kind: ArtifactKind;
+    promptFn: (artifactsDir: string) => string;
+}
+export declare function registerArtifactCommand(program: Command, opts: RegisterArtifactOptions): void;