constructor-research-mcp 0.0.0-stage → 0.3.0

package/dist/wait.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+/**
+ * Blocks until deployments finish, for agents that have nothing else to do and for
+ * client hooks that wake an agent. It watches the checkpoints the MCP writes; if no
+ * process has advanced a deployment for a minute (the MCP was closed), it continues
+ * the deployment itself.
+ */
+import { setTimeout as delay } from "node:timers/promises";
+import { readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { configFromEnv, sessionFile } from "./config.js";
+import { PlatformApi } from "./api.js";
+import { StateStore } from "./store.js";
+import { DeploymentEngine, terminal } from "./deployment.js";
+import { DeploymentRuntime, paused } from "./runtime.js";
+import { FileManager } from "./files.js";
+import { LogFollower } from "./logs.js";
+const ok = new Set(["started", "stopped", "built"]);
+const ID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+export const EXIT = {
+    done: 0,
+    error: 1,
+    attention: 2,
+    running: 3,
+    nothing: 4,
+};
+const final = (status) => terminal.has(status) || paused.has(status);
+/** Deployments still in progress that were touched in the last two hours. */
+export async function active(store) {
+    const since = Date.now() - 2 * 60 * 60 * 1000;
+    const ids = [];
+    for (const id of await store.ids()) {
+        try {
+            const op = await store.load(id);
+            if (op &&
+                !final(op.status) &&
+                Math.max(Date.parse(op.updated_at), await store.lastBeat(id)) > since)
+                ids.push(id);
+        }
+        catch {
+            /* Foreign or corrupt checkpoints are not ours to wait for. */
+        }
+    }
+    return ids;
+}
+export async function waitFor(runtime, ids, { maxMs, staleMs = 60000, pollMs = 5000 }) {
+    const store = runtime.engine.store;
+    const deadline = Date.now() + maxMs;
+    const pending = new Set(ids);
+    const results = [];
+    for (;;) {
+        for (const id of [...pending]) {
+            const op = await store.load(id);
+            if (!op) {
+                results.push({
+                    deployment_id: id,
+                    status: "not_found",
+                    message: "No such deployment in the local state.",
+                });
+                pending.delete(id);
+            }
+            else if (final(op.status)) {
+                results.push(await runtime.get({ deployment_id: id }));
+                pending.delete(id);
+            }
+            else if (Date.now() -
+                Math.max(Date.parse(op.updated_at), await store.lastBeat(id)) >
+                staleMs)
+                await runtime.get({ deployment_id: id, resume: true, wait_seconds: 0 });
+        }
+        if (!pending.size || Date.now() >= deadline)
+            break;
+        await delay(Math.min(pollMs, Math.max(0, deadline - Date.now())));
+    }
+    const running = [...pending];
+    return {
+        results,
+        running,
+        code: results.some((r) => !ok.has(r.status))
+            ? EXIT.attention
+            : running.length
+                ? EXIT.running
+                : EXIT.done,
+    };
+}
+/** One line per deployment, for an agent to read. */
+export function summary({ results, running }) {
+    const lines = results.map((r) => {
+        const services = (r.services ?? [])
+            .map((s) => `${s.name} ${s.status ?? ""}${s.public_url ? ` ${s.public_url}` : ""}`.trim())
+            .join(", ");
+        return [
+            `Deployment ${r.deployment_id}: ${r.status}.`,
+            r.message,
+            services && `Services: ${services}.`,
+            r.next_action && `Next: ${r.next_action}`,
+        ]
+            .filter(Boolean)
+            .join(" ");
+    });
+    for (const id of running)
+        lines.push(`Deployment ${id}: still in progress. Run the wait command again to keep waiting.`);
+    return lines.join("\n");
+}
+async function stdin() {
+    if (process.stdin.isTTY)
+        return "";
+    let text = "";
+    for await (const chunk of process.stdin)
+        text += chunk;
+    return text;
+}
+/** Only one hook waiter per deployment, so the agent is woken once. */
+async function claim(dir, id) {
+    const file = join(dir, `${id}.waiter`);
+    try {
+        await writeFile(file, String(process.pid), { flag: "wx", mode: 0o600 });
+    }
+    catch {
+        try {
+            process.kill(Number(await readFile(file, "utf8")), 0);
+            return undefined;
+        }
+        catch {
+            await writeFile(file, String(process.pid), { mode: 0o600 });
+        }
+    }
+    return () => unlink(file).catch(() => { });
+}
+const USAGE = `Usage: constructor-research-wait [deployment_id ...] [--max-minutes N] [--hook claude-code|codex|opencode]
+
+Waits until the deployments finish (all in-progress ones when no ID is given) and prints one line each.
+Exit codes: 0 finished, 2 needs the user (failed, token, upload, confirmation), 3 still running at the
+time limit, 4 nothing to wait for, 1 usage error.
+
+--hook claude-code  PostToolUse hook with asyncRewake: waits for the deployment in the tool result and
+                    wakes Claude with the outcome (exit 2). opencode: the same, for the plugin.
+--hook codex        Stop hook: waits for in-progress deployments, then continues the turn with the outcome.`;
+async function main(argv) {
+    const ids = [];
+    let hook;
+    let minutes;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--hook")
+            hook = argv[++i];
+        else if (a === "--max-minutes")
+            minutes = Number(argv[++i]);
+        else if (a === "-h" || a === "--help") {
+            console.log(USAGE);
+            return EXIT.done;
+        }
+        else if (/^[0-9a-f-]{36}$/i.test(a))
+            ids.push(a);
+        else {
+            console.error(USAGE);
+            return EXIT.error;
+        }
+    }
+    if ((hook && !["claude-code", "codex", "opencode"].includes(hook)) ||
+        (minutes !== undefined && !(minutes > 0))) {
+        console.error(USAGE);
+        return EXIT.error;
+    }
+    const config = configFromEnv();
+    // A hook runs for one harness: use that harness's session.
+    if (hook && !config.cookieFileFixed)
+        config.cookieFile = sessionFile(hook);
+    const api = new PlatformApi(config);
+    await api.followSession();
+    const store = new StateStore(config);
+    const engine = new DeploymentEngine(api, store);
+    engine.files = new FileManager(api, engine);
+    engine.logs = new LogFollower(api);
+    const runtime = new DeploymentRuntime(engine);
+    const release = [];
+    try {
+        const toolHook = hook === "claude-code" || hook === "opencode";
+        if (toolHook) {
+            // Only deployments still running when the tool returned; a finished one was already reported.
+            for (const id of new Set((await stdin()).match(ID) ?? [])) {
+                const op = await store.load(id).catch(() => undefined);
+                const free = op && !final(op.status) && (await claim(config.stateDir, id));
+                if (free) {
+                    ids.push(id);
+                    release.push(free);
+                }
+            }
+            if (!ids.length)
+                return EXIT.done;
+        }
+        else if (hook === "codex")
+            await stdin();
+        // Deployments found by scanning may belong to other sessions: watch them, never drive them.
+        const named = ids.length > 0;
+        if (!named)
+            ids.push(...(await active(store)));
+        if (!ids.length) {
+            if (!hook)
+                console.log("No deployment is in progress.");
+            return hook ? EXIT.done : EXIT.nothing;
+        }
+        // Codex stops a hook after its timeout (600 s by default); stay under it.
+        const maxMs = (minutes ?? (hook === "codex" ? 9 : 60)) * 60000;
+        const result = await waitFor(runtime, ids, {
+            maxMs,
+            staleMs: named ? undefined : Infinity,
+        });
+        const text = summary(result);
+        if (toolHook) {
+            console.error(text);
+            return EXIT.attention;
+        }
+        if (hook === "codex") {
+            console.log(JSON.stringify({ decision: "block", reason: text }));
+            return EXIT.done;
+        }
+        console.log(text);
+        return result.code;
+    }
+    finally {
+        await runtime.close();
+        await engine.logs.close();
+        await Promise.all(release.map((f) => f()));
+    }
+}
+const invoked = (() => {
+    try {
+        return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+})();
+if (invoked)
+    main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(EXIT.error);
+    });

package/examples/claude-hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "mcp__constructor-research__(deploy_app|update_app|build_image|start_app|stop_app|get_deployment)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx -y -p constructor-research-mcp constructor-research-wait --hook claude-code",
+            "asyncRewake": true
+          }
+        ]
+      }
+    ]
+  }
+}

package/examples/claude.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "constructor-research": {
+      "command": "npx",
+      "args": ["-y", "constructor-research-mcp@latest"]
+    }
+  }
+}

package/examples/codex-hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx -y -p constructor-research-mcp constructor-research-wait --hook codex",
+            "timeout": 600,
+            "statusMessage": "Waiting for Constructor deployments"
+          }
+        ]
+      }
+    ]
+  }
+}

package/examples/codex.toml

@@ -0,0 +1,6 @@
+[mcp_servers.constructor-research]
+command = "npx"
+args = ["-y", "constructor-research-mcp@latest"]
+# The first start downloads the package.
+startup_timeout_sec = 60
+tool_timeout_sec = 30

package/examples/deploy-app.json

@@ -0,0 +1,39 @@
+{
+  "project_id": "PROJECT_ID",
+  "application_name": "task-tracker",
+  "files_uploaded": true,
+  "services": [
+    {
+      "name": "backend",
+      "build": {
+        "desk_id": "DISK_ID",
+        "dockerfile": "/backend/Dockerfile"
+      },
+      "ports": [
+        {
+          "number": 3000,
+          "expose_to_internet": true
+        }
+      ]
+    },
+    {
+      "name": "frontend",
+      "build": {
+        "desk_id": "DISK_ID",
+        "dockerfile": "/frontend/Dockerfile"
+      },
+      "ports": [
+        {
+          "number": 5000,
+          "expose_to_internet": true
+        }
+      ],
+      "environment_variables": {
+        "BACKEND_URL": {
+          "service": "backend",
+          "exposure": "public"
+        }
+      }
+    }
+  ]
+}

package/examples/opencode-plugin.js

@@ -0,0 +1,43 @@
+// Wakes the OpenCode agent when a Constructor deployment it started finishes.
+// Copy to .opencode/plugins/ or ~/.config/opencode/plugins/.
+import { spawn } from "node:child_process";
+
+const WAIT = [
+  "-y",
+  "-p",
+  "constructor-research-mcp",
+  "constructor-research-wait",
+];
+// Any CONSTRUCTOR_* settings your MCP entry sets besides the defaults.
+const ENV = {};
+const TOOLS =
+  /(deploy_app|update_app|build_image|start_app|stop_app|get_deployment)$/;
+
+export const ConstructorDeployWait = async ({ client }) => ({
+  "tool.execute.after": async (input, output) => {
+    if (!TOOLS.test(input.tool)) return;
+    const child = spawn("npx", [...WAIT, "--hook", "opencode"], {
+      env: { ...process.env, ...ENV },
+      shell: process.platform === "win32", // npx is npx.cmd there
+      stdio: ["pipe", "ignore", "pipe"],
+    });
+    let text = "";
+    child.stderr.on("data", (chunk) => (text += chunk));
+    child.stdin.end(JSON.stringify({ tool_response: output.output ?? "" }));
+    child.on("close", async (code) => {
+      // Exit 2 carries the outcome; 0 means nothing was in progress (or another waiter has it).
+      if (code !== 2 || !text.trim()) return;
+      await client.session.prompt({
+        path: { id: input.sessionID },
+        body: {
+          parts: [
+            {
+              type: "text",
+              text: `Constructor deployment update:\n${text.trim()}`,
+            },
+          ],
+        },
+      });
+    });
+  },
+});

package/examples/opencode-v2.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "servers": {
+      "constructor-research": {
+        "type": "local",
+        "command": ["npx", "-y", "constructor-research-mcp@latest"]
+      }
+    }
+  }
+}

package/examples/opencode.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "constructor-research": {
+      "type": "local",
+      "command": ["npx", "-y", "constructor-research-mcp@latest"]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "constructor-research-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "type": "module",
+  "description": "Local deployment MCP for Constructor Research",
+  "license": "MIT",
+  "author": "Constructor Tech",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NRGGIT/constructor-research-mcp.git"
+  },
+  "homepage": "https://github.com/NRGGIT/constructor-research-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/NRGGIT/constructor-research-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "constructor",
+    "claude-code",
+    "codex",
+    "opencode"
+  ],
+  "bin": {
+    "constructor-research-mcp": "dist/server.js",
+    "constructor-research-wait": "dist/wait.js",
+    "constructor-research-login": "dist/login.js",
+    "constructor-research-set-token": "dist/set-token.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "INSTALL.md",
+    "examples"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/server.js",
+    "test": "tsx --test test/*.test.ts",
+    "check": "tsc --noEmit",
+    "pretest": "npm run build",
+    "format": "prettier --write src test examples README.md INSTALL.md",
+    "format:check": "prettier --check src test examples README.md INSTALL.md",
+    "set-token": "node dist/set-token.js",
+    "wait": "node dist/wait.js",
+    "login": "node dist/login.js",
+    "prepublishOnly": "npm run check && npm run format:check && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.5",
+    "prettier": "3.9.10",
+    "tsx": "4.23.15",
+    "typescript": "7.0.2"
+  }
+}