@codeursenior/pek 0.0.0-stage → 0.1.8

package/dist/scan/identity.js

@@ -0,0 +1,61 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { inside } from "./values.js";
+/** Read only bounded regular files inside the selected project. */
+async function read(root, name, limit) {
+    try {
+        const real = await fs.realpath(path.join(root, ".agents", name));
+        if (!inside(root, real))
+            return;
+        const stat = await fs.stat(real);
+        if (!stat.isFile() || stat.size > limit)
+            return;
+        const file = await fs.open(real, "r");
+        try {
+            const opened = await file.stat();
+            if (!opened.isFile() || opened.size > limit)
+                return;
+            const buffer = Buffer.alloc(limit + 1);
+            let size = 0;
+            while (size < buffer.length) {
+                const { bytesRead } = await file.read(buffer, size, buffer.length - size);
+                if (!bytesRead)
+                    break;
+                size += bytesRead;
+            }
+            return size <= limit ? buffer.subarray(0, size) : undefined;
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch {
+        // An optional identity must never prevent opening the workspace.
+        return;
+    }
+}
+export async function discoverIdentity(root) {
+    const identity = {};
+    const text = await read(root, "NAME.md", 4096);
+    const name = text
+        ?.toString("utf8")
+        .trim()
+        .split(/\r?\n|\r/)[0]
+        ?.replace(/^#{1,6}(?:\s+|$)/, "")
+        .trim();
+    if (name && [...name].length <= 100 && !/[\p{Cc}\p{Cf}\uFFFD]/u.test(name))
+        identity.name = name;
+    for (const [filename, mime, signature] of [
+        ["AVATAR.png", "image/png", "89504e470d0a1a0a"],
+        ["AVATAR.jpeg", "image/jpeg", "ffd8ff"],
+    ]) {
+        const bytes = await read(root, filename, 2 * 1024 * 1024);
+        if (bytes
+            ?.subarray(0, signature.length / 2)
+            .equals(Buffer.from(signature, "hex"))) {
+            identity.avatar = `data:${mime};base64,${bytes.toString("base64")}`;
+            break;
+        }
+    }
+    return identity.name || identity.avatar ? identity : undefined;
+}

package/dist/scan/mcp.js

@@ -0,0 +1,111 @@
+import { parse as jsonc } from "jsonc-parser";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parse as toml } from "smol-toml";
+import { errorCode, id, inside, record, slash } from "./values.js";
+export async function discoverMcp(projectConfigs, env) {
+    const { root, home, codexHome, includeUser, allowed, display, warnings } = env;
+    const mcp = [];
+    async function readConfig(file, format = "json") {
+        try {
+            const real = await fs.realpath(file);
+            if (![...allowed, path.join(home, ".claude.json")].some((base) => inside(base, real)))
+                return {};
+            if ((await fs.stat(real)).size > 2 * 1024 * 1024) {
+                warnings.push(`Skipped oversized config: ${path.basename(file)}`);
+                return {};
+            }
+            const text = await fs.readFile(real, "utf8");
+            if (format === "toml")
+                return record(toml(text));
+            const errors = [];
+            const result = jsonc(text, errors, { allowTrailingComma: true });
+            if (errors.length)
+                throw new Error("Invalid JSON");
+            return record(result);
+        }
+        catch (error) {
+            if (!["ENOENT", "ENOTDIR"].includes(errorCode(error) ?? ""))
+                warnings.push(`Could not parse ${display(file, inside(root, file) ? "project" : "user")}.`);
+            return {};
+        }
+    }
+    function addServers(servers, file, scope, clients, origin) {
+        if (!servers || typeof servers !== "object" || Array.isArray(servers))
+            return;
+        for (const [name, raw] of Object.entries(record(servers))) {
+            if (!raw || typeof raw !== "object")
+                continue;
+            const config = record(raw);
+            const disabled = config.enabled === false || config.disabled === true;
+            // Whitelist public fields. Never expose arguments, env, headers, URLs or credentials.
+            mcp.push({
+                id: id(`${file}:${scope}:${clients.join(",")}:${name}:${origin || ""}`),
+                name,
+                scope,
+                path: display(file, inside(root, file) ? "project" : "user"),
+                clients,
+                transport: config.url
+                    ? config.type === "sse"
+                        ? "SSE"
+                        : "HTTP"
+                    : config.command
+                        ? "stdio"
+                        : "Unknown",
+                status: disabled ? "Disabled" : "Not verified",
+                configured: !disabled,
+                origin: origin || "File configuration",
+            });
+        }
+    }
+    const bases = [[root, "project"]];
+    if (includeUser)
+        bases.push([home, "user"]);
+    const locations = [
+        [".cursor/mcp.json", ["cursor"], "json"],
+        [".mcp.json", ["claude", "copilot"], "json"],
+        [".codex/config.toml", ["codex"], "toml"],
+        [".vscode/mcp.json", ["copilot"], "json"],
+        [".copilot/mcp-config.json", ["copilot"], "json"],
+    ];
+    for (const [base, scope] of bases) {
+        for (const [rel, clients, format] of locations) {
+            if (scope === "user" &&
+                (rel === ".mcp.json" || rel.startsWith(".vscode")))
+                continue;
+            if (scope === "project" && rel.startsWith(".copilot"))
+                continue;
+            const file = scope === "user" && clients.includes("codex")
+                ? path.join(codexHome, "config.toml")
+                : path.join(base, rel);
+            const config = await readConfig(file, format);
+            addServers(config?.mcpServers || config?.mcp_servers || config?.servers, file, scope, clients);
+        }
+    }
+    for (const file of projectConfigs) {
+        const relative = slash(path.relative(root, file));
+        if ([
+            ".mcp.json",
+            ".cursor/mcp.json",
+            ".codex/config.toml",
+            ".vscode/mcp.json",
+        ].includes(relative))
+            continue;
+        const clients = relative.endsWith(".cursor/mcp.json")
+            ? ["cursor"]
+            : relative.endsWith(".codex/config.toml")
+                ? ["codex"]
+                : relative.endsWith(".vscode/mcp.json")
+                    ? ["copilot"]
+                    : ["claude", "copilot"];
+        const config = await readConfig(file, clients.includes("codex") ? "toml" : "json");
+        addServers(config?.mcpServers || config?.mcp_servers || config?.servers, file, "project", clients, "Nested project configuration");
+    }
+    if (includeUser) {
+        const file = path.join(home, ".claude.json");
+        const config = await readConfig(file);
+        addServers(config?.mcpServers, file, "user", ["claude"]);
+        addServers(record(record(config.projects)[root]).mcpServers, file, "project", ["claude"], "Project-local configuration in user settings");
+    }
+    return mcp.sort((a, b) => a.name.localeCompare(b.name));
+}

package/dist/scan/metadata.js

@@ -0,0 +1,67 @@
+import path from "node:path";
+import { parse as yaml } from "yaml";
+import { inside, MARKDOWN, record, required, slash } from "./values.js";
+export const ruleClient = (file) => {
+    if (path.basename(file).toLowerCase() === ".cursorrules")
+        return "cursor";
+    if (!MARKDOWN.test(file))
+        return null;
+    const normalized = slash(file).toLowerCase();
+    if (/(^|\/)\.cursor\/rules\//.test(normalized))
+        return "cursor";
+    if (/(^|\/)\.claude\/rules\//.test(normalized))
+        return "claude";
+    if (/(^|\/)(?:\.github|\.copilot)\/instructions\/.+\.instructions\.md$/.test(normalized))
+        return "copilot";
+    return null;
+};
+export const toolsForSkill = (p) => {
+    const result = [];
+    if (/(^|\/)\.(agents|cursor|claude|codex)\/skills\//.test(p))
+        result.push("cursor");
+    if (/(^|\/)\.claude\/skills\//.test(p))
+        result.push("claude");
+    if (/(^|\/)\.(agents|codex)\/skills\//.test(p))
+        result.push("codex");
+    if (/(^|\/)\.(github|agents|claude|copilot)\/skills\//.test(p))
+        result.push("copilot");
+    return result;
+};
+export const clientsForContextEntry = (alias, scope, root, codexHome) => {
+    const name = path.basename(alias).toLowerCase();
+    if (name === "copilot-instructions.md")
+        return /[\\/](?:\.github|\.copilot)[\\/]copilot-instructions\.md$/i.test(alias)
+            ? ["copilot"]
+            : [];
+    if (name === "agents.override.md")
+        return ["codex"];
+    if (name === "agents.md") {
+        if (scope === "user")
+            return inside(codexHome, alias) ? ["codex"] : ["cursor"];
+        return ["cursor", "codex", "copilot"];
+    }
+    if (name === "claude.local.md")
+        return ["claude"];
+    if (name === "claude.md")
+        return scope === "project" && path.dirname(alias) === root
+            ? ["cursor", "claude"]
+            : ["claude"];
+    return [];
+};
+export function frontmatter(text) {
+    const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+    if (!match)
+        return {};
+    const result = yaml(required(match[1]), { maxAliasCount: 20 });
+    return record(result);
+}
+export function links(text) {
+    const result = [];
+    for (const m of text.matchAll(/\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/g))
+        result.push({ target: required(m[1]).split("#")[0] ?? "", wiki: true });
+    for (const m of text.matchAll(/\]\(\s*(?:<([^>]+)>|([^\s)]+))(?:\s+['"][^)]*)?\)/g))
+        result.push({ target: required(m[1] || m[2]), wiki: false });
+    for (const m of text.matchAll(/(?:`|@)((?:\.{0,2}\/|~\/)?[\w.\-/À-ž]+\.(?:md|mdc))(?=`|\s|$|[,;)])/g))
+        result.push({ target: required(m[1]), wiki: false });
+    return result;
+}

package/dist/scan/references.js

@@ -0,0 +1,46 @@
+import path from "node:path";
+import { required, slash } from "./values.js";
+/** Shared matching semantics for the context graph and token inventory. */
+export function referenceResolver(entries, env) {
+    const { root, home } = env;
+    const byAlias = new Map();
+    const byName = new Map();
+    for (const entry of entries) {
+        for (const alias of entry.aliases)
+            byAlias.set(alias, entry);
+        const name = path
+            .basename(entry.file)
+            .replace(/\.(md|mdc)$/i, "")
+            .toLowerCase();
+        if (!byName.has(name))
+            byName.set(name, []);
+        required(byName.get(name)).push(entry);
+    }
+    return (entry, link) => {
+        let target;
+        try {
+            target = decodeURIComponent(link.target.split("#")[0] ?? "");
+        }
+        catch {
+            return undefined;
+        }
+        if (!target || /^(https?:|mailto:|data:|file:|javascript:)/i.test(target))
+            return undefined;
+        let found;
+        const absolute = target.startsWith("~/")
+            ? path.join(home, target.slice(2))
+            : path.resolve(path.dirname(entry.file), target);
+        found = byAlias.get(absolute) || byAlias.get(`${absolute}.md`);
+        if (!found && !link.wiki)
+            found = byAlias.get(path.resolve(root, target));
+        if (!found && link.wiki) {
+            const candidates = (byName.get(path.basename(target).replace(/\.md$/i, "").toLowerCase()) ||
+                []).filter((e) => e.scope === entry.scope &&
+                (!target.includes("/") ||
+                    e.aliases.some((a) => slash(a).endsWith(`${target.replace(/\.md$/i, "")}.md`))));
+            if (candidates.length === 1)
+                found = candidates[0];
+        }
+        return found;
+    };
+}

package/dist/scan/types.js

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

package/dist/scan/values.js

@@ -0,0 +1,36 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+export const MAX_FILES = 20000;
+export const MAX_BYTES = 512 * 1024;
+export const MAX_DEPTH = 35;
+export const INSTRUCTION = /^(AGENTS(?:\.override)?|CLAUDE(?:\.local)?|GEMINI|copilot-instructions)\.md$|^\.cursorrules$/i;
+export const MARKDOWN = /\.(md|mdc)$/i;
+export const id = (value) => createHash("sha256").update(value).digest("hex").slice(0, 16);
+export const slash = (value) => value.split(path.sep).join("/");
+export const inside = (base, file) => {
+    const relative = path.relative(base, file);
+    return (relative === "" ||
+        (!relative.startsWith(`..${path.sep}`) &&
+            relative !== ".." &&
+            !path.isAbsolute(relative)));
+};
+export const lineCount = (text) => text.length === 0
+    ? 0
+    : text.split(/\r\n|\r|\n/).length - Number(/(?:\r\n|\r|\n)$/.test(text));
+export const truth = (value) => value === true || /^(true|yes|on|1)$/i.test(String(value));
+export const falsehood = (value) => value === false || /^(false|no|off|0)$/i.test(String(value));
+export function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+export function errorCode(error) {
+    const code = record(error).code;
+    return typeof code === "string" ? code : undefined;
+}
+/** Indexes asserted here come from internal maps/arrays populated in the same scan. */
+export function required(value) {
+    if (value === undefined || value === null)
+        throw new Error("Missing indexed scan value");
+    return value;
+}

package/dist/scanner.js

@@ -0,0 +1,68 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { discoverAssets } from "./scan/assets.js";
+import { collectFiles } from "./scan/collect.js";
+import { buildGraph } from "./scan/graph.js";
+import { discoverIdentity } from "./scan/identity.js";
+import { discoverMcp } from "./scan/mcp.js";
+import { inside, slash } from "./scan/values.js";
+import { contextInventory } from "./token-estimator.js";
+/** Inventory only: never executes instructions, hooks, skills or MCP commands. */
+export async function scanProject(project, options = {}) {
+    const home = options.home ?? os.homedir();
+    const includeUser = options.includeUser ?? true;
+    const codexHome = options.codexHome ?? process.env.CODEX_HOME ?? path.join(home, ".codex");
+    const root = await fs.realpath(path.resolve(project));
+    if (!(await fs.stat(root)).isDirectory())
+        throw new Error("Choose a folder to scan.");
+    const allowed = [
+        root,
+        ...(includeUser
+            ? [
+                path.join(home, ".agents"),
+                path.join(home, ".claude"),
+                path.join(home, ".cursor"),
+                path.join(home, ".copilot"),
+                codexHome,
+            ]
+            : []),
+    ];
+    const env = {
+        root,
+        home,
+        codexHome,
+        includeUser,
+        allowed,
+        warnings: [],
+        display(file, scope) {
+            if (scope === "user" && process.platform === "win32")
+                return file;
+            return scope === "user" && inside(home, file)
+                ? "~/" + slash(path.relative(home, file))
+                : slash(path.relative(root, file)) || path.basename(root);
+        },
+    };
+    const { entries, projectConfigs, inspected, capped } = await collectFiles(env);
+    const { context, rules, skills, content, editable, addContext } = await discoverAssets(entries, env);
+    const edges = buildGraph(entries, context, addContext, env);
+    const mcp = await discoverMcp(projectConfigs, env);
+    const data = {
+        project: { name: path.basename(root), path: root },
+        agent: await discoverIdentity(root),
+        scannedAt: new Date().toISOString(),
+        nodes: [...context.values()],
+        rules: [...rules.values()].sort((a, b) => a.name.localeCompare(b.name)),
+        edges,
+        skills: [...skills.values()].sort((a, b) => a.name.localeCompare(b.name)),
+        mcp,
+        warnings: [...new Set(env.warnings)],
+        limits: { includeUser, scannedFiles: inspected, truncated: capped },
+    };
+    return {
+        data,
+        tokenInventory: contextInventory(entries, data, env),
+        content,
+        editable,
+    };
+}

package/dist/server.js

@@ -0,0 +1,127 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs/promises";
+import http from "node:http";
+import { fileURLToPath } from "node:url";
+import { browserAssets } from "./http/assets.js";
+import { HttpError } from "./http/errors.js";
+import { FileOperations } from "./http/files.js";
+import { authenticated, localRequest, securityHeaders, } from "./http/security.js";
+import { scanProject } from "./scanner.js";
+import { optimizationChecks } from "./optimization-checks.js";
+import { estimateTokens } from "./token-estimator.js";
+export async function startServer({ root, port = 0, ...options }) {
+    let snapshot = await scanProject(root, options);
+    let refresh;
+    let checking;
+    const files = new FileOperations();
+    const token = randomBytes(24).toString("hex");
+    const assets = await browserAssets(fileURLToPath(new URL("../dist/browser/", import.meta.url)));
+    const server = http.createServer(async (req, res) => {
+        const address = server.address();
+        if (!address || typeof address === "string") {
+            res.end();
+            return;
+        }
+        const host = `127.0.0.1:${address.port}`;
+        const nonce = randomBytes(24).toString("base64");
+        securityHeaders(res, nonce);
+        const send = (status, body, type = "application/json; charset=utf-8") => {
+            res.writeHead(status, { "Content-Type": type });
+            res.end(typeof body === "string" || Buffer.isBuffer(body)
+                ? body
+                : JSON.stringify(body));
+        };
+        if (!localRequest(req, host))
+            return send(403, { error: "Local requests only." });
+        let url;
+        try {
+            url = new URL(req.url ?? "/", `http://${host}`);
+        }
+        catch {
+            return send(400, { error: "Invalid URL." });
+        }
+        if (url.pathname.startsWith("/api/")) {
+            if (!authenticated(req, token))
+                return send(401, {
+                    error: "Open the URL printed in your terminal to access this session.",
+                });
+            try {
+                if (url.pathname === "/api/file") {
+                    if (!["GET", "PUT", "DELETE"].includes(req.method ?? ""))
+                        return send(405, { error: "Method not allowed." });
+                    const target = snapshot.editable.get(url.searchParams.get("id") ?? "");
+                    if (!target)
+                        return send(404, { error: "Editable file not found." });
+                    return send(200, await files.handle(req, target));
+                }
+                if (req.method !== "GET")
+                    return send(405, { error: "Method not allowed." });
+                if (url.pathname === "/api/optimization-checks") {
+                    checking ??= optimizationChecks(snapshot.data.project.path).finally(() => {
+                        checking = undefined;
+                    });
+                    return send(200, await checking);
+                }
+                if (url.pathname === "/api/token-estimate")
+                    return send(200, estimateTokens(snapshot, url.searchParams.get("client"), url.searchParams.get("model")));
+                if (url.pathname === "/api/scan") {
+                    if (url.searchParams.has("refresh")) {
+                        refresh ??= scanProject(root, options)
+                            .then((result) => {
+                            snapshot = result;
+                        })
+                            .finally(() => {
+                            refresh = undefined;
+                        });
+                        await refresh;
+                    }
+                    return send(200, snapshot.data);
+                }
+                if (url.pathname === "/api/content") {
+                    const text = snapshot.content.get(url.searchParams.get("id") ?? "");
+                    return text === undefined
+                        ? send(404, { error: "Context file not found." })
+                        : send(200, { text });
+                }
+                return send(404, { error: "Not found." });
+            }
+            catch (error) {
+                return send(error instanceof HttpError ? error.status : 500, {
+                    error: error instanceof HttpError
+                        ? error.message
+                        : "File operation failed. Check permissions and try again.",
+                });
+            }
+        }
+        if (req.method !== "GET")
+            return send(405, { error: "Method not allowed." });
+        const asset = assets.get(url.pathname);
+        if (!asset)
+            return send(url.pathname === "/" ? 500 : 404, {
+                error: url.pathname === "/"
+                    ? "UI assets missing. Run npm run build."
+                    : "Not found.",
+            });
+        try {
+            const bytes = await fs.readFile(asset.file);
+            send(200, url.pathname === "/"
+                ? bytes.toString("utf8").replaceAll("__CSP_NONCE__", nonce)
+                : bytes, asset.type);
+        }
+        catch {
+            send(500, { error: "UI assets missing. Run npm run build." });
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("Server did not bind to a local port.");
+    return {
+        server,
+        token,
+        url: `http://127.0.0.1:${address.port}/#token=${token}`,
+    };
+}