@axplusb/kepler 1.0.5 → 1.0.9

package/src/skills/loader.mjs

@@ -1,147 +1,252 @@
 /**
- * Skills Loader — loads skills from .claude/skills/{name}/SKILL.md
+ * Portable Agent Skills loader.
  *
- * Skills are invoked via /skill-name in REPL or the Skill tool.
- * Each skill has a SKILL.md that defines:
- * - name, description, trigger conditions
- * - The prompt to inject when the skill is invoked
+ * Discovers standard <root>/<skill>/SKILL.md bundles from Kepler and Claude
+ * locations. Only metadata is exposed eagerly; instructions and resources are
+ * loaded on demand through view().
  */
 
-import fs from 'fs';
-import path from 'path';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const DEFAULT_MAX_CHARS = 12_000;
+
+function isWithin(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function parseScalar(value) {
+    const trimmed = value.trim();
+    if (
+        (trimmed.startsWith('"') && trimmed.endsWith('"'))
+        || (trimmed.startsWith("'") && trimmed.endsWith("'"))
+    ) {
+        return trimmed.slice(1, -1);
+    }
+    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+        return trimmed.slice(1, -1).split(',').map(item => parseScalar(item)).filter(Boolean);
+    }
+    if (trimmed === 'true') return true;
+    if (trimmed === 'false') return false;
+    return trimmed;
+}
+
+export function parseSkill(content, fallbackName) {
+    const match = content.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/);
+    if (!match) throw new Error('SKILL.md requires YAML frontmatter');
+
+    const metadata = {};
+    let activeList = null;
+    for (const rawLine of match[1].split(/\r?\n/)) {
+        if (!rawLine.trim() || rawLine.trimStart().startsWith('#')) continue;
+        const listMatch = rawLine.match(/^\s*-\s+(.+)$/);
+        if (listMatch && activeList) {
+            metadata[activeList].push(parseScalar(listMatch[1]));
+            continue;
+        }
+        const fieldMatch = rawLine.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (!fieldMatch) continue;
+        const [, key, rawValue] = fieldMatch;
+        if (!rawValue.trim()) {
+            metadata[key] = [];
+            activeList = key;
+        } else {
+            metadata[key] = parseScalar(rawValue);
+            activeList = null;
+        }
+    }
+
+    const name = String(metadata.name || fallbackName || '').trim();
+    const description = String(metadata.description || '').trim();
+    const instructions = content.slice(match[0].length).trim();
+    if (!name) throw new Error("SKILL.md requires non-empty 'name'");
+    if (!description) throw new Error("SKILL.md requires non-empty 'description'");
+    if (!instructions) throw new Error('SKILL.md requires instruction content');
+
+    return {
+        name,
+        description,
+        aliases: Array.isArray(metadata.aliases) ? metadata.aliases : [],
+        compatibility: Array.isArray(metadata.compatibility) ? metadata.compatibility : [],
+        metadata,
+        instructions,
+        prompt: instructions,
+    };
+}
+
+export function discoverSkillDirectories(root) {
+    if (!root || !fs.existsSync(root)) return [];
+    const resolved = fs.realpathSync(root);
+    if (fs.existsSync(path.join(resolved, 'SKILL.md'))) return [resolved];
+    return fs.readdirSync(resolved, { withFileTypes: true })
+        .filter(entry => entry.isDirectory() && !entry.isSymbolicLink())
+        .map(entry => path.join(resolved, entry.name))
+        .filter(dir => fs.existsSync(path.join(dir, 'SKILL.md')))
+        .sort();
+}
+
+function walkFiles(root) {
+    const files = [];
+    const queue = [root];
+    while (queue.length) {
+        const current = queue.shift();
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            const fullPath = path.join(current, entry.name);
+            if (entry.isSymbolicLink()) continue;
+            if (entry.isDirectory()) queue.push(fullPath);
+            else if (entry.isFile()) files.push(fullPath);
+        }
+    }
+    return files.sort((a, b) => a.localeCompare(b));
+}
+
+function contentHash(root) {
+    const digest = crypto.createHash('sha256');
+    for (const filePath of walkFiles(root)) {
+        digest.update(path.relative(root, filePath).split(path.sep).join('/'));
+        digest.update('\0');
+        digest.update(fs.readFileSync(filePath));
+        digest.update('\0');
+    }
+    return `sha256:${digest.digest('hex')}`;
+}
+
+function bounded(content, maxChars) {
+    if (content.length <= maxChars) return content;
+    const head = Math.floor(maxChars * 0.7);
+    const tail = maxChars - head;
+    return `${content.slice(0, head)}\n\n[... skill content truncated ...]\n\n${content.slice(-tail)}`;
+}
 
 export class SkillsLoader {
-    constructor() {
+    constructor({ homeDir = os.homedir() } = {}) {
+        this.homeDir = homeDir;
         this.skills = new Map();
+        this.versions = new Map();
         this.searchPaths = [];
     }
 
-    /**
-     * Load skills from standard directories.
-     * @param {string} [cwd] - project working directory
-     */
     load(cwd = process.cwd()) {
+        this.skills.clear();
+        this.versions.clear();
+        const project = path.resolve(cwd);
         this.searchPaths = [
-            path.join(cwd, '.claude', 'skills'),
-            path.join(process.env.HOME || '', '.claude', 'skills'),
+            { dir: path.join(project, '.kepler', 'skills'), source: 'kepler-project', scope: 'project', priority: 500 },
+            { dir: path.join(project, '.claude', 'skills'), source: 'claude-project', scope: 'project', priority: 400 },
+            { dir: path.join(this.homeDir, '.kepler', 'skills'), source: 'kepler-global', scope: 'global', priority: 300 },
+            { dir: path.join(this.homeDir, '.claude', 'skills'), source: 'claude-global', scope: 'global', priority: 200 },
         ];
 
-        for (const dir of this.searchPaths) {
-            this._loadFromDir(dir);
-        }
-
+        for (const config of this.searchPaths) this._loadFromDir(config);
         return this;
     }
 
-    _loadFromDir(dir) {
-        try {
-            const entries = fs.readdirSync(dir, { withFileTypes: true });
-            for (const entry of entries) {
-                if (!entry.isDirectory()) continue;
-
-                const skillFile = path.join(dir, entry.name, 'SKILL.md');
-                try {
-                    const content = fs.readFileSync(skillFile, 'utf-8');
-                    const skill = parseSkill(content, entry.name);
-                    if (skill) {
-                        skill.source = skillFile;
-                        this.skills.set(skill.name, skill);
-                    }
-                } catch {
-                    // Skill directory without SKILL.md, skip
-                }
+    _loadFromDir(config) {
+        for (const skillDir of discoverSkillDirectories(config.dir)) {
+            try {
+                const skillFile = path.join(skillDir, 'SKILL.md');
+                if (fs.lstatSync(skillFile).isSymbolicLink()) continue;
+                const parsed = parseSkill(fs.readFileSync(skillFile, 'utf-8'), path.basename(skillDir));
+                const skill = {
+                    ...parsed,
+                    root: skillDir,
+                    source: config.source,
+                    source_id: `${config.source}:${parsed.name}`,
+                    scope: config.scope,
+                    priority: config.priority,
+                    content_hash: contentHash(skillDir),
+                };
+                const versions = this.versions.get(skill.name) || [];
+                versions.push(skill);
+                versions.sort((a, b) => b.priority - a.priority || a.source.localeCompare(b.source));
+                this.versions.set(skill.name, versions);
+                this.skills.set(skill.name, versions[0]);
+            } catch {
+                // Invalid third-party bundles are ignored during discovery.
             }
-        } catch {
-            // Directory does not exist
         }
     }
 
-    /**
-     * Get a skill by name.
-     * @param {string} name
-     * @returns {object|null}
-     */
-    get(name) {
-        // Try exact match, then prefix match
+    get(name, sourceId = null) {
+        if (sourceId) {
+            return (this.versions.get(name) || []).find(skill => skill.source_id === sourceId) || null;
+        }
         if (this.skills.has(name)) return this.skills.get(name);
-        for (const [key, skill] of this.skills) {
-            if (key.startsWith(name) || skill.aliases?.includes(name)) {
-                return skill;
-            }
+        for (const skill of this.skills.values()) {
+            if (skill.name.startsWith(name) || skill.aliases.includes(name)) return skill;
         }
         return null;
     }
 
-    /**
-     * List all loaded skills.
-     * @returns {Array<object>}
-     */
-    list() {
-        return [...this.skills.values()];
+    list({ query = '', source = '', scope = '' } = {}) {
+        const needle = query.toLowerCase();
+        return [...this.skills.values()]
+            .filter(skill => !source || skill.source === source)
+            .filter(skill => !scope || skill.scope === scope)
+            .filter(skill => !needle || `${skill.name} ${skill.description}`.toLowerCase().includes(needle))
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map(skill => ({
+                name: skill.name,
+                description: skill.description,
+                source: skill.source,
+                source_id: skill.source_id,
+                scope: skill.scope,
+                content_hash: skill.content_hash,
+                compatibility: skill.compatibility,
+                shadowed_sources: (this.versions.get(skill.name) || []).slice(1).map(item => item.source_id),
+            }));
     }
 
-    /**
-     * Run a skill, returning its prompt for injection into the conversation.
-     * @param {string} name - skill name
-     * @param {string} [args] - optional arguments
-     * @returns {string} skill prompt
-     */
-    async run(name, args) {
-        const skill = this.get(name);
-        if (!skill) {
-            throw new Error(`Unknown skill: ${name}`);
-        }
-
-        let prompt = skill.prompt;
-        if (args) {
-            prompt = prompt.replace('$ARGUMENTS', args);
-            prompt += `\n\nArguments: ${args}`;
+    view(name, resourcePath = null, { sourceId = null, maxChars = DEFAULT_MAX_CHARS } = {}) {
+        const skill = this.get(name, sourceId);
+        if (!skill) throw new Error(`Unknown skill: ${name}`);
+        if (!resourcePath) {
+            return {
+                name: skill.name,
+                description: skill.description,
+                source: skill.source,
+                source_id: skill.source_id,
+                scope: skill.scope,
+                content_hash: skill.content_hash,
+                compatibility: skill.compatibility,
+                shadowed_sources: (this.versions.get(skill.name) || [])
+                    .filter(item => item.source_id !== skill.source_id)
+                    .map(item => item.source_id),
+                instructions: bounded(skill.instructions, maxChars),
+                resources: walkFiles(skill.root)
+                    .map(file => path.relative(skill.root, file).split(path.sep).join('/'))
+                    .filter(file => file !== 'SKILL.md'),
+                metadata: skill.metadata,
+            };
         }
 
-        return `[Skill: ${skill.name}]\n${prompt}`;
-    }
-}
-
-/**
- * Parse a SKILL.md file into a skill definition.
- */
-function parseSkill(content, dirName) {
-    const lines = content.split('\n');
-    const skill = {
-        name: dirName,
-        description: '',
-        aliases: [],
-        trigger: null,
-        prompt: content,
-    };
-
-    // Parse YAML frontmatter if present
-    if (lines[0]?.trim() === '---') {
-        const endIdx = lines.indexOf('---', 1);
-        if (endIdx > 0) {
-            const frontmatter = lines.slice(1, endIdx).join('\n');
-            for (const line of frontmatter.split('\n')) {
-                const colonIdx = line.indexOf(':');
-                if (colonIdx === -1) continue;
-                const key = line.slice(0, colonIdx).trim();
-                const value = line.slice(colonIdx + 1).trim();
-
-                if (key === 'name') skill.name = value;
-                else if (key === 'description') skill.description = value;
-                else if (key === 'trigger') skill.trigger = value;
-                else if (key === 'aliases') {
-                    skill.aliases = value.replace(/[\[\]]/g, '').split(',').map(s => s.trim());
-                }
-            }
-            skill.prompt = lines.slice(endIdx + 1).join('\n').trim();
+        if (path.isAbsolute(resourcePath)) throw new Error('Skill resource path must be relative');
+        const candidate = path.resolve(skill.root, resourcePath);
+        if (!isWithin(skill.root, candidate)) throw new Error('Skill resource escapes its bundle');
+        const relativeParts = path.relative(skill.root, candidate).split(path.sep);
+        let cursor = skill.root;
+        for (const part of relativeParts) {
+            cursor = path.join(cursor, part);
+            if (!fs.existsSync(cursor)) throw new Error(`Skill resource not found: ${resourcePath}`);
+            if (fs.lstatSync(cursor).isSymbolicLink()) throw new Error('Symlinked skill resources are not allowed');
         }
+        if (!fs.statSync(candidate).isFile()) throw new Error(`Skill resource not found: ${resourcePath}`);
+        return {
+            name: skill.name,
+            source_id: skill.source_id,
+            path: resourcePath,
+            content: bounded(fs.readFileSync(candidate, 'utf-8'), maxChars),
+        };
     }
 
-    // Extract description from first paragraph if not in frontmatter
-    if (!skill.description && skill.prompt) {
-        const firstLine = skill.prompt.split('\n').find(l => l.trim() && !l.startsWith('#'));
-        if (firstLine) skill.description = firstLine.trim().slice(0, 100);
+    async run(name, args) {
+        const skill = this.get(name);
+        if (!skill) throw new Error(`Unknown skill: ${name}`);
+        let prompt = skill.instructions;
+        if (args) prompt = prompt.replace(/\$ARGUMENTS/g, args);
+        return `[Skill: ${skill.name}]\n${prompt}${args ? `\n\nArguments: ${args}` : ''}`;
     }
-
-    return skill;
 }

package/src/terminal/main.mjs

@@ -47,6 +47,17 @@ async function main() {
     return;
   }
 
+  if (subcommand === 'skills' || subcommand === 'skill') {
+    const { runSkillsCommand } = await import('./skills.mjs');
+    try {
+      await runSkillsCommand(subcommandArgs);
+    } catch (err) {
+      process.stderr.write(`\x1b[31m✗ Skills command failed: ${err.message}\x1b[0m\n`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
   if (subcommand === 'login') {
     const { TarangAuth } = await import('../auth/tarang-auth.mjs');
     const auth = new TarangAuth();
@@ -99,6 +110,13 @@ async function main() {
     kepler stats              Show aggregate local session stats
     kepler history            Show recent prompt history
 
+  \x1b[1mSkills:\x1b[0m
+    kepler skills list [--all|--project]
+    kepler skills view <name> [resource]
+    kepler skills install <path-or-git-url> [--project] [--force]
+    kepler skills update <name> [--project]
+    kepler skills remove <name> [--project]
+
   \x1b[1mREPL Commands:\x1b[0m
     /help                   Show available commands
     /stats                  Session metrics (tokens, cost, tools)

package/src/terminal/repl.mjs

@@ -17,17 +17,17 @@
 
 import * as readline from 'node:readline';
 import * as path from 'node:path';
+import * as fs from 'node:fs';
 import { c, progressBar, spinner, inPlace, renderMarkdown, renderDiff, formatElapsed, formatCost, stripAnsi } from './ansi.mjs';
 import { calculateCost, formatCostValue, formatTokens } from '../core/pricing.mjs';
 import { TarangStreamClient, EVENT_TYPES } from '../core/stream-client.mjs';
 import { JsonlWriter } from '../core/jsonl-writer.mjs';
 import { createToolExecutor } from '../core/tool-executor.mjs';
+import { persistProjectArtifacts } from '../core/project-artifacts.mjs';
 import { TarangAuth } from '../auth/tarang-auth.mjs';
 import { ApprovalManager } from '../core/approval.mjs';
 import { resolveBackendUrl } from '../core/backend-url.mjs';
 import { BUILTIN_AGENTS, runAgent } from './agents.mjs';
-import { ContextRetriever } from '../context/retriever.mjs';
-import { buildProjectSkeleton } from '../context/skeleton.mjs';
 import { SessionManager } from '../core/session-manager.mjs';
 import { parseArgs } from '../config/cli-args.mjs';
 import { formatShellCommand, toolDisplayLabel, toolDisplaySummary } from './tool-display.mjs';
@@ -621,6 +621,16 @@ function renderEvent(event) {
       break;
     }
 
+    case 'plan_created': {
+      process.stderr.write(`  ${c.dim('project plan prepared')}\n`);
+      break;
+    }
+
+    case 'goal_created': {
+      process.stderr.write(`  ${c.dim('project goal prepared')}\n`);
+      break;
+    }
+
     case 'session_info': {
       if (data?.session_id) {
         session.id = data.session_id;
@@ -1122,9 +1132,8 @@ export async function startTerminalRepl() {
   const cliArgs = parseArgs(process.argv.slice(2));
   const auth = new TarangAuth();
 
-  // BM25 retriever — indexes project files for search_code tool
-  const retriever = new ContextRetriever(safeCwd());
-  const toolExecutor = createToolExecutor({ retriever });
+  // Projects are registered and indexed on demand through get_project_overview.
+  const toolExecutor = createToolExecutor();
   const skipPerms = cliArgs.freeswim;
   const approval = new ApprovalManager({ autoApprove: skipPerms });
 
@@ -1142,51 +1151,13 @@ export async function startTerminalRepl() {
 
   printBanner(auth);
 
-  // ── Initialization with progress ──
-  // BM25 indexing is CPU-bound and blocks the event loop, so setInterval
-  // spinners won't tick during it. Instead, show a static "Initializing..."
-  // message, then yield to the event loop between phases so the spinner runs.
-  let projectSkeleton = '';
-
-  // Phase 1: Show immediate feedback
+  // ── Initialization ──
   process.stderr.write(`  ${c.brand('⠋')} ${c.dim('Initializing...')}\r`);
-
-  // Fetch user in parallel (network I/O, won't block event loop)
-  const userPromise = fetchUser(ctx);
-
-  // Phase 2: BM25 index — CPU-bound, blocks event loop.
-  // Wrap in a microtask break so the initial message renders first.
-  const indexResult = await new Promise((resolve) => {
-    // Let the event loop flush stderr before blocking
-    setImmediate(async () => {
-      try {
-        process.stderr.write(`\r  ${c.brand('⠹')} ${c.dim('Indexing project files...')}${' '.repeat(20)}\r`);
-        const result = await retriever.buildIndex();
-        resolve(result);
-      } catch {
-        resolve({ fileCount: 0, chunkCount: 0 });
-      }
-    });
-  });
-
-  // Phase 3: Build skeleton (fast, synchronous)
-  process.stderr.write(`\r  ${c.brand('⠼')} ${c.dim('Building project skeleton...')}${' '.repeat(20)}\r`);
-  await new Promise(r => setImmediate(r)); // yield so message renders
-  projectSkeleton = buildProjectSkeleton(safeCwd());
-
-  // Wait for user fetch
-  await userPromise;
+  await fetchUser(ctx);
 
   // Clear the spinner line
   process.stderr.write(`\r${' '.repeat(60)}\r`);
-
-  // Show init summary
-  if (indexResult.fileCount > 0) {
-    process.stderr.write(`  ${c.green('✓')} ${c.dim(`Indexed ${indexResult.fileCount} files (${indexResult.chunkCount} chunks)`)}\n`);
-  }
-  if (projectSkeleton) {
-    process.stderr.write(`  ${c.green('✓')} ${c.dim('Project skeleton ready')}\n`);
-  }
+  process.stderr.write(`  ${c.green('✓')} ${c.dim('Ready; projects will be indexed on demand')}\n`);
   if (session.user) {
     process.stderr.write(`  ${c.green('✓')} ${c.dim(`Logged in as ${session.user.github_username || session.user.email || 'user'}`)}\n`);
   }
@@ -1367,9 +1338,17 @@ export async function startTerminalRepl() {
 
       const execContext = { cwd: safeCwd() };
       if (skipPerms) execContext.freeswim = true;
-      if (projectSkeleton) execContext.project_skeleton = projectSkeleton;
+      execContext.project_resources = toolExecutor.getProjectResources();
+      execContext.agent_context = toolExecutor.getAgentContext();
 
       for await (const event of client.execute(input, execContext, session.history)) {
+        if (event.type === 'plan_created' || event.type === 'goal_created') {
+          persistProjectArtifacts(
+            event.data,
+            toolExecutor.getProjectResources(),
+            message => process.stderr.write(`  ${c.dim(message)}\n`),
+          );
+        }
         renderEvent(event);
 
         if (event.type === 'content_partial') {

package/src/terminal/skills.mjs

@@ -0,0 +1,54 @@
+import { SkillInstaller } from '../skills/installer.mjs';
+import { SkillsLoader } from '../skills/loader.mjs';
+
+function has(args, flag) {
+    return args.includes(flag);
+}
+
+function scopeFrom(args) {
+    return has(args, '--project') ? 'project' : 'global';
+}
+
+function print(value) {
+    process.stdout.write(typeof value === 'string' ? `${value}\n` : `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export async function runSkillsCommand(args, { cwd = process.cwd() } = {}) {
+    const action = args[0] || 'list';
+    const rest = args.slice(1);
+    const scope = scopeFrom(rest);
+    const installer = new SkillInstaller({ cwd });
+    const loader = new SkillsLoader().load(cwd);
+
+    if (action === 'list') {
+        const rows = loader.list({ scope: has(rest, '--all') ? '' : scope });
+        if (has(rest, '--json')) print(rows);
+        else if (!rows.length) print('No skills found.');
+        else for (const row of rows) print(`${row.name}\t${row.scope}\t${row.source}\t${row.description}`);
+        return;
+    }
+    if (action === 'view') {
+        const name = rest.find(arg => !arg.startsWith('--'));
+        if (!name) throw new Error('Usage: kepler skills view <name> [resource-path]');
+        const nameIndex = rest.indexOf(name);
+        const resource = rest.slice(nameIndex + 1).find(arg => !arg.startsWith('--')) || null;
+        print(loader.view(name, resource));
+        return;
+    }
+    if (action === 'install') {
+        const source = rest.find(arg => !arg.startsWith('--'));
+        print(installer.install(source, { scope, force: has(rest, '--force') }));
+        return;
+    }
+    if (action === 'remove') {
+        const name = rest.find(arg => !arg.startsWith('--'));
+        print(installer.remove(name, { scope }));
+        return;
+    }
+    if (action === 'update') {
+        const name = rest.find(arg => !arg.startsWith('--'));
+        print(installer.update(name, { scope }));
+        return;
+    }
+    throw new Error(`Unknown skills command: ${action}`);
+}

package/src/tools/bash.mjs

@@ -27,6 +27,7 @@ export const BashTool = {
             command: { type: 'string', description: 'The command to execute' },
             timeout: { type: 'number', description: 'Timeout in ms (max 600000)', default: 120000 },
             description: { type: 'string', description: 'Description of what this command does' },
+            cwd: { type: 'string', description: 'Working directory for the command' },
             run_in_background: { type: 'boolean', description: 'Run in background', default: false },
         },
         required: ['command'],
@@ -40,7 +41,7 @@ export const BashTool = {
         const timeout = Math.min(input.timeout || 120000, 600000);
 
         if (input.run_in_background) {
-            return runBackground(input.command);
+            return runBackground(input.command, input.cwd);
         }
 
         return new Promise((resolve) => {
@@ -50,6 +51,7 @@ export const BashTool = {
             let exitCode = null;
 
             const proc = spawn('bash', ['-c', input.command], {
+                cwd: input.cwd,
                 env: { ...process.env },
                 stdio: ['pipe', 'pipe', 'pipe'],
                 timeout: 0, // we handle timeout ourselves
@@ -120,9 +122,10 @@ export const BashTool = {
 const backgroundJobs = new Map();
 let bgJobId = 0;
 
-function runBackground(command) {
+function runBackground(command, cwd) {
     const id = ++bgJobId;
     const proc = spawn('bash', ['-c', command], {
+        cwd,
         detached: true,
         stdio: ['ignore', 'pipe', 'pipe'],
     });