@mirnoorata/codexa 0.2.0

package/dist/types.js

@@ -0,0 +1,12 @@
+export const VERIFICATION_PROVENANCE_SCHEMA_VERSION = 1;
+export const VERIFICATION_COMMAND_COVERAGE_CLASSIFIER_VERSION = "command-coverage-v3";
+export const VERIFICATION_COMMAND_ENVELOPE_RULESET_VERSION = "command-envelope-v2";
+export const VERIFICATION_LEDGER_VERSION = "verification-ledger-v2";
+export const CURRENT_VERIFICATION_PROVENANCE = {
+    schemaVersion: VERIFICATION_PROVENANCE_SCHEMA_VERSION,
+    commandCoverageClassifier: "codexa-command-coverage",
+    commandCoverageClassifierVersion: VERIFICATION_COMMAND_COVERAGE_CLASSIFIER_VERSION,
+    commandEnvelopeRulesetVersion: VERIFICATION_COMMAND_ENVELOPE_RULESET_VERSION,
+    verificationLedgerVersion: VERIFICATION_LEDGER_VERSION
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA41BA,MAAM,CAAC,MAAM,sCAAsC,GAAG,CAAU,CAAC;AACjE,MAAM,CAAC,MAAM,gDAAgD,GAAG,qBAAqB,CAAC;AACtF,MAAM,CAAC,MAAM,6CAA6C,GAAG,qBAAqB,CAAC;AACnF,MAAM,CAAC,MAAM,2BAA2B,GAAG,wBAAwB,CAAC;AAUpE,MAAM,CAAC,MAAM,+BAA+B,GAA2B;IACrE,aAAa,EAAE,sCAAsC;IACrD,yBAAyB,EAAE,yBAAyB;IACpD,gCAAgC,EAAE,gDAAgD;IAClF,6BAA6B,EAAE,6CAA6C;IAC5E,yBAAyB,EAAE,2BAA2B;CACvD,CAAC"}

package/dist/util.d.ts

@@ -0,0 +1,11 @@
+export declare function normalizePath(filePath: string): string;
+export declare function stableId(...parts: Array<string | number | undefined | null>): string;
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function uniqueSorted(values: Iterable<string>): string[];
+export declare function topBy<T>(items: T[], score: (item: T) => number, limit: number): T[];
+export declare function mapLimit<T, R>(items: T[], limit: number, mapper: (item: T) => Promise<R>): Promise<R[]>;
+export declare function relativeTo(base: string, target: string): string;
+export declare function formatPathLine(filePath: string, line?: number): string;
+export declare function escapeMarkdown(value: string): string;
+export declare function limitText(value: string, max?: number): string;
+export declare function isSubpath(candidate: string, parent: string): boolean;

package/dist/util.js

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+export function normalizePath(filePath) {
+    return filePath.split(path.sep).join("/");
+}
+export function stableId(...parts) {
+    const hash = createHash("sha1");
+    hash.update(parts.filter((part) => part !== undefined && part !== null).join("\0"));
+    return hash.digest("hex").slice(0, 16);
+}
+export function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+export function uniqueSorted(values) {
+    return [...new Set(values)].sort((a, b) => a.localeCompare(b));
+}
+export function topBy(items, score, limit) {
+    return [...items].sort((a, b) => score(b) - score(a) || stableSortKey(a).localeCompare(stableSortKey(b))).slice(0, limit);
+}
+export async function mapLimit(items, limit, mapper) {
+    const results = new Array(items.length);
+    let cursor = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (cursor < items.length) {
+            const index = cursor;
+            cursor += 1;
+            results[index] = await mapper(items[index]);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+function stableSortKey(item) {
+    if (item && typeof item === "object") {
+        const record = item;
+        for (const key of ["path", "qualifiedName", "name", "id"]) {
+            if (typeof record[key] === "string") {
+                return record[key];
+            }
+        }
+    }
+    return JSON.stringify(item);
+}
+export function relativeTo(base, target) {
+    return normalizePath(path.relative(base, target));
+}
+export function formatPathLine(filePath, line) {
+    return line ? `${filePath}:${line}` : filePath;
+}
+export function escapeMarkdown(value) {
+    return value.replaceAll("|", "\\|").replaceAll("\n", " ");
+}
+export function limitText(value, max = 2000) {
+    if (value.length <= max) {
+        return value;
+    }
+    return `${value.slice(0, max - 20)}\n... truncated ...`;
+}
+export function isSubpath(candidate, parent) {
+    const rel = path.relative(parent, candidate);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const CODEXA_VERSION: string;

package/dist/version.js

@@ -0,0 +1,5 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const packageJson = require("../package.json");
+export const CODEXA_VERSION = typeof packageJson.version === "string" && packageJson.version ? packageJson.version : "0.0.0";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAA0B,CAAC;AAExE,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,WAAW,CAAC,OAAO,KAAK,QAAQ,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@mirnoorata/codexa",
+  "version": "0.2.0",
+  "mcpName": "io.github.mirnoorata/codexa",
+  "description": "Codex-native codebase intelligence context compiler and query-only MCP server.",
+  "keywords": [
+    "codex",
+    "mcp",
+    "code-intelligence",
+    "symbol-search",
+    "impact-analysis",
+    "local-first",
+    "verification"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mirnoorata/codexa.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mirnoorata/codexa/issues"
+  },
+  "homepage": "https://github.com/mirnoorata/codexa#readme",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "codexa": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "plugins/codexa"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "node scripts/verify-source-hygiene.mjs && node scripts/verify-release-path.mjs && bash scripts/verify-codexa-publish.sh",
+    "audit": "npm audit --audit-level=moderate",
+    "privacy": "node scripts/verify-public-hygiene.mjs",
+    "privacy:history": "node scripts/verify-public-hygiene.mjs --history",
+    "privacy:release": "npm run privacy && npm run privacy:history",
+    "plugin:hygiene": "node scripts/verify-plugin-package.mjs",
+    "package:hygiene": "node scripts/verify-package-hygiene.mjs && npm run plugin:hygiene",
+    "smoke:package": "node scripts/package-install-smoke.mjs",
+    "benchmark:ci": "npm run build && node scripts/benchmark-hot-paths.mjs --output .codex/cache/codexa-benchmarks/latest.json",
+    "ci:extended": "npm run smoke:package && npm run benchmark:ci",
+    "public:snapshot-check": "node scripts/verify-public-snapshot.mjs",
+    "clean:private-artifacts": "node scripts/clean-private-artifacts.mjs",
+    "prepare:codera-parking": "node scripts/prepare-codera-parking-package.mjs && node scripts/verify-package-hygiene.mjs .local/release/codera",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run security:check",
+    "publish:codexa": "bash scripts/codexa-publish.sh",
+    "release:archive": "npm run check && git archive --format=tar.gz --output codexa-public-head.tar.gz HEAD",
+    "release:github:dry-run": "npm run build && node dist/cli.js github-release . --dry-run",
+    "release:github": "npm run security:check && node dist/cli.js github-release .",
+    "test": "npm run build && vitest run",
+    "test:schema": "vitest run tests/schema.test.ts",
+    "test:claude-code": "bash integrations/claude-code/tests/cmd-smoke.sh && bash integrations/claude-code/tests/hook-smoke.sh",
+    "check": "npm run typecheck && npm run lint && npm run privacy && npm run test:claude-code && npm test",
+    "security:check": "npm run check && npm run audit && npm run public:snapshot-check && npm run package:hygiene && npm run smoke:package",
+    "dev": "tsx src/cli.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "commander": "15.0.0",
+    "tree-sitter": "0.21.1",
+    "tree-sitter-python": "0.21.0",
+    "tree-sitter-typescript": "0.23.2",
+    "typescript": "6.0.3",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "25.6.2",
+    "tsx": "4.22.4",
+    "vitest": "4.1.8"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/plugins/codexa/.codex-plugin/plugin.json

@@ -0,0 +1,38 @@
+{
+  "name": "codexa",
+  "version": "0.1.0",
+  "description": "Codex-native codebase intelligence workflows, MCP setup, and edit accountability for repositories indexed by Codexa.",
+  "author": {
+    "name": "Codexa maintainers",
+    "url": "https://github.com/mirnoorata/codexa"
+  },
+  "homepage": "https://github.com/mirnoorata/codexa#readme",
+  "repository": "https://github.com/mirnoorata/codexa",
+  "license": "MIT",
+  "keywords": [
+    "codex",
+    "mcp",
+    "codebase-intelligence",
+    "task-brief",
+    "post-edit-review"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Codexa",
+    "shortDescription": "Use Codexa context packets, change plans, and post-edit reviews inside Codex.",
+    "longDescription": "Codexa packages a repository-focused Codex workflow: load task briefs before edits, save change-plan snapshots for non-trivial work, review drift after edits, and request targeted verification from the local Codexa MCP server.",
+    "developerName": "Codexa maintainers",
+    "category": "Productivity",
+    "capabilities": [
+      "Read"
+    ],
+    "websiteURL": "https://github.com/mirnoorata/codexa",
+    "defaultPrompt": [
+      "Use Codexa to brief this code change before editing.",
+      "Use Codexa to review the dirty tree against the saved change plan.",
+      "Use Codexa to recommend targeted tests for this task."
+    ],
+    "brandColor": "#2563EB"
+  }
+}

package/plugins/codexa/.mcp.json

@@ -0,0 +1,20 @@
+{
+  "mcpServers": {
+    "codexa": {
+      "command": "node",
+      "args": [
+        "./scripts/codexa-mcp.js"
+      ],
+      "env_vars": [
+        "CODEXA_REPO",
+        "CODEXA_FOCUSED_REPO",
+        "CODEXA_WORKSPACE_FOCUS_FILE",
+        "CODEX_WORKSPACE",
+        "CODEX_WORKSPACE_ROOT",
+        "CODEXA_PLUGIN_AUTO_REFRESH"
+      ],
+      "startup_timeout_sec": 20,
+      "tool_timeout_sec": 60
+    }
+  }
+}

package/plugins/codexa/scripts/codexa-mcp.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+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 or focused workspace. Set CODEXA_REPO to the repository root or run Codexa from inside the workspace."
+  );
+  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) {
+  const serveArgs = ["serve", repoRoot, autoRefresh ? "--auto-refresh" : "--no-auto-refresh"];
+  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 (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 bundled Codexa CLI. Reinstall the Codexa plugin package or set CODEXA_PLUGIN_ALLOW_NPX_FALLBACK=1 to allow npm registry fallback."
+  );
+  process.exit(1);
+}
+
+function resolveRepoRoot(explicit) {
+  const candidates = [
+    explicit,
+    process.env.CODEXA_REPO,
+    process.env.CODEXA_FOCUSED_REPO,
+    process.env.CODEX_WORKSPACE_ROOT,
+    process.env.CODEX_WORKSPACE,
+    process.env.PWD,
+    process.cwd()
+  ].filter((value) => typeof value === "string" && value.trim().length > 0);
+
+  for (const candidate of candidates) {
+    const resolved = path.resolve(candidate);
+    const root = gitRoot(resolved);
+    if (root) {
+      return root;
+    }
+    if (workspaceFocusFileExists(resolved)) {
+      return resolved;
+    }
+  }
+  return null;
+}
+
+function workspaceFocusFileExists(candidate) {
+  return focusFileCandidates(candidate).some((focusFile) => existsSync(focusFile));
+}
+
+function focusFileCandidates(candidate) {
+  return [process.env.CODEXA_WORKSPACE_FOCUS_FILE, path.join(candidate, ".codex", "WORKING.md")].filter(
+    (value) => typeof value === "string" && value.trim().length > 0
+  );
+}
+
+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;
+}

package/plugins/codexa/skills/codexa/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: codexa
+description: Use Codexa's repository context server for first-class hybrid semantic search, task briefs, change plans, post-edit reviews, dependency/workflow tracing, verification planning, and evidence review before or after code edits.
+---
+
+# Codexa Workflow
+
+Use this skill when a task involves understanding, editing, reviewing, or verifying a repository that has Codexa installed or available through the Codexa MCP server.
+
+## Operating Rules
+
+1. Resolve the active repository first. If the repo has `.codex/config.toml`, use the project-local Codexa MCP server. If the MCP server is unavailable, run the equivalent `codexa` CLI command from the repository.
+2. Primary Codexa path: `session_context -> search(if target unclear) -> task_brief -> change_plan(saveSnapshot) -> post_edit_review -> test_plan`.
+3. For broad tasks, call `session_context` first. If the target is unclear or `actionability` says `needs_target`, `raw_search_better`, or `raw_search_sufficient`, use first-class `search` or ask for an explicit target before planning edits.
+4. For code edits, debugging, reviews, or non-trivial refactors, call `search` first when the target is unclear; otherwise call `task_brief` before reading or editing source.
+5. For symbol-level changes, call `symbol_context` or `impact` when you need callers, callees, implementations, tests, risks, edge evidence, or the next exact Codexa tool.
+6. Before non-trivial edits, call `change_plan` with `saveSnapshot=true` so Codexa can compare the plan with the final dirty tree and planned-test provenance.
+7. After edits, call go-to `post_edit_review` before the final response and pass any commands or test reports that were actually run. Treat degraded snapshot tests as evidence to inspect or rerun, not as trusted coverage. MCP `post_edit_review` is review-only; AutoVerify execution is limited to the Codexa hook path when the user environment enables it.
+8. For workflow/runtime/API/rename/delete changes, use `workflow_path`, `callers`, `callees`, or `dependency_path` before editing shared surfaces.
+9. Finish with `test_plan` when the verification surface is unclear.
+
+## Thin Adapter Rules
+
+1. Keep host adapters thin. They should launch the shared Codexa MCP server or CLI and should not add independent planning, ranking, indexing, or source-editing behavior.
+2. Codexa MCP tools may write generated `.codex/` cache artifacts, but there must be no source-mutating MCP tool path.
+3. Do not add broad host-specific tools when the primary MCP path or an existing advanced tool can answer the need.
+
+## CLI Fallbacks
+
+Use these commands from the target repository when MCP is not available:
+
+```bash
+codexa session-context .
+codexa search . --query "<task, literal, or symbol>"
+codexa brief . --task "<task>"
+codexa explain . --symbol "<symbol_or_stable_id>"
+codexa impact . --symbol "<symbol_or_stable_id>"
+codexa change-plan . --task "<task>" --save-snapshot --task-id "<task_id>"
+codexa post-edit-review . --task-id "<task_id>" --ran-command "<command>"
+codexa test-plan .
+codexa serve . --transport http --host 127.0.0.1 --port 8729
+```
+
+Prefer `--task-id` for `post-edit-review` so Codexa can compare against the
+saved snapshot. Use `post-edit-review . --task "<task>" ...` only when no
+snapshot exists.
+
+Use `--no-auto-refresh` only when the host requires strict filesystem-read-only metadata. The default auto-refresh mode may update generated Codexa cache artifacts under `.codex/`, but it does not mutate source files.