@mirnoorata/codexa 0.2.1 → 0.3.0

package/integrations/claude-code/commands/codexa-brief.md

@@ -0,0 +1,14 @@
+---
+description: Get a Codexa task brief for the current dirty tree + a user task
+argument-hint: "<task description>"
+disable-model-invocation: true
+allowed-tools: Bash(bash:*)
+---
+
+Ask Codexa for a focused task brief. This is the first call before any
+non-trivial codexa-wired edit. It bundles impact, risks, covering tests,
+freshness, read-first files, relationship evidence where available, quality
+signals, and structured `nextTools` for the stated task plus the existing dirty
+diff.
+
+!`bash "${CLAUDE_PLUGIN_ROOT}/scripts/cmd/brief.sh" "$ARGUMENTS"`

package/integrations/claude-code/commands/codexa-impact.md

@@ -0,0 +1,14 @@
+---
+description: Show Codexa blast-radius impact for a file/symbol, or diff-impact when no argument
+argument-hint: "[path or symbol]"
+disable-model-invocation: true
+allowed-tools: Bash(bash:*)
+---
+
+Show Codexa impact evidence. With an argument, query `impact` for that file or
+symbol. Without an argument, show `diff-impact` for the current dirty tree.
+Relationship-backed results may include edge evidence ids, confidence labels,
+stale/degraded flags, and structured next Codexa tools for symbol context,
+change planning, or targeted tests.
+
+!`bash "${CLAUDE_PLUGIN_ROOT}/scripts/cmd/impact.sh" "$ARGUMENTS"`

package/integrations/claude-code/commands/codexa-plan.md

@@ -0,0 +1,20 @@
+---
+description: Save a Codexa change-plan snapshot before editing concrete files
+argument-hint: '"<task>" [file ...]'
+allowed-tools: Bash(bash:*)
+---
+
+Save a Codexa change-plan snapshot so the post-edit review can compute drift
+afterward. Quote the task so it is parsed as a single argument, then list the
+files you intend to edit. The saved snapshot includes planned-test provenance,
+verification recipes, freshness, and dirty-file hashes so the later review can
+distinguish trusted coverage from degraded legacy or stale evidence.
+
+Examples:
+
+```
+/codexa-plan "fix auth bug" src/auth.py
+/codexa-plan "redesign frame header" web/src/App.tsx web/src/styles.css
+```
+
+!`bash "${CLAUDE_PLUGIN_ROOT}/scripts/cmd/plan.sh" "$ARGUMENTS"`

package/integrations/claude-code/commands/codexa-review.md

@@ -0,0 +1,23 @@
+---
+description: Run Codexa post-edit review against the saved change-plan snapshot
+argument-hint: "[--change-type <type>] [--ran-test <path> ...] [--ran-command <cmd> ...]"
+allowed-tools: Bash(bash:*)
+---
+
+Compare the current dirty tree against the saved Codexa change-plan snapshot.
+Reports tests still unaccounted for, drift signals, and known gaps. Saved
+planned tests now carry provenance; legacy, stale, or scope-mismatched snapshot
+tests are reported as degraded instead of silently trusted. Passing structured
+command reports lets Codexa account for verification and persist compact local
+outcomes for future visible ranking/test boosts.
+
+Allowlisted flags (others are rejected): `--change-type`, `--ran-test`, `--ran-command`, `--ran-command-report`, `--waive-check`, `--waiver`, `--file`, `--symbol`, `--budget`, `--limit`, `--snippets`, `--no-snippets`, `--auto-refresh`, `--no-auto-refresh`, `--task-id`.
+
+Common use:
+
+```
+/codexa-review --change-type style
+/codexa-review --change-type behavior --ran-test tests/test_queue.py --ran-command "pytest tests/"
+```
+
+!`bash "${CLAUDE_PLUGIN_ROOT}/scripts/cmd/review.sh" "$ARGUMENTS"`

package/integrations/claude-code/commands/codexa-status.md

@@ -0,0 +1,10 @@
+---
+description: Show Codexa index freshness for the current repo
+argument-hint: ""
+disable-model-invocation: true
+allowed-tools: Bash(bash:*)
+---
+
+Show the Codexa index freshness, commit, indexed-at, and dirty-file count for the repo you are focused on. Return the output verbatim.
+
+!`bash "${CLAUDE_PLUGIN_ROOT}/scripts/cmd/status.sh"`

package/integrations/claude-code/hooks/hooks.json

@@ -0,0 +1,39 @@
+{
+  "description": "Codexa integration for Claude Code.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/session-start.sh\"",
+            "timeout": 6
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/pre-edit.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/stop.sh\"",
+            "timeout": 35
+          }
+        ]
+      }
+    ]
+  }
+}

package/integrations/claude-code/scripts/cmd/brief.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -u
+CMD_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+# shellcheck source=lib.sh
+. "$CMD_DIR/lib.sh"
+
+raw_args="${1-}"
+if [[ -z "$raw_args" ]]; then
+  printf 'Usage: /codexa-brief <task description>\n' >&2
+  exit 2
+fi
+
+# Task may include shell metacharacters; treat the whole string as the task.
+task="$raw_args"
+
+repo="$(cmd_require_codexa_repo)" || exit 1
+cmd_require_codexa_cli
+exec "$NODE_BIN" "$CODEXA_CLI" brief "$repo" --task "$task" --diff

package/integrations/claude-code/scripts/cmd/impact.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -u
+CMD_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+# shellcheck source=lib.sh
+. "$CMD_DIR/lib.sh"
+
+raw_args="${1-}"
+
+repo="$(cmd_require_codexa_repo)" || exit 1
+cmd_require_codexa_cli
+
+if [[ -z "$raw_args" ]]; then
+  exec "$NODE_BIN" "$CODEXA_CLI" diff-impact "$repo"
+fi
+
+declare -a tokens
+if ! cmd_shlex_split "$raw_args" tokens; then
+  exit 2
+fi
+
+if [[ ${#tokens[@]} -ne 1 ]]; then
+  printf 'Usage: /codexa-impact [path or symbol]\n' >&2
+  exit 2
+fi
+
+target="${tokens[0]}"
+cmd_validate_path_token "$target"
+
+# If the argument resolves to a real file (relative to repo or absolute),
+# treat it as a path; otherwise fall back to --symbol.
+if [[ -e "$repo/$target" ]] || [[ -e "$target" ]]; then
+  exec "$NODE_BIN" "$CODEXA_CLI" impact "$repo" --file "$target"
+else
+  exec "$NODE_BIN" "$CODEXA_CLI" impact "$repo" --symbol "$target"
+fi

package/integrations/claude-code/scripts/cmd/lib.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# Shared helpers for the /codexa-* slash-command implementations.
+#
+# Every slash-command `.md` file passes the raw "$ARGUMENTS" string as the
+# single first positional argument. We do NOT eval it or let the shell
+# word-split it — shlex handles quoting and shell metacharacters safely.
+
+set -u
+
+CMD_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+CMD_LIB_INTEGRATION_ROOT="$(cd "$CMD_LIB_DIR/../.." && pwd -P)"
+# shellcheck source=../lib/codexa-repo.sh
+. "$CMD_LIB_INTEGRATION_ROOT/scripts/lib/codexa-repo.sh"
+
+# Populate a bash array from shell-like tokenization of a single string.
+# Usage: cmd_shlex_split "quoted string \"with escapes\"" arr_name
+# After the call, ${arr_name[@]} holds the parsed tokens. Tokens may include
+# newlines/tabs — we use a NUL delimiter end-to-end. Returns 2 on malformed
+# input (unbalanced quotes, etc.), with the error written to stderr.
+cmd_shlex_split() {
+  local raw="${1:-}"
+  # No `local -n` nameref: that is bash 4.3+, and stock macOS ships bash
+  # 3.2. The array name is allowlist-validated before any eval so untrusted
+  # input can never reach the evaluated identifier.
+  local arr_name="${2:-}"
+  case "$arr_name" in
+    "" | *[!a-zA-Z0-9_]*) return 2 ;;
+  esac
+  eval "$arr_name=()"
+  [[ -z "$raw" ]] && return 0
+  local tokens_file err_file
+  tokens_file="$(mktemp)" || return 2
+  err_file="$(mktemp)" || { rm -f "$tokens_file"; return 2; }
+  python3 - "$raw" >"$tokens_file" 2>"$err_file" <<'PY'
+import shlex, sys
+try:
+    tokens = shlex.split(sys.argv[1])
+except ValueError as exc:
+    sys.stderr.write("argument parse error: " + str(exc) + "\n")
+    sys.exit(2)
+for t in tokens:
+    sys.stdout.write(t)
+    sys.stdout.write("\0")
+PY
+  local rc=$?
+  if [[ $rc -ne 0 ]]; then
+    cat "$err_file" >&2
+    rm -f "$tokens_file" "$err_file"
+    return "$rc"
+  fi
+  rm -f "$err_file"
+  local token
+  while IFS= read -r -d '' token; do
+    eval "$arr_name+=(\"\$token\")"
+  done <"$tokens_file"
+  rm -f "$tokens_file"
+  return 0
+}
+
+# Resolve the target codexa-wired repo for a slash command.
+#
+# Resolution order:
+#   (1) Walk up from PWD looking for .codex/config.toml (existing behavior).
+#   (2) If no ancestor is wired, scan direct children of PWD for wired repos.
+#       If exactly one, auto-pick it and note the choice on stderr so the
+#       user sees which repo the command ran against. If more than one,
+#       error with the list so the user can disambiguate by cd-ing in.
+#
+# Writes the repo root to stdout and returns 0 on success. On failure writes
+# a diagnostic to stderr and returns 1 — callers use `|| exit 1` in command
+# substitution so the parent script actually exits.
+cmd_require_codexa_repo() {
+  local repo
+  repo="$(claudio_find_codexa_repo "$PWD")"
+  if [[ -n "$repo" ]]; then
+    printf '%s' "$repo"
+    return 0
+  fi
+
+  local -a children=()
+  local line
+  while IFS= read -r line; do
+    [[ -z "$line" ]] && continue
+    children+=("$line")
+  done < <(claudio_list_child_codexa_repos "$PWD")
+
+  case "${#children[@]}" in
+    0)
+      printf 'No codexa-wired repo (.codex/config.toml) found from %s.\n' "$PWD" >&2
+      return 1
+      ;;
+    1)
+      printf '[codexa] no wired repo at %s; auto-selected sole child: %s\n' \
+        "$PWD" "${children[0]}" >&2
+      printf '%s' "${children[0]}"
+      return 0
+      ;;
+    *)
+      printf 'Ambiguous codexa target: %s has %d wired child repos.\n' \
+        "$PWD" "${#children[@]}" >&2
+      printf 'cd into one of these and re-run:\n' >&2
+      local child
+      for child in "${children[@]}"; do
+        printf '  - %s\n' "$child" >&2
+      done
+      return 1
+      ;;
+  esac
+}
+
+# Require a usable codexa CLI and print a clear error if missing.
+cmd_require_codexa_cli() {
+  if ! claudio_codexa_available; then
+    printf 'codexa CLI not available at %s (NODE=%s).\n' "$CODEXA_CLI" "$NODE_BIN" >&2
+    exit 127
+  fi
+}
+
+# Reject tokens that look like path-traversal or obvious shell injection
+# before passing them through to --file flags. Call once per user-supplied
+# file path. We do not try to sandbox — just block the dumb cases.
+cmd_validate_path_token() {
+  local tok="${1:-}"
+  if [[ -z "$tok" ]]; then
+    return 0
+  fi
+  case "$tok" in
+    *$'\n'*|*$'\r'*|*$'\t'*)
+      printf 'rejecting path with control character: %q\n' "$tok" >&2
+      exit 2
+      ;;
+  esac
+  # Allow relative .. under repo root (valid monorepo paths may include it)
+  # but disallow an absolute path outside known workspace, home, or repo roots.
+  return 0
+}

package/integrations/claude-code/scripts/cmd/plan.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+set -u
+CMD_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+# shellcheck source=lib.sh
+. "$CMD_DIR/lib.sh"
+
+raw_args="${1-}"
+if [[ -z "$raw_args" ]]; then
+  cat >&2 <<'USAGE'
+Usage: /codexa-plan "<task>" [file ...]
+
+The task must be a quoted string. Additional tokens are treated as file
+paths to snapshot. Examples:
+
+  /codexa-plan "fix auth bug" src/auth.py
+  /codexa-plan "redesign frame header" web/src/App.tsx web/src/styles.css
+USAGE
+  exit 2
+fi
+
+declare -a tokens
+if ! cmd_shlex_split "$raw_args" tokens; then
+  exit 2
+fi
+
+if [[ ${#tokens[@]} -eq 0 ]]; then
+  printf 'Parsed zero tokens from arguments.\n' >&2
+  exit 2
+fi
+
+task="${tokens[0]}"
+files=("${tokens[@]:1}")
+
+if [[ -z "$task" ]]; then
+  printf 'First argument (task description) must be non-empty.\n' >&2
+  exit 2
+fi
+
+# Validate file tokens BEFORE touching codexa.
+for f in "${files[@]}"; do
+  cmd_validate_path_token "$f"
+done
+
+repo="$(cmd_require_codexa_repo)" || exit 1
+cmd_require_codexa_cli
+
+cli_args=(change-plan "$repo" --task "$task" --save-snapshot)
+for f in "${files[@]}"; do
+  cli_args+=(--file "$f")
+done
+
+exec "$NODE_BIN" "$CODEXA_CLI" "${cli_args[@]}"

package/integrations/claude-code/scripts/cmd/review.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+set -u
+CMD_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+# shellcheck source=lib.sh
+. "$CMD_DIR/lib.sh"
+
+raw_args="${1-}"
+
+repo="$(cmd_require_codexa_repo)" || exit 1
+cmd_require_codexa_cli
+
+if [[ ! -f "$repo/.codex/cache/codexa-tasks/latest.json" ]]; then
+  printf 'No change-plan snapshot found at %s/.codex/cache/codexa-tasks/latest.json.\nRun /codexa-plan first.\n' "$repo" >&2
+  exit 1
+fi
+
+declare -a tokens
+if ! cmd_shlex_split "$raw_args" tokens; then
+  exit 2
+fi
+
+# Only allow a known flag set through. The CLI has many flags; we allow
+# the post-edit-relevant ones and refuse anything else so a stray argument
+# can't slip a shell metachar or an unknown subcommand.
+allowed_flags=(--change-type --ran-test --ran-command --ran-command-report \
+               --waive-check --waiver --file --symbol --budget --limit \
+               --snippets --no-snippets --auto-refresh --no-auto-refresh \
+               --task-id)
+is_allowed() {
+  local candidate="$1"
+  for f in "${allowed_flags[@]}"; do
+    if [[ "$candidate" == "$f" ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+i=0
+cli_args=(post-edit-review "$repo")
+while [[ $i -lt ${#tokens[@]} ]]; do
+  tok="${tokens[$i]}"
+  if [[ "$tok" == --* ]]; then
+    if ! is_allowed "$tok"; then
+      printf 'refusing unknown flag %q\n' "$tok" >&2
+      exit 2
+    fi
+    cli_args+=("$tok")
+    # flags with a value: consume next token too unless it's the start of
+    # another flag or we're at end of list.
+    if [[ $((i + 1)) -lt ${#tokens[@]} ]]; then
+      next="${tokens[$((i + 1))]}"
+      if [[ "$next" != --* ]]; then
+        cli_args+=("$next")
+        i=$((i + 2))
+        continue
+      fi
+    fi
+    i=$((i + 1))
+  else
+    printf 'positional arguments are not supported for /codexa-review: %q\n' "$tok" >&2
+    exit 2
+  fi
+done
+
+exec "$NODE_BIN" "$CODEXA_CLI" "${cli_args[@]}"

package/integrations/claude-code/scripts/cmd/status.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# /codexa-status
+#
+# Single-repo case: walks up from PWD for an ancestor with .codex/config.toml
+# and runs `codexa status` on it. That matches the common "terminal is inside
+# the repo" workflow.
+#
+# Multi-repo case: when PWD is above a set of wired children (e.g. an IDE
+# opened at a workspace root with two sibling projects both wired via
+# `codexa init`), we fan out and run `codexa status` on every wired child
+# rather than erroring on ambiguity. The IDE-workspace-root view is
+# "show me everything."
+set -u
+CMD_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+# shellcheck source=lib.sh
+. "$CMD_DIR/lib.sh"
+
+cmd_require_codexa_cli
+
+ancestor="$(claudio_find_codexa_repo "$PWD")"
+if [[ -n "$ancestor" ]]; then
+  exec "$NODE_BIN" "$CODEXA_CLI" status "$ancestor"
+fi
+
+declare -a children=()
+while IFS= read -r line; do
+  [[ -z "$line" ]] && continue
+  children+=("$line")
+done < <(claudio_list_child_codexa_repos "$PWD")
+
+case "${#children[@]}" in
+  0)
+    printf 'No codexa-wired repo (.codex/config.toml) found from %s.\n' "$PWD" >&2
+    exit 1
+    ;;
+  1)
+    exec "$NODE_BIN" "$CODEXA_CLI" status "${children[0]}"
+    ;;
+  *)
+    printf '[codexa] no wired repo at %s; fanning out status across %d wired children:\n' \
+      "$PWD" "${#children[@]}" >&2
+    rc=0
+    for child in "${children[@]}"; do
+      printf '=== %s ===\n' "$(claudio_display_path "$child")"
+      if ! "$NODE_BIN" "$CODEXA_CLI" status "$child"; then
+        rc=1
+      fi
+      printf '\n'
+    done
+    exit "$rc"
+    ;;
+esac

package/integrations/claude-code/scripts/codexa-mcp.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// MCP launcher for the Codexa Claude Code plugin. Claude Code starts plugin
+// MCP servers with the session's project directory as cwd; this script
+// resolves the repository from there, resolves the Codexa CLI (explicit
+// override, walked-up package/checkout dist, global install), and execs
+// `codexa serve` over stdio. Self-contained on purpose: when the plugin is
+// installed from a marketplace only this directory is copied, so it cannot
+// reference files outside the plugin root.
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const explicitRepo = process.argv[2];
+const autoRefresh = process.env.CODEXA_PLUGIN_AUTO_REFRESH !== "0";
+const repoRoot = resolveRepoRoot(explicitRepo);
+if (!repoRoot) {
+  console.error(
+    "codexa plugin MCP could not find a git repository. Set CODEXA_REPO to the repository root or start Claude Code inside the repository."
+  );
+  process.exit(1);
+}
+
+const launch = resolveCodexaLaunch(repoRoot, autoRefresh);
+const child = spawn(launch.command, launch.args, {
+  cwd: repoRoot,
+  stdio: ["inherit", "inherit", "inherit"],
+  env: process.env
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 1);
+});
+
+child.on("error", (error) => {
+  console.error(`codexa plugin MCP failed to start ${launch.command}: ${error.message}`);
+  process.exit(1);
+});
+
+function resolveCodexaLaunch(repoRoot, autoRefresh) {
+  // Claude Code has no client-side tool allowlist, so the profile is applied
+  // server-side. Default core matches `codexa init`'s default and the
+  // plugin's token-discipline pitch; CODEXA_PLUGIN_TOOLS=full widens it.
+  const toolProfile = process.env.CODEXA_PLUGIN_TOOLS === "full" ? "full" : "core";
+  const serveArgs = ["serve", repoRoot, autoRefresh ? "--auto-refresh" : "--no-auto-refresh", "--tools", toolProfile];
+  const overrideCli = process.env.CODEXA_CLI;
+  if (overrideCli && existsSync(overrideCli)) {
+    return { command: process.execPath, args: [overrideCli, ...serveArgs] };
+  }
+  // npm package layout: integrations/claude-code/scripts -> package root.
+  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+  const bundledCli = path.resolve(scriptDir, "../../../dist/cli.js");
+  if (existsSync(bundledCli)) {
+    return { command: process.execPath, args: [bundledCli, ...serveArgs] };
+  }
+  if (commandExists("codexa")) {
+    return { command: "codexa", args: serveArgs };
+  }
+  if (process.env.CODEXA_PLUGIN_ALLOW_NPX_FALLBACK === "1") {
+    return { command: "npx", args: ["-y", "@mirnoorata/codexa", ...serveArgs] };
+  }
+  console.error(
+    "codexa plugin MCP could not find the Codexa CLI. Install it with `npm install -g @mirnoorata/codexa`, set CODEXA_CLI to a dist/cli.js path, or set CODEXA_PLUGIN_ALLOW_NPX_FALLBACK=1 to allow npm registry fallback."
+  );
+  process.exit(1);
+}
+
+function commandExists(command) {
+  const probe = process.platform === "win32" ? "where" : "which";
+  try {
+    return spawnSync(probe, [command], { stdio: "ignore" }).status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function resolveRepoRoot(explicit) {
+  // Claude Code starts plugin MCP servers with the session's project
+  // directory as cwd; that is the authoritative signal. $PWD is deliberately
+  // NOT consulted — it is inherited shell state and can point at an
+  // unrelated repository.
+  const candidates = [explicit, process.env.CODEXA_REPO, process.env.CLAUDE_PROJECT_DIR, process.cwd()].filter(
+    (value) => typeof value === "string" && value.trim().length > 0
+  );
+  for (const candidate of candidates) {
+    const root = gitRoot(path.resolve(candidate));
+    if (root) {
+      return root;
+    }
+  }
+  return null;
+}
+
+function gitRoot(candidate) {
+  if (!existsSync(candidate)) {
+    return null;
+  }
+  const result = spawnSync("git", ["-C", candidate, "rev-parse", "--show-toplevel"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  if (result.status !== 0) {
+    return null;
+  }
+  const root = result.stdout.trim();
+  return root ? path.resolve(root) : null;
+}