pullfrog 0.0.197 → 0.0.198

package/dist/utils/log.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Logging utilities that work well in both local and GitHub Actions environments
+ */
+import type { AgentUsage } from "../agents/shared.ts";
+/** run `fn` with every log line prefixed by `prefix` (e.g. "[task-label]") in magenta */
+export declare function withLogPrefix<T>(prefix: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Start a collapsed group (GitHub Actions) or regular group (local)
+ */
+declare function startGroup(name: string): void;
+/**
+ * End a collapsed group
+ */
+declare function endGroup(): void;
+/**
+ * Run a callback within a collapsed group
+ */
+declare function group(name: string, fn: () => void): void;
+/**
+ * Print a formatted box with text
+ */
+declare function box(text: string, options?: {
+    title?: string;
+    maxWidth?: number;
+}): void;
+/**
+ * Overwrite the job summary with the given text.
+ * Skips if:
+ * - Not in GitHub Actions
+ * - Running inside Docker (CI tests inherit host env vars but can't access host paths)
+ * - GITHUB_STEP_SUMMARY not set
+ */
+export declare function writeSummary(text: string): Promise<void>;
+/**
+ * Print a formatted table using the table package
+ */
+declare function printTable(rows: Array<Array<{
+    data: string;
+    header?: boolean;
+} | string>>, options?: {
+    title?: string;
+}): void;
+/**
+ * Print a separator line
+ */
+declare function separator(length?: number): void;
+/**
+ * Main logging utility object - import this once and access all utilities
+ */
+export declare const log: {
+    /** Print info message */
+    info: (...args: unknown[]) => void;
+    /** Print a warning message. Use only for warnings that should be displayed in the job summary. */
+    warning: (...args: unknown[]) => void;
+    /** Print an error message. Use only for errors that should be displayed in the job summary. */
+    error: (...args: unknown[]) => void;
+    /** Print success message */
+    success: (...args: unknown[]) => void;
+    /** Print debug message (only when debug mode is enabled) */
+    debug: (...args: unknown[]) => void;
+    /** Print a formatted box with text */
+    box: typeof box;
+    /** Print a formatted table using the table package */
+    table: typeof printTable;
+    /** Print a separator line */
+    separator: typeof separator;
+    /** Start a collapsed group (GitHub Actions) or regular group (local) */
+    startGroup: typeof startGroup;
+    /** End a collapsed group */
+    endGroup: typeof endGroup;
+    /** Run a callback within a collapsed group */
+    group: typeof group;
+    /** Log tool call information to console with formatted output */
+    toolCall: ({ toolName, input }: {
+        toolName: string;
+        input: unknown;
+    }) => void;
+};
+/**
+ * Format a value as JSON, using compact format for simple values and pretty-printed for complex ones
+ */
+export declare function formatJsonValue(value: unknown): string;
+/**
+ * Format a multi-line string with proper indentation for tool call output
+ * First line has the label, subsequent lines are indented 4 spaces
+ */
+export declare function formatIndentedField(label: string, content: string): string;
+/**
+ * format aggregated usage data as a markdown table for the GitHub step summary
+ */
+export declare function formatUsageSummary(entries: AgentUsage[]): string;
+export {};

package/dist/utils/normalizeEnv.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Normalize environment variables to uppercase.
+ * This handles case-insensitive env var names (e.g., `anthropic_api_key` -> `ANTHROPIC_API_KEY`).
+ *
+ * If there are conflicts (same key with different capitalizations but different values),
+ * logs a warning and keeps the uppercase version.
+ *
+ * Also registers sensitive values as masks in GitHub Actions.
+ */
+export declare function normalizeEnv(): void;

package/dist/utils/payload.d.ts

@@ -0,0 +1,41 @@
+import type { PayloadEvent } from "../external.ts";
+import type { RepoSettings } from "./runContext.ts";
+export declare const JsonPayload: import("arktype/internal/variants/object.ts").ObjectType<{
+    "~pullfrog": true;
+    version: string;
+    prompt: string;
+    model?: string | undefined;
+    triggerer?: string | undefined;
+    eventInstructions?: string;
+    event?: object;
+    timeout?: string | undefined;
+    progressCommentId?: string | undefined;
+}, {}>;
+export declare const Inputs: import("arktype/internal/variants/object.ts").ObjectType<{
+    prompt: string;
+    model?: string | undefined;
+    timeout?: string | undefined;
+    push?: "disabled" | "enabled" | "restricted" | undefined;
+    shell?: "disabled" | "enabled" | "restricted" | undefined;
+    cwd?: string | undefined;
+    output_schema?: string | undefined;
+}, {}>;
+export type Inputs = typeof Inputs.infer;
+export type ResolvedPromptInput = string | typeof JsonPayload.infer;
+export declare function resolvePromptInput(): ResolvedPromptInput;
+export declare function resolvePayload(resolvedPromptInput: ResolvedPromptInput, repoSettings: RepoSettings): {
+    "~pullfrog": true;
+    version: string;
+    model: string | undefined;
+    prompt: string;
+    triggerer: string | undefined;
+    eventInstructions: string | undefined;
+    event: PayloadEvent;
+    timeout: string | undefined;
+    cwd: string | undefined;
+    progressCommentId: string | undefined;
+    push: import("../external.ts").PushPermission;
+    shell: import("../external.ts").ShellPermission;
+    proxyModel: string | undefined;
+};
+export type ResolvedPayload = ReturnType<typeof resolvePayload>;

package/dist/utils/providerErrors.d.ts

@@ -0,0 +1 @@
+export declare function detectProviderError(text: string): string | null;

package/dist/utils/rangeDiff.d.ts

@@ -0,0 +1,51 @@
+type ComputeIncrementalDiffParams = {
+    baseBranch: string;
+    beforeSha: string;
+    headSha: string;
+};
+/**
+ * computes the incremental diff between two versions of a PR using range-diff
+ * on virtual squash commits created via `git commit-tree`.
+ *
+ * each PR version is squashed into a single synthetic commit (merge-base → tip tree),
+ * then range-diff compares those two single-commit ranges. this:
+ * - isolates each version's net effect (base branch noise eliminated via per-version merge bases)
+ * - avoids commit-matching issues that raw range-diff has with rebases/squashes/reordering
+ * - creates only loose git objects, no branches or refs (unlike temp-branch squash approaches)
+ *
+ * unlike fetchAndFormatPrDiff/formatFilesWithLineNumbers, this output has no line numbers.
+ * range-diff compares *patches* (diffs-of-diffs), not file trees — its hunk headers are
+ * `@@ file.ts` breadcrumbs, not positional `@@ -X,Y +A,B @@` markers. reconstructing
+ * line numbers would require cross-referencing with the v2 diff or content-matching against
+ * file trees, both of which are fragile (duplicate lines, hunk boundary shifts after rebase).
+ * a structured interdiff approach (diff two parsed patches, compare only +/- keys via Myers)
+ * could approximate line numbers but loses semantic precision: range-diff understands patch
+ * structure natively (rename detection, hunk-aware matching, dual-prefix inner/outer changes),
+ * while flat key-sequence comparison can misalign duplicate lines and can't distinguish
+ * "new addition to the PR" from "existing code newly modified by the PR". range-diff is the
+ * right abstraction here — the incremental diff answers "how did the changeset evolve?",
+ * not "where in the file is this?", and forcing positional line numbers onto it would be
+ * semantically misleading.
+ *
+ * alternatives considered:
+ * - plain git diff (two-tree or three-dot): includes base branch changes, no PR isolation
+ * - patch-text diffing (interdiff / diff-of-diffs): fragile, hunk offset noise on rebase
+ * - range-diff on raw commit ranges: confused by commit reorganization across force-pushes
+ */
+export declare function computeIncrementalDiff(params: ComputeIncrementalDiffParams): string | null;
+/**
+ * transforms git range-diff output into a clean incremental diff.
+ *
+ * range-diff content lines have two prefix characters:
+ *   1st (outer): range-diff level — space (same in both), + (new only), - (old only)
+ *   2nd (inner): original diff level — space (context), + (added), - (removed)
+ *
+ * stripping the inner prefix produces a standard unified-diff-like output where
+ * +/- means "changed between PR versions" rather than "changed vs base branch".
+ *
+ * uses a streaming approach: a ring buffer of before-context lines is flushed when
+ * a change is hit, then afterCount lines of after-context are emitted directly.
+ * nearest preceding ## / @@ headers are force-included when outside the context window.
+ */
+export declare function postProcessRangeDiff(raw: string, contextLines?: number): string | null;
+export {};

package/dist/utils/retry.d.ts

@@ -0,0 +1,7 @@
+export type RetryOptions = {
+    maxAttempts?: number;
+    delayMs?: number;
+    shouldRetry?: (error: unknown) => boolean;
+    label?: string;
+};
+export declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/utils/reviewCleanup.d.ts

@@ -0,0 +1,14 @@
+import type { ToolContext } from "../mcp/server.ts";
+/**
+ * post-agent review lifecycle: runs after the agent exits (success or timeout).
+ *
+ * normally the agent handles new commits inline: create_pull_request_review
+ * detects HEAD movement and tells the agent to pull and review the delta.
+ * this dispatch is a safety net for cases where the agent couldn't handle
+ * it (timeout, error, etc).
+ *
+ * ordering matters: reportReviewNodeId marks this run "done" FIRST so push
+ * webhooks stop being suppressed by dedup. the HEAD check runs SECOND to
+ * catch any pushes that were suppressed while this run was in-flight.
+ */
+export declare function postReviewCleanup(ctx: ToolContext): Promise<void>;

package/dist/utils/run.d.ts

@@ -0,0 +1,9 @@
+import type { AgentResult } from "../agents/shared.ts";
+import type { MainResult } from "../main.ts";
+import type { ToolState } from "../mcp/server.ts";
+export interface HandleAgentResultParams {
+    result: AgentResult;
+    toolState: ToolState;
+    silent: boolean | undefined;
+}
+export declare function handleAgentResult(ctx: HandleAgentResultParams): Promise<MainResult>;

package/dist/utils/runContext.d.ts

@@ -0,0 +1,36 @@
+import type { PushPermission, ShellPermission } from "../external.ts";
+import type { RepoContext } from "./github.ts";
+export interface Mode {
+    id: string;
+    name: string;
+    description: string;
+    prompt: string;
+}
+export interface RepoSettings {
+    model: string | null;
+    modes: Mode[];
+    setupScript: string | null;
+    postCheckoutScript: string | null;
+    prepushScript: string | null;
+    push: PushPermission;
+    shell: ShellPermission;
+    prApproveEnabled: boolean;
+    modeInstructions: Record<string, string>;
+    learnings: string | null;
+}
+export interface RunContext {
+    settings: RepoSettings;
+    apiToken: string;
+    oss: boolean;
+    proxyModel?: string | undefined;
+    dbSecrets?: Record<string, string> | undefined;
+}
+/**
+ * fetch run context from Pullfrog API
+ * returns settings + API token for subsequent calls
+ * returns defaults if fetch fails
+ */
+export declare function fetchRunContext(params: {
+    token: string;
+    repoContext: RepoContext;
+}): Promise<RunContext>;

package/dist/utils/runContextData.d.ts

@@ -0,0 +1,24 @@
+import type { Octokit } from "@octokit/rest";
+import { type OctokitWithPlugins } from "./github.ts";
+import { type RepoSettings } from "./runContext.ts";
+export interface RunContextData {
+    repo: {
+        owner: string;
+        name: string;
+        data: Awaited<ReturnType<Octokit["repos"]["get"]>>["data"];
+    };
+    repoSettings: RepoSettings;
+    apiToken: string;
+    oss: boolean;
+    proxyModel?: string | undefined;
+    dbSecrets?: Record<string, string> | undefined;
+}
+interface ResolveRunContextDataParams {
+    octokit: OctokitWithPlugins;
+    token: string;
+}
+/**
+ * initialize run context data: parse context, fetch repo info and settings
+ */
+export declare function resolveRunContextData(params: ResolveRunContextDataParams): Promise<RunContextData>;
+export {};

package/dist/utils/secrets.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Secret detection and redaction utilities
+ * Redacts actual secret values rather than using pattern matching
+ */
+export declare const SENSITIVE_PATTERNS: RegExp[];
+export declare function isSensitiveEnvName(key: string): boolean;
+/** filter env vars, removing sensitive values (tokens, keys, secrets) */
+export declare function filterEnv(): Record<string, string>;
+export type EnvMode = "restricted" | "inherit" | Record<string, string>;
+/**
+ * resolve env mode to actual env object
+ * - "restricted" (default): filterEnv() to prevent secret leakage
+ * - "inherit": full process.env
+ * - object: custom env merged with restricted base
+ */
+export declare function resolveEnv(mode: EnvMode | undefined): Record<string, string | undefined>;
+export declare function redactSecrets(content: string, secrets?: string[]): string;

package/dist/utils/setup.d.ts

@@ -0,0 +1,33 @@
+import type { ShellPermission } from "../external.ts";
+import type { ToolState } from "../mcp/server.ts";
+import type { OctokitWithPlugins } from "./github.ts";
+export interface SetupOptions {
+    tempDir: string;
+}
+/**
+ * Create a shared temp directory for the action
+ */
+export declare function createTempDirectory(): string;
+/**
+ * Setup the test repository for running actions
+ */
+export declare function setupTestRepo(options: SetupOptions): void;
+export interface GitContext {
+    gitToken: string;
+    owner: string;
+    name: string;
+    octokit: OctokitWithPlugins;
+    toolState: ToolState;
+    shell: ShellPermission;
+    postCheckoutScript: string | null;
+}
+export type SetupGitParams = GitContext;
+/**
+ * setup git configuration and authentication for the repository.
+ * - configures git identity (user.email, user.name)
+ * - sets up authentication via gitToken (minimal contents:write)
+ *
+ * gitToken is a minimal-permission token (contents + workflows) used for git operations.
+ * it is assumed to be potentially exfiltratable, so it has limited scope.
+ */
+export declare function setupGit(params: SetupGitParams): Promise<void>;

package/dist/utils/shell.d.ts

@@ -0,0 +1,32 @@
+import { type EnvMode } from "./secrets.ts";
+interface ShellOptions {
+    cwd?: string;
+    encoding?: "utf-8" | "utf8" | "ascii" | "base64" | "base64url" | "hex" | "latin1" | "ucs-2" | "ucs2" | "utf16le";
+    log?: boolean;
+    /**
+     * env mode: "restricted" (default) filters secrets, "inherit" passes full env,
+     * or provide a custom env object (merged with restricted base)
+     */
+    env?: EnvMode;
+    onError?: (result: {
+        status: number;
+        stdout: string;
+        stderr: string;
+    }) => void;
+}
+/**
+ * Execute a shell command safely using spawnSync with argument arrays.
+ * Prevents shell injection by avoiding string interpolation in shell commands.
+ *
+ * SECURITY: by default, env vars are filtered to remove secrets (tokens, keys, passwords).
+ * this prevents malicious code (git hooks, npm scripts, etc.) from exfiltrating credentials.
+ * use env: "inherit" only when absolutely necessary.
+ *
+ * @param cmd - The command to execute
+ * @param args - Array of arguments to pass to the command
+ * @param options - Optional configuration (cwd, encoding, onError)
+ * @returns The trimmed stdout output
+ * @throws Error if command fails and no onError handler is provided
+ */
+export declare function $(cmd: string, args: string[], options?: ShellOptions): string;
+export {};

package/dist/utils/skills.d.ts

@@ -0,0 +1,6 @@
+export declare function addSkill(params: {
+    ref: string;
+    skill: string;
+    env: Record<string, string>;
+    agent: string;
+}): void;

package/dist/utils/subprocess.d.ts

@@ -0,0 +1,32 @@
+import { type ChildProcess } from "node:child_process";
+export type TrackChildOptions = {
+    child: ChildProcess;
+    killGroup?: boolean;
+};
+export type SignalHandler = (signal: NodeJS.Signals) => void;
+export declare function trackChild(options: TrackChildOptions): void;
+export declare function untrackChild(child: ChildProcess): void;
+export declare function setSignalHandler(handler: SignalHandler | null): void;
+export declare function killTrackedChildren(): void;
+export interface SpawnOptions {
+    cmd: string;
+    args: string[];
+    env?: NodeJS.ProcessEnv;
+    input?: string;
+    timeout?: number;
+    activityTimeout?: number;
+    cwd?: string;
+    stdio?: ("pipe" | "ignore" | "inherit")[];
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+}
+export interface SpawnResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    durationMs: number;
+}
+/**
+ * Spawn a subprocess with streaming callbacks and buffered results
+ */
+export declare function spawn(options: SpawnOptions): Promise<SpawnResult>;

package/dist/utils/time.d.ts

@@ -0,0 +1,14 @@
+/**
+ * time string parsing utilities for timeout configuration.
+ * supports formats like "10m", "1h30m", "10m12s", "30s".
+ */
+export declare const TIMEOUT_DISABLED = "none";
+/**
+ * parse a time string like "10m", "1h30m", "10m12s" into milliseconds.
+ * returns null if the string is not a valid time format.
+ */
+export declare function parseTimeString(input: string): number | null;
+/**
+ * check if a string is a valid time format.
+ */
+export declare function isValidTimeString(input: string): boolean;

package/dist/utils/timer.d.ts

@@ -0,0 +1,12 @@
+export declare class Timer {
+    private initialTimestamp;
+    private lastCheckpointTimestamp;
+    constructor();
+    checkpoint(name: string): void;
+}
+export declare class ThinkingTimer {
+    private readonly durationFormatter;
+    private lastToolResultTimestamp;
+    markToolResult(): void;
+    markToolCall(): void;
+}

package/dist/utils/todoTracking.d.ts

@@ -0,0 +1,14 @@
+export type TodoTracker = {
+    update: (input: unknown) => void;
+    flush: () => Promise<void>;
+    cancel: () => void;
+    /** resolves when any in-flight onUpdate call completes */
+    settled: () => Promise<void>;
+    /** mark in-progress items as completed (for final snapshot before review/progress post) */
+    completeInProgress: () => void;
+    renderCollapsible: () => string;
+    readonly enabled: boolean;
+    /** true after the tracker has successfully called onUpdate at least once */
+    readonly hasPublished: boolean;
+};
+export declare function createTodoTracker(onUpdate: (body: string) => Promise<void>): TodoTracker;

package/dist/utils/token.d.ts

@@ -0,0 +1,40 @@
+import type { PushPermission } from "../external.ts";
+import { acquireNewToken } from "./github.ts";
+export { acquireNewToken as acquireInstallationToken };
+export { revokeGitHubInstallationToken as revokeInstallationToken };
+/**
+ * get the job-scoped token from action input.
+ * this token has permissions defined by the workflow's permissions block.
+ *
+ * fallback order:
+ * 1. INPUT_TOKEN (from workflow `with: token:`)
+ * 2. GH_TOKEN (external token override)
+ * 3. GITHUB_TOKEN (pre-acquired in tests or from GHA env)
+ */
+export declare function getJobToken(): string;
+export type TokenRef = {
+    gitToken: string;
+    mcpToken: string;
+    [Symbol.asyncDispose]: () => Promise<void>;
+};
+type ResolveTokensParams = {
+    push: PushPermission;
+};
+/**
+ * resolve tokens for the action run.
+ *
+ * creates two separate tokens:
+ * - gitToken: contents permission based on `push` setting (assumed exfiltratable)
+ *   - push: enabled → contents:write (can push)
+ *   - push: disabled → contents:read (read-only)
+ * - mcpToken: full installation token - used for GitHub API calls in MCP tools (not exfiltratable)
+ *
+ * security-conscious users can pass their own token via GH_TOKEN env var or inputs.token.
+ */
+export declare function resolveTokens(params: ResolveTokensParams): Promise<TokenRef>;
+/**
+ * get the MCP token from memory.
+ * this is the token used for GitHub API calls in MCP tools.
+ */
+export declare function getGitHubInstallationToken(): string;
+export declare function revokeGitHubInstallationToken(token: string): Promise<void>;

package/dist/utils/version.d.ts

@@ -0,0 +1,2 @@
+import packageJson from "../package.json";
+export declare function getDevDependencyVersion(name: keyof typeof packageJson.devDependencies): string;

package/dist/utils/versioning.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @throws Error if the action can't process payload
+ * The compatibility is determined according to the COMPATIBILITY_POLICY above.
+ * @param payloadVersion the version of the payload
+ * @param actionVersion the version of the action (recipient)
+ */
+export declare function validateCompatibility(payloadVersion: string, actionVersion: string): void;

package/dist/utils/workflow.d.ts

@@ -0,0 +1,14 @@
+import type { OctokitWithPlugins } from "./github.ts";
+interface ResolveRunParams {
+    octokit: OctokitWithPlugins;
+}
+export interface ResolveRunResult {
+    runId: number | undefined;
+    jobId: string | undefined;
+}
+/**
+ * Resolve GitHub Actions workflow run context.
+ * Uses GITHUB_REPOSITORY and GITHUB_RUN_ID env vars.
+ */
+export declare function resolveRun(params: ResolveRunParams): Promise<ResolveRunResult>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pullfrog",
-  "version": "0.0.197",
+  "version": "0.0.198",
   "type": "module",
   "bin": {
     "pullfrog": "dist/cli.mjs",
@@ -13,7 +13,7 @@
   "scripts": {
     "test": "vitest",
     "typecheck": "tsc --noEmit",
-    "build": "node esbuild.config.js",
+    "build": "node esbuild.config.js && tsc -p tsconfig.exports.json",
     "check:entrypoints": "node scripts/check-entrypoint-imports.ts",
     "play": "node play.ts",
     "runtest": "node test/run.ts",
@@ -74,22 +74,19 @@
     "url": "https://github.com/pullfrog/pullfrog/issues"
   },
   "homepage": "https://github.com/pullfrog/pullfrog#readme",
-  "zshy": {
-    "exports": "./index.ts"
-  },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "@pullfrog/source": "./index.ts",
-      "types": "./dist/index.d.cts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "default": "./dist/index.js"
     },
     "./internal": {
       "@pullfrog/source": "./internal/index.ts",
-      "types": "./dist/internal.d.cts",
+      "types": "./dist/internal/index.d.ts",
       "import": "./dist/internal.js",
       "default": "./dist/internal.js"
     },