aiwcli 0.10.2 → 0.11.0

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

@@ -0,0 +1,162 @@
+/**
+ * Subprocess environment utilities.
+ * See SPEC.md §5.10
+ */
+
+import { execFile, execSync } from "node:child_process";
+
+/**
+ * Check if this is an internal subprocess call.
+ * All hooks should check this and return early to prevent recursion.
+ */
+export function isInternalCall(): boolean {
+  return process.env.AIWCLI_INTERNAL_CALL === "true";
+}
+
+/**
+ * Get environment for internal subprocess calls.
+ * Returns a copy of process.env with AIWCLI_INTERNAL_CALL=true.
+ */
+export function getInternalSubprocessEnv(): Record<string, string | undefined> {
+  return {
+    ...process.env,
+    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): null | string {
+  try {
+    const cmd = process.platform === "win32" ? `where ${name}` : `which ${name}`;
+    const lines = execSync(cmd, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] })
+      .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;
+  message: string;
+  signal: null | string;
+  status: null | number;
+  stderr: Buffer | string;
+  stdout: Buffer | 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 {
+  exitCode: number;
+  killed: boolean;
+  signal: null | string;
+  stderr: string;
+  stdout: string;
+}
+
+/** Options for execFileAsync. */
+export interface ExecAsyncOptions {
+  /** Environment variables for the child process. */
+  env?: Record<string, string | undefined>;
+  /** Data piped to the child's stdin. */
+  input?: string;
+  /** Maximum bytes on stdout/stderr. Default: 10 MB. */
+  maxBuffer?: number;
+  /** Timeout in milliseconds (not seconds). */
+  timeout?: number;
+}
+
+/**
+ * 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,
+      },
+      (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 && options?.input !== undefined && child.stdin) {
+      child.stdin.write(options.input);
+      child.stdin.end();
+    }
+  });
+}

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

@@ -0,0 +1,184 @@
+/**
+ * Core utilities for shared context management.
+ * See SPEC.md §14.2, §14.3
+ */
+
+import { sanitizeTitle } from "./constants.js";
+import { logDebug, logError, logWarn } from "./logger.js";
+import { STOP_WORDS } from "./stop-words.js";
+
+/**
+ * Print to stderr. For terminal-only UX messages, not diagnostics.
+ */
+export function eprint(...args: any[]): void {
+  process.stderr.write(args.map(String).join(" ") + "\n");
+}
+
+/**
+ * Get current local datetime as Date.
+ */
+export function nowLocal(): Date {
+  return new Date();
+}
+
+/**
+ * Get current time as ISO 8601 string (local time, no timezone suffix).
+ * Matches Python datetime.now().isoformat() behavior.
+ */
+export function nowIso(): string {
+  const d = new Date();
+  const year = d.getFullYear();
+  const month = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  const hours = String(d.getHours()).padStart(2, "0");
+  const minutes = String(d.getMinutes()).padStart(2, "0");
+  const seconds = String(d.getSeconds()).padStart(2, "0");
+  const ms = String(d.getMilliseconds()).padStart(3, "0");
+  return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}.${ms}`;
+}
+
+/**
+ * Format datetime for display.
+ * Returns "YYYY-MM-DD HH:MM:SS"
+ * See SPEC.md §14.3
+ */
+export function formatTimestamp(dt?: Date): string {
+  const d = dt ?? nowLocal();
+  const year = d.getFullYear();
+  const month = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  const hours = String(d.getHours()).padStart(2, "0");
+  const minutes = String(d.getMinutes()).padStart(2, "0");
+  const seconds = String(d.getSeconds()).padStart(2, "0");
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+}
+
+/**
+ * Parse ISO 8601 timestamp string.
+ * Returns null if parsing fails.
+ * See SPEC.md §14.3
+ */
+export function parseIsoTimestamp(isoStr: string): Date | null {
+  try {
+    const normalized = isoStr.replace("Z", "+00:00");
+    const d = new Date(normalized);
+    if (isNaN(d.getTime())) return null;
+    return d;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Clean text for stop-word matching in slug generation.
+ * Strips apostrophes (i'm -> im), removes punctuation, normalizes whitespace.
+ * See SPEC.md §14.2
+ */
+export function cleanTextForSlug(text: string): string {
+  if (!text) return "";
+  let result = text.toLowerCase();
+  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
+ * Delegates slug generation to generateSlug().
+ * See SPEC.md §14.2
+ */
+export function generateContextId(
+  summary: string,
+  existingIds?: Set<string>,
+): string {
+  const now = new Date();
+  const yy = String(now.getFullYear()).slice(2);
+  const mm = String(now.getMonth() + 1).padStart(2, "0");
+  const dd = String(now.getDate()).padStart(2, "0");
+  const hh = String(now.getHours()).padStart(2, "0");
+  const min = String(now.getMinutes()).padStart(2, "0");
+  const timestamp = `${yy}${mm}${dd}-${hh}${min}`;
+
+  let baseId: string;
+
+  try {
+    const slug = generateSlug(summary);
+    baseId = `${timestamp}-${slug}`;
+  } catch (error: any) {
+    logError(
+      "utils",
+      `Context ID generation failed entirely, using timestamp: ${error}`,
+    );
+    baseId = `${timestamp}-context`;
+  }
+
+  if (!existingIds || !existingIds.has(baseId)) {
+    return baseId;
+  }
+
+  let counter = 2;
+  while (existingIds.has(`${baseId}-${counter}`)) {
+    counter++;
+  }
+
+  return `${baseId}-${counter}`;
+}