@bridge_gpt/mcp-server 0.2.53 → 0.2.54

package/build/local-artifact-storage.js

@@ -0,0 +1,130 @@
+/**
+ * Structured local artifact persistence primitives (BAPI-1121).
+ *
+ * WHY THIS EXISTS. `wait_for_ticket_review`'s generation-aware artifact gate
+ * (`ticket-review-artifact-gate.ts`) needs a write/removal outcome it can
+ * branch on — did the accepted clarify leg actually land on disk, did the
+ * withheld critique file actually get removed — without parsing a
+ * human-readable note string. The pre-existing `saveLocally` in `index.ts`
+ * returns exactly that kind of note, and every existing artifact tool (the
+ * six single-artifact request/get tools, the BAPI-342 heavy-read saves, the
+ * combined ticket-review fan-out) depends on its exact rendered shape. This
+ * module extracts the underlying write mechanics into one place, so both the
+ * legacy byte-compatible `saveLocally` and the new structured primitives the
+ * gate uses share a single implementation rather than diverging.
+ *
+ * WHY A SEPARATE MODULE. `index.ts` is the file every other module is
+ * imported INTO; a helper defined there cannot be imported back into a module
+ * `index.ts` itself imports without an import cycle. This module has no
+ * dependency on `index.ts`, so `index.ts` imports `saveLocally` from here
+ * (BAPI-1121) instead of defining it locally, and the artifact gate imports
+ * the structured primitives directly.
+ */
+import { writeFile, mkdir, rename, unlink } from "fs/promises";
+import path from "path";
+import { randomUUID } from "node:crypto";
+/**
+ * Write `content` to `dir/filename` via per-file temporary staging followed by
+ * an atomic rename, so a concurrent reader can never observe a partially
+ * written file and a failed write never leaves a corrupt final artifact.
+ *
+ * The staging filename includes a random suffix so concurrent writes to the
+ * same final filename (unusual, but not prevented at this layer) cannot stage
+ * onto the same temporary path.
+ *
+ * Throws on failure — this is the shared low-level primitive both
+ * {@link saveLocally} (byte-compatible legacy notes) and
+ * {@link writeCanonicalArtifact} (sanitized structured outcome) wrap
+ * differently, because they render a failure to their callers in two
+ * deliberately different shapes.
+ */
+async function writeFileAtomic(dir, filename, content) {
+    const finalPath = path.join(dir, filename);
+    const stagingPath = path.join(dir, `.${filename}.${randomUUID()}.tmp`);
+    await mkdir(dir, { recursive: true });
+    try {
+        await writeFile(stagingPath, content, "utf-8");
+        await rename(stagingPath, finalPath);
+    }
+    catch (err) {
+        // Best-effort cleanup of an orphaned staging file. Cleanup failure (or the
+        // staging file never having been created) does not change the outcome
+        // that matters: the original write/rename error propagates below.
+        try {
+            await unlink(stagingPath);
+        }
+        catch {
+            // Nothing to clean up, or cleanup itself failed — either way the
+            // original error is what the caller needs to see.
+        }
+        throw err;
+    }
+    return finalPath;
+}
+/**
+ * Byte-compatible replacement for the pre-BAPI-1121 `saveLocally` in
+ * `index.ts`. Preserves the exact call shape (`dir`, `filename`, `content` ->
+ * a rendered note string) and the exact rendered success/failure notes every
+ * existing artifact-tool caller depends on — including the raw error suffix
+ * on failure, which existing tests assert verbatim. The only behavioral
+ * change is that the write is now staged-then-renamed rather than written
+ * in place, which is externally invisible on success and, on failure, means
+ * no partial file is ever left at `dir/filename` (an improvement, not a
+ * compatibility break).
+ */
+export async function saveLocally(dir, filename, content) {
+    try {
+        const finalPath = await writeFileAtomic(dir, filename, content);
+        return `\n\n---\nSaved to ${finalPath}`;
+    }
+    catch (writeErr) {
+        const filePath = path.join(dir, filename);
+        return `\n\n---\nNote: Failed to save file to ${filePath}: ${writeErr}`;
+    }
+}
+/**
+ * Structured canonical write for the generation-aware artifact gate. Returns
+ * `{ ok, path, message }` rather than throwing or requiring the caller to
+ * parse a note string. The public `message` is sanitized to the path and
+ * outcome only; any detailed local diagnostic (the underlying filesystem
+ * error) goes only to `console.error`, never through MCP.
+ */
+export async function writeCanonicalArtifact(dir, filename, content) {
+    const finalPath = path.join(dir, filename);
+    try {
+        await writeFileAtomic(dir, filename, content);
+        return { ok: true, path: finalPath, message: `Saved to ${finalPath}` };
+    }
+    catch (err) {
+        console.error(`[local-artifact-storage] write failed for ${finalPath}:`, err);
+        return { ok: false, path: finalPath, message: `Failed to save file to ${finalPath}` };
+    }
+}
+/**
+ * Remove the exact canonical path for a withheld or stale artifact.
+ *
+ * Idempotent by design: an already-absent target (`ENOENT`) is reported as a
+ * SUCCESSFUL cleanup outcome, not an error — a retried removal, or a removal
+ * that runs after an earlier successful one, must never report failure. Only
+ * an actual removal failure (permissions, a directory at that path, etc.) is
+ * reported as `ok: false`.
+ *
+ * Removes exactly the given path — no globbing, no directory recursion, no
+ * inference of sibling files to clean up. The caller is responsible for
+ * passing the exact canonical target; this primitive never widens the blast
+ * radius of a removal on its own.
+ */
+export async function removeCanonicalArtifact(targetPath) {
+    try {
+        await unlink(targetPath);
+        return { ok: true, path: targetPath, message: `Removed ${targetPath}` };
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT") {
+            return { ok: true, path: targetPath, message: `${targetPath} was already absent` };
+        }
+        console.error(`[local-artifact-storage] removal failed for ${targetPath}:`, err);
+        return { ok: false, path: targetPath, message: `Failed to remove ${targetPath}` };
+    }
+}