@snagset/server 0.1.2 → 0.1.4

package/dist/serverless.js

@@ -4,129 +4,95 @@ import { loadConfig } from "./config.js";
 import { applyPlatformDefaults } from "./platform.js";
 import { createApp } from "./app.js";
 import { resolveSecretKey } from "./boot.js";
-/**
- * The serverless entry point — 08 §3.2, LOCK L5, L2.3.
- *
- * The SECOND entry on the same `createApp(deps)`. The bin owns a process and
- * can boot, tick and hold a pool; a function instance owns none of that, and
- * §3.2 names the four differences. All four are implemented here and nowhere
- * else, which is the point of there being one app factory.
- *
- *  1. **Jobs are a cron, not an interval.** `/api/jobs/run` invokes
- *     `runDueJobs`, driven by `vercel.json`'s schedule. Nothing may depend on
- *     a long-lived process — no LISTEN/NOTIFY, no resident state.
- *  2. **Migrations run at deploy**, as a release step. A function instance has
- *     no boot to hook, and migrating on cold start would take the advisory
- *     lock on a request's critical path — every instance queueing behind one
- *     that is applying DDL, on somebody's first page load.
- *  3. **`DATABASE_URL` must be POOLED.** The marketplace resources hand one
- *     out. Interactive transactions work in transaction-pooling mode, so L6's
- *     same-transaction outbox guarantee holds.
- *  4. **`SNAGSET_SECRET_KEY` is required**, because §4.2's generate-a-key-to-
- *     disk is bin-only: the filesystem here is ephemeral, so a generated key
- *     would differ per instance and every session and encrypted credential
- *     would decrypt on one and fail on the next. Checked below, with the
- *     reason, rather than left to fail as corrupted ciphertext.
- */
-/**
- * The app, built ONCE per instance and reused across invocations.
- *
- * Module scope is the only warm thing a function has. Rebuilding per request
- * would re-read config, re-derive the keyring and open a new pool on every
- * call — which on a pooled Postgres is how an instance exhausts the very
- * connection limit the pooler exists to protect.
- */
-let cached = null;
-function boot() {
-    if (cached)
+export function createServerlessHandler(options = {}) {
+    let cached = null;
+    function boot() {
+        if (cached)
+            return cached;
+        applyPlatformDefaults(process.env); // D105 — Vercel names its own deployment
+        const cfg = loadConfig(process.env);
+        if (!cfg.get("SNAGSET_SECRET_KEY") && !cfg.get("SNAGSET_SECRET_KEY_FILE")) {
+            throw new Error("SNAGSET_SECRET_KEY is required on serverless. The filesystem here is ephemeral, so " +
+                "the bin's generate-a-key-on-first-boot path cannot work: each instance would invent " +
+                "a different key, and a session or an encrypted credential written by one would fail " +
+                "to decrypt on the next. Generate 32 random bytes, base64url them, and set it in the " +
+                "deploy's environment (08 §4.2).");
+        }
+        const sql = connect(cfg.required("DATABASE_URL"), { max: cfg.int("SNAGSET_DATABASE_POOL_MAX") });
+        const app = createApp({
+            sql,
+            cfg,
+            secretKey: resolveSecretKey(cfg, null, () => { }),
+            // A function instance cannot run the boot state machine — that reads and
+            // writes the claim token and would race across instances. The state is
+            // derived per request from the database instead, which is what `createApp`
+            // does when it is told nothing.
+            state: "READY",
+            version: options.version ?? process.env["SNAGSET_VERSION"] ?? "0.0.0",
+            commit: process.env["VERCEL_GIT_COMMIT_SHA"] ?? "unknown",
+            sourceUrl: options.sourceUrl ?? "https://github.com/snagset/snagset",
+            modified: false,
+            ...(options.planResolver ? { planResolver: options.planResolver } : {}),
+        });
+        cached = { app, sql };
         return cached;
-    applyPlatformDefaults(process.env); // D105 — Vercel names its own deployment
-    const cfg = loadConfig(process.env);
-    if (!cfg.get("SNAGSET_SECRET_KEY") && !cfg.get("SNAGSET_SECRET_KEY_FILE")) {
-        throw new Error("SNAGSET_SECRET_KEY is required on serverless. The filesystem here is ephemeral, so " +
-            "the bin's generate-a-key-on-first-boot path cannot work: each instance would invent " +
-            "a different key, and a session or an encrypted credential written by one would fail " +
-            "to decrypt on the next. Generate 32 random bytes, base64url them, and set it in the " +
-            "deploy's environment (08 §4.2).");
     }
-    const sql = connect(cfg.required("DATABASE_URL"), { max: cfg.int("SNAGSET_DATABASE_POOL_MAX") });
-    const app = createApp({
-        sql,
-        cfg,
-        secretKey: resolveSecretKey(cfg, null, () => { }),
-        // A function instance cannot run the boot state machine — that reads and
-        // writes the claim token and would race across instances. The state is
-        // derived per request from the database instead, which is what `createApp`
-        // does when it is told nothing.
-        state: "READY",
-        version: process.env["SNAGSET_VERSION"] ?? "0.0.0",
-        commit: process.env["VERCEL_GIT_COMMIT_SHA"] ?? "unknown",
-        sourceUrl: "https://github.com/snagset/snagset",
-        modified: false,
-    });
-    cached = { app, sql };
-    return cached;
-}
-/**
- * The Web-standard handler every serverless target accepts.
- *
- * A `fetch(Request) => Response` rather than a Vercel-shaped adapter, because
- * that is the same signature Cloudflare Workers, Deno and Bun take — D24 makes
- * Workers the next hosting milestone on this same app factory, and an entry
- * point written to one vendor's helper is one that has to be rewritten for it.
- */
-/**
- * A CONFIGURATION FAILURE SHOULD SAY SO, not crash.
- *
- * `boot()` throws when a required variable is missing, and until 2026-09-01
- * that throw reached the platform — which renders "This Serverless Function
- * has crashed. FUNCTION_INVOCATION_FAILED" and puts the real message in
- * function logs the operator may not know exist. On the deploy we bless, on
- * the very first request, for the most ordinary mistake there is.
- *
- * The bin has had `explain()` for this since it shipped: an unreachable
- * database prints "✗ no Postgres answered at host:port. Start one, or point
- * DATABASE_URL at a database that is running." Serverless had nothing, so the
- * same operator got a sentence on the bin and a shrug on Vercel.
- *
- * NAMES ONLY, never values — this response is public, and the whole point of
- * the variable being missing is that somebody is about to paste a secret into
- * a dashboard. `503` rather than `500`: the instance is not broken, it is not
- * configured, and a proxy should feel free to retry once it is.
- */
-function configFailure(e) {
-    const message = e instanceof Error ? e.message : String(e);
-    return new Response(`Snagset is deployed but not configured.\n\n${message}\n\n` +
-        `Set it in your platform's environment settings and redeploy.\n` +
-        `\`snagset env\` lists every variable this build accepts.\n`, { status: 503, headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" } });
-}
-function serve(request) {
-    let app;
-    try {
-        app = boot().app;
+    /**
+     * The Web-standard handler every serverless target accepts.
+     *
+     * A `fetch(Request) => Response` rather than a Vercel-shaped adapter, because
+     * that is the same signature Cloudflare Workers, Deno and Bun take — D24 makes
+     * Workers the next hosting milestone on this same app factory, and an entry
+     * point written to one vendor's helper is one that has to be rewritten for it.
+     */
+    /**
+     * A CONFIGURATION FAILURE SHOULD SAY SO, not crash.
+     *
+     * `boot()` throws when a required variable is missing, and until 2026-09-01
+     * that throw reached the platform — which renders "This Serverless Function
+     * has crashed. FUNCTION_INVOCATION_FAILED" and puts the real message in
+     * function logs the operator may not know exist. On the deploy we bless, on
+     * the very first request, for the most ordinary mistake there is.
+     *
+     * The bin has had `explain()` for this since it shipped: an unreachable
+     * database prints "✗ no Postgres answered at host:port. Start one, or point
+     * DATABASE_URL at a database that is running." Serverless had nothing, so the
+     * same operator got a sentence on the bin and a shrug on Vercel.
+     *
+     * NAMES ONLY, never values — this response is public, and the whole point of
+     * the variable being missing is that somebody is about to paste a secret into
+     * a dashboard. `503` rather than `500`: the instance is not broken, it is not
+     * configured, and a proxy should feel free to retry once it is.
+     */
+    function configFailure(e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return new Response(`Snagset is deployed but not configured.\n\n${message}\n\n` +
+            `Set it in your platform's environment settings and redeploy.\n` +
+            `\`snagset env\` lists every variable this build accepts.\n`, { status: 503, headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" } });
     }
-    catch (e) {
-        // Nothing is cached on this path, so the NEXT request boots again — set
-        // the variable and the instance recovers without a redeploy.
-        return configFailure(e);
+    function serve(request) {
+        let app;
+        try {
+            app = boot().app;
+        }
+        catch (e) {
+            // Nothing is cached on this path, so the NEXT request boots again — set
+            // the variable and the instance recovers without a redeploy.
+            return configFailure(e);
+        }
+        return app.fetch(request);
     }
-    return app.fetch(request);
-}
-export default { fetch: serve };
-/** Named, for platforms whose convention is a bare exported function. */
-export const handler = serve;
-/**
- * Release the instance's pool. **Tests only** — a function instance is torn
- * down by the platform and never calls this.
- *
- * It exists because the cache above is module scope, which is exactly what
- * makes a warm instance cheap and what makes a test process hang: without it
- * node's runner waits forever on a pool nothing will close.
- */
-export async function closeForTests() {
-    const held = cached;
-    cached = null;
-    if (held)
-        await held.sql.end({ timeout: 5 });
+    async function closeForTests() {
+        const held = cached;
+        cached = null;
+        if (held)
+            await held.sql.end({ timeout: 5 });
+    }
+    return { fetch: serve, closeForTests };
 }
+/** The blessed deploy: the engine as it is, no resolver, unlimited — every self-host's serverless entry. */
+const standard = createServerlessHandler();
+export default { fetch: standard.fetch };
+export const handler = standard.fetch;
+export const closeForTests = standard.closeForTests;
 //# sourceMappingURL=serverless.js.map

package/dist/serverless.js.map

@@ -1 +1 @@
-{"version":3,"file":"serverless.js","sourceRoot":"","sources":["../src/serverless.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"serverless.js","sourceRoot":"","sources":["../src/serverless.ts"],"names":[],"mappings":"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"}

package/dist/storage/settings.js

@@ -1,5 +1,6 @@
 import { open, seal } from "../crypto.js";
 import { createBucket } from "./bucket.js";
+import { maintenance } from "../db/scope.js";
 /**
  * The bucket, from the environment — D60, and the PRIMARY path.
  *
@@ -47,10 +48,10 @@ export function envBucketConfig(env) {
     };
 }
 const orgRow = async (sql) => {
-    const rows = await sql `
+    const rows = await maintenance(sql, (tx) => tx `
     SELECT id, storage_config, storage_credentials, storage_credentials_iv, storage_connected_at
     FROM orgs WHERE deleted_at IS NULL ORDER BY created_at LIMIT 1
-  `;
+  `);
     return rows[0] ?? null;
 };
 export async function storageStatus(sql, keys, env = process.env) {
@@ -102,15 +103,15 @@ export async function connectBucket(sql, keys, config, creds) {
     if (!org)
         return { ok: false, step: "instance", detail: "this instance is not claimed yet" };
     const sealed = seal(keys, JSON.stringify(creds));
-    await sql `
+    await maintenance(sql, (tx) => tx `
     UPDATE orgs
-    SET storage_config = ${sql.json({ ...config })},
+    SET storage_config = ${tx.json({ ...config })},
         storage_credentials = ${sealed.ciphertext},
         storage_credentials_iv = ${sealed.iv},
         storage_connected_at = now(),
         updated_at = now()
     WHERE id = ${org.id}
-  `;
+  `);
     return { ok: true };
 }
 /**
@@ -122,11 +123,11 @@ export async function connectBucket(sql, keys, config, creds) {
  * costing money and recoverable by nobody.
  */
 export async function disconnectBucket(sql) {
-    await sql `
+    await maintenance(sql, (tx) => tx `
     UPDATE orgs
     SET storage_connected_at = NULL, storage_credentials = NULL,
         storage_credentials_iv = NULL, updated_at = now()
     WHERE deleted_at IS NULL
-  `;
+  `);
 }
 //# sourceMappingURL=settings.js.map

package/dist/storage/settings.js.map

@@ -1 +1 @@
-{"version":3,"file":"settings.js","sourceRoot":"","sources":["../../src/storage/settings.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../../src/storage/settings.ts"],"names":[],"mappings":"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"}

package/dist/vendor/mcp/bin.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+/**
+ * The stdio entry point — 07 §8.1's supported transport.
+ *
+ * | Transport | Where it runs | Default |
+ * |---|---|---|
+ * | **stdio** | the developer's own machine, spawned by their MCP client | **the supported path** |
+ * | streamable HTTP | our server, at `POST /mcp` (D107) | **off** until the switch on Studio › Integrations › MCP, or `SNAGSET_MCP_HTTP_ENABLED` (D108) |
+ *
+ * This file is the first. stdio is the default and §8.5 is the reason, not
+ * a scheduling accident: source mapping needs the checkout, the checkout is
+ * on the developer's machine, and a remote server cannot offer `source:map`
+ * at all — the instance serves the second without it.
+ *
+ * ── NOTHING MAY BE WRITTEN TO STDOUT ──
+ *
+ * stdout IS the protocol channel. A `console.log` anywhere in this package
+ * corrupts the JSON-RPC stream and the client reports a parse error with no
+ * indication of where it came from. Diagnostics go to stderr, which the client
+ * shows in its logs. This is the single most common way an MCP server that
+ * works in a test fails in a real client.
+ */
+const env = process.env;
+/**
+ * Config comes from the MCP CLIENT's process env (§8.2), not ours — it is
+ * written into the client's config file:
+ *
+ * ```jsonc
+ * { "mcpServers": { "snagset": { "command": "npx", "args": ["-y", "./server.js"],
+ *     "env": { "SNAGSET_MCP_TOKEN": "…", "SNAGSET_MCP_HOST": "https://review.example.com" } } } }
+ * ```
+ *
+ * `CLICKREVIEW_TOKEN` and `CLICKREVIEW_HOST` are DELETED — the last
+ * un-namespaced spelling in 07, kept there only as a deletion record. They are
+ * not read here, not even as a fallback: a fallback is how a deleted name stays
+ * alive for years.
+ */
+const token = env["SNAGSET_MCP_TOKEN"];
+const host = env["SNAGSET_MCP_HOST"];
+function die(message) {
+    // stderr, and a non-zero exit. A server that starts and then answers every
+    // tool call with "no token" looks to the agent like a product that does not
+    // work; failing at startup puts the message where the developer configuring
+    // it will actually see it.
+    process.stderr.write(`snagset-mcp: ${message}\n`);
+    process.exit(2);
+}
+if (!token) {
+    die("SNAGSET_MCP_TOKEN is not set. Mint one on the instance with `snagset mcp-token create <name>` " +
+        "and put it in your MCP client's config under env.");
+}
+if (!host) {
+    die("SNAGSET_MCP_HOST is not set — the base URL of your Snagset instance, e.g. https://review.example.com");
+}
+if (!token.startsWith("snagmcp_")) {
+    // Named early because the two credentials look nothing alike and the failure
+    // otherwise arrives as a 401 on the first tool call, three steps later.
+    die("SNAGSET_MCP_TOKEN does not look like an MCP token — they begin `snagmcp_`. An API key will not work here.");
+}
+const server = createServer({
+    host,
+    token,
+    // The client spawns us in the developer's project directory, which is what
+    // makes `map_thread_to_source` work with no configuration at all.
+    repoRoot: env["SNAGSET_MCP_REPO_ROOT"] ?? process.cwd(),
+    project: env["SNAGSET_MCP_PROJECT"],
+    version: env["SNAGSET_MCP_VERSION"] ?? "0.0.0",
+});
+await server.connect(new StdioServerTransport());
+process.stderr.write(`snagset-mcp: connected to ${host}\n`);

package/dist/vendor/mcp/client.js

@@ -0,0 +1,107 @@
+/**
+ * The HTTP client — 07 §8.1's load-bearing sentence made literal.
+ *
+ * > *"It is not a second API. Every read the MCP server performs goes through
+ * > the same `/api/v1` routes with the same authorisation as any other caller;
+ * > it holds no database connection, no credential store and no cache of its
+ * > own. A bug in this package cannot read a thread its token could not already
+ * > read."*
+ *
+ * That last clause is a claim about THIS FILE, and it is only true while this
+ * is the only way out of the package. There is no `postgres` dependency here
+ * and there must never be one: the day this package can reach the database, its
+ * scopes become advisory and every mitigation in §8.6 rests on the agent
+ * behaving.
+ *
+ * The whole surface is one method. `fetch` is the platform's, so the package
+ * carries no HTTP dependency either.
+ */
+export class Client {
+    #host;
+    #token;
+    #fetch;
+    constructor(cfg) {
+        // Trailing slash removed once, here, rather than at eleven call sites —
+        // `https://x/` + `/api/v1` is a double slash, which some proxies 404 and
+        // some silently normalise, so it fails on somebody else's deployment and
+        // not on ours.
+        this.#host = cfg.host.replace(/\/+$/, "");
+        this.#token = cfg.token;
+        this.#fetch = cfg.fetch ?? globalThis.fetch;
+    }
+    get host() {
+        return this.#host;
+    }
+    async call(path, init = {}) {
+        const url = new URL(this.#host + path);
+        for (const [k, v] of Object.entries(init.query ?? {})) {
+            if (v !== undefined && v !== "")
+                url.searchParams.set(k, v);
+        }
+        let res;
+        try {
+            res = await this.#fetch(url, {
+                method: init.method ?? "GET",
+                headers: {
+                    Authorization: `Bearer ${this.#token}`,
+                    ...(init.body === undefined ? {} : { "content-type": "application/json" }),
+                },
+                ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+            });
+        }
+        catch (e) {
+            // A network failure is the single most likely thing to go wrong here —
+            // the agent is on a laptop, the instance is somewhere else — and the
+            // message names the host, because "fetch failed" sends a developer to
+            // look at their code rather than at their VPN.
+            return {
+                ok: false,
+                status: 0,
+                message: `Could not reach ${this.#host}: ${e instanceof Error ? e.message : String(e)}. Check SNAGSET_MCP_HOST and that the instance is running.`,
+            };
+        }
+        const text = await res.text();
+        if (!res.ok) {
+            const parsed = safeJson(text);
+            const code = parsed?.error?.code;
+            const message = parsed?.error?.message ?? text.slice(0, 400);
+            // 07 §8.4: on 429 the tool layer must tell the agent to STOP and ask its
+            // user — *"never a silent retry, never a sleep-and-retry loop. An agent
+            // that has been talked into mass-resolving threads must hit a wall it has
+            // to report, because the wall is the only part of the mitigation a human
+            // sees."* This client therefore has no retry logic at all, on any status.
+            if (res.status === 429) {
+                // Appended only when the server did not already say it. The server's
+                // own budget message ends "do not retry", and adding ours produced
+                // "…do not retry. Do not retry — tell your user." — a stop signal that
+                // reads like a stutter, which is the opposite of what it is for.
+                const stop = /do not retry/i.test(message) ? "" : " Do not retry — tell your user.";
+                return { ok: false, status: 429, message: message + stop };
+            }
+            if (code === "mcp_scope_denied") {
+                return { ok: false, status: 403, message };
+            }
+            return { ok: false, status: res.status, message: `${res.status}: ${message}` };
+        }
+        const value = safeJson(text);
+        if (value === null && text.trim() !== "null") {
+            return {
+                ok: false,
+                status: res.status,
+                // The exact failure the server's own widget route had: a 200 with an
+                // HTML body, because an SPA fallback answered a path nobody had
+                // registered. Named, because "unexpected token <" is not a diagnosis.
+                message: `${this.#host} answered ${res.status} with something that is not JSON. Is SNAGSET_MCP_HOST pointing at a Snagset instance?`,
+            };
+        }
+        return { ok: true, value: value };
+    }
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}