@codeursenior/pek 0.0.0-stage → 0.1.7

package/dist/token-estimator.js

@@ -0,0 +1,159 @@
+import path from "node:path";
+import { HttpError } from "./http/errors.js";
+import { clientsForContextEntry, links, toolsForSkill, } from "./scan/metadata.js";
+import { referenceResolver } from "./scan/references.js";
+import { inside, slash } from "./scan/values.js";
+export const modelPrices = [
+    {
+        id: "gpt-5.3-codex",
+        name: "GPT-5.3 Codex",
+        inputPerMillion: 1.75,
+        source: "https://developers.openai.com/api/docs/pricing",
+        verifiedAt: "2026-10-10",
+    },
+    {
+        id: "claude-sonnet-5.5",
+        name: "Claude Sonnet 5.5",
+        inputPerMillion: 2,
+        source: "https://platform.claude.com/docs/en/about-claude/pricing",
+        verifiedAt: "2026-10-10",
+    },
+    {
+        id: "claude-opus-5.5",
+        name: "Claude Opus 5.5",
+        inputPerMillion: 4,
+        source: "https://platform.claude.com/docs/en/about-claude/pricing",
+        verifiedAt: "2026-10-10",
+    },
+];
+const clients = ["codex", "claude", "cursor", "copilot"];
+export const estimationMethod = "Local heuristic: Unicode characters / 4, rounded up per entry. Words are whitespace-separated; sizes are UTF-8 bytes. Not a model tokenizer or live usage measurement.";
+/** Counts discovered text only; references never promote their targets to startup. */
+export function contextInventory(entries, data, env) {
+    const byAlias = new Map(entries.flatMap((entry) => entry.aliases.map((alias) => [alias, entry])));
+    const result = {
+        codex: [],
+        claude: [],
+        cursor: [],
+        copilot: [],
+    };
+    const resolveReference = referenceResolver(entries, env);
+    const nodes = new Map(data.nodes.map((node) => [node.id, node]));
+    const rules = new Map(data.rules.map((rule) => [rule.id, rule]));
+    const skills = new Map(data.skills.flatMap((skill) => skill.editTargets.map((target) => [target.id, skill])));
+    for (const client of clients) {
+        const rows = new Map();
+        const queue = new Set();
+        const add = (entry, kind, startup, text = entry.text, name = path.basename(entry.file), id = entry.id) => {
+            queue.add(entry);
+            const existing = rows.get(id);
+            if (existing) {
+                if (startup)
+                    rows.set(id, {
+                        ...existing,
+                        portion: "startup",
+                        path: env.display(entry.file, entry.scope),
+                    });
+                return;
+            }
+            rows.set(id, {
+                id,
+                name,
+                path: env.display(entry.file, entry.scope),
+                scope: entry.scope,
+                kind,
+                portion: startup ? "startup" : "on-demand",
+                tokens: Math.ceil(Array.from(text).length / 4),
+                words: text.match(/\S+/gu)?.length ?? 0,
+                bytes: Buffer.byteLength(text),
+                inputCost: 0,
+            });
+        };
+        for (const entry of entries) {
+            const node = nodes.get(entry.id);
+            if (node?.kind === "instruction") {
+                const aliases = entry.aliases.filter((alias) => clientsForContextEntry(alias, entry.scope, env.root, env.codexHome).includes(client));
+                const effective = aliases.filter((alias) => !(client === "codex" &&
+                    path.basename(alias) === "AGENTS.md" &&
+                    byAlias.has(path.join(path.dirname(alias), "AGENTS.override.md"))));
+                if (effective.length)
+                    add(entry, "instruction", effective.some((alias) => entry.scope === "user" ||
+                        path.dirname(alias) === env.root ||
+                        (client === "claude" &&
+                            path.dirname(alias) === path.join(env.root, ".claude")) ||
+                        (client === "copilot" &&
+                            alias ===
+                                path.join(env.root, ".github/copilot-instructions.md"))));
+            }
+            const rule = rules.get(entry.id);
+            if (rule?.clients.includes(client)) {
+                const unscoped = client === "cursor"
+                    ? rule.alwaysApply || rule.legacy
+                    : client === "claude"
+                        ? !rule.pathsCondition.length
+                        : rule.applyTo.includes("**") || rule.applyTo.includes("**/*");
+                const rootRule = entry.scope === "user" ||
+                    entry.aliases.some((alias) => /^(?:\.cursorrules|\.(?:claude|cursor)\/rules\/|\.github\/instructions\/)/.test(slash(path.relative(env.root, alias))));
+                add(entry, "rule", unscoped && rootRule);
+            }
+            const skill = skills.get(entry.id);
+            if (skill?.clients.includes(client) &&
+                entry.aliases.some((alias) => toolsForSkill(slash(alias)).includes(client) ||
+                    (client === "codex" &&
+                        entry.scope === "user" &&
+                        inside(path.join(env.codexHome, "skills"), alias)))) {
+                // Identical copies and symlink aliases represent one discovered skill.
+                const catalog = `${skill.name}\n${skill.description}`;
+                const startup = entry.scope === "user" ||
+                    entry.aliases.some((alias) => {
+                        const relative = slash(path.relative(env.root, alias));
+                        return (/^\.(?:agents|codex|claude|cursor|github)\/skills\//.test(relative) && toolsForSkill(relative).includes(client));
+                    });
+                add(entry, "skill-catalog", startup, catalog, skill.name, `${skill.id}:skill-catalog`);
+                add(entry, "skill-body", false, entry.text.replace(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/, ""), skill.name, `${skill.id}:skill-body`);
+            }
+        }
+        // Sets preserve insertion order and visit newly discovered references, including cycles, once.
+        for (const entry of queue) {
+            for (const link of links(entry.text)) {
+                const found = resolveReference(entry, link);
+                if (!found ||
+                    queue.has(found) ||
+                    !env.allowed.some((base) => inside(base, found.real)))
+                    continue;
+                add(found, "document", false);
+            }
+        }
+        result[client] = [...rows.values()].sort((a, b) => b.tokens - a.tokens || a.path.localeCompare(b.path));
+    }
+    return result;
+}
+export function estimateTokens(snapshot, clientId, modelId) {
+    const client = clients.find((client) => client === clientId);
+    const model = modelPrices.find((model) => model.id === modelId);
+    if (!client || !model)
+        throw new HttpError(400, "Select one supported agent and model.");
+    const entries = snapshot.tokenInventory[client].map((entry) => ({
+        ...entry,
+        inputCost: (entry.tokens * model.inputPerMillion) / 1_000_000,
+    }));
+    const total = (portion) => entries
+        .filter((entry) => entry.portion === portion)
+        .reduce((sum, entry) => ({
+        tokens: sum.tokens + entry.tokens,
+        words: sum.words + entry.words,
+        bytes: sum.bytes + entry.bytes,
+        inputCost: sum.inputCost + entry.inputCost,
+    }), { tokens: 0, words: 0, bytes: 0, inputCost: 0 });
+    return {
+        client,
+        model,
+        models: modelPrices,
+        method: estimationMethod,
+        entries,
+        startup: total("startup"),
+        onDemand: total("on-demand"),
+        includeUser: snapshot.data.limits.includeUser,
+        warnings: snapshot.data.warnings,
+    };
+}

package/docs/architecture.md

@@ -0,0 +1,47 @@
+# Architecture
+
+`src/cli.ts` parses arguments, starts the server for the requested folder and opens the default browser using OS launchers with argument arrays and no shell interpolation. TypeScript compiles it to `dist/cli.js`, retaining its executable shebang. The CLI resolves its version relative to the installed package, independently of the caller's working directory.
+
+`src/scanner.ts` orchestrates a fresh snapshot. Modules under `src/scan/` handle filesystem collection, metadata parsing, context/rule/skill discovery, reference resolution and graph construction, and MCP discovery. Parsing starts with unknown values and narrows them before normalization. Context client discovery propagates across explicit reference edges, never folder-scope edges. Documents remain data, never instructions to the application. MCP output is an explicit metadata whitelist, never a serialized configuration.
+
+`src/server.ts` owns the in-memory snapshot, coalesced refresh promise, and random session credential. Modules under `src/http/` handle authentication/security headers, serialized file writes, request validation, and browser asset enumeration. Requests select static files from an allowlist built from `dist/browser`; they never resolve arbitrary paths. Previews and edits use indexed opaque IDs, size limits, and content revision checks. CSP blocks remote code, frames, plugins and inline scripts. Each HTML response receives a fresh nonce for Angular component styles; critical CSS inlining is disabled.
+
+`src/contracts.ts` defines browser-safe JSON shapes shared by the server and UI. Internal snapshot maps and real filesystem write targets live separately in `src/scan/types.ts`. These are internal contracts, not a published library API.
+
+`src/token-estimator.ts` classifies local context per client and computes static volumes and one-load input costs. `src/optimization-checks.ts` runs fixed, bounded RTK identity probes; it never executes workspace-supplied commands or installs software. See [Token Optimizer](token-optimizer.md) for estimation assumptions, pricing sources and discovery limits.
+
+The Angular UI uses standalone OnPush components and signals. `WorkspaceState` owns inventory, navigation, filters, theme and selection; `WorkspaceApi` owns authenticated HTTP requests. Components render the sidebar, filters, tables, graph, and detail editor. Angular text bindings display untrusted content without HTML interpretation. The session token moves from the URL fragment to tab session storage and is removed from the visible URL.
+
+The detail component owns its edit draft and revision. A request sequence prevents late previews or writes from updating a different selection. The graph component delegates only its SVG subtree to the typed D3 renderer. Simulation nodes and links are copies of API data. Initial positions, layout forces and bounded warm-up are preserved; cleanup stops simulations and removes listeners when the graph is replaced or destroyed.
+
+## Extending and testing
+
+- Add filesystem discovery behavior to the relevant scan module, with a synthetic fixture in the backend tests. Test normalization and reference rules as pure functions when possible; retain real filesystem tests for symlinks, scope boundaries, and limits.
+- Change shared JSON contracts first when introducing API data. Add transport tests for new routes or file operations. Keep credentials and filesystem capabilities out of browser-visible types.
+- Add UI behavior to its owning component or state service, with a Vitest test through Angular TestBed. Use `await fixture.whenStable()` after interactions rather than forced change detection. Keep HTTP calls behind `WorkspaceApi`.
+- Keep D3-specific mutations inside the renderer. Validate gestures and production CSP in Playwright against the compiled server; do not rely on DOM emulation for SVG geometry.
+- Run `npm run check` before committing. Browser baselines cover the original UI and both themes; update them only for reviewed visual changes. Coverage reports are diagnostic rather than percentage gates.
+
+Development uses Node 24 and the Angular CLI's supported Vitest integration. Backend code is checked against Node 20 types and emitted as ESM; test/build tooling uses newer Node types separately. Angular and D3 are bundled into browser assets and are not installed as runtime dependencies. The npm archive includes only compiled output, documentation and licenses. Build caches, sources and fixtures stay out of it.
+
+Client badges use local raster marks from [Cursor](https://cursor.com/brand), [Claude](https://claude.com/), and [ChatGPT](https://chatgpt.com/). The Codex discovery indicator uses the ChatGPT mark; Copilot uses a local text mark. The static asset allowlist keeps the images available without remote requests.
+
+## Discovery references
+
+Behavior was checked against official documentation on 2026-09-30. Runtime behavior can differ by client release or configuration.
+
+- [Codex skills](https://developers.openai.com/codex/skills/): repository and user `.agents/skills` discovery and symlink support.
+- [Codex MCP](https://developers.openai.com/codex/mcp/): TOML server definitions and project/user configuration.
+- [Claude Code skills](https://code.claude.com/docs/en/skills): `.claude/skills`, invocation metadata, and nested discovery.
+- [Claude Code MCP](https://code.claude.com/docs/en/mcp): `.mcp.json` plus user and project-local entries in `~/.claude.json`.
+- [Cursor skills](https://cursor.com/docs/skills): `.agents/skills`, `.cursor/skills`, and compatibility with Claude/Codex directories.
+- [Cursor MCP](https://cursor.com/docs/context/model-context-protocol): `.cursor/mcp.json` project/user configuration.
+- [Cursor rules](https://cursor.com/docs/context/rules): `.cursor/rules` and legacy `.cursorrules`.
+- [Cursor rules help](https://prod.cursor.com/help/customization/rules): project-root `AGENTS.md` and `CLAUDE.md` are both read by Cursor.
+- [Claude Code rules](https://code.claude.com/docs/en/memory): `.claude/rules` and `paths` frontmatter.
+- [Codex instructions](https://learn.chatgpt.com/docs/agent-configuration/agents-md): `AGENTS.md` belongs in Context. [Codex command rules](https://learn.chatgpt.com/docs/agent-configuration/rules) are a separate execution policy.
+- [Copilot instructions in VS Code](https://code.visualstudio.com/docs/agent-customization/custom-instructions): repository and personal instructions, `AGENTS.md`, and targeted `.instructions.md` files with `applyTo` metadata.
+- [Copilot skills in VS Code](https://code.visualstudio.com/docs/agent-customization/agent-skills): project and personal skill locations and invocation metadata.
+- [MCP servers in VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers): workspace `.vscode/mcp.json`, portable `.mcp.json`, and Agent Host `~/.copilot/mcp-config.json`.
+
+A live connection indicator needs an explicit integration with each client's running session. Executing commands found in arbitrary repository configuration is deliberately outside the viewer's scope. File-based discovery, configuration enablement, transport reachability and authenticated session connectivity are separate facts.

package/docs/token-optimizer.md

@@ -0,0 +1,56 @@
+# Token Optimizer design
+
+Status: implemented. The implementation request approved the confirmed decisions below.
+
+## Confirmed decisions
+
+- Place Token Optimizer after MCP servers in the navigation, with a static context estimate represented as an iceberg. Keep the optimization checklist in its own following tab.
+- Above water: applicable startup instruction contents and skill catalog entries, including names and descriptions.
+- Below water: linked documents, skill bodies, and instructions applicable only in specific subfolders.
+- Count a reference's text in its containing instruction file. Do not automatically include the referenced document's contents in the startup estimate.
+- Require one selected agent: Codex, Claude Code, Cursor, or GitHub Copilot. Include its project and user context. Do not offer an aggregate "All clients" estimate.
+- These estimates describe discoverable local context, not observed usage in a running conversation.
+- Estimate the input cost of loading each iceberg portion once, using the selected model's input price without caching discounts.
+- The on-demand price is hypothetical: it assumes all available on-demand content is loaded once. Neither price predicts session spending.
+- Provide model presets with input prices maintained by the application. V1 has no custom model or manual price entry; users are not responsible for supplying pricing data.
+- Include an extensible checklist starting with "Install RTK". Its checkbox reflects detected installation status, not a user's manual declaration.
+- When RTK is detected, show the checkbox checked and disabled.
+- When RTK is missing, show the checkbox unchecked and provide installation instructions with a "Check again" button. Do not install RTK from the application. Check and disable the checkbox only after detection succeeds.
+- Show only above-water (startup) entries in the breakdown by file or skill, sorted by token count from largest to smallest, with word count and estimated input cost. Omit the byte-size column.
+- Show context metrics and price estimates for both iceberg portions. Keep the visualization free of the illustration caption and repeated context/pricing caveats; retain the estimation method and official pricing in the expandable details.
+- Exclude quality scores and rewrite suggestions from V1.
+
+## Implementation research
+
+- RTK's [official installation guide](https://www.rtk-ai.app/docs/getting-started/installation/) documents `rtk --version` and `rtk gain` as installation checks. Version output alone is insufficient because another tool shares the executable name. Detection must verify Rust Token Killer specifically.
+- Select and document a local token-estimation method and verify model input prices against official provider sources during implementation. Do not imply exact live usage or apply an RTK discount to static file totals.
+
+## V1 implementation
+
+The authenticated `/api/token-estimate` endpoint requires exactly one supported `client` and `model`. It uses the latest scan snapshot, including a refreshed snapshot after Rescan. `/api/optimization-checks` runs bounded, fixed RTK identity probes on demand. Neither endpoint installs anything or contacts a model provider.
+
+### Estimation method
+
+V1 uses `ceil(Unicode code points / 4)` per entry, whitespace-separated word counts and UTF-8 byte sizes. This lightweight, deterministic heuristic needs no network service or tokenizer dependency. It is approximate, particularly for code and non-Latin text, and is not interchangeable with any provider's tokenizer. Empty text has zero tokens. Totals sum the rounded entry estimates.
+
+A skill catalog entry contains its name, a newline and its description. Its on-demand body excludes YAML frontmatter. Other skill metadata and client-generated catalog wrappers are not modeled. Identical skill copies are grouped; physical context-file aliases are counted once. References are followed locally, including references from rules and skills, with cycle protection. Link text stays in the referring file; linked contents stay on demand unless independently applicable at startup.
+
+Startup means a session at the scanned project root. Root instructions, supported user instructions, unconditional rules and root/user skill catalogs qualify. Nested instructions and nested skill catalogs are on demand. Codex override files replace AGENTS.md in the same folder. Rule conditions use Cursor `alwaysApply`, Claude `paths`, and universal Copilot `applyTo` patterns. Other rules are on demand. Estimates inherit the scanner's file-size, directory-depth, symlink and discovery boundaries. Ancestor instructions outside the scanned root, remote sources, installed plugin stores and session-specific client settings are not inspected. The UI reports when user discovery was disabled and displays scan warnings.
+
+### Maintained pricing
+
+Prices verified on 2026-10-10, USD per million standard uncached input tokens:
+
+| Preset            | Input price | Official source                                                            |
+| ----------------- | ----------: | -------------------------------------------------------------------------- |
+| GPT-5.3 Codex     |       $1.75 | [OpenAI API pricing](https://developers.openai.com/api/docs/pricing)       |
+| Claude Sonnet 5.5 |       $2.00 | [Claude pricing](https://platform.claude.com/docs/en/about-claude/pricing) |
+| Claude Opus 5.5   |       $4.00 | [Claude pricing](https://platform.claude.com/docs/en/about-claude/pricing) |
+
+Presets are pricing scenarios, not a promise that each client exposes each model. Maintainers update `src/token-estimator.ts` and this table together when prices change. Calculations exclude output tokens, caching, batch discounts, regional surcharges, subscription pricing and repeated session loads.
+
+### RTK detection
+
+Detection requires both a valid `rtk --version` response and the `Rust Token Killer` identity in `rtk -h`, as declared in [RTK's CLI source](https://github.com/rtk-ai/rtk/blob/master/src/main.rs). Short help avoids opening or modifying an analytics database. Each process has a three-second timeout and a 64 KiB output limit. Relative PATH entries and paths inside the scanned project are excluded. Concurrent HTTP checks share one probe. Installation detection does not assert hook configuration or apply a discount to context totals.
+
+The dedicated Optimization checklist tab loads an array of detected checks, initially RTK only. Token Optimizer does not run installation probes, and the checklist does not request token estimates. An unchecked disabled checkbox cannot be marked manually. Installation commands and the official guide are displayed when detection fails; Check again probes the server environment anew.

package/package.json

@@ -1,6 +1,89 @@
 {
   "name": "@codeursenior/pek",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.7",
+  "description": "Agent Visualizer: explore your AI context, skills and MCP configuration in a local dashboard.",
+  "type": "module",
+  "bin": {
+    "pek": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsx scripts/clean.ts && npm run build:server && ng build",
+    "build:server": "tsc -p tsconfig.json",
+    "prestart": "npm run build",
+    "start": "node dist/cli.js audit agent",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json && ngc -p tsconfig.app.json --noEmit",
+    "lint": "eslint . && prettier --check .",
+    "test": "npm run test:server && npm run test:ui",
+    "test:server": "vitest run --config vitest.config.ts",
+    "test:ui": "ng test --watch=false",
+    "test:coverage": "npm run test:server -- --coverage && npm run test:ui -- --coverage",
+    "test:e2e": "playwright test",
+    "test:package": "tsx scripts/package-smoke.ts",
+    "test:reproducibility": "tsx scripts/reproducibility.ts",
+    "check": "npm run lint && npm run typecheck && npm run build && npm test",
+    "prepack": "npm run build",
+    "format": "prettier --write ."
+  },
+  "keywords": [
+    "agents",
+    "codex",
+    "copilot",
+    "claude",
+    "cursor",
+    "mcp",
+    "skills",
+    "visualizer"
+  ],
+  "author": "Simon Dieny",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codeursenior/product-engineer-kit.git",
+    "directory": "packages/agent-visualizer"
+  },
+  "homepage": "https://github.com/codeursenior/product-engineer-kit/tree/main/packages/agent-visualizer#readme",
+  "bugs": "https://github.com/codeursenior/product-engineer-kit/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "jsonc-parser": "^3.3.1",
+    "smol-toml": "^1.4.2",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@angular/build": "22.2.0",
+    "@angular/cli": "22.2.0",
+    "@angular/common": "22.2.0",
+    "@angular/compiler": "22.2.0",
+    "@angular/compiler-cli": "22.2.0",
+    "@angular/core": "22.2.0",
+    "@angular/platform-browser": "22.2.0",
+    "@playwright/test": "1.63.0",
+    "@types/d3": "7.4.3",
+    "@types/node": "22.20.4",
+    "@types/node20": "npm:@types/node@20.19.43",
+    "@vitest/coverage-v8": "5.0.3",
+    "angular-eslint": "22.5.0",
+    "d3": "^7.9.0",
+    "eslint": "10.11.0",
+    "jiti": "2.7.0",
+    "jsdom": "30.1.1",
+    "prettier": "^3.9.8",
+    "rxjs": "7.8.2",
+    "tslib": "2.8.1",
+    "tsx": "4.23.15",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.71.0",
+    "vitest": "5.0.3"
+  }
+}