@crouton-kit/crouter 0.1.9 → 0.2.2

package/dist/commands/skill.js

@@ -1,11 +1,11 @@
 import { join } from 'node:path';
 import { writeFileSync } from 'node:fs';
-import { SCOPE_SKILL_PLUGIN, SKILL_ENTRY_FILE, SKILLS_DIR, } from '../types.js';
+import { SCOPE_SKILL_PLUGIN, SKILL_ENTRY_FILE, SKILLS_DIR, SKILL_TYPES, isSkillType, } 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, scopeSkillsDir, } from '../core/scope.js';
-import { resolveSkill, listAllSkills, listInstalledPlugins, findPluginByName, parseSkillQualifier, } from '../core/resolver.js';
+import { resolveSkill, listAllSkills, listInstalledPlugins, findPluginByName, parseSkillQualifier, listSkillSiblings, listSkillChildren, } 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';
@@ -23,7 +23,7 @@ const KNOWN_VERBS = new Set([
     'disable',
     'search',
 ]);
-const AUTHORING_GUIDE_SKILL = 'authoring-skills';
+const AUTHORING_GUIDE_SKILL = 'crouter-development/skills';
 function buildShowFooter(skillPath) {
     return (`crtr: edit this skill directly at ${skillPath} — ` +
         `for SKILL.md authoring guidance run \`crtr skill ${AUTHORING_GUIDE_SKILL}\``);
@@ -31,6 +31,46 @@ function buildShowFooter(skillPath) {
 function wrapSkill(name, path, content) {
     return `<skill name="${name}" path="${path}">\n${content.endsWith('\n') ? content : content + '\n'}</skill>`;
 }
+function formatNeighborQualifier(s) {
+    return s.plugin === SCOPE_SKILL_PLUGIN ? `${s.scope}:${s.name}` : `${s.plugin}/${s.name}`;
+}
+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. Use `--no-neighbors` to suppress.*',
+        '',
+    ];
+    if (siblings.length > 0) {
+        lines.push('**Siblings:**');
+        for (const s of siblings) {
+            const desc = s.frontmatter.description !== undefined ? s.frontmatter.description : '';
+            lines.push(`- \`${formatNeighborQualifier(s)}\`${desc ? ` — ${desc}` : ''}`);
+        }
+        if (children.length > 0)
+            lines.push('');
+    }
+    if (children.length > 0) {
+        lines.push('**Nested:**');
+        for (const s of children) {
+            const desc = s.frontmatter.description !== undefined ? s.frontmatter.description : '';
+            lines.push(`- \`${formatNeighborQualifier(s)}\`${desc ? ` — ${desc}` : ''}`);
+        }
+    }
+    return lines.join('\n');
+}
+function appendNeighbors(skill, body, suppress) {
+    if (suppress)
+        return 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`;
+}
 const SKILL_IDENTIFIER_HELP = 'Skill identifier forms (accepted by show, path, where, enable, disable):\n' +
     '  <name>                       bare name — resolves scope-root first, then plugins\n' +
     '  <plugin>:<name>              explicit plugin (canonical)\n' +
@@ -52,7 +92,8 @@ export function registerSkillCommands(program) {
             try {
                 const skillObj = resolveSkill(nameOrVerb);
                 const content = readText(skillObj.path);
-                const body = opts.frontmatter ? content : parseFrontmatter(content).body;
+                const rawBody = opts.frontmatter ? content : parseFrontmatter(content).body;
+                const body = appendNeighbors(skillObj, rawBody, false);
                 out(wrapSkill(skillObj.name, skillObj.path, body));
                 hint(buildShowFooter(skillObj.path));
             }
@@ -117,6 +158,7 @@ export function registerSkillCommands(program) {
         .option('--scope <scope>', 'user|project')
         .option('--plugin <name>', 'filter by plugin name')
         .option('--frontmatter', 'include YAML frontmatter in the printed body')
+        .option('--no-neighbors', 'suppress the auto-appended ## Neighbors section')
         .option('--json', 'emit JSON')
         .addHelpText('after', '\nExamples:\n' +
         '  crtr skill show rules                              # bare name\n' +
@@ -133,7 +175,9 @@ export function registerSkillCommands(program) {
             }
             const skillObj = resolveSkill(name, resolveOpts);
             const content = readText(skillObj.path);
-            const body = opts.frontmatter ? content : parseFrontmatter(content).body;
+            const rawBody = opts.frontmatter ? content : parseFrontmatter(content).body;
+            const suppressNeighbors = opts.neighbors === false;
+            const body = appendNeighbors(skillObj, rawBody, suppressNeighbors);
             if (opts.json) {
                 jsonOut({
                     name: skillObj.name,
@@ -235,12 +279,20 @@ export function registerSkillCommands(program) {
         .description('scaffold a new skill — <name> (scope-direct) or <plugin>:<name>')
         .option('--scope <scope>', 'user|project (default: project then user)')
         .option('--description <text>', 'skill description for frontmatter')
+        .option('--type <type>', `skill type for frontmatter — one of: ${SKILL_TYPES.join(' | ')}`)
         .action(async (qualifier, opts) => {
         try {
             const { plugin: pluginName, name: skillName } = parseSkillQualifier(qualifier);
             if (!skillName) {
                 throw usage('skill name required');
             }
+            let skillType;
+            if (opts.type !== undefined) {
+                if (!isSkillType(opts.type)) {
+                    throw usage(`unknown skill type: ${opts.type} / valid: ${SKILL_TYPES.join(' | ')}`);
+                }
+                skillType = opts.type;
+            }
             const scopeArg = opts.scope !== undefined ? resolveScopeArg(opts.scope) : undefined;
             // Scope-direct: no plugin qualifier, or explicit `_:` sentinel
             if (pluginName === undefined || pluginName === SCOPE_SKILL_PLUGIN) {
@@ -266,6 +318,7 @@ export function registerSkillCommands(program) {
                 const fm = serializeFrontmatter({
                     name: skillName,
                     description: opts.description,
+                    type: skillType,
                 });
                 writeFileSync(skillFile, fm, 'utf8');
                 out(skillFile);
@@ -292,6 +345,7 @@ export function registerSkillCommands(program) {
             const fm = serializeFrontmatter({
                 name: skillName,
                 description: opts.description,
+                type: skillType,
             });
             writeFileSync(skillFile, fm, 'utf8');
             out(skillFile);
@@ -305,7 +359,7 @@ export function registerSkillCommands(program) {
     // create — pick a template type
     skill
         .command('create [topic...]')
-        .description('pick a template type for a new skill (primer | playbook | freeform)')
+        .description(`pick a template type for a new skill (${SKILL_TYPES.join(' | ')})`)
         .action(async (topic) => {
         const arg = topic && topic.length > 0 ? topic.join(' ') : '';
         out(skillCreatePrompt(arg));
@@ -313,7 +367,7 @@ export function registerSkillCommands(program) {
     // template — full workflow + skeleton for one template type
     skill
         .command('template <type> [topic...]')
-        .description('full workflow + skeleton for a template type (primer | playbook | freeform)')
+        .description(`full workflow + skeleton for a template type (${SKILL_TYPES.join(' | ')})`)
         .action(async (type, topic) => {
         const arg = topic && topic.length > 0 ? topic.join(' ') : '';
         out(skillTemplatePrompt(type, arg));

package/dist/core/frontmatter.d.ts

@@ -1,4 +1,4 @@
-import type { SkillFrontmatter } from '../types.js';
+import { type SkillFrontmatter } from '../types.js';
 export interface ParsedFrontmatter {
     data: SkillFrontmatter | null;
     body: string;

package/dist/core/frontmatter.js

@@ -1,3 +1,4 @@
+import { isSkillType } from '../types.js';
 const FRONTMATTER_RE = /^---\s*\r?\n([\s\S]*?)\r?\n---\s*\r?\n?/;
 export function parseFrontmatter(source) {
     const match = source.match(FRONTMATTER_RE);
@@ -126,6 +127,7 @@ function parseSimpleYaml(yaml) {
         name: typeof out.name === 'string' ? out.name : '',
         description: typeof out.description === 'string' ? out.description : undefined,
         keywords: Array.isArray(out.keywords) ? out.keywords : undefined,
+        type: isSkillType(out.type) ? out.type : undefined,
     };
     return fm;
 }
@@ -141,6 +143,9 @@ export function serializeFrontmatter(data) {
     if (data.description !== undefined) {
         lines.push(`description: ${quoteIfNeeded(data.description)}`);
     }
+    if (data.type !== undefined) {
+        lines.push(`type: ${data.type}`);
+    }
     if (data.keywords && data.keywords.length) {
         const inline = `[${data.keywords.map(quoteIfNeeded).join(', ')}]`;
         lines.push(`keywords: ${inline}`);

package/dist/core/resolver.d.ts

@@ -13,6 +13,8 @@ export declare function effectiveSkillEnabled(pluginName: string, skillName: str
 export declare function listSkillsInPlugin(plugin: InstalledPlugin, cfgs?: ScopeConfigs): Skill[];
 export declare function listScopeRootSkills(scope: Scope, cfgs?: ScopeConfigs): Skill[];
 export declare function listAllSkills(scopeFilter?: Scope): Skill[];
+export declare function listSkillSiblings(skill: Skill): Skill[];
+export declare function listSkillChildren(skill: Skill): Skill[];
 export interface SkillResolutionOpts {
     scope?: Scope;
     pluginFilter?: string;

package/dist/core/resolver.js

@@ -5,8 +5,29 @@ import { listDirs, pathExists, readText, walkFiles, } from './fs-utils.js';
 import { readMarketplaceManifest, readPluginManifest } from './manifest.js';
 import { parseFrontmatter } from './frontmatter.js';
 import { ambiguous, notFound, usage } from './errors.js';
-import { marketplacesDir, pluginsDir, projectScopeRoot, scopeSkillsDir, userScopeRoot, } from './scope.js';
+import { builtinSkillsRoot, marketplacesDir, pluginsDir, projectScopeRoot, scopeSkillsDir, userScopeRoot, } from './scope.js';
+function getBuiltinPlugin() {
+    const root = builtinSkillsRoot();
+    if (!pathExists(root))
+        return null;
+    const manifest = readPluginManifest(root);
+    if (!manifest)
+        return null;
+    return {
+        name: manifest.name,
+        scope: 'builtin',
+        root,
+        manifest,
+        enabled: true,
+        builtin: true,
+        version: manifest.version,
+    };
+}
 export function listInstalledPlugins(scope) {
+    if (scope === 'builtin') {
+        const builtin = getBuiltinPlugin();
+        return builtin ? [builtin] : [];
+    }
     const dir = pluginsDir(scope);
     if (!dir || !pathExists(dir))
         return [];
@@ -40,13 +61,14 @@ export function listAllPlugins() {
     if (projectScopeRoot())
         scopes.push('project');
     scopes.push('user');
+    scopes.push('builtin');
     return scopes.flatMap(listInstalledPlugins);
 }
 export function findPluginByName(name, scope) {
     if (scope) {
         return listInstalledPlugins(scope).find((p) => p.name === name) ?? null;
     }
-    for (const s of ['project', 'user'].filter((sc) => sc === 'project' ? projectScopeRoot() !== null : true)) {
+    for (const s of ['project', 'user', 'builtin'].filter((sc) => sc === 'project' ? projectScopeRoot() !== null : true)) {
         const match = listInstalledPlugins(s).find((p) => p.name === name);
         if (match)
             return match;
@@ -100,6 +122,8 @@ export function listSkillsInPlugin(plugin, cfgs) {
     return skills.sort((a, b) => a.name.localeCompare(b.name));
 }
 export function listScopeRootSkills(scope, cfgs) {
+    if (scope === 'builtin')
+        return [];
     const skillsRoot = scopeSkillsDir(scope);
     if (!skillsRoot || !pathExists(skillsRoot))
         return [];
@@ -138,6 +162,41 @@ export function listAllSkills(scopeFilter) {
         ...plugins.filter((p) => p.enabled).flatMap((p) => listSkillsInPlugin(p, cfgs)),
     ];
 }
+function enumerateNeighborPool(skill) {
+    if (skill.plugin === SCOPE_SKILL_PLUGIN) {
+        return listScopeRootSkills(skill.scope);
+    }
+    const plugin = listInstalledPlugins(skill.scope).find((p) => p.name === skill.plugin);
+    if (!plugin)
+        return [];
+    return listSkillsInPlugin(plugin);
+}
+export function listSkillSiblings(skill) {
+    const pool = enumerateNeighborPool(skill);
+    const segs = skill.name.split('/');
+    const depth = segs.length;
+    const parentPrefix = segs.slice(0, -1).join('/');
+    return pool.filter((s) => {
+        if (s.name === skill.name)
+            return false;
+        const sSegs = s.name.split('/');
+        if (sSegs.length !== depth)
+            return false;
+        if (parentPrefix === '')
+            return !s.name.includes('/');
+        return s.name.startsWith(parentPrefix + '/');
+    });
+}
+export function listSkillChildren(skill) {
+    const pool = enumerateNeighborPool(skill);
+    const prefix = skill.name + '/';
+    return pool.filter((s) => {
+        if (!s.name.startsWith(prefix))
+            return false;
+        const rest = s.name.slice(prefix.length);
+        return rest.length > 0 && !rest.includes('/');
+    });
+}
 export function resolveSkill(rawName, opts = {}) {
     const parsed = parseSkillQualifier(rawName);
     if (parsed.scope && opts.scope && parsed.scope !== opts.scope) {
@@ -353,6 +412,8 @@ export function parseSkillQualifier(raw) {
 }
 function orderPluginsByResolution(plugins) {
     const score = (p) => {
+        if (p.scope === 'builtin')
+            return 4;
         const fromMarketplace = Boolean(p.sourceMarketplace);
         if (p.scope === 'project' && !fromMarketplace)
             return 0;

package/dist/core/scope.d.ts

@@ -1,4 +1,5 @@
 import type { Scope } from '../types.js';
+export declare function builtinSkillsRoot(): string;
 export declare function userScopeRoot(): string;
 export declare function findProjectScopeRoot(startDir?: string): string | null;
 export declare function projectScopeRoot(startDir?: string): string | null;

package/dist/core/scope.js

@@ -1,9 +1,17 @@
 import { homedir } from 'node:os';
 import { existsSync, statSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { CRTR_DIR_NAME } from '../types.js';
 import { usage } from './errors.js';
 let cachedProjectRoot;
+export function builtinSkillsRoot() {
+    // Resolve relative to this file: src/core/scope.ts → src/builtin-skills/ OR dist/core/scope.js → dist/builtin-skills/
+    const thisFile = fileURLToPath(import.meta.url);
+    const coreDir = dirname(thisFile);
+    const pkgDir = dirname(coreDir); // src/ or dist/
+    return join(pkgDir, 'builtin-skills');
+}
 export function userScopeRoot() {
     return join(homedir(), CRTR_DIR_NAME);
 }
@@ -37,6 +45,8 @@ export function projectScopeRoot(startDir) {
     return findProjectScopeRoot(startDir);
 }
 export function scopeRoot(scope) {
+    if (scope === 'builtin')
+        return builtinSkillsRoot();
     return scope === 'user' ? userScopeRoot() : projectScopeRoot();
 }
 export function requireScopeRoot(scope) {
@@ -71,9 +81,9 @@ export function resolveScopeArg(scopeArg) {
     if (scopeArg === undefined)
         return 'all';
     const value = scopeArg.toLowerCase();
-    if (value === 'user' || value === 'project' || value === 'all')
+    if (value === 'user' || value === 'project' || value === 'builtin' || value === 'all')
         return value;
-    throw usage(`invalid --scope: ${scopeArg} (expected user|project|all)`);
+    throw usage(`invalid --scope: ${scopeArg} (expected user|project|builtin|all)`);
 }
 export function listScopes(scopeArg) {
     const v = resolveScopeArg(scopeArg);
@@ -82,6 +92,7 @@ export function listScopes(scopeArg) {
         if (projectScopeRoot())
             out.push('project');
         out.push('user');
+        out.push('builtin');
         return out;
     }
     return [v];