@axplusb/kepler 1.0.5 → 1.0.10

package/src/skills/installer.mjs

@@ -0,0 +1,188 @@
+/**
+ * Portable skill installation and lock metadata.
+ *
+ * Bundles are copied as data. No scripts or hooks from a skill are executed.
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { discoverSkillDirectories, parseSkill } from './loader.mjs';
+
+function isGitSource(source) {
+    return /^(https?:\/\/|ssh:\/\/|git@|github:)/.test(source) || source.endsWith('.git');
+}
+
+function normalizeGitSource(source) {
+    if (source.startsWith('github:')) {
+        return `https://github.com/${source.slice('github:'.length).replace(/\.git$/, '')}.git`;
+    }
+    return source;
+}
+
+function discoverInstallableSkills(root, maxDepth = 4) {
+    const direct = discoverSkillDirectories(root);
+    if (direct.length) return direct;
+
+    const found = [];
+    const queue = [{ dir: root, depth: 0 }];
+    const ignored = new Set(['.git', 'node_modules', '.venv', 'venv', 'dist', 'build']);
+    while (queue.length) {
+        const { dir, depth } = queue.shift();
+        if (depth >= maxDepth) continue;
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (!entry.isDirectory() || entry.isSymbolicLink() || ignored.has(entry.name)) continue;
+            const child = path.join(dir, entry.name);
+            if (fs.existsSync(path.join(child, 'SKILL.md'))) {
+                found.push(child);
+            } else {
+                queue.push({ dir: child, depth: depth + 1 });
+            }
+        }
+    }
+    return found.sort();
+}
+
+function rejectSymlinks(root) {
+    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()) throw new Error(`Symlinked skill resource is not allowed: ${fullPath}`);
+            if (entry.isDirectory()) queue.push(fullPath);
+        }
+    }
+}
+
+function copyDirectory(source, destination) {
+    fs.mkdirSync(destination, { recursive: true });
+    for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+        const from = path.join(source, entry.name);
+        const to = path.join(destination, entry.name);
+        if (entry.isDirectory()) copyDirectory(from, to);
+        else if (entry.isFile()) fs.copyFileSync(from, to);
+    }
+}
+
+function readJson(file, fallback) {
+    try { return JSON.parse(fs.readFileSync(file, 'utf-8')); } catch { return fallback; }
+}
+
+function writeJson(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+}
+
+export class SkillInstaller {
+    constructor({ cwd = process.cwd(), homeDir = os.homedir() } = {}) {
+        this.cwd = path.resolve(cwd);
+        this.homeDir = homeDir;
+    }
+
+    paths(scope = 'global') {
+        const base = scope === 'project'
+            ? path.join(this.cwd, '.kepler')
+            : path.join(this.homeDir, '.kepler');
+        return {
+            skillsDir: path.join(base, 'skills'),
+            lockFile: path.join(base, 'skills.lock.json'),
+        };
+    }
+
+    install(source, { scope = 'global', force = false, onlyNames = null } = {}) {
+        if (!source) throw new Error('A local directory or Git repository is required');
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'kepler-skill-'));
+        let resolvedSource;
+        let commit = null;
+        try {
+            if (isGitSource(source)) {
+                resolvedSource = path.join(tempRoot, 'repository');
+                execFileSync(
+                    'git',
+                    ['clone', '--depth', '1', normalizeGitSource(source), resolvedSource],
+                    { stdio: 'pipe' },
+                );
+                commit = execFileSync('git', ['-C', resolvedSource, 'rev-parse', 'HEAD'], { encoding: 'utf-8' }).trim();
+            } else {
+                resolvedSource = fs.realpathSync(path.resolve(this.cwd, source));
+            }
+
+            const skillDirs = discoverInstallableSkills(resolvedSource);
+            if (!skillDirs.length) throw new Error(`No SKILL.md bundles found in ${source}`);
+
+            const { skillsDir, lockFile } = this.paths(scope);
+            const lock = readJson(lockFile, { version: 1, skills: {} });
+            const installed = [];
+            fs.mkdirSync(skillsDir, { recursive: true });
+
+            const plans = [];
+            for (const skillDir of skillDirs) {
+                rejectSymlinks(skillDir);
+                const content = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf-8');
+                const name = parseSkill(content, path.basename(skillDir)).name;
+                if (onlyNames && !onlyNames.includes(name)) continue;
+                if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) throw new Error(`Unsafe skill name: ${name}`);
+                const destination = path.join(skillsDir, name);
+                if (fs.existsSync(destination)) {
+                    if (!force) throw new Error(`Skill already installed: ${name} (use --force to replace)`);
+                }
+                plans.push({ skillDir, content, name, destination });
+            }
+            if (!plans.length) {
+                throw new Error(
+                    onlyNames
+                        ? `Requested skill not found in source: ${onlyNames.join(', ')}`
+                        : `No installable skills found in ${source}`,
+                );
+            }
+
+            for (const { skillDir, content, name, destination } of plans) {
+                if (fs.existsSync(destination)) fs.rmSync(destination, { recursive: true, force: true });
+                copyDirectory(skillDir, destination);
+
+                const digest = crypto.createHash('sha256')
+                    .update(content)
+                    .digest('hex');
+                lock.skills[name] = {
+                    source,
+                    scope,
+                    commit,
+                    destination,
+                    installed_at: new Date().toISOString(),
+                    manifest_hash: `sha256:${digest}`,
+                };
+                installed.push(name);
+            }
+            writeJson(lockFile, lock);
+            return { installed, scope, lock_file: lockFile };
+        } finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    }
+
+    remove(name, { scope = 'global' } = {}) {
+        const { skillsDir, lockFile } = this.paths(scope);
+        const destination = path.join(skillsDir, name);
+        if (!fs.existsSync(destination)) throw new Error(`Skill is not installed: ${name}`);
+        fs.rmSync(destination, { recursive: true, force: true });
+        const lock = readJson(lockFile, { version: 1, skills: {} });
+        delete lock.skills[name];
+        writeJson(lockFile, lock);
+        return { removed: name, scope };
+    }
+
+    update(name, { scope = 'global' } = {}) {
+        const { lockFile } = this.paths(scope);
+        const lock = readJson(lockFile, { version: 1, skills: {} });
+        const entry = lock.skills[name];
+        if (!entry?.source) throw new Error(`No locked source for skill: ${name}`);
+        return this.install(entry.source, { scope, force: true, onlyNames: [name] });
+    }
+
+    lock(scope = 'global') {
+        return readJson(this.paths(scope).lockFile, { version: 1, skills: {} });
+    }
+}

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/ansi.mjs

@@ -399,7 +399,7 @@ export function formatElapsed(startMs) {
 
 // ── Format Cost ──
 
-import { calculateCost, formatCostValue } from '../core/pricing.mjs';
+import { calculateCost, formatCostValue, costToCredits, formatCredits } from '../core/pricing.mjs';
 
 /**
  * Format cost from token counts.
@@ -407,15 +407,13 @@ import { calculateCost, formatCostValue } from '../core/pricing.mjs';
  * or a single usage object with optional per-model breakdown.
  */
 export function formatCost(inputOrUsage, outputTokens) {
-  // New API: pass a usage object directly
   if (typeof inputOrUsage === 'object' && inputOrUsage !== null) {
     const { total } = calculateCost(inputOrUsage);
-    return formatCostValue(total);
+    return formatCredits(costToCredits(total));
   }
-  // Legacy API: flat input/output token counts, default pricing
   const { total } = calculateCost({
     input_tokens: inputOrUsage || 0,
     output_tokens: outputTokens || 0,
   });
-  return formatCostValue(total);
+  return formatCredits(costToCredits(total));
 }

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)