@open330/oac 2026.4.3 → 2026.220.1

package/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Changelog
+
+All notable changes to OAC (Open Agent Contribution) are documented here.
+
+## [Unreleased]
+
+_No unreleased changes._
+
+---
+
+## [2026.2.5] — 2026-02-20
+
+> **Note**: Versions `2026.3.x` and `2026.4.x` were published with an incorrect CalVer month.
+> This release corrects the version to `2026.2.5` (year=2026, month=February, patch=5th iteration).
+
+### Config Loader Fix (`fb57557`)
+- **fix**: Config loader now matches `@open330/oac` import (previously only matched `@open330/oac-core`)
+
+### OpenCode Provider Integration (`afdf725`)
+- **feat**: OpenCode adapter (`src/execution/agents/opencode.adapter.ts`)
+- **feat**: Adapter registry replacing hard-coded switch (`src/execution/agents/registry.ts`)
+- **fix**: 7 pre-existing typecheck errors resolved (`doctor.ts`, `explain.ts`, `init.ts`, `task.ts`)
+
+### Security & Quality Fixes (`55780e4`)
+- **security**: Fixed shell injection in dashboard browser opener (replaced `exec` with `open` library)
+- **security**: Sanitized branch names in `sandbox.ts` against path traversal
+- **security**: Replaced `sh -c` shell redirect with `execa` piping in `github-auth.ts`
+- **security**: Added `AbortSignal.timeout` to all GitHub API `fetch` calls
+- **security**: SHA-pinned all CI/CD workflow actions
+- **refactor**: Consolidated `truncate()` and `isRecord()` into `core/utils.ts`
+- **refactor**: Unified error normalization into shared `normalizeError` module
+- **refactor**: Extracted `AsyncEventQueue` into shared module for agent adapters
+- **refactor**: Created scanner factory to eliminate construction duplication
+- **chore**: Annotated all 10 empty catch blocks with `// best-effort` comments
+- **ci**: Added `pnpm audit --prod` to CI pipeline
+
+### Deploy Readiness (`91898c8`)
+- **chore**: Added `LICENSE`, `CHANGELOG.md`, `docs/` to npm `files` array
+- **chore**: Added `prepublishOnly` script (`pnpm build && pnpm test`)
+- **chore**: Restored CI/CD workflows (SHA-pinned actions)
+- **chore**: Lowered Node.js requirement from `>=24` to `>=20`
+- **chore**: Fixed repository URL in `package.json`
+
+### Wave 9 — Final P3/T3 Polish (`f8ff2ae`)
+- **feat**: `oac init --minimal` for quick, non-interactive setup
+- **feat**: `oac explain <task-id>` command — inspect why a task/epic was selected
+- **feat**: Colored diff output in `--dry-run` mode (source files, complexity, scanner)
+- **docs**: Comprehensive troubleshooting section in README
+- **perf**: Streaming file reads in analyzer for large files (>1MB threshold)
+- **perf**: Memory pressure monitoring — PQueue auto-throttles when heap usage exceeds 85%
+
+### Wave 8 — Final UX Polish (`806a170`)
+- **docs**: Auto-generated config reference from Zod schema (`docs/config-reference.md`)
+- **docs**: Added CHANGELOG
+
+### Maintenance
+- **chore**: Temporarily removed CI/CD workflows during dev phase (`cb90214`)
+
+---
+
+## [2026.4.3] — 2026-02-18 _(deprecated — wrong CalVer month)_
+
+### Wave 7 — Quick Wins Bundle (`7c179a0`)
+- **feat**: `oac r` alias for `oac run` (power-user shortcut)
+- **feat**: Distinct exit codes for CI/CD integration:
+  - `0` — all tasks succeeded or dry-run
+  - `1` — unhandled error
+  - `2` — config/validation error
+  - `3` — every task/epic failed
+  - `4` — partial success (some tasks failed)
+- **feat**: Resettable token counters (`claudeCounter.reset()`, `codexCounter.reset()`) for correctness in long-lived processes
+- **feat**: Progress percentages on long operations (file analysis, task estimation, epic execution)
+
+### Wave 6 — Single-Command Pipeline (`156c7d2`)
+- **feat**: `oac run` now performs the full scan → analyze → execute pipeline in one command
+- **ux**: Clarified distinction between `oac scan` (discover tasks) and `oac analyze` (build context)
+
+### Wave 5 — Run Module Decomposition (`aea2760`)
+- **refactor**: Decomposed the 1,692-line `run.ts` monolith into `src/cli/commands/run/` with 8 focused modules:
+  - `index.ts` — command definition and option parsing
+  - `pipeline.ts` — top-level orchestration
+  - `epic.ts` — epic-based execution flow
+  - `task.ts` — single-task execution
+  - `retry.ts` — `--retry-failed` pipeline
+  - `output.ts` — summary rendering and JSON output
+  - `validation.ts` — config and input validation
+  - `types.ts` — shared types, exit codes, `ConfigError`
+
+### Wave 4 — Timeout, Completion, & Retry (`cb1af6c`)
+- **feat**: PR creation timeout (prevents hanging on GitHub API issues)
+- **perf**: Replaced hand-rolled `runWithConcurrency` with `PQueue` for bounded parallelism
+- **feat**: `oac completion` command for shell tab-completion (bash/zsh/fish)
+- **feat**: `--retry-failed` flag to re-run only previously failed tasks
+
+### Wave 3 — UX & CLI Improvements (`9869073`)
+- **ux**: Usage examples in every `--help` screen
+- **feat**: Global `--quiet` flag suppresses spinner/progress output (for CI pipelines)
+- **ux**: Failed task/epic details included in run summary
+- **perf**: Parallelized epic execution pipeline with bounded concurrency
+
+### Wave 2 — Helpers, Parallelism, & Cleanup (`417fc85`)
+- **refactor**: Extracted 11 duplicated helper functions into `src/cli/helpers.ts`
+- **perf**: Parallelized `analyzer.ts` file processing with `PQueue`
+- **perf**: Parallelized `todo-scanner.ts` file processing
+- **chore**: Removed dead `withTimeout` utility
+
+### Wave 1 — Foundation Fixes (`4196c59`)
+- **fix**: `withWorktreeLock` now correctly releases locks on error
+- **perf**: Bounded `Promise.all` with `PQueue` to prevent unbounded parallelism
+- **perf**: Replaced `child_process.spawn` with `execa` for better error handling
+- **feat**: SIGINT handler for graceful shutdown
+- **fix**: Removed simulation fallback that silently skipped real execution
+- **feat**: `defineConfig()` wrapper for type-safe config files
+- **ux**: Getting Started help text for first-time users
+

package/README.md

@@ -14,7 +14,7 @@
 
 [![npm](https://img.shields.io/npm/v/@open330/oac?label=npm&color=CB3837&logo=npm)](https://www.npmjs.com/package/@open330/oac)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D24-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-3178C6?logo=typescript&logoColor=white)](https://typescriptlang.org/)
 
 [Getting Started](#-getting-started) · [How It Works](#-how-it-works) · [Commands](#commands) · [Configuration](#configuration) · [Architecture](#architecture) · [Contributing](#contributing)
@@ -93,7 +93,7 @@ npx @open330/oac run --repo facebook/react --tokens unlimited
 
 ### Prerequisites
 
-- **Node.js** >= 24 (see `engines` in package.json)
+- **Node.js** >= 20 (see `engines` in package.json)
 - **git** installed
 - At least one AI agent CLI: [Claude Code](https://claude.ai/code), [Codex](https://github.com/openai/codex), or [OpenCode](https://github.com/opencode-ai/opencode)
 

package/dist/{chunk-YWIB3TRI.js → chunk-6A37SKAJ.js}

@@ -38,8 +38,21 @@ function createMemoryMonitor(options) {
   };
 }
 
+// src/core/utils.ts
+function truncate(value, maxLength, ellipsis = "\u2026") {
+  if (value.length <= maxLength) {
+    return value;
+  }
+  return `${value.slice(0, Math.max(0, maxLength - ellipsis.length))}${ellipsis}`;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
 export {
   getMemorySnapshot,
-  createMemoryMonitor
+  createMemoryMonitor,
+  truncate,
+  isRecord
 };
-//# sourceMappingURL=chunk-YWIB3TRI.js.map
+//# sourceMappingURL=chunk-6A37SKAJ.js.map

package/dist/chunk-6A37SKAJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/memory.ts","../src/core/utils.ts"],"sourcesContent":["/**\n * Memory pressure monitoring utilities.\n *\n * Provides lightweight heap-usage checks that callers can use to\n * throttle work when the process is approaching memory limits.\n */\n\n/** Default threshold: pause work when heap usage exceeds 85% of the limit. */\nconst DEFAULT_PRESSURE_RATIO = 0.85;\n\nexport interface MemorySnapshot {\n  heapUsedMB: number;\n  heapTotalMB: number;\n  rssUsedMB: number;\n  /** Ratio of heapUsed / heapTotal (0–1). */\n  heapPressure: number;\n  /** True when heapPressure exceeds the configured threshold. */\n  isUnderPressure: boolean;\n}\n\n/**\n * Take a snapshot of current memory usage.\n *\n * @param pressureRatio - Threshold ratio (0–1) above which `isUnderPressure`\n *   is set to `true`. Defaults to 0.85.\n */\nexport function getMemorySnapshot(pressureRatio = DEFAULT_PRESSURE_RATIO): MemorySnapshot {\n  const mem = process.memoryUsage();\n  const heapUsedMB = mem.heapUsed / 1_048_576;\n  const heapTotalMB = mem.heapTotal / 1_048_576;\n  const rssUsedMB = mem.rss / 1_048_576;\n  const heapPressure = mem.heapTotal > 0 ? mem.heapUsed / mem.heapTotal : 0;\n\n  return {\n    heapUsedMB: Math.round(heapUsedMB * 10) / 10,\n    heapTotalMB: Math.round(heapTotalMB * 10) / 10,\n    rssUsedMB: Math.round(rssUsedMB * 10) / 10,\n    heapPressure: Math.round(heapPressure * 1000) / 1000,\n    isUnderPressure: heapPressure >= pressureRatio,\n  };\n}\n\n/**\n * Creates a monitor that periodically checks memory pressure and calls\n * `onPressure` when the threshold is exceeded.  The monitor can be used\n * to pause a PQueue or reduce concurrency under load.\n *\n * Returns a `stop` function to clear the interval.\n */\nexport function createMemoryMonitor(options: {\n  /** Polling interval in milliseconds (default: 5 000). */\n  intervalMs?: number;\n  /** Heap pressure ratio threshold (default: 0.85). */\n  pressureRatio?: number;\n  /** Called when heap pressure exceeds the threshold. */\n  onPressure: (snapshot: MemorySnapshot) => void;\n  /** Called when heap pressure drops back below the threshold. */\n  onRelief?: (snapshot: MemorySnapshot) => void;\n}): { stop: () => void } {\n  const intervalMs = options.intervalMs ?? 5_000;\n  const pressureRatio = options.pressureRatio ?? DEFAULT_PRESSURE_RATIO;\n  let wasPressured = false;\n\n  const timer = setInterval(() => {\n    const snapshot = getMemorySnapshot(pressureRatio);\n\n    if (snapshot.isUnderPressure && !wasPressured) {\n      wasPressured = true;\n      options.onPressure(snapshot);\n    } else if (!snapshot.isUnderPressure && wasPressured) {\n      wasPressured = false;\n      options.onRelief?.(snapshot);\n    }\n  }, intervalMs);\n\n  // Unref so this doesn't keep the process alive\n  if (typeof timer === \"object\" && \"unref\" in timer) {\n    timer.unref();\n  }\n\n  return {\n    stop() {\n      clearInterval(timer);\n    },\n  };\n}\n\n","/**\n * Shared utility functions used across the codebase.\n */\n\n/**\n * Truncate a string to `maxLength`, appending an ellipsis when trimmed.\n * Defaults to the unicode ellipsis `\"…\"` (1 char).  Pass `\"...\"` for the\n * three-dot ASCII variant.\n */\nexport function truncate(\n  value: string,\n  maxLength: number,\n  ellipsis = \"…\",\n): string {\n  if (value.length <= maxLength) {\n    return value;\n  }\n  return `${value.slice(0, Math.max(0, maxLength - ellipsis.length))}${ellipsis}`;\n}\n\n/**\n * Type guard: returns `true` when `value` is a non-null object\n * (i.e.\\ a `Record<string, unknown>`).\n */\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n\n"],"mappings":";AAQA,IAAM,yBAAyB;AAkBxB,SAAS,kBAAkB,gBAAgB,wBAAwC;AACxF,QAAM,MAAM,QAAQ,YAAY;AAChC,QAAM,aAAa,IAAI,WAAW;AAClC,QAAM,cAAc,IAAI,YAAY;AACpC,QAAM,YAAY,IAAI,MAAM;AAC5B,QAAM,eAAe,IAAI,YAAY,IAAI,IAAI,WAAW,IAAI,YAAY;AAExE,SAAO;AAAA,IACL,YAAY,KAAK,MAAM,aAAa,EAAE,IAAI;AAAA,IAC1C,aAAa,KAAK,MAAM,cAAc,EAAE,IAAI;AAAA,IAC5C,WAAW,KAAK,MAAM,YAAY,EAAE,IAAI;AAAA,IACxC,cAAc,KAAK,MAAM,eAAe,GAAI,IAAI;AAAA,IAChD,iBAAiB,gBAAgB;AAAA,EACnC;AACF;AASO,SAAS,oBAAoB,SASX;AACvB,QAAM,aAAa,QAAQ,cAAc;AACzC,QAAM,gBAAgB,QAAQ,iBAAiB;AAC/C,MAAI,eAAe;AAEnB,QAAM,QAAQ,YAAY,MAAM;AAC9B,UAAM,WAAW,kBAAkB,aAAa;AAEhD,QAAI,SAAS,mBAAmB,CAAC,cAAc;AAC7C,qBAAe;AACf,cAAQ,WAAW,QAAQ;AAAA,IAC7B,WAAW,CAAC,SAAS,mBAAmB,cAAc;AACpD,qBAAe;AACf,cAAQ,WAAW,QAAQ;AAAA,IAC7B;AAAA,EACF,GAAG,UAAU;AAGb,MAAI,OAAO,UAAU,YAAY,WAAW,OAAO;AACjD,UAAM,MAAM;AAAA,EACd;AAEA,SAAO;AAAA,IACL,OAAO;AACL,oBAAc,KAAK;AAAA,IACrB;AAAA,EACF;AACF;;;AC5EO,SAAS,SACd,OACA,WACA,WAAW,UACH;AACR,MAAI,MAAM,UAAU,WAAW;AAC7B,WAAO;AAAA,EACT;AACA,SAAO,GAAG,MAAM,MAAM,GAAG,KAAK,IAAI,GAAG,YAAY,SAAS,MAAM,CAAC,CAAC,GAAG,QAAQ;AAC/E;AAMO,SAAS,SAAS,OAAkD;AACzE,SAAO,OAAO,UAAU,YAAY,UAAU;AAChD;","names":[]}

package/dist/{chunk-ZRYAHZQJ.js → chunk-7C7SC4TZ.js}

@@ -355,4 +355,4 @@ export {
   createEventBus,
   UNLIMITED_BUDGET
 };
-//# sourceMappingURL=chunk-ZRYAHZQJ.js.map
+//# sourceMappingURL=chunk-7C7SC4TZ.js.map