@methodts/runtime 0.1.0

package/dist/sessions/runtime-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-tools.js","sourceRoot":"","sources":["../../src/sessions/runtime-tools.ts"],"names":[],"mappings":"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"}

package/dist/sessions/scope-hook.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Scope enforcement configuration for a session.
+ */
+export interface ScopeConstraint {
+    /** Glob patterns of files the agent is allowed to modify. */
+    allowed_paths: string[];
+    /**
+     * Enforcement mode:
+     * - 'enforce': pre-commit hook rejects out-of-scope commits (default)
+     * - 'warn': PTY watcher emits events but commits are not blocked
+     */
+    mode: 'enforce' | 'warn';
+}
+/**
+ * Generate the bash pre-commit hook script content.
+ *
+ * Uses bash pattern matching to check staged files against allowed patterns.
+ * The hook is designed to work with Git for Windows bash and standard Unix bash.
+ *
+ * @param sessionId - Session identifier for traceability in hook comments
+ * @param allowedPaths - Array of glob patterns the agent may modify
+ * @returns The complete bash hook script as a string
+ */
+export declare function generateHookScript(sessionId: string, allowedPaths: string[]): string;
+/**
+ * Resolve the correct hooks directory for a git worktree.
+ *
+ * For linked worktrees, the hooks path may differ from the main repository.
+ * Uses `git rev-parse --git-path hooks` to resolve correctly across git versions.
+ *
+ * @param worktreePath - The root path of the worktree
+ * @returns Absolute path to the hooks directory
+ */
+export declare function resolveHooksDir(worktreePath: string): string;
+/**
+ * Install a scope-enforcing pre-commit hook in a worktree.
+ *
+ * Creates the hooks directory if it doesn't exist, writes the hook script,
+ * and sets executable permissions. Only operates on worktree-isolated sessions.
+ *
+ * @param worktreePath - Path to the worktree root
+ * @param sessionId - Session identifier for hook traceability
+ * @param allowedPaths - Glob patterns of files the agent may modify
+ * @returns Object indicating success and the hook file path
+ */
+export declare function installScopeHook(worktreePath: string, sessionId: string, allowedPaths: string[]): {
+    installed: boolean;
+    hookPath: string | null;
+    error?: string;
+};
+/**
+ * Check if a file path matches any of the allowed patterns.
+ *
+ * This is the TypeScript equivalent of the bash pattern matching in the hook.
+ * Used by the PTY watcher for real-time scope violation detection (Phase 2).
+ *
+ * @param filePath - The file path to check (relative to repo root)
+ * @param allowedPaths - Array of glob patterns
+ * @returns true if the file matches at least one allowed pattern
+ */
+export declare function isPathAllowed(filePath: string, allowedPaths: string[]): boolean;
+/**
+ * Match a file path against a single glob pattern.
+ *
+ * Supports:
+ * - `**` matches any number of path segments (including zero)
+ * - `*` matches any characters within a single path segment (no /)
+ * - `?` matches any single character (not /)
+ * - Literal characters match themselves
+ * - Patterns without `/` match at any depth (like gitignore)
+ *
+ * @param filePath - Normalized file path (forward slashes)
+ * @param pattern - Glob pattern to match against
+ * @returns true if the path matches the pattern
+ */
+export declare function matchGlobPattern(filePath: string, pattern: string): boolean;
+//# sourceMappingURL=scope-hook.d.ts.map

package/dist/sessions/scope-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-hook.d.ts","sourceRoot":"","sources":["../../src/sessions/scope-hook.ts"],"names":[],"mappings":"AAUA;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB;;;;OAIG;IACH,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,MAAM,CAqGpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAiB5D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EAAE,GACrB;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAkDjE;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAY/E;AAeD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAS3E"}

package/dist/sessions/scope-hook.js

@@ -0,0 +1,323 @@
+// SPDX-License-Identifier: Apache-2.0
+// ── PRD 014: Pre-Commit Hook Generator ─────────────────────────
+// Generates a bash pre-commit hook that enforces allowed_paths
+// scope constraints in git worktrees. The hook is self-contained
+// with zero runtime dependencies.
+import { writeFileSync, mkdirSync, chmodSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+/**
+ * Generate the bash pre-commit hook script content.
+ *
+ * Uses bash pattern matching to check staged files against allowed patterns.
+ * The hook is designed to work with Git for Windows bash and standard Unix bash.
+ *
+ * @param sessionId - Session identifier for traceability in hook comments
+ * @param allowedPaths - Array of glob patterns the agent may modify
+ * @returns The complete bash hook script as a string
+ */
+export function generateHookScript(sessionId, allowedPaths) {
+    if (allowedPaths.length === 0) {
+        // No constraint — hook is a no-op
+        return '#!/usr/bin/env bash\n# PRD 014: No scope constraints — all paths allowed\nexit 0\n';
+    }
+    // Convert glob patterns to bash-compatible patterns.
+    // gitignore-style '**' maps to bash extglob '**' (with shopt -s globstar).
+    // For pattern matching via [[ $file == $pattern ]], bash handles * and ** natively.
+    const escapedPatterns = allowedPaths.map(p => {
+        // Escape single quotes in patterns for safe bash embedding
+        return p.replace(/'/g, "'\\''");
+    });
+    const patternsArray = escapedPatterns.map(p => `'${p}'`).join(' ');
+    const patternsComment = allowedPaths.map(p => `#   ${p}`).join('\n');
+    return `#!/usr/bin/env bash
+# Auto-generated by pv-method bridge (PRD 014)
+# Scope enforcement for session: ${sessionId}
+# Allowed paths:
+${patternsComment}
+
+ALLOWED_PATTERNS=(${patternsArray})
+
+# Convert a glob pattern to a bash regex where:
+#   ** matches any characters (including /)
+#   *  matches any characters except /
+#   ?  matches any single character except /
+#   .  is escaped to literal dot
+glob_to_regex() {
+  local pattern="$1"
+  local regex=""
+  local i=0
+  local len=\${#pattern}
+  while [ $i -lt $len ]; do
+    local char="\${pattern:$i:1}"
+    local next="\${pattern:$((i+1)):1}"
+    if [ "$char" = "*" ] && [ "$next" = "*" ]; then
+      local after="\${pattern:$((i+2)):1}"
+      if [ "$after" = "/" ]; then
+        regex+="(.+/)?"; i=$((i+3))
+      else
+        regex+=".*"; i=$((i+2))
+      fi
+    elif [ "$char" = "*" ]; then
+      regex+="[^/]*"; i=$((i+1))
+    elif [ "$char" = "?" ]; then
+      regex+="[^/]"; i=$((i+1))
+    elif [ "$char" = "." ]; then
+      regex+="[.]"; i=$((i+1))
+    else
+      regex+="$char"; i=$((i+1))
+    fi
+  done
+  echo "$regex"
+}
+
+# Get staged files
+STAGED=$(git diff --cached --name-only)
+
+if [ -z "$STAGED" ]; then
+  exit 0
+fi
+
+VIOLATIONS=()
+
+while IFS= read -r file; do
+  [ -z "$file" ] && continue
+  # Strip trailing CR (Windows CRLF)
+  file="\${file%$'\\r'}"
+  allowed=false
+  for pattern in "\${ALLOWED_PATTERNS[@]}"; do
+    # If pattern has no /, allow matching at any depth (gitignore semantics)
+    if [[ "$pattern" != */* ]]; then
+      pattern="**/$pattern"
+    fi
+    regex=$(glob_to_regex "$pattern")
+    if [[ "$file" =~ ^$regex$ ]]; then
+      allowed=true
+      break
+    fi
+  done
+  if [ "$allowed" = false ]; then
+    VIOLATIONS+=("$file")
+  fi
+done <<< "$STAGED"
+
+if [ \${#VIOLATIONS[@]} -gt 0 ]; then
+  echo ""
+  echo "SCOPE VIOLATION: The following files are not in allowed_paths for this session:"
+  printf '  %s\\n' "\${VIOLATIONS[@]}"
+  echo "Allowed patterns: \${ALLOWED_PATTERNS[*]}"
+  echo ""
+  echo "Remove the file(s) from staging (git reset HEAD '<file>') or request scope extension."
+  echo "Session: ${sessionId}"
+  exit 1
+fi
+
+exit 0
+`;
+}
+/**
+ * Resolve the correct hooks directory for a git worktree.
+ *
+ * For linked worktrees, the hooks path may differ from the main repository.
+ * Uses `git rev-parse --git-path hooks` to resolve correctly across git versions.
+ *
+ * @param worktreePath - The root path of the worktree
+ * @returns Absolute path to the hooks directory
+ */
+export function resolveHooksDir(worktreePath) {
+    try {
+        const hooksPath = execSync('git rev-parse --git-path hooks', {
+            cwd: worktreePath,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        // git rev-parse may return a relative path — resolve it
+        if (hooksPath.startsWith('/') || /^[A-Z]:/i.test(hooksPath)) {
+            return hooksPath;
+        }
+        return join(worktreePath, hooksPath);
+    }
+    catch {
+        // Fallback: standard .git/hooks location
+        return join(worktreePath, '.git', 'hooks');
+    }
+}
+/**
+ * Install a scope-enforcing pre-commit hook in a worktree.
+ *
+ * Creates the hooks directory if it doesn't exist, writes the hook script,
+ * and sets executable permissions. Only operates on worktree-isolated sessions.
+ *
+ * @param worktreePath - Path to the worktree root
+ * @param sessionId - Session identifier for hook traceability
+ * @param allowedPaths - Glob patterns of files the agent may modify
+ * @returns Object indicating success and the hook file path
+ */
+export function installScopeHook(worktreePath, sessionId, allowedPaths) {
+    if (allowedPaths.length === 0) {
+        return { installed: false, hookPath: null };
+    }
+    try {
+        const hooksDir = resolveHooksDir(worktreePath);
+        const hookPath = join(hooksDir, 'pre-commit');
+        // Ensure hooks directory exists
+        mkdirSync(hooksDir, { recursive: true });
+        // Check for existing pre-commit hook (F-D-3: don't silently overwrite)
+        if (existsSync(hookPath)) {
+            const existing = readFileSync(hookPath, 'utf-8');
+            if (!existing.includes('PRD 014')) {
+                // Chain: prepend scope check, then call existing hook
+                const script = generateHookScript(sessionId, allowedPaths);
+                const chained = script.replace(/^exit 0\n$/m, '# Chain: run original pre-commit hook\nexec "$(dirname "$0")/pre-commit.original" "$@" 2>/dev/null\nexit 0\n');
+                writeFileSync(hookPath + '.original', existing, { encoding: 'utf-8' });
+                try {
+                    chmodSync(hookPath + '.original', 0o755);
+                }
+                catch { /* Windows */ }
+                writeFileSync(hookPath, chained, { encoding: 'utf-8' });
+                try {
+                    chmodSync(hookPath, 0o755);
+                }
+                catch { /* Windows */ }
+                return { installed: true, hookPath };
+            }
+        }
+        // Generate and write the hook script
+        const script = generateHookScript(sessionId, allowedPaths);
+        writeFileSync(hookPath, script, { encoding: 'utf-8' });
+        // Make executable (Unix). On Windows, git uses bash to run hooks,
+        // so the shebang line is sufficient, but we set permissions anyway.
+        try {
+            chmodSync(hookPath, 0o755);
+        }
+        catch {
+            // chmod may fail on Windows — non-fatal, hooks still work via bash
+        }
+        return { installed: true, hookPath };
+    }
+    catch (e) {
+        return {
+            installed: false,
+            hookPath: null,
+            error: `Failed to install scope hook: ${e.message}`,
+        };
+    }
+}
+/**
+ * Check if a file path matches any of the allowed patterns.
+ *
+ * This is the TypeScript equivalent of the bash pattern matching in the hook.
+ * Used by the PTY watcher for real-time scope violation detection (Phase 2).
+ *
+ * @param filePath - The file path to check (relative to repo root)
+ * @param allowedPaths - Array of glob patterns
+ * @returns true if the file matches at least one allowed pattern
+ */
+export function isPathAllowed(filePath, allowedPaths) {
+    if (allowedPaths.length === 0)
+        return true; // No constraint
+    // Normalize path separators and resolve traversal
+    const normalized = normalizePath(filePath);
+    for (const pattern of allowedPaths) {
+        if (matchGlobPattern(normalized, pattern.replace(/\\/g, '/'))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Normalize a file path: forward slashes, resolve '..' and '.' segments.
+ */
+function normalizePath(filePath) {
+    const parts = filePath.replace(/\\/g, '/').split('/');
+    const resolved = [];
+    for (const seg of parts) {
+        if (seg === '..')
+            resolved.pop();
+        else if (seg !== '.' && seg !== '')
+            resolved.push(seg);
+    }
+    return resolved.join('/');
+}
+/**
+ * Match a file path against a single glob pattern.
+ *
+ * Supports:
+ * - `**` matches any number of path segments (including zero)
+ * - `*` matches any characters within a single path segment (no /)
+ * - `?` matches any single character (not /)
+ * - Literal characters match themselves
+ * - Patterns without `/` match at any depth (like gitignore)
+ *
+ * @param filePath - Normalized file path (forward slashes)
+ * @param pattern - Glob pattern to match against
+ * @returns true if the path matches the pattern
+ */
+export function matchGlobPattern(filePath, pattern) {
+    // If the pattern contains no directory separator, it can match at any depth
+    // (gitignore semantics: `*.ts` matches `src/foo.ts`, not just `foo.ts`)
+    const effectivePattern = pattern.includes('/') ? pattern : `**/${pattern}`;
+    // Convert glob pattern to regex
+    const regexStr = globToRegex(effectivePattern);
+    const regex = new RegExp(`^${regexStr}$`);
+    return regex.test(filePath);
+}
+/**
+ * Convert a glob pattern to a regex string.
+ * Internal helper for matchGlobPattern.
+ */
+function globToRegex(pattern) {
+    let result = '';
+    let i = 0;
+    while (i < pattern.length) {
+        const char = pattern[i];
+        if (char === '*') {
+            if (pattern[i + 1] === '*') {
+                // ** — match any path segments
+                if (pattern[i + 2] === '/') {
+                    // **/ — match zero or more directories
+                    result += '(?:.+/)?';
+                    i += 3;
+                }
+                else if (i + 2 >= pattern.length) {
+                    // ** at end — match everything
+                    result += '.*';
+                    i += 2;
+                }
+                else {
+                    // ** followed by something else
+                    result += '.*';
+                    i += 2;
+                }
+            }
+            else {
+                // * — match within a single path segment (no /)
+                result += '[^/]*';
+                i += 1;
+            }
+        }
+        else if (char === '?') {
+            result += '[^/]';
+            i += 1;
+        }
+        else if (char === '.') {
+            result += '\\.';
+            i += 1;
+        }
+        else if (char === '\\') {
+            result += '\\\\';
+            i += 1;
+        }
+        else if (char === '(' || char === ')' || char === '+' || char === '^' || char === '$' || char === '|' || char === '{' || char === '}' || char === '[' || char === ']') {
+            // Escape regex special chars
+            result += '\\' + char;
+            i += 1;
+        }
+        else {
+            result += char;
+            i += 1;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=scope-hook.js.map

package/dist/sessions/scope-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-hook.js","sourceRoot":"","sources":["../../src/sessions/scope-hook.ts"],"names":[],"mappings":"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"}

package/dist/sessions/scope-hook.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scope-hook.test.d.ts.map

package/dist/sessions/scope-hook.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-hook.test.d.ts","sourceRoot":"","sources":["../../src/sessions/scope-hook.test.ts"],"names":[],"mappings":""}