@moretea-labs/forge 1.5.1 → 1.7.0

package/src/cli/repositories/command-classifier.ts

@@ -4,6 +4,13 @@ export type RepositoryCommandRisk = 'readonly' | 'workspace_write' | 'remote_wri
 export type RepositoryCommandAuthorization = 'explicit_user_request' | 'confirmed_plan' | 'policy' | 'full_access' | 'goal_delegation' | 'gpt_risk_delegate' | 'user_confirmation';
 export type RepositoryCommandConfirmation = 'none' | 'authorization' | 'strong_confirmation';
 
+/**
+ * Advisory command metadata only. This classifier is intentionally heuristic:
+ * consumers may use it for observability, replay hints, and conservative
+ * resource-claim selection, but it is not an execution-permission authority.
+ * Repository command admission is defined by concrete repository/cwd/capability
+ * scope and the Process Runtime rather than an exhaustive command allow/deny list.
+ */
 export interface RepositoryCommandClassification {
   risk: RepositoryCommandRisk;
   confirmation: RepositoryCommandConfirmation;
@@ -80,6 +87,77 @@ function shellSegments(command: string): string[] {
   return segments;
 }
 
+function shellWordsPreservingQuotes(segment: string): string[] {
+  const words: string[] = [];
+  let current = '';
+  let quote: "'" | '"' | undefined;
+  let escaped = false;
+  const flush = () => {
+    if (current) words.push(current);
+    current = '';
+  };
+  for (let index = 0; index < segment.length; index += 1) {
+    const char = segment[index]!;
+    if (escaped) { current += char; escaped = false; continue; }
+    if (char === '\\' && quote !== "'") { escaped = true; continue; }
+    if (quote) {
+      if (char === quote) quote = undefined;
+      else current += char;
+      continue;
+    }
+    if (char === "'" || char === '"') { quote = char; continue; }
+    if (/\s/.test(char)) { flush(); continue; }
+    current += char;
+  }
+  flush();
+  return words;
+}
+
+const SAFE_SQLITE_READ_OPTIONS = new Set([
+  '-safe', '--safe', '-readonly', '--readonly', '-batch', '--batch',
+  '-header', '--header', '-noheader', '--noheader', '-json', '--json',
+  '-csv', '--csv', '-list', '--list', '-line', '--line', '-column', '--column',
+  '-tabs', '--tabs', '-table', '--table', '-box', '--box', '-markdown', '--markdown',
+  '-quote', '--quote', '-ascii', '--ascii',
+]);
+
+function isSingleReadOnlySql(sql: string): boolean {
+  const normalized = sql.trim();
+  if (!normalized || normalized.startsWith('.')) return false;
+  const withoutTrailingSemicolon = normalized.endsWith(';') ? normalized.slice(0, -1).trimEnd() : normalized;
+  if (withoutTrailingSemicolon.includes(';')) return false;
+  if (!/^(?:select\b|with\b)/i.test(withoutTrailingSemicolon)) return false;
+  return !/\b(?:insert|update|delete|replace|create|drop|alter|vacuum|attach|detach|reindex|analyze|pragma|begin|commit|rollback|savepoint|release)\b/i.test(withoutTrailingSemicolon);
+}
+
+function isSafeReadOnlySqliteWords(rawWords: string[]): boolean {
+  const words = rawWords.filter(Boolean);
+  const program = words[0]?.split(/[\\/]/).at(-1)?.toLowerCase();
+  if (program !== 'sqlite3') return false;
+  const args = words.slice(1);
+  if (args.some((word) => /^(?:--?nonce)(?:=|$)/i.test(word) || /^(?:--?unsafe-testing)(?:=|$)/i.test(word))) return false;
+  let safe = false;
+  let readonly = false;
+  let index = 0;
+  for (; index < args.length; index += 1) {
+    const arg = args[index]!;
+    if (!arg.startsWith('-')) break;
+    if (!SAFE_SQLITE_READ_OPTIONS.has(arg.toLowerCase())) return false;
+    if (arg === '-safe' || arg === '--safe') safe = true;
+    if (arg === '-readonly' || arg === '--readonly') readonly = true;
+  }
+  if (!safe || !readonly) return false;
+  const database = args[index];
+  const sql = args[index + 1];
+  if (!database || !sql || args.length !== index + 2) return false;
+  return isSingleReadOnlySql(sql);
+}
+
+function isSafeReadOnlySqliteSegment(segment: string): boolean {
+  const stripped = segment.replace(/^\s*(?:[A-Za-z_][A-Za-z0-9_]*=[^\s]+\s+)*/, '');
+  return isSafeReadOnlySqliteWords(shellWordsPreservingQuotes(stripped));
+}
+
 function isSedInPlaceSegment(segment: string): boolean {
   const words = firstWords(segment);
   if (words[0]?.toLowerCase() !== 'sed') return false;
@@ -177,22 +255,125 @@ function readOnlyGitSegment(words: string[], _segment: string): boolean {
   return isReadOnlyGitCommand(words);
 }
 
+function isReadOnlyCodegraphCommand(words: string[]): boolean {
+  const program = words[0]?.split(/[\\/]/).at(-1)?.toLowerCase();
+  return program === 'codegraph' && words[1]?.toLowerCase() === 'status';
+}
+
+function githubCliApiMethod(words: string[]): string | undefined {
+  for (let index = 2; index < words.length; index += 1) {
+    const word = words[index]?.toLowerCase();
+    if (word === '-x' || word === '--method') return words[index + 1]?.toUpperCase();
+    if (word?.startsWith('--method=')) return word.slice('--method='.length).toUpperCase();
+  }
+  return undefined;
+}
+
+function isReadOnlyGitHubCliCommand(words: string[]): boolean {
+  const program = words[0]?.split(/[\\/]/).at(-1)?.toLowerCase();
+  if (program !== 'gh') return false;
+  const group = words[1]?.toLowerCase() ?? '';
+  const action = words[2]?.toLowerCase() ?? '';
+  if (['--version', 'version', 'help', '--help', '-h'].includes(group)) return true;
+  if (group === 'auth' && action === 'status') return true;
+  if (group === 'search' && ['code', 'commits', 'issues', 'prs', 'repos'].includes(action)) return true;
+  if (group === 'repo' && action === 'view') return true;
+  if (group === 'pr' && ['list', 'view', 'status', 'checks', 'diff'].includes(action)) return true;
+  if (group === 'issue' && ['list', 'view'].includes(action)) return true;
+  if (group === 'run' && ['list', 'view', 'watch'].includes(action)) return true;
+  if (group === 'workflow' && ['list', 'view'].includes(action)) return true;
+  if (group === 'release' && ['list', 'view', 'download'].includes(action)) return true;
+  if (group !== 'api') return false;
+
+  const method = githubCliApiMethod(words);
+  if (method) return method === 'GET' || method === 'HEAD';
+  const hasBodyInput = words.slice(2).some((word) => {
+    const lower = word.toLowerCase();
+    return lower === '-f' || lower === '--raw-field' || lower === '--field'
+      || lower === '--input' || lower.startsWith('--raw-field=') || lower.startsWith('--field=') || lower.startsWith('--input=');
+  });
+  return !hasBodyInput;
+}
+
+function isLocalGitHubCliWorkspaceCommand(words: string[]): boolean {
+  const program = words[0]?.split(/[\\/]/).at(-1)?.toLowerCase();
+  if (program !== 'gh') return false;
+  const group = words[1]?.toLowerCase() ?? '';
+  const action = words[2]?.toLowerCase() ?? '';
+  return (group === 'repo' && action === 'clone') || (group === 'pr' && action === 'checkout');
+}
+
+function isGitHubCliExternalMutation(words: string[]): boolean {
+  const program = words[0]?.split(/[\\/]/).at(-1)?.toLowerCase();
+  if (program !== 'gh') return false;
+  if (isReadOnlyGitHubCliCommand(words) || isLocalGitHubCliWorkspaceCommand(words)) return false;
+  return true;
+}
+
 function isReadOnlySegment(segment: string): boolean {
   const words = firstWords(segment);
   const program = words[0]?.toLowerCase();
   if (!program) return false;
   if (program === 'git') return readOnlyGitSegment(words, segment);
+  if (isReadOnlyCodegraphCommand(words)) return true;
+  if (program === 'curl') return isReadOnlyLoopbackCurl(words);
+  if (program === 'sqlite3') return isSafeReadOnlySqliteSegment(segment);
   if (program === 'find') return !/(?:-delete|-exec|-execdir|-ok|-okdir)\b/.test(segment);
   if (program === 'sed') return !isSedInPlaceSegment(segment);
-  if (program === 'gh') {
-    return /\bgh\s+(?:repo\s+view|pr\s+(?:list|view|status|checks|diff)|issue\s+(?:list|view)|run\s+(?:list|view|watch)|release\s+(?:list|view|download))(?:\s|$)/.test(segment);
-  }
+  if (program === 'gh') return isReadOnlyGitHubCliCommand(words);
   return READ_ONLY_PROGRAMS.has(program);
 }
 
 /** Package scripts that are local validation (not install/publish/mutate deps). */
 const SAFE_PACKAGE_SCRIPT = /^(?:test|check|lint|typecheck|format:check|tsc)(?::|$)/i;
 
+function isReadOnlyLoopbackCurl(words: string[]): boolean {
+  const program = words[0]?.split(/[\\/]/).at(-1)?.toLowerCase();
+  if (program !== 'curl') return false;
+  const args = words.slice(1);
+  const urls: string[] = [];
+  const safeLongFlags = new Set(['--fail', '--fail-with-body', '--silent', '--show-error', '--head']);
+  const safeValueFlags = new Set(['--connect-timeout', '--max-time', '--retry', '--retry-delay', '--retry-max-time']);
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] ?? '';
+    if (arg.startsWith('http://') || arg.startsWith('https://')) {
+      urls.push(arg);
+      continue;
+    }
+    const lower = arg.toLowerCase();
+    if (lower === '-x' || lower === '--request') {
+      const method = (args[index + 1] ?? '').toUpperCase();
+      if (method !== 'GET' && method !== 'HEAD') return false;
+      index += 1;
+      continue;
+    }
+    if (lower.startsWith('--request=')) {
+      const method = arg.slice(arg.indexOf('=') + 1).toUpperCase();
+      if (method !== 'GET' && method !== 'HEAD') return false;
+      continue;
+    }
+    if (safeLongFlags.has(lower)) continue;
+    if (['>/dev/null', '1>/dev/null', '2>/dev/null', '>>/dev/null', '1>>/dev/null', '2>>/dev/null'].includes(arg)) continue;
+    if (['>', '1>', '2>', '>>', '1>>', '2>>'].includes(arg) && args[index + 1] === '/dev/null') {
+      index += 1;
+      continue;
+    }
+    if (safeValueFlags.has(lower)) {
+      const value = Number(args[index + 1]);
+      if (!Number.isFinite(value) || value < 0) return false;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith('-') && arg.length > 1 && Array.from(arg.slice(1)).every((flag) => ['f', 's', 'S', 'I'].includes(flag))) continue;
+    return false;
+  }
+  if (urls.length === 0) return false;
+  return urls.every((url) => {
+    try { return ['127.0.0.1', 'localhost', '::1'].includes(new URL(url).hostname.toLowerCase()); }
+    catch { return false; }
+  });
+}
+
 function isSafePackageRunner(program: string, words: string[]): boolean {
   if (!['bun', 'npm', 'pnpm', 'yarn', 'node'].includes(program)) return false;
   // bun test <path>, npm test, etc.
@@ -440,6 +621,15 @@ function classifyArgvCommand(
   if (program === 'git' && isReadOnlyGitCommand(argv)) {
     return { risk: 'readonly', confirmation: 'none', reasons: ['the argv command is a recognized repository-local read operation'] };
   }
+  if (isReadOnlyCodegraphCommand(argv)) {
+    return { risk: 'readonly', confirmation: 'none', reasons: ['CodeGraph status only observes the local semantic index'] };
+  }
+  if (program === 'curl' && isReadOnlyLoopbackCurl(argv)) {
+    return { risk: 'readonly', confirmation: 'none', reasons: ['curl performs a read-only loopback HTTP observation without writing response data to disk'] };
+  }
+  if (program === 'sqlite3' && isSafeReadOnlySqliteWords(argv)) {
+    return { risk: 'readonly', confirmation: 'none', reasons: ['sqlite3 is constrained by safe mode, readonly database access, and one read-only SQL statement'] };
+  }
   // Explicit shell wrappers are common in generated diagnostics. Re-classify
   // the fixed inner command instead of treating `sh -c` / `bash -lc` wrappers
   // as workspace mutations. Unsafe shell constructs are still rejected by the
@@ -463,19 +653,16 @@ function classifyArgvCommand(
   if (program === 'log' && ['show', 'stream', 'stats', 'config'].includes(subcommand ?? '') && subcommand !== 'config') {
     return { risk: 'readonly', confirmation: 'none', reasons: ['system log observation is read-only'] };
   }
-  // Explicit readonly GitHub CLI observations (must not be treated as workspace write).
   if (program === 'gh') {
-    const group = subcommand ?? '';
-    const action = (argv[2] ?? '').toLowerCase();
-    const readonlyGh =
-      (group === 'repo' && action === 'view')
-      || (group === 'pr' && ['list', 'view', 'status', 'checks', 'diff'].includes(action))
-      || (group === 'issue' && ['list', 'view'].includes(action))
-      || (group === 'run' && ['list', 'view', 'watch'].includes(action))
-      || (group === 'release' && ['list', 'view', 'download'].includes(action));
-    if (readonlyGh) {
+    if (isReadOnlyGitHubCliCommand(argv)) {
       return { risk: 'readonly', confirmation: 'none', reasons: ['the argv command is a recognized GitHub read operation'] };
     }
+    if (isLocalGitHubCliWorkspaceCommand(argv)) {
+      return { risk: 'workspace_write', confirmation: 'authorization', reasons: ['the GitHub CLI command changes only the local checkout'] };
+    }
+    if (isGitHubCliExternalMutation(argv)) {
+      return { risk: 'remote_write', confirmation: 'authorization', reasons: ['the GitHub CLI command may mutate external GitHub state'] };
+    }
   }
   if (program === 'git' && ['add', 'commit', 'pull', 'fetch', 'merge', 'rebase', 'checkout', 'switch', 'cherry-pick', 'revert', 'stash', 'mv', 'restore', 'apply', 'am', 'bisect'].includes(subcommand ?? '')) {
     return { risk: 'workspace_write', confirmation: 'authorization', reasons: ['changes the checkout, local refs, index, or working tree'] };
@@ -484,6 +671,12 @@ function classifyArgvCommand(
     || (['npm', 'bun', 'pnpm', 'yarn'].includes(program) && ['install', 'add', 'remove', 'update', 'run'].includes(subcommand ?? ''))) {
     return { risk: 'workspace_write', confirmation: 'authorization', reasons: ['writes repository files'] };
   }
+  // Package-manager `version` is a mutation command (for example
+  // `npm version 1.5.1 --no-git-tag-version` updates package metadata). Keep
+  // flag-style queries such as `npm --version` on the readonly path below.
+  if (['npm', 'pnpm', 'yarn'].includes(program) && subcommand === 'version') {
+    return { risk: 'workspace_write', confirmation: 'authorization', reasons: ['package-manager version command may update package metadata'] };
+  }
   // Lightweight project script info queries stay readonly when they only request help/version.
   if (['bun', 'node', 'npm', 'pnpm', 'yarn', 'python', 'python3', 'cargo', 'go', 'swift'].includes(program)
     && argv.slice(1).some((word) => word === '--help' || word === '-h' || word === '--version' || word === '-V' || word === 'version' || word === 'help')) {
@@ -548,10 +741,12 @@ function classifyShellCommand(
 
   const remoteWritePatterns: Array<[RegExp, string]> = [
     [/\bgit\s+push\b/i, 'writes Git refs to a remote'],
-    [/\bgh\s+(?:pr\s+(?:create|edit|close|reopen|merge|comment|review)|issue\s+(?:create|edit|close|reopen|comment)|release\s+(?:create|edit|delete|upload)|repo\s+(?:create|edit|archive|delete))\b/i, 'writes GitHub remote state'],
     [/\b(?:npm|bun)\s+publish\b/i, 'publishes a package'],
   ];
   for (const [pattern, reason] of remoteWritePatterns) if (pattern.test(normalized)) reasons.push(reason);
+  for (const segment of shellSegments(normalized)) {
+    if (isGitHubCliExternalMutation(firstWords(segment))) reasons.push('writes GitHub remote state');
+  }
   if (reasons.length > 0) return { risk: 'remote_write', confirmation: 'authorization', reasons };
 
   if (hasRepositoryOutputRedirection(normalized)) reasons.push('redirects output into a repository file');