@almightygpt/core 0.2.0

package/src/context/manifest.ts

@@ -0,0 +1,94 @@
+/**
+ * Build the context-manifest.json that accompanies every run.
+ *
+ * The manifest is the auditable record of what was sent to the model:
+ *   - which files were included,
+ *   - which were skipped and why,
+ *   - file content hashes (so re-runs against unchanged files can be
+ *     short-circuited later — caching is task #14+ scope but the hashes are
+ *     captured now to keep the format stable),
+ *   - redaction counts so the user can see how many secrets were filtered.
+ *
+ * For MVP 1 diff review, the "files" are the files in the diff; the manifest
+ * does not currently re-read full file contents (that's task #13 expansion
+ * for path review). Token estimates are 4-char heuristics.
+ */
+
+import { writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import type { RedactionMatch } from "./redact.js";
+
+export interface ManifestFile {
+  path: string;
+  bytes: number;
+  sha256: string;
+  /** Why this file was excluded, if so. Undefined means included. */
+  skippedReason?: string;
+}
+
+export interface ContextManifest {
+  generatedAt: string;
+  inputSource: "diff" | "diff-range" | "path" | "requirement-file" | "ask";
+  filesIncluded: ManifestFile[];
+  filesSkipped: ManifestFile[];
+  redaction: {
+    enabled: boolean;
+    totalCount: number;
+    byKind: RedactionMatch[];
+  };
+  totalTokensEstimate: number;
+  diffBytes: number;
+}
+
+export interface BuildManifestOptions {
+  inputSource: ContextManifest["inputSource"];
+  filesIncluded: { path: string; bytes: number; content?: string }[];
+  filesSkipped: { path: string; bytes: number; skippedReason: string }[];
+  diffText: string;
+  redaction: { enabled: boolean; totalCount: number; byKind: RedactionMatch[] };
+}
+
+export function buildContextManifest(
+  opts: BuildManifestOptions,
+): ContextManifest {
+  const included: ManifestFile[] = opts.filesIncluded.map((f) => ({
+    path: f.path,
+    bytes: f.bytes,
+    sha256: f.content ? sha256(f.content) : "",
+  }));
+
+  const skipped: ManifestFile[] = opts.filesSkipped.map((f) => ({
+    path: f.path,
+    bytes: f.bytes,
+    sha256: "",
+    skippedReason: f.skippedReason,
+  }));
+
+  return {
+    generatedAt: new Date().toISOString(),
+    inputSource: opts.inputSource,
+    filesIncluded: included,
+    filesSkipped: skipped,
+    redaction: opts.redaction,
+    totalTokensEstimate: Math.ceil(opts.diffText.length / 4),
+    diffBytes: opts.diffText.length,
+  };
+}
+
+export async function writeContextManifest(
+  runFolderAbsPath: string,
+  manifest: ContextManifest,
+): Promise<string> {
+  const relPath = "context-manifest.json";
+  await writeFile(
+    join(runFolderAbsPath, relPath),
+    JSON.stringify(manifest, null, 2) + "\n",
+    "utf8",
+  );
+  return relPath;
+}
+
+function sha256(s: string): string {
+  return createHash("sha256").update(s).digest("hex");
+}

package/src/context/redact.ts

@@ -0,0 +1,93 @@
+/**
+ * Secret redaction.
+ *
+ * Runs a battery of regex patterns over text and replaces matches with a
+ * `[REDACTED:<kind>:<short-hash>]` placeholder. The hash lets the user
+ * confirm two redactions refer to the same secret (useful for audit) without
+ * leaking the value.
+ *
+ * This is a defense-in-depth measure. The first line of defense is the
+ * `.almightyignore` file which prevents secret-bearing files from being
+ * included in the first place. Redaction catches what slips through.
+ *
+ * Patterns are deliberately conservative — false positives are better than
+ * leaking real secrets. Users can disable redaction via config if needed.
+ */
+
+import { createHash } from "node:crypto";
+
+export interface RedactionMatch {
+  kind: string;
+  count: number;
+}
+
+export interface RedactionResult {
+  text: string;
+  redactions: RedactionMatch[];
+  totalCount: number;
+}
+
+interface Pattern {
+  kind: string;
+  regex: RegExp;
+}
+
+const PATTERNS: Pattern[] = [
+  // OpenAI keys
+  { kind: "openai_key", regex: /\bsk-[A-Za-z0-9]{20,}\b/g },
+  // GitHub PATs (classic + fine-grained)
+  { kind: "github_pat", regex: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g },
+  // Anthropic keys
+  { kind: "anthropic_key", regex: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g },
+  // Generic AWS access key id
+  { kind: "aws_access_key_id", regex: /\b(AKIA|ASIA)[A-Z0-9]{16}\b/g },
+  // Slack bot token
+  { kind: "slack_token", regex: /\bxox[abp]-[A-Za-z0-9-]{20,}\b/g },
+  // Generic JWT (3 base64url segments)
+  {
+    kind: "jwt",
+    regex: /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g,
+  },
+  // PEM private key block
+  {
+    kind: "pem_private_key",
+    regex:
+      /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----[\s\S]+?-----END (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/g,
+  },
+  // Bearer tokens in headers (catches "Authorization: Bearer <token>")
+  {
+    kind: "bearer_token",
+    regex: /\b[Bb]earer\s+[A-Za-z0-9_\-.~+/=]{16,}/g,
+  },
+  // Generic high-entropy key= or password= assignments in code / yaml / env
+  // (catches things like API_KEY="ABCDEFG..." or password: '...')
+  {
+    kind: "assignment_secret",
+    regex:
+      /\b(?:api[_-]?key|secret|password|token|access[_-]?key)\s*[:=]\s*["']?([A-Za-z0-9+/=_\-.]{20,})["']?/gi,
+  },
+];
+
+export function redactSecrets(text: string): RedactionResult {
+  const counts = new Map<string, number>();
+  let out = text;
+
+  for (const { kind, regex } of PATTERNS) {
+    out = out.replace(regex, (match) => {
+      const hash = shortHash(match);
+      counts.set(kind, (counts.get(kind) ?? 0) + 1);
+      return `[REDACTED:${kind}:${hash}]`;
+    });
+  }
+
+  const redactions: RedactionMatch[] = [...counts.entries()].map(
+    ([kind, count]) => ({ kind, count }),
+  );
+  const totalCount = redactions.reduce((sum, r) => sum + r.count, 0);
+
+  return { text: out, redactions, totalCount };
+}
+
+function shortHash(s: string): string {
+  return createHash("sha256").update(s).digest("hex").slice(0, 8);
+}

package/src/git/status.ts

@@ -0,0 +1,108 @@
+/**
+ * Git status safety check.
+ *
+ * Before any agent (or `almightygpt init`) writes a file that already exists,
+ * we check whether the target has uncommitted changes. If it does, refuse to
+ * overwrite — the user has work in progress that we should not silently
+ * destroy.
+ *
+ * This is the same rule the project's own CLAUDE.md enforces for the team,
+ * and it ships in the default Convention Pack rules so every adopter gets
+ * the same protection.
+ */
+
+import { execa } from "execa";
+
+export interface GitStatusCheck {
+  /** True if the file is tracked but modified, staged, or is an untracked path. */
+  dirty: boolean;
+  /** True if the target path is not inside a git repository. */
+  notInGitRepo?: boolean;
+  /** Raw git porcelain output if dirty, useful for surfacing context to the user. */
+  porcelain?: string;
+}
+
+/**
+ * Check whether a path has uncommitted changes in its containing git repo.
+ *
+ * - Returns `{ dirty: false, notInGitRepo: true }` if `repoRoot` is not a git
+ *   working tree. Callers may treat this as "no protection available; proceed".
+ * - Returns `{ dirty: false }` if the path is clean (or does not exist yet).
+ * - Returns `{ dirty: true, porcelain }` if `git status --short` reports
+ *   anything for the path.
+ *
+ * The relative path is normalized to use forward slashes (git's preferred form).
+ */
+export async function checkGitStatus(
+  repoRoot: string,
+  relativePath: string,
+): Promise<GitStatusCheck> {
+  const normalized = relativePath.replace(/\\/g, "/");
+
+  try {
+    const { stdout } = await execa(
+      "git",
+      ["status", "--short", "--", normalized],
+      {
+        cwd: repoRoot,
+        reject: false,
+        stripFinalNewline: true,
+      },
+    );
+
+    if (stdout.trim().length === 0) {
+      return { dirty: false };
+    }
+
+    return { dirty: true, porcelain: stdout };
+  } catch (err) {
+    // execa throws if git is missing. Surface as not-in-repo so callers can
+    // proceed cautiously rather than crash.
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("ENOENT")) {
+      return { dirty: false, notInGitRepo: true };
+    }
+    // "not a git repository" returns non-zero but we used reject:false above,
+    // so this branch is rare. Still, treat unknown errors as no-protection.
+    return { dirty: false, notInGitRepo: true };
+  }
+}
+
+/**
+ * Assert that a path is safe to overwrite. Throws if dirty unless `force` is set.
+ *
+ * Intended call sites:
+ *   - `almightygpt init` when a convention file already exists.
+ *   - Reviewer adapters before writing `docs/<reviewer>-reviews/<topic>.md`.
+ *   - Any future agent that writes Markdown into a tracked path.
+ */
+export async function assertSafeToWrite(
+  repoRoot: string,
+  relativePath: string,
+  force = false,
+): Promise<void> {
+  if (force) return;
+
+  const status = await checkGitStatus(repoRoot, relativePath);
+  if (!status.dirty) return;
+
+  const lines = (status.porcelain ?? "").split("\n").filter(Boolean);
+  const detail = lines.map((l) => `    ${l}`).join("\n");
+  throw new GitStatusDirtyError(
+    `Refusing to overwrite ${relativePath} — it has uncommitted changes:\n${detail}\n\n` +
+      `Commit or stash the changes, or re-run with --force to override.`,
+    relativePath,
+    status.porcelain ?? "",
+  );
+}
+
+export class GitStatusDirtyError extends Error {
+  override readonly name = "GitStatusDirtyError";
+  constructor(
+    message: string,
+    public readonly path: string,
+    public readonly porcelain: string,
+  ) {
+    super(message);
+  }
+}

package/src/index.ts

@@ -0,0 +1,127 @@
+/**
+ * @almightygpt/core
+ *
+ * Core orchestrator, adapters, config, runs, and review logic.
+ * MVP 1 status:
+ *   - git/        ✅ task #8
+ *   - templates/  ✅ task #7 installer (used by init, task #6)
+ *   - config/     ✅ task #11 schema + loader
+ *   - adapters/   ✅ task #9 mock + task #10 OpenAI
+ *   - context/    ✅ task #13 manifest + secret redaction
+ *   - runs/       ✅ task #12 dual-artifact folder + run.json
+ *   - review/     ✅ task #11 diff review pipeline (with #12/#13/#14 wiring)
+ *   - budget/     ✅ task #14 BudgetTracker + BudgetExceededError
+ */
+
+export const VERSION = "0.2.0";
+
+// Git safety primitives
+export {
+  checkGitStatus,
+  assertSafeToWrite,
+  GitStatusDirtyError,
+  type GitStatusCheck,
+} from "./git/status.js";
+
+// Template installer
+export {
+  installTemplate,
+  hasExistingConfig,
+  type InstallOptions,
+  type InstallResult,
+} from "./templates/install.js";
+
+// Config
+export { loadConfig, ConfigError } from "./config/load.js";
+export {
+  ConfigSchema,
+  AgentConfigSchema,
+  AgentRoleSchema,
+  type Config,
+  type AgentConfig,
+} from "./config/schema.js";
+
+// Adapters
+export {
+  AdapterError,
+  MockAdapter,
+  OpenAIAdapter,
+  ClaudeAdapter,
+  GeminiAdapter,
+  type Adapter,
+  type AdapterInput,
+  type AdapterOutput,
+  type AgentRole,
+  type OpenAIAdapterOptions,
+  type ClaudeAdapterOptions,
+  type GeminiAdapterOptions,
+} from "./adapters/index.js";
+
+// Context / redaction
+export { redactSecrets, type RedactionResult, type RedactionMatch } from "./context/redact.js";
+export {
+  buildContextManifest,
+  writeContextManifest,
+  type ContextManifest,
+  type ManifestFile,
+} from "./context/manifest.js";
+
+// Runs
+export {
+  createRunFolder,
+  writeRunMetadata,
+  writeRunInput,
+  writeAgentOutput,
+  collectGitContext,
+  type CreatedRunFolder,
+} from "./runs/folder.js";
+export type {
+  RunMetadata,
+  RunStatus,
+  RunType,
+  AgentMetrics,
+  HumanDecision,
+  DecisionStatus,
+} from "./runs/types.js";
+export {
+  listRuns,
+  findRunById,
+  findLatestRun,
+  formatDuration,
+  type RunSummary,
+  type ListRunsResult,
+  type ListRunsOptions,
+} from "./runs/list.js";
+export {
+  recordDecision,
+  type RecordDecisionOptions,
+  type RecordDecisionResult,
+} from "./runs/decide.js";
+
+// Review pipeline
+export {
+  runDiffReview,
+  type DiffReviewOptions,
+  type DiffReviewResult,
+} from "./review/run-diff-review.js";
+export {
+  runWorkerReviewerReview,
+  type WorkerReviewerOptions,
+  type WorkerReviewerResult,
+} from "./review/run-worker-reviewer.js";
+export { collectGitDiff, type DiffOptions, type DiffResult } from "./review/diff.js";
+export {
+  writeHumanReviewFile,
+  ReviewFileExistsError,
+  type WriteReviewFileOptions,
+} from "./review/write.js";
+export {
+  BudgetTracker,
+  BudgetExceededError,
+  type BudgetCaps,
+} from "./review/budget.js";
+export type {
+  ReviewEvent,
+  ReviewEventHandler,
+  AgentRoleInRun,
+} from "./review/events.js";

package/src/review/budget.ts

@@ -0,0 +1,116 @@
+/**
+ * Budget tracking and enforcement for review runs.
+ *
+ * Two checks:
+ *   - Pre-flight: estimate cost from prompt size + max output tokens, abort
+ *     if estimate already exceeds maxCostPerRunUsd.
+ *   - Post-call: aggregate actual cost across all adapter calls in the run,
+ *     abort if cap is breached.
+ *
+ * Estimates use the same PRICING_USD_PER_1M table as the OpenAI adapter.
+ * For non-OpenAI providers we fall back to a conservative default.
+ */
+
+const DEFAULT_INPUT_USD_PER_1M = 3.0;
+const DEFAULT_OUTPUT_USD_PER_1M = 15.0;
+
+const KNOWN_PRICING: Record<string, { input: number; output: number }> = {
+  "gpt-4o": { input: 2.5, output: 10.0 },
+  "gpt-4o-mini": { input: 0.15, output: 0.6 },
+  "gpt-4-turbo": { input: 10.0, output: 30.0 },
+  "gpt-3.5-turbo": { input: 0.5, output: 1.5 },
+  "claude-3-5-sonnet": { input: 3.0, output: 15.0 },
+  "claude-3-5-haiku": { input: 0.8, output: 4.0 },
+  "claude-3-opus": { input: 15.0, output: 75.0 },
+  "gemini-2.5-pro": { input: 1.25, output: 10.0 },
+  "gemini-2.5-flash": { input: 0.3, output: 2.5 },
+  "gemini-2.0-flash": { input: 0.1, output: 0.4 },
+  "gemini-1.5-pro": { input: 1.25, output: 5.0 },
+  "gemini-1.5-flash": { input: 0.075, output: 0.3 },
+};
+
+export class BudgetExceededError extends Error {
+  override readonly name = "BudgetExceededError";
+  constructor(
+    message: string,
+    public readonly stage: "pre-flight" | "post-call",
+    public readonly capUsd: number,
+    public readonly actualUsd: number,
+  ) {
+    super(message);
+  }
+}
+
+export interface BudgetCaps {
+  maxCostPerRunUsd: number;
+  maxTokensPerRun: number;
+}
+
+export class BudgetTracker {
+  private totalCostUsd = 0;
+  private totalTokens = 0;
+
+  constructor(private readonly caps: BudgetCaps) {}
+
+  /** Conservative pre-flight check before calling an adapter. */
+  preflightCheck(opts: {
+    model: string;
+    estimatedTokensIn: number;
+    maxOutputTokens: number;
+  }): void {
+    const rates = lookupPricing(opts.model);
+    const estimatedCost =
+      (opts.estimatedTokensIn / 1_000_000) * rates.input +
+      (opts.maxOutputTokens / 1_000_000) * rates.output;
+    const projected = this.totalCostUsd + estimatedCost;
+
+    if (projected > this.caps.maxCostPerRunUsd) {
+      throw new BudgetExceededError(
+        `Pre-flight cost estimate $${projected.toFixed(4)} exceeds budget cap ` +
+          `$${this.caps.maxCostPerRunUsd.toFixed(4)}. Lower max_output_tokens, ` +
+          `shrink the diff, or raise budget.maxCostPerRunUsd in .almightygpt/config.yaml.`,
+        "pre-flight",
+        this.caps.maxCostPerRunUsd,
+        projected,
+      );
+    }
+  }
+
+  /** Record actual usage after a successful adapter call; trip the cap if exceeded. */
+  record(opts: { tokensIn: number; tokensOut: number; costUsd: number }): void {
+    this.totalCostUsd += opts.costUsd;
+    this.totalTokens += opts.tokensIn + opts.tokensOut;
+
+    if (this.totalCostUsd > this.caps.maxCostPerRunUsd) {
+      throw new BudgetExceededError(
+        `Run cost $${this.totalCostUsd.toFixed(4)} exceeded cap ` +
+          `$${this.caps.maxCostPerRunUsd.toFixed(4)} after adapter call.`,
+        "post-call",
+        this.caps.maxCostPerRunUsd,
+        this.totalCostUsd,
+      );
+    }
+    if (this.totalTokens > this.caps.maxTokensPerRun) {
+      throw new BudgetExceededError(
+        `Run tokens ${this.totalTokens} exceeded cap ${this.caps.maxTokensPerRun}.`,
+        "post-call",
+        this.caps.maxTokensPerRun,
+        this.totalTokens,
+      );
+    }
+  }
+
+  get totals(): { costUsd: number; tokens: number } {
+    return { costUsd: this.totalCostUsd, tokens: this.totalTokens };
+  }
+}
+
+function lookupPricing(model: string): { input: number; output: number } {
+  const key = Object.keys(KNOWN_PRICING).find((k) =>
+    model.toLowerCase().startsWith(k),
+  );
+  if (!key) {
+    return { input: DEFAULT_INPUT_USD_PER_1M, output: DEFAULT_OUTPUT_USD_PER_1M };
+  }
+  return KNOWN_PRICING[key]!;
+}

package/src/review/diff.ts

@@ -0,0 +1,85 @@
+/**
+ * Collect a git diff for review.
+ *
+ * Default: uncommitted working tree changes (staged + unstaged).
+ * Optional range: e.g. "HEAD~1..HEAD" to review the last commit.
+ */
+
+import { execa } from "execa";
+
+export interface DiffResult {
+  diff: string;
+  /** Files touched in the diff (relative paths). */
+  files: string[];
+  /** True if the working tree had no changes and no range was supplied. */
+  empty: boolean;
+}
+
+export interface DiffOptions {
+  /** Optional git range like "HEAD~3..HEAD". If omitted, uncommitted changes. */
+  range?: string;
+  /** Hard cap on diff size to avoid blowing the context window. Default 200 KB. */
+  maxBytes?: number;
+}
+
+export async function collectGitDiff(
+  repoRoot: string,
+  opts: DiffOptions = {},
+): Promise<DiffResult> {
+  const maxBytes = opts.maxBytes ?? 200_000;
+  const args = ["diff", "--no-color"];
+  if (opts.range) {
+    args.push(opts.range);
+  } else {
+    // Include staged + unstaged + untracked-vs-HEAD.
+    args.push("HEAD");
+  }
+
+  const { stdout, exitCode } = await execa("git", args, {
+    cwd: repoRoot,
+    reject: false,
+    stripFinalNewline: false,
+    maxBuffer: maxBytes * 2,
+  });
+
+  // exitCode is 0 on success, 1 on dirty diff in some git modes; treat both as ok.
+  if (exitCode !== 0 && exitCode !== 1) {
+    throw new Error(
+      `git diff failed with exit ${exitCode}. Args: ${args.join(" ")}`,
+    );
+  }
+
+  const truncated =
+    stdout.length > maxBytes
+      ? stdout.slice(0, maxBytes) +
+        `\n\n[…truncated — diff exceeded ${maxBytes} bytes]\n`
+      : stdout;
+
+  const files = await collectFilesInDiff(repoRoot, opts.range);
+
+  return {
+    diff: truncated,
+    files,
+    empty: truncated.trim().length === 0,
+  };
+}
+
+async function collectFilesInDiff(
+  repoRoot: string,
+  range?: string,
+): Promise<string[]> {
+  const args = ["diff", "--name-only"];
+  if (range) args.push(range);
+  else args.push("HEAD");
+
+  const { stdout } = await execa("git", args, {
+    cwd: repoRoot,
+    reject: false,
+    stripFinalNewline: true,
+  });
+
+  return stdout
+    .split("\n")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}

package/src/review/events.ts

@@ -0,0 +1,86 @@
+/**
+ * Review run event stream.
+ *
+ * Emitted by review pipelines via an optional `onEvent` callback. The CLI
+ * uses these events to drive both human progress output and the structured
+ * --json stream that future VS Code / dashboard surfaces will consume.
+ *
+ * Each event is a discriminated union — the `type` field is the
+ * discriminator. Tooling should be tolerant of unknown event types so we
+ * can add new ones without breaking existing consumers.
+ */
+
+export type AgentRoleInRun = "worker" | "reviewer" | "judge";
+
+export type ReviewEvent =
+  | RunStartedEvent
+  | AgentStartedEvent
+  | AgentCompletedEvent
+  | RedactionCompleteEvent
+  | ReviewWrittenEvent
+  | RunCompletedEvent
+  | RunFailedEvent;
+
+export interface RunStartedEvent {
+  type: "run_started";
+  runId: string;
+  runType: string;
+  topic: string;
+  reviewsDir: string;
+  runFolder: string;
+}
+
+export interface AgentStartedEvent {
+  type: "agent_started";
+  role: AgentRoleInRun;
+  agent: string;
+  provider: string;
+}
+
+export interface AgentCompletedEvent {
+  type: "agent_completed";
+  role: AgentRoleInRun;
+  agent: string;
+  provider: string;
+  model: string;
+  outputPath: string;
+  tokensIn: number;
+  tokensOut: number;
+  costUsd: number;
+  latencyMs: number;
+}
+
+export interface RedactionCompleteEvent {
+  type: "redaction_complete";
+  totalCount: number;
+  byKind: { kind: string; count: number }[];
+}
+
+export interface ReviewWrittenEvent {
+  type: "review_written";
+  reviewPath: string;
+  bytes: number;
+  shallowWarning?: string;
+}
+
+export interface RunCompletedEvent {
+  type: "run_completed";
+  runId: string;
+  reviewPath: string;
+  runFolder: string;
+  totals: {
+    tokensIn: number;
+    tokensOut: number;
+    costUsd: number;
+    latencyMs: number;
+  };
+}
+
+export interface RunFailedEvent {
+  type: "run_failed";
+  runId: string;
+  error: { name: string; message: string };
+}
+
+/** Callback signature for receiving the event stream. */
+export type ReviewEventHandler = (event: ReviewEvent) => void;