chamba 0.7.0 → 0.9.0

package/templates/webterm/tools/index.js

@@ -0,0 +1,26 @@
+// =========================================================================================================================================
+// tools/index.js - The tools this pane hosts.
+//
+// One list, and everything about a tool is derived from its row: what is mounted, what is routed, what is broadcast, what a button
+// types and how much of the typing channel one session gets. server.js reads the list and never a tool's name, so a third tool is
+// a row here and a table beside it.
+//
+// The order is the order the tabs are drawn in, which is the pane's own list in `public/app/pane-shell.js`, less Pages: the
+// interface draws that one itself and it has no table here. The two lists are checked against each other by the interface's tests
+// rather than derived from one another, because the pane is drawn in the browser and this file is read in the server.
+// =========================================================================================================================================
+
+import { HOME_TABLE } from "./home.js";
+import { REVIEWS_TABLE } from "./reviews.js";
+import { SPECS_TABLE } from "./specs.js";
+
+export const TOOLS = [HOME_TABLE, SPECS_TABLE, REVIEWS_TABLE];
+
+/** The table of one tool, or undefined. Asked with `find`, so a name that is not a tool's is not one. */
+export function toolTable(id) {
+    return TOOLS.find((table) => table.id === id);
+}
+
+export { commandFor, commandSkill, commandsOf, TOOL_COMMAND_SKILLS, TOOL_COMMANDS } from "./commands.js";
+export { mountTool } from "./mount.js";
+export { CLIENT_PREFIX, toolPaths } from "./paths.js";

package/templates/webterm/tools/mount.js

@@ -0,0 +1,337 @@
+// =========================================================================================================================================
+// tools/mount.js - A pane tool behind its credentials, whichever tool it is.
+//
+// A tool's own knowledge - what its root holds, what one piece of work holds, what it writes - is a module built elsewhere and
+// bundled into one file (see ../../pane-apps/). This is the mount around it: the credentials that open it, the rules about which
+// request may reach which part of it, and the shape of every answer. Nothing here is about one tool, and every tool is mounted
+// through it. What each one is sits in a table of its own, beside this file.
+//
+// One function decides all of that. `handle()` takes a request as plain data and answers with a status, headers and a body, and it
+// neither throws nor rejects: a module that fails answers with a status, so a bug in one tool costs its tab the view and nothing
+// else. A module that answers a promise is awaited here rather than by the caller, so one tool computing its answers with git and
+// another reading a directory are the same thing to everything above. The express side is one delegation in server.js, and holds
+// no decision.
+//
+// Three kinds of request reach a tool, each with its own credential, and neither credential opens anything but its own kind:
+//   - The tool's client, a document and its assets, served open by server.js like every other static file.
+//     It holds nothing secret and drives nothing, and its responses are CORS-readable because the client runs with an opaque
+//     origin and fetches its own module scripts cross-origin.
+//   - The data routes, gated by a tool-scoped key the shell hands into the frame, presented as a header and never in a URL. These
+//     alone answer the cross-origin preflight that header needs.
+//   - Workspace-file loads, gated by a raw-route token that rides as a path segment, because a frame and an image cannot send a
+//     header.
+// The master key opens none of this, and none of this opens the master key: a rendering bug inside a frame leaks that one tool's
+// reading at worst, never the key that types into terminals.
+// =========================================================================================================================================
+
+import { timingSafeEqual } from "node:crypto";
+import { toolPaths } from "./paths.js";
+
+// Read by a frame, which has an opaque origin, so every answer it may read says so. It carries no credential of its own - the
+// browser sends none without `Access-Control-Allow-Credentials`, which nothing here sends - so this opens a route to any origin
+// that already holds the key the route asks for.
+//
+// The data routes alone. Workspace files are not readable cross-origin by anybody: a jailed document can read the token out of its
+// own URL, and making the files it opens readable as well would turn one rendering bug into every file the tool serves, posted
+// anywhere. A frame and an image need no permission to render.
+const CORS_OPEN = { "Access-Control-Allow-Origin": "*" };
+
+// The jail on workspace bytes, sent whatever the media type. Unconditional on purpose: a per-type list would put the one control
+// between workspace content and this origin at the mercy of an enumeration, and the next scriptable type would walk past it. The
+// sandbox token set is the one /pane/page already sends.
+const JAIL = {
+    "Content-Security-Policy": "sandbox allow-scripts allow-forms",
+    "X-Content-Type-Options": "nosniff",
+    "Cache-Control": "no-store",
+};
+
+/** One query or header value as a string. A repeated parameter parses to an array, which is not a value. */
+export function field(value) {
+    return typeof value === "string" ? value : "";
+}
+
+/** Whether a presented credential is the live one, compared in constant time. */
+function holds(presented, secret) {
+    if (typeof presented !== "string" || presented === "") return false;
+    // Byte lengths, not string lengths: timingSafeEqual throws on a length mismatch, and a multi-byte character makes those two
+    // differ.
+    const shown = Buffer.from(presented);
+    const live = Buffer.from(secret);
+    if (shown.length !== live.length) return false;
+    return timingSafeEqual(shown, live);
+}
+
+/** A path as the URL spells it, one segment at a time. Throws for a segment that is not a path. */
+function decodeSegments(rest) {
+    return rest.split("/").map((segment) => decodeURIComponent(segment));
+}
+
+// -----------------------------------------------------------------------------------------------------------------------------------------
+// The route table, as a pattern
+//
+// A pattern is the part of the path after the api prefix, with `:name` for a segment that is the caller's own word:
+// `review/:slug/hunks`. A flat name is a pattern of one literal segment, which is what every Specs route is.
+// -----------------------------------------------------------------------------------------------------------------------------------------
+
+/**
+ * The route a path names, with whatever its pattern captured, or null.
+ *
+ * A literal segment beats a captured one, so `review/:slug/hunks` is a page of hunks rather than an act named `hunks`, however the
+ * two patterns happen to be ordered in the table.
+ *
+ * The table is read through `Object.entries`, which is its own entries and never what an object inherits: a request for
+ * `constructor` or `toString` finds no route, rather than finding a function and treating it as one.
+ */
+export function routeFor(routes, asked) {
+    let best = null;
+    for (const [pattern, route] of Object.entries(routes)) {
+        const parts = pattern.split("/");
+        if (parts.length !== asked.length) continue;
+        const params = {};
+        let literals = 0;
+        let fits = true;
+        for (let at = 0; at < parts.length; at += 1) {
+            const part = parts[at];
+            const said = asked[at];
+            if (part.startsWith(":")) {
+                // A captured segment is somebody's name for something. An empty one names nothing.
+                if (said === "") {
+                    fits = false;
+                    break;
+                }
+                params[part.slice(1)] = said;
+                continue;
+            }
+            if (part !== said) {
+                fits = false;
+                break;
+            }
+            literals += 1;
+        }
+        if (!fits) continue;
+        if (best === null || literals > best.literals) best = { route, params, literals };
+    }
+    return best;
+}
+
+// -----------------------------------------------------------------------------------------------------------------------------------------
+// The mount
+// -----------------------------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Mount one tool behind its credentials.
+ *
+ * `table` is what this tool is - its id, its routes, its verbs and its raw files - and `module` is what it knows, made by the
+ * table's own maker and handed in the way paneStore is handed to the pane: this file decides who may ask, never what the answer is.
+ * `key` opens the data routes and `rawToken` opens the workspace files, and the two are separate so that neither one is the
+ * other's spare.
+ */
+export function mountTool({ table, module, key, rawToken }) {
+    const paths = toolPaths(table.id);
+    const DATA = table.routes(module);
+    const VERBS = table.verbs(module);
+    // The status a thrown error is answered with, out of this tool's own bundle. Every module maps a code rather than a class, so
+    // the answer would be the same from either bundle - and asking the one that threw is what keeps that a property rather than a
+    // coincidence.
+    const statusFor = table.statusFor;
+
+    /** What a caller is told a failure was.
+     *
+     * The module's own words name the path it was asked for, which is the caller's own text. Anything else came from below it, and
+     * those messages carry the container path the tool resolved to - which no caller needs and which the log is the place for.
+     */
+    function reason(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.startsWith(`${table.id}:`)) return message;
+        console.warn(`[webterm] ${table.id}: ${message}`);
+        return "that could not be read";
+    }
+
+    /** The path a workspace file is loaded from. The token is a segment because a frame sends no headers. */
+    const rawBase = `${paths.raw}${rawToken}`;
+
+    function refused(what) {
+        return { status: 403, headers: CORS_OPEN, body: { error: what } };
+    }
+
+    /** The route a data path names, or null. The path is decoded segment by segment, like a raw one. */
+    function dataRoute(path) {
+        let asked;
+        try {
+            asked = decodeSegments(path.slice(paths.api.length));
+        } catch {
+            return null;
+        }
+        return routeFor(DATA, asked);
+    }
+
+    // The preflight the tool's key header needs, answered for the data routes and for nothing else. A route that is not in the
+    // table gets no `Access-Control-Allow-` header at all, which is what a browser reads as "not allowed" rather than as an answer
+    // it may act on.
+    function preflight(path) {
+        const found = dataRoute(path);
+        if (!found) return { status: 403, headers: {}, body: { error: `not a ${table.label} data route` } };
+        return {
+            status: 204,
+            headers: {
+                ...CORS_OPEN,
+                "Access-Control-Allow-Methods": Object.keys(found.route).join(", "),
+                "Access-Control-Allow-Headers": `${paths.keyHeader}, content-type`,
+                "Access-Control-Max-Age": "600",
+            },
+            body: null,
+        };
+    }
+
+    async function data(method, path, query, body, headers) {
+        const found = dataRoute(path);
+        if (!found) return { status: 404, headers: CORS_OPEN, body: { error: `no such ${table.label} route` } };
+        // The gate before the body: a caller without the key learns nothing about what a body would have done.
+        if (!holds(field(headers[paths.keyHeader]), key)) {
+            return refused(`the ${table.label} routes take their key in the ${paths.keyHeader} header`);
+        }
+        const handler = found.route[method];
+        if (!handler) {
+            const allowed = Object.keys(found.route).join(", ");
+            return { status: 405, headers: { ...CORS_OPEN, Allow: allowed }, body: { error: `this route takes ${allowed}` } };
+        }
+        let payload = null;
+        if (body !== null && body !== undefined && body !== "") {
+            try {
+                payload = typeof body === "string" ? JSON.parse(body) : body;
+            } catch {
+                return { status: 400, headers: CORS_OPEN, body: { error: "the body is not JSON" } };
+            }
+        }
+        // Awaited inside the try, so a module that answers a promise is answered by the same rules as one that answers a value: a
+        // rejection is this tool's own status and its own words, rather than a rejection nobody is holding and an empty body.
+        try {
+            return { status: 200, headers: CORS_OPEN, body: await handler({ params: found.params, query, body: payload }) };
+        } catch (error) {
+            return { status: statusFor(error), headers: CORS_OPEN, body: { error: reason(error) } };
+        }
+    }
+
+    async function raw(method, path, headers) {
+        // The jail rides on every answer this route gives, a refusal included: the rule is about the route, not about the happy
+        // path, and a body that says why is still workspace-shaped text.
+        const base = { ...JAIL };
+        if (method !== "GET" && method !== "HEAD") {
+            return { status: 405, headers: { ...base, Allow: "GET, HEAD" }, body: { error: "this route takes GET, HEAD" } };
+        }
+        // Frame and subresource only. The jail's second mechanism is the sandbox of whatever embeds the file, and a top-level
+        // document has no embedder - it would rest on the header alone, which is the one-mechanism state the content boundary
+        // forbids, and a top-level document can do more on an origin than a framed one can.
+        //
+        // A request that says nothing about where it is going is refused with it. Reading an absent header as "not a document"
+        // would hand that refusal to whoever leaves the header off, and the cost of the other way round is visible and small: in a
+        // browser that sends no Fetch Metadata, workspace files do not render.
+        const dest = field(headers["sec-fetch-dest"]);
+        if (dest === "" || dest === "document") {
+            return { status: 403, headers: base, body: { error: "a workspace file renders inside the tool, not as a page of its own" } };
+        }
+        const rest = path.slice(paths.raw.length);
+        const cut = rest.indexOf("/");
+        if (!holds(cut === -1 ? rest : rest.slice(0, cut), rawToken)) {
+            return { status: 403, headers: base, body: { error: "the workspace files take their token in the path" } };
+        }
+        let wanted = "";
+        try {
+            wanted = decodeSegments(cut === -1 ? "" : rest.slice(cut + 1)).join("/");
+        } catch {
+            return { status: 400, headers: base, body: { error: "that path cannot be read" } };
+        }
+        try {
+            const file = await table.raw(module, wanted);
+            return { status: 200, headers: { ...base, "Content-Type": file.mediaType }, body: file.bytes };
+        } catch (error) {
+            return { status: statusFor(error), headers: base, body: { error: reason(error) } };
+        }
+    }
+
+    return {
+        /** Which tool this is, so a caller holding several of them can say which one answered. */
+        id: table.id,
+        /** The root the module resolved, so the mount can say what it is serving. */
+        root: module.root,
+        /** The path prefix a workspace file is loaded from, token included. Handed to the frame, never logged. */
+        rawBase,
+
+        /**
+         * Where a file the tool wrote sits on disk, or null.
+         *
+         * What a typed line is allowed to name. Each module refuses any path that is not one of its own writes, so a delivery can
+         * point an agent at something that tool wrote and at nothing else - not at a file of the workspace, and not at anything
+         * outside the served root.
+         */
+        fileFor(path) {
+            try {
+                return module.toolPath(field(path));
+            } catch {
+                return null;
+            }
+        },
+
+        /**
+         * Answer one verb from this tool's helper.
+         *
+         * The other half of the coordination channel: the pane writes a file and types a line, and an agent moves the work through
+         * these. There is no key here on purpose - the caller is gated by being a process inside a session this server started,
+         * which server.js works out from the caller's pid, the way it does for `webpane`. A key on disk would add nothing, since
+         * everything in the container can read the one that is there.
+         */
+        async agent({ verb, entry, payload }) {
+            const name = field(verb);
+            if (!Object.hasOwn(VERBS, name)) {
+                return { status: 400, body: { error: `${table.id}: no verb named ${name || "(none)"}` } };
+            }
+            try {
+                return { status: 200, body: await VERBS[name](field(entry), payload ?? null) };
+            } catch (error) {
+                return { status: statusFor(error), body: { error: reason(error) } };
+            }
+        },
+
+        /**
+         * Answer one request under this tool's prefix.
+         *
+         * Takes the request as plain data - method, path, query, headers, body - and gives back `{ status, headers, body }`, where
+         * the body is a Buffer for a workspace file, an object for everything else, and null for an answer that carries none. It
+         * never throws, and it never rejects: a module that answers a promise is awaited here, so what a caller gets back is
+         * settled either way.
+         */
+        async handle({ method, path, query, headers, body }) {
+            const verb = String(method || "GET").toUpperCase();
+            const where = String(path || "");
+            // The path decides first and the method second, so the workspace-file route answers everything under it - a preflight
+            // included, which it refuses as a method it does not take, with the jail on the refusal like every other answer it
+            // gives.
+            if (where.startsWith(paths.raw)) return raw(verb, where, headers ?? {});
+            if (where.startsWith(paths.api)) {
+                if (verb === "OPTIONS") return preflight(where);
+                return data(verb, where, query ?? {}, body, headers ?? {});
+            }
+            return { status: 404, headers: {}, body: { error: `no such ${table.label} route` } };
+        },
+
+        /**
+         * Whether this request may carry a body at all.
+         *
+         * Asked before a body is read, so nothing without the key reaches a parser - not the JSON one, and not the buffering
+         * underneath it, which would otherwise hold whatever an anonymous caller sent up to the body limit. The rule is the same
+         * one the data routes are gated by; it is answered earlier.
+         */
+        takesBody(method, path, headers) {
+            const verb = String(method || "").toUpperCase();
+            const where = String(path || "");
+            if ((verb !== "POST" && verb !== "PUT") || !where.startsWith(paths.api)) return false;
+            if (!dataRoute(where)?.route[verb]) return false;
+            return holds(field(headers?.[paths.keyHeader]), key);
+        },
+
+        /** Stop watching the root. The mount holds nothing else that outlives it. */
+        close() {
+            module.close();
+        },
+    };
+}

package/templates/webterm/tools/paths.js

@@ -0,0 +1,34 @@
+// =========================================================================================================================================
+// tools/paths.js - Where a tool answers, derived from its name.
+//
+// Every path and every header a tool has follows from its id. Written out per tool they are six strings that have to agree with
+// each other, with the client's own copy of them, and with the helper's - and a prefix that agrees with a header only most of the
+// time is a tool whose frame is refused for a reason nobody can see. So they are derived, once, here.
+//
+// The client derives the same two names from the same id (`src/lib/api.ts` and `src/lib/shell.ts` in the pane-apps package), which
+// is why a tool's id is the one thing about it that may never be spelled differently on the two sides.
+// =========================================================================================================================================
+
+/**
+ * The paths, prefixes and headers of one tool.
+ *
+ * `keys` and `agent` sit behind the master key, and are the shell's and the helper's doors. `api` and `raw` are the tool's own two
+ * kinds of request, each with its own credential. Both end in a slash, because both are matched as a prefix and a tool named
+ * `review` must never answer for one named `reviews`.
+ */
+export function toolPaths(id) {
+    return {
+        prefix: `/${id}`,
+        keys: `/${id}/keys`,
+        agent: `/${id}/agent`,
+        api: `/${id}/api/`,
+        raw: `/${id}/raw/`,
+        /** The header the tool's key travels in. A header rather than a URL: a document can read the URL it was loaded from. */
+        keyHeader: `x-${id}-key`,
+        /** The header the helper says which process it is in. A claim, and gated as one - see the helper's door in server.js. */
+        pidHeader: `x-${id}-pid`,
+    };
+}
+
+/** Where the built client of one tool is served from. Open statics, one directory per tool. */
+export const CLIENT_PREFIX = "/pane-apps";

package/templates/webterm/tools/reviews.js

@@ -0,0 +1,137 @@
+// =========================================================================================================================================
+// tools/reviews.js - What the Code Reviews tool is, as one table.
+//
+// The same shape as the Specs table beside it, and the differences are the tool's own. A review is a directory with a slug, so its
+// routes name their subject in the path rather than in a query, and the acts of the screen are one route with the act as a segment.
+// Its raw files are two named locations rather than any workspace file, so a browser reaches a stored blob and a signature and
+// nothing else. And it is one of the two modules in this container that run a child process, Home being the other, which is why it
+// is handed the workspace as well as its own root: every git call it makes runs with the repository as its working directory. The
+// runner itself is shared, in the pane-apps server library, and this module hands it a closed table of read-only operations of its own.
+//
+// The framed sentences are the three acts that keep the review with the reviewer. Sending feedback, syncing and filing a review all
+// hand it over, and each of those types the review's command instead: the act starts the agent, and the skill reads the review's
+// state to know what it was woken for. Two lines for one act would be one line too many - the second is refused by the gap the
+// limits set, and an agent acts on whichever arrived first.
+// =========================================================================================================================================
+
+import { createReviewsModule, statusFor } from "../../pane-apps/server/reviews.mjs";
+import {
+    MAX_REVIEWS_BYTES,
+    MAX_REVIEWS_LINE_LENGTH,
+    MAX_REVIEWS_LINES_PER_SESSION,
+    REVIEWS_KEY,
+    REVIEWS_LINE_MIN_INTERVAL_MS,
+    REVIEWS_NEW_SESSION_DELAY_MS,
+    REVIEWS_RAW_TOKEN,
+    REVIEWS_ROOT,
+    WORKSPACE_ROOT,
+} from "../config.js";
+import { field } from "./mount.js";
+
+// The module maker, re-exported so the path to the built dist is written once, as it is for every tool.
+export { createReviewsModule };
+
+/** A count out of a query, or zero. A page asks for a number and gets what the module will give it. */
+function count(value) {
+    const asked = Number.parseInt(field(value), 10);
+    return Number.isFinite(asked) && asked > 0 ? asked : 0;
+}
+
+/**
+ * A selection request out of a query, or null where the query names no kind.
+ *
+ * The words a person typed, passed on as they are: the module reads what it takes and resolves every one of them through git, so
+ * nothing here has to know which of the five shapes carries which field.
+ */
+function selectionFrom(query) {
+    const kind = field(query.kind);
+    if (kind === "") return null;
+    const request = { kind, uncommitted: field(query.uncommitted) === "true" };
+    for (const name of ["branch", "commit", "from", "to", "base"]) {
+        const value = field(query[name]);
+        if (value !== "") request[name] = value;
+    }
+    return request;
+}
+
+export const REVIEWS_TABLE = {
+    id: "reviews",
+    label: "Code Reviews",
+    key: REVIEWS_KEY,
+    rawToken: REVIEWS_RAW_TOKEN,
+    statusFor,
+
+    /** The reviews root, and the repository they are of. */
+    create: ({ onChange }) => createReviewsModule({ root: REVIEWS_ROOT, workspace: WORKSPACE_ROOT, onChange }),
+
+    /**
+     * What a delivery may say it is, in the server's own words.
+     *
+     * Each one is a review that stayed with the reviewer: the agent was stopped mid-act, the review followed a merge, or the
+     * reviewer wants to talk about one hunk in the terminal. Nothing here starts the agent on a review - that is the command in
+     * `commands.js`, and it is typed by the four acts that hand the review over.
+     */
+    events: {
+        stopped: "The reviewer stopped the agent",
+        followed: "This review followed its merge",
+        talk: "The reviewer wants to talk about a hunk",
+    },
+
+    /** As the Specs limits, and for the same reasons. A review carries no images, so its bodies are smaller. */
+    limits: {
+        bytes: MAX_REVIEWS_BYTES,
+        line: MAX_REVIEWS_LINE_LENGTH,
+        interval: REVIEWS_LINE_MIN_INTERVAL_MS,
+        perSession: MAX_REVIEWS_LINES_PER_SESSION,
+        newSession: REVIEWS_NEW_SESSION_DELAY_MS,
+    },
+
+    /**
+     * A stored blob or a signature, by the address the client loads it from.
+     *
+     * The rule about which of the two a path is belongs to the module, which reads it through its own reader: no path here reaches
+     * a file of the workspace, and none reaches anything under a review but those two.
+     */
+    raw: (module, path) => module.raw(path),
+
+    // The pane's routes. A review is named in the path because it is a directory with a name, and the acts of the screen are one
+    // route with the act as its last segment - which is why a literal segment beats a captured one in the matcher: `hunks` is a
+    // page of hunks and never an act.
+    routes: (module) => ({
+        list: { GET: () => module.list() },
+        // With no query it is the offered options, each with its counts. With one it is the single option that query describes,
+        // which is how a commit the reviewer typed and a base they changed get their counts from the same code.
+        options: { GET: ({ query }) => module.options(selectionFrom(query)) },
+        start: { POST: ({ body }) => module.start(body, "form") },
+        "review/:slug": { GET: ({ params }) => module.review(params.slug) },
+        "review/:slug/hunks": {
+            GET: ({ params, query }) => module.hunks(params.slug, count(query.from), count(query.count)),
+        },
+        // The unchanged code around a hunk, from the blob the baseline stored. It is text, so it comes through the data routes
+        // where the tool's key opens them, and not from the raw path - that path is for what a browser renders for itself.
+        "review/:slug/blob": {
+            GET: ({ params, query }) => module.blobLines(params.slug, field(query.name), count(query.from), count(query.count)),
+        },
+        // One route for every act of a review. The module holds the list of them and refuses a name that is not one, so what
+        // an act is stays in one place rather than being a row here as well.
+        "review/:slug/:act": { POST: ({ params, body }) => module.act(params.slug, params.act, body) },
+    }),
+
+    // The helper's verbs. The agent writes metadata and replies and says what it is doing; nothing here marks a hunk seen, closes a
+    // thread, approves, or changes the baseline of its own accord.
+    verbs: (module) => ({
+        // The first call any agent makes: where the reviews live, and what a review may hold.
+        stages: () => module.stages(),
+        state: (entry) => module.agentState(entry),
+        // A review filed from the terminal, which the tab shows with a note saying so.
+        start: (_entry, payload) => module.start(payload, "terminal"),
+        metadata: (entry, payload) => module.metadata(entry, payload),
+        // One group at a time, which several workers may post at once without treading on one another.
+        group: (entry, payload) => module.group(entry, payload),
+        ungroup: (entry, payload) => module.ungroup(entry, payload),
+        reply: (entry, payload) => module.reply(entry, payload),
+        activity: (entry, payload) => module.activity(entry, payload),
+        done: (entry) => module.done(entry),
+        log: (entry, payload) => module.log(entry, payload),
+    }),
+};