aiwcli 0.10.2 → 0.11.0

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,124 @@
+/**
+ * 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 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/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
+  }
+}

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

@@ -0,0 +1,119 @@
+/**
+ * CC-Native plan review library — package entry point.
+ * Re-exports the public API from all modules.
+ */
+
+// Agent aggregation
+export {
+  aggregateAgents,
+  extractBody,
+  extractFrontmatter,
+} from "./aggregate-agents.js";
+
+// Artifacts
+export {
+  buildCombinedJson,
+  buildHighIssuesDocument,
+  buildInlineReviewSummary,
+  extractTopIssuesText,
+  formatCombinedMarkdown,
+  formatReviewMarkdown,
+  generateReviewIndex,
+  writeCombinedArtifacts,
+} from "./artifacts.js";
+
+// CC-native state
+export {
+  getCcNativeState,
+  isPlanAlreadyReviewed,
+  markPlanReviewed,
+  markQuestionsAsked,
+  saveCcNativeState,
+  wasPlanPreviouslyDenied,
+  wasQuestionsAsked,
+} from "./cc-native-state.js";
+
+// CLI output parsing
+export { parseCliOutput } from "./cli-output-parser.js";
+
+// Configuration
+export { getDisplaySettings, loadConfig } from "./config.js";
+
+// Constants & security
+export {
+  ENABLE_PLAN_NOTIFICATIONS,
+  ENABLE_ROBUST_PLAN_WRITES,
+  MAX_ERROR_FILE_SIZE,
+  MAX_PLAN_PATH_LENGTH,
+  MAX_RETRY_ATTEMPTS,
+  MAX_TOTAL_RETRY_TIME_MS,
+  PLANS_DIR,
+  RETRY_BACKOFF_MS,
+  validatePlanPath,
+} from "./constants.js";
+
+// Debug logging
+export { cleanupDebugFolder, debugLog, debugRaw, getDebugDir } from "./debug.js";
+
+// JSON parsing
+export { coerceToReview, parseJsonMaybe } from "./json-parser.js";
+
+// Orchestrator
+export { buildOrchestratorSchema, runOrchestrator } from "./orchestrator.js";
+
+// Reviewers
+export {
+  AgentReviewer,
+  CodexReviewer,
+  GeminiReviewer,
+  runAgentReview,
+  runCodexReview,
+  runGeminiReview,
+} from "./reviewers/index.js";
+
+// Iteration state
+export {
+  deleteState,
+  getIterationState,
+  getStateFilePath,
+  loadState,
+  saveStateToPlan,
+  shouldContinueIterating,
+  updateIterationState,
+} from "./state.js";
+
+// Types & schemas
+export type {
+  AgentConfig,
+  CcNativeState,
+  CombinedReviewResult,
+  ComplexityCategory,
+  DisplaySettings,
+  IterationEntry,
+  IterationState,
+  OrchestratorConfig,
+  OrchestratorResult,
+  PlanReviewConfig,
+  PlanReviewState,
+  QuestionsAskedState,
+  ReviewData,
+  ReviewDecision,
+  ReviewDecisionResult,
+  Reviewer,
+  ReviewerResult,
+  ReviewIssue,
+  ReviewOptions,
+  Verdict,
+} from "./types.js";
+
+export {
+  AGENT_REVIEW_PROMPT_PREFIX,
+  DEFAULT_DISPLAY,
+  DEFAULT_SANITIZATION,
+  ORCHESTRATOR_SCHEMA,
+  REVIEW_PROMPT_PREFIX,
+  REVIEW_SCHEMA,
+} from "./types.js";
+
+// Verdict aggregation
+export { computeReviewDecision, worstVerdict } from "./verdict.js";