aiwcli 0.10.2 → 0.11.0

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

@@ -0,0 +1,306 @@
+/**
+ * Constants and path utilities for shared context management.
+ * See SPEC.md §2
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+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([
+  "AUX", "COM1", "COM2", "COM3",
+  "COM4", "COM5", "COM6", "COM7", "COM8", "COM9", "CON", "LPT1", "LPT2",
+  "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9", "NUL", "PRN",
+]);
+
+/**
+ * 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.replaceAll(/[^a-z0-9_-]/g, "-");
+  result = result.replaceAll(/[-_]+/g, "-");
+  result = result.replaceAll(/^[-_]+|[-_]+$/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 getAiwcliDir(projectRoot?: string): string {
+  return path.join(projectRoot ?? getProjectRoot(), ".aiwcli");
+}
+
+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.replaceAll(/[^A-Za-z0-9._-]+/g, "_");
+  result = result.replaceAll(/^[._-]+|[._-]+$/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.replaceAll(' ', "-");
+  result = result.replaceAll(/[^a-z0-9._-]+/g, "_");
+  result = result.replaceAll(/[-_]+/g, "-");
+  result = result.replaceAll(/^[._-]+|[._-]+$/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)";
+  }
+}