aiwcli 0.10.1 → 0.10.3

package/dist/templates/_shared/lib-ts/base/atomic-write.ts

@@ -0,0 +1,138 @@
+/**
+ * Cross-platform atomic file writes with security.
+ * Crash-safe writes by writing to temp file then renaming.
+ * NOT for concurrent access — assumes single-session-per-context.
+ * See SPEC.md §4
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import * as crypto from "node:crypto";
+
+/**
+ * Write file atomically with retry logic.
+ * Creates temp file, writes, fsyncs, renames.
+ * Returns [success, error].
+ * See SPEC.md §4.2
+ */
+export function atomicWrite(
+  filePath: string,
+  content: string,
+  maxAttempts = 2,
+  backoffMs: number[] = [500, 1000],
+): [boolean, string | null] {
+  // Ensure parent directory exists
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const stem = path.basename(filePath, path.extname(filePath));
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const tmpName = `.${stem}_${crypto.randomBytes(4).toString("hex")}.tmp`;
+    const tmpPath = path.join(dir, tmpName);
+
+    try {
+      // Write to temp file
+      const fd = fs.openSync(tmpPath, "w");
+      try {
+        fs.writeSync(fd, content, undefined, "utf-8");
+        fs.fsyncSync(fd);
+      } finally {
+        fs.closeSync(fd);
+      }
+
+      // Set restrictive permissions (best-effort)
+      try {
+        fs.chmodSync(tmpPath, 0o600);
+      } catch {
+        // May fail on some filesystems
+      }
+
+      // Atomic rename (cross-platform on modern Node/Bun)
+      fs.renameSync(tmpPath, filePath);
+
+      return [true, null];
+    } catch (e: any) {
+      // Clean up temp file
+      try {
+        fs.unlinkSync(tmpPath);
+      } catch {
+        // Best-effort cleanup
+      }
+
+      if (attempt < maxAttempts - 1) {
+        const waitMs = backoffMs[Math.min(attempt, backoffMs.length - 1)] ?? backoffMs[backoffMs.length - 1] ?? 500;
+        sleepSync(waitMs);
+      } else {
+        const errType = e?.constructor?.name ?? "Error";
+        const errMsg = String(e).split("\n")[0]?.slice(0, 200) ?? "";
+        return [false, `${errType}: ${errMsg}`];
+      }
+    }
+  }
+
+  return [false, "Max retry attempts exceeded"];
+}
+
+/**
+ * Append to file with retry logic.
+ * For JSONL files where each line is independent.
+ * See SPEC.md §4.3
+ */
+export function atomicAppend(
+  filePath: string,
+  content: string,
+  maxAttempts = 2,
+  backoffMs: number[] = [500, 1000],
+): [boolean, string | null] {
+  // Ensure parent directory exists
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const isNewFile = !fs.existsSync(filePath);
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      const fd = fs.openSync(filePath, "a");
+      try {
+        fs.writeSync(fd, content, undefined, "utf-8");
+        fs.fsyncSync(fd);
+      } finally {
+        fs.closeSync(fd);
+      }
+
+      // Set permissions on newly created files (best-effort)
+      if (isNewFile) {
+        try {
+          fs.chmodSync(filePath, 0o600);
+        } catch {
+          // May fail on some filesystems
+        }
+      }
+
+      return [true, null];
+    } catch (e: any) {
+      if (attempt < maxAttempts - 1) {
+        const waitMs = backoffMs[Math.min(attempt, backoffMs.length - 1)] ?? backoffMs[backoffMs.length - 1] ?? 500;
+        sleepSync(waitMs);
+      } else {
+        const errType = e?.constructor?.name ?? "Error";
+        const errMsg = String(e).split("\n")[0]?.slice(0, 200) ?? "";
+        return [false, `${errType}: ${errMsg}`];
+      }
+    }
+  }
+
+  return [false, "Max retry attempts exceeded"];
+}
+
+/**
+ * Synchronous sleep for retry backoff.
+ * Uses Atomics.wait() for CPU-friendly blocking instead of busy-wait.
+ */
+function sleepSync(ms: number): void {
+  const sab = new SharedArrayBuffer(4);
+  const i32 = new Int32Array(sab);
+  Atomics.wait(i32, 0, 0, ms);
+}

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

@@ -0,0 +1,299 @@
+/**
+ * Constants and path utilities for shared context management.
+ * See SPEC.md §2
+ */
+
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { logWarn } from "./logger.js";
+
+// Directory names (relative to project root)
+const OUTPUT_DIR = "_output";
+const CONTEXTS_DIR = "contexts";
+const ARCHIVE_DIR = "_archive";
+const INDEX_FILENAME = "index.json";
+
+// Context ID validation
+export const MAX_CONTEXT_ID_LENGTH = 64;
+export const VALID_CONTEXT_ID_PATTERN =
+  /^[a-z0-9][a-z0-9_-]*[a-z0-9]$|^[a-z0-9]$/;
+
+// File size limits
+export const MAX_EVENT_SIZE = 64 * 1024;
+export const MAX_INDEX_SIZE = 1024 * 1024;
+
+// Performance constants
+export const MAX_RETRY_ATTEMPTS = 2;
+export const RETRY_BACKOFF_MS = [500, 1000];
+
+// Windows reserved filenames
+const WINDOWS_RESERVED = new Set([
+  "CON", "PRN", "AUX", "NUL",
+  "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9",
+  "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9",
+]);
+
+/**
+ * Sanitize a string into a valid context ID.
+ * See SPEC.md §2.3
+ */
+export function sanitizeContextId(contextId: string): string {
+  if (!contextId) return "context";
+
+  let result = contextId.toLowerCase();
+  result = result.replace(/[^a-z0-9_-]/g, "-");
+  result = result.replace(/[-_]+/g, "-");
+  result = result.replace(/^[-_]+|[-_]+$/g, "");
+
+  if (result.length > MAX_CONTEXT_ID_LENGTH) {
+    result = result.slice(0, MAX_CONTEXT_ID_LENGTH).replace(/[-_]+$/, "");
+  }
+
+  return result || "context";
+}
+
+/**
+ * Validate and normalize context ID.
+ * Throws only for security violations (path traversal).
+ * See SPEC.md §2.3
+ */
+export function validateContextId(contextId: string): string {
+  if (!contextId) return "context";
+
+  // SECURITY: Check for path traversal BEFORE any normalization
+  if (
+    contextId.includes("..") ||
+    contextId.includes("/") ||
+    contextId.includes("\\")
+  ) {
+    throw new Error(
+      `Invalid context ID '${contextId}': path traversal not allowed`,
+    );
+  }
+
+  // Check for URL-encoded variants
+  const lower = contextId.toLowerCase();
+  if (
+    lower.includes("%2e") ||
+    lower.includes("%2f") ||
+    lower.includes("%5c")
+  ) {
+    throw new Error(
+      `Invalid context ID '${contextId}': encoded path traversal not allowed`,
+    );
+  }
+
+  return sanitizeContextId(contextId);
+}
+
+/**
+ * Get project root from environment or cwd.
+ * Priority: CLAUDE_PROJECT_DIR > payload cwd > process.cwd()
+ * See SPEC.md §2.2
+ */
+export function getProjectRoot(payloadCwd?: string): string {
+  const envDir = process.env.CLAUDE_PROJECT_DIR;
+  if (envDir) {
+    if (!path.isAbsolute(envDir)) {
+      logWarn("utils", `CLAUDE_PROJECT_DIR is not absolute: '${envDir}', ignoring`);
+    } else if (envDir.includes("..")) {
+      logWarn("utils", `CLAUDE_PROJECT_DIR contains '..': '${envDir}', ignoring`);
+    } else {
+      return envDir;
+    }
+  }
+  if (payloadCwd) return payloadCwd;
+  return process.cwd();
+}
+
+// §2.4 — Path functions
+
+export function getOutputDir(projectRoot?: string): string {
+  return path.join(projectRoot ?? getProjectRoot(), OUTPUT_DIR);
+}
+
+export function getContextsDir(projectRoot?: string): string {
+  return path.join(getOutputDir(projectRoot), CONTEXTS_DIR);
+}
+
+export function getContextDir(
+  contextId: string,
+  projectRoot?: string,
+): string {
+  const validatedId = validateContextId(contextId);
+  const contextsDir = getContextsDir(projectRoot);
+  const resultPath = path.join(contextsDir, validatedId);
+
+  // SECURITY: Verify resolved path stays within contexts directory
+  const resolved = path.resolve(resultPath);
+  const contextsResolved = path.resolve(contextsDir);
+  if (
+    !resolved.toLowerCase().startsWith(contextsResolved.toLowerCase())
+  ) {
+    throw new Error(
+      `Invalid context ID '${contextId}': path escapes contexts directory`,
+    );
+  }
+
+  return resultPath;
+}
+
+export function getContextPlansDir(
+  contextId: string,
+  projectRoot?: string,
+): string {
+  return path.join(getContextDir(contextId, projectRoot), "plans");
+}
+
+export function getContextHandoffsDir(
+  contextId: string,
+  projectRoot?: string,
+): string {
+  return path.join(getContextDir(contextId, projectRoot), "handoffs");
+}
+
+export function getContextReviewsDir(
+  contextId: string,
+  projectRoot?: string,
+): string {
+  return path.join(getContextDir(contextId, projectRoot), "reviews");
+}
+
+export function getIndexPath(projectRoot?: string): string {
+  return path.join(getOutputDir(projectRoot), INDEX_FILENAME);
+}
+
+export function getContextFilePath(
+  contextId: string,
+  projectRoot?: string,
+): string {
+  return path.join(getContextDir(contextId, projectRoot), "context.json");
+}
+
+export function getEventsFilePath(
+  contextId: string,
+  projectRoot?: string,
+): string {
+  return path.join(getContextDir(contextId, projectRoot), "events.jsonl");
+}
+
+export function getAutoStatePath(
+  contextId: string,
+  projectRoot?: string,
+): string {
+  return path.join(
+    getContextDir(contextId, projectRoot),
+    "auto-state.json",
+  );
+}
+
+export function getArchiveDir(projectRoot?: string): string {
+  return path.join(getContextsDir(projectRoot), ARCHIVE_DIR);
+}
+
+export function getArchiveContextDir(
+  contextId: string,
+  projectRoot?: string,
+): string {
+  const validatedId = validateContextId(contextId);
+  return path.join(getArchiveDir(projectRoot), validatedId);
+}
+
+export function getArchiveIndexPath(projectRoot?: string): string {
+  return path.join(getArchiveDir(projectRoot), INDEX_FILENAME);
+}
+
+/**
+ * Get path for a new handoff folder with datetime naming.
+ * Handles collisions by appending -N suffix.
+ * See SPEC.md §2.4
+ */
+export function getHandoffFolderPath(
+  contextId: string,
+  projectRoot?: string,
+): string {
+  const handoffsDir = getContextHandoffsDir(contextId, projectRoot);
+  const now = new Date();
+  const timestamp = [
+    now.getFullYear().toString(),
+    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"),
+  ].join("");
+  // Format: YYYY-MM-DD-HHMM
+  const ts = `${timestamp.slice(0, 4)}-${timestamp.slice(4, 6)}-${timestamp.slice(6, 8)}${timestamp.slice(8)}`;
+
+  let folder = path.join(handoffsDir, ts);
+  let counter = 1;
+  while (fs.existsSync(folder)) {
+    folder = path.join(handoffsDir, `${ts}-${counter}`);
+    counter++;
+  }
+  return folder;
+}
+
+/**
+ * Get path for a new review folder.
+ * See SPEC.md §2.4
+ */
+export function getReviewFolderPath(
+  contextId: string,
+  iteration: number,
+  projectRoot?: string,
+): string {
+  const reviewsDir = path.join(
+    getContextReviewsDir(contextId, projectRoot),
+    "cc-native",
+  );
+  const now = new Date();
+  const ts = [
+    now.getFullYear().toString(),
+    "-",
+    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"),
+  ].join("");
+  return path.join(reviewsDir, `${ts}-iteration-${iteration}`);
+}
+
+// §2.5 — Filename sanitization
+
+export function sanitizeFilename(
+  s: string,
+  maxLen = 32,
+  allowLeadingDot = false,
+): string {
+  let result = s.replace(/[^A-Za-z0-9._-]+/g, "_");
+  result = result.replace(/^[._-]+|[._-]+$/g, "").slice(0, maxLen) || "unknown";
+
+  if (!allowLeadingDot) {
+    result = result.replace(/^\.+/, "");
+  }
+
+  const baseName = (result.split(".")[0] ?? result).toUpperCase();
+  if (WINDOWS_RESERVED.has(baseName)) {
+    result = `_${result}`;
+  }
+
+  return result || "unknown";
+}
+
+export function sanitizeTitle(s: string, maxLen = 50): string {
+  let result = s.toLowerCase().trim();
+  result = result.replace(/ /g, "-");
+  result = result.replace(/[^a-z0-9._-]+/g, "_");
+  result = result.replace(/[-_]+/g, "-");
+  result = result.replace(/^[._-]+|[._-]+$/g, "").slice(0, maxLen) || "unknown";
+
+  const baseName = (result.split(".")[0] ?? result).toUpperCase();
+  if (WINDOWS_RESERVED.has(baseName)) {
+    result = `_${result}`;
+  }
+
+  return result || "unknown";
+}

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

@@ -0,0 +1,58 @@
+import { execFileSync } from "node:child_process";
+
+/**
+ * Capture current git state for session snapshots.
+ * All fields are optional — failures are silently ignored.
+ */
+export function getGitState(projectRoot: string): Record<string, any> {
+  const gitState: Record<string, any> = {};
+  const isWin = process.platform === "win32";
+  const opts = {
+    cwd: projectRoot,
+    timeout: 5000,
+    encoding: "utf-8" as const,
+    stdio: ["pipe", "pipe", "pipe"] as ["pipe", "pipe", "pipe"],
+    shell: isWin,
+  };
+
+  try {
+    const branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], opts);
+    if (branch) gitState.branch = branch.trim();
+  } catch { /* non-fatal */ }
+
+  try {
+    const status = execFileSync("git", ["status", "--short"], opts);
+    if (status) {
+      const files = status.trim().split("\n")
+        .filter(Boolean)
+        .slice(0, 10)
+        .map(line => line.trimStart().split(/\s+/).slice(1).join(" "));
+      if (files.length > 0) gitState.uncommitted_files = files;
+    }
+  } catch { /* non-fatal */ }
+
+  try {
+    const log = execFileSync("git", ["log", "-1", "--oneline"], opts);
+    if (log) gitState.last_commit_short = log.trim();
+  } catch { /* non-fatal */ }
+
+  return gitState;
+}
+
+/**
+ * Get short git status string for display (e.g., in handoff documents).
+ */
+export function getGitStatusShort(projectRoot?: string): string {
+  try {
+    const result = execFileSync("git", ["status", "--short"], {
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: ["pipe", "pipe", "pipe"],
+      ...(projectRoot ? { cwd: projectRoot } : {}),
+      shell: process.platform === "win32",
+    });
+    return result.trim() || "(no changes)";
+  } catch {
+    return "(git status unavailable)";
+  }
+}