@axplusb/kepler 0.0.1 → 1.0.1

package/src/permissions/path-check.mjs

@@ -0,0 +1,102 @@
+/**
+ * File Path Sanitization — validate file paths before allowing access.
+ *
+ * Prevents directory traversal, blocks sensitive files, and normalizes paths.
+ */
+
+import path from 'path';
+
+/** File patterns that should never be read or written. */
+const SENSITIVE_PATTERNS = [
+    /\.env$/,
+    /\.env\..+$/,
+    /credentials\.json$/,
+    /credentials\.yaml$/,
+    /\.pem$/,
+    /\.key$/,
+    /id_rsa$/,
+    /id_ed25519$/,
+    /\.ssh\/config$/,
+    /\.netrc$/,
+    /\.pgpass$/,
+    /\.aws\/credentials$/,
+    /\.docker\/config\.json$/,
+    /secrets\.yaml$/,
+    /secrets\.json$/,
+];
+
+/** Directories that should never be written to. */
+const PROTECTED_DIRS = [
+    '/etc',
+    '/usr',
+    '/sbin',
+    '/boot',
+    '/sys',
+    '/proc',
+];
+
+/**
+ * Validate a file path for safety.
+ * @param {string} filePath - the path to validate
+ * @param {object} [options]
+ * @param {string} [options.cwd] - current working directory (default: process.cwd())
+ * @param {boolean} [options.write] - whether this is a write operation
+ * @returns {{ safe: boolean, resolved: string, reason?: string, warning?: string }}
+ */
+export function validatePath(filePath, options = {}) {
+    if (typeof filePath !== 'string' || filePath.trim().length === 0) {
+        return { safe: false, resolved: '', reason: 'Empty or invalid path' };
+    }
+
+    const resolved = path.resolve(filePath);
+    const cwd = options.cwd || process.cwd();
+
+    // Check for null bytes (path injection)
+    if (filePath.includes('\0')) {
+        return { safe: false, resolved, reason: 'Null byte in path' };
+    }
+
+    // Check sensitive file patterns
+    for (const pattern of SENSITIVE_PATTERNS) {
+        if (pattern.test(resolved) || pattern.test(path.basename(resolved))) {
+            return { safe: false, resolved, reason: 'Sensitive file' };
+        }
+    }
+
+    // Check protected directories for writes
+    if (options.write) {
+        for (const dir of PROTECTED_DIRS) {
+            if (resolved.startsWith(dir + '/') || resolved === dir) {
+                return { safe: false, resolved, reason: `Protected directory: ${dir}` };
+            }
+        }
+    }
+
+    // Check for traversal outside cwd
+    let warning;
+    if (!resolved.startsWith(cwd) && !resolved.startsWith('/tmp')) {
+        warning = 'Path is outside the current working directory';
+    }
+
+    return { safe: true, resolved, warning };
+}
+
+/**
+ * Check if a filename matches sensitive patterns.
+ * @param {string} filename
+ * @returns {boolean}
+ */
+export function isSensitiveFile(filename) {
+    for (const pattern of SENSITIVE_PATTERNS) {
+        if (pattern.test(filename)) return true;
+    }
+    return false;
+}
+
+/**
+ * Get list of sensitive patterns (for display/testing).
+ * @returns {RegExp[]}
+ */
+export function getSensitivePatterns() {
+    return [...SENSITIVE_PATTERNS];
+}

package/src/permissions/prompt.mjs

@@ -0,0 +1,73 @@
+/**
+ * Permission Prompts — interactive yes/no for dangerous operations.
+ *
+ * Used in "default" permission mode to ask the user before executing
+ * potentially dangerous tool calls (Bash, Edit, Write, Agent).
+ */
+
+/**
+ * Prompt the user for permission to execute a tool.
+ * @param {string} toolName - tool being invoked
+ * @param {object} input - tool input
+ * @param {object} rl - readline interface with .question()
+ * @returns {Promise<boolean>} true if allowed
+ */
+export async function promptPermission(toolName, input, rl) {
+    if (!rl || typeof rl.question !== 'function') {
+        // No readline available — deny by default
+        return false;
+    }
+
+    const summary = formatToolSummary(toolName, input);
+    return new Promise(resolve => {
+        rl.question(`Allow ${summary}? [y/N] `, answer => {
+            resolve(answer.trim().toLowerCase() === 'y');
+        });
+    });
+}
+
+/**
+ * Format a human-readable summary of a tool call.
+ * @param {string} toolName
+ * @param {object} input
+ * @returns {string}
+ */
+export function formatToolSummary(toolName, input) {
+    switch (toolName) {
+        case 'Bash':
+            return `Bash: ${truncate(input.command || '', 60)}`;
+        case 'Edit':
+            return `Edit: ${input.file_path || 'unknown file'}`;
+        case 'Write':
+            return `Write: ${input.file_path || 'unknown file'} (${(input.content || '').length} chars)`;
+        case 'MultiEdit':
+            return `MultiEdit: ${input.file_path || 'unknown file'} (${(input.edits || []).length} edits)`;
+        case 'Agent':
+            return `Agent: ${truncate(input.prompt || '', 40)}`;
+        case 'WebFetch':
+            return `WebFetch: ${truncate(input.url || '', 50)}`;
+        case 'RemoteTrigger':
+            return `RemoteTrigger: ${input.url || 'unknown'}`;
+        default:
+            return `${toolName}`;
+    }
+}
+
+/**
+ * Check if a tool requires interactive permission in default mode.
+ * Read-only tools are always allowed.
+ * @param {string} toolName
+ * @returns {boolean}
+ */
+export function requiresPermission(toolName) {
+    const SAFE_TOOLS = new Set([
+        'Read', 'Glob', 'Grep', 'LS', 'ToolSearch',
+        'AskUser', 'CronList', 'TodoWrite',
+    ]);
+    return !SAFE_TOOLS.has(toolName);
+}
+
+function truncate(str, maxLen) {
+    if (str.length <= maxLen) return str;
+    return str.substring(0, maxLen - 3) + '...';
+}

package/src/permissions/sandbox.mjs

@@ -0,0 +1,112 @@
+/**
+ * Sandbox — wrap commands in platform-specific sandboxes.
+ *
+ * Linux: bubblewrap (bwrap)
+ * macOS: sandbox-exec (seatbelt)
+ * Windows/other: passthrough (no sandbox)
+ */
+
+export class Sandbox {
+    /**
+     * @param {string} [platform] - override process.platform
+     */
+    constructor(platform) {
+        this.platform = platform || process.platform;
+    }
+
+    /**
+     * Wrap a command to run inside a sandbox.
+     * @param {string} command - the command to sandbox
+     * @param {object} [options]
+     * @param {string[]} [options.allowWrite] - directories to allow writes
+     * @param {string[]} [options.allowNet] - allow network access (macOS)
+     * @param {boolean} [options.allowDevices] - allow device access
+     * @returns {string} sandboxed command
+     */
+    wrapCommand(command, options = {}) {
+        if (this.platform === 'linux') return this.bubblewrap(command, options);
+        if (this.platform === 'darwin') return this.seatbelt(command, options);
+        return command; // fallback: no sandbox
+    }
+
+    /**
+     * Linux sandbox using bubblewrap.
+     * Creates a minimal read-only root with /dev, /proc, /tmp.
+     */
+    bubblewrap(command, opts = {}) {
+        const args = [
+            '--ro-bind', '/', '/',
+            '--dev', '/dev',
+            '--proc', '/proc',
+            '--tmpfs', '/tmp',
+        ];
+
+        // Allow specific writable directories
+        if (opts.allowWrite) {
+            for (const dir of opts.allowWrite) {
+                if (typeof dir === 'string' && dir.length > 0) {
+                    args.push('--bind', dir, dir);
+                }
+            }
+        }
+
+        // Allow /dev access if requested
+        if (opts.allowDevices) {
+            args.push('--dev-bind', '/dev', '/dev');
+        }
+
+        return `bwrap ${args.join(' ')} -- ${command}`;
+    }
+
+    /**
+     * macOS sandbox using sandbox-exec with a seatbelt profile.
+     * Returns a sandbox-exec wrapped command with a generated profile.
+     */
+    seatbelt(command, opts = {}) {
+        const rules = [
+            '(version 1)',
+            '(deny default)',
+            '(allow process-exec)',
+            '(allow process-fork)',
+            '(allow file-read*)',
+            '(allow sysctl-read)',
+            '(allow mach-lookup)',
+        ];
+
+        // Allow writes to specific directories
+        if (opts.allowWrite) {
+            for (const dir of opts.allowWrite) {
+                if (typeof dir === 'string' && dir.length > 0) {
+                    rules.push(`(allow file-write* (subpath "${dir}"))`);
+                }
+            }
+        }
+
+        // Allow /tmp writes by default
+        rules.push('(allow file-write* (subpath "/tmp"))');
+
+        // Allow network if requested
+        if (opts.allowNet) {
+            rules.push('(allow network*)');
+        }
+
+        const profile = rules.join('\n');
+        // Escape single quotes in profile for shell
+        const escaped = profile.replace(/'/g, "'\\''");
+        return `sandbox-exec -p '${escaped}' ${command}`;
+    }
+
+    /**
+     * Check if sandbox tooling is available on this platform.
+     * @returns {{ available: boolean, tool: string }}
+     */
+    check() {
+        if (this.platform === 'linux') {
+            return { available: true, tool: 'bwrap' };
+        }
+        if (this.platform === 'darwin') {
+            return { available: true, tool: 'sandbox-exec' };
+        }
+        return { available: false, tool: 'none' };
+    }
+}

package/src/plugins/loader.mjs

@@ -0,0 +1,138 @@
+/**
+ * Plugin Loader — load plugins from directory, git, or npm.
+ *
+ * Plugins can provide: tools, agents, skills, hooks.
+ * Plugin format: a directory with a plugin.json manifest.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { execSync } from 'child_process';
+
+export class PluginLoader {
+    /**
+     * @param {string} [pluginDir] - directory to scan for plugins
+     */
+    constructor(pluginDir) {
+        this.pluginDir = pluginDir ||
+            path.join(os.homedir(), '.claude', 'plugins');
+        this.plugins = new Map();
+    }
+
+    /**
+     * Load plugins from the plugin directory.
+     * @returns {Array<object>} loaded plugin manifests
+     */
+    async loadFromDirectory(dir) {
+        const targetDir = dir || this.pluginDir;
+        const loaded = [];
+
+        try {
+            if (!fs.existsSync(targetDir)) return loaded;
+
+            const entries = fs.readdirSync(targetDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory()) continue;
+
+                const manifestPath = path.join(targetDir, entry.name, 'plugin.json');
+                if (!fs.existsSync(manifestPath)) continue;
+
+                try {
+                    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                    manifest._dir = path.join(targetDir, entry.name);
+                    manifest._name = entry.name;
+                    this.plugins.set(manifest.name || entry.name, manifest);
+                    loaded.push(manifest);
+                } catch {
+                    // Skip malformed plugins
+                }
+            }
+        } catch {
+            // Directory not readable
+        }
+
+        return loaded;
+    }
+
+    /**
+     * Clone a plugin from a git repo and load it.
+     * @param {string} repoUrl - git repository URL
+     * @param {string} [name] - plugin name (default: repo name)
+     * @returns {object|null} loaded manifest
+     */
+    async loadFromGit(repoUrl, name) {
+        const pluginName = name || repoUrl.split('/').pop()?.replace('.git', '') || 'plugin';
+        const targetDir = path.join(this.pluginDir, pluginName);
+
+        try {
+            fs.mkdirSync(this.pluginDir, { recursive: true });
+
+            if (fs.existsSync(targetDir)) {
+                // Update existing
+                execSync('git pull', { cwd: targetDir, stdio: 'pipe' });
+            } else {
+                // Clone new
+                execSync(`git clone --depth 1 ${repoUrl} ${targetDir}`, { stdio: 'pipe' });
+            }
+
+            const manifestPath = path.join(targetDir, 'plugin.json');
+            if (fs.existsSync(manifestPath)) {
+                const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                manifest._dir = targetDir;
+                manifest._name = pluginName;
+                this.plugins.set(manifest.name || pluginName, manifest);
+                return manifest;
+            }
+        } catch {
+            // Git operation failed
+        }
+
+        return null;
+    }
+
+    /**
+     * Get all installed plugins.
+     * @returns {Array<object>}
+     */
+    getInstalledPlugins() {
+        return [...this.plugins.values()];
+    }
+
+    /**
+     * Get a plugin by name.
+     * @param {string} name
+     * @returns {object|undefined}
+     */
+    getPlugin(name) {
+        return this.plugins.get(name);
+    }
+
+    /**
+     * Remove a plugin by name.
+     * @param {string} name
+     * @returns {boolean}
+     */
+    removePlugin(name) {
+        const plugin = this.plugins.get(name);
+        if (!plugin) return false;
+
+        try {
+            if (plugin._dir && fs.existsSync(plugin._dir)) {
+                fs.rmSync(plugin._dir, { recursive: true, force: true });
+            }
+        } catch {
+            // Best effort
+        }
+
+        return this.plugins.delete(name);
+    }
+
+    /**
+     * Get plugin count.
+     * @returns {number}
+     */
+    count() {
+        return this.plugins.size;
+    }
+}

package/src/skills/loader.mjs

@@ -0,0 +1,147 @@
+/**
+ * Skills Loader — loads skills from .claude/skills/{name}/SKILL.md
+ *
+ * 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
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+export class SkillsLoader {
+    constructor() {
+        this.skills = new Map();
+        this.searchPaths = [];
+    }
+
+    /**
+     * Load skills from standard directories.
+     * @param {string} [cwd] - project working directory
+     */
+    load(cwd = process.cwd()) {
+        this.searchPaths = [
+            path.join(cwd, '.claude', 'skills'),
+            path.join(process.env.HOME || '', '.claude', 'skills'),
+        ];
+
+        for (const dir of this.searchPaths) {
+            this._loadFromDir(dir);
+        }
+
+        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
+                }
+            }
+        } catch {
+            // Directory does not exist
+        }
+    }
+
+    /**
+     * Get a skill by name.
+     * @param {string} name
+     * @returns {object|null}
+     */
+    get(name) {
+        // Try exact match, then prefix match
+        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;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * List all loaded skills.
+     * @returns {Array<object>}
+     */
+    list() {
+        return [...this.skills.values()];
+    }
+
+    /**
+     * 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}`;
+        }
+
+        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();
+        }
+    }
+
+    // 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);
+    }
+
+    return skill;
+}

package/src/skills/runner.mjs

@@ -0,0 +1,55 @@
+/**
+ * Skills Runner — executes a skill by injecting its prompt.
+ *
+ * When a skill is invoked, its prompt is injected as a system message
+ * into the conversation context, guiding the agent's behavior.
+ */
+
+export class SkillRunner {
+    /**
+     * @param {object} loader - SkillsLoader instance
+     * @param {object} agentLoop - agent loop instance
+     */
+    constructor(loader, agentLoop) {
+        this.loader = loader;
+        this.loop = agentLoop;
+    }
+
+    /**
+     * Execute a skill.
+     * @param {string} name - skill name
+     * @param {string} [args] - optional arguments
+     * @returns {AsyncGenerator} event stream from agent loop
+     */
+    async *execute(name, args) {
+        const skill = this.loader.get(name);
+        if (!skill) {
+            yield { type: 'error', message: `Unknown skill: ${name}` };
+            return;
+        }
+
+        // Build the skill prompt
+        let prompt = skill.prompt;
+        if (args) {
+            prompt = prompt.replace(/\$ARGUMENTS/g, args);
+        }
+
+        // Inject skill context as a user message
+        const message = `[Invoking skill: ${skill.name}]\n\n${prompt}${args ? `\n\nArguments: ${args}` : ''}`;
+
+        // Run through agent loop
+        yield* this.loop.run(message);
+    }
+
+    /**
+     * List available skills for display.
+     * @returns {Array<{name: string, description: string}>}
+     */
+    listAvailable() {
+        return this.loader.list().map(s => ({
+            name: s.name,
+            description: s.description,
+            aliases: s.aliases || [],
+        }));
+    }
+}