@crouton-kit/crouter 0.1.1 → 0.1.2

package/dist/core/output.d.ts

@@ -0,0 +1,35 @@
+import { CrtrError } from './errors.js';
+export declare const stdoutColor: {
+    dim: (s: string) => string;
+    bold: (s: string) => string;
+    red: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    blue: (s: string) => string;
+    cyan: (s: string) => string;
+    gray: (s: string) => string;
+};
+export declare const stderrColor: {
+    dim: (s: string) => string;
+    bold: (s: string) => string;
+    red: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    blue: (s: string) => string;
+    cyan: (s: string) => string;
+    gray: (s: string) => string;
+};
+export declare function out(line: string): void;
+export declare function err(line: string): void;
+export declare function hint(line: string): void;
+export declare function warn(line: string): void;
+export declare function info(line: string): void;
+export declare function jsonOut(obj: unknown): void;
+export declare function jsonError(error: CrtrError | Error): void;
+export declare function isTTY(): boolean;
+export declare function isJsonRequested(opts: {
+    json?: boolean;
+} | undefined): boolean;
+export declare function handleError(error: unknown, opts?: {
+    json?: boolean;
+}): never;

package/dist/core/output.js

@@ -0,0 +1,99 @@
+import { CrtrError } from './errors.js';
+import { ExitCode, SCHEMA_VERSION } from '../types.js';
+const ANSI = {
+    reset: '\x1b[0m',
+    dim: '\x1b[2m',
+    bold: '\x1b[1m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m',
+};
+function shouldColor(stream) {
+    if (process.env.NO_COLOR)
+        return false;
+    if (process.env.FORCE_COLOR)
+        return true;
+    return Boolean(stream.isTTY);
+}
+function paint(stream, code, text) {
+    return shouldColor(stream) ? `${code}${text}${ANSI.reset}` : text;
+}
+export const stdoutColor = {
+    dim: (s) => paint(process.stdout, ANSI.dim, s),
+    bold: (s) => paint(process.stdout, ANSI.bold, s),
+    red: (s) => paint(process.stdout, ANSI.red, s),
+    green: (s) => paint(process.stdout, ANSI.green, s),
+    yellow: (s) => paint(process.stdout, ANSI.yellow, s),
+    blue: (s) => paint(process.stdout, ANSI.blue, s),
+    cyan: (s) => paint(process.stdout, ANSI.cyan, s),
+    gray: (s) => paint(process.stdout, ANSI.gray, s),
+};
+export const stderrColor = {
+    dim: (s) => paint(process.stderr, ANSI.dim, s),
+    bold: (s) => paint(process.stderr, ANSI.bold, s),
+    red: (s) => paint(process.stderr, ANSI.red, s),
+    green: (s) => paint(process.stderr, ANSI.green, s),
+    yellow: (s) => paint(process.stderr, ANSI.yellow, s),
+    blue: (s) => paint(process.stderr, ANSI.blue, s),
+    cyan: (s) => paint(process.stderr, ANSI.cyan, s),
+    gray: (s) => paint(process.stderr, ANSI.gray, s),
+};
+export function out(line) {
+    process.stdout.write(line.endsWith('\n') ? line : line + '\n');
+}
+export function err(line) {
+    process.stderr.write(line.endsWith('\n') ? line : line + '\n');
+}
+export function hint(line) {
+    err(stderrColor.dim(`# ${line}`));
+}
+export function warn(line) {
+    err(stderrColor.yellow(`crtr: ${line}`));
+}
+export function info(line) {
+    err(stderrColor.gray(`crtr: ${line}`));
+}
+export function jsonOut(obj) {
+    const enriched = typeof obj === 'object' && obj !== null && !Array.isArray(obj)
+        ? { schema_version: SCHEMA_VERSION, ...obj }
+        : { schema_version: SCHEMA_VERSION, data: obj };
+    process.stdout.write(JSON.stringify(enriched, null, 2) + '\n');
+}
+export function jsonError(error) {
+    const e = error instanceof CrtrError ? error : new CrtrError('error', error.message, ExitCode.GENERAL);
+    process.stdout.write(JSON.stringify({
+        schema_version: SCHEMA_VERSION,
+        error: true,
+        code: e.code,
+        message: e.message,
+        ...(e.details ?? {}),
+    }, null, 2) + '\n');
+}
+export function isTTY() {
+    return Boolean(process.stdout.isTTY);
+}
+export function isJsonRequested(opts) {
+    return Boolean(opts?.json);
+}
+export function handleError(error, opts = {}) {
+    if (error instanceof CrtrError) {
+        if (opts.json) {
+            jsonError(error);
+        }
+        else {
+            err(stderrColor.red(`crtr: ${error.message}`));
+        }
+        process.exit(error.exitCode);
+    }
+    const e = error;
+    if (opts.json) {
+        jsonError(e);
+    }
+    else {
+        err(stderrColor.red(`crtr: ${e.message ?? String(e)}`));
+    }
+    process.exit(ExitCode.GENERAL);
+}

package/dist/core/resolver.d.ts

@@ -0,0 +1,28 @@
+import type { InstalledMarketplace, InstalledPlugin, Scope, ScopeConfig, Skill } from '../types.js';
+export declare function listInstalledPlugins(scope: Scope): InstalledPlugin[];
+export declare function listAllPlugins(): InstalledPlugin[];
+export declare function findPluginByName(name: string, scope?: Scope): InstalledPlugin | null;
+interface ScopeConfigs {
+    project?: ScopeConfig;
+    user: ScopeConfig;
+}
+export declare function effectiveSkillEnabled(pluginName: string, skillName: string, cfgs: ScopeConfigs): {
+    enabled: boolean;
+    disabledIn?: Scope;
+};
+export declare function listSkillsInPlugin(plugin: InstalledPlugin, cfgs?: ScopeConfigs): Skill[];
+export declare function listAllSkills(scopeFilter?: Scope): Skill[];
+export interface SkillResolutionOpts {
+    scope?: Scope;
+    pluginFilter?: string;
+}
+export declare function resolveSkill(rawName: string, opts?: SkillResolutionOpts): Skill;
+export declare function parseSkillQualifier(raw: string): {
+    plugin?: string;
+    name: string;
+};
+export declare function listInstalledMarketplaces(scope: Scope): InstalledMarketplace[];
+export declare function listAllMarketplaces(): InstalledMarketplace[];
+export declare function findMarketplaceByName(name: string, scope?: Scope): InstalledMarketplace | null;
+export declare function scopeRootsLabel(): string;
+export {};

package/dist/core/resolver.js

@@ -0,0 +1,228 @@
+import { join, relative, sep, dirname } from 'node:path';
+import { SKILL_ENTRY_FILE, SKILLS_DIR, skillConfigKey, } from '../types.js';
+import { readConfig } from './config.js';
+import { listDirs, pathExists, readText, walkFiles, } from './fs-utils.js';
+import { readMarketplaceManifest, readPluginManifest } from './manifest.js';
+import { parseFrontmatter } from './frontmatter.js';
+import { ambiguous, notFound } from './errors.js';
+import { marketplacesDir, pluginsDir, projectScopeRoot, userScopeRoot } from './scope.js';
+export function listInstalledPlugins(scope) {
+    const dir = pluginsDir(scope);
+    if (!dir || !pathExists(dir))
+        return [];
+    const cfg = readConfig(scope);
+    const out = [];
+    for (const name of listDirs(dir)) {
+        const root = join(dir, name);
+        const manifest = readPluginManifest(root);
+        if (!manifest)
+            continue;
+        const entry = cfg.plugins[name];
+        let version;
+        if (entry && entry.version !== undefined)
+            version = entry.version;
+        else if (manifest.version !== undefined)
+            version = manifest.version;
+        out.push({
+            name,
+            scope,
+            root,
+            manifest,
+            enabled: entry ? entry.enabled : true,
+            sourceMarketplace: entry ? entry.source_marketplace : undefined,
+            version,
+        });
+    }
+    return out;
+}
+export function listAllPlugins() {
+    const scopes = [];
+    if (projectScopeRoot())
+        scopes.push('project');
+    scopes.push('user');
+    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)) {
+        const match = listInstalledPlugins(s).find((p) => p.name === name);
+        if (match)
+            return match;
+    }
+    return null;
+}
+function loadScopeConfigs() {
+    const user = readConfig('user');
+    if (projectScopeRoot())
+        return { project: readConfig('project'), user };
+    return { user };
+}
+export function effectiveSkillEnabled(pluginName, skillName, cfgs) {
+    const key = skillConfigKey(pluginName, skillName);
+    if (cfgs.project && cfgs.project.skills[key] !== undefined) {
+        const e = cfgs.project.skills[key].enabled;
+        return e ? { enabled: true } : { enabled: false, disabledIn: 'project' };
+    }
+    if (cfgs.user.skills[key] !== undefined) {
+        const e = cfgs.user.skills[key].enabled;
+        return e ? { enabled: true } : { enabled: false, disabledIn: 'user' };
+    }
+    return { enabled: true };
+}
+export function listSkillsInPlugin(plugin, cfgs) {
+    const skillsRoot = join(plugin.root, SKILLS_DIR);
+    if (!pathExists(skillsRoot))
+        return [];
+    const configs = cfgs === undefined ? loadScopeConfigs() : cfgs;
+    const skills = [];
+    const skillFiles = walkFiles(skillsRoot, (n) => n === SKILL_ENTRY_FILE);
+    for (const file of skillFiles) {
+        const rel = relative(skillsRoot, dirname(file));
+        const name = rel.split(sep).join('/');
+        if (!name)
+            continue;
+        const source = readText(file);
+        const { data } = parseFrontmatter(source);
+        const { enabled, disabledIn } = effectiveSkillEnabled(plugin.name, name, configs);
+        skills.push({
+            name,
+            plugin: plugin.name,
+            scope: plugin.scope,
+            path: file,
+            pluginRoot: plugin.root,
+            frontmatter: data === null ? { name } : data,
+            enabled,
+            disabledIn,
+        });
+    }
+    return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
+export function listAllSkills(scopeFilter) {
+    const plugins = scopeFilter ? listInstalledPlugins(scopeFilter) : listAllPlugins();
+    const cfgs = loadScopeConfigs();
+    return plugins
+        .filter((p) => p.enabled)
+        .flatMap((p) => listSkillsInPlugin(p, cfgs));
+}
+export function resolveSkill(rawName, opts = {}) {
+    const { plugin: pluginQualifier, name } = parseSkillQualifier(rawName);
+    const plugins = opts.scope ? listInstalledPlugins(opts.scope) : listAllPlugins();
+    const enabledPlugins = plugins.filter((p) => p.enabled);
+    const cfgs = loadScopeConfigs();
+    const ordered = orderPluginsByResolution(enabledPlugins);
+    const matches = [];
+    for (const plugin of ordered) {
+        if (pluginQualifier && plugin.name !== pluginQualifier)
+            continue;
+        if (opts.pluginFilter && plugin.name !== opts.pluginFilter)
+            continue;
+        const skillPath = join(plugin.root, SKILLS_DIR, ...name.split('/'), SKILL_ENTRY_FILE);
+        if (!pathExists(skillPath))
+            continue;
+        const source = readText(skillPath);
+        const { data } = parseFrontmatter(source);
+        const { enabled, disabledIn } = effectiveSkillEnabled(plugin.name, name, cfgs);
+        matches.push({
+            name,
+            plugin: plugin.name,
+            scope: plugin.scope,
+            path: skillPath,
+            pluginRoot: plugin.root,
+            frontmatter: data === null ? { name } : data,
+            enabled,
+            disabledIn,
+        });
+    }
+    if (matches.length === 0) {
+        throw notFound(pluginQualifier
+            ? `skill not found: ${pluginQualifier}:${name}`
+            : `skill not found: ${name}`, { skill: name, plugin: pluginQualifier });
+    }
+    if (matches.length === 1)
+        return matches[0];
+    const sameScopeAndPlugin = matches.every((m) => m.plugin === matches[0].plugin && m.scope === matches[0].scope);
+    if (sameScopeAndPlugin)
+        return matches[0];
+    // Resolution order picks the first; flag ambiguity only if user didn't qualify.
+    if (!pluginQualifier) {
+        return matches[0];
+    }
+    throw ambiguous(`ambiguous skill: ${name}`, {
+        skill: name,
+        candidates: matches.map((m) => ({
+            plugin: m.plugin,
+            scope: m.scope,
+            path: m.path,
+        })),
+    });
+}
+export function parseSkillQualifier(raw) {
+    const idx = raw.indexOf(':');
+    if (idx === -1)
+        return { name: raw };
+    return { plugin: raw.slice(0, idx), name: raw.slice(idx + 1) };
+}
+function orderPluginsByResolution(plugins) {
+    const score = (p) => {
+        const fromMarketplace = Boolean(p.sourceMarketplace);
+        if (p.scope === 'project' && !fromMarketplace)
+            return 0;
+        if (p.scope === 'user' && !fromMarketplace)
+            return 1;
+        if (p.scope === 'project' && fromMarketplace)
+            return 2;
+        return 3;
+    };
+    return [...plugins].sort((a, b) => score(a) - score(b));
+}
+export function listInstalledMarketplaces(scope) {
+    const dir = marketplacesDir(scope);
+    if (!dir || !pathExists(dir))
+        return [];
+    const cfg = readConfig(scope);
+    const out = [];
+    for (const name of listDirs(dir)) {
+        const root = join(dir, name);
+        const manifest = readMarketplaceManifest(root);
+        if (!manifest)
+            continue;
+        const entry = cfg.marketplaces[name];
+        const url = entry && entry.url !== undefined ? entry.url : '';
+        const ref = entry && entry.ref !== undefined ? entry.ref : 'main';
+        out.push({
+            name,
+            scope,
+            root,
+            manifest,
+            url,
+            ref,
+        });
+    }
+    return out;
+}
+export function listAllMarketplaces() {
+    const scopes = [];
+    if (projectScopeRoot())
+        scopes.push('project');
+    scopes.push('user');
+    return scopes.flatMap(listInstalledMarketplaces);
+}
+export function findMarketplaceByName(name, scope) {
+    if (scope) {
+        return listInstalledMarketplaces(scope).find((m) => m.name === name) ?? null;
+    }
+    for (const s of ['project', 'user']) {
+        if (s === 'project' && !projectScopeRoot())
+            continue;
+        const found = listInstalledMarketplaces(s).find((m) => m.name === name);
+        if (found)
+            return found;
+    }
+    return null;
+}
+export function scopeRootsLabel() {
+    const proj = projectScopeRoot();
+    return proj ? `project=${proj}, user=${userScopeRoot()}` : `user=${userScopeRoot()}`;
+}

package/dist/core/scope.d.ts

@@ -0,0 +1,12 @@
+import type { Scope } from '../types.js';
+export declare function userScopeRoot(): string;
+export declare function findProjectScopeRoot(startDir?: string): string | null;
+export declare function projectScopeRoot(startDir?: string): string | null;
+export declare function scopeRoot(scope: Scope): string | null;
+export declare function requireScopeRoot(scope: Scope): string;
+export declare function ensureProjectScopeRoot(startDir?: string): string;
+export declare function pluginsDir(scope: Scope): string | null;
+export declare function marketplacesDir(scope: Scope): string | null;
+export declare function resolveScopeArg(scopeArg: string | undefined): Scope | 'all';
+export declare function listScopes(scopeArg: string | undefined): Scope[];
+export declare function resetScopeCache(): void;

package/dist/core/scope.js

@@ -0,0 +1,87 @@
+import { homedir } from 'node:os';
+import { existsSync, statSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { CRTR_DIR_NAME } from '../types.js';
+import { usage } from './errors.js';
+let cachedProjectRoot;
+export function userScopeRoot() {
+    return join(homedir(), CRTR_DIR_NAME);
+}
+export function findProjectScopeRoot(startDir = process.cwd()) {
+    if (cachedProjectRoot !== undefined)
+        return cachedProjectRoot;
+    const userRoot = userScopeRoot();
+    let dir = resolve(startDir);
+    while (true) {
+        const candidate = join(dir, CRTR_DIR_NAME);
+        if (candidate !== userRoot && existsSync(candidate)) {
+            try {
+                if (statSync(candidate).isDirectory()) {
+                    cachedProjectRoot = candidate;
+                    return candidate;
+                }
+            }
+            catch {
+                /* fall through */
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            cachedProjectRoot = null;
+            return null;
+        }
+        dir = parent;
+    }
+}
+export function projectScopeRoot(startDir) {
+    return findProjectScopeRoot(startDir);
+}
+export function scopeRoot(scope) {
+    return scope === 'user' ? userScopeRoot() : projectScopeRoot();
+}
+export function requireScopeRoot(scope) {
+    const root = scopeRoot(scope);
+    if (!root) {
+        throw usage(`no ${scope} scope available — run \`crtr init\` here or use --scope user`);
+    }
+    return root;
+}
+export function ensureProjectScopeRoot(startDir = process.cwd()) {
+    const found = findProjectScopeRoot(startDir);
+    if (found)
+        return found;
+    // Initialize new project scope at startDir
+    const root = join(resolve(startDir), CRTR_DIR_NAME);
+    cachedProjectRoot = root;
+    return root;
+}
+export function pluginsDir(scope) {
+    const root = scopeRoot(scope);
+    return root ? join(root, 'plugins') : null;
+}
+export function marketplacesDir(scope) {
+    const root = scopeRoot(scope);
+    return root ? join(root, 'marketplaces') : null;
+}
+export function resolveScopeArg(scopeArg) {
+    if (scopeArg === undefined)
+        return 'all';
+    const value = scopeArg.toLowerCase();
+    if (value === 'user' || value === 'project' || value === 'all')
+        return value;
+    throw usage(`invalid --scope: ${scopeArg} (expected user|project|all)`);
+}
+export function listScopes(scopeArg) {
+    const v = resolveScopeArg(scopeArg);
+    if (v === 'all') {
+        const out = [];
+        if (projectScopeRoot())
+            out.push('project');
+        out.push('user');
+        return out;
+    }
+    return [v];
+}
+export function resetScopeCache() {
+    cachedProjectRoot = undefined;
+}

package/dist/prompts/plan.d.ts

@@ -0,0 +1 @@
+export declare function planPrompt(plansDir: string): string;

package/dist/prompts/plan.js

@@ -0,0 +1,99 @@
+export function planPrompt(plansDir) {
+    return `# Planning workflow
+
+You are entering a focused planning session. The goal is to produce an
+implementation plan that another agent (or you, in a later turn) can execute
+without re-discovering everything. A plan is a map, not a tutorial.
+
+Plans for this directory live at:
+  ${plansDir}
+
+If a relevant prior plan already exists there, read it first.
+
+## Phase 1: Initial Understanding
+
+Build a comprehensive picture of the user's request and the code involved.
+Actively search for existing functions, utilities, and patterns that can be
+reused — do not propose new code when a suitable implementation already
+exists.
+
+- **Launch up to 3 Explore subagents IN PARALLEL** (single message, multiple
+  tool calls) to cover the codebase efficiently.
+  - Use 1 agent when the task is isolated to known files, the user provided
+    specific paths, or the change is small and targeted.
+  - Use multiple agents when scope is uncertain, multiple areas of the codebase
+    are involved, or you need to understand existing patterns before planning.
+  - Quality over quantity — 3 agents maximum; usually 1 is right.
+  - When using multiple agents, give each a distinct focus (existing impls,
+    related components, test patterns) so they do not duplicate work.
+
+## Phase 2: Design
+
+Design the implementation approach based on Phase 1 findings.
+
+- **Default**: launch at least 1 Plan agent — it validates your understanding
+  and surfaces alternatives.
+- **Skip agents** only for truly trivial tasks (typo fixes, single-line
+  changes, simple renames).
+- **Multiple agents (up to 3)** for tasks that benefit from different
+  perspectives — large refactors, architectural changes, many edge cases.
+
+In the Plan agent prompt:
+- Provide comprehensive background context from Phase 1, including filenames
+  and code-path traces.
+- Describe requirements and constraints.
+- Request a detailed implementation plan.
+
+## Phase 3: Review
+
+- Read the critical files identified by agents to deepen your understanding.
+- Ensure the plan aligns with the user's original request.
+- Use **AskUserQuestion** to clarify any remaining questions with the user.
+  Bias toward asking when a decision is non-obvious — interrupting once is
+  cheaper than building the wrong thing.
+
+**Important:** Use AskUserQuestion ONLY to clarify requirements or choose
+between approaches. Never use it to ask the user "is this plan okay?" or
+"should I proceed?" — the save step below is the approval moment.
+
+## Phase 4: Final Plan
+
+Save the plan with \`crtr plan --name <kebab-case-name>\`. Pipe the markdown
+body in via stdin (heredoc):
+
+\`\`\`bash
+crtr plan --name <kebab-case-name> <<'EOF'
+# Plan: <one-line title>
+
+## Context
+<why this change is being made — the problem it addresses, what prompted it,
+and the intended outcome>
+
+## Recommended approach
+<your chosen approach. Include only the recommendation, not all alternatives.
+Be concise enough to scan, detailed enough to execute.>
+
+## Files to modify / create
+- \`path/to/file.ts\` — <what changes>
+- ...
+
+## Existing utilities to reuse
+- \`function-name\` from \`path/to/file.ts:LL\` — <why it fits>
+
+## Verification
+<how to test the changes end-to-end — run the code, run tests, etc.>
+EOF
+\`\`\`
+
+- Pick a short, descriptive kebab-case name. Names may be nested
+  (\`crtr plan --name auth/jwt-refresh\`) — they become subdirectories.
+- The file lands at \`${plansDir}/<name>.md\`.
+- If you are running inside tmux, the saved plan auto-opens in a side pane
+  via termrender. No extra step needed.
+
+## Phase 5: Done
+
+Your turn ends after the save command succeeds. No need to summarize the plan
+in chat — the user can read the file.
+`;
+}

package/dist/prompts/spec.d.ts

@@ -0,0 +1 @@
+export declare function specPrompt(specsDir: string): string;