@axplusb/kepler 2.0.7 → 2.3.0

package/src/permissions/command-classifier.mjs

@@ -144,6 +144,41 @@ function containsCommandSubstitution(command) {
     return false;
 }
 
+function isQuotedMessage(text) {
+    const value = String(text || '').trim();
+    return /^echo\s+(?:"[^"]*"|'[^']*'|[A-Za-z0-9_ .:-]+)$/.test(value);
+}
+
+function isNumericKillCommand(command) {
+    const trimmed = String(command || '').trim();
+    return /^kill\s+(?:-(?:\d+|[A-Z]+)\s+)?\d+(?:\s+\d+)*\s*(?:2>\s*\/dev\/null)?$/.test(trimmed);
+}
+
+function isPortLsofKillSubstitution(command) {
+    const trimmed = String(command || '').trim();
+    return /^kill\s+(?:-(?:\d+|[A-Z]+)\s+)?\$\(\s*lsof\s+-ti:?\d+\s*\)\s*(?:2>\s*\/dev\/null)?$/.test(trimmed);
+}
+
+function isPortLsofXargsKill(command) {
+    const trimmed = String(command || '').trim();
+    return /^lsof\s+-ti:?\d+\s*\|\s*xargs\s+kill(?:\s+-(?:\d+|[A-Z]+))?\s*(?:2>\s*\/dev\/null)?(?:\s*;\s*echo\s+(?:"[^"]*"|'[^']*'|[A-Za-z0-9_ .:-]+))?$/.test(trimmed);
+}
+
+function isApprovedProcessCleanupCommand(command) {
+    const trimmed = String(command || '').trim();
+    if (!trimmed) return false;
+    if (isPortLsofXargsKill(trimmed)) return true;
+    const segments = splitCommand(trimmed);
+    if (segments.length === 0) return false;
+    return segments.every(segment => {
+        const sub = segment.trim();
+        return isNumericKillCommand(sub) ||
+            isPortLsofKillSubstitution(sub) ||
+            isPortLsofXargsKill(sub) ||
+            isQuotedMessage(sub);
+    });
+}
+
 // ═══════════════════════════════════════════════════════════════════
 // Section 3: Read-Only Command Allowlist
 // ═══════════════════════════════════════════════════════════════════
@@ -207,6 +242,10 @@ const COMMAND_ALLOWLIST = {
     find: { flags: { '-name': 'string', '-iname': 'string', '-path': 'string', '-ipath': 'string', '-type': 'string', '-maxdepth': 'number', '-mindepth': 'number', '-newer': 'string', '-size': 'string', '-mtime': 'string', '-atime': 'string', '-ctime': 'string', '-perm': 'string', '-user': 'string', '-group': 'string', '-not': 'none', '!': 'none', '-or': 'none', '-o': 'none', '-and': 'none', '-a': 'none', '-print': 'none', '-print0': 'none', '-empty': 'none', '-readable': 'none', '-writable': 'none', '-executable': 'none', '-follow': 'none', '-L': 'none', '-P': 'none', '-H': 'none', '-xdev': 'none', '-mount': 'none', '-daystart': 'none', '-regextype': 'string', '-regex': 'string', '-iregex': 'string' },
         blocked: ['-exec', '-execdir', '-ok', '-okdir', '-delete', '-fprint', '-fprint0', '-fls', '-fprintf'] },
 
+    // ── sed (read-only subset — NO -i/--in-place) ──
+    sed: { flags: { '-n': 'none', '--quiet': 'none', '--silent': 'none', '-E': 'none', '-r': 'none', '--regexp-extended': 'none', '-e': 'string', '--expression': 'string', '-f': 'string', '--file': 'string', '-l': 'number', '--line-length': 'number', '-u': 'none', '--unbuffered': 'none' },
+        blocked: ['-i', '--in-place', '-z', '--null-data', '-s', '--separate'] },
+
     // ── ls ──
     ls: { flags: { '-l': 'none', '-a': 'none', '-A': 'none', '-h': 'none', '--human-readable': 'none', '-R': 'none', '--recursive': 'none', '-S': 'none', '-t': 'none', '-r': 'none', '--reverse': 'none', '-1': 'none', '-d': 'none', '--directory': 'none', '-F': 'none', '--classify': 'none', '-i': 'none', '--inode': 'none', '-s': 'none', '--size': 'none', '--color': 'string', '--sort': 'string', '--time': 'string', '--group-directories-first': 'none', '-p': 'none', '-G': 'none', '-n': 'none', '--numeric-uid-gid': 'none' } },
 
@@ -295,6 +334,7 @@ const BLOCKED_PATTERNS = [
     /curl.*\|\s*(ba)?sh/,                                     // pipe curl to shell
     /wget.*\|\s*(ba)?sh/,                                     // pipe wget to shell
     /eval\s*\$\(/,                                            // eval command substitution
+    /\bfind\s+\/(?:\s|$)/,                                    // find / scans the whole VM
     /find\s.*-exec/,                                           // find with -exec (code execution)
     /find\s.*-delete/,                                         // find with -delete
 ];
@@ -349,6 +389,7 @@ function validateFlags(tokens, startIdx, config) {
         if (blocked) {
             for (const b of blocked) {
                 if (token === b || token.startsWith(b + '=')) return false;
+                if (/^-[A-Za-z]$/.test(b) && token.startsWith(b) && token.length > b.length) return false;
             }
         }
 
@@ -449,6 +490,14 @@ export function classifyCommand(command) {
 
     const trimmed = command.trim();
 
+    if (isApprovedProcessCleanupCommand(trimmed)) {
+        return {
+            classification: 'contained',
+            reason: 'Process cleanup by numeric PID or lsof port lookup; requires approval',
+            highRisk: true,
+        };
+    }
+
     // ── Step 1: Check for always-blocked patterns ──
     for (const pattern of BLOCKED_PATTERNS) {
         if (pattern.test(trimmed)) {
@@ -461,6 +510,10 @@ export function classifyCommand(command) {
         return { classification: 'blocked', reason: 'Contains command substitution (backticks or $())' };
     }
 
+    if (containsUnsafeOutputRedirection(trimmed)) {
+        return { classification: 'contained', reason: 'Writes shell output via redirection' };
+    }
+
     // ── Step 3: Split compound commands and classify each ──
     const subcommands = splitCommand(trimmed);
 
@@ -500,6 +553,31 @@ export function classifyCommand(command) {
     };
 }
 
+function containsUnsafeOutputRedirection(command) {
+    let inSingle = false;
+    let inDouble = false;
+    let escaped = false;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (escaped) { escaped = false; continue; }
+        if (ch === '\\' && !inSingle) { escaped = true; continue; }
+        if (ch === "'" && !inDouble) { inSingle = !inSingle; continue; }
+        if (ch === '"' && !inSingle) { inDouble = !inDouble; continue; }
+        if (inSingle || inDouble || ch !== '>') continue;
+
+        const prev = command[i - 1] || '';
+        const next = command[i + 1] || '';
+        if (next === '&') continue;
+        let cursor = next === '>' ? i + 2 : i + 1;
+        while (/\s/.test(command[cursor] || '')) cursor++;
+        const target = command.slice(cursor).match(/^[^\s;&|]+/)?.[0] || '';
+        if (target === '/dev/null') continue;
+        if (prev === '2' && target === '/dev/null') continue;
+        return true;
+    }
+    return false;
+}
+
 /**
  * Classify a single (non-compound) command.
  */

package/src/terminal/init.mjs

@@ -0,0 +1,145 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const FILES = {
+  'README.md': `# .kepler/ - project agent context
+
+Kepler reads and writes here to keep state between sessions.
+
+## Files Kepler writes
+- \`plan.md\` - current agent plan
+- \`goal.md\` - durable session goal
+- \`tasks/\` - task list
+- \`reports/*.md\` - end-of-turn mission reports
+- \`sessions/*.jsonl\` - turn transcripts
+- \`commands.log\` - command executions
+- \`approvals.log\` - HITL decisions
+- \`trust.json\` - approved patterns
+
+## Files you can write
+- \`config.json\` - project policy
+- \`project.md\` - durable project context
+- \`style.md\` - codebase conventions
+- \`hitl.md\` - approval guidance
+- \`skills/<name>/SKILL.md\` - reusable domain skills
+
+Format v1. Markdown files are intentionally hand-editable.
+`,
+  'config.json': JSON.stringify({
+    version: 1,
+    context: {
+      loadEveryTurn: ['KEPLER.md', 'project.md', 'style.md', 'goal.md', 'plan.md', 'tasks/*.md'],
+      showReloadNotice: true,
+    },
+    planning: { owner: 'auto', onUserEditedPlan: 'prefer_user_plan' },
+    tasks: { storage: 'project_markdown', syncTodoWrite: true, resumePrompt: true },
+    hitl: {
+      defaultScope: 'once',
+      allowSessionTrust: true,
+      allowProjectTrust: false,
+      reaskAfterMinutes: 30,
+    },
+    commands: {
+      enabled: ['map', 'probe', 'footprint', 'heal', 'align', 'distill', 'brief', 'rewind'],
+      dryRunDefault: false,
+    },
+  }, null, 2) + '\n',
+  'settings.json': JSON.stringify({
+    env: {},
+    permissions: {
+      shellAllowlist: ['git', 'npm', 'pnpm'],
+      editDenylist: ['**/*.env', 'secrets/**'],
+    },
+    hooks: {
+      UserPromptSubmit: [],
+      PreToolUse: [],
+      PostToolUse: [],
+      Stop: [],
+    },
+  }, null, 2) + '\n',
+  'KEPLER.md': `# Project
+
+## Quick Facts
+- Stack:
+- Test command:
+- Lint command:
+- Build command:
+
+## Key Directories
+
+## Code Style
+
+## Critical Rules
+`,
+  'project.md': '# Project Context\n\nAdd durable project context here.\n',
+  'style.md': '# Style\n\nAdd code and communication conventions here.\n',
+  'hitl.md': '# HITL Guidance\n\nAdd project-specific approval guidance here.\n',
+  'trust.json': JSON.stringify({ version: 1, rules: [] }, null, 2) + '\n',
+  'tasks/README.md': `# Kepler Tasks
+
+Checklist files are read every turn.
+
+- \`backlog.md\` - pending tasks
+- \`active.md\` - current task
+- \`done.md\` - completed tasks
+- \`blocked.md\` - waiting on input
+`,
+  'tasks/backlog.md': '# Backlog\n\n',
+  'tasks/active.md': '# Active\n\n',
+  'tasks/done.md': '# Done\n\n',
+  'tasks/blocked.md': '# Blocked\n\n',
+  'skills/starter/SKILL.md': `---
+name: starter
+description: Project-specific conventions and setup notes. Use when onboarding to this repo.
+---
+
+# Starter Skill
+
+Add reusable project knowledge here.
+`,
+  'commands/onboard.md': `---
+name: onboard
+description: Explore the project and record onboarding notes.
+---
+
+# Onboard
+
+Context:
+$ARGUMENTS
+
+Explore the codebase, ask clarifying questions, and record useful notes in .kepler/tasks/active.md.
+`,
+};
+
+export function scaffoldKeplerProject({ cwd = process.cwd(), force = false } = {}) {
+  const root = path.join(cwd, '.kepler');
+  const written = [];
+  const skipped = [];
+  for (const [rel, content] of Object.entries(FILES)) {
+    const filePath = path.join(root, rel);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    if (fs.existsSync(filePath) && !force) {
+      skipped.push(filePath);
+      continue;
+    }
+    fs.writeFileSync(filePath, content);
+    written.push(filePath);
+  }
+
+  const gitignore = path.join(root, '.gitignore');
+  if (!fs.existsSync(gitignore) || force) {
+    fs.writeFileSync(gitignore, 'settings.local.json\nsessions/\nreports/\n*.log\n');
+    written.push(gitignore);
+  }
+
+  return { root, written, skipped };
+}
+
+export async function runInitCommand(args = [], { cwd = process.cwd() } = {}) {
+  const force = args.includes('--force');
+  const result = scaffoldKeplerProject({ cwd, force });
+  process.stderr.write(`\x1b[32m✓\x1b[0m Initialized .kepler at ${result.root}\n`);
+  process.stderr.write(`  wrote ${result.written.length} files`);
+  if (result.skipped.length) process.stderr.write(`, skipped ${result.skipped.length} existing files`);
+  process.stderr.write('\n');
+}

package/src/terminal/main.mjs

@@ -47,6 +47,12 @@ async function main() {
     return;
   }
 
+  if (subcommand === 'init') {
+    const { runInitCommand } = await import('./init.mjs');
+    await runInitCommand(subcommandArgs);
+    return;
+  }
+
   if (subcommand === 'skills' || subcommand === 'skill') {
     const { runSkillsCommand } = await import('./skills.mjs');
     try {
@@ -103,6 +109,7 @@ async function main() {
     kepler dashboard          Open Kepler Pulse analytics dashboard
     kepler login              Sign in via browser
     kepler logout             Sign out and clear credentials
+    kepler init               Scaffold .kepler config, memory, hooks, tasks
     kepler version            Show version
 
   \x1b[1mAnalytics:\x1b[0m
@@ -155,6 +162,8 @@ async function main() {
       model: args.model,
       timeout: args.timeout || (args.maxTurns ? args.maxTurns * 60 : 600),
       verbose: args.verbose,
+      cacheReport: args.cacheReport,
+      local: args.local,
     });
     return;
   }