@amg555/frameforge-mcp 2.7.6 → 2.7.7

package/.agent/skills/gstack-browse/src/network-capture.ts

@@ -1,179 +0,0 @@
-/**
- * Network response body capture — SizeCappedBuffer + capture lifecycle.
- *
- * Architecture:
- *   page.on('response') listener → filter by URL pattern → store body
- *   SizeCappedBuffer: evicts oldest entries when total size exceeds cap
- *   Export: writes JSONL file (one response per line)
- *
- * Memory management:
- *   - 50MB total buffer cap (configurable)
- *   - 5MB per-entry body cap (larger responses stored as metadata only)
- *   - Binary responses stored as base64
- *   - Text responses stored as-is
- */
-
-import * as fs from 'fs';
-import type { Response as PlaywrightResponse } from 'playwright';
-
-export interface CapturedResponse {
-  url: string;
-  status: number;
-  headers: Record<string, string>;
-  body: string;
-  contentType: string;
-  timestamp: number;
-  size: number;
-  bodyTruncated: boolean;
-}
-
-const MAX_BUFFER_SIZE = 50 * 1024 * 1024; // 50MB total
-const MAX_ENTRY_SIZE = 5 * 1024 * 1024;   // 5MB per response body
-
-export class SizeCappedBuffer {
-  private entries: CapturedResponse[] = [];
-  private totalSize = 0;
-  private readonly maxSize: number;
-
-  constructor(maxSize = MAX_BUFFER_SIZE) {
-    this.maxSize = maxSize;
-  }
-
-  push(entry: CapturedResponse): void {
-    // Evict oldest entries until we have room
-    while (this.entries.length > 0 && this.totalSize + entry.size > this.maxSize) {
-      const evicted = this.entries.shift()!;
-      this.totalSize -= evicted.size;
-    }
-    this.entries.push(entry);
-    this.totalSize += entry.size;
-  }
-
-  toArray(): CapturedResponse[] {
-    return [...this.entries];
-  }
-
-  get length(): number {
-    return this.entries.length;
-  }
-
-  get byteSize(): number {
-    return this.totalSize;
-  }
-
-  clear(): void {
-    this.entries = [];
-    this.totalSize = 0;
-  }
-
-  /** Export to JSONL file. */
-  exportToFile(filePath: string): number {
-    const lines = this.entries.map(e => JSON.stringify(e));
-    fs.writeFileSync(filePath, lines.join('\n') + '\n');
-    return this.entries.length;
-  }
-
-  /** Summary of captured responses (URL, status, size). */
-  summary(): string {
-    if (this.entries.length === 0) return 'No captured responses.';
-    const lines = this.entries.map((e, i) =>
-      `  [${i + 1}] ${e.status} ${e.url.slice(0, 100)} (${Math.round(e.size / 1024)}KB${e.bodyTruncated ? ', truncated' : ''})`
-    );
-    return `${this.entries.length} responses (${Math.round(this.totalSize / 1024)}KB total):\n${lines.join('\n')}`;
-  }
-}
-
-/** Global capture state. */
-let captureBuffer = new SizeCappedBuffer();
-let captureActive = false;
-let captureFilter: RegExp | null = null;
-let captureListener: ((response: PlaywrightResponse) => Promise<void>) | null = null;
-
-export function isCaptureActive(): boolean {
-  return captureActive;
-}
-
-export function getCaptureBuffer(): SizeCappedBuffer {
-  return captureBuffer;
-}
-
-/** Create the response listener function. */
-function createResponseListener(filter: RegExp | null): (response: PlaywrightResponse) => Promise<void> {
-  return async (response: PlaywrightResponse) => {
-    const url = response.url();
-    if (filter && !filter.test(url)) return;
-
-    // Skip non-content responses (redirects, 204, etc.)
-    const status = response.status();
-    if (status === 204 || status === 301 || status === 302 || status === 304) return;
-
-    const contentType = response.headers()['content-type'] || '';
-    let body = '';
-    let bodySize = 0;
-    let truncated = false;
-
-    try {
-      const rawBody = await response.body();
-      bodySize = rawBody.length;
-
-      if (bodySize > MAX_ENTRY_SIZE) {
-        truncated = true;
-        body = '';
-      } else if (contentType.includes('json') || contentType.includes('text') || contentType.includes('xml') || contentType.includes('html')) {
-        body = rawBody.toString('utf-8');
-      } else {
-        body = rawBody.toString('base64');
-      }
-    } catch {
-      // Response body may be unavailable (e.g., streaming, aborted)
-      body = '';
-      truncated = true;
-    }
-
-    const entry: CapturedResponse = {
-      url,
-      status,
-      headers: response.headers(),
-      body,
-      contentType,
-      timestamp: Date.now(),
-      size: bodySize,
-      bodyTruncated: truncated,
-    };
-
-    captureBuffer.push(entry);
-  };
-}
-
-/** Start capturing response bodies. */
-export function startCapture(filterPattern?: string): { filter: string | null } {
-  captureFilter = filterPattern ? new RegExp(filterPattern) : null;
-  captureActive = true;
-  captureListener = createResponseListener(captureFilter);
-  return { filter: filterPattern || null };
-}
-
-/** Get the active listener (to attach to page). */
-export function getCaptureListener(): ((response: PlaywrightResponse) => Promise<void>) | null {
-  return captureListener;
-}
-
-/** Stop capturing. */
-export function stopCapture(): { count: number; sizeKB: number } {
-  captureActive = false;
-  captureListener = null;
-  return {
-    count: captureBuffer.length,
-    sizeKB: Math.round(captureBuffer.byteSize / 1024),
-  };
-}
-
-/** Clear the capture buffer. */
-export function clearCapture(): void {
-  captureBuffer.clear();
-}
-
-/** Export captured responses to JSONL file. */
-export function exportCapture(filePath: string): number {
-  return captureBuffer.exportToFile(filePath);
-}

package/.agent/skills/gstack-browse/src/path-security.ts

@@ -1,132 +0,0 @@
-/**
- * Shared path validation — single source of truth for file path security.
- *
- * Previously duplicated across write-commands.ts, meta-commands.ts, and read-commands.ts.
- * All file I/O commands (screenshot, pdf, download, scrape, archive, eval) must
- * validate paths through these functions.
- *
- *   validateOutputPath(path)   — for writing files (screenshot, pdf, download, scrape, archive)
- *   validateReadPath(path)     — for reading files (eval)
- *   validateTempPath(path)     — for serving files to remote agents (GET /file, TEMP_DIR only)
- *
- * Security invariants:
- *   1. All paths resolved to absolute before checking
- *   2. Symlinks resolved to catch traversal via symlink inside safe dir
- *   3. SAFE_DIRECTORIES = [...TEMP_DIRS, cwd] for local commands (TEMP_DIRS =
- *      classic TEMP_DIR plus os.tmpdir(), which differ on macOS and under
- *      TMPDIR-honoring CI/sandbox environments)
- *   4. TEMP_ONLY = [TEMP_DIR] for remote file serving (prevents project file exfil)
- *   5. Safe directories and targets go through the same realpath (#3104):
- *      on Windows `fs.realpathSync` keeps an 8.3 short name such as
- *      C:\Users\BURCIN~1 while `fs.realpathSync.native` expands it, so mixing
- *      them rejected paths inside the temp dir. Resolved paths compare exactly;
- *      only a tail that does not exist yet is case-folded on Windows.
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { TEMP_DIR, TEMP_DIRS, isPathWithin } from './platform';
-
-const realpath = fs.realpathSync.native;
-const foldMissing = (component: string) => process.platform === 'win32' ? component.toLowerCase() : component;
-
-/**
- * Resolve the longest existing prefix of `filePath` with the one realpath
- * function and append the missing tail, case-folded on Windows. Throws for
- * resolution errors other than ENOENT.
- */
-export function resolveRealPath(filePath: string): string {
-  const absolute = path.resolve(filePath);
-  try {
-    return realpath(absolute);
-  } catch (err: any) {
-    const parent = path.dirname(absolute);
-    if (err?.code !== 'ENOENT' || parent === absolute) throw err;
-    return path.join(resolveRealPath(parent), foldMissing(path.basename(absolute)));
-  }
-}
-
-const resolveSafeDir = (dir: string) => {
-  try { return resolveRealPath(dir); } catch { return path.resolve(dir); }
-};
-
-// Resolved like every target, so symlinks (macOS /tmp → /private/tmp) and
-// Windows 8.3 names compare equal.
-export const SAFE_DIRECTORIES = [...TEMP_DIRS, process.cwd()].map(resolveSafeDir);
-
-const TEMP_ONLY = [TEMP_DIR].map(resolveSafeDir);
-
-/**
- * Validate a file path for writing (screenshot, pdf, download, scrape, archive).
- *
- * Walks the path one component at a time the way the kernel will, resolving
- * every existing component (symlinks included) before applying the next, so
- * `link/../x` follows `link` first. A component that does not exist yet must
- * already sit inside a safe directory; a dangling symlink is rejected because
- * a write would create its target. Both the caller's spelling and its lexical
- * normalization are checked, since callers write with either.
- */
-export function validateOutputPath(filePath: string): void {
-  const reject = () => { throw new Error(`Path must be within: ${SAFE_DIRECTORIES.join(', ')}`); };
-  for (const spelling of new Set([filePath, path.resolve(filePath)])) {
-    const root = path.parse(spelling).root;
-    let resolved = path.resolve(root || '.');
-    for (const component of spelling.slice(root.length).split(process.platform === 'win32' ? /[\\/]+/ : /\/+/)) {
-      if (!component || component === '.') continue;
-      if (component === '..') {
-        resolved = path.dirname(resolved);
-        continue;
-      }
-      const next = path.join(resolved, component);
-      try {
-        fs.lstatSync(next);
-      } catch (err: any) {
-        resolved = path.join(resolved, foldMissing(component));
-        if (err?.code === 'ENOENT' && SAFE_DIRECTORIES.some(dir => isPathWithin(resolved, dir))) continue;
-        reject();
-      }
-      try {
-        resolved = realpath(next);
-      } catch {
-        reject();
-      }
-    }
-    if (!SAFE_DIRECTORIES.some(dir => isPathWithin(resolved, dir))) reject();
-  }
-}
-
-/** Validate a file path for reading (eval command). */
-export function validateReadPath(filePath: string): void {
-  let realPath: string;
-  try {
-    realPath = resolveRealPath(filePath);
-  } catch (err: any) {
-    throw new Error(`Cannot resolve real path: ${filePath} (${err.code})`);
-  }
-  const isSafe = SAFE_DIRECTORIES.some(dir => isPathWithin(realPath, dir));
-  if (!isSafe) {
-    throw new Error(`Path must be within: ${SAFE_DIRECTORIES.join(', ')}`);
-  }
-}
-
-/** Validate a file path for remote serving (GET /file). TEMP_DIR only, not cwd. */
-export function validateTempPath(filePath: string): void {
-  let realPath: string;
-  try {
-    realPath = realpath(path.resolve(filePath));
-  } catch (err: any) {
-    if (err.code === 'ENOENT') {
-      throw new Error('File not found');
-    }
-    throw new Error(`Cannot resolve path: ${filePath}`);
-  }
-  const isSafe = TEMP_ONLY.some(dir => isPathWithin(realPath, dir));
-  if (!isSafe) {
-    throw new Error(`Path must be within: ${TEMP_ONLY.join(', ')} (remote file serving is restricted to temp directory)`);
-  }
-}
-
-/** Escape special regex metacharacters in a user-supplied string to prevent ReDoS. */
-export function escapeRegExp(s: string): string {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}

package/.agent/skills/gstack-browse/src/platform.ts

@@ -1,38 +0,0 @@
-/**
- * Cross-platform constants for gstack browse.
- *
- * On macOS/Linux: TEMP_DIR = '/tmp', path.sep = '/'  — identical to hardcoded values.
- * On Windows: TEMP_DIR = os.tmpdir(), path.sep = '\\' — correct Windows behavior.
- */
-
-import * as os from 'os';
-import * as path from 'path';
-
-export const IS_WINDOWS = process.platform === 'win32';
-export const TEMP_DIR = IS_WINDOWS ? os.tmpdir() : '/tmp';
-
-/**
- * All temp roots local commands may read/write. On macOS os.tmpdir() is the
- * per-user /var/folders/... dir (not /tmp), and TMPDIR-honoring environments
- * (CI, syscall-supervised sandboxes that screen /tmp) point os.tmpdir()
- * elsewhere entirely — both are legitimate scratch space alongside the
- * classic /tmp. Remote file serving (TEMP_ONLY in path-security.ts) stays
- * pinned to TEMP_DIR alone; this wider set is for LOCAL path validation only.
- */
-/** A TMPDIR pointed at `/`, the user's home, or a parent of the daemon's cwd
- *  would widen local path validation to that whole subtree for the daemon's
- *  lifetime — treat such a value as misconfiguration and ignore it. */
-function trustableTmpdir(dir: string): boolean {
-  const resolved = path.resolve(dir);
-  const home = os.homedir();
-  if (resolved === path.parse(resolved).root) return false;
-  if (resolved === home) return false;
-  return !isPathWithin(path.resolve(process.cwd()), resolved) || isPathWithin(resolved, TEMP_DIR);
-}
-
-export const TEMP_DIRS = [...new Set([TEMP_DIR, os.tmpdir()].filter((d, i) => i === 0 || trustableTmpdir(d)))];
-
-/** Check if resolvedPath is within dir, using platform-aware separators. */
-export function isPathWithin(resolvedPath: string, dir: string): boolean {
-  return resolvedPath === dir || resolvedPath.startsWith(dir + path.sep);
-}

package/.agent/skills/gstack-browse/src/port-allocator.ts

@@ -1,140 +0,0 @@
-/**
- * Shared loopback port allocation (#2314, decision 8).
- *
- * One fixed scan range (10000-49151) for EVERY long-lived gstack listener:
- * the main browse daemon and the terminal-agent. Binding `port: 0` instead
- * hands out a port from the OS EPHEMERAL range (49152-65535 on macOS) — the
- * same pool every short-lived test server draws from — so a daemon that
- * lives for weeks ends up squatting ports that `app.listen(0)` test servers
- * expect to receive, silently absorbing their traffic as phantom 404s. The
- * range therefore ends AT 49151: a max above it would put a fraction of
- * picks back inside the pool this module exists to avoid (the original
- * 60000 cap left ~22% of allocations in 49152-59999).
- *
- * Extracted from server.ts (which had this logic since #486) so
- * terminal-agent.ts can reuse it without importing the whole server module.
- */
-
-import * as net from 'net';
-
-export type PortCheckResult =
-  | { available: true }
-  | { available: false; code?: string; message: string };
-
-export type FailedPortAttempt = {
-  port: number;
-  result: Extract<PortCheckResult, { available: false }>;
-};
-
-export const RANDOM_PORT_MIN = 10000;
-export const RANDOM_PORT_MAX = 49151; // last port BELOW the macOS ephemeral pool (49152-65535)
-export const RANDOM_PORT_RETRIES = 5;
-
-export function normalizePortError(err: unknown): Extract<PortCheckResult, { available: false }> {
-  const maybeNodeError = err as NodeJS.ErrnoException | undefined;
-  return {
-    available: false,
-    code: maybeNodeError?.code,
-    message: maybeNodeError?.message || String(err),
-  };
-}
-
-export function isOccupiedPort(result: Extract<PortCheckResult, { available: false }>): boolean {
-  return result.code === 'EADDRINUSE';
-}
-
-export function formatPortFailureDetail(attempt: FailedPortAttempt): string {
-  const { code, message } = attempt.result;
-  return code ? `${attempt.port} (${code}: ${message})` : `${attempt.port} (${message})`;
-}
-
-export function formatExplicitPortUnavailableError(
-  port: number,
-  result: Extract<PortCheckResult, { available: false }>
-): Error {
-  if (isOccupiedPort(result)) {
-    return new Error(`[browse] Port ${port} (from BROWSE_PORT env) is in use`);
-  }
-
-  const detail = result.code ? `${result.code}: ${result.message}` : result.message;
-  return new Error(
-    `[browse] Cannot bind BROWSE_PORT=${port} on 127.0.0.1 (${detail}). ` +
-    `This usually means localhost port binding is blocked by the current sandbox or OS permissions, ` +
-    `not that the port is occupied. Allow localhost binding, or run browse from an unrestricted terminal.`
-  );
-}
-
-export function formatRandomPortUnavailableError(attempts: FailedPortAttempt[]): Error {
-  const blockingAttempts = attempts.filter((attempt) => !isOccupiedPort(attempt.result));
-
-  if (blockingAttempts.length > 0) {
-    const last = blockingAttempts[blockingAttempts.length - 1];
-    return new Error(
-      `[browse] Cannot bind localhost ports after ${attempts.length} attempts in range ` +
-      `${RANDOM_PORT_MIN}-${RANDOM_PORT_MAX}. Last error: ${formatPortFailureDetail(last)}. ` +
-      `This usually means the current sandbox or OS permissions are blocking localhost port binding, ` +
-      `not that every sampled port is occupied. Allow localhost binding, set BROWSE_PORT to an approved ` +
-      `port, or run browse from an unrestricted terminal.`
-    );
-  }
-
-  return new Error(
-    `[browse] No available port after ${RANDOM_PORT_RETRIES} attempts in range ` +
-    `${RANDOM_PORT_MIN}-${RANDOM_PORT_MAX}; every sampled port was already in use`
-  );
-}
-
-// Test if a port is available by binding and immediately releasing.
-// Uses net.createServer instead of Bun.serve to avoid a race condition
-// in the Node.js polyfill where listen/close are async but the caller
-// expects synchronous bind semantics. See: #486
-export function checkPortAvailable(port: number, hostname: string = '127.0.0.1'): Promise<PortCheckResult> {
-  return new Promise((resolve) => {
-    const srv = net.createServer();
-    let settled = false;
-    const finish = (result: PortCheckResult) => {
-      if (settled) return;
-      settled = true;
-      resolve(result);
-    };
-
-    srv.once('error', (err) => finish(normalizePortError(err)));
-    try {
-      srv.listen(port, hostname, () => {
-        srv.close(() => finish({ available: true }));
-      });
-    } catch (err) {
-      finish(normalizePortError(err));
-    }
-  });
-}
-
-export function isPortAvailable(port: number, hostname: string = '127.0.0.1'): Promise<boolean> {
-  return checkPortAvailable(port, hostname).then((result) => result.available);
-}
-
-/**
- * Find a port: the explicit override when given, otherwise a random port in
- * the fixed 10000-49151 scan range with bounded retries. NEVER `port: 0` —
- * see the module header for why the ephemeral range is off-limits.
- */
-export async function findAvailablePort(explicitPort?: number | null): Promise<number> {
-  if (explicitPort) {
-    const result = await checkPortAvailable(explicitPort);
-    if (result.available) {
-      return explicitPort;
-    }
-    throw formatExplicitPortUnavailableError(explicitPort, result);
-  }
-
-  const attempts: FailedPortAttempt[] = [];
-  for (let attempt = 0; attempt < RANDOM_PORT_RETRIES; attempt++) {
-    const port = RANDOM_PORT_MIN + Math.floor(Math.random() * (RANDOM_PORT_MAX - RANDOM_PORT_MIN));
-    const result = await checkPortAvailable(port);
-    if (result.available) {
-      return port;
-    }
-    attempts.push({ port, result });
-  }
-  throw formatRandomPortUnavailableError(attempts);
-}

package/.agent/skills/gstack-browse/src/project-slug.ts

@@ -1,36 +0,0 @@
-/**
- * Project slug resolution for the browse daemon.
- *
- * Used by domain-skills (per-project storage) and sidebar prompt-context
- * injection. Cached after first call — slug is derived from the daemon's
- * git remote (or env override) and doesn't change between commands.
- */
-
-import * as path from 'path';
-import * as os from 'os';
-import { execSync } from 'child_process';
-
-let cachedSlug: string | null = null;
-
-export function getCurrentProjectSlug(): string {
-  if (cachedSlug) return cachedSlug;
-  const explicit = process.env.GSTACK_PROJECT_SLUG;
-  if (explicit) {
-    cachedSlug = explicit;
-    return explicit;
-  }
-  try {
-    const slugBin = path.join(os.homedir(), '.claude/skills/gstack/bin/gstack-slug');
-    const out = execSync(slugBin, { encoding: 'utf8', timeout: 2000, windowsHide: true }).trim();
-    const m = out.match(/SLUG="?([^"\n]+)"?/);
-    cachedSlug = m ? m[1]! : (out || 'unknown');
-  } catch {
-    cachedSlug = 'unknown';
-  }
-  return cachedSlug;
-}
-
-/** Reset cache; for tests only. */
-export function _resetProjectSlugCache(): void {
-  cachedSlug = null;
-}