oakode 0.0.0-stage → 0.5.1

package/dist/auth.js

@@ -0,0 +1,456 @@
+/**
+ * Credentials: "Sign in with OICKI" (OAuth 2 authorization code + PKCE, public client) or an API key. Never logs secrets.
+ *
+ * OICKI rotates refresh tokens and treats a reused one as leaked, revoking the whole grant. Several OAKODE processes
+ * share one credentials file, so every refresh happens under a lock file and starts by re-reading the file: a process
+ * whose copy was already rotated by another simply adopts the new tokens instead of sending a stale refresh token.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { chmodSync, closeSync, linkSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeSync } from "node:fs";
+import { OickiError } from "./oicki.js";
+import { DEFAULT_CLIENT_ID, DEFAULT_REDIRECT_PORT, VERSION, baseUrl, home, loadConfig, readJson, writeJson } from "./config.js";
+/**
+ * Where the credentials and their lock live: the data directory, or OAKODE_AUTH_DIR. Evaluations set it so that runs with
+ * their own temporary data directories share ONE sign-in file and lock (rotating refresh tokens stay coordinated);
+ * a sign-in is never copied.
+ */
+const authDir = () => process.env.OAKODE_AUTH_DIR || home();
+const authFile = () => join(authDir(), "auth.json");
+const lockFile = () => join(authDir(), "auth.lock");
+const b64url = (b) => b.toString("base64url");
+/** Refresh this long before expiry, so a request never starts with a token about to lapse. */
+const EARLY_MS = 60_000;
+const expiring = (s) => s.expiresAt - Date.now() < EARLY_MS;
+/** Ports tried in order for the sign-in callback; each must be registered as a redirect URI of the OAKODE service. */
+export const REDIRECT_PORTS = [DEFAULT_REDIRECT_PORT, DEFAULT_REDIRECT_PORT + 1, DEFAULT_REDIRECT_PORT + 2];
+/** OICKI rewrites loopback redirects to `localhost` when it sends the browser back, and the code is bound to that form. */
+export const redirectUri = (port) => `http://localhost:${port}/callback`;
+export const clientIdSetting = () => process.env.OAKODE_CLIENT_ID || loadConfig().clientId || DEFAULT_CLIENT_ID;
+function load() {
+    const s = readJson(authFile());
+    if (!s || (s.type !== "oauth" && s.type !== "apikey"))
+        return undefined;
+    return s;
+}
+export class Auth {
+    stored = load();
+    inflight;
+    /** Called when the credentials on disk turn out to be another sign-in (`oakode login` in another terminal). */
+    onSwitch;
+    constructor() {
+        // A credentials file readable by others (copied, restored from backup, wrong umask) is tightened, not trusted.
+        try {
+            if (statSync(authFile()).mode & 0o077)
+                chmodSync(authFile(), 0o600);
+        }
+        catch { }
+    }
+    /** Where the credentials in use come from. */
+    source() {
+        if (process.env.OICKI_API_KEY?.trim())
+            return "env";
+        return this.stored?.type === "apikey" ? "stored-apikey" : this.stored ? "oauth" : "none";
+    }
+    expiresAt() {
+        return this.stored?.type === "oauth" ? this.stored.expiresAt : undefined;
+    }
+    kind() {
+        if (process.env.OICKI_API_KEY?.trim() || this.stored?.type === "apikey")
+            return "apikey";
+        return this.stored ? "oauth" : "none";
+    }
+    scopes() {
+        return this.stored?.type === "oauth" ? (this.stored.scope ?? "").split(" ").filter(Boolean) : [];
+    }
+    /** The server the stored credentials belong to (older files did not record it: then the default server). */
+    storedServer() {
+        return this.stored ? (this.stored.server ?? "https://oicki.vercel.app") : undefined;
+    }
+    async token() {
+        if (process.env.OICKI_API_KEY?.trim())
+            return process.env.OICKI_API_KEY.trim();
+        let s = checked(this.stored);
+        if (s.type === "apikey")
+            return s.apiKey;
+        if (expiring(s)) {
+            s = checked(this.reload()); // another process may have refreshed (or signed out, or signed in elsewhere)
+            if (s.type === "oauth" && expiring(s))
+                await this.refresh();
+            s = checked(this.stored);
+        }
+        return s.type === "apikey" ? s.apiKey : s.accessToken;
+    }
+    /** Re-reads the credentials file (another OAKODE process may have rotated or removed the tokens). */
+    reload() {
+        const before = this.stored;
+        this.stored = load();
+        // `signIn` is a random id made at `oakode login` and kept through token refreshes (files from before it have none)
+        if (before && this.stored && (before.type !== this.stored.type || (before.signIn && this.stored.signIn && before.signIn !== this.stored.signIn)))
+            this.onSwitch?.("The OICKI credentials changed on disk (a new `oakode login`, maybe in another terminal). This session now uses them, so requests from here on are billed to that sign-in. `/status` shows its plan and credits.");
+        return this.stored;
+    }
+    /**
+     * Gets a fresh access token. `rejected` is the token a request was refused with (401): if another process has
+     * replaced it meanwhile, that one is adopted and nothing is sent to OICKI. Single-flight within the process and
+     * locked across processes.
+     */
+    refresh(rejected) {
+        if (this.stored?.type !== "oauth" || process.env.OICKI_API_KEY?.trim())
+            return Promise.resolve(false);
+        return (this.inflight ??= withLock(() => this.doRefresh(rejected)).finally(() => (this.inflight = undefined)));
+    }
+    async doRefresh(rejected) {
+        const r = this.reload();
+        if (r?.type !== "oauth")
+            return false; // signed out elsewhere
+        const s = checked(r); // a refresh token only ever goes to the server that issued it
+        if (!expiring(s) && s.accessToken !== rejected)
+            return true; // already rotated by another process
+        let tok;
+        try {
+            tok = await tokenRequest({ grant_type: "refresh_token", client_id: s.clientId, refresh_token: s.refreshToken });
+        }
+        catch (e) {
+            if (e instanceof OAuthError && (e.code === "invalid_grant" || e.code === "unauthorized_client" || e.code === "invalid_client")) {
+                // The grant is gone (expired after 30 idle days, revoked, or a reused token was detected). Forget the dead
+                // tokens so no process tries them again, and say what to do.
+                this.clear();
+                throw new OickiError(401, "session_expired", "Your OICKI sign-in has expired or was revoked.");
+            }
+            throw e;
+        }
+        try {
+            this.save({ ...s, ...toStored(tok), scope: tok.scope ?? s.scope });
+        }
+        catch (e) {
+            // OICKI has rotated the tokens but the new pair cannot be stored: the old refresh token on disk is now dead and
+            // would get the grant revoked if another process used it. Remove it; signing in again is the safe way back.
+            this.stored = undefined;
+            try {
+                rmSync(authFile(), { force: true });
+            }
+            catch { }
+            throw new OickiError(401, "session_expired", `The renewed sign-in could not be saved (${e.message}).`);
+        }
+        return true;
+    }
+    save(s) {
+        this.stored = { ...s, server: baseUrl() };
+        writeJson(authFile(), this.stored, true); // persisted before the new tokens are used
+    }
+    setApiKey(apiKey) {
+        this.save({ type: "apikey", apiKey, signIn: randomBytes(8).toString("hex") });
+    }
+    /**
+     * Ends the sign-in on OICKI (POST /oauth/revoke with the refresh token, which revokes both tokens of this sign-in only)
+     * and removes the credentials stored on this computer, whatever OICKI answered. Under the lock, so a refresh in flight
+     * cannot write them back. True when OICKI confirmed the revocation.
+     */
+    logout() {
+        return withLock(async () => {
+            this.reload();
+            const s = this.stored;
+            let revoked = false;
+            if (s?.type === "oauth") {
+                try {
+                    // the server that issued the tokens, never another one
+                    const res = await fetch(this.storedServer() + "/oauth/revoke", {
+                        method: "POST",
+                        headers: { "Content-Type": "application/x-www-form-urlencoded", "User-Agent": `oakode/${VERSION}` },
+                        body: new URLSearchParams({ token: s.refreshToken, token_type_hint: "refresh_token", client_id: s.clientId }),
+                        signal: AbortSignal.timeout(5000),
+                    });
+                    revoked = res.ok;
+                }
+                catch { }
+            }
+            this.clear();
+            return revoked;
+        });
+    }
+    clear() {
+        this.stored = undefined;
+        rmSync(authFile(), { force: true });
+    }
+    async login(opts) {
+        const clientId = opts.clientId || clientIdSetting();
+        if (!clientId)
+            throw new Error("This build of OAKODE has no OICKI client id configured. Use `oakode login --api-key`, or pass `--client-id <your service id>`.");
+        const scope = ["ai:use", "billing:read", ...(opts.expensive ? ["models:expensive"] : [])].join(" ");
+        const verifier = b64url(randomBytes(32));
+        const state = b64url(randomBytes(16));
+        const ports = process.env.OAKODE_REDIRECT_PORT ? [Number(process.env.OAKODE_REDIRECT_PORT)] : REDIRECT_PORTS;
+        const cb = await listenForCallback(ports, state, opts.signal);
+        try {
+            const url = new URL(baseUrl() + "/oauth/authorize");
+            url.search = new URLSearchParams({
+                response_type: "code",
+                client_id: clientId,
+                redirect_uri: redirectUri(cb.port),
+                scope,
+                required_scope: "ai:use",
+                state,
+                code_challenge: b64url(createHash("sha256").update(verifier).digest()),
+                code_challenge_method: "S256",
+            }).toString();
+            const remote = opts.noBrowser || isRemoteSession();
+            if (remote) {
+                opts.log(`Open this link in a browser to sign in:\n\n  ${url}\n\n` +
+                    (isRemoteSession()
+                        ? `This looks like a remote session: the sign-in page sends your browser back to localhost:${cb.port} on the machine running the browser. ` +
+                            `Forward that port first, from your own computer:\n\n  ssh -L ${cb.port}:localhost:${cb.port} <this host>\n\n` +
+                            `Or use an API key instead: oakode login --api-key\n`
+                        : "") +
+                    `Waiting for the browser (Ctrl+C to cancel)…`);
+            }
+            else {
+                opts.log(`Opening your browser to sign in with OICKI. If it does not open, visit:\n\n  ${url}\n\nWaiting for the browser (Ctrl+C to cancel)…`);
+                openBrowser(url.toString());
+            }
+            const code = await cb.code;
+            try {
+                const tok = await tokenRequest({ grant_type: "authorization_code", client_id: clientId, code, redirect_uri: redirectUri(cb.port), code_verifier: verifier });
+                const granted = (tok.scope ?? scope).split(" ").filter(Boolean);
+                if (!granted.includes("ai:use"))
+                    throw new Error("OICKI did not grant `ai:use`, which OAKODE needs. Nothing was saved.");
+                await withLock(async () => this.save({ ...toStored(tok), clientId, scope: granted.join(" "), signIn: randomBytes(8).toString("hex") }));
+                cb.respond(true);
+                return { scopes: granted };
+            }
+            catch (e) {
+                cb.respond(false, e.message);
+                throw e;
+            }
+        }
+        finally {
+            cb.close();
+        }
+    }
+}
+/** A terminal on another machine (SSH) or without a display: opening a browser here would not reach the user. */
+export function isRemoteSession(env = process.env, platform = process.platform) {
+    if (env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY)
+        return true;
+    return platform === "linux" && !env.DISPLAY && !env.WAYLAND_DISPLAY;
+}
+/**
+ * Cross-process mutual exclusion on the credentials: an exclusive-create lock file. A lock older than 30 s belongs to
+ * a process that died while holding it and is taken over.
+ */
+export async function withLock(f) {
+    const file = lockFile();
+    const stamp = `${process.pid} ${Date.now()} ${randomBytes(6).toString("hex")}`;
+    const deadline = Date.now() + 150_000;
+    for (;;) {
+        try {
+            const fd = openSync(file, "wx", 0o600);
+            writeSync(fd, stamp);
+            closeSync(fd);
+            break;
+        }
+        catch (e) {
+            const code = e.code;
+            if (code === "ENOENT") {
+                mkdirSync(home(), { recursive: true, mode: 0o700 });
+                continue;
+            }
+            if (code !== "EEXIST")
+                throw e;
+            takeOverIfStale(file);
+            if (Date.now() > deadline)
+                throw new Error(`Timed out waiting for another OAKODE process to finish renewing the sign-in (${file}).`);
+            await new Promise((r) => setTimeout(r, 100));
+        }
+    }
+    try {
+        return await f();
+    }
+    finally {
+        // only our own lock: if ours was taken over as stale, the file now belongs to someone else
+        try {
+            if (readFileSync(file, "utf8") === stamp)
+                rmSync(file, { force: true });
+        }
+        catch { }
+    }
+}
+/** Longer than any token request (30 s timeout), so a slow refresh is never mistaken for a dead one. */
+const LOCK_STALE_MS = 120_000;
+/**
+ * Removes the lock if its owner is gone: the process is dead, or the lock is older than any refresh can take. The lock
+ * is moved aside atomically and checked to be the one judged stale; if another process replaced it in between, it
+ * is put back (link() does not overwrite).
+ */
+function takeOverIfStale(file) {
+    let seen, mtime;
+    try {
+        seen = readFileSync(file, "utf8");
+        mtime = statSync(file).mtimeMs;
+    }
+    catch {
+        return;
+    }
+    const pid = Number(seen.split(" ")[0]);
+    if (!(Date.now() - mtime > LOCK_STALE_MS || (pid > 0 && !alive(pid))))
+        return;
+    const aside = `${file}.${randomBytes(6).toString("hex")}`;
+    try {
+        renameSync(file, aside);
+    }
+    catch {
+        return; // someone else moved it first
+    }
+    try {
+        if (readFileSync(aside, "utf8") !== seen)
+            linkSync(aside, file); // not the stale one: restore it
+    }
+    catch { }
+    rmSync(aside, { force: true });
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM"; // exists, owned by someone else
+    }
+}
+/** The stored credentials, if there are any and they belong to the server in use. */
+function checked(s) {
+    if (!s)
+        throw new OickiError(401, "not_logged_in", "Not signed in.");
+    const server = (s.server ?? "https://oicki.vercel.app").replace(/\/+$/, "");
+    if (server !== baseUrl())
+        throw new OickiError(401, "wrong_server", `The saved sign-in is for ${server}, but OAKODE is using ${baseUrl()}. Sign in again for this server, or unset OAKODE_BASE_URL.`);
+    return s;
+}
+const toStored = (t) => ({
+    type: "oauth",
+    accessToken: t.access_token,
+    refreshToken: t.refresh_token,
+    expiresAt: Date.now() + t.expires_in * 1000,
+});
+class OAuthError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+async function tokenRequest(params) {
+    let res;
+    try {
+        res = await fetch(baseUrl() + "/oauth/token", {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json", "User-Agent": `oakode/${VERSION}` },
+            body: new URLSearchParams(params),
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch (e) {
+        throw new OickiError(0, "network_error", `Could not reach OICKI to sign in: ${e.message}`);
+    }
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || typeof body.access_token !== "string" || typeof body.refresh_token !== "string") {
+        const code = String(body.error ?? `http_${res.status}`);
+        throw new OAuthError(code, `OICKI refused the sign-in (${code}${body.error_description ? `: ${body.error_description}` : ""}).`);
+    }
+    return body;
+}
+const escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+const page = (title, body) => `<!doctype html><html><head><meta charset="utf-8"><title>OAKODE</title></head><body style="font-family:system-ui,sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem;line-height:1.5"><h2>${escapeHtml(title)}</h2><p>${escapeHtml(body)}</p></body></html>`;
+/**
+ * Listens on the first port of `ports` that is free on the loopback interface, for the browser's return. OICKI sends
+ * the browser to `localhost`, which a browser may resolve to 127.0.0.1 or ::1, so both are bound (::1 only where the
+ * machine has IPv6). The browser's request is answered only once the sign-in has actually finished (`respond`), so
+ * the page never says "signed in" when the token exchange failed.
+ */
+async function listenForCallback(ports, state, signal) {
+    let settle;
+    const code = new Promise((resolve, reject) => (settle = (e, c) => (e ? reject(e) : resolve(c))));
+    code.catch(() => { });
+    let done = false;
+    const finish = (e, c) => {
+        if (done)
+            return;
+        done = true;
+        clearTimeout(timer);
+        settle(e, c);
+    };
+    const timer = setTimeout(() => finish(new Error("Sign-in timed out after 5 minutes. Run `oakode login` to try again.")), 300_000);
+    timer.unref?.();
+    signal?.addEventListener("abort", () => finish(new Error("Sign-in cancelled.")), { once: true });
+    let waiting; // the browser's request, answered by respond()
+    const html = (res, status, title, body) => res.writeHead(status, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" }).end(page(title, body));
+    const handler = (req, res) => {
+        const u = new URL(req.url ?? "/", "http://localhost");
+        if (u.pathname !== "/callback")
+            return void res.writeHead(404).end();
+        const err = u.searchParams.get("error");
+        const c = u.searchParams.get("code");
+        if (u.searchParams.get("state") !== state || done) {
+            // not our request (a stale tab, or someone else's page): refuse without ending the wait
+            return html(res, 400, "This sign-in link is not the current one.", "Go back to the terminal and run `oakode login` again if needed.");
+        }
+        if (err) {
+            const why = u.searchParams.get("error_description") ?? err;
+            html(res, 400, "Sign-in was not completed.", `${why}. You can close this tab.`);
+            return finish(new Error(err === "access_denied" ? "Sign-in was declined in the browser." : `Sign-in failed: ${why}`));
+        }
+        if (!c)
+            return html(res, 400, "Sign-in failed.", "The response had no code.");
+        waiting = res;
+        finish(undefined, c);
+    };
+    const respond = (ok, detail) => {
+        const res = waiting;
+        waiting = undefined;
+        if (!res)
+            return;
+        if (ok)
+            html(res, 200, "Signed in to OAKODE.", "You can close this tab and go back to the terminal.");
+        else
+            html(res, 400, "Sign-in failed.", `${detail ?? "See the terminal for details."} You can close this tab.`);
+    };
+    const listen = (server, port, host) => new Promise((resolve) => {
+        server.once("error", (e) => resolve(e));
+        server.listen(port, host, () => resolve(undefined));
+    });
+    for (const port of ports) {
+        const v4 = createServer(handler);
+        if (await listen(v4, port, "127.0.0.1"))
+            continue;
+        const v6 = createServer(handler);
+        const e6 = await listen(v6, port, "::1");
+        // no IPv6 on this machine is fine; ::1 taken by another program is not (the browser might go there)
+        if (e6 && e6.code !== "EADDRNOTAVAIL" && e6.code !== "EAFNOSUPPORT") {
+            v4.close();
+            continue;
+        }
+        const servers = e6 ? [v4] : [v4, v6];
+        const close = () => {
+            respond(false);
+            for (const s of servers) {
+                s.close();
+                s.closeAllConnections?.();
+            }
+        };
+        return { port, code, respond, close };
+    }
+    clearTimeout(timer);
+    throw new Error(`Ports ${ports.join(", ")} on localhost are all in use, so the browser cannot return to OAKODE. Close the program using them, or use \`oakode login --api-key\`.`);
+}
+function openBrowser(url) {
+    if (process.env.OAKODE_NO_BROWSER)
+        return;
+    // the URL is passed as a single argument, never through a shell, so nothing in it is interpreted
+    const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]] : ["xdg-open", [url]];
+    try {
+        spawn(cmd, args, { stdio: "ignore", detached: true }).on("error", () => { }).unref();
+    }
+    catch { }
+}

package/dist/brief.js

@@ -0,0 +1,97 @@
+/**
+ * A short project brief for the first request: layout, branch and the commands that build and test the project, so
+ * the model does not spend its first replies running ls and cat package.json. Built once per session (it is part of
+ * the cached prompt prefix) and never runs anything a repository could configure: the branch comes from .git/HEAD,
+ * the file list from the same `git ls-files` the search tools use.
+ */
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { workspaceFiles } from "./fileio.js";
+const MAX_ENTRIES = 40;
+/** A small regular file's text: never a FIFO or device (which would block), a symlink, or something huge. */
+function readSmall(p) {
+    try {
+        const st = lstatSync(p);
+        return st.isFile() && st.size < 1024 * 1024 ? readFileSync(p, "utf8") : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readJson(p) {
+    try {
+        return JSON.parse(readSmall(p) ?? "");
+    }
+    catch {
+        return undefined;
+    }
+}
+function branch(cwd) {
+    try {
+        const head = readSmall(join(cwd, ".git", "HEAD"))?.trim();
+        if (!head)
+            return undefined;
+        if (head.startsWith("ref: refs/heads/"))
+            return head.slice(16).replace(/[^\w./-]/g, "?").slice(0, 100);
+        return /^[0-9a-f]{40,64}$/.test(head) ? `detached at ${head.slice(0, 10)}` : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** How this project is built and tested, from its manifest files. */
+export function projectCommands(cwd) {
+    const out = [];
+    const pkg = readJson(join(cwd, "package.json"));
+    if (pkg) {
+        const pm = existsSync(join(cwd, "pnpm-lock.yaml")) ? "pnpm" : existsSync(join(cwd, "yarn.lock")) ? "yarn" : existsSync(join(cwd, "bun.lockb")) || existsSync(join(cwd, "bun.lock")) ? "bun" : "npm";
+        const scripts = Object.entries(pkg.scripts ?? {}).filter(([k]) => /^(test|build|lint|typecheck|check|dev|start|format)(:|$)/.test(k));
+        for (const [k, v] of scripts.slice(0, 10))
+            out.push(`${pm} run ${k}  # ${String(v).slice(0, 100)}`);
+        if (!scripts.length)
+            out.push(`${pm} (package.json has no test/build scripts)`);
+    }
+    if (existsSync(join(cwd, "pyproject.toml")) || existsSync(join(cwd, "setup.py")))
+        out.push(existsSync(join(cwd, "uv.lock")) ? "uv run pytest" : "python -m pytest  # Python project");
+    if (existsSync(join(cwd, "Cargo.toml")))
+        out.push("cargo build / cargo test");
+    if (existsSync(join(cwd, "go.mod")))
+        out.push("go build ./... / go test ./...");
+    const makefile = readSmall(join(cwd, "Makefile"));
+    if (makefile) {
+        const targets = [...makefile.matchAll(/^([A-Za-z][\w-]*):/gm)].map((m) => m[1]).filter((t) => /^(all|build|test|check|lint|run)$/.test(t));
+        if (targets.length)
+            out.push(`make ${targets.join(" | make ")}`);
+    }
+    return out;
+}
+export async function projectBrief(cwd, signal) {
+    const lines = [];
+    const b = branch(cwd);
+    if (b)
+        lines.push(`Git branch: ${b}`);
+    let files = [];
+    let gitignore = false;
+    try {
+        ({ files, gitignore } = await workspaceFiles(cwd, signal));
+    }
+    catch { }
+    if (files.length) {
+        // top-level entries with how many files each holds
+        const counts = new Map();
+        for (const f of files) {
+            const parts = relative(cwd, f).split(sep);
+            const key = parts.length > 1 ? `${parts[0]}/` : parts[0];
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+        }
+        const entries = [...counts].sort(([a], [b]) => Number(b.endsWith("/")) - Number(a.endsWith("/")) || a.localeCompare(b));
+        const shown = entries.slice(0, MAX_ENTRIES).map(([k, n]) => (k.endsWith("/") ? `${k} (${n} file${n > 1 ? "s" : ""})` : k));
+        lines.push(`Top level (${files.length} files${gitignore ? ", .gitignore applied" : ""}): ${shown.join(", ")}${entries.length > MAX_ENTRIES ? `, … ${entries.length - MAX_ENTRIES} more` : ""}`);
+    }
+    else
+        lines.push("The working directory is empty.");
+    const cmds = projectCommands(cwd);
+    if (cmds.length)
+        lines.push("Build/test commands:", ...cmds.map((c) => `  ${c}`));
+    return lines.join("\n");
+}