@occasiolabs/occasio 0.8.1

package/src/policy/shell-path.js

@@ -0,0 +1,135 @@
+'use strict';
+
+/**
+ * Extract file-read operand paths from a shell command so the policy engine
+ * can apply deny_paths / allow_paths to shell-mediated reads (cat, head, tail,
+ * type, bat, Get-Content) the same way it does for the typed `read_file` tool.
+ *
+ * Closes the bypass where `Bash { command: "cat <denied-path>" }` and the
+ * PowerShell equivalent skipped path policy because the canonical tool name
+ * is `shell_bash` / `shell_powershell` and not in PATH_BEARING_TOOLS.
+ *
+ * Scope is intentionally narrow: only the shapes the native handler in
+ * src/interceptor.js actually executes locally. Unrecognised commands return
+ * an empty array — the existing classifier still gates them.
+ */
+
+const path = require('path');
+
+// Read-content primitives that the native handler reads from disk.
+// Each entry: command head (lowercased) → parser(parts) → relative file path or null.
+//
+// Keep these parsers byte-compatible with interceptor.nativeHandle() so we
+// never block a path the native handler would not actually read.
+function parseSimpleRead(parts) {
+  // cat|bat|type|head|tail [-flags] <file>
+  let i = 1;
+  while (i < parts.length && parts[i].startsWith('-')) {
+    if ((parts[i] === '-n' || parts[i] === '--lines') && /^\d+$/.test(parts[i + 1] || '')) i++;
+    i++;
+  }
+  const file = stripQuotes(parts.slice(i).join(' '));
+  return file || null;
+}
+
+function parseGetContent(parts) {
+  // Get-Content [-Path|-LiteralPath] <file>
+  let idx = 1;
+  if (/^-(?:path|literalpath)$/i.test(parts[1] || '')) idx = 2;
+  const file = stripQuotes(parts.slice(idx).join(' '));
+  return file || null;
+}
+
+const READ_HEADS = new Map([
+  ['cat',         parseSimpleRead],
+  ['bat',         parseSimpleRead],
+  ['type',        parseSimpleRead],
+  ['head',        parseSimpleRead],
+  ['tail',        parseSimpleRead],
+  ['get-content', parseGetContent],
+]);
+
+function stripQuotes(s) {
+  if (!s) return s;
+  return s.trim().replace(/^(['"])(.*)\1$/, '$2');
+}
+
+/** Extract the directory operand from a `cd <dir>` / `Set-Location <dir>` segment. */
+function extractCwdFromCdSegment(seg) {
+  const m = /^(?:cd|Set-Location)\s+(.+)$/i.exec(seg.trim());
+  if (!m) return null;
+  return stripQuotes(m[1]);
+}
+
+/**
+ * Try to extract a relative-or-absolute file path from a single command
+ * segment that reads file content. Returns null if the segment is not a
+ * recognised read shape.
+ */
+function readPathFromSegment(seg) {
+  const trimmed = seg.trim().replace(/\s+2>&1\s*$/, '');
+  if (!trimmed) return null;
+  const parts = trimmed.split(/\s+/);
+  const head  = parts[0];
+  if (!head) return null;
+  const parser = READ_HEADS.get(head.toLowerCase());
+  if (!parser) return null;
+  return parser(parts);
+}
+
+/**
+ * Walk a shell command and return every file path the native handler would
+ * actually read, resolved to absolute form. Handles three shapes:
+ *
+ *   1. Bare read:                   `cat <file>`
+ *   2. cd-prefixed Bash chain:      `cd <dir> && cat <file>`
+ *   3. Set-Location PowerShell:     `Set-Location <dir>; Get-Content <file>`
+ *
+ * The cwd tracked across cd/Set-Location segments only affects path
+ * resolution for subsequent segments — process.cwd() is never mutated. The
+ * caller (policy.engine) resolves each returned path against deny_paths /
+ * allow_paths exactly like it does for a typed `read_file` tool.
+ *
+ * Returns an array of absolute path strings (deduplicated, order-preserving).
+ */
+function extractShellReadPaths(command, baseCwd) {
+  if (!command || typeof command !== 'string') return [];
+  const cwdStart = baseCwd || process.cwd();
+
+  // Split into segments. Bash `&&`, PowerShell `;`. A command with neither
+  // separator is a single segment.
+  const segments = command.includes(' && ')
+    ? command.split(' && ')
+    : command.includes(';')
+      ? command.split(';').map(s => s.trim()).filter(Boolean)
+      : [command];
+
+  const results = [];
+  const seen    = new Set();
+  let cwd = cwdStart;
+
+  for (const seg of segments) {
+    const s = seg.trim();
+    if (!s) continue;
+
+    const cdTarget = extractCwdFromCdSegment(s);
+    if (cdTarget) {
+      // Resolve cd target against the previously tracked cwd so chained
+      // relative cd's work (mirrors interceptor.runCompound).
+      cwd = path.resolve(cwd, cdTarget);
+      continue;
+    }
+
+    const filePart = readPathFromSegment(s);
+    if (!filePart) continue;
+
+    const abs = path.resolve(cwd, filePart);
+    if (!seen.has(abs)) {
+      seen.add(abs);
+      results.push(abs);
+    }
+  }
+  return results;
+}
+
+module.exports = { extractShellReadPaths };

package/src/policy/show.js

@@ -0,0 +1,196 @@
+'use strict';
+
+/**
+ * occasio policy show — display the active policy in human-readable form.
+ *
+ * Shows global flags and per-tool routing/transform decisions, annotating
+ * each value as either the default or a user override from policy.yml.
+ *
+ * Usage:
+ *   occasio policy [show]         Full view of the active policy
+ *   occasio policy show --diff    Only values that differ from defaults
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// Transforms currently implemented in the dispatcher.
+const KNOWN_TRANSFORMS = new Set(['redact-secrets', 'distill-output']);
+
+// Global flag keys, in display order.
+const GLOBAL_FLAG_KEYS = [
+  'block_secrets_in_tool_results',
+  'redact_secrets_in_tool_results',
+  'distill_tool_results',
+  'block_requests_over_budget',
+];
+
+const col = {
+  r: s => `\x1b[31m${s}\x1b[0m`,
+  g: s => `\x1b[32m${s}\x1b[0m`,
+  y: s => `\x1b[33m${s}\x1b[0m`,
+  c: s => `\x1b[36m${s}\x1b[0m`,
+  d: s => `\x1b[2m${s}\x1b[0m`,
+  b: s => `\x1b[1m${s}\x1b[0m`,
+};
+
+function pad(s, n) { return String(s).padEnd(n); }
+
+/**
+ * Format one tool entry for display.
+ * Returns { line: string, warn: string|null }
+ */
+function formatToolEntry(entry) {
+  if (!entry) {
+    return { line: col.y('PASS') + col.d('  (absent from tools: block → cloud only)'), warn: null };
+  }
+  const a = entry.action;
+  if (a === 'LOCAL') {
+    return { line: col.g('LOCAL'), warn: null };
+  }
+  if (a === 'TRANSFORM') {
+    const tf = entry.transform || '(none)';
+    const known = KNOWN_TRANSFORMS.has(tf);
+    const tfStr = known ? col.c(tf) : col.r(tf);
+    const warn  = known ? null : `unknown transform '${tf}' — not implemented in dispatcher`;
+    return { line: `${col.c('TRANSFORM')} → ${tfStr}`, warn };
+  }
+  if (a === 'PASS') {
+    return { line: col.d('PASS') + col.d('  (cloud only)'), warn: null };
+  }
+  return { line: col.r(`${a}  (unrecognized action)`), warn: `unrecognized action '${a}'` };
+}
+
+/**
+ * Determine if an active tool entry differs from the default entry.
+ */
+function isToolOverride(actEntry, defEntry) {
+  if (!actEntry && !defEntry) return false;
+  if (!actEntry || !defEntry) return true;   // one is absent — different
+  return actEntry.action !== defEntry.action || actEntry.transform !== defEntry.transform;
+}
+
+/**
+ * Main display function.
+ *
+ * @param {string[]} args   Remaining CLI args after 'policy [show]'
+ * @param {object}   [opts] { loader } — injectable for tests; defaults to real loader
+ */
+function runPolicyCli(args, opts = {}) {
+  const loader   = opts.loader || require('./loader');
+  const diffMode = (args || []).includes('--diff');
+
+  // ── Source detection ──────────────────────────────────────────────────────
+  const filePath = loader.DEFAULT_PATH;
+  let fileExists = false;
+  let userParsed = {};
+  try {
+    const text = fs.readFileSync(filePath, 'utf8');
+    fileExists = true;
+    userParsed = loader.parse(text);
+  } catch {}
+
+  const active   = loader.load();
+  const defaults = loader.DEFAULT_POLICY;
+
+  // ── Header ────────────────────────────────────────────────────────────────
+  console.log(col.b('\n⚡ Occasio — Active Policy\n'));
+
+  const fileStatus = fileExists
+    ? `${filePath}  ${col.g('(loaded)')}`
+    : `${col.d(filePath)}  ${col.d('(not found — defaults apply)')}`;
+  console.log(`  File:    ${fileStatus}`);
+
+  if (diffMode && !fileExists) {
+    console.log(col.d('\n  No overrides — no policy.yml found; all defaults apply.\n'));
+    return;
+  }
+
+  // ── Global flags ──────────────────────────────────────────────────────────
+  const globalOverrides = GLOBAL_FLAG_KEYS.filter(k => active[k] !== defaults[k]);
+
+  if (!diffMode || globalOverrides.length > 0) {
+    console.log(col.b('\n  Global flags:'));
+    const keyWidth = Math.max(...GLOBAL_FLAG_KEYS.map(k => k.length)) + 2;
+    for (const k of GLOBAL_FLAG_KEYS) {
+      const isOverride = active[k] !== defaults[k];
+      if (diffMode && !isOverride) continue;
+      const val      = active[k];
+      const valStr   = String(val);
+      const valCol   = val === true  ? col.g(valStr)
+                     : val === false ? col.d(valStr)
+                     : col.y(valStr);
+      const ann = isOverride ? col.c('  ← override') : col.d('  (default)');
+      console.log(`    ${pad(k, keyWidth)}  ${valCol}${ann}`);
+    }
+  }
+
+  // ── Tool routing ──────────────────────────────────────────────────────────
+  const defaultTools = defaults.tools || {};
+  const activeTools  = active.tools   || {};
+
+  // Unified tool name list: all default tools + any user-defined extras
+  const allNames = [...new Set([
+    ...Object.keys(defaultTools),
+    ...Object.keys(activeTools),
+  ])];
+
+  // Detect which tools have a user-declared tools: block at all
+  const userHasToolsBlock = fileExists &&
+    userParsed.tools && typeof userParsed.tools === 'object' &&
+    Object.keys(userParsed.tools).length > 0;
+
+  // Tools removed by a user tools: block (default tools now absent from activeTools)
+  const removedByUserBlock = userHasToolsBlock
+    ? Object.keys(defaultTools).filter(k => !activeTools[k])
+    : [];
+
+  // Filter to display
+  const namesToShow = allNames.filter(name => {
+    if (!diffMode) return true;
+    return isToolOverride(activeTools[name], defaultTools[name]);
+  });
+
+  if (!diffMode || namesToShow.length > 0 || removedByUserBlock.length > 0) {
+    const userExtra = allNames.filter(n => !defaultTools[n] && activeTools[n]);
+    const countNote = userExtra.length
+      ? col.d(` (${Object.keys(defaultTools).length} defaults + ${userExtra.length} user-defined)`)
+      : col.d(` (${allNames.length} tools)`);
+    console.log(col.b('\n  Tool routing:') + countNote);
+
+    // Warn if user's tools: block removed defaults
+    if (removedByUserBlock.length > 0) {
+      console.log(col.y('\n  ⚠  tools: block replaces all defaults.') +
+        col.d(' Tools not listed will PASS to cloud:'));
+      console.log(col.y(`       ${removedByUserBlock.join(', ')}`));
+    }
+
+    const nameWidth = Math.max(...allNames.map(n => n.length), 16) + 2;
+
+    for (const name of allNames) {
+      const actEntry = activeTools[name];
+      const defEntry = defaultTools[name];
+      const isOverride = isToolOverride(actEntry, defEntry);
+
+      if (diffMode && !isOverride) continue;
+
+      // For user tools: block — absent defaults show as override (removed)
+      const entryToShow = actEntry || null;
+      const { line, warn } = formatToolEntry(entryToShow);
+      const ann = isOverride ? col.c('  ← override') : col.d('  (default)');
+      const extra = !defEntry ? col.d('  (user-defined)') : '';
+      const warnStr = warn ? col.y(`  ⚠ ${warn}`) : '';
+
+      console.log(`    ${pad(name, nameWidth)}  ${line}${ann}${extra}${warnStr}`);
+    }
+  }
+
+  if (diffMode && !globalOverrides.length && !namesToShow.length && !removedByUserBlock.length) {
+    console.log(col.d('\n  No overrides — active policy matches defaults.\n'));
+    return;
+  }
+
+  console.log('');
+}
+
+module.exports = { runPolicyCli, KNOWN_TRANSFORMS, formatToolEntry, isToolOverride };

package/src/policy/validate.js

@@ -0,0 +1,310 @@
+'use strict';
+
+/**
+ * occasio policy validate — parse ~/.occasio/policy.yml and report
+ * every issue that would cause silent failures at runtime.
+ *
+ * Two severity levels:
+ *   error   — field will be silently dropped or mis-applied at runtime
+ *   warning — field is valid but suspicious (unknown name, unused entry, etc.)
+ *
+ * Exit code via the caller (index.js):
+ *   0  — no errors (clean or warnings-only)
+ *   1  — at least one error
+ *
+ * Usage:
+ *   occasio policy validate
+ *   occasio policy validate --file /path/to/policy.yml
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// ── Validation constants ───────────────────────────────────────────────────────
+
+const KNOWN_TOP_LEVEL = new Set([
+  'version',
+  'block_secrets_in_tool_results',
+  'redact_secrets_in_tool_results',
+  'distill_tool_results',
+  'block_requests_over_budget',
+  'tools',
+  'deny_paths',
+  'allow_paths',
+  'deny_patterns',
+]);
+
+const BOOLEAN_FLAGS = [
+  'block_secrets_in_tool_results',
+  'redact_secrets_in_tool_results',
+  'distill_tool_results',
+  'block_requests_over_budget',
+];
+
+const VALID_ACTIONS    = new Set(['PASS', 'LOCAL', 'TRANSFORM']);
+const KNOWN_TRANSFORMS = new Set(['redact-secrets', 'distill-output']);
+
+// Sourced from policy/built-in-classifiers.js — kept as a plain Set here so
+// validate.js has no require-time dependency on the runtime classifier code.
+const KNOWN_CLASSIFIERS = new Set([
+  'read-input-validator',
+  'glob-input-validator',
+  'grep-input-validator',
+  'todo-write-validator',
+  'todo-read-validator',
+  'bash-allowlist',
+  'powershell-allowlist',
+]);
+
+const KNOWN_TOOL_ENTRY_KEYS = new Set(['action', 'transform', 'executor', 'classifier', 'reason', 'max_output_tokens']);
+
+// ── ANSI colors ────────────────────────────────────────────────────────────────
+
+const col = {
+  r: s => `\x1b[31m${s}\x1b[0m`,
+  g: s => `\x1b[32m${s}\x1b[0m`,
+  y: s => `\x1b[33m${s}\x1b[0m`,
+  d: s => `\x1b[2m${s}\x1b[0m`,
+  b: s => `\x1b[1m${s}\x1b[0m`,
+};
+
+function pad(s, n) { return String(s).padEnd(n); }
+
+// ── Core validation ────────────────────────────────────────────────────────────
+
+/**
+ * Validate a single tool entry object. Pushes issues into the shared arrays.
+ */
+function validateToolEntry(toolPath, entry, errors, warnings) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    errors.push({ path: toolPath, message: 'entry must be a mapping (e.g. action: LOCAL)' });
+    return;
+  }
+
+  // Unknown fields in the tool entry
+  for (const key of Object.keys(entry)) {
+    if (!KNOWN_TOOL_ENTRY_KEYS.has(key)) {
+      warnings.push({ path: `${toolPath}.${key}`, message: 'unknown field — will be ignored at runtime' });
+    }
+  }
+
+  const action = entry.action;
+  if (action === undefined || action === null || action === '') {
+    errors.push({ path: `${toolPath}.action`, message: 'missing required field "action"' });
+    return;
+  }
+  if (!VALID_ACTIONS.has(action)) {
+    errors.push({
+      path:    `${toolPath}.action`,
+      message: `"${action}" is not a valid action — must be PASS, LOCAL, or TRANSFORM`,
+    });
+    return;
+  }
+
+  if (action === 'TRANSFORM') {
+    if (!entry.transform || typeof entry.transform !== 'string' || !entry.transform.trim()) {
+      errors.push({
+        path:    `${toolPath}.transform`,
+        message: 'TRANSFORM requires a non-empty "transform" field (e.g. transform: distill-output)',
+      });
+    } else if (!KNOWN_TRANSFORMS.has(entry.transform.trim())) {
+      warnings.push({
+        path:    `${toolPath}.transform`,
+        message: `"${entry.transform}" is not a built-in transform — ensure it is implemented in the dispatcher`,
+      });
+    }
+  }
+
+  if (action === 'LOCAL' && entry.classifier) {
+    if (!KNOWN_CLASSIFIERS.has(entry.classifier)) {
+      warnings.push({
+        path:    `${toolPath}.classifier`,
+        message: `"${entry.classifier}" is not a known classifier — entry will fall back to PASS at runtime`,
+      });
+    }
+  }
+
+  if ('max_output_tokens' in entry) {
+    const v = entry.max_output_tokens;
+    if (typeof v !== 'number' || !Number.isFinite(v) || !Number.isInteger(v) || v <= 0) {
+      errors.push({
+        path:    `${toolPath}.max_output_tokens`,
+        message: `expected a positive integer (tokens), got ${JSON.stringify(v)}`,
+      });
+    }
+  }
+}
+
+/**
+ * Validate a parsed policy object (output of loader.parse()).
+ *
+ * @param {object} parsed  Raw parsed policy (not yet normalized)
+ * @returns {{ errors: Array<{path, message}>, warnings: Array<{path, message}> }}
+ */
+function validatePolicy(parsed) {
+  const errors   = [];
+  const warnings = [];
+
+  if (!parsed || typeof parsed !== 'object') {
+    errors.push({ path: '(document)', message: 'policy must be a YAML mapping at the top level' });
+    return { errors, warnings };
+  }
+
+  // Unknown top-level keys
+  for (const key of Object.keys(parsed)) {
+    if (!KNOWN_TOP_LEVEL.has(key)) {
+      warnings.push({ path: key, message: 'unknown key — will be ignored at runtime' });
+    }
+  }
+
+  // version type
+  if ('version' in parsed && typeof parsed.version !== 'number') {
+    errors.push({ path: 'version', message: `expected a number, got ${JSON.stringify(parsed.version)}` });
+  }
+
+  // Boolean flags
+  for (const flag of BOOLEAN_FLAGS) {
+    if (flag in parsed && typeof parsed[flag] !== 'boolean') {
+      errors.push({
+        path:    flag,
+        message: `expected true or false, got ${JSON.stringify(parsed[flag])}`,
+      });
+    }
+  }
+
+  // deny_paths / allow_paths — error severity because a silently skipped deny
+  // entry is a silent security gap, not just a misconfiguration warning.
+  for (const listKey of ['deny_paths', 'allow_paths']) {
+    if (listKey in parsed) {
+      const val = parsed[listKey];
+      if (!Array.isArray(val)) {
+        errors.push({ path: listKey, message: 'must be a list (each entry on a new line starting with "- ")' });
+      } else {
+        val.forEach((entry, i) => {
+          if (typeof entry !== 'string' || !entry.trim()) {
+            errors.push({
+              path:    `${listKey}[${i}]`,
+              message: 'entry is not a non-empty string — will be silently skipped at runtime',
+            });
+          }
+        });
+      }
+    }
+  }
+
+  // deny_patterns — error severity for invalid RegExp values
+  if ('deny_patterns' in parsed) {
+    const val = parsed.deny_patterns;
+    if (!val || typeof val !== 'object' || Array.isArray(val)) {
+      errors.push({ path: 'deny_patterns', message: 'must be a mapping of label: "regex-string" entries' });
+    } else {
+      for (const [label, rawPattern] of Object.entries(val)) {
+        if (typeof rawPattern !== 'string') {
+          errors.push({
+            path:    `deny_patterns.${label}`,
+            message: `value must be a regex string, got ${JSON.stringify(rawPattern)}`,
+          });
+        } else {
+          try { new RegExp(rawPattern); } catch (e) {
+            errors.push({
+              path:    `deny_patterns.${label}`,
+              message: `invalid RegExp "${rawPattern}" — ${e.message}`,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  // tools block
+  if ('tools' in parsed) {
+    const t = parsed.tools;
+    if (!t || typeof t !== 'object' || Array.isArray(t)) {
+      errors.push({ path: 'tools', message: 'must be a mapping of tool names to entries' });
+    } else {
+      for (const [name, entry] of Object.entries(t)) {
+        validateToolEntry(`tools.${name}`, entry, errors, warnings);
+      }
+    }
+  }
+
+  return { errors, warnings };
+}
+
+// ── CLI display ────────────────────────────────────────────────────────────────
+
+/**
+ * @param {string[]} args  Remaining CLI args after 'policy validate'
+ * @param {object}  [opts] { loader, fs } — injectable for tests
+ * @returns {{ ok: boolean }}  ok=false when errors exist; caller should exit(1)
+ */
+function runValidateCli(args, opts = {}) {
+  const loader = opts.loader || require('./loader');
+  const fsMod  = opts.fs     || fs;
+
+  // Determine file path — support --file override
+  const fileArgIdx = (args || []).indexOf('--file');
+  const filePath   = (fileArgIdx >= 0 && args[fileArgIdx + 1])
+    ? path.resolve(args[fileArgIdx + 1])
+    : loader.DEFAULT_PATH;
+
+  // Attempt to read the file
+  let text       = null;
+  let fileExists = false;
+  try {
+    text       = fsMod.readFileSync(filePath, 'utf8');
+    fileExists = true;
+  } catch { /* file absent or unreadable */ }
+
+  // Header
+  console.log(col.b('\n⚡ Occasio — Policy Validate\n'));
+  const fileStatus = fileExists
+    ? `${filePath}  ${col.g('(loaded)')}`
+    : `${col.d(filePath)}  ${col.d('(not found)')}`;
+  console.log(`  File:    ${fileStatus}`);
+
+  if (!fileExists) {
+    console.log(col.g('\n  ✓  No policy file — built-in defaults apply.\n'));
+    return { ok: true };
+  }
+
+  // Parse the raw text and validate
+  const parsed             = loader.parse(text);
+  const { errors, warnings } = validatePolicy(parsed);
+
+  if (errors.length === 0 && warnings.length === 0) {
+    console.log(col.g('\n  ✓  Policy is valid — no issues found.\n'));
+    return { ok: true };
+  }
+
+  const pathWidth = (items) =>
+    items.length ? Math.max(...items.map(i => i.path.length)) + 2 : 0;
+
+  if (errors.length) {
+    const pw = pathWidth(errors);
+    console.log(col.r(`\n  ✗  ${errors.length} error${errors.length !== 1 ? 's' : ''}:`));
+    for (const e of errors) {
+      console.log(`     ${pad(e.path, pw)}  ${col.r(e.message)}`);
+    }
+  }
+
+  if (warnings.length) {
+    const pw = pathWidth(warnings);
+    console.log(col.y(`\n  ⚠  ${warnings.length} warning${warnings.length !== 1 ? 's' : ''}:`));
+    for (const w of warnings) {
+      console.log(`     ${pad(w.path, pw)}  ${col.y(w.message)}`);
+    }
+  }
+
+  console.log('');
+
+  if (errors.length) {
+    console.log(col.r('  Errors found — policy will not apply as written.\n'));
+    return { ok: false };
+  }
+
+  console.log(col.y('  Warnings present — review the issues above.\n'));
+  return { ok: true };
+}
+
+module.exports = { validatePolicy, runValidateCli, KNOWN_TOP_LEVEL, KNOWN_TRANSFORMS, KNOWN_CLASSIFIERS, VALID_ACTIONS };