@moretea-labs/forge 1.6.0 → 1.7.1

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;
@@ -35,7 +42,7 @@ const READ_ONLY_GIT_SUBCOMMANDS = new Set([
   'count-objects', 'verify-pack', 'check-ignore',
 ]);
 
-function shellSegments(command: string): string[] {
+export function shellSegments(command: string): string[] {
   const segments: string[] = [];
   let current = '';
   let quote: "'" | '"' | undefined;
@@ -80,7 +87,7 @@ function shellSegments(command: string): string[] {
   return segments;
 }
 
-function shellWordsPreservingQuotes(segment: string): string[] {
+export function shellWordsPreservingQuotes(segment: string): string[] {
   const words: string[] = [];
   let current = '';
   let quote: "'" | '"' | undefined;
@@ -253,18 +260,67 @@ function isReadOnlyCodegraphCommand(words: string[]): boolean {
   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);
 }
 
@@ -275,15 +331,42 @@ function isReadOnlyLoopbackCurl(words: string[]): boolean {
   const program = words[0]?.split(/[\\/]/).at(-1)?.toLowerCase();
   if (program !== 'curl') return false;
   const args = words.slice(1);
-  const writeFlags = new Set(['-d', '--data', '--data-raw', '--data-binary', '-f', '--form', '-t', '--upload-file', '-o', '--output', '-O', '--remote-name']);
-  if (args.some((arg) => writeFlags.has(arg))) return false;
+  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) {
-    if (args[index] === '-X' || args[index] === '--request') {
-      if (!/^(?:GET|HEAD)$/i.test(args[index + 1] ?? '')) return false;
+    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;
   }
-  const urls = args.filter((arg) => /^https?:\/\//i.test(arg));
   if (urls.length === 0) return false;
   return urls.every((url) => {
     try { return ['127.0.0.1', 'localhost', '::1'].includes(new URL(url).hostname.toLowerCase()); }
@@ -570,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'] };
@@ -661,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');