@codeursenior/pek 0.0.0-stage → 0.1.8

package/dist/cli.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { errorCode, record } from "./scan/values.js";
+import { startServer } from "./server.js";
+const help = `Agent Visualizer · Product Engineer Kit
+
+Usage: npx @codeursenior/pek audit agent [folder] [options]
+
+Explore context, skills and MCP configuration in your default browser.
+
+  --port <number>   Choose a port (default: an available port)
+  --no-open         Print the URL without opening a browser
+  --project-only    Skip user-level assets
+  --help, -h        Show this help
+  --version, -v     Show the installed version
+
+Local workspace. No telemetry. Ctrl+C to stop.
+`;
+try {
+    const { values, positionals } = parseArgs({
+        options: {
+            port: { type: "string" },
+            "no-open": { type: "boolean" },
+            "project-only": { type: "boolean" },
+            help: { type: "boolean", short: "h" },
+            version: { type: "boolean", short: "v" },
+        },
+        allowPositionals: true,
+    });
+    if (values.version) {
+        const { version } = record(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")));
+        console.log(version);
+    }
+    else if (values.help || !positionals.length) {
+        console.log(help);
+    }
+    else {
+        if (positionals[0] !== "audit" ||
+            positionals[1] !== "agent" ||
+            positionals.length > 3)
+            throw new Error("Expected: pek audit agent [folder]. Use --help for options.");
+        const port = values.port === undefined ? 0 : Number(values.port);
+        if (!Number.isInteger(port) || port < 0 || port > 65535)
+            throw new Error("Port must be an integer between 0 and 65535.");
+        const root = path.resolve(positionals[2] || process.cwd());
+        console.log(`\n  Agent Visualizer\n  Scanning ${root} ...`);
+        const { server, url } = await startServer({
+            root,
+            port,
+            includeUser: !values["project-only"],
+        });
+        console.log(`\n  ${url}\n\n  Local workspace · Ctrl+C to stop\n`);
+        if (!values["no-open"]) {
+            const command = process.platform === "darwin"
+                ? "open"
+                : process.platform === "win32"
+                    ? "rundll32"
+                    : "xdg-open";
+            const args = process.platform === "win32"
+                ? ["url.dll,FileProtocolHandler", url]
+                : [url];
+            const child = spawn(command, args, {
+                stdio: "ignore",
+                detached: true,
+                shell: false,
+            });
+            child.on("error", () => console.log("  Open the URL above in your browser."));
+            child.on("exit", (code) => {
+                if (code)
+                    console.log("  Open the URL above in your browser.");
+            });
+            child.unref();
+        }
+        for (const signal of ["SIGINT", "SIGTERM"])
+            process.once(signal, () => {
+                server.close();
+                server.closeAllConnections();
+            });
+    }
+}
+catch (error) {
+    console.error(`\n  ${errorCode(error) === "EADDRINUSE" ? "Port is in use. Choose another --port or omit it." : error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+}

package/dist/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/http/assets.js

@@ -0,0 +1,42 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const types = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".webp": "image/webp",
+    ".ico": "image/x-icon",
+    ".txt": "text/plain; charset=utf-8",
+    ".woff2": "font/woff2",
+};
+/** Enumerate build output once. Request paths are map keys, never filesystem paths. */
+export async function browserAssets(directory) {
+    const assets = new Map();
+    async function visit(relative) {
+        for (const entry of await fs.readdir(path.join(directory, relative), {
+            withFileTypes: true,
+        })) {
+            const name = path.posix.join(relative, entry.name);
+            if (entry.isDirectory())
+                await visit(name);
+            else if (entry.isFile()) {
+                const type = types[path.extname(name)];
+                if (type)
+                    assets.set(name === "index.html" ? "/" : "/" + name, {
+                        file: path.join(directory, name),
+                        type,
+                    });
+            }
+        }
+    }
+    try {
+        await visit("");
+    }
+    catch {
+        /* Missing build is reported on requests. */
+    }
+    return assets;
+}

package/dist/http/errors.js

@@ -0,0 +1,7 @@
+export class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}

package/dist/http/files.js

@@ -0,0 +1,72 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import { record } from "../scan/values.js";
+import { HttpError } from "./errors.js";
+const MAX_EDIT_BYTES = 512 * 1024;
+const revision = (text) => createHash("sha256").update(text).digest("hex");
+async function readEditBody(req, deleting) {
+    if (!req.headers["content-type"]?.startsWith("application/json"))
+        throw new HttpError(415, "Expected JSON.");
+    const chunks = [];
+    let bytes = 0;
+    for await (const raw of req) {
+        const chunk = raw;
+        if (!Buffer.isBuffer(chunk))
+            throw new HttpError(400, "Invalid JSON.");
+        bytes += chunk.length;
+        if (bytes > MAX_EDIT_BYTES * 2)
+            throw new HttpError(413, "File is too large to edit.");
+        chunks.push(chunk);
+    }
+    let body;
+    try {
+        body = record(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+    }
+    catch {
+        throw new HttpError(400, "Invalid JSON.");
+    }
+    if (typeof body.revision !== "string" ||
+        (!deleting && typeof body.text !== "string")) {
+        throw new HttpError(400, deleting ? "Missing revision." : "Missing text or revision.");
+    }
+    const text = typeof body.text === "string" ? body.text : "";
+    if (!deleting && Buffer.byteLength(text) > MAX_EDIT_BYTES)
+        throw new HttpError(413, "File is too large to edit.");
+    return { revision: body.revision, text };
+}
+async function readCurrent(target) {
+    if ((await fs.realpath(target.file)) !== target.real)
+        throw new HttpError(409, "File path changed. Rescan before editing.");
+    const stat = await fs.stat(target.real);
+    if (!stat.isFile() || stat.size > MAX_EDIT_BYTES)
+        throw new HttpError(413, "File is too large to edit.");
+    return fs.readFile(target.real, "utf8");
+}
+/** One write queue per server; failed writes must not poison subsequent requests. */
+export class FileOperations {
+    saving = Promise.resolve();
+    async handle(req, target) {
+        if (req.method === "GET") {
+            const text = await readCurrent(target);
+            return { text, revision: revision(text) };
+        }
+        const deleting = req.method === "DELETE";
+        const body = await readEditBody(req, deleting);
+        const save = this.saving.then(async () => {
+            const current = await readCurrent(target);
+            if (revision(current) !== body.revision)
+                throw new HttpError(409, "File changed on disk. Reopen it before changing it.");
+            if (deleting) {
+                if (!target.deletable ||
+                    (await fs.lstat(target.file)).isSymbolicLink())
+                    throw new HttpError(409, "This file has another path. Rescan before deleting.");
+                await fs.unlink(target.file);
+                return { deleted: true };
+            }
+            await fs.writeFile(target.real, body.text, "utf8");
+            return { revision: revision(body.text) };
+        });
+        this.saving = save.catch(() => undefined);
+        return save;
+    }
+}

package/dist/http/security.js

@@ -0,0 +1,16 @@
+import { timingSafeEqual } from "node:crypto";
+export function localRequest(req, host) {
+    return (req.headers.host === host &&
+        (!req.headers.origin || req.headers.origin === `http://${host}`));
+}
+export function authenticated(req, token) {
+    const provided = Buffer.from(req.headers.authorization?.replace(/^Bearer /, "") || "");
+    const expected = Buffer.from(token);
+    return (provided.length === expected.length && timingSafeEqual(provided, expected));
+}
+export function securityHeaders(res, nonce) {
+    res.setHeader("Cache-Control", "no-store");
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    res.setHeader("Referrer-Policy", "no-referrer");
+    res.setHeader("Content-Security-Policy", `default-src 'self'; script-src 'self'; style-src 'self' 'nonce-${nonce}'; img-src 'self' data:; connect-src 'self'; object-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'`);
+}

package/dist/optimization-checks.js

@@ -0,0 +1,57 @@
+import { execFile } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import { inside } from "./scan/values.js";
+/** Fixed read-only probes only; never execute commands from workspace metadata. */
+export async function optimizationChecks(root) {
+    const probe = (argument) => new Promise((resolve, reject) => {
+        const searchPath = (process.env.PATH ?? "")
+            .split(path.delimiter)
+            .filter((directory) => path.isAbsolute(directory) && !inside(root, directory))
+            .join(path.delimiter);
+        execFile("rtk", [argument], {
+            cwd: os.tmpdir(),
+            env: { ...process.env, PATH: searchPath },
+            timeout: 3000,
+            maxBuffer: 64 * 1024,
+            encoding: "utf8",
+            windowsHide: true,
+        }, (error, stdout) => (error ? reject(error) : resolve(stdout)));
+    });
+    let detected = false;
+    let detail = "Rust Token Killer was not detected on the server's PATH. Install it in your terminal, then check again.";
+    try {
+        const version = await probe("--version");
+        const help = await probe("-h");
+        detected =
+            /^rtk\s+\d+\.\d+\.\d+/m.test(version) && /Rust Token Killer/i.test(help);
+        detail = detected
+            ? "Rust Token Killer installation detected. Agent integration is not verified."
+            : "An rtk executable responded, but its Rust Token Killer identity could not be verified.";
+    }
+    catch {
+        /* Missing, inaccessible, or timed-out executable remains unchecked. */
+    }
+    return {
+        checks: [
+            {
+                id: "rtk",
+                label: "Install RTK",
+                detected,
+                detail,
+                guide: "https://www.rtk-ai.app/docs/getting-started/installation/",
+                instructions: [
+                    {
+                        label: "macOS / Linux (Homebrew)",
+                        command: "brew install rtk-ai/tap/rtk",
+                    },
+                    { label: "Windows", command: "winget install rtk-ai.rtk" },
+                    {
+                        label: "Cargo",
+                        command: "cargo install --git https://github.com/rtk-ai/rtk --branch master rtk",
+                    },
+                ],
+            },
+        ],
+    };
+}

package/dist/scan/assets.js

@@ -0,0 +1,171 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parse as yaml } from "yaml";
+import { clientsForContextEntry, frontmatter, ruleClient, toolsForSkill, } from "./metadata.js";
+import { falsehood, id, inside, INSTRUCTION, lineCount, record, required, slash, truth, } from "./values.js";
+export async function discoverAssets(entries, env) {
+    const { root, codexHome, display, warnings } = env;
+    const context = new Map();
+    const rules = new Map();
+    const skills = new Map();
+    const content = new Map();
+    const editable = new Map();
+    function addContext(entry) {
+        if (context.has(entry.id))
+            return;
+        const aliases = entry.aliases.filter((p) => !ruleClient(p));
+        const firstAlias = aliases[0];
+        if (!firstAlias)
+            return;
+        const deletable = entry.aliases.length === 1 &&
+            path.relative(entry.file, entry.real) === "";
+        const paths = aliases.map((p) => display(p, entry.scope));
+        const kind = aliases.some((p) => INSTRUCTION.test(path.basename(p)))
+            ? "instruction"
+            : aliases.some((p) => /[\\/]rules[\\/]|\.mdc$/.test(p))
+                ? "rule"
+                : "knowledge";
+        context.set(entry.id, {
+            id: entry.id,
+            name: path.basename(firstAlias),
+            path: required(paths[0]),
+            aliases: paths,
+            clients: [
+                ...new Set(aliases.flatMap((alias) => clientsForContextEntry(alias, entry.scope, root, codexHome))),
+            ],
+            editTargets: [{ id: entry.id, path: required(paths[0]), deletable }],
+            scope: entry.scope,
+            kind,
+            bytes: Buffer.byteLength(entry.text),
+            lines: lineCount(entry.text),
+            excerpt: entry.text.slice(0, 180),
+        });
+        content.set(entry.id, entry.text);
+        editable.set(entry.id, { file: entry.file, real: entry.real, deletable });
+    }
+    for (const entry of entries) {
+        if (path.basename(entry.file) === "SKILL.md") {
+            const deletable = entry.aliases.length === 1 &&
+                path.relative(entry.file, entry.real) === "";
+            let meta = {};
+            try {
+                meta = frontmatter(entry.text);
+            }
+            catch {
+                warnings.push(`Invalid skill frontmatter: ${display(entry.file, entry.scope)}`);
+            }
+            const name = typeof meta.name === "string"
+                ? meta.name
+                : path.basename(path.dirname(entry.file));
+            const key = `${entry.scope}:${name}:${id(entry.text)}`;
+            if (!skills.has(key))
+                skills.set(key, {
+                    id: id(key),
+                    name,
+                    description: typeof meta.description === "string" ? meta.description : "",
+                    scope: entry.scope,
+                    paths: [],
+                    editTargets: [],
+                    clients: [],
+                    invocation: {},
+                    legacy: false,
+                    mode: "Not discovered",
+                });
+            const skill = required(skills.get(key));
+            content.set(skill.id, entry.text);
+            editable.set(entry.id, { file: entry.file, real: entry.real, deletable });
+            skill.editTargets.push({
+                id: entry.id,
+                path: display(entry.file, entry.scope),
+                deletable,
+            });
+            let policy = {};
+            try {
+                policy = record(record(yaml(await fs.readFile(path.join(path.dirname(entry.real), "agents/openai.yaml"), "utf8"))).policy);
+            }
+            catch {
+                /* Optional metadata. */
+            }
+            for (const alias of entry.aliases) {
+                const p = display(alias, entry.scope);
+                skill.paths.push(p);
+                if (p.includes(".codex/skills/"))
+                    skill.legacy = true;
+                const discovered = toolsForSkill(slash(alias));
+                if (entry.scope === "user" &&
+                    inside(path.join(codexHome, "skills"), alias) &&
+                    !discovered.includes("codex"))
+                    discovered.push("codex");
+                for (const client of discovered) {
+                    if (!skill.clients.includes(client))
+                        skill.clients.push(client);
+                    const invocation = client === "codex"
+                        ? falsehood(policy.allow_implicit_invocation)
+                            ? "User only"
+                            : "Model + user"
+                        : truth(meta["disable-model-invocation"])
+                            ? falsehood(meta["user-invocable"])
+                                ? "Disabled"
+                                : "User only"
+                            : falsehood(meta["user-invocable"]) &&
+                                (client === "claude" || client === "copilot")
+                                ? "Model only"
+                                : "Model + user";
+                    skill.invocation[client] = [
+                        ...new Set([
+                            ...(skill.invocation[client]?.split(" / ") || []),
+                            invocation,
+                        ]),
+                    ].join(" / ");
+                }
+            }
+            skill.mode =
+                [...new Set(Object.values(skill.invocation))].join(" / ") ||
+                    "Not discovered";
+        }
+        else {
+            const ruleAliases = entry.aliases.filter((p) => ruleClient(p));
+            if (ruleAliases.length) {
+                let meta = {};
+                try {
+                    meta = frontmatter(entry.text);
+                }
+                catch {
+                    warnings.push(`Invalid rule frontmatter: ${display(entry.file, entry.scope)}`);
+                }
+                const patterns = (value) => (Array.isArray(value)
+                    ? value
+                    : typeof value === "string"
+                        ? [value]
+                        : [])
+                    .filter((item) => typeof item === "string")
+                    .map((item) => item.trim())
+                    .filter(Boolean);
+                rules.set(entry.id, {
+                    id: entry.id,
+                    name: path.basename(required(ruleAliases[0])),
+                    description: typeof meta.description === "string" ? meta.description : "",
+                    scope: entry.scope,
+                    paths: ruleAliases.map((p) => display(p, entry.scope)),
+                    clients: [
+                        ...new Set(ruleAliases
+                            .map(ruleClient)
+                            .filter((client) => client !== null)),
+                    ],
+                    legacy: ruleAliases.some((p) => path.basename(p).toLowerCase() === ".cursorrules"),
+                    globs: patterns(meta.globs),
+                    pathsCondition: patterns(meta.paths),
+                    applyTo: patterns(meta.applyTo),
+                    alwaysApply: meta.alwaysApply === true,
+                });
+                content.set(entry.id, entry.text);
+            }
+            if (!entry.aliases.every((p) => /[\\/]skills[\\/]/.test(p)) &&
+                entry.aliases.some((p) => !ruleClient(p) &&
+                    (INSTRUCTION.test(path.basename(p)) ||
+                        /[\\/]\.(agents|claude|cursor|codex)[\\/](knowledge|rules)[\\/]/.test(p))))
+                addContext(entry);
+        }
+    }
+    return { context, rules, skills, content, editable, addContext };
+}

package/dist/scan/collect.js

@@ -0,0 +1,107 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { errorCode, id, inside, INSTRUCTION, MARKDOWN, MAX_BYTES, MAX_FILES, required, } from "./values.js";
+const SKIP = new Set([
+    "node_modules",
+    ".git",
+    ".local",
+    "dist",
+    "build",
+    "coverage",
+    ".next",
+    ".cache",
+    ".angular",
+    ".venv",
+    "vendor",
+    "target",
+    "plugins",
+    "sessions",
+    "history",
+]);
+const AGENT_DIRS = [".agents", ".claude", ".codex", ".cursor", ".github"];
+export async function collectFiles(env) {
+    const { root, home, codexHome, includeUser, allowed, display, warnings } = env;
+    const userBases = allowed.slice(1);
+    const files = new Map();
+    const projectConfigs = new Set();
+    let inspected = 0;
+    let capped = false;
+    async function collect(file, scope, ancestors = new Set(), depth = 0) {
+        if (depth > 35 || inspected >= MAX_FILES) {
+            capped = true;
+            return;
+        }
+        try {
+            const real = await fs.realpath(file);
+            if (!allowed.some((base) => inside(base, real)))
+                return;
+            const stat = await fs.stat(real);
+            if (stat.isDirectory()) {
+                if (ancestors.has(real))
+                    return;
+                const next = new Set(ancestors).add(real);
+                const entries = await fs.readdir(file, { withFileTypes: true });
+                for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+                    if (path.basename(file) === ".github" &&
+                        ["agents", "prompts"].includes(entry.name))
+                        continue;
+                    if (SKIP.has(entry.name) ||
+                        (entry.name.startsWith(".") &&
+                            entry.isDirectory() &&
+                            !AGENT_DIRS.includes(entry.name) &&
+                            entry.name !== ".system" &&
+                            entry.name !== ".vscode"))
+                        continue;
+                    await collect(path.join(file, entry.name), scope, next, depth + 1);
+                }
+            }
+            else if (stat.isFile()) {
+                inspected++;
+                if (scope === "project" &&
+                    /(?:^|[\\/])(?:\.mcp\.json|\.cursor[\\/]mcp\.json|\.codex[\\/]config\.toml|\.vscode[\\/]mcp\.json)$/.test(file))
+                    projectConfigs.add(file);
+                if (!MARKDOWN.test(file) && !INSTRUCTION.test(path.basename(file)))
+                    return;
+                if (stat.size > MAX_BYTES) {
+                    warnings.push(`Skipped large context file: ${display(file, scope)}`);
+                    return;
+                }
+                const key = `${scope}:${real}`;
+                if (files.has(key)) {
+                    required(files.get(key)).aliases.push(file);
+                    return;
+                }
+                files.set(key, {
+                    id: id(key),
+                    real,
+                    file,
+                    aliases: [file],
+                    scope,
+                    text: await fs.readFile(real, "utf8"),
+                });
+            }
+        }
+        catch (error) {
+            if (!["ENOENT", "ENOTDIR"].includes(errorCode(error) ?? ""))
+                warnings.push(`Cannot read ${display(file, scope)} (${errorCode(error) || "invalid file"}).`);
+        }
+    }
+    await collect(root, "project");
+    if (includeUser) {
+        for (const base of userBases) {
+            for (const child of ["skills", "knowledge", "rules", "instructions"])
+                await collect(path.join(base, child), "user");
+        }
+        for (const file of [
+            path.join(home, ".claude", "CLAUDE.md"),
+            path.join(codexHome, "AGENTS.md"),
+            path.join(codexHome, "AGENTS.override.md"),
+            path.join(home, ".cursor", "AGENTS.md"),
+            path.join(home, ".copilot", "copilot-instructions.md"),
+        ])
+            await collect(file, "user");
+    }
+    if (capped)
+        warnings.push(`Scan stopped at ${MAX_FILES} files or 35 folder levels. Some assets may be missing.`);
+    return { entries: [...files.values()], projectConfigs, inspected, capped };
+}

package/dist/scan/graph.js

@@ -0,0 +1,71 @@
+import path from "node:path";
+import { referenceResolver } from "./references.js";
+import { links, ruleClient } from "./metadata.js";
+import { inside, required } from "./values.js";
+export function buildGraph(entries, context, addContext, env) {
+    const edges = new Map();
+    const resolveReference = referenceResolver(entries, env);
+    // Follow references from context roots, never turn the entire codebase into a graph.
+    const queue = entries.filter((entry) => context.has(entry.id));
+    const visited = new Set();
+    for (let i = 0; i < queue.length; i++) {
+        const entry = required(queue[i]);
+        if (visited.has(entry.id))
+            continue;
+        visited.add(entry.id);
+        for (const link of links(entry.text)) {
+            const found = resolveReference(entry, link);
+            if (found &&
+                path.basename(found.file) !== "SKILL.md" &&
+                found.aliases.some((p) => !ruleClient(p))) {
+                addContext(found);
+                if (context.has(found.id))
+                    queue.push(found);
+                if (context.has(found.id) && found.id !== entry.id)
+                    edges.set(`${entry.id}:${found.id}`, {
+                        source: entry.id,
+                        target: found.id,
+                        kind: "reference",
+                    });
+            }
+        }
+    }
+    // Dashed hierarchy edges are distinct from explicit document references.
+    const instructions = entries.filter((e) => context.get(e.id)?.kind === "instruction");
+    for (const child of instructions) {
+        const parents = instructions.filter((p) => p.id !== child.id &&
+            p.scope === child.scope &&
+            path.dirname(p.file) !== path.dirname(child.file) &&
+            inside(path.dirname(p.file), child.file));
+        parents.sort((a, b) => b.file.length - a.file.length);
+        if (parents[0])
+            edges.set(`scope:${parents[0].id}:${child.id}`, {
+                source: parents[0].id,
+                target: child.id,
+                kind: "scope",
+            });
+    }
+    // Only explicit references carry discovery to other documents. Folder scope
+    // describes where instructions apply; it does not import the child file.
+    const references = new Map();
+    for (const edge of edges.values()) {
+        if (edge.kind !== "reference")
+            continue;
+        if (!references.has(edge.source))
+            references.set(edge.source, []);
+        required(references.get(edge.source)).push(edge.target);
+    }
+    const pending = [...context.values()].filter((node) => node.clients.length);
+    for (let i = 0; i < pending.length; i++) {
+        const source = required(pending[i]);
+        for (const targetId of references.get(source.id) || []) {
+            const target = required(context.get(targetId));
+            const added = source.clients.filter((client) => !target.clients.includes(client));
+            if (!added.length)
+                continue;
+            target.clients.push(...added);
+            pending.push(target);
+        }
+    }
+    return [...edges.values()];
+}