aiwcli 0.10.3 → 0.11.1

package/dist/templates/cc-native/_cc-native/lib-ts/cc-native-state.ts

@@ -0,0 +1,199 @@
+/**
+ * CC-native state accessor for context state.json.
+ * Deduplicates state access patterns for cc-native hooks.
+ * See cc-native-plan-review-spec.md §4.5
+ */
+
+import type {
+  CcNativeState,
+  IterationState,
+  PlanReviewState,
+  QuestionsAskedState as _QuestionsAskedState,
+} from "./types.js";
+import { logInfo, logWarn } from "../../_shared/lib-ts/base/logger.js";
+import { nowIso } from "../../_shared/lib-ts/base/utils.js";
+import { getContextBySessionId, saveState } from "../../_shared/lib-ts/context/context-store.js";
+import type { ContextState } from "../../_shared/lib-ts/types.js";
+
+/**
+ * ContextState extended with the cc_native method-specific data.
+ * ContextState doesn't include cc_native in its type definition because it's
+ * a shared type. This local extension bridges the gap for cc-native code.
+ */
+type CcNativeContextState = ContextState & { cc_native?: CcNativeState };
+
+// ---------------------------------------------------------------------------
+// Core State Access
+// ---------------------------------------------------------------------------
+
+/**
+ * Get cc_native state from context state.json.
+ * Returns the cc_native dict or null if not found.
+ */
+export function getCcNativeState(
+  sessionId: string,
+  projectRoot: string,
+): CcNativeState | null {
+  try {
+    const state = getContextBySessionId(sessionId, projectRoot) as CcNativeContextState | null;
+    if (state?.cc_native && typeof state.cc_native === "object") {
+      return state.cc_native;
+    }
+  } catch {
+    // Fail-safe: return null
+  }
+
+  return null;
+}
+
+/**
+ * Save cc_native state to context state.json.
+ * Returns true on success, false on failure.
+ */
+export function saveCcNativeState(
+  sessionId: string,
+  projectRoot: string,
+  ccNativeData: CcNativeState,
+): boolean {
+  try {
+    const state = getContextBySessionId(sessionId, projectRoot) as CcNativeContextState | null;
+    if (state) {
+      state.cc_native = ccNativeData;
+      saveState(state.id, state, projectRoot);
+      return true;
+    }
+  } catch (error: unknown) {
+    logWarn("utils", `Failed to save cc_native state: ${error}`);
+  }
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Plan Review State
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if this exact plan has already been reviewed in this session.
+ */
+export function isPlanAlreadyReviewed(
+  sessionId: string,
+  planHash: string,
+  projectRoot: string,
+): boolean {
+  const ccNative = getCcNativeState(sessionId, projectRoot);
+  if (!ccNative) return false;
+  const reviewState = ccNative.plan_review;
+  return reviewState?.plan_hash === planHash;
+}
+
+/**
+ * Check if this plan hash was previously reviewed and denied.
+ * Matches any deny variant: "deny", "hook_deny_iteration", "hook_deny_final".
+ */
+export function wasPlanPreviouslyDenied(
+  sessionId: string,
+  planHash: string,
+  projectRoot: string,
+): boolean {
+  const ccNative = getCcNativeState(sessionId, projectRoot);
+  if (!ccNative) return false;
+  const reviewState = ccNative.plan_review;
+  if (reviewState?.plan_hash !== planHash) return false;
+  const decision = reviewState.decision ?? "";
+  return decision === "deny" || decision.startsWith("hook_deny");
+}
+
+/**
+ * Mark this plan as reviewed (stores hash and decision in state.json).
+ */
+export function markPlanReviewed(
+  sessionId: string,
+  planHash: string,
+  projectRoot: string,
+  hookName = "cc-native",
+  iterationState?: IterationState,
+  decision = "allow",
+): void {
+  try {
+    const ccNative = getCcNativeState(sessionId, projectRoot) ?? {};
+
+    const reviewData: PlanReviewState = {
+      plan_hash: planHash,
+      reviewed_at: nowIso(),
+      decision,
+    };
+
+    if (iterationState) {
+      reviewData.iteration = {
+        current: iterationState.current ?? 1,
+        max: iterationState.max ?? 1,
+        complexity: iterationState.complexity ?? "unknown",
+      };
+      const {history} = iterationState;
+      if (history && history.length > 0) {
+        const lastEntry = history.at(-1);
+        if (lastEntry) {
+          reviewData.iteration.latest_verdict = lastEntry.verdict ?? "unknown";
+        }
+      }
+    }
+
+    ccNative.plan_review = reviewData;
+
+    if (saveCcNativeState(sessionId, projectRoot, ccNative)) {
+      const iterInfo = iterationState
+        ? ` (iteration ${reviewData.iteration?.current ?? "?"}/${reviewData.iteration?.max ?? "?"})`
+        : "";
+      logInfo(hookName, `Saved plan review state (hash: ${planHash})${iterInfo}`);
+    } else {
+      logWarn(
+        hookName,
+        `Failed to save plan review state for session ${sessionId}`,
+      );
+    }
+  } catch (error: unknown) {
+    logWarn(hookName, `Failed to mark plan reviewed: ${error}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Questions Asked State
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if AskUserQuestion was called this session.
+ * Returns false on any error (fail-safe: allow feature to work).
+ */
+export function wasQuestionsAsked(
+  sessionId: string,
+  projectRoot: string,
+): boolean {
+  const ccNative = getCcNativeState(sessionId, projectRoot);
+  if (!ccNative) return false;
+  return ccNative.questions_asked?.asked === true;
+}
+
+/**
+ * Mark that AskUserQuestion was called. Returns true on success.
+ * Only stores timestamp, no user data.
+ */
+export function markQuestionsAsked(
+  sessionId: string,
+  projectRoot: string,
+): boolean {
+  try {
+    const ccNative = getCcNativeState(sessionId, projectRoot) ?? {};
+
+    ccNative.questions_asked = {
+      asked: true,
+      asked_at: nowIso(),
+    };
+
+    return saveCcNativeState(sessionId, projectRoot, ccNative);
+  } catch (error: unknown) {
+    logWarn("utils", `Failed to mark questions asked: ${error}`);
+    return false;
+  }
+}
+

package/dist/templates/cc-native/_cc-native/lib-ts/cli-output-parser.ts

@@ -0,0 +1,144 @@
+/**
+ * Unified Claude CLI output parser.
+ * Deduplicates identical logic from orchestrator.py and reviewers/agent.py.
+ * See cc-native-plan-review-spec.md §4.6
+ */
+
+import { parseJsonMaybe } from "./json-parser.js";
+import { logDebug, logError, logWarn } from "../../_shared/lib-ts/base/logger.js";
+
+/**
+ * Parse Claude CLI JSON output, handling various formats.
+ *
+ * Claude CLI can output in several formats:
+ * - Direct structured_output dict
+ * - Assistant message with StructuredOutput tool use
+ * - List of events with assistant messages
+ * - Raw text with embedded JSON (heuristic fallback)
+ *
+ * @param raw - Raw stdout from Claude CLI
+ * @param requireFields - Optional fields to validate in heuristic fallback
+ * @returns Parsed JSON dict or null if parsing failed
+ */
+export function parseCliOutput(
+  raw: string,
+  requireFields?: string[],
+): null | Record<string, unknown> {
+  try {
+    const result: unknown = JSON.parse(raw);
+
+    if (result !== null && typeof result === "object" && !Array.isArray(result)) {
+      const dict = result as Record<string, unknown>;
+
+      // Strategy 1: Direct structured_output key
+      if ("structured_output" in dict) {
+        logDebug("cli_parser", "Found structured_output in root dict");
+        return dict.structured_output as Record<string, unknown>;
+      }
+
+      // Strategy 1.5: Session result envelope (type: "result")
+      // When the model fails to call StructuredOutput, the CLI returns a
+      // session metadata object with type/subtype/duration_ms/usage/etc.
+      // but no structured_output key. Check for the `result` text field
+      // (model may have written review as text) and for error states.
+      if (dict.type === "result" || ("duration_ms" in dict && "session_id" in dict)) {
+        if (dict.is_error === true || (Array.isArray(dict.errors) && (dict.errors as unknown[]).length > 0)) {
+          logWarn("cli_parser", `CLI returned error result: ${JSON.stringify(dict.errors ?? "is_error=true")}`);
+          return null;
+        }
+        if (typeof dict.result === "string" && dict.result) {
+          logDebug("cli_parser", "Found result text in session envelope, attempting JSON extraction");
+          const extracted = parseJsonMaybe(dict.result as string, requireFields);
+          if (extracted) return extracted;
+          logWarn("cli_parser", "Session envelope result text contained no extractable JSON");
+        }
+        logDebug("cli_parser", "Session result envelope with no structured_output or extractable result");
+        return null;
+      }
+
+      // Strategy 2: Assistant message with StructuredOutput tool use
+      if (dict.type === "assistant") {
+        const message = dict.message as Record<string, unknown> | undefined;
+        const content = message?.content;
+        if (Array.isArray(content)) {
+          for (const item of content) {
+            if (
+              item !== null &&
+              typeof item === "object" &&
+              (item as Record<string, unknown>).name === "StructuredOutput"
+            ) {
+              logDebug(
+                "cli_parser",
+                "Found StructuredOutput in assistant message content",
+              );
+              return (item as Record<string, unknown>).input as Record<
+                string,
+                unknown
+              >;
+            }
+          }
+        }
+
+        logDebug(
+          "cli_parser",
+          "Assistant message found but no StructuredOutput tool use in content",
+        );
+      }
+    } else if (Array.isArray(result)) {
+      // Strategy 3: List of events with assistant messages
+      logDebug(
+        "cli_parser",
+        `Received list of ${(result as unknown[]).length} events, searching for assistant message`,
+      );
+      for (let i = 0; i < (result as unknown[]).length; i++) {
+        const event = (result as unknown[])[i];
+        if (event === null || typeof event !== "object") continue;
+
+        const dict = event as Record<string, unknown>;
+        if (dict.type === "assistant") {
+          const message = dict.message as Record<string, unknown> | undefined;
+          const content = message?.content;
+          if (Array.isArray(content)) {
+            for (const item of content) {
+              if (
+                item !== null &&
+                typeof item === "object" &&
+                (item as Record<string, unknown>).name === "StructuredOutput"
+              ) {
+                logDebug(
+                  "cli_parser",
+                  `Found StructuredOutput in event[${i}] assistant message`,
+                );
+                return (item as Record<string, unknown>).input as Record<
+                  string,
+                  unknown
+                >;
+              }
+            }
+          }
+        }
+      }
+
+      logDebug(
+        "cli_parser",
+        "No StructuredOutput found in any assistant message in event list",
+      );
+    }
+  } catch (error: unknown) {
+    if (error instanceof SyntaxError) {
+      logWarn("cli_parser", `JSON decode error: ${error.message}`);
+    } else {
+      logError(
+        "cli_parser",
+        `Unexpected error during structured parsing: ${error}`,
+      );
+    }
+  }
+
+  // Strategy 4: Heuristic {…} extraction fallback
+  logDebug(
+    "cli_parser",
+    "No structured output found, falling back to heuristic JSON extraction",
+  );
+  return parseJsonMaybe(raw, requireFields);
+}

package/dist/templates/cc-native/_cc-native/lib-ts/config.ts

@@ -0,0 +1,57 @@
+/**
+ * Configuration loading for cc-native plan review.
+ * See cc-native-plan-review-spec.md §4.4
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import type { DisplaySettings, PlanReviewConfig } from "./types.js";
+import { DEFAULT_DISPLAY } from "./types.js";
+import { logWarn } from "../../_shared/lib-ts/base/logger.js";
+
+/**
+ * Load full CC-Native config from _cc-native/plan-review.config.json.
+ */
+export function loadConfig(projectDir: string): PlanReviewConfig {
+  const settingsPath = path.join(
+    projectDir,
+    "_cc-native",
+    "plan-review.config.json",
+  );
+
+  if (!fs.existsSync(settingsPath)) {
+    return {};
+  }
+
+  try {
+    const raw = fs.readFileSync(settingsPath, "utf8");
+    return JSON.parse(raw) as PlanReviewConfig;
+  } catch (error: unknown) {
+    logWarn("cc-native", `Failed to load config: ${error}`);
+    return {};
+  }
+}
+
+/**
+ * Get display settings, checking section-specific first, then root.
+ */
+export function getDisplaySettings(
+  config: PlanReviewConfig,
+  section: string,
+): DisplaySettings {
+  const sectionConfig = config[section];
+  const sectionDisplay =
+    sectionConfig && typeof sectionConfig === "object"
+      ? ((sectionConfig as Record<string, unknown>).display as
+          | Partial<DisplaySettings>
+          | undefined) ?? {}
+      : {};
+  const rootDisplay = config.display ?? {};
+
+  return {
+    ...DEFAULT_DISPLAY,
+    ...rootDisplay,
+    ...sectionDisplay,
+  };
+}

package/dist/templates/cc-native/_cc-native/lib-ts/constants.ts

@@ -0,0 +1,83 @@
+/**
+ * Security and configuration constants for cc-native plan review.
+ * See cc-native-plan-review-spec.md §4.15
+ */
+
+import * as os from "node:os";
+import * as path from "node:path";
+
+// ---------------------------------------------------------------------------
+// Feature Flags
+// ---------------------------------------------------------------------------
+
+/** Enable atomic writes for plan state files (env: CC_NATIVE_ROBUST_WRITES) */
+export const ENABLE_ROBUST_PLAN_WRITES =
+  (process.env.CC_NATIVE_ROBUST_WRITES ?? "true").toLowerCase() === "true";
+
+/** Enable plan review notifications (env: CC_NATIVE_NOTIFICATIONS) */
+export const ENABLE_PLAN_NOTIFICATIONS =
+  (process.env.CC_NATIVE_NOTIFICATIONS ?? "false").toLowerCase() === "true";
+
+// ---------------------------------------------------------------------------
+// Security Constants
+// ---------------------------------------------------------------------------
+
+/** Default plans directory */
+export const PLANS_DIR = path.join(os.homedir(), ".claude", "plans");
+
+/** Maximum plan path length */
+export const MAX_PLAN_PATH_LENGTH = 4096;
+
+/** Maximum error file size (10KB) */
+export const MAX_ERROR_FILE_SIZE = 10 * 1024;
+
+// ---------------------------------------------------------------------------
+// Performance Constants
+// ---------------------------------------------------------------------------
+
+/** Fast-fail: 2 attempts max */
+export const MAX_RETRY_ATTEMPTS = 2;
+
+/** Backoff schedule: 0.5s, 1s */
+export const RETRY_BACKOFF_MS = [500, 1000];
+
+/** 3 seconds total, well under 5s hook timeout */
+export const MAX_TOTAL_RETRY_TIME_MS = 3000;
+
+// ---------------------------------------------------------------------------
+// Path Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate and sanitize plan path to prevent traversal attacks.
+ * Throws ValueError if path is invalid, too long, or outside allowed directory.
+ */
+export function validatePlanPath(planPath: string): string {
+  // Input validation
+  if (!planPath || planPath.length > MAX_PLAN_PATH_LENGTH) {
+    throw new Error(
+      `Invalid plan path length: ${planPath ? planPath.length : 0}`,
+    );
+  }
+
+  if (planPath.includes("\u0000")) {
+    throw new Error("Null bytes not allowed in path");
+  }
+
+  // Normalize and resolve to absolute canonical path
+  let resolved: string;
+  try {
+    resolved = path.resolve(planPath);
+  } catch (error: unknown) {
+    throw new Error(`Path resolution failed: ${error}`);
+  }
+
+  // Verify path is within allowed directory (case-insensitive on Windows)
+  const resolvedLower = resolved.toLowerCase().replaceAll('\\', "/");
+  const plansDirLower = PLANS_DIR.toLowerCase().replaceAll('\\', "/");
+  if (!resolvedLower.startsWith(plansDirLower)) {
+    throw new Error(`Path outside allowed directory: ${PLANS_DIR}`);
+  }
+
+  return resolved;
+}

package/dist/templates/cc-native/_cc-native/lib-ts/corroboration.ts

@@ -0,0 +1,115 @@
+/**
+ * Corroboration-based verdict computation for plan review.
+ *
+ * Replaces the old per-verdict aggregation with proportional thresholding:
+ * high-severity issues in a dimension only block when the total count
+ * exceeds 2× the number of distinct agents contributing to that dimension.
+ *
+ * **Why proportional thresholding:**
+ * The agent pool has dimensional imbalance (e.g., 10 completeness agents vs
+ * 1 maintainability agent). A fixed "2+ agents agree = block" would mean
+ * any 2 completeness agents always block. Proportional scaling (issues > 2×agents)
+ * sets a fair bar regardless of how many agents focus on each dimension.
+ *
+ * **Convergence problem this solves:**
+ * Agents with opposing philosophies (simplicity-guardian vs completeness-gaps)
+ * produce contradictory high-severity issues. Because the old system treated
+ * every agent's finding as independently authoritative, plans oscillated —
+ * addressing one agent's feedback triggered the opposing agent.
+ *
+ * **Revert path:** Change one line in cc-native-plan-review.ts back to
+ * `computeReviewDecision(allVerdicts)`. Old function kept in verdict.ts.
+ */
+
+import type {
+  ReviewerResult,
+  ReviewIssue,
+  IssueDimension,
+  CorroborationResult,
+  CorroboratedGroup,
+  SoloFinding,
+} from "./types.js";
+
+/**
+ * Compute a corroboration-based review decision from all reviewer results.
+ *
+ * Algorithm:
+ * 1. Collect all high-severity issues with a `dimension` field
+ * 2. Group by dimension, tracking distinct agent names per group
+ * 3. For each dimension: block if `issues.length > 2 × agentCount`
+ * 4. Issues without `dimension` are unclassified (never block)
+ * 5. Non-high issues are ignored (informational only)
+ *
+ * @param allResults - Map of reviewer name → ReviewerResult (CLI + agent)
+ * @returns CorroborationResult with blocking groups, solo findings, and verdict
+ */
+export function computeCorroboratedDecision(
+  allResults: Record<string, ReviewerResult>,
+): CorroborationResult {
+  // Accumulator: dimension → { issues, agentNames }
+  const dimMap = new Map<
+    IssueDimension,
+    {
+      issues: Array<{ agent: string; issue: ReviewIssue }>;
+      agentNames: Set<string>;
+    }
+  >();
+
+  const unclassified: Array<{ agent: string; issue: ReviewIssue }> = [];
+
+  for (const [agentName, result] of Object.entries(allResults)) {
+    if (!result.data) continue;
+    const issues = result.data.issues as ReviewIssue[] | undefined;
+    if (!Array.isArray(issues)) continue;
+
+    for (const issue of issues) {
+      // Only high-severity issues participate in corroboration
+      if (issue.severity !== "high") continue;
+
+      // Issues without dimension are unclassified — cannot block
+      if (!issue.dimension) {
+        unclassified.push({ agent: agentName, issue });
+        continue;
+      }
+
+      let group = dimMap.get(issue.dimension);
+      if (!group) {
+        group = { issues: [], agentNames: new Set() };
+        dimMap.set(issue.dimension, group);
+      }
+      group.issues.push({ agent: agentName, issue });
+      group.agentNames.add(agentName);
+    }
+  }
+
+  const blocking: CorroboratedGroup[] = [];
+  const solo: SoloFinding[] = [];
+
+  for (const [dimension, group] of dimMap) {
+    const agentCount = group.agentNames.size;
+    const threshold = 2 * agentCount;
+
+    if (group.issues.length > threshold) {
+      blocking.push({
+        dimension,
+        issues: group.issues,
+        agentCount,
+        threshold,
+      });
+    } else {
+      solo.push({
+        dimension,
+        issues: group.issues,
+        agentCount,
+        threshold,
+      });
+    }
+  }
+
+  return {
+    blocking,
+    solo,
+    unclassified,
+    verdict: blocking.length > 0 ? "fail" : "pass",
+  };
+}

package/dist/templates/cc-native/_cc-native/lib-ts/debug.ts

@@ -0,0 +1,80 @@
+/**
+ * Per-context debug logging for cc-native hooks.
+ * Thin delegation layer over the unified logger.
+ * See cc-native-plan-review-spec.md §4.13
+ *
+ * Can be disabled via CCNATIVE_DEBUG_DISABLE=1 environment variable.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { hookLog } from "../../_shared/lib-ts/base/logger.js";
+
+/** Feature flag — set CCNATIVE_DEBUG_DISABLE=1 to turn off */
+const DEBUG_ENABLED = !["1", "true", "yes"].includes(
+  (process.env.CCNATIVE_DEBUG_DISABLE ?? "").toLowerCase(),
+);
+
+/**
+ * Get or create debug directory within context folder.
+ */
+export function getDebugDir(contextPath: string): string {
+  const debugDir = path.join(contextPath, "debug");
+  fs.mkdirSync(debugDir, { recursive: true });
+  return debugDir;
+}
+
+/**
+ * Write a debug log entry. Delegates to unified logger.
+ */
+export function debugLog(
+  contextPath: string,
+  sessionName: string,
+  component: string,
+  message: string,
+  data?: unknown,
+): void {
+  if (!DEBUG_ENABLED) return;
+
+  hookLog("debug", sessionName, message, {
+    component,
+    data,
+  });
+}
+
+/**
+ * Log raw output (stdout, stderr, etc). Delegates to unified logger.
+ */
+export function debugRaw(
+  contextPath: string,
+  sessionName: string,
+  component: string,
+  label: string,
+  raw: string,
+  maxLen = 10_000,
+): void {
+  if (!DEBUG_ENABLED) return;
+
+  const truncated = raw.length > maxLen ? raw.slice(0, maxLen) : raw;
+  const suffix =
+    raw.length > maxLen ? ` [TRUNCATED from ${raw.length} chars]` : "";
+
+  hookLog("debug", sessionName, `${label}${suffix}: ${truncated}`, {
+    component,
+  });
+}
+
+/**
+ * Remove debug folder during context archive.
+ */
+export function cleanupDebugFolder(contextPath: string): void {
+  try {
+    const debugDir = path.join(contextPath, "debug");
+    if (fs.existsSync(debugDir)) {
+      fs.rmSync(debugDir, { recursive: true, force: true });
+    }
+  } catch {
+    // Best effort cleanup
+  }
+}