aiwcli 0.11.1 → 0.12.1

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 = new Set(['0.0.9']);
 /**
  * Detects Claude Code version by executing `claude --version`.
  *
@@ -109,7 +109,7 @@ export function checkVersionCompatibility(version) {
         };
     }
     // Check known incompatible versions first
-    if (INCOMPATIBLE_VERSIONS.includes(version)) {
+    if (INCOMPATIBLE_VERSIONS.has(version)) {
         return {
             compatible: false,
             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

@@ -5,18 +5,70 @@
  */
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
+import * as path from "node:path";
 
-import { getProjectRoot } from "../lib-ts/base/constants.js";
+import { getProjectRoot, getContextDir } from "../lib-ts/base/constants.js";
 import { getGitState } from "../lib-ts/base/git-state.js";
 import {
-  loadHookInput, logDebug, logDiagnostic, logError, logInfo, logWarn as _logWarn, runHook,
+  loadHookInput, runHook, logDebug, logInfo, logWarn, logError, logDiagnostic,
 } from "../lib-ts/base/hook-utils.js";
 import { nowIso } from "../lib-ts/base/utils.js";
 import { getContextBySessionId, saveState } from "../lib-ts/context/context-store.js";
 import {
-  extractPlanAnchors, findLatestPlan, generatePlanId, normalizePlanContent,
+  findLatestPlan, normalizePlanContent, generatePlanId, extractPlanAnchors,
 } from "../lib-ts/context/plan-manager.js";
 
+/**
+ * Archive session transcript to context's session-transcripts/ folder.
+ * Returns archived path on success, null if skipped or failed.
+ */
+function archiveTranscript(
+  transcriptPath: string,
+  contextId: string,
+  sessionId: string,
+  projectRoot: string,
+): string | null {
+  // 1. Validate inputs
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+    logDebug("session_end", `Transcript not found: ${transcriptPath}`);
+    return null;
+  }
+
+  // 2. Ensure session-transcripts directory exists
+  const contextDir = getContextDir(contextId, projectRoot);
+  const transcriptsDir = path.join(contextDir, "session-transcripts");
+  fs.mkdirSync(transcriptsDir, { recursive: true });
+
+  // 3. Generate archive filename: YYYY-MM-DD-HHMM-{session_id}.jsonl
+  const now = new Date();
+  // Format: 2026-02-14-1400 (year-month-day-hourminute)
+  // Note: Hours and minutes are concatenated without separator (HHMM)
+  const timestamp =
+    `${now.getFullYear()}-` +
+    `${String(now.getMonth() + 1).padStart(2, "0")}-` +
+    `${String(now.getDate()).padStart(2, "0")}-` +
+    `${String(now.getHours()).padStart(2, "0")}${String(now.getMinutes()).padStart(2, "0")}`;
+
+  // 4. Handle collisions (rare, but possible with rapid session churn)
+  let archiveName = `${timestamp}-${sessionId}.jsonl`;
+  let archivePath = path.join(transcriptsDir, archiveName);
+  let counter = 2;
+  while (fs.existsSync(archivePath)) {
+    archiveName = `${timestamp}-${sessionId}-${counter}.jsonl`;
+    archivePath = path.join(transcriptsDir, archiveName);
+    counter++;
+  }
+
+  // 5. Copy transcript file
+  try {
+    fs.copyFileSync(transcriptPath, archivePath);
+    return archivePath;
+  } catch (error) {
+    logError("session_end", `Failed to copy transcript: ${error}`);
+    return null;
+  }
+}
+
 function main(): void {
   const payload = loadHookInput();
   if (!payload) return;
@@ -50,6 +102,25 @@ function main(): void {
   };
   state.last_active = nowIso();
 
+  // Archive transcript (NEW)
+  // Note: state is a ContextState object (from getContextBySessionId on line 33)
+  // state.id is the context ID used to construct paths like _output/contexts/{context_id}/
+  if (payload.transcript_path) {
+    try {
+      const archived = archiveTranscript(
+        payload.transcript_path,
+        state.id,  // Context ID, verified by existing code on line 98: saveState(state.id, ...)
+        sessionId,
+        projectRoot,
+      );
+      if (archived) {
+        logInfo("session_end", `Archived transcript: ${path.basename(archived)}`);
+      }
+    } catch (error) {
+      logError("session_end", `Transcript archival failed: ${error}`);
+    }
+  }
+
   // Plan fallback assignment (skip in plan mode — rejected plans shouldn't stage)
   if (permissionMode !== "plan") {
     // Step 1: Assign plan fields if missing
@@ -57,7 +128,7 @@ function main(): void {
       const latestPlanPath = findLatestPlan(state.id, projectRoot);
       if (latestPlanPath) {
         try {
-          const content = fs.readFileSync(latestPlanPath, "utf8");
+          const content = fs.readFileSync(latestPlanPath, "utf-8");
           const normalized = normalizePlanContent(content);
           const planHash = crypto.createHash("sha256")
             .update(normalized, "utf-8")

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

@@ -5,16 +5,16 @@
  */
 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 {
   buildRestoreSections, formatHandoffContinuation, getModeDisplay,
 } from "../lib-ts/context/context-formatter.js";
 import {
-  bindSession, getAllContexts, getContextBySessionId, updateMode,
+  getContextBySessionId, getAllContexts, bindSession, 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;
 
@@ -125,20 +125,18 @@ function main(): void {
 
   switch (source) {
     case "clear": {
-      handleClearRestore(sessionId, projectRoot);
-      break;
+      await handleClearRestore(sessionId, projectRoot);
+      break;
     }
-
     case "compact": {
       handleCompactRestore(sessionId, projectRoot);
-      break;
+      break;
     }
-
     default: {
       logDebug("session_start", `Unhandled source: ${source}`);
-      break;
+      break;
     }
   }
 }
 
-runHook(main, "session_start");
+runHookAsync(main, "session_start");

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

@@ -4,15 +4,15 @@
  * 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 { determineContext, BlockRequest } from "../lib-ts/context/context-selector.js";
 import {
-  bindSession, getContextBySessionId, maybeActivate, saveState,
+  getContextBySessionId, bindSession, maybeActivate, saveState,
 } from "../lib-ts/context/context-store.js";
 
 async function asyncMain(): Promise<void> {
@@ -41,7 +41,6 @@ async function asyncMain(): Promise<void> {
     } catch (error) {
       hookLog("warn", "user_prompt_submit", `maybeActivate failed (non-critical): ${error}`, { stderr: false });
     }
-
     hookLog("debug", "user_prompt_submit", `Session bound to ${existingCtx.id}`, { stderr: false });
   } else if (prompt) {
     // First prompt — need to determine context
@@ -67,10 +66,9 @@ async function asyncMain(): Promise<void> {
       }
     } catch (error) {
       if (error instanceof BlockRequest) {
-        logBlocking("user_prompt_submit", (error as Error).message);
-        process.exit(2); // Block the prompt
+        emitBlock((error as Error).message);
+        return;
       }
-
       throw error; // 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()` |