settld 0.1.1 → 0.1.5

package/scripts/ci/run-mcp-host-smoke.mjs

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import crypto from "node:crypto";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { rm, mkdtemp, mkdir, writeFile } from "node:fs/promises";
+
+function randomId(prefix) {
+  return `${prefix}_${crypto.randomBytes(6).toString("hex")}`;
+}
+
+function pickPort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      const port = addr && typeof addr === "object" ? addr.port : null;
+      server.close(() => {
+        if (!Number.isInteger(port) || port <= 0) {
+          reject(new Error("failed to allocate loopback port"));
+          return;
+        }
+        resolve(port);
+      });
+    });
+    server.on("error", reject);
+  });
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitFor(label, fn, { timeoutMs = 30_000, intervalMs = 250 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  let lastErr = null;
+  while (Date.now() < deadline) {
+    try {
+      const ok = await fn();
+      if (ok) return;
+    } catch (err) {
+      lastErr = err;
+    }
+    await sleep(intervalMs);
+  }
+  if (lastErr) {
+    const wrapped = new Error(`${label} timed out: ${lastErr.message}`);
+    wrapped.cause = lastErr;
+    throw wrapped;
+  }
+  throw new Error(`${label} timed out`);
+}
+
+function startNodeProc({ name, scriptPath, env }) {
+  const logs = [];
+  const child = spawn(process.execPath, [scriptPath], {
+    env: { ...process.env, ...(env ?? {}) },
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+  const push = (line) => {
+    if (!line) return;
+    logs.push(line);
+    if (logs.length > 240) logs.shift();
+  };
+  child.stdout.on("data", (chunk) => {
+    for (const line of String(chunk).split(/\r?\n/)) push(`[${name}:stdout] ${line}`);
+  });
+  child.stderr.on("data", (chunk) => {
+    for (const line of String(chunk).split(/\r?\n/)) push(`[${name}:stderr] ${line}`);
+  });
+  return { child, logs };
+}
+
+async function stopProc(child) {
+  if (!child || typeof child.kill !== "function") return;
+  if (child.exitCode !== null && child.exitCode !== undefined) return;
+  try {
+    child.kill("SIGTERM");
+  } catch {
+    return;
+  }
+  const exited = await Promise.race([
+    new Promise((resolve) => child.once("exit", () => resolve(true))),
+    sleep(3000).then(() => false)
+  ]);
+  if (!exited) {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+      // ignore
+    }
+  }
+}
+
+async function requestJson({ baseUrl, method, route, headers = {}, body = undefined }) {
+  const response = await fetch(`${baseUrl}${route}`, {
+    method,
+    headers: {
+      ...headers,
+      ...(body === undefined ? {} : { "content-type": "application/json" })
+    },
+    body: body === undefined ? undefined : JSON.stringify(body)
+  });
+  const raw = await response.text();
+  let json = null;
+  try {
+    json = raw ? JSON.parse(raw) : null;
+  } catch {
+    json = null;
+  }
+  if (!response.ok) {
+    const details = json && typeof json === "object" ? json : raw;
+    const err = new Error(`HTTP ${response.status} ${method} ${route}`);
+    err.details = details;
+    throw err;
+  }
+  return json;
+}
+
+function runNodeScript(scriptPath, args, { env = process.env } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [scriptPath, ...(args ?? [])], {
+      env,
+      stdio: "inherit"
+    });
+    child.on("error", reject);
+    child.on("exit", (code, signal) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${path.basename(scriptPath)} failed (code=${code ?? "null"} signal=${signal ?? "null"})`));
+    });
+  });
+}
+
+async function main() {
+  const reportPath = path.resolve(process.cwd(), process.env.MCP_HOST_SMOKE_REPORT_PATH || "artifacts/ops/mcp-host-smoke.json");
+  const opsToken = randomId("ops");
+  const magicLinkApiKey = randomId("ml_admin");
+  const tenantId = randomId("tenant");
+
+  const apiPort = await pickPort();
+  const magicLinkPort = await pickPort();
+  const baseApiUrl = `http://127.0.0.1:${apiPort}`;
+  const baseMagicLinkUrl = `http://127.0.0.1:${magicLinkPort}`;
+  const dataDir = await mkdtemp(path.join(os.tmpdir(), "settld-ci-mcp-host-smoke-"));
+
+  const api = startNodeProc({
+    name: "api",
+    scriptPath: "src/api/server.js",
+    env: {
+      PORT: String(apiPort),
+      PROXY_BIND_HOST: "127.0.0.1",
+      PROXY_OPS_TOKEN: opsToken,
+      PROXY_AUTOTICK_INTERVAL_MS: "200"
+    }
+  });
+
+  const magicLink = startNodeProc({
+    name: "magic-link",
+    scriptPath: "services/magic-link/src/server.js",
+    env: {
+      MAGIC_LINK_HOST: "127.0.0.1",
+      MAGIC_LINK_PORT: String(magicLinkPort),
+      MAGIC_LINK_API_KEY: magicLinkApiKey,
+      MAGIC_LINK_DATA_DIR: dataDir,
+      MAGIC_LINK_ARCHIVE_EXPORT_ENABLED: "0",
+      MAGIC_LINK_SETTLD_API_BASE_URL: baseApiUrl,
+      MAGIC_LINK_SETTLD_OPS_TOKEN: opsToken
+    }
+  });
+
+  const report = {
+    schemaVersion: "McpHostSmokeReport.v1",
+    generatedAt: new Date().toISOString(),
+    ok: false,
+    tenantId,
+    apiBaseUrl: baseApiUrl,
+    magicLinkBaseUrl: baseMagicLinkUrl,
+    checks: [],
+    error: null
+  };
+
+  try {
+    await waitFor("api /healthz", async () => {
+      if (api.child.exitCode !== null) throw new Error(`api exited early (${api.child.exitCode})`);
+      const res = await fetch(`${baseApiUrl}/healthz`).catch(() => null);
+      return Boolean(res && res.ok);
+    });
+    report.checks.push({ id: "api_healthz", ok: true });
+
+    await waitFor("magic-link /health", async () => {
+      if (magicLink.child.exitCode !== null) throw new Error(`magic-link exited early (${magicLink.child.exitCode})`);
+      const res = await fetch(`${baseMagicLinkUrl}/health`).catch(() => null);
+      return Boolean(res && res.ok);
+    });
+    report.checks.push({ id: "magic_link_health", ok: true });
+
+    await requestJson({
+      baseUrl: baseMagicLinkUrl,
+      method: "POST",
+      route: "/v1/tenants",
+      headers: { "x-api-key": magicLinkApiKey },
+      body: {
+        tenantId,
+        name: "CI MCP Host Smoke Tenant",
+        contactEmail: "ci@settld.work",
+        billingEmail: "ci-billing@settld.work"
+      }
+    });
+
+    const runtimeBootstrap = await requestJson({
+      baseUrl: baseMagicLinkUrl,
+      method: "POST",
+      route: `/v1/tenants/${encodeURIComponent(tenantId)}/onboarding/runtime-bootstrap`,
+      headers: { "x-api-key": magicLinkApiKey },
+      body: {}
+    });
+
+    const mcpEnv = runtimeBootstrap?.mcp?.env ?? null;
+    if (!mcpEnv || typeof mcpEnv !== "object") {
+      throw new Error("runtime bootstrap did not return mcp.env");
+    }
+    if (typeof mcpEnv.SETTLD_API_KEY !== "string" || !mcpEnv.SETTLD_API_KEY.trim()) {
+      throw new Error("runtime bootstrap did not return SETTLD_API_KEY");
+    }
+    report.checks.push({ id: "runtime_bootstrap", ok: true });
+
+    await requestJson({
+      baseUrl: baseMagicLinkUrl,
+      method: "POST",
+      route: `/v1/tenants/${encodeURIComponent(tenantId)}/onboarding/runtime-bootstrap/smoke-test`,
+      headers: { "x-api-key": magicLinkApiKey },
+      body: { env: mcpEnv }
+    });
+    report.checks.push({ id: "runtime_smoke_test", ok: true });
+
+    // verify initialize/tools list + tool invocation from an MCP host perspective
+    await runNodeScript("scripts/mcp/probe.mjs", ["--call", "settld.about", "{}"], {
+      env: { ...process.env, ...mcpEnv, MCP_PROBE_TIMEOUT_MS: "30000" }
+    });
+    report.checks.push({ id: "mcp_initialize_tools_list", ok: true });
+    report.checks.push({ id: "mcp_tool_call_settld_about", ok: true });
+
+    report.ok = true;
+
+    process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+  } catch (err) {
+    report.ok = false;
+    report.error = {
+      message: err?.message ?? String(err),
+      details: err?.details ?? null
+    };
+    const apiLogs = api.logs.join("\n");
+    const magicLogs = magicLink.logs.join("\n");
+    const details = err?.details ? `\nDetails: ${JSON.stringify(err.details)}` : "";
+    process.stderr.write(
+      `${err?.stack ?? err?.message ?? String(err)}${details}\n--- api logs ---\n${apiLogs}\n--- magic-link logs ---\n${magicLogs}\n`
+    );
+    process.exitCode = 1;
+  } finally {
+    await mkdir(path.dirname(reportPath), { recursive: true });
+    await writeFile(reportPath, JSON.stringify(report, null, 2) + "\n", "utf8");
+    process.stdout.write(`wrote mcp host smoke report: ${reportPath}\n`);
+    await stopProc(magicLink.child);
+    await stopProc(api.child);
+    await rm(dataDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err?.stack ?? err?.message ?? String(err)}\n`);
+  process.exit(1);
+});

package/scripts/ci/run-self-serve-launch-gate.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { loadSelfServeLaunchTrackerFromPath } from "./lib/self-serve-launch-gate.mjs";
+
+async function main() {
+  const trackerPath = resolve(
+    process.cwd(),
+    process.env.SELF_SERVE_LAUNCH_TRACKER_PATH || "planning/launch/self-serve-launch-tracker.json"
+  );
+  const reportPath = resolve(
+    process.cwd(),
+    process.env.SELF_SERVE_LAUNCH_GATE_REPORT_PATH || "artifacts/gates/self-serve-launch-gate.json"
+  );
+  await mkdir(dirname(reportPath), { recursive: true });
+
+  let evaluation = null;
+  let trackerOk = false;
+  try {
+    evaluation = await loadSelfServeLaunchTrackerFromPath(trackerPath);
+    trackerOk = evaluation.ok === true;
+  } catch (err) {
+    evaluation = {
+      ok: false,
+      error: err?.message ?? "unable to load self-serve launch tracker"
+    };
+    trackerOk = false;
+  }
+
+  const report = {
+    schemaVersion: "SelfServeLaunchGateReport.v1",
+    generatedAt: new Date().toISOString(),
+    checks: [
+      {
+        id: "self_serve_kpi_thresholds",
+        ok: trackerOk,
+        trackerPath,
+        summary: evaluation
+      }
+    ],
+    verdict: {
+      ok: trackerOk,
+      requiredChecks: 1,
+      passedChecks: trackerOk ? 1 : 0
+    }
+  };
+
+  await writeFile(reportPath, JSON.stringify(report, null, 2) + "\n", "utf8");
+  process.stdout.write(`wrote self-serve launch gate report: ${reportPath}\n`);
+  if (!trackerOk) process.exitCode = 1;
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err?.stack || err?.message || String(err)}\n`);
+  process.exit(1);
+});

package/scripts/ci/runtime-import-smoke.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const REQUIRED_MODULES = Object.freeze([
+  "src/api/app.js",
+  "src/core/settlement-kernel.js",
+  "src/core/settlement-verifier.js",
+  "src/db/store-pg.js"
+]);
+
+function toAbsolute(modulePath) {
+  return path.resolve(process.cwd(), modulePath);
+}
+
+function assertFileReadable(modulePath) {
+  const absolute = toAbsolute(modulePath);
+  try {
+    fs.accessSync(absolute, fs.constants.R_OK);
+  } catch (err) {
+    const wrapped = new Error(`missing or unreadable module: ${modulePath}`);
+    wrapped.cause = err;
+    throw wrapped;
+  }
+  return absolute;
+}
+
+async function importModule(absolutePath) {
+  const moduleUrl = pathToFileURL(absolutePath).toString();
+  await import(moduleUrl);
+}
+
+async function main() {
+  const imported = [];
+  for (const modulePath of REQUIRED_MODULES) {
+    const absolutePath = assertFileReadable(modulePath);
+    await importModule(absolutePath);
+    imported.push(modulePath);
+  }
+  process.stdout.write(
+    JSON.stringify(
+      {
+        ok: true,
+        checkedAt: new Date().toISOString(),
+        imported
+      },
+      null,
+      2
+    ) + "\n"
+  );
+}
+
+main().catch((err) => {
+  const message = err?.stack ?? err?.message ?? String(err);
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+});

package/scripts/ci/update-lighthouse-tracker.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { evaluateLighthouseTracker } from "./lib/lighthouse-tracker.mjs";
+
+const ALLOWED_STATUSES = new Set([
+  "targeting",
+  "contracting",
+  "integration_in_progress",
+  "go_live_scheduled",
+  "paid_production_settlement_confirmed",
+  "production_active"
+]);
+
+function parseArgs(argv) {
+  const flags = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) continue;
+    const key = token.slice(2);
+    const next = argv[index + 1];
+    if (next && !next.startsWith("--")) {
+      flags[key] = next;
+      index += 1;
+      continue;
+    }
+    flags[key] = "true";
+  }
+  return flags;
+}
+
+function normalizeNonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+
+function normalizeNullableString(value) {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  const text = String(value).trim();
+  if (text === "" || text.toLowerCase() === "null") return null;
+  return text;
+}
+
+function assertIsoOrNull(name, value) {
+  if (value === undefined || value === null) return;
+  if (!Number.isFinite(Date.parse(value))) {
+    throw new Error(`${name} must be a valid ISO timestamp`);
+  }
+}
+
+async function main() {
+  const flags = parseArgs(process.argv.slice(2));
+  const trackerPath = resolve(process.cwd(), flags.path || "planning/launch/lighthouse-production-tracker.json");
+  const accountId = normalizeNonEmptyString(flags.account);
+  const status = normalizeNullableString(flags.status);
+  if (!accountId) throw new Error("--account is required");
+  if (!status || !ALLOWED_STATUSES.has(status)) {
+    throw new Error(`--status is required and must be one of: ${Array.from(ALLOWED_STATUSES).join(", ")}`);
+  }
+
+  const raw = await readFile(trackerPath, "utf8");
+  const tracker = JSON.parse(raw);
+  if (!Array.isArray(tracker?.accounts)) throw new Error("tracker.accounts must be an array");
+  const row = tracker.accounts.find((item) => String(item?.accountId ?? "") === accountId);
+  if (!row) throw new Error(`account not found: ${accountId}`);
+
+  row.status = status;
+
+  const companyName = normalizeNullableString(flags["company-name"]);
+  const owner = normalizeNullableString(flags.owner);
+  const signedAt = normalizeNullableString(flags["signed-at"]);
+  const goLiveAt = normalizeNullableString(flags["go-live-at"]);
+  const settlementRef = normalizeNullableString(flags["settlement-ref"]);
+  const notes = normalizeNullableString(flags.notes);
+
+  assertIsoOrNull("signed-at", signedAt);
+  assertIsoOrNull("go-live-at", goLiveAt);
+
+  if (companyName !== undefined) row.companyName = companyName ?? "";
+  if (owner !== undefined) row.owner = owner ?? "";
+  if (signedAt !== undefined) row.signedAt = signedAt;
+  if (goLiveAt !== undefined) row.goLiveAt = goLiveAt;
+  if (settlementRef !== undefined) row.productionSettlementRef = settlementRef;
+  if (notes !== undefined) row.notes = notes ?? "";
+
+  tracker.updatedAt = new Date().toISOString();
+  const evaluation = evaluateLighthouseTracker(tracker);
+
+  await writeFile(trackerPath, JSON.stringify(tracker, null, 2) + "\n", "utf8");
+  process.stdout.write(
+    JSON.stringify(
+      {
+        ok: true,
+        trackerPath,
+        accountId,
+        status,
+        trackerSummary: {
+          readyAccounts: evaluation.activeAccounts,
+          requiredActiveAccounts: evaluation.requiredActiveAccounts,
+          trackerOk: evaluation.ok
+        }
+      },
+      null,
+      2
+    ) + "\n"
+  );
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err?.stack || err?.message || String(err)}\n`);
+  process.exit(1);
+});