aiwcli 0.11.0 → 0.12.0

package/dist/lib/template-settings-reconstructor.js

@@ -13,31 +13,20 @@
  *
  * @module lib/template-settings-reconstructor
  */
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
 import { mergeClaudeSettings } from './hooks-merger.js';
 import { IdePathResolver } from './ide-path-resolver.js';
 import { readClaudeSettings, writeClaudeSettings } from './settings-hierarchy.js';
-import { getTemplatePath } from './template-resolver.js';
+import { getSharedTemplatePath, getTemplatePath } from './template-resolver.js';
 import { getTargetHooksFile, readWindsurfHooks, writeWindsurfHooks } from './windsurf-hooks-hierarchy.js';
 import { mergeWindsurfHooks } from './windsurf-hooks-merger.js';
-/**
- * Get the path to the _shared template directory.
- *
- * @returns Absolute path to the _shared template
- */
-function getSharedTemplatePath() {
-    const currentFilePath = fileURLToPath(import.meta.url);
-    const currentDir = dirname(currentFilePath);
-    return join(currentDir, '..', 'templates', '_shared');
-}
 /**
  * Reconstruct .claude/settings.json and .windsurf/hooks.json from the union
  * of all specified templates.
  *
  * The function:
  * 1. Starts with empty settings
- * 2. Merges _shared template settings (always included)
+ * 2. Merges _shared template settings (when active templates exist)
  * 3. For each active template, merges its template-source settings
  * 4. Writes the result to the IDE settings file
  *
@@ -71,11 +60,13 @@ async function reconstructClaudeSettings(targetDir, activeTemplates, sharedTempl
     const methodsTracking = existingSettings?.methods;
     // Start from empty and merge all template settings
     let reconstructed = {};
-    // 1. Merge _shared template settings
-    const sharedSettingsPath = join(sharedTemplatePath, '.claude', 'settings.json');
-    const sharedSettings = await readClaudeSettings(sharedSettingsPath);
-    if (sharedSettings) {
-        reconstructed = mergeClaudeSettings(reconstructed, sharedSettings);
+    // 1. Merge _shared template settings (only when active templates exist that need them)
+    if (activeTemplates.length > 0) {
+        const sharedSettingsPath = join(sharedTemplatePath, '.claude', 'settings.json');
+        const sharedSettings = await readClaudeSettings(sharedSettingsPath);
+        if (sharedSettings) {
+            reconstructed = mergeClaudeSettings(reconstructed, sharedSettings);
+        }
     }
     // 2. Merge each active template's settings (sequential for deterministic merge order)
     for (const template of activeTemplates) {
@@ -105,11 +96,13 @@ async function reconstructWindsurfHooks(targetDir, activeTemplates, sharedTempla
     const hooksPath = getTargetHooksFile(targetDir);
     // Start from empty
     let reconstructed = { hooks: {} };
-    // 1. Merge _shared template hooks
-    const sharedHooksPath = join(sharedTemplatePath, '.windsurf', 'hooks.json');
-    const sharedHooks = await readWindsurfHooks(sharedHooksPath);
-    if (sharedHooks) {
-        reconstructed = mergeWindsurfHooks(reconstructed, sharedHooks);
+    // 1. Merge _shared template hooks (only when active templates exist that need them)
+    if (activeTemplates.length > 0) {
+        const sharedHooksPath = join(sharedTemplatePath, '.windsurf', 'hooks.json');
+        const sharedHooks = await readWindsurfHooks(sharedHooksPath);
+        if (sharedHooks) {
+            reconstructed = mergeWindsurfHooks(reconstructed, sharedHooks);
+        }
     }
     // 2. Merge each active template's hooks (sequential for deterministic merge order)
     for (const template of activeTemplates) {

package/dist/lib/terminal.d.ts

@@ -29,7 +29,7 @@
 /**
  * Options for launching a new terminal window.
  */
-export interface TerminalLaunchOptions {
+interface TerminalLaunchOptions {
     /**
      * Command to execute in the new terminal.
      */
@@ -47,7 +47,7 @@ export interface TerminalLaunchOptions {
 /**
  * Result of a terminal launch operation.
  */
-export interface TerminalLaunchResult {
+interface TerminalLaunchResult {
     /**
      * Error message if launch failed.
      */
@@ -57,14 +57,6 @@ export interface TerminalLaunchResult {
      */
     success: boolean;
 }
-/**
- * Escape a shell argument for safe execution.
- * Wraps path in double quotes and escapes internal quotes.
- *
- * @param arg - Argument to escape
- * @returns Escaped argument safe for shell execution
- */
-declare function escapeShellArg(arg: string): string;
 /**
  * Launch a new terminal window with the specified command.
  *
@@ -96,7 +88,4 @@ declare function escapeShellArg(arg: string): string;
  * ```
  */
 export declare function launchTerminal(options: TerminalLaunchOptions): Promise<TerminalLaunchResult>;
-/**
- * Escape shell argument utility - exported for use in command construction.
- */
-export { escapeShellArg };
+export {};

package/dist/lib/terminal.js

@@ -239,7 +239,3 @@ export async function launchTerminal(options) {
     // Linux/Unix
     return launchLinuxTerminal(cwd, command, debugLog);
 }
-/**
- * Escape shell argument utility - exported for use in command construction.
- */
-export { escapeShellArg };

package/dist/lib/version.d.ts

@@ -25,20 +25,10 @@
  *
  * @module lib/version
  */
-/**
- * Minimum supported Claude Code version.
- * Versions below this will trigger a compatibility warning.
- */
-export declare const MIN_CLAUDE_CODE_VERSION = "0.1.0";
-/**
- * Known incompatible Claude Code versions.
- * These versions have confirmed issues with AI Workflow CLI.
- */
-export declare const INCOMPATIBLE_VERSIONS: string[];
 /**
  * Result of version compatibility check.
  */
-export interface VersionCheckResult {
+interface VersionCheckResult {
     /**
      * Whether the version is compatible with AI Workflow CLI.
      * If version is unknown, assumes compatible (graceful degradation).
@@ -97,3 +87,4 @@ export declare function getClaudeCodeVersion(): Promise<null | string>;
  * ```
  */
 export declare function checkVersionCompatibility(version: null | string | undefined): VersionCheckResult;
+export {};

package/dist/lib/version.js

@@ -32,12 +32,12 @@ const execAsync = promisify(exec);
  * Minimum supported Claude Code version.
  * Versions below this will trigger a compatibility warning.
  */
-export const MIN_CLAUDE_CODE_VERSION = '0.1.0';
+const MIN_CLAUDE_CODE_VERSION = '0.1.0';
 /**
  * Known incompatible Claude Code versions.
  * These versions have confirmed issues with AI Workflow CLI.
  */
-export const INCOMPATIBLE_VERSIONS = ['0.0.9'];
+const INCOMPATIBLE_VERSIONS = ['0.0.9'];
 /**
  * Detects Claude Code version by executing `claude --version`.
  *

package/dist/lib/windsurf-hooks-merger.d.ts

@@ -1,18 +1,4 @@
-import type { WindsurfHooks, WindsurfHooksConfig } from './windsurf-hooks-types.js';
-/**
- * Merge hooks configurations from template into existing
- *
- * Strategy:
- * - For each event type in template hooks
- * - Concatenate with existing hooks for that event
- * - Deduplicate based on command configuration
- * - Maintain order: existing hooks first, then template hooks
- *
- * @param existing - Existing hooks configuration (will not be modified)
- * @param template - Template hooks configuration to merge
- * @returns New merged hooks configuration
- */
-export declare function mergeWindsurfHooksConfig(existing: undefined | WindsurfHooksConfig, template: undefined | WindsurfHooksConfig): WindsurfHooksConfig;
+import type { WindsurfHooks } from './windsurf-hooks-types.js';
 /**
  * Merge complete Windsurf hooks configurations
  *

package/dist/lib/windsurf-hooks-merger.js

@@ -21,7 +21,7 @@ function areHookCommandsEqual(a, b) {
  * @param template - Template hooks configuration to merge
  * @returns New merged hooks configuration
  */
-export function mergeWindsurfHooksConfig(existing, template) {
+function mergeWindsurfHooksConfig(existing, template) {
     return mergeConfigByEventType(existing, template, (existingCommands, templateCommands) => mergeArraysWithDedup(existingCommands, templateCommands, areHookCommandsEqual));
 }
 /**

package/dist/templates/_shared/.codex/workflows/handoff.md

@@ -150,7 +150,7 @@ If a plan document path was provided in `$ARGUMENTS`:
 Instead of writing the file directly, pipe your handoff content to the save script:
 
 ```bash
-python .aiwcli/_shared/scripts/save_handoff.py "{context_id}" <<'EOF'
+bun .aiwcli/_shared/scripts/save_handoff.ts "{context_id}" <<'EOF'
 {Your complete handoff markdown content from Step 3}
 EOF
 ```

package/dist/templates/_shared/.windsurf/workflows/handoff.md

@@ -150,7 +150,7 @@ If a plan document path was provided in `$ARGUMENTS`:
 Instead of writing the file directly, pipe your handoff content to the save script:
 
 ```bash
-python .aiwcli/_shared/scripts/save_handoff.py "{context_id}" <<'EOF'
+bun .aiwcli/_shared/scripts/save_handoff.ts "{context_id}" <<'EOF'
 {Your complete handoff markdown content from Step 3}
 EOF
 ```

package/dist/templates/_shared/hooks-ts/session_end.ts

@@ -69,7 +69,10 @@ function main(): void {
           state.plan_signature = content.slice(0, 200);
           state.plan_id = generatePlanId();
           state.plan_anchors = extractPlanAnchors(content);
-          state.plan_consumed = false;
+          // Preserve plan_consumed if already true (plan was implemented) —
+          // resetting it would re-stage the plan and block handoff staging.
+          // Only set to false when no prior consumption has occurred.
+          state.plan_consumed = state.plan_consumed || false;
 
           logInfo("session_end", `Assigned plan fallback: hash=${planHash}, path=${latestPlanPath}`);
         } catch (error) {

package/dist/templates/_shared/hooks-ts/session_start.ts

@@ -3,18 +3,18 @@
  * SessionStart hook: Restore context after /clear (plan/handoff) or compaction.
  * Routes by source field to appropriate handler.
  */
-import { getProjectRoot } from "../lib-ts/base/constants.js";
 import {
-  emitContext, loadHookInput, logDebug,
-  logDiagnostic, logError as _logError, logInfo, runHook,
+  loadHookInput, emitContext, runHook, runHookAsync,
+  logDebug, logInfo, logError, logDiagnostic,
 } from "../lib-ts/base/hook-utils.js";
+import { getProjectRoot } from "../lib-ts/base/constants.js";
+import {
+  getContextBySessionId, getAllContexts, bindSession, updateMode,
+} from "../lib-ts/context/context-store.js";
 import {
   buildRestoreSections, formatHandoffContinuation, getModeDisplay,
 } from "../lib-ts/context/context-formatter.js";
-import {
-  bindSession, getAllContexts, getContextBySessionId, updateMode,
-} from "../lib-ts/context/context-store.js";
-import type { ContextState as _ContextState } from "../lib-ts/types.js";
+import type { ContextState } from "../lib-ts/types.js";
 
 /**
  * Handle post-compaction restore: re-inject context that was lost during compaction.
@@ -53,7 +53,7 @@ function handleCompactRestore(sessionId: string, projectRoot: string): void {
  * Handle post-clear restore: find staged has_plan or has_handoff context,
  * bind session, transition to active, inject context.
  */
-function handleClearRestore(sessionId: string, projectRoot: string): void {
+async function handleClearRestore(sessionId: string, projectRoot: string): Promise<void> {
   const allContexts = getAllContexts("active", projectRoot);
 
   // Priority 1: has_plan contexts
@@ -108,7 +108,7 @@ function handleClearRestore(sessionId: string, projectRoot: string): void {
   logDebug("session_start", "No has_plan or has_handoff contexts found");
 }
 
-function main(): void {
+async function main(): Promise<void> {
   const payload = loadHookInput();
   if (!payload) return;
 
@@ -124,21 +124,16 @@ function main(): void {
   logDiagnostic("session_start", "entry", `source=${source}, session=${sessionId}`);
 
   switch (source) {
-    case "clear": {
-      handleClearRestore(sessionId, projectRoot);
-      break;
-    }
-
-    case "compact": {
+    case "compact":
       handleCompactRestore(sessionId, projectRoot);
       break;
-    }
-
-    default: {
+    case "clear":
+      await handleClearRestore(sessionId, projectRoot);
+      break;
+    default:
       logDebug("session_start", `Unhandled source: ${source}`);
       break;
-    }
   }
 }
 
-runHook(main, "session_start");
+runHookAsync(main, "session_start");

package/dist/templates/_shared/hooks-ts/user_prompt_submit.ts

@@ -4,16 +4,16 @@
  * to a tracked context. The most complex shared hook.
  *
  * Uses emitContext() for output — context text is passed via hookSpecificOutput JSON.
- * Catches BlockRequest and exits with code 2 to block the prompt.
+ * Catches BlockRequest and uses emitBlock() to block the prompt.
  */
-import { getProjectRoot } from "../lib-ts/base/constants.js";
 import {
-  emitContext, hookLog, loadHookInput, logBlocking, logDebug, logDiagnostic as _logDiagnostic, logInfo, logWarn as _logWarn, runHookAsync,
+  loadHookInput, runHookAsync, logDebug, logInfo, logWarn, logBlocking, logDiagnostic, hookLog, emitContext, emitBlock,
 } from "../lib-ts/base/hook-utils.js";
-import { BlockRequest, determineContext } from "../lib-ts/context/context-selector.js";
+import { getProjectRoot } from "../lib-ts/base/constants.js";
 import {
-  bindSession, getContextBySessionId, maybeActivate, saveState,
+  getContextBySessionId, bindSession, maybeActivate, saveState,
 } from "../lib-ts/context/context-store.js";
+import { determineContext, BlockRequest } from "../lib-ts/context/context-selector.js";
 
 async function asyncMain(): Promise<void> {
   const payload = loadHookInput();
@@ -38,10 +38,9 @@ async function asyncMain(): Promise<void> {
     // Returning user — context already bound (stderr: false to avoid "hook error" display)
     try {
       maybeActivate(existingCtx.id, permissionMode, projectRoot, "user_prompt_submit");
-    } catch (error) {
-      hookLog("warn", "user_prompt_submit", `maybeActivate failed (non-critical): ${error}`, { stderr: false });
+    } catch (e) {
+      hookLog("warn", "user_prompt_submit", `maybeActivate failed (non-critical): ${e}`, { stderr: false });
     }
-
     hookLog("debug", "user_prompt_submit", `Session bound to ${existingCtx.id}`, { stderr: false });
   } else if (prompt) {
     // First prompt — need to determine context
@@ -65,13 +64,12 @@ async function asyncMain(): Promise<void> {
       if (outputText) {
         outputs.push(outputText);
       }
-    } catch (error) {
-      if (error instanceof BlockRequest) {
-        logBlocking("user_prompt_submit", (error as Error).message);
-        process.exit(2); // Block the prompt
+    } catch (e) {
+      if (e instanceof BlockRequest) {
+        emitBlock((e as Error).message);
+        return;
       }
-
-      throw error; // Re-throw unexpected errors
+      throw e; // Re-throw unexpected errors
     }
   }
 

package/dist/templates/_shared/lib-ts/CLAUDE.md

@@ -83,18 +83,38 @@ logBlocking("my_hook", "Critical: state corrupt"); // shows in UI
 
 ---
 
-## Hook Output — Three Communication Channels
+## Hook Output — Communication Channels
 
-Hooks have three channels back to the session. Pick the right one:
+Hooks have multiple channels back to the session. Pick the right one:
 
 | Want to... | Function | Who sees it |
 |------------|----------|-------------|
-| Block tool + return message | `emitContextAndBlock(context, reason)` | Claude + user (denial reason prominent) |
+| **Block (any event)** | `emitBlock(reason, context?)` | Claude + user — auto-dispatches to correct mechanism |
+| Block tool (PreToolUse only) | `emitContextAndBlock(context, reason)` | Claude + user (denial reason prominent) |
 | Return message, don't block | `emitContext(context)` | Claude + user (in transcript) |
 | Log only (diagnostics) | `logInfo()` / `logWarn()` / etc. | Nobody in session — file only |
 
 **There is no way to show something to the user but hide it from Claude, or vice versa.** Both `emitContext()` and `emitContextAndBlock()` produce output visible to both.
 
+### Universal Blocking: `emitBlock()` (RECOMMENDED)
+
+```typescript
+emitBlock("Reason for blocking", "Optional detailed context");
+```
+
+Auto-detects the correct blocking mechanism from the current hook event:
+
+| Event | Mechanism | Dispatches to |
+|-------|-----------|---------------|
+| **PreToolUse** | `permissionDecision: "deny"` in hookSpecificOutput | `emitContextAndBlock()` |
+| **UserPromptSubmit** | Top-level `{ decision: "block", reason }` | `emitBlockPrompt()` |
+| **PostToolUse / PostToolUseFailure** | Exit code 2 + stderr | `emitBlockViaExit()` |
+| **Stop / SubagentStop** | Top-level `{ decision: "block", reason }` | `emitBlockTopLevel()` |
+| **PermissionRequest** | `{ decision: { behavior: "deny" } }` | `emitPermissionDecision()` |
+| **SessionStart / Notification / SubagentStart / SessionEnd** | No blocking mechanism — warns and no-ops | — |
+
+**Use `emitBlock()` for all new hooks.** The per-pattern functions below exist for advanced use cases only.
+
 ### Channel 1: Block + Context (PreToolUse only)
 
 ```typescript
@@ -103,12 +123,41 @@ emitContextAndBlock(
   "Short reason for the block"        // permissionDecisionReason
 );
 // No SystemExit needed — permissionDecision:"deny" with exit 0 is sufficient.
-// runHookAsync drains stdout before exit to ensure pipe consumers receive the JSON.
+// Warns if called from non-PreToolUse events (output will be silently rejected by Claude Code).
 ```
 
 The tool call is **prevented from executing**. Only works for PreToolUse hooks.
 
-### Channel 2: Non-blocking Context (any hook event)
+### Channel 2: Block Prompt Submission (UserPromptSubmit only)
+
+```typescript
+emitBlockPrompt("Reason the prompt was blocked", "Optional context for Claude");
+```
+
+Emits top-level `{ decision: "block", reason }`. The prompt is rejected before Claude processes it.
+
+### Channel 3: Block via Exit Code (PostToolUse / PostToolUseFailure)
+
+```typescript
+emitBlockViaExit("Reason for blocking", "Optional context prepended to stderr");
+// Throws SystemExit:2 — handled by runHook/runHookAsync
+// NOTE: Exit 2 causes Claude Code to ignore all JSON stdout — only stderr matters
+```
+
+### Channel 4: Block Stop/SubagentStop
+
+```typescript
+emitBlockTopLevel("Reason to prevent stopping");
+```
+
+### Channel 5: PermissionRequest Decision
+
+```typescript
+emitPermissionDecision("deny", { message: "Why denied" });
+emitPermissionDecision("allow", { updatedInput: { /* modified input */ } });
+```
+
+### Channel 6: Non-blocking Context (any hook event)
 
 ```typescript
 emitContext("Information added to Claude's context");
@@ -116,7 +165,7 @@ emitContext("Information added to Claude's context");
 
 The tool call / session continues normally. Works for PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Notification, SubagentStart.
 
-### Channel 3: Log-only (diagnostics)
+### Channel 7: Log-only (diagnostics)
 
 ```typescript
 logInfo("my_hook", "Processing started");     // File only
@@ -252,7 +301,7 @@ Use this table to find the right file. Read the source for full API details.
 
 | File | Purpose | Key Exports |
 |------|---------|-------------|
-| `hook-utils.ts` | Hook lifecycle, stdin parsing, output emit, re-exports | `runHook`, `runHookAsync`, `loadHookInput`, `emitContext`, `emitContextAndBlock`, `logDebug`...`logBlocking` |
+| `hook-utils.ts` | Hook lifecycle, stdin parsing, output emit, re-exports | `runHook`, `runHookAsync`, `loadHookInput`, `emitContext`, `emitContextAndBlock`, `emitBlock`, `emitBlockPrompt`, `emitBlockViaExit`, `emitBlockTopLevel`, `emitPermissionDecision`, `logDebug`...`logBlocking` |
 | `logger.ts` | JSONL logging engine | `hookLog`, `logDebug`, `logInfo`, `logWarn`, `logError`, `logBlocking`, `logHookError`, `logDiagnostic` |
 | `constants.ts` | Path resolution, limits | `getProjectRoot()`, `getContextDir()`, `MAX_FILE_SIZE` |
 | `atomic-write.ts` | Crash-safe file writes | `atomicWriteFileSync()` |

package/dist/templates/_shared/lib-ts/base/git-state.ts

@@ -23,7 +23,7 @@ export function getGitState(projectRoot: string): Record<string, any> {
   try {
     const status = execFileSync("git", ["status", "--short"], opts);
     if (status) {
-      const files = status.trim().split("\n")
+      const files = status.trim().split(/\r?\n/)
         .filter(Boolean)
         .slice(0, 10)
         .map(line => line.trimStart().split(/\s+/).slice(1).join(" "));