jev-agent-tools 0.1.4 → 0.2.0

package/dist/adapters/syntax.js

@@ -0,0 +1,187 @@
+let parserPromise;
+/** Optional grammars resolve from this extension, not the repository under review. */
+export function loadSyntaxParser() {
+    parserPromise ??= createParser();
+    return parserPromise;
+}
+/** Raw AST access shares grammar availability and registration with declaration extraction. */
+export function loadSyntaxRootParser() {
+    parserPromise ??= createParser();
+    return parserPromise;
+}
+async function createParser() {
+    try {
+        const napi = await import("@ast-grep/napi");
+        let python = false;
+        try {
+            const language = await import("@ast-grep/lang-python");
+            napi.registerDynamicLanguage({ python: language.default });
+            python = true;
+        }
+        catch {
+            /* buildUnits reports the missing grammar for each affected file. */
+        }
+        const parser = {
+            supports: (path) => /\.[cm]?[jt]sx?$/.test(path) || (python && path.endsWith(".py")),
+            parseRaw(path, text) {
+                try {
+                    const language = path.endsWith(".py")
+                        ? "python"
+                        : /\.[cm]?tsx?$/.test(path)
+                            ? path.endsWith("tsx")
+                                ? napi.Lang.Tsx
+                                : napi.Lang.TypeScript
+                            : path.endsWith(".jsx")
+                                ? "jsx"
+                                : napi.Lang.JavaScript;
+                    const root = napi.parse(language, text).root();
+                    return { ok: true, root };
+                }
+                catch {
+                    return { ok: false, error: "Source parser unavailable" };
+                }
+            },
+            parse(path, text) {
+                const parsed = this.parseRaw(path, text);
+                if (!parsed.ok)
+                    return parsed;
+                return parsed.root.find({ rule: { kind: "ERROR" } })
+                    ? { ok: false, error: "Source syntax incomplete" }
+                    : parsed;
+            },
+            declarations(path, text, options) {
+                const isPython = path.endsWith(".py");
+                const parsed = this.parseRaw(path, text);
+                if (!parsed.ok)
+                    return { declarations: [], limits: [{ kind: "parse_failed" }] };
+                const root = parsed.root;
+                const result = [];
+                const limits = [];
+                const errors = root.findAll({ rule: { kind: "ERROR" } });
+                const declarationKind = /^(?:function_declaration|generator_function_declaration|method_definition|function_definition|lexical_declaration|variable_declaration|type_alias_declaration|interface_declaration|enum_declaration|class_declaration|class_definition)$/;
+                if (errors.some((error) => !error
+                    .ancestors()
+                    .some((node) => declarationKind.test(String(node.kind()))) &&
+                    (error
+                        .findAll({ rule: { regex: ".*" } })
+                        .some((node) => declarationKind.test(String(node.kind()))) ||
+                        /^(?:export\s+)?(?:function|const|let|var|class)\b/.test(error.text().trim()))))
+                    return { declarations: [], limits: [{ kind: "parse_failed" }] };
+                const attributedErrors = new Set();
+                const source = text.split("\n");
+                const visit = (node) => {
+                    const kind = String(node.kind());
+                    // Most AST nodes cannot yield a declaration; avoid constructing their ancestor chains.
+                    if (!/^(?:function_declaration|generator_function_declaration|method_definition|function_definition|lexical_declaration|variable_declaration|type_alias_declaration|interface_declaration|enum_declaration|expression_statement|class_declaration|class_definition)$/.test(kind)) {
+                        for (const child of node.children())
+                            visit(child);
+                        return;
+                    }
+                    const ancestors = node.ancestors();
+                    const functionNode = /^(?:function_declaration|generator_function_declaration|method_definition|function_definition)$/.test(kind);
+                    const variable = /^(?:lexical_declaration|variable_declaration|type_alias_declaration|interface_declaration|enum_declaration)$/.test(kind) &&
+                        ancestors.every((a) => !/function|method|statement_block/.test(String(a.kind())));
+                    const callableVariable = variable &&
+                        node.find({
+                            rule: {
+                                any: [
+                                    { kind: "arrow_function" },
+                                    { kind: "function_expression" },
+                                ],
+                            },
+                        }) !== null;
+                    const assignment = isPython &&
+                        kind === "expression_statement" &&
+                        node.parent()?.kind() === "module" &&
+                        node.children().some((child) => child.kind() === "assignment");
+                    const classNode = options?.descendAbove !== undefined &&
+                        /^(?:class_declaration|class_definition)$/.test(kind);
+                    if (functionNode || variable || assignment || classNode) {
+                        let envelope = node;
+                        if (node.parent()?.kind() === "decorated_definition" ||
+                            node.parent()?.kind() === "export_statement")
+                            envelope = node.parent() ?? node;
+                        const named = node.field("name") ?? node.find({ rule: { kind: "identifier" } });
+                        const owner = ancestors
+                            .filter((a) => /^(?:class_definition|class_declaration|internal_module|module)$/.test(String(a.kind())))
+                            .reverse()
+                            .map((a) => a.field("name")?.text())
+                            .filter(Boolean);
+                        let name = [...owner, named?.text() ?? "declaration"].join(".");
+                        if (assignment)
+                            name = node.text().split(/\s*[:=]/, 1)[0] ?? "declaration";
+                        let start = envelope.range().start.line;
+                        const body = node.field("body") ??
+                            (callableVariable
+                                ? node
+                                    .find({
+                                    rule: {
+                                        any: [
+                                            { kind: "arrow_function" },
+                                            { kind: "function_expression" },
+                                        ],
+                                    },
+                                })
+                                    ?.field("body")
+                                : null);
+                        const tokens = (part) => {
+                            const children = part.children();
+                            if (!children.length ||
+                                /string|comment/.test(String(part.kind())))
+                                return part.kind() === "comment" ? [] : [part.text()];
+                            return children.flatMap(tokens);
+                        };
+                        const accessor = kind === "method_definition"
+                            ? node
+                                .children()
+                                .find((child) => /^(get|set)$/.test(String(child.kind())))
+                                ?.kind()
+                            : undefined;
+                        const end = envelope.range().end;
+                        // Include the immediately preceding comment block without swallowing another declaration.
+                        while (start > 0 &&
+                            /^\s*(?:\/\/|\/\*|\*|\*\/|#)/.test(source[start - 1] ?? ""))
+                            start--;
+                        result.push({
+                            kind: functionNode || callableVariable ? "function" : "declaration",
+                            name,
+                            type: accessor ? `${kind}:${accessor}` : kind,
+                            signatureEnd: body
+                                ? body.range().start.line + (isPython ? 0 : 1)
+                                : undefined,
+                            body: body ? JSON.stringify(tokens(body)) : undefined,
+                            exported: isPython
+                                ? !name.split(".").some((part) => part.startsWith("_"))
+                                : ancestors.some((a) => a.kind() === "export_statement") ||
+                                    envelope.kind() === "export_statement",
+                            start: start + 1,
+                            end: end.line + (end.column === 0 ? 0 : 1),
+                        });
+                        const declarationErrors = envelope.findAll({
+                            rule: { kind: "ERROR" },
+                        });
+                        if (declarationErrors.length) {
+                            limits.push({ kind: "parse_partial", declaration: name });
+                            for (const error of declarationErrors)
+                                attributedErrors.add(error.id());
+                        }
+                        if (options?.descendAbove === undefined ||
+                            end.line + (end.column === 0 ? 0 : 1) - start <=
+                                options.descendAbove)
+                            return;
+                    }
+                    for (const child of node.children())
+                        visit(child);
+                };
+                visit(root);
+                if (errors.some((error) => !attributedErrors.has(error.id())))
+                    limits.push({ kind: "parse_partial" });
+                return { declarations: result, limits };
+            },
+        };
+        return parser;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/adapters/test-inventory.js

@@ -0,0 +1,131 @@
+import { lstat } from "node:fs/promises";
+import { TEST_SOURCE_MAX_BYTES, TIMEOUT_MS } from "../constants.js";
+import { checkFileAdmission, openRepoFile, resolveInsideRepo, } from "./files.js";
+import { decodeUtf8 } from "./utf8.js";
+export async function collectTestInventory(exec, cwd, signal) {
+    const root = await exec("git", ["rev-parse", "--show-toplevel"], {
+        cwd,
+        timeout: TIMEOUT_MS,
+        signal,
+    });
+    if (root.code !== 0 || root.killed)
+        return {
+            ok: false,
+            error: root.stderr || "Cannot identify repository root.",
+        };
+    cwd = root.stdout.replace(/\n$/, "");
+    const listed = await exec("git", [
+        "ls-files",
+        "--cached",
+        "--others",
+        "--exclude-standard",
+        "--full-name",
+        "-z",
+    ], { cwd, timeout: TIMEOUT_MS, signal });
+    if (listed.code !== 0 || listed.killed)
+        return {
+            ok: false,
+            error: listed.stderr || "Cannot inventory repository files.",
+        };
+    const ignored = await exec("git", ["ls-files", "--cached", "--ignored", "--exclude-standard", "-z"], { cwd, timeout: TIMEOUT_MS, signal });
+    if (ignored.code !== 0 || ignored.killed)
+        return {
+            ok: false,
+            error: ignored.stderr || "Cannot identify ignored tracked files.",
+        };
+    const excluded = new Set(ignored.stdout.split("\0").filter(Boolean));
+    const paths = listed.stdout
+        .split("\0")
+        .filter((path) => path &&
+        (!excluded.has(path) ||
+            /(?:^|\/)(?:package|tsconfig[^/]*)\.json$/.test(path)));
+    const admitted = new Set(paths);
+    const limits = [];
+    const cache = new Map();
+    for (let offset = 0; offset < paths.length; offset += 16) {
+        const inspected = await Promise.all(paths.slice(offset, offset + 16).map(async (path) => {
+            try {
+                signal?.throwIfAborted();
+                const admission = await checkFileAdmission(cwd, path, exec, signal, admitted);
+                if (!admission.ok)
+                    return "unreadable";
+                const resolved = await resolveInsideRepo(cwd, path);
+                if (!resolved.ok)
+                    return "unreadable";
+                const stat = await lstat(resolved.abs);
+                if (!stat.isFile())
+                    return "unreadable";
+                return stat.size > TEST_SOURCE_MAX_BYTES
+                    ? "too_large"
+                    : undefined;
+            }
+            catch {
+                return "unreadable";
+            }
+        }));
+        for (const [index, kind] of inspected.entries()) {
+            if (!kind)
+                continue;
+            const path = paths[offset + index];
+            if (path === undefined || cache.has(path))
+                continue;
+            limits.push({ path, kind });
+            cache.set(path, Promise.resolve(undefined));
+        }
+    }
+    const read = (path) => {
+        const cached = cache.get(path);
+        if (cached)
+            return cached;
+        const pending = (async () => {
+            let handle;
+            try {
+                signal?.throwIfAborted();
+                const opened = await openRepoFile(cwd, path, {
+                    exec,
+                    signal,
+                    inventory: admitted,
+                });
+                if (!opened.ok)
+                    return { path, kind: "unreadable" };
+                handle = opened.handle;
+                const stat = { size: opened.size };
+                if (stat.size > TEST_SOURCE_MAX_BYTES)
+                    return { path, kind: "too_large" };
+                const bytes = Buffer.alloc(Math.min(stat.size + 1, TEST_SOURCE_MAX_BYTES + 1));
+                let count = 0;
+                while (count < bytes.length) {
+                    signal?.throwIfAborted();
+                    const part = await handle.read(bytes, count, bytes.length - count, null);
+                    if (!part.bytesRead)
+                        break;
+                    count += part.bytesRead;
+                }
+                if (count === bytes.length)
+                    return { path, kind: "too_large" };
+                if (bytes.subarray(0, count).includes(0))
+                    return { path, text: "" };
+                const decoded = decodeUtf8(bytes.subarray(0, count));
+                if (!decoded.ok)
+                    return { path, kind: "not UTF-8 text" };
+                const text = decoded.text;
+                return { path, text };
+            }
+            catch {
+                return { path, kind: "unreadable" };
+            }
+            finally {
+                await handle?.close();
+            }
+        })().then((file) => {
+            if (file.kind) {
+                limits.push({ path: file.path, kind: file.kind });
+                return undefined;
+            }
+            return { path: file.path, text: file.text };
+        });
+        cache.set(path, pending);
+        return pending;
+    };
+    return { ok: true, cwd, paths, read, limits };
+}

package/dist/adapters/usage.js

@@ -0,0 +1,20 @@
+export function hostUsage(isOmp, usage) {
+    if (isOmp || !usage)
+        return {};
+    return {
+        usage: {
+            input: usage.inputTokens,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            totalTokens: usage.inputTokens,
+            cost: {
+                input: usage.costUsd,
+                output: 0,
+                cacheRead: 0,
+                cacheWrite: 0,
+                total: usage.costUsd,
+            },
+        },
+    };
+}

package/dist/adapters/utf8.js

@@ -0,0 +1,47 @@
+import { isUtf8 } from "node:buffer";
+import { createHash } from "node:crypto";
+/** Callers enforce byte budgets before decoding. BOM and legitimate controls are preserved. */
+export function decodeUtf8(bytes) {
+    return isUtf8(bytes)
+        ? {
+            ok: true,
+            text: Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("utf8"),
+        }
+        : { ok: false, error: "not UTF-8 text" };
+}
+/** Keep incomplete code points between chunks, but reject them at EOF. */
+export function createUtf8Decoder() {
+    const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+    return (bytes) => {
+        try {
+            return {
+                ok: true,
+                text: decoder.decode(bytes, { stream: bytes !== undefined }),
+            };
+        }
+        catch {
+            return { ok: false, error: "not UTF-8 text" };
+        }
+    };
+}
+/** Verify host-decoded text against the raw Git object; replacement cannot silently become evidence. */
+export function verifyGitUtf8(text, id, size) {
+    const bytes = Buffer.from(text, "utf8");
+    if (size !== undefined && bytes.length !== size)
+        return { ok: false, error: "not UTF-8 text" };
+    if (id && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(id)) {
+        const actual = createHash(id.length === 64 ? "sha256" : "sha1")
+            .update(`blob ${bytes.length}\0`)
+            .update(bytes)
+            .digest("hex");
+        if (actual !== id)
+            return { ok: false, error: "not UTF-8 text" };
+    }
+    else if (text.includes("\uFFFD")) {
+        return {
+            ok: false,
+            error: "not verifiable as UTF-8 text (contains U+FFFD after host decoding)",
+        };
+    }
+    return decodeUtf8(bytes);
+}

package/dist/configuration.js

@@ -0,0 +1,257 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, rename, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { privateStorage, } from "./adapters/private-storage.js";
+import { createJevClient } from "./jev/client.js";
+const fields = ["url", "apiKey", "model"];
+const defaults = { url: "", apiKey: "", model: "openjev" };
+const storageError = () => new Error("Cannot read or save Jev configuration. Check that the configuration directory and config.json are owned by you, private, regular storage without symlinks, and contain valid configuration JSON.");
+function nonempty(value) {
+    return value !== undefined && value.trim().length > 0;
+}
+function validate(values) {
+    let validUrl = false;
+    try {
+        const url = new URL(values.url);
+        validUrl =
+            /^https?:\/\//i.test(values.url) &&
+                (url.protocol === "http:" || url.protocol === "https:") &&
+                url.hostname !== "" &&
+                url.username === "" &&
+                url.password === "";
+    }
+    catch {
+        // Keep user-controlled URL and credentials out of error messages.
+    }
+    if (!validUrl ||
+        !nonempty(values.apiKey) ||
+        /[^\x20-\x7e\x80-\xff]/.test(values.apiKey) ||
+        !nonempty(values.model)) {
+        throw new Error("Jev configuration requires a full HTTP(S) URL without embedded credentials, a nonempty HTTP-header-compatible API key, and a nonempty model.");
+    }
+}
+/** Effective configuration and its client move together, only after a save succeeds. */
+export class ConfigController {
+    environment = {};
+    flags = {};
+    saved = {};
+    session = {};
+    directory;
+    storage;
+    initialization;
+    currentClient;
+    constructor(options = {}) {
+        const env = options.env ?? process.env;
+        this.storage = options.storage ?? privateStorage();
+        for (const [field, name] of [
+            ["url", "JEV_TOOLS_URL"],
+            ["apiKey", "JEV_TOOLS_API_KEY"],
+            ["model", "JEV_TOOLS_MODEL"],
+        ]) {
+            if (nonempty(env[name]))
+                this.environment[field] = env[name];
+        }
+        const base = nonempty(env.XDG_CONFIG_HOME) && isAbsolute(env.XDG_CONFIG_HOME)
+            ? env.XDG_CONFIG_HOME
+            : join(homedir(), ".config");
+        this.directory = resolve(options.directory ?? join(base, "jev-agent-tools"));
+        if (nonempty(this.environment.url) && nonempty(this.environment.apiKey)) {
+            const effective = this.values();
+            validate(effective);
+            this.currentClient = createJevClient(effective);
+        }
+    }
+    get client() {
+        return this.currentClient;
+    }
+    initialize(flags) {
+        if (this.initialization)
+            return this.initialization;
+        this.initialization = this.load(flags).catch((error) => {
+            this.initialization = undefined;
+            throw error;
+        });
+        return this.initialization;
+    }
+    values() {
+        return {
+            ...defaults,
+            ...this.saved,
+            ...this.session,
+            ...this.flags,
+            ...this.environment,
+        };
+    }
+    locked(field) {
+        return (this.environment[field] !== undefined || this.flags[field] !== undefined);
+    }
+    async apply(values, persist) {
+        if (!this.initialization) {
+            throw new Error("Initialize Jev configuration before applying changes.");
+        }
+        await this.initialization;
+        const session = { ...this.session };
+        for (const field of fields) {
+            if (!this.locked(field))
+                session[field] = values[field];
+        }
+        const effective = {
+            ...defaults,
+            ...this.saved,
+            ...session,
+            ...this.flags,
+            ...this.environment,
+        };
+        validate(effective);
+        const saved = { ...this.saved, ...session };
+        if (persist)
+            await this.save(saved);
+        const previous = this.values();
+        this.session = session;
+        if (persist)
+            this.saved = saved;
+        if (fields.some((field) => previous[field] !== effective[field])) {
+            this.currentClient?.clearCache();
+            this.currentClient = createJevClient(effective);
+        }
+        else {
+            this.currentClient ??= createJevClient(effective);
+        }
+    }
+    async load(flags) {
+        const saved = await this.readSaved();
+        const supplied = {};
+        if (nonempty(flags.url))
+            supplied.url = flags.url;
+        if (nonempty(flags.model))
+            supplied.model = flags.model;
+        const effective = {
+            ...defaults,
+            ...saved,
+            ...supplied,
+            ...this.environment,
+        };
+        if (nonempty(effective.url) && nonempty(effective.apiKey)) {
+            validate(effective);
+            this.currentClient?.clearCache();
+            this.currentClient = createJevClient(effective);
+        }
+        this.saved = saved;
+        this.flags = supplied;
+    }
+    async checkDirectory() {
+        // Check ancestors too: recursive mkdir and path-based reads must not follow symlinks.
+        // Privacy of the directory itself is checked with its file in readSaved,
+        // using the operating system's own permission model.
+        let path = this.directory;
+        let exists = true;
+        while (true) {
+            try {
+                const stat = await lstat(path);
+                if (!stat.isDirectory() || stat.isSymbolicLink())
+                    throw storageError();
+            }
+            catch (error) {
+                if (error?.code !== "ENOENT")
+                    throw storageError();
+                if (path === this.directory)
+                    exists = false;
+            }
+            const parent = dirname(path);
+            if (parent === path)
+                break;
+            path = parent;
+        }
+        return exists;
+    }
+    async readSaved() {
+        try {
+            if (!(await this.checkDirectory()))
+                return {};
+            const directory = {
+                path: this.directory,
+                stat: await lstat(this.directory),
+            };
+            const path = join(this.directory, "config.json");
+            try {
+                const stat = await lstat(path);
+                if (!stat.isFile() || stat.isSymbolicLink())
+                    throw storageError();
+            }
+            catch (error) {
+                if (error?.code === "ENOENT") {
+                    if (!(await this.storage.isPrivate([directory])))
+                        throw storageError();
+                    return {};
+                }
+                throw error;
+            }
+            const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                const stat = await file.stat();
+                if (!stat.isFile() ||
+                    stat.nlink !== 1 ||
+                    !(await this.storage.isPrivate([directory, { path, stat }]))) {
+                    throw storageError();
+                }
+                const value = JSON.parse(await file.readFile("utf8"));
+                if (value === null ||
+                    typeof value !== "object" ||
+                    Array.isArray(value) ||
+                    Object.entries(value).some(([key, entry]) => !fields.some((field) => field === key) ||
+                        typeof entry !== "string")) {
+                    throw storageError();
+                }
+                return value;
+            }
+            finally {
+                await file.close();
+            }
+        }
+        catch {
+            throw storageError();
+        }
+    }
+    async save(values) {
+        let temporary;
+        try {
+            const existed = await this.checkDirectory();
+            if (!existed) {
+                await mkdir(this.directory, { recursive: true, mode: 0o700 });
+            }
+            // Windows ignores mkdir's mode, so restrict the ACL before any secret is
+            // written: always for a new directory, and for an existing one only while
+            // it holds no configuration (e.g. left behind by an earlier failed save).
+            // Existing configuration is never re-permissioned; readSaved refuses it.
+            if (!existed ||
+                !(await lstat(join(this.directory, "config.json")).then(() => true, () => false)))
+                await this.storage.restrictDirectory(this.directory);
+            // Refuse to replace malformed, insecure or newly introduced storage.
+            await this.readSaved();
+            temporary = join(this.directory, `.config-${randomUUID()}.tmp`);
+            const file = await open(temporary, constants.O_WRONLY |
+                constants.O_CREAT |
+                constants.O_EXCL |
+                constants.O_NOFOLLOW, 0o600);
+            try {
+                await file.writeFile(`${JSON.stringify(values, null, 2)}\n`, "utf8");
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            await this.readSaved();
+            await rename(temporary, join(this.directory, "config.json"));
+            temporary = undefined;
+        }
+        catch {
+            throw storageError();
+        }
+        finally {
+            if (temporary)
+                await unlink(temporary).catch(() => { });
+        }
+    }
+}