aiwcli 0.15.5 → 0.17.0

package/dist/lib/env-sanitizer.js

@@ -0,0 +1,46 @@
+/**
+ * Centralized env var management for REPL nesting detection.
+ * Replaces scattered cleanClaudeEnv(), UNSET_NESTING_SH, etc.
+ */
+/**
+ * Env vars set by REPL tools (Claude Code, Codex, Devin) that trigger
+ * nesting detection. Must be cleared when spawning a new REPL pane so
+ * the child tool starts fresh instead of refusing to launch.
+ */
+export const REPL_NESTING_VARS = [
+    'CLAUDECODE',
+    'CLAUDE_CODE_ENTRYPOINT',
+    'CLAUDE_SESSION_ID',
+    'CODEX_THREAD_ID',
+    'AIWCLI_INTERNAL_CALL',
+];
+/**
+ * Check whether the current process was invoked from a REPL tool.
+ * Must be called BEFORE clearProcessNestingVars().
+ */
+export function isCalledFromRepl() {
+    return REPL_NESTING_VARS.some((v) => Boolean(process.env[v]));
+}
+/**
+ * Clear REPL nesting vars from the current process environment.
+ * Call once at orchestrator startup so inline launches don't see them.
+ */
+export function clearProcessNestingVars() {
+    for (const v of REPL_NESTING_VARS) {
+        delete process.env[v];
+    }
+}
+/**
+ * Build a clean process env with nesting vars removed and optional extras merged.
+ * Used for createSession() spawn calls that inherit process.env.
+ */
+export function sanitizedProcessEnv(extraEnv) {
+    const env = {
+        ...process.env,
+        ...extraEnv,
+    };
+    for (const key of REPL_NESTING_VARS) {
+        delete env[key];
+    }
+    return env;
+}

package/dist/lib/errors.d.ts

@@ -111,16 +111,3 @@ export declare class ProcessSpawnError extends AiwError {
     readonly code?: string | undefined;
     constructor(message: string, code?: string | undefined);
 }
-/**
- * Format error message following AI Workflow CLI convention.
- * @param what - Description of what went wrong
- * @param howToFix - Actionable steps to fix the problem
- * @returns Formatted error message in format: "{what}. {howToFix}."
- * @example
- * formatErrorMessage(
- *   'AIW_DIR directory not found',
- *   'Set AIW_DIR env var or run "aiw setup"'
- * )
- * // Returns: "AIW_DIR directory not found. Set AIW_DIR env var or run \"aiw setup\"."
- */
-export declare function formatErrorMessage(what: string, howToFix: string): string;

package/dist/lib/errors.js

@@ -128,18 +128,3 @@ export class ProcessSpawnError extends AiwError {
         this.name = 'ProcessSpawnError';
     }
 }
-/**
- * Format error message following AI Workflow CLI convention.
- * @param what - Description of what went wrong
- * @param howToFix - Actionable steps to fix the problem
- * @returns Formatted error message in format: "{what}. {howToFix}."
- * @example
- * formatErrorMessage(
- *   'AIW_DIR directory not found',
- *   'Set AIW_DIR env var or run "aiw setup"'
- * )
- * // Returns: "AIW_DIR directory not found. Set AIW_DIR env var or run \"aiw setup\"."
- */
-export function formatErrorMessage(what, howToFix) {
-    return `${what}. ${howToFix}.`;
-}

package/dist/lib/git-exclude-manager.d.ts

@@ -7,7 +7,7 @@ export declare const AIW_EXCLUDE_ENTRIES: string[];
  * @param targetDir - Directory to resolve git dir for
  * @returns Absolute path to the git directory, or null if not a git repo
  */
-export declare function resolveGitDir(targetDir: string): Promise<string | null>;
+export declare function resolveGitDir(targetDir: string): Promise<null | string>;
 /**
  * Prune stale entries from the AIW Installation section in git exclude file.
  * Checks each entry against disk existence and removes entries whose paths don't exist.
@@ -15,7 +15,7 @@ export declare function resolveGitDir(targetDir: string): Promise<string | null>
  *
  * @param gitDir - Git directory (contains info/exclude)
  * @param targetDir - Project root directory (for disk-existence checks)
- * @returns True if any entries were pruned
+ * @returns True if unknown entries were pruned
  */
 export declare function pruneExcludeStaleEntries(gitDir: string, targetDir: string): Promise<boolean>;
 /**

package/dist/lib/git-exclude-manager.js

@@ -9,7 +9,7 @@ const execFileAsync = promisify(execFile);
  */
 const AIW_EXCLUDE_HEADER = '# AIW Installation';
 /** Standard exclude entries managed by AIW */
-export const AIW_EXCLUDE_ENTRIES = ['.aiwcli', '_output', '.claude', '.windsurf'];
+export const AIW_EXCLUDE_ENTRIES = ['.aiwcli', '_output', '.claude', '.codex', '.windsurf', '.devin'];
 /** Entries that should NEVER be removed from exclude, even on clear */
 const AIW_PERMANENT_ENTRIES = ['_output'];
 /**
@@ -48,7 +48,7 @@ async function ensureInfoDir(gitDir) {
  *
  * @param gitDir - Git directory (contains info/exclude)
  * @param targetDir - Project root directory (for disk-existence checks)
- * @returns True if any entries were pruned
+ * @returns True if unknown entries were pruned
  */
 export async function pruneExcludeStaleEntries(gitDir, targetDir) {
     const excludePath = getExcludePath(gitDir);
@@ -142,7 +142,7 @@ function cleanupEmptySections(content) {
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
         if (line === AIW_EXCLUDE_HEADER) {
-            // Look ahead to see if there are any patterns
+            // Look ahead to see if there are unknown patterns
             const nextLine = lines[i + 1];
             if (nextLine === undefined || nextLine === '' || nextLine.startsWith('#')) {
                 // Skip the header — section is empty

package/dist/lib/hooks/context-monitor-logic.d.ts

@@ -0,0 +1,6 @@
+export declare const CONTEXT_WARNING_30: string;
+export declare const CONTEXT_WARNING_15: string;
+export declare function selectWarningMessage(pctRemaining: number, alreadyFired: number[]): {
+    pct: number;
+    msg: string;
+} | null;

package/dist/lib/hooks/context-monitor-logic.js

@@ -0,0 +1,25 @@
+export const CONTEXT_WARNING_30 = "## Context Window: ~30% Remaining\n\n" +
+    "This session is approaching its context limit. Consider:\n\n" +
+    "- Completing your current task, then pausing for the user to decide next steps\n" +
+    "- If significant work remains, mention that `/aiwcli-shared:handoff` can capture progress " +
+    "for a fresh session\n\n" +
+    "Do not rush or cut corners — finish the current task properly. " +
+    "Just be aware that starting large new tasks may not complete before context runs out.";
+export const CONTEXT_WARNING_15 = "## Context Window: ~15% Remaining — Wrap Up Now\n\n" +
+    "Context is critically low. After completing your current step:\n\n" +
+    "1. **Stop taking on new work**\n" +
+    "2. Summarize what was accomplished and what remains\n" +
+    "3. Offer to run `/aiwcli-shared:handoff` so progress transfers to a fresh session\n\n" +
+    "Do not start new multi-step tasks. Focus on clean closure.";
+const WARNING_THRESHOLDS = [
+    { pct: 15, msg: CONTEXT_WARNING_15 },
+    { pct: 30, msg: CONTEXT_WARNING_30 },
+];
+export function selectWarningMessage(pctRemaining, alreadyFired) {
+    for (const warning of WARNING_THRESHOLDS) {
+        if (pctRemaining <= warning.pct && !alreadyFired.includes(warning.pct)) {
+            return warning;
+        }
+    }
+    return null;
+}

package/dist/lib/hooks/hook-utils.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Common utilities for hook scripts.
+ * Standardized boilerplate for JSON parsing, validation, error handling.
+ * See SPEC.md §5
+ */
+import type { ContextState, HookInput } from "../types.js";
+export declare const CONTEXT_BASELINE_TOKENS = 22600;
+export declare const DEFAULT_CONTEXT_WINDOW_SIZE = 200000;
+export interface BoundSessionContext {
+    payload: HookInput;
+    projectRoot: string;
+    sessionId: string;
+    state: ContextState;
+}
+export interface PersistenceContext extends BoundSessionContext {
+    toolInput: Record<string, unknown>;
+}
+export interface ToolInputContext {
+    payload: HookInput;
+    toolInput: Record<string, unknown>;
+}
+/**
+ * Load the current payload, resolve its project root, and require an already-bound session.
+ * Returns null when the hook should quietly no-op.
+ */
+export declare function requireBoundSession(hookName: string, prefetchedPayload?: HookInput | null): BoundSessionContext | null;
+/**
+ * Require a bound session plus tool_input for PostToolUse task persistence hooks.
+ */
+export declare function requirePersistenceContext(expectedTool: string, hookName: string): PersistenceContext | null;
+/**
+ * Require a tool_input payload for tool-oriented hooks without needing a bound session.
+ */
+export declare function requireToolInput(hookName: string): ToolInputContext | null;
+/**
+ * Best-effort wrapper around maybeActivate. Hooks should never fail closed on activation.
+ */
+export declare function safeMaybeActivate(contextId: string, permissionMode: string, projectRoot?: string, hookName?: string): boolean;
+/**
+ * Load and parse JSON from stdin (or return prefetched input if set).
+ * Returns null if stdin is empty or invalid JSON.
+ * See SPEC.md §5.1
+ */
+export declare function loadHookInput(): HookInput | null;
+/**
+ * Validate hook event type and optional tool name.
+ * See SPEC.md §5.2
+ */
+export declare function validateHookEvent(payload: HookInput, expectedEvent: string, expectedTool?: string): boolean;
+/**
+ * Extract and validate tool_input from payload.
+ * See SPEC.md §5.3
+ */
+export declare function getToolInput(payload: HookInput): Record<string, unknown> | null;
+/**
+ * Check if persistence should be skipped based on metadata flags.
+ * See SPEC.md §5.4
+ */
+export declare function checkSkipPersistence(payload: HookInput, hookName?: string): boolean;
+/**
+ * Emit hookSpecificOutput with additionalContext to stdout.
+ * hookEventName is required by Claude Code's Zod validator (discriminated union).
+ * Auto-detected from stdin payload (set by loadHookInput/runHook).
+ *
+ * SubagentStop and Stop events use top-level systemMessage field instead of hookSpecificOutput.
+ * See SPEC.md §5.5
+ */
+export declare function emitContext(additionalContext: string): void;
+/**
+ * Emit hookSpecificOutput that denies the tool call with context and reason.
+ * hookEventName is required by Claude Code's Zod validator (discriminated union).
+ * Auto-detected from stdin payload (set by loadHookInput/runHook).
+ * See SPEC.md §5.6
+ */
+export declare function emitContextAndBlock(additionalContext: string, reason: string): void;
+/**
+ * Block a user prompt submission with a reason.
+ * Only works for UserPromptSubmit hooks.
+ * Output: top-level { decision: "block", reason } + optional hookSpecificOutput.additionalContext
+ */
+export declare function emitBlockPrompt(reason: string, context?: string): void;
+/**
+ * Block via exit code 2 + stderr feedback.
+ * Works for PostToolUse, PostToolUseFailure.
+ * The reason becomes the stderr message (fed to Claude as system-reminder).
+ * If context is provided, it's prepended to the stderr message for richer feedback.
+ * NOTE: Exit 2 causes Claude Code to ignore all JSON stdout — only stderr matters.
+ */
+export declare function emitBlockViaExit(reason: string, context?: string): void;
+/**
+ * Block via top-level { decision: "block", reason }.
+ * Works for Stop and SubagentStop events.
+ * These events do NOT support additionalContext — only reason is available.
+ */
+export declare function emitBlockTopLevel(reason: string): void;
+/**
+ * Respond to a PermissionRequest with allow/deny.
+ * Only works for PermissionRequest hooks.
+ */
+export declare function emitPermissionDecision(behavior: "allow" | "deny", opts?: {
+    message?: string;
+    updatedInput?: Record<string, unknown>;
+    updatedPermissions?: Record<string, unknown>;
+}): void;
+/**
+ * Unified block dispatcher — auto-detects the correct blocking mechanism
+ * based on the current hook event type.
+ *
+ * PreToolUse → permissionDecision: "deny" (via emitContextAndBlock)
+ * UserPromptSubmit → top-level decision: "block" (via emitBlockPrompt)
+ * PostToolUse/PostToolUseFailure → exit(2) + stderr (via emitBlockViaExit)
+ * Stop/SubagentStop → top-level { decision: "block", reason } (via emitBlockTopLevel)
+ * PermissionRequest → decision: { behavior: "deny" } (via emitPermissionDecision)
+ * SessionStart/Notification/SubagentStart/SessionEnd/etc. → warn and no-op
+ *
+ * This is the RECOMMENDED universal blocking API. Hook authors should use
+ * emitBlock() and let the library handle event-specific dispatch.
+ */
+export declare function emitBlock(reason: string, context?: string): void;
+/**
+ * Parse context window from hook input.
+ * Returns [tokensUsed, maxTokens] or [null, null].
+ * See SPEC.md §5.9
+ */
+export declare function parseContextWindow(hookInput: HookInput): [number | null, number | null];
+/**
+ * Get context percentage remaining with fallback.
+ * Returns [percentRemaining, tokensUsed, maxTokens] or [null, null, null].
+ * See SPEC.md §5.9
+ */
+export declare function getContextPercentRemaining(hookInput: HookInput): [number | null, number | null, number | null];
+/**
+ * Standard hook entry point with lifecycle logging.
+ * See SPEC.md §5.7
+ */
+export declare function runHook(mainFunc: () => number | void, hookName?: string, prefetchedInput?: Record<string, unknown>): never;
+/**
+ * Async variant of runHook for hooks that need await (e.g., AI inference).
+ * Provides identical structured JSONL lifecycle logging as runHook.
+ * See SPEC.md §5.7
+ */
+export declare function runHookAsync(mainFunc: () => Promise<number | void>, hookName?: string, prefetchedInput?: Record<string, unknown>): void;
+export { hookLog, logBlocking, logDebug, logDiagnostic, logError, logHookError, logInfo, logWarn, setContextPath, setSessionId } from "../runtime/logger.js";