@crouton-kit/crouter 0.3.11 → 0.3.13

package/dist/commands/skill/read.js

@@ -0,0 +1,89 @@
+import { defineLeaf } from '../../core/command.js';
+import { CrtrError } from '../../core/errors.js';
+import { resolveSkill, resolveCategory, buildCategoryIndex, } from '../../core/resolver.js';
+import { resolveScopeArg } from '../../core/scope.js';
+import { parseFrontmatter } from '../../core/frontmatter.js';
+import { readText } from '../../core/fs-utils.js';
+import { appendNeighbors } from './shared.js';
+export const readLeaf = defineLeaf({
+    name: 'read',
+    help: {
+        name: 'skill read',
+        summary: 'load SKILL.md body and resolution metadata for a named skill',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Skill identifier. Forms: <name>, <plugin>/<name>, <scope>/<name>, <scope>/<plugin>/<name>.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution when name is ambiguous.' },
+            { kind: 'flag', name: 'plugin', type: 'string', required: false, constraint: 'Narrows resolution to a specific plugin.' },
+            { kind: 'flag', name: 'frontmatter', type: 'bool', required: false, constraint: 'When present, includes YAML frontmatter in the output content.' },
+            { kind: 'flag', name: 'no-body', type: 'bool', required: false, constraint: 'When present, omits the body — returns resolution metadata only. Use to confirm a skill exists or locate it without loading SKILL.md.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'Resolved skill name, or category id when the name resolved to a group.' },
+            { name: 'kind', type: 'string', required: false, constraint: '"category" when the name resolved to a group rather than a single skill.' },
+            { name: 'count', type: 'integer', required: false, constraint: 'Number of skills in the category. Present when kind is "category".' },
+            { name: 'plugin', type: 'string', required: false, constraint: 'Plugin the skill belongs to. Omitted for category reads.' },
+            { name: 'scope', type: 'string', required: false, constraint: 'Scope the skill was resolved from. Omitted for category reads.' },
+            { name: 'path', type: 'string', required: false, constraint: 'Absolute path to SKILL.md. Omitted for category reads.' },
+            { name: 'content', type: 'string', required: false, constraint: 'SKILL.md body or category index. Omitted when --no-body is set.' },
+            { name: 'follow_up', type: 'string', required: false, constraint: 'Hints at variant flags or next commands. Omitted when --no-body is set.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const nameRaw = input['name'];
+        const scopeStr = input['scope'];
+        const pluginFilter = input['plugin'];
+        const includeFrontmatter = input['frontmatter'];
+        const noBody = input['noBody'];
+        const resolveOpts = {};
+        if (scopeStr !== undefined) {
+            const resolved = resolveScopeArg(scopeStr);
+            if (resolved !== 'all')
+                resolveOpts.scope = resolved;
+        }
+        if (pluginFilter !== undefined)
+            resolveOpts.pluginFilter = pluginFilter;
+        let skillObj;
+        let notFoundErr;
+        try {
+            skillObj = resolveSkill(nameRaw, resolveOpts);
+        }
+        catch (e) {
+            if (e instanceof CrtrError && e.code === 'not_found') {
+                notFoundErr = e;
+            }
+            else {
+                throw e;
+            }
+        }
+        if (skillObj === undefined) {
+            const cat = resolveCategory(nameRaw, resolveOpts);
+            if (cat !== null) {
+                if (noBody)
+                    return { name: cat.id, kind: 'category', count: cat.skills.length };
+                return {
+                    name: cat.id,
+                    kind: 'category',
+                    count: cat.skills.length,
+                    content: buildCategoryIndex(cat),
+                    follow_up: 'Read a listed skill with `crtr skill read <id>`.',
+                };
+            }
+            throw notFoundErr;
+        }
+        const out = {
+            name: skillObj.name,
+            plugin: skillObj.plugin,
+            scope: skillObj.scope,
+            path: skillObj.path,
+        };
+        if (noBody)
+            return out;
+        const rawContent = readText(skillObj.path);
+        const rawBody = includeFrontmatter ? rawContent : parseFrontmatter(rawContent).body;
+        out['content'] = appendNeighbors(skillObj, rawBody);
+        out['follow_up'] = 'Add --no-body to skip the body and return path/scope/plugin only. Add --frontmatter to include YAML frontmatter in content.';
+        return out;
+    },
+});

package/dist/commands/skill/shared.d.ts

@@ -0,0 +1,19 @@
+import type { Skill, Scope } from '../../types.js';
+export declare function formatNeighborQualifier(s: Skill): string;
+export declare function formatNeighborKeywords(s: Skill): string;
+export declare function buildNeighborsSection(skill: Skill): string | null;
+export declare function appendNeighbors(skill: Skill, body: string): string;
+export declare function resolveWriteScope(scopeStr: string | undefined): Scope;
+export declare const VALID_TYPES: readonly ["playbook", "primer", "reference", "runbook", "freeform"];
+type CatalogSource = {
+    plugin: string;
+    roots: string[];
+};
+/** The skill subtree's live state: the loaded-skills catalog as a self-named
+ *  `<skills count="N">` element. The tag carries the label and the count is an
+ *  attribute, so the body is the grouped tree alone — no "Loaded skills (N)"
+ *  header to duplicate. Returns null (block omitted) when discovery fails or
+ *  nothing is loaded. */
+export declare function buildSkillCatalog(): string | null;
+export declare function renderCatalogSection(label: string, sources: CatalogSource[], descriptions: Map<string, string>, out: string[]): void;
+export {};

package/dist/commands/skill/shared.js

@@ -0,0 +1,207 @@
+import { stateBlock } from '../../core/help.js';
+import { usage } from '../../core/errors.js';
+import { SCOPE_SKILL_PLUGIN } from '../../types.js';
+import { listSkillSiblings, listSkillChildren, listAllSkills, listAllPlugins, } from '../../core/resolver.js';
+import { resolveScopeArg, projectScopeRoot } from '../../core/scope.js';
+// ---------------------------------------------------------------------------
+// Neighbors section (ported from old impl)
+// ---------------------------------------------------------------------------
+export function formatNeighborQualifier(s) {
+    return s.plugin === SCOPE_SKILL_PLUGIN
+        ? `${s.scope}/${s.name}`
+        : `${s.plugin}/${s.name}`;
+}
+export function formatNeighborKeywords(s) {
+    const kw = s.frontmatter.keywords;
+    if (!kw || kw.length === 0)
+        return '';
+    return ` — [${kw.join(', ')}]`;
+}
+export function buildNeighborsSection(skill) {
+    const siblings = listSkillSiblings(skill);
+    const children = listSkillChildren(skill);
+    if (siblings.length === 0 && children.length === 0)
+        return null;
+    const lines = [
+        '## Neighbors',
+        '*Auto-discovered from filesystem. Run `crtr skill read <name>` for full description + body.*',
+        '',
+    ];
+    if (siblings.length > 0) {
+        lines.push('**Siblings:**');
+        for (const s of siblings) {
+            lines.push(`- \`${formatNeighborQualifier(s)}\`${formatNeighborKeywords(s)}`);
+        }
+        if (children.length > 0)
+            lines.push('');
+    }
+    if (children.length > 0) {
+        lines.push('**Nested:**');
+        for (const s of children) {
+            lines.push(`- \`${formatNeighborQualifier(s)}\`${formatNeighborKeywords(s)}`);
+        }
+    }
+    return lines.join('\n');
+}
+export function appendNeighbors(skill, body) {
+    const section = buildNeighborsSection(skill);
+    if (section === null)
+        return body;
+    const sep = body.endsWith('\n') ? '\n' : '\n\n';
+    return body + sep + `<neighbors>\n${section}\n</neighbors>\n`;
+}
+// ---------------------------------------------------------------------------
+// Resolve scope for enable/disable/scaffold
+// ---------------------------------------------------------------------------
+export function resolveWriteScope(scopeStr) {
+    if (scopeStr !== undefined) {
+        const resolved = resolveScopeArg(scopeStr);
+        if (resolved === 'all') {
+            throw usage('scope must be user or project, not all');
+        }
+        return resolved;
+    }
+    return projectScopeRoot() !== null ? 'project' : 'user';
+}
+// ---------------------------------------------------------------------------
+// Valid skill types (used by author sub-branch)
+// ---------------------------------------------------------------------------
+export const VALID_TYPES = ['playbook', 'primer', 'reference', 'runbook', 'freeform'];
+const CATALOG_T = 5;
+/** The skill subtree's live state: the loaded-skills catalog as a self-named
+ *  `<skills count="N">` element. The tag carries the label and the count is an
+ *  attribute, so the body is the grouped tree alone — no "Loaded skills (N)"
+ *  header to duplicate. Returns null (block omitted) when discovery fails or
+ *  nothing is loaded. */
+export function buildSkillCatalog() {
+    let skills;
+    try {
+        skills = listAllSkills().filter((s) => s.enabled);
+    }
+    catch {
+        return null;
+    }
+    if (skills.length === 0)
+        return null;
+    const pluginDescriptions = new Map();
+    for (const p of listAllPlugins()) {
+        if (p.manifest.description)
+            pluginDescriptions.set(p.name, p.manifest.description);
+    }
+    const bySource = new Map();
+    for (const s of skills) {
+        const key = `${s.scope}\t${s.plugin}`;
+        const arr = bySource.get(key);
+        if (arr)
+            arr.push(s);
+        else
+            bySource.set(key, [s]);
+    }
+    const projectSources = [];
+    const userSources = [];
+    for (const [key, group] of bySource) {
+        const [scope, plugin] = key.split('\t');
+        const names = group.map((g) => g.name);
+        const roots = names
+            .filter((n) => !names.some((m) => m !== n && n.startsWith(m + '/')))
+            .sort();
+        if (roots.length === 0)
+            continue;
+        (scope === 'project' ? projectSources : userSources).push({ plugin, roots });
+    }
+    const body = [];
+    renderCatalogSection('Project', projectSources, pluginDescriptions, body);
+    renderCatalogSection('User', userSources, pluginDescriptions, body);
+    // renderCatalogSection leads each section with a blank separator; drop the
+    // leading one so the element body starts on its first real line.
+    while (body.length > 0 && body[0] === '')
+        body.shift();
+    body.push('');
+    body.push("Groups shown as `name/  N skills` are collapsed. Read the group to get its menu before assuming a skill is or isn't there: `crtr skill read <group>` (or `crtr skill find list --plugin <group>`). Search across everything with `crtr skill find search <topic>`.");
+    return stateBlock('skills', { count: skills.length }, body.join('\n'));
+}
+export function renderCatalogSection(label, sources, descriptions, out) {
+    if (sources.length === 0)
+        return;
+    const count = sources.reduce((n, s) => n + s.roots.length, 0);
+    out.push('');
+    out.push(`${label} (${count})`);
+    const sentinel = sources.filter((s) => s.plugin === SCOPE_SKILL_PLUGIN);
+    const named = sources
+        .filter((s) => s.plugin !== SCOPE_SKILL_PLUGIN)
+        .sort((a, b) => a.plugin.localeCompare(b.plugin));
+    for (const s of sentinel) {
+        if (s.roots.length > CATALOG_T) {
+            out.push(`  (scope skills)  ${s.roots.length} skills`);
+        }
+        else {
+            for (const n of s.roots)
+                out.push(`  ${n}`);
+        }
+    }
+    if (named.length === 0)
+        return;
+    const classified = named.map((s) => {
+        const subcats = new Map();
+        const bare = [];
+        for (const n of s.roots) {
+            const slash = n.indexOf('/');
+            if (slash === -1) {
+                bare.push(n);
+            }
+            else {
+                const sub = n.slice(0, slash);
+                const rest = n.slice(slash + 1);
+                const arr = subcats.get(sub);
+                if (arr)
+                    arr.push(rest);
+                else
+                    subcats.set(sub, [rest]);
+            }
+        }
+        return { plugin: s.plugin, roots: s.roots, subcats, bare };
+    });
+    const descSuffix = (plugin) => {
+        const d = descriptions.get(plugin);
+        if (!d)
+            return '';
+        return ` — ${d.length > 80 ? d.slice(0, 77) + '…' : d}`;
+    };
+    // inlineW aligns the count column for collapsed + inline-enumerated plugins
+    // (nested plugins render their own header line, don't use this width)
+    const inlineW = classified
+        .filter((p) => {
+        const direct = p.subcats.size + p.bare.length;
+        return direct > CATALOG_T || p.subcats.size < 2;
+    })
+        .reduce((m, p) => Math.max(m, p.plugin.length + 1), 0);
+    for (const p of classified) {
+        const direct = p.subcats.size + p.bare.length;
+        if (direct > CATALOG_T) {
+            out.push(`  ${(p.plugin + '/').padEnd(inlineW)}  ${p.roots.length} skills${descSuffix(p.plugin)}`);
+            continue;
+        }
+        if (p.subcats.size >= 2) {
+            out.push(`  ${p.plugin}/`);
+            if (p.bare.length > 0) {
+                out.push(`    ${[...p.bare].sort().join(', ')}`);
+            }
+            const subKeys = [...p.subcats.keys()].sort();
+            const subW = subKeys
+                .map((k) => `${k}/`)
+                .reduce((m, l) => (l.length > m ? l.length : m), 0);
+            for (const subKey of subKeys) {
+                const children = p.subcats.get(subKey).sort();
+                if (children.length > CATALOG_T) {
+                    out.push(`    ${(subKey + '/').padEnd(subW)}  ${children.length} skills`);
+                }
+                else {
+                    out.push(`    ${(subKey + '/').padEnd(subW)}  ${children.join(', ')}`);
+                }
+            }
+        }
+        else {
+            out.push(`  ${(p.plugin + '/').padEnd(inlineW)}  ${[...p.roots].sort().join(', ')}`);
+        }
+    }
+}

package/dist/commands/skill/state.d.ts

@@ -0,0 +1,3 @@
+export declare const stateEnable: import("../../core/command.js").LeafDef;
+export declare const stateDisable: import("../../core/command.js").LeafDef;
+export declare const stateBranch: import("../../core/command.js").BranchDef;

package/dist/commands/skill/state.js

@@ -0,0 +1,69 @@
+import { defineLeaf, defineBranch } from '../../core/command.js';
+import { skillConfigKey } from '../../types.js';
+import { resolveSkill } from '../../core/resolver.js';
+import { requireScopeRoot } from '../../core/scope.js';
+import { updateConfig, ensureScopeInitialized } from '../../core/config.js';
+import { resolveWriteScope } from './shared.js';
+async function toggleSkill(input, enabled) {
+    const nameRaw = input['name'];
+    const scopeStr = input['scope'];
+    const scope = resolveWriteScope(scopeStr);
+    const skillObj = resolveSkill(nameRaw);
+    const key = skillConfigKey(skillObj.plugin, skillObj.name);
+    const scopeRootPath = requireScopeRoot(scope);
+    ensureScopeInitialized(scope, scopeRootPath);
+    updateConfig(scope, (cfg) => {
+        cfg.skills[key] = { enabled };
+    });
+    return { name: skillObj.name, scope, enabled };
+}
+export const stateEnable = defineLeaf({
+    name: 'enable',
+    help: {
+        name: 'skill state enable',
+        summary: 'enable a skill in the given scope',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Skill identifier. Same forms as skill read.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: project if available, else user.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'Resolved skill name.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope where the enable was applied.' },
+            { name: 'enabled', type: 'boolean', required: true, constraint: 'Always true.' },
+        ],
+        outputKind: 'object',
+        effects: ['Writes the skill enable flag to config.json in the target scope.'],
+    },
+    run: async (input) => toggleSkill(input, true),
+});
+export const stateDisable = defineLeaf({
+    name: 'disable',
+    help: {
+        name: 'skill state disable',
+        summary: 'disable a skill in the given scope, hiding it from list and agent discovery',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Skill identifier. Same forms as skill read.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: project if available, else user.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'Resolved skill name.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope where the disable was applied.' },
+            { name: 'enabled', type: 'boolean', required: true, constraint: 'Always false.' },
+        ],
+        outputKind: 'object',
+        effects: ['Writes the skill disable flag to config.json in the target scope.'],
+    },
+    run: async (input) => toggleSkill(input, false),
+});
+export const stateBranch = defineBranch({
+    name: 'state',
+    help: {
+        name: 'skill state',
+        summary: 'enable or disable skills',
+        children: [
+            { name: 'enable', desc: 'enable a skill', useWhen: 'making a previously disabled skill available again' },
+            { name: 'disable', desc: 'disable a skill', useWhen: 'hiding a skill from list and agent discovery without removing it' },
+        ],
+    },
+    children: [stateEnable, stateDisable],
+});