@crouton-kit/crouter 0.1.1 → 0.1.3

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,106 @@
+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.
+
+## See also
+
+- \`crtr plan list\` — list saved plans for the current directory
+- \`crtr plan show <name>\` — print the body of a saved plan
+- \`crtr plan edit <name>\` — open a saved plan in \$EDITOR
+- \`crtr plan path [name]\` — absolute path of a plan or the plans directory
+`;
+}

package/dist/prompts/skill.d.ts

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

package/dist/prompts/skill.js

@@ -0,0 +1,49 @@
+export function skillPrompt() {
+    return `# Skill workflow
+
+\`crtr\` ships skills — markdown reference with frontmatter that you pull on
+demand. When the user's task matches a skill's description, run
+\`crtr skill show <name>\` and apply the guidance. Ambiguous names exit \`4\` —
+disambiguate with \`<plugin>:<name>\`.
+
+## Discover
+
+\`\`\`
+crtr skill list                    # one per line: <scope>:<plugin>/<name>  — <description>
+crtr skill search <query>          # rank by name, description, keywords
+crtr skill grep <pattern>          # regex search across SKILL.md bodies
+\`\`\`
+
+## Load
+
+\`\`\`
+crtr skill show <name>             # print SKILL.md body to stdout
+crtr skill show <plugin>:<name>    # disambiguate when names collide
+crtr skill path <name>             # absolute path to SKILL.md
+crtr skill where <name>            # {scope, plugin, path} as JSON
+\`\`\`
+
+\`show\` is the default verb: \`crtr skill <name>\` (with no verb) also prints
+the body.
+
+## Author
+
+\`\`\`
+crtr skill new <plugin>:<name> --description "..."   # scaffold a new skill
+crtr skill show authoring-skills                     # the SKILL.md authoring guide
+\`\`\`
+
+## Toggle
+
+\`\`\`
+crtr skill enable <name>           # clear any disable in the chosen scope
+crtr skill disable <name>          # hide from list and agent discovery
+\`\`\`
+
+## Exit codes
+
+- \`0\` — success
+- \`3\` — skill not found
+- \`4\` — ambiguous name; use \`<plugin>:<name>\`
+`;
+}

package/dist/prompts/spec.d.ts

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

package/dist/prompts/spec.js

@@ -0,0 +1,113 @@
+export function specPrompt(specsDir) {
+    return `# Spec workflow
+
+You are entering a focused spec session. The goal is to produce a design +
+requirements spec — a document describing **what** to build, the shape of the
+solution, and the behaviors it must satisfy. A spec is upstream of a plan: it
+captures decisions, not implementation steps.
+
+Specs for this directory live at:
+  ${specsDir}
+
+If a relevant prior spec already exists there, read it first. Treat an
+existing spec as the starting point — extend or revise rather than restart.
+
+## Phase 1: Shape
+
+Build a comprehensive picture of the problem and the relevant code. Surface
+existing patterns, constraints, and prior decisions.
+
+- **Launch up to 3 Explore subagents IN PARALLEL** (single message, multiple
+  tool calls) to cover the codebase efficiently.
+  - Use 1 agent for narrow, well-scoped problems.
+  - Use multiple agents when the spec touches several subsystems or you need
+    to compare existing implementations.
+  - Quality over quantity — 3 agents maximum.
+
+After exploration, draft a high-level design in your head: the shape of the
+solution, the new or changed pieces, the boundaries.
+
+## Phase 2: Requirements
+
+Translate the shape into concrete behavioral requirements. Each requirement
+should be:
+
+- **Testable** — has a clear pass/fail condition.
+- **Behavior-focused** — describes what the system does, not how.
+- **Scoped** — covers one observable behavior.
+
+Prefer EARS-style phrasing where it fits (\`When <trigger>, the system shall
+<behavior>\`), but do not force it. Group requirements by capability.
+
+You may launch a Plan agent to draft requirements for a specific capability
+in parallel, but for small specs writing them yourself is usually faster.
+
+## Phase 3: Deepen
+
+- Read the critical files identified during Phase 1 to deepen your
+  understanding before locking decisions.
+- Reconcile the requirements against the shape — if a requirement reveals a
+  gap in the design, refine the design before saving.
+- Use **AskUserQuestion** for any remaining ambiguities. Bias toward asking
+  when a decision is non-obvious or when the user's intent is genuinely
+  unclear.
+
+**Important:** Use AskUserQuestion ONLY to clarify requirements or choose
+between approaches. Never use it to ask "is this spec okay?" or "should I
+save?" — the save step below is the approval moment.
+
+## Phase 4: Save
+
+Save the spec with \`crtr spec --name <kebab-case-name>\`. Pipe the markdown
+body in via stdin (heredoc):
+
+\`\`\`bash
+crtr spec --name <kebab-case-name> <<'EOF'
+# Spec: <one-line title>
+
+## Context
+<the problem this spec addresses, what motivates it, and the intended
+outcome. Include relevant constraints — user goals, stakeholders, deadlines.>
+
+## Design
+<the shape of the solution. Components, data flow, key decisions and why
+they were chosen. Reference existing code with \`file_path:line_number\`.>
+
+## Requirements
+<grouped behavioral requirements. Each one testable.>
+
+### <Capability A>
+- When <trigger>, the system shall <behavior>.
+- ...
+
+### <Capability B>
+- ...
+
+## Out of scope
+<things explicitly NOT covered, so the next reader knows where the edges
+are.>
+
+## Open questions
+<anything you could not resolve. Empty if all decisions are pinned.>
+EOF
+\`\`\`
+
+- Pick a short, descriptive kebab-case name. Names may be nested
+  (\`crtr spec --name auth/refresh-tokens\`).
+- The file lands at \`${specsDir}/<name>.md\`.
+- If you are running inside tmux, the saved spec 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 spec
+in chat — the user can read the file.
+
+## See also
+
+- \`crtr spec list\` — list saved specs for the current directory
+- \`crtr spec show <name>\` — print the body of a saved spec
+- \`crtr spec edit <name>\` — open a saved spec in \$EDITOR
+- \`crtr spec path [name]\` — absolute path of a spec or the specs directory
+`;
+}

package/dist/types.d.ts

@@ -0,0 +1,115 @@
+export type Scope = 'user' | 'project';
+export declare const ExitCode: {
+    readonly SUCCESS: 0;
+    readonly GENERAL: 1;
+    readonly USAGE: 2;
+    readonly NOT_FOUND: 3;
+    readonly AMBIGUOUS: 4;
+    readonly NETWORK: 5;
+};
+export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];
+export declare const SCHEMA_VERSION = 1;
+export interface OwnerRef {
+    name?: string;
+    email?: string;
+}
+export interface PluginManifest {
+    name: string;
+    version?: string;
+    description?: string;
+    source?: string;
+    owner?: OwnerRef;
+    kinds?: string[];
+}
+export interface MarketplacePluginEntry {
+    name: string;
+    source: string;
+    version?: string;
+    description?: string;
+    keywords?: string[];
+}
+export interface MarketplaceManifest {
+    name: string;
+    version?: string;
+    owner?: OwnerRef;
+    plugins: MarketplacePluginEntry[];
+}
+export interface ConfigMarketplaceEntry {
+    url: string;
+    ref: string;
+    installed_at: string;
+}
+export interface ConfigPluginEntry {
+    enabled: boolean;
+    source_marketplace?: string;
+    version?: string;
+}
+export interface ConfigSkillEntry {
+    enabled: boolean;
+}
+export type AutoUpdateMode = 'notify' | 'apply' | false;
+export interface AutoUpdateConfig {
+    crtr: AutoUpdateMode;
+    content: AutoUpdateMode;
+    interval_hours: number;
+}
+export interface ScopeConfig {
+    schema_version: number;
+    marketplaces: Record<string, ConfigMarketplaceEntry>;
+    plugins: Record<string, ConfigPluginEntry>;
+    skills: Record<string, ConfigSkillEntry>;
+    auto_update: AutoUpdateConfig;
+}
+export interface ScopeState {
+    marketplaces: Record<string, {
+        last_updated?: string;
+    }>;
+    plugins: Record<string, {
+        last_updated?: string;
+    }>;
+    last_self_check?: string;
+}
+export interface SkillFrontmatter {
+    name: string;
+    description?: string;
+    keywords?: string[];
+}
+export interface Skill {
+    name: string;
+    plugin: string;
+    scope: Scope;
+    path: string;
+    pluginRoot: string;
+    frontmatter: SkillFrontmatter;
+    enabled: boolean;
+    disabledIn?: Scope;
+}
+export interface InstalledPlugin {
+    name: string;
+    scope: Scope;
+    root: string;
+    manifest: PluginManifest;
+    enabled: boolean;
+    sourceMarketplace?: string;
+    version?: string;
+}
+export interface InstalledMarketplace {
+    name: string;
+    scope: Scope;
+    root: string;
+    manifest: MarketplaceManifest;
+    url: string;
+    ref: string;
+}
+export declare const PLUGIN_MANIFEST_DIR = ".crouter-plugin";
+export declare const PLUGIN_MANIFEST_FILE = "plugin.json";
+export declare const MARKETPLACE_MANIFEST_DIR = ".crouter-marketplace";
+export declare const MARKETPLACE_MANIFEST_FILE = "marketplace.json";
+export declare const CRTR_DIR_NAME = ".crouter";
+export declare const CONFIG_FILE = "config.json";
+export declare const STATE_FILE = "state.json";
+export declare const SKILL_ENTRY_FILE = "SKILL.md";
+export declare const SKILLS_DIR = "skills";
+export declare function defaultScopeConfig(): ScopeConfig;
+export declare function skillConfigKey(plugin: string, name: string): string;
+export declare function defaultScopeState(): ScopeState;

package/dist/types.js

@@ -0,0 +1,33 @@
+export const ExitCode = {
+    SUCCESS: 0,
+    GENERAL: 1,
+    USAGE: 2,
+    NOT_FOUND: 3,
+    AMBIGUOUS: 4,
+    NETWORK: 5,
+};
+export const SCHEMA_VERSION = 1;
+export const PLUGIN_MANIFEST_DIR = '.crouter-plugin';
+export const PLUGIN_MANIFEST_FILE = 'plugin.json';
+export const MARKETPLACE_MANIFEST_DIR = '.crouter-marketplace';
+export const MARKETPLACE_MANIFEST_FILE = 'marketplace.json';
+export const CRTR_DIR_NAME = '.crouter';
+export const CONFIG_FILE = 'config.json';
+export const STATE_FILE = 'state.json';
+export const SKILL_ENTRY_FILE = 'SKILL.md';
+export const SKILLS_DIR = 'skills';
+export function defaultScopeConfig() {
+    return {
+        schema_version: SCHEMA_VERSION,
+        marketplaces: {},
+        plugins: {},
+        skills: {},
+        auto_update: { crtr: 'notify', content: 'notify', interval_hours: 24 },
+    };
+}
+export function skillConfigKey(plugin, name) {
+    return `${plugin}:${name}`;
+}
+export function defaultScopeState() {
+    return { marketplaces: {}, plugins: {} };
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.1.1",
-  "description": "crouter CLI",
+  "version": "0.1.3",
+  "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "crouter": "dist/cli.js"
+    "crtr": "bin/crtr",
+    "crouter": "bin/crouter"
   },
   "exports": {
     ".": {
@@ -18,12 +19,14 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "bin"
   ],
   "scripts": {
     "build": "tsc",
     "dev": "tsx src/cli.ts",
-    "link": "npm link"
+    "link": "npm link",
+    "prepublishOnly": "npm run build"
   },
   "repository": {
     "type": "git",