aiwcli 0.10.3 → 0.11.1

package/dist/templates/_shared/lib-ts/base/subprocess-utils.ts

@@ -3,6 +3,8 @@
  * See SPEC.md §5.10
  */
 
+import { execSync, execFile } from "node:child_process";
+
 /**
  * Check if this is an internal subprocess call.
  * All hooks should check this and return early to prevent recursion.
@@ -21,3 +23,143 @@ export function getInternalSubprocessEnv(): Record<string, string | undefined> {
     AIWCLI_INTERNAL_CALL: "true",
   };
 }
+
+/**
+ * Find an executable on the system PATH.
+ * Uses `where` on Windows, `which` on Unix.
+ * On Windows, prefers .cmd/.exe over extensionless shims since
+ * execFileSync cannot spawn extensionless shell scripts.
+ * Returns the first match or null if not found.
+ */
+export function findExecutable(name: string): string | null {
+  try {
+    const cmd = process.platform === "win32" ? `where ${name}` : `which ${name}`;
+    const lines = execSync(cmd, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], shell: true })
+      .trim()
+      .split(/\r?\n/)
+      .map((l) => l.trim())
+      .filter(Boolean);
+
+    if (lines.length === 0) return null;
+
+    // On Windows, `where` may return an extensionless shim first (e.g. npm creates
+    // both `claude` and `claude.cmd`). execFileSync can't spawn the extensionless
+    // one, so prefer .cmd or .exe.
+    if (process.platform === "win32") {
+      const preferred = lines.find((l) => /\.(cmd|exe)$/i.test(l));
+      return preferred ?? lines[0] ?? null;
+    }
+
+    return lines[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Type guard for Node.js child_process exec errors.
+ * ExecSync throws objects with these extra properties on non-zero exit or timeout.
+ */
+export interface ExecSyncError {
+  killed: boolean;
+  signal: string | null;
+  stdout: Buffer | string;
+  stderr: Buffer | string;
+  status: number | null;
+  message: string;
+}
+
+/** Check if an unknown error is an ExecSync error with process info. */
+export function isExecSyncError(e: unknown): e is ExecSyncError {
+  return (
+    typeof e === "object" &&
+    e !== null &&
+    "killed" in e &&
+    "signal" in e
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Async Subprocess Execution
+// ---------------------------------------------------------------------------
+
+/**
+ * Result from an async subprocess execution.
+ * Never throws — callers inspect fields to determine outcome.
+ */
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  killed: boolean;
+  signal: string | null;
+}
+
+/** Options for execFileAsync. */
+export interface ExecAsyncOptions {
+  /** Data piped to the child's stdin. */
+  input?: string;
+  /** Timeout in milliseconds (not seconds). */
+  timeout?: number;
+  /** Environment variables for the child process. */
+  env?: Record<string, string | undefined>;
+  /** Maximum bytes on stdout/stderr. Default: 10 MB. */
+  maxBuffer?: number;
+  /** Use shell for execution. Required on Windows for .cmd files. */
+  shell?: boolean;
+}
+
+/**
+ * Async subprocess execution that does NOT block the event loop.
+ * Drop-in replacement for execFileSync in Promise-based parallel patterns.
+ *
+ * Returns ExecResult on both success and non-zero exit.
+ * On timeout: result.killed = true, result.signal = "SIGTERM".
+ * On spawn failure: result.exitCode = -1, result.stderr contains error.
+ */
+export function execFileAsync(
+  file: string,
+  args: string[],
+  options?: ExecAsyncOptions,
+): Promise<ExecResult> {
+  return new Promise((resolve) => {
+    const child = execFile(
+      file,
+      args,
+      {
+        encoding: "utf-8",
+        timeout: options?.timeout ?? 0,
+        env: options?.env as NodeJS.ProcessEnv,
+        maxBuffer: options?.maxBuffer ?? 10 * 1024 * 1024,
+        shell: options?.shell,
+      },
+      (error, stdout, stderr) => {
+        if (error) {
+          // execFile callback error includes process exit info
+          const errObj = error as unknown as Record<string, unknown>;
+          resolve({
+            stdout: String(stdout ?? ""),
+            stderr: String(stderr ?? ""),
+            exitCode: typeof errObj.code === "number" ? errObj.code : (error as any).status ?? 1,
+            killed: Boolean(errObj.killed),
+            signal: typeof errObj.signal === "string" ? errObj.signal : null,
+          });
+        } else {
+          resolve({
+            stdout: String(stdout ?? ""),
+            stderr: String(stderr ?? ""),
+            exitCode: 0,
+            killed: false,
+            signal: null,
+          });
+        }
+      },
+    );
+
+    // Pipe input to stdin if provided
+    if (options?.input != null && child.stdin) {
+      child.stdin.write(options.input);
+      child.stdin.end();
+    }
+  });
+}

package/dist/templates/_shared/lib-ts/base/utils.ts

@@ -4,8 +4,8 @@
  */
 
 import { sanitizeTitle } from "./constants.js";
+import { logDebug, logError, logWarn } from "./logger.js";
 import { STOP_WORDS } from "./stop-words.js";
-import { logDebug, logWarn, logError } from "./logger.js";
 
 /**
  * Print to stderr. For terminal-only UX messages, not diagnostics.
@@ -77,22 +77,79 @@ export function parseIsoTimestamp(isoStr: string): Date | null {
 export function cleanTextForSlug(text: string): string {
   if (!text) return "";
   let result = text.toLowerCase();
-  result = result.replace(/'/g, "");            // i'm -> im, you're -> youre
-  result = result.replace(/[^a-z0-9\s]/g, " "); // punctuation -> spaces
-  result = result.replace(/\s+/g, " ").trim();
+  result = result.replaceAll('\'', "");            // i'm -> im, you're -> youre
+  result = result.replaceAll(/[^a-z0-9\s]/g, " "); // punctuation -> spaces
+  result = result.replaceAll(/\s+/g, " ").trim();
   return result;
 }
 
+/**
+ * Generate a slug from text using AI inference with stop-word fallbacks.
+ * Pipeline: AI inference → stop-word post-filter → stop-word fallback → word-length fallback.
+ * Reusable by both context ID generation and plan archival.
+ * See SPEC.md §14.2
+ */
+export function generateSlug(
+  text: string,
+  maxLen = 150,
+  fallbackSlug = "context",
+): string {
+  if (!text || !text.trim()) return fallbackSlug;
+
+  let slug: null | string = null;
+  const cleanedText = cleanTextForSlug(text);
+
+  // Tier 1: AI inference via generateContextIdSlug (sync — uses execFileSync)
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, no-undef
+    const { generateContextIdSlug } = require("./inference.js");
+    const aiSlug = generateContextIdSlug(text);
+    if (aiSlug) {
+      const filteredWords = aiSlug
+        .split(/\s+/)
+        .filter(
+          (w: string) => !STOP_WORDS.has(w.toLowerCase()) && w.length > 1,
+        );
+      if (filteredWords.length >= 5) {
+        slug = sanitizeTitle(filteredWords.join(" "), maxLen);
+      } else {
+        logDebug(
+          "utils",
+          `AI slug too generic after stop-word filter (${filteredWords.length} words remain), using fallback`,
+        );
+      }
+    }
+  } catch (error: any) {
+    logWarn("utils", `AI slug generation failed, using fallback: ${error}`);
+  }
+
+  // Tier 2: Stop-word filtering on cleaned text
+  if (!slug) {
+    const words = cleanedText
+      .split(/\s+/)
+      .filter((w) => !STOP_WORDS.has(w) && w.length > 1)
+      .slice(0, 12);
+    slug = words.length >= 3
+      ? sanitizeTitle(words.join(" "), maxLen)
+      : sanitizeTitle(
+          cleanedText.split(/\s+/).filter((w) => w.length > 2).slice(0, 6).join(" "),
+          maxLen,
+        ) || fallbackSlug;
+  }
+
+  return slug;
+}
+
 /**
  * Generate a context ID from a summary string.
  * Format: YYMMDD-HHMM-slug
- * 3-tier slug: AI inference → stop-word filter → simple word filter
+ * Delegates slug generation to generateSlug().
  * See SPEC.md §14.2
  */
-export async function generateContextId(
+export function generateContextId(
   summary: string,
   existingIds?: Set<string>,
-): Promise<string> {
+): string {
   const now = new Date();
   const yy = String(now.getFullYear()).slice(2);
   const mm = String(now.getMonth() + 1).padStart(2, "0");
@@ -104,70 +161,12 @@ export async function generateContextId(
   let baseId: string;
 
   try {
-    if (!summary || !summary.trim()) {
-      baseId = `${timestamp}-context`;
-    } else {
-      let slug: string | null = null;
-      // Pre-clean for Tier 2/3: strip punctuation so stop words match
-      const cleanedSummary = cleanTextForSlug(summary);
-
-      // Tier 1: AI inference (imported dynamically to avoid circular deps)
-      try {
-        const { generateContextIdSlug } = await import("./inference.js");
-        const aiSlug = generateContextIdSlug(summary);
-        if (aiSlug) {
-          const filteredWords = aiSlug
-            .split(/\s+/)
-            .filter(
-              (w: string) => !STOP_WORDS.has(w.toLowerCase()) && w.length > 1,
-            );
-          if (filteredWords.length >= 5) {
-            slug = sanitizeTitle(filteredWords.join(" "), 150);
-          } else {
-            logDebug(
-              "utils",
-              `AI slug too generic after stop-word filter (${filteredWords.length} words remain), using fallback`,
-            );
-          }
-        }
-      } catch (e: any) {
-        logWarn("utils", `AI context ID slug failed, using fallback: ${e}`);
-      }
-
-      // Tier 2: Stop-word filtering on cleaned text
-      if (!slug) {
-        try {
-          const words = cleanedSummary
-            .split(/\s+/)
-            .filter((w) => !STOP_WORDS.has(w) && w.length > 1)
-            .slice(0, 12);
-          if (words.length >= 3) {
-            slug = sanitizeTitle(words.join(" "), 150);
-          } else {
-            logDebug("utils", `Tier 2 too few content words (${words.length}), falling through to Tier 3`);
-          }
-        } catch (e: any) {
-          logWarn("utils", `Stop-word fallback failed: ${e}`);
-        }
-      }
-
-      // Tier 3: Simple word-length filter on cleaned text
-      if (!slug || slug === "unknown") {
-        const words = cleanedSummary
-          .split(/\s+/)
-          .filter((w) => w.length > 2)
-          .slice(0, 6);
-        slug = words.length > 0
-          ? sanitizeTitle(words.join(" "), 150)
-          : "context";
-      }
-
-      baseId = `${timestamp}-${slug}`;
-    }
-  } catch (e: any) {
+    const slug = generateSlug(summary);
+    baseId = `${timestamp}-${slug}`;
+  } catch (error: any) {
     logError(
       "utils",
-      `Context ID generation failed entirely, using timestamp: ${e}`,
+      `Context ID generation failed entirely, using timestamp: ${error}`,
     );
     baseId = `${timestamp}-context`;
   }
@@ -180,5 +179,6 @@ export async function generateContextId(
   while (existingIds.has(`${baseId}-${counter}`)) {
     counter++;
   }
+
   return `${baseId}-${counter}`;
 }

package/dist/templates/_shared/lib-ts/context/context-formatter.ts

@@ -8,7 +8,8 @@
  */
 
 import * as fs from "node:fs";
-import * as path from "node:path";
+import * as _path from "node:path";
+
 import { parseIsoTimestamp } from "../base/utils.js";
 import type { ContextState, Task } from "../types.js";
 
@@ -41,10 +42,10 @@ export function getModeDisplay(mode: string): string {
  * Format ISO timestamp as '2 hours ago', 'yesterday', etc.
  * See SPEC.md §11.3
  */
-export function formatRelativeTime(isoTimestamp: string | null): string {
+export function formatRelativeTime(isoTimestamp: null | string): string {
   if (!isoTimestamp) return "unknown";
 
-  let dt = parseIsoTimestamp(isoTimestamp);
+  const dt = parseIsoTimestamp(isoTimestamp);
   if (!dt) return isoTimestamp.slice(0, 16);
 
   const now = new Date();
@@ -61,8 +62,10 @@ export function formatRelativeTime(isoTimestamp: string | null): string {
       if (diffMin === 0) return "just now";
       return diffMin === 1 ? "1 minute ago" : `${diffMin} minutes ago`;
     }
+
     return diffHours === 1 ? "1 hour ago" : `${diffHours} hours ago`;
   }
+
   if (diffDays === 1) return "yesterday";
   if (diffDays < 7) return `${diffDays} days ago`;
 
@@ -77,21 +80,23 @@ export function formatRelativeTime(isoTimestamp: string | null): string {
 // Internal helpers
 // ---------------------------------------------------------------------------
 
-function taskAttr(task: Task | Record<string, any>, key: string, defaultVal = ""): string {
+function taskAttr(task: Record<string, any> | Task, key: string, defaultVal = ""): string {
   if (typeof task === "object" && task !== null) {
     return (task as any)[key] ?? defaultVal;
   }
+
   return defaultVal;
 }
 
-function readPlanContent(planPath: string): [string | null, boolean, number] {
+function readPlanContent(planPath: string): [null | string, boolean, number] {
   try {
     if (!fs.existsSync(planPath)) return [null, false, 0];
-    const content = fs.readFileSync(planPath, "utf-8");
+    const content = fs.readFileSync(planPath, "utf8");
     const total = content.length;
     if (total > MAX_PLAN_INLINE_CHARS) {
       return [content.slice(0, MAX_PLAN_INLINE_CHARS), true, total];
     }
+
     return [content, false, total];
   } catch {
     return [null, false, 0];
@@ -100,7 +105,7 @@ function readPlanContent(planPath: string): [string | null, boolean, number] {
 
 function modeLabel(ctx: ContextState): string {
   const d = getModeDisplay(ctx.mode ?? "idle");
-  return d ? d.replace(/^\[|\]$/g, "") : "Active";
+  return d ? d.replaceAll(/^\[|\]$/g, "") : "Active";
 }
 
 /**
@@ -119,7 +124,7 @@ export function buildRestoreSections(
     const savedAt = lastSession.saved_at ?? "";
     if (savedAt) {
       const reason = lastSession.save_reason ?? "";
-      const reasonDisplay = reason ? reason.replace(/_/g, " ") : "unknown";
+      const reasonDisplay = reason ? reason.replaceAll('_', " ") : "unknown";
       sections.push(`**Last session ended:** ${formatRelativeTime(savedAt)} (${reasonDisplay})`);
     }
   }
@@ -138,6 +143,7 @@ export function buildRestoreSections(
         buckets[s]!.push(taskAttr(t, "subject"));
       }
     }
+
     if (Object.values(buckets).some(b => b.length > 0)) {
       sections.push("", `### Previous Work (${tasks.length} tasks)`, "");
       const marks: Record<string, string> = {
@@ -195,8 +201,7 @@ function resumeBlock(ctx: ContextState, projectRoot: string | undefined, modeTex
   ];
   const restore = buildRestoreSections(ctx, projectRoot, true);
   if (restore) lines.push(restore);
-  lines.push("", "---", "", "**Instructions:**");
-  lines.push(...instructions);
+  lines.push("", "---", "", "**Instructions:**", ...instructions);
   return lines.join("\n");
 }
 
@@ -218,12 +223,12 @@ export function formatHandoffContinuation(ctx: ContextState, projectRoot?: strin
 
   try {
     if (handoffPath && fs.existsSync(handoffPath)) {
-      lines.push("### Previous Session Handoff", "", fs.readFileSync(handoffPath, "utf-8"), "");
+      lines.push("### Previous Session Handoff", "", fs.readFileSync(handoffPath, "utf8"), "");
     } else {
       lines.push(`*Handoff document not found at \`${handoffPath}\`*`, "");
     }
-  } catch (e: any) {
-    lines.push(`*Handoff document at \`${handoffPath}\` could not be read: ${e}*`, "");
+  } catch (error: any) {
+    lines.push(`*Handoff document at \`${handoffPath}\` could not be read: ${error}*`, "");
   }
 
   const restore = buildRestoreSections(ctx, projectRoot, true);
@@ -266,20 +271,21 @@ export function formatContextList(contexts: ContextState[]): string {
   if (contexts.length === 0) return "No active contexts found.";
 
   const lines = ["## Active Contexts\n"];
-  for (let i = 0; i < contexts.length; i++) {
-    const ctx = contexts[i]!;
+  for (const [i, context_] of contexts.entries()) {
+    const ctx = context_!;
     const timeStr = formatRelativeTime(ctx.last_active);
     const md = getModeDisplay(ctx.mode ?? "idle");
     const si = md ? ` ${md}` : "";
-    lines.push(`**${i + 1}. ${ctx.id}**${si}`);
-    lines.push(`   ${ctx.summary}`);
+    lines.push(`**${i + 1}. ${ctx.id}**${si}`, `   ${ctx.summary}`);
     if (ctx.method) {
       lines.push(`   Method: ${ctx.method} | Last active: ${timeStr}`);
     } else {
       lines.push(`   Last active: ${timeStr}`);
     }
+
     lines.push("");
   }
+
   return lines.join("\n");
 }
 
@@ -349,11 +355,11 @@ export function formatContextPickerStderr(contexts: ContextState[]): string {
   ];
 
   let selectableCount = 0;
-  for (let i = 0; i < contexts.length; i++) {
-    const ctx = contexts[i]!;
+  for (const [i, context_] of contexts.entries()) {
+    const ctx = context_!;
     const timeStr = formatRelativeTime(ctx.last_active);
     const mode = ctx.mode ?? "idle";
-    const isSelectable = mode === "active" || !!ctx.handoff_path;
+    const isSelectable = mode === "active" || Boolean(ctx.handoff_path);
     if (isSelectable) selectableCount++;
 
     let status = "";
@@ -366,10 +372,7 @@ export function formatContextPickerStderr(contexts: ContextState[]): string {
     const summary = ctx.summary.length > 48 ? ctx.summary.slice(0, 45) + "..." : ctx.summary;
     const selTag = isSelectable ? " [selectable]" : " [end only]";
 
-    lines.push(`|  ^${i + 1}  ${ctx.id}${status}${selTag}`);
-    lines.push(`|       ${summary}`);
-    lines.push(`|       [${timeStr}]`);
-    lines.push("|");
+    lines.push(`|  ^${i + 1}  ${ctx.id}${status}${selTag}`, `|       ${summary}`, `|       [${timeStr}]`, "|");
   }
 
   lines.push(
@@ -394,6 +397,7 @@ export function formatContextPickerStderr(contexts: ContextState[]): string {
       "+----------------------------------------------------------------+",
     );
   }
+
   lines.push("");
   return lines.join("\n");
 }
@@ -413,6 +417,7 @@ export function formatCommandFeedback(
       const s = ctx.summary.length > 50 ? ctx.summary.slice(0, 50) + "..." : ctx.summary;
       lines.push(`- **${ctx.id}**: ${s}`);
     }
+
     lines.push("");
   }
 
@@ -428,5 +433,6 @@ export function formatCommandFeedback(
       "Tasks created with TaskCreate will be persisted to this context.",
     );
   }
+
   return lines.join("\n");
 }