codex-context-map 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Han-1413141
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+<div align="center">
+
+# Codex Context Map
+
+**Know what your agent reads.**
+
+An offline visual debugger for `AGENTS.md` discovery, overrides, and byte limits.
+
+[Live demo](https://han-1413141.github.io/codex-context-map/) · [简体中文](README.zh-CN.md) · [How it works](docs/semantics.md) · [Releases](https://github.com/Han-1413141/codex-context-map/releases)
+
+[![CI](https://github.com/Han-1413141/codex-context-map/actions/workflows/ci.yml/badge.svg)](https://github.com/Han-1413141/codex-context-map/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/codex-context-map)](https://www.npmjs.com/package/codex-context-map)
+![Node](https://img.shields.io/badge/node-%3E%3D20-087f6b)
+[![License: MIT](https://img.shields.io/badge/License-MIT-087f6b.svg)](LICENSE)
+
+[![Codex Context Map showing a real, interactive instruction chain for the fictional Northstar workspace](docs/assets/preview.png)](https://han-1413141.github.io/codex-context-map/)
+
+</div>
+
+You added an instruction. Codex still behaves differently. Is the file outside the launch directory? Is an override hiding it? Did the byte budget cut off the last paragraph?
+
+**Pick a directory and see the chain.** Switch directories to compare it. Lower the budget to reveal the cutoff. No account, API key, or model call required.
+
+## Try it in 10 seconds
+
+Open the **[interactive demo](https://han-1413141.github.io/codex-context-map/)** and click **Hidden override**, **Budget cutoff**, or **Empty override**. You can also open a project folder: the page processes instruction files on your device.
+
+Or inspect your repository with Node.js 20+:
+
+```bash
+npx codex-context-map . --html context-map.html
+```
+
+Open the generated `context-map.html` in your browser. It is a single, self-contained file that also works offline.
+
+```text
+CODEX CONTEXT MAP · northstar
+
+Launch directory: services/payments
+Project content: 1,024 / 1,024 bytes
+
+  loaded    AGENTS.md                                  (535/535 bytes)
+  loaded    services/AGENTS.md                         (264/264 bytes)
+  partial   services/payments/AGENTS.override.md       (225/748 bytes)
+  shadowed  services/payments/AGENTS.md → project:services/payments/AGENTS.override.md
+```
+
+This example comes from `npx codex-context-map --demo --max-bytes 1024`.
+
+## What you get
+
+| Feature | What it answers |
+| --- | --- |
+| Directory map | Which instruction chain is discovered from this launch directory? |
+| Override explanations | Which same-directory files are shadowed, including empty overrides? |
+| Byte budget simulator | Which file is truncated, and how much content is lost? |
+| Directory comparison | Which instruction sources are added, removed, or shared? |
+| Assembled preview | What text does this discovery model produce, in order? |
+| Portable HTML and JSON | Can I inspect the same snapshot offline or attach it to a bug report? |
+| CI check | Does the chosen instruction chain exceed its configured budget? |
+
+English and Chinese UI. No runtime dependencies. No background server. No telemetry or browser storage.
+
+## CLI examples
+
+```bash
+# Inspect the directory containing this file
+npx codex-context-map ./services/payments/handler.ts
+
+# Compare against another launch directory, relative to the detected root
+npx codex-context-map ./services/payments --compare apps/web
+
+# Match your Codex configuration explicitly
+npx codex-context-map . --max-bytes 65536 --fallback TEAM_GUIDE.md --fallback .agents.md
+
+# Global AGENTS files are opt-in
+npx codex-context-map . --global --html context-map.html
+
+# Portable JSON with the selected result; fail CI when content is cut off
+npx codex-context-map ./services/payments --json --check
+
+# Explore the bundled fictional workspace
+npx codex-context-map --demo --html demo.html
+```
+
+Run `npx codex-context-map --help` for all options. `--check` returns **0** without a cutoff, **1** with a cutoff, and **2** for invalid input or I/O failures. It checks the selected directory. Use one invocation per critical launch directory in CI. Existing HTML files are protected unless you pass `--force`.
+
+Without npm registry access, clone this repository and run `node bin/codex-context-map.js --demo`. No dependency installation is needed for the CLI. Release tarballs can also be installed with `npm install -g ./codex-context-map-0.1.0.tgz`.
+
+## A map with explicit boundaries
+
+This is a **static discovery preview for one trusted project**, not a live view of a Codex conversation. It follows a [pinned upstream implementation](docs/semantics.md), with its assumptions visible:
+
+- The CLI detects the nearest `.git` marker. Nested repositories form new boundaries. With no marker, only the launch directory is checked. `--root` supplies an explicit boundary.
+- `AGENTS.override.md` takes priority over `AGENTS.md`, then configured fallbacks. A later directory adds to the chain; it does not erase all parent text.
+- The project budget defaults to **32,768 content bytes**. Separators and optional global guidance are accounted for separately. This is not a token or billing estimate.
+- **Configuration is not read automatically.** Match `--max-bytes`, `--fallback` and `--root` to your actual setup. Global guidance needs `--global`.
+- Skills, MCP, hooks, account/thread instructions, system prompts, untrusted-project behavior, multiple environments and mid-session refresh are outside this model.
+- Natural-language conflicts and whether a model obeys instructions cannot be proven by this tool.
+
+The empty-file behavior in current source is more specific than the prose documentation. [See the exact rule, source reference, and test coverage.](docs/semantics.md)
+
+## Privacy
+
+The CLI reads instruction filenames and directory metadata. It does not read your credentials, conversation history, or source-file contents. Global files are opt-in. The browser has `connect-src 'none'` and does not upload imported files. The initial hosted page request is handled by GitHub Pages as usual.
+
+**Exports include instruction text and relative paths.** Review them before sharing; this tool does not redact secrets. The CLI skips symlinks with a warning. Browser folder pickers do not expose symlink metadata. Generated/dependency directories are excluded by default; use `--include-ignored` if needed. See [limits and exclusions](docs/semantics.md#scan-and-import-limits).
+
+## Development
+
+```bash
+git clone https://github.com/Han-1413141/codex-context-map.git
+cd codex-context-map
+npm ci
+npm run check
+npx playwright install chromium
+npm run test:browser
+```
+
+`src/core.js` is the shared, pure discovery engine. `src/scan.js` handles filesystem input. `site/` contains the UI. `npm run build` produces the complete standalone demo at `docs/index.html`; no bundler is needed.
+
+Contributions with reproducible discovery mismatches are especially useful. See [CONTRIBUTING.md](CONTRIBUTING.md) and the [roadmap](docs/roadmap.md).
+
+MIT licensed. Independent project, not affiliated with or endorsed by OpenAI. Codex is a product of OpenAI.

package/README.zh-CN.md

@@ -0,0 +1,108 @@
+<div align="center">
+
+# Codex Context Map
+
+**看清你的 Agent 读到了什么。**
+
+本地运行的 `AGENTS.md` 可视化调试器：加载链、覆盖关系、字节截断，一眼可见。
+
+[在线演示](https://han-1413141.github.io/codex-context-map/) · [English](README.md) · [解析规则](docs/semantics.md) · [下载版本](https://github.com/Han-1413141/codex-context-map/releases)
+
+[![CI](https://github.com/Han-1413141/codex-context-map/actions/workflows/ci.yml/badge.svg)](https://github.com/Han-1413141/codex-context-map/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/codex-context-map)](https://www.npmjs.com/package/codex-context-map)
+[![MIT](https://img.shields.io/badge/License-MIT-087f6b.svg)](LICENSE)
+
+[![Codex Context Map 的真实界面，展示虚构 Northstar 项目的指令加载链](docs/assets/preview.png)](https://han-1413141.github.io/codex-context-map/)
+
+</div>
+
+你写了指令，Codex 的行为却不符合预期：文件不在启动目录的搜索范围内？同目录有覆盖文件？最后一段被字节上限截去了？
+
+**选一个目录，直接查看加载链。** 切换目录可比较指令来源；降低字节上限可看到截断位置。不需要账号、API Key 或模型调用。
+
+## 快速体验
+
+打开 **[在线演示](https://han-1413141.github.io/codex-context-map/)**，点击右上角「中文」，体验「隐藏的覆盖」「超出长度预算」「空覆盖文件」。也可以打开自己的项目文件夹，指令内容只在当前设备处理。
+
+使用 Node.js 20+ 在仓库中运行：
+
+```bash
+npx codex-context-map . --html context-map.html
+```
+
+用浏览器打开生成的 `context-map.html`。这是一个完整独立的 HTML 文件，断网后也能使用。
+
+## 主要功能
+
+| 功能 | 解决的问题 |
+| --- | --- |
+| 目录地图 | 从某目录启动时，会发现哪些指令文件？ |
+| 覆盖解释 | 哪个同目录文件被遮盖？空覆盖文件会怎样？ |
+| 字节预算模拟 | 哪个文件被截断、损失多少字节？ |
+| 目录对比 | 换一个启动目录，会新增、移除或共享哪些指令？ |
+| 合并预览 | 按此发现模型组装的指令全文是什么？ |
+| HTML / JSON 导出 | 如何离线检查，或附在问题报告中？ |
+| CI 检查 | 当前目录的指令链是否超过指定预算？ |
+
+界面支持中英文，零运行时依赖，无后台服务、遥测或浏览器存储。
+
+## 命令示例
+
+```bash
+# 检查文件所在目录
+npx codex-context-map ./services/payments/handler.ts
+
+# 与另一个目录比较；后者相对于检测到的项目根目录
+npx codex-context-map ./services/payments --compare apps/web
+
+# 显式匹配你的 Codex 配置
+npx codex-context-map . --max-bytes 65536 --fallback TEAM_GUIDE.md --fallback .agents.md
+
+# 显式包含全局 AGENTS 文件
+npx codex-context-map . --global --html context-map.html
+
+# 导出 JSON，发生截断时返回失败退出码
+npx codex-context-map ./services/payments --json --check
+
+# 使用虚构示例，无需扫描本机项目
+npx codex-context-map --demo --html demo.html
+```
+
+`--check` 对选定目录进行检查：未截断返回 **0**，发生截断返回 **1**，输入或读写错误返回 **2**。CI 可分别检查关键启动目录。HTML 默认不覆盖已有文件，需要覆盖时显式加 `--force`。完整参数见 `--help`。
+
+无法访问 npm 时，可以克隆仓库后直接运行 `node bin/codex-context-map.js --demo`，命令行不需要安装依赖。也可下载 Release 中的包，再运行 `npm install -g ./codex-context-map-0.1.0.tgz`。
+
+## 解析范围
+
+这是**单个可信项目的静态发现预览**，采用有版本依据的 [Codex 源码规则](docs/semantics.md)，不读取正在运行的会话。
+
+- 命令行检测最近的 `.git` 标记；嵌套仓库有自己的边界。没有标记时只检查启动目录。可用 `--root` 指定边界。
+- 同目录依次选择 `AGENTS.override.md`、`AGENTS.md`、配置的备用文件名。更深目录的文件追加到加载链，不删除上级全文。
+- 默认预算为 **32,768 个内容字节**；分隔符和全局指令单独统计。这里不估算 Token 或费用。
+- **不会自动读取配置文件。** 请使 `--max-bytes`、`--fallback`、`--root` 与实际配置一致。全局指令需显式添加 `--global`。
+- 不涵盖系统提示、技能、MCP、Hook、任务及账号指令、不可信项目、多环境或会话中途刷新，也不证明模型是否遵守了指令。
+
+当前源码中，空覆盖文件的行为与文档中的简述存在细节差异，工具明确展示这个情况。具体依据与限制见 [解析规则](docs/semantics.md)。
+
+## 隐私
+
+CLI 只读取指定名称的指令文件和目录信息，不读取凭据、会话历史或源代码文件内容。全局指令仅在显式启用后读取。浏览器页面禁止网络连接，不上传导入文件；访问在线演示本身仍会向 GitHub Pages 发起正常页面请求。
+
+**导出内容包含指令文本和相对路径，分享前请检查；工具不会自动脱敏。** CLI 跳过符号链接并提示，浏览器文件夹选择器不提供符号链接元数据。生成目录和依赖目录默认排除，必要时用 `--include-ignored`。完整列表见 [扫描限制](docs/semantics.md#scan-and-import-limits)。
+
+## 参与开发
+
+```bash
+git clone https://github.com/Han-1413141/codex-context-map.git
+cd codex-context-map
+npm ci
+npm run check
+npx playwright install chromium
+npm run test:browser
+```
+
+共享解析引擎在 `src/core.js`，文件系统扫描在 `src/scan.js`，界面在 `site/`。`npm run build` 生成独立演示页 `docs/index.html`，无需打包器。
+
+欢迎提交能复现的解析差异、测试或改进。参见 [贡献指南](CONTRIBUTING.md) 和 [路线图](docs/roadmap.md)。
+
+MIT 协议。独立项目，与 OpenAI 无隶属关系，也未经 OpenAI 背书。Codex 是 OpenAI 的产品。

package/bin/codex-context-map.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { writeFile, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { scanProject } from "../src/scan.js";
+import { createDemo } from "../src/demo.js";
+import {
+  resolveContext,
+  compareContexts,
+  validateBudget,
+} from "../src/core.js";
+import { renderReport } from "../src/report.js";
+
+const help = `Codex Context Map — explain AGENTS.md discovery, offline.
+
+Usage: codex-context-map [directory-or-file] [options]
+
+  --html <file>         Write a self-contained interactive report
+  --json                Print a portable snapshot and resolved context as JSON
+  --compare <directory> Compare another directory (relative to project root)
+  --max-bytes <number>  Project content budget (default 32768, maximum 1048576)
+  --fallback <filename> Add a fallback filename; repeat to specify order
+  --root <directory>    Explicit project boundary (otherwise nearest .git)
+  --global              Also read AGENTS files from CODEX_HOME or ~/.codex
+  --codex-home <dir>    Use this global directory (requires --global)
+  --include-ignored     Traverse build/dependency folders too (.git is excluded)
+  --check               Exit 1 if the selected chain is truncated or excluded
+  --force               Allow overwriting the HTML output
+  --demo                Use the bundled fictional workspace
+  --version             Print version
+  --help                Show this help
+
+Examples:
+  npx codex-context-map . --html context-map.html
+  npx codex-context-map ./services/payments --compare apps/web
+  npx codex-context-map . --json --check
+
+Uses an explicit static model, not a live Codex session. No network calls.
+Config, skills, MCP, account/thread instructions and extra environments are not read.
+Match --max-bytes, --fallback and --root to your Codex configuration.
+Global instructions are opt-in. HTML/JSON exports contain instruction text.
+`;
+
+try {
+  const { values: v, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      html: { type: "string" },
+      json: { type: "boolean" },
+      compare: { type: "string" },
+      "max-bytes": { type: "string" },
+      fallback: { type: "string", multiple: true },
+      root: { type: "string" },
+      global: { type: "boolean" },
+      "codex-home": { type: "string" },
+      "include-ignored": { type: "boolean" },
+      check: { type: "boolean" },
+      force: { type: "boolean" },
+      demo: { type: "boolean" },
+      version: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+  if (v.help) {
+    console.log(help);
+  } else if (v.version) {
+    console.log(
+      JSON.parse(
+        await readFile(new URL("../package.json", import.meta.url), "utf8"),
+      ).version,
+    );
+  } else {
+    if (positionals.length > 1)
+      throw new Error("Provide one target directory or file.");
+    if (v["codex-home"] && !v.global)
+      throw new Error("--codex-home requires --global.");
+    if (v["max-bytes"] !== undefined && !/^\d+$/.test(v["max-bytes"]))
+      throw new Error("--max-bytes requires a nonnegative integer.");
+    const maxBytes =
+      v["max-bytes"] === undefined
+        ? undefined
+        : validateBudget(Number(v["max-bytes"]));
+    const snapshot = v.demo
+      ? createDemo()
+      : await scanProject(positionals[0] ?? ".", {
+          root: v.root,
+          maxBytes,
+          fallbackNames: v.fallback,
+          global: v.global,
+          codexHome: v["codex-home"],
+          includeIgnored: v["include-ignored"],
+        });
+    if (v.demo && positionals.length)
+      throw new Error("--demo does not accept a filesystem target.");
+    if (maxBytes !== undefined) snapshot.settings.maxBytes = maxBytes;
+    if (v.fallback) snapshot.settings.fallbackNames = v.fallback;
+    const result = resolveContext(snapshot);
+    const comparison = v.compare
+      ? compareContexts(result, resolveContext(snapshot, v.compare))
+      : undefined;
+    if (v.html) {
+      // Exclusive creation protects existing source and instruction files by default.
+      await writeFile(
+        resolve(v.html),
+        await renderReport(snapshot, { demo: !!v.demo }),
+        { encoding: "utf8", flag: v.force ? "w" : "wx" },
+      );
+      console.error(`Interactive report: ${resolve(v.html)}`);
+    }
+    if (v.json)
+      console.log(
+        JSON.stringify(
+          { ...snapshot, result, ...(comparison ? { comparison } : {}) },
+          null,
+          2,
+        ),
+      );
+    else {
+      console.log(`\nCODEX CONTEXT MAP · ${snapshot.projectName}\n`);
+      console.log(
+        `Launch directory: ${result.target}\nProject content: ${result.usedBytes.toLocaleString("en-US")} / ${result.budget.toLocaleString("en-US")} bytes\n`,
+      );
+      for (const file of result.selected)
+        console.log(
+          `  ${file.status.padEnd(9)} ${file.scope === "global" ? "$CODEX_HOME/" : ""}${file.path}  (${file.usedBytes}/${file.bytes} bytes)`,
+        );
+      if (!result.selected.length)
+        console.log("  No instruction files discovered.");
+      for (const f of result.records.filter((f) => f.status === "shadowed"))
+        console.log(`  shadowed  ${f.path} → ${f.shadowedBy}`);
+      if (comparison)
+        console.log(
+          `\nCompared with ${v.compare}:\n${JSON.stringify(comparison, null, 2)}`,
+        );
+      for (const warning of snapshot.warnings)
+        console.error(`Warning: ${warning}`);
+      console.log(
+        "\nStatic discovery preview. Use --help for model boundaries.",
+      );
+    }
+    if (v.check && result.hasCutoff) process.exitCode = 1;
+  }
+} catch (error) {
+  console.error(
+    `codex-context-map: ${error.code === "EEXIST" ? "Output exists; choose a new filename or pass --force." : error.message}`,
+  );
+  process.exitCode = 2;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "codex-context-map",
+  "version": "0.1.0",
+  "description": "See which AGENTS.md files Codex discovers, what overrides what, and where instructions get cut off. Offline CLI + interactive map.",
+  "type": "module",
+  "bin": {
+    "codex-context-map": "bin/codex-context-map.js"
+  },
+  "exports": {
+    ".": "./src/core.js",
+    "./scan": "./src/scan.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "site",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "build": "node scripts/build.js",
+    "test:browser": "playwright test",
+    "check": "npm test && npm run build",
+    "prepack": "npm run check"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "author": "Han-1413141",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Han-1413141/codex-context-map.git"
+  },
+  "homepage": "https://han-1413141.github.io/codex-context-map/",
+  "bugs": "https://github.com/Han-1413141/codex-context-map/issues",
+  "keywords": [
+    "codex",
+    "agents-md",
+    "openai",
+    "developer-tools",
+    "context-engineering",
+    "cli",
+    "visualization",
+    "offline"
+  ],
+  "devDependencies": {
+    "@playwright/test": "1.63.0"
+  }
+}