@50arms/platform-mcp 0.0.0-stage → 0.1.437

package/dist/docs-tools.js

@@ -0,0 +1,140 @@
+/**
+ * DX-5582 - `docs_search` and `docs_read`: one pair of tools over four places a docs root can live, picked by `source`:
+ *
+ *   - `{kind: "local"}`            this checkout's `docs/pages` (the server's working directory),
+ *   - `{kind: "dir", path}`        another docs root on this machine,
+ *   - `{kind: "remote", repo}`     a team repo's hosted docs on the dashboard, by the repo's name (`GET /api/docs/:repo/search`, `GET /api/docs/:repo/pages/:id`),
+ *   - `{kind: "product"}`          50 Arms' own product docs, which every team reads (`GET /api/product-docs/search`, `GET /api/product-docs/pages/:id`).
+ *
+ * The tools never put page text in the agent's context. A search answers which pages and where their files are, with each file's size; a
+ * read answers the path of a file on THIS machine and its size, and the agent reads it with its own file tools (Read with offset/limit,
+ * grep). That is what `50arms_api` cannot do: it answers into context and cannot write a local file.
+ *
+ * The ranking is one engine (`@danxbot/docs` `search.ts`): in-process for local and dir, on the dashboard for remote and product. A local or dir
+ * answer's `file` is an ABSOLUTE path, usable as it stands; a hosted answer's `file` is the page's path inside its docs, and
+ * `docs_read` is what brings it to disk. A hosted page is written to `<tmp>/danx-docs/<repo>/<id>.md` (`<tmp>/danx-product-docs/<id>.md`), replaced on every read, so the
+ * agent never reads a stale copy and re-reads of one page share one path. The file is written under a temp name and renamed into place
+ * (DX-5597), so a reader never sees half a page.
+ */
+import { statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { z } from "zod";
+import { MAX_SEARCH_LIMIT, UnknownNodeIdError, loadLocalDocs, locateLocalPage, searchLocalDocs } from "@danxbot/docs/agent";
+import { repoNameArgSchema } from "./board-id.js";
+import { writeFileDurable } from "./durable-write.js";
+/** The tools' shared `source` argument (one flat object so the schema stays plain: `path` goes with `dir`, `repo` with `remote`; `sourceProblem` enforces it). */
+export const docsSourceShape = z
+    .object({
+    kind: z.enum(["local", "dir", "remote", "product"]).describe("local: this checkout's docs/pages. dir: another docs root here (set path). remote: a team repo's hosted docs (set repo). product: 50 Arms' own product docs, which every team may read."),
+    path: z.string().min(1).optional().describe("kind dir: the docs root directory."),
+    repo: repoNameArgSchema.optional().describe("kind remote: the repo's name."),
+})
+    .strict();
+const REFUSED = 400;
+function refusal(status, error, extra = {}) {
+    return { ok: false, status, body: { error, ...extra } };
+}
+/** A docs page id becomes a file name and a URL segment: refuse anything that is not a plain name before it reaches either. */
+const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** A `source` whose fields do not match its kind is the caller's mistake; say which field, never guess what was meant. */
+function sourceProblem(source) {
+    if (source.kind === "dir") {
+        if (source.path === undefined || source.path === "")
+            return 'source {kind: "dir"} needs a `path`: the docs root directory';
+        if (source.repo !== undefined)
+            return 'source {kind: "dir"} takes a `path`, not a `repo`';
+    }
+    else if (source.kind === "remote") {
+        if (source.repo === undefined)
+            return 'source {kind: "remote"} needs a `repo`: the name of one of the team\'s repos';
+        if (source.path !== undefined)
+            return 'source {kind: "remote"} takes a `repo`, not a `path`';
+    }
+    else if (source.path !== undefined || source.repo !== undefined) {
+        return `source {kind: "${source.kind}"} takes no other field`;
+    }
+    return null;
+}
+/** Where a hosted source's routes live: a repo's under `/api/docs/<repo>`, the product docs' under `/api/product-docs`. Only called once `sourceProblem` passed. */
+function hostedBase(source) {
+    return source.kind === "product" ? "/api/product-docs" : `/api/docs/${source.repo}`;
+}
+/** The local docs root a non-hosted source names; a missing path or one that is not a directory is an error naming it, never an empty search. */
+function localRoot(source, deps) {
+    const root = source.kind === "local" ? path.join(deps.cwd, "docs", "pages") : path.resolve(deps.cwd, source.path);
+    const kind = source.kind === "local" ? "local" : "dir";
+    const stat = statSync(root, { throwIfNoEntry: false });
+    if (stat === undefined)
+        return refusal(404, `no docs root at ${root}`, { source: kind });
+    if (!stat.isDirectory())
+        return refusal(REFUSED, `${root} is not a directory; a docs root is the folder of page files`, { source: kind });
+    return root;
+}
+export async function docsSearch(client, args, deps) {
+    const problem = sourceProblem(args.source);
+    if (problem !== null)
+        return refusal(REFUSED, problem);
+    // DX-5597: refused for every source alike, as the dashboard's search route refuses it (400), never an empty answer for local alone. The
+    // tool schema's `.min(1)` already refuses `""`; this catches a query of only whitespace.
+    if (args.query.trim() === "")
+        return refusal(REFUSED, "query is empty: say what to look for");
+    if (args.limit !== undefined && (!Number.isInteger(args.limit) || args.limit < 1 || args.limit > MAX_SEARCH_LIMIT)) {
+        return refusal(REFUSED, `limit must be a whole number from 1 to ${MAX_SEARCH_LIMIT}`);
+    }
+    if (args.source.kind === "remote" || args.source.kind === "product") {
+        return client.request({
+            method: "GET",
+            path: "/search",
+            basePath: hostedBase(args.source),
+            query: { q: args.query, ...(args.limit === undefined ? {} : { limit: args.limit }) },
+        });
+    }
+    const root = localRoot(args.source, deps);
+    if (typeof root !== "string")
+        return root;
+    const docs = loadLocalDocs(root);
+    const answer = searchLocalDocs(docs, args.query, args.limit === undefined ? {} : { limit: args.limit });
+    return {
+        ok: true,
+        status: 200,
+        body: {
+            query: answer.query,
+            results: answer.results,
+            // A docs tree that still has files the loader rejected would otherwise read as "no docs about this".
+            ...(docs.skipped > 0 ? { skipped_files: docs.skipped } : {}),
+        },
+    };
+}
+export async function docsRead(client, args, deps) {
+    const problem = sourceProblem(args.source);
+    if (problem !== null)
+        return refusal(REFUSED, problem);
+    if (args.source.kind === "remote" || args.source.kind === "product") {
+        if (!SAFE_NAME.test(args.id))
+            return refusal(REFUSED, `"${args.id}" is not a docs page id`);
+        const fetched = await client.request({ method: "GET", path: `/pages/${args.id}`, basePath: hostedBase(args.source) });
+        if (!fetched.ok)
+            return fetched;
+        const page = fetched.body;
+        // DX-5597: the file is named by the id this call validated, never by a field of the answer, and lands whole: a temp name, then a rename.
+        const tmp = deps.tmpDir ?? os.tmpdir();
+        const file = args.source.kind === "product" ? path.join(tmp, "danx-product-docs", `${args.id}.md`) : path.join(tmp, "danx-docs", args.source.repo, `${args.id}.md`);
+        writeFileDurable(file, page.content);
+        const body = { id: args.id, path: file, bytes: page.bytes, lines: page.lines };
+        return { ok: true, status: 200, body };
+    }
+    const root = localRoot(args.source, deps);
+    if (typeof root !== "string")
+        return root;
+    try {
+        const located = locateLocalPage(loadLocalDocs(root), args.id);
+        const body = { id: located.id, path: located.path, bytes: located.bytes, lines: located.lines };
+        return { ok: true, status: 200, body };
+    }
+    catch (err) {
+        if (err instanceof UnknownNodeIdError)
+            return refusal(404, err.message, { nearest: err.nearest });
+        throw err;
+    }
+}

package/dist/durable-write.js

@@ -0,0 +1,56 @@
+/**
+ * DX-6156 - the one durable "atomic" file write of this package: a temp sibling, flushed to disk, then renamed over the target.
+ * Without the flush NTFS journals the rename but not the data, so a hard crash can leave the target at full length filled with NUL bytes.
+ * DX-6117: the parent directory is created here (recursive), so no caller repeats it; a failure before the rename removes the temp sibling and rethrows.
+ * The parent directory is synced after the rename on POSIX only; Windows cannot open a directory for fsync and NTFS journals the rename itself.
+ */
+import { closeSync, fsyncSync, mkdirSync, openSync, renameSync, unlinkSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+const realFs = { openSync, writeSync: (fd, data, offset) => writeSync(fd, data, offset), fsyncSync, closeSync, renameSync, mkdirSync: (path, options) => void mkdirSync(path, options), unlinkSync };
+let tempSeq = 0;
+/**
+ * Write `data` to a temp sibling of `target` (named here, unique per process and call), flush it, then rename it over `target`.
+ * A failing step throws and leaves the old `target` untouched: it is only ever replaced by the rename.
+ */
+export function writeFileDurable(target, data, options = {}) {
+    const fs = options.fs ?? realFs;
+    const temp = `${target}.${process.pid}.${tempSeq++}.tmp`;
+    const bytes = Buffer.from(data, "utf-8");
+    fs.mkdirSync(dirname(target), { recursive: true });
+    const fd = fs.openSync(temp, "w", options.mode);
+    try {
+        try {
+            // writeSync may write fewer bytes than asked; a truncated temp file must never reach the rename.
+            for (let written = 0; written < bytes.length;) {
+                const n = fs.writeSync(fd, bytes, written);
+                if (n <= 0)
+                    throw new Error(`short write to ${temp}: ${written} of ${bytes.length} bytes`);
+                written += n;
+            }
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(temp, target);
+    }
+    catch (err) {
+        // DX-6117: a partial temp sibling is never left behind; the original failure is the one reported.
+        try {
+            fs.unlinkSync(temp);
+        }
+        catch {
+            // the temp may already be gone
+        }
+        throw err;
+    }
+    if ((options.platform ?? process.platform) !== "win32") {
+        const dir = fs.openSync(dirname(target), "r");
+        try {
+            fs.fsyncSync(dir);
+        }
+        finally {
+            fs.closeSync(dir);
+        }
+    }
+}

package/dist/entrypoint.js

@@ -0,0 +1,35 @@
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+/**
+ * True when this module is the process entrypoint (the published bin) rather
+ * than an `import` — the DX-1606 tool-defs generator + its drift test import
+ * the module to introspect tool schemas without booting the stdio server, so
+ * `boot()` + `server.connect()` must run ONLY for the real bin invocation.
+ *
+ * Why the realpath resolve matters (DX-1647): `import.meta.url` reports the
+ * module's REALPATH — Node resolves symlinks for ESM module URLs by default.
+ * When the bin runs via a SYMLINK — both `npx` and global installs link
+ * `node_modules/.bin/platform-mcp` → `dist/index.js` — `process.argv[1]`
+ * is the symlink path, which `pathToFileURL` would NOT match against the
+ * realpath `import.meta.url` carries. So resolve argv[1]'s realpath first; then
+ * the entrypoint is detected under BOTH direct `node dist/index.js` and the
+ * symlinked `npx -y @50arms/platform-mcp` the worker spawns.
+ *
+ * Without this, npx imports the module, registers the tools, and exits 0
+ * WITHOUT starting the server — every dispatch then fails the worker's
+ * "MCP loaded" preflight (`declared-not-loaded=[platform]`).
+ */
+export function isEntrypointModule(moduleUrl, argvPath) {
+    if (typeof argvPath !== "string" || argvPath.length === 0)
+        return false;
+    let resolved;
+    try {
+        resolved = realpathSync(argvPath);
+    }
+    catch {
+        // argv[1] may not resolve on disk (synthetic paths in tests) — fall back to
+        // the raw path so a non-symlinked match still holds.
+        resolved = argvPath;
+    }
+    return moduleUrl === pathToFileURL(resolved).href;
+}

package/dist/forbidden-hint.js

@@ -0,0 +1,23 @@
+export const FORBIDDEN_HINT_KEY = "forbidden.request_permission";
+function hintText(permission) {
+    return (`Refused: your key lacks the permission \`${permission}\`. Call \`request_permission({permissions: ["${permission}"], reason})\` ` +
+        "to ask a person to grant it (it answers at once; keep working on anything else). If you are blocked without it, " +
+        "raise a problem on the card: a person sees problems in Needs You.");
+}
+/** `result` with the hint appended to its `reminders[]` when it is a `403 forbidden` naming a permission, else `result` itself. */
+export function withForbiddenHint(result) {
+    if (result.ok || result.status !== 403)
+        return result;
+    const body = result.body;
+    if (typeof body !== "object" || body === null || Array.isArray(body))
+        return result;
+    const { error, permission, reminders } = body;
+    if (error !== "forbidden" || typeof permission !== "string" || permission === "")
+        return result;
+    if (reminders !== undefined && !Array.isArray(reminders))
+        return result;
+    const existing = (reminders ?? []);
+    if (existing.some((r) => r?.key === FORBIDDEN_HINT_KEY))
+        return result;
+    return { ...result, body: { ...body, reminders: [...existing, { key: FORBIDDEN_HINT_KEY, text: hintText(permission) }] } };
+}

package/dist/guarded-calls.js

@@ -0,0 +1,21 @@
+import { agentGateHalt } from "./agent-gate.js";
+import { withForbiddenHint } from "./forbidden-hint.js";
+/**
+ * DX-5549 / DX-5724 - the one way a tool reaches the dashboard, built over late-bound access and the agent gate (read at CALL time, as `index.ts` binds them in `boot()`).
+ * The agent gate comes first - a session holding no team agent does no dashboard work and gets the sign-in's own answer - except for a call the gate leaves open
+ * (`opts.gateOpen`: `isAgentGateOpenCall` for the proposal routes - proposing an agent is how a session with none gets one - and the no-agent `50arms_api_list` / `50arms_api_spec` answers about them). Then the sign-in halt.
+ *
+ * DX-4434: a refused call's `403 forbidden` gains its `request_permission` hint here, the ONE place it is added.
+ */
+export function makeGuardedCalls(deps) {
+    const guardedCall = async (run, opts = {}) => {
+        if (opts.gateOpen !== true) {
+            const noAgent = agentGateHalt(deps.gate);
+            if (noAgent !== null)
+                return { halt: noAgent };
+        }
+        const guarded = await deps.access().guard(run);
+        return "halt" in guarded ? guarded : { result: withForbiddenHint(guarded.result) };
+    };
+    return { guardedCall };
+}