@domino-sdk/relay-cli 0.1.0

package/cli/connection.mjs

@@ -0,0 +1,114 @@
+import {
+  mkdir,
+  readFile,
+  writeFile,
+  chmod,
+  rename,
+  rm,
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+
+export function apiUrl(value) {
+  const url = new URL(value);
+  if (url.username || url.password || url.search || url.hash)
+    throw new Error(
+      "API URL must not contain credentials, a query, or a fragment.",
+    );
+  if (
+    url.protocol !== "https:" &&
+    !(
+      url.protocol === "http:" &&
+      ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)
+    )
+  )
+    throw new Error(
+      "Use HTTPS for remote APIs. HTTP is allowed only on loopback.",
+    );
+  return url.href.replace(/\/+$/, "");
+}
+
+const credentialsPath = () =>
+  join(
+    process.env.RELAY_CONFIG_DIR ?? join(homedir(), ".config", "domino"),
+    "credentials.json",
+  );
+async function credentials() {
+  try {
+    return JSON.parse(await readFile(credentialsPath(), "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw error;
+  }
+}
+export async function savedToken(url) {
+  return (await credentials())[url];
+}
+export async function saveToken(url, token) {
+  const values = await credentials();
+  if (token) values[url] = token;
+  else delete values[url];
+  const path = credentialsPath();
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, JSON.stringify(values) + "\n", {
+      mode: 0o600,
+      flag: "wx",
+    });
+    await chmod(temporary, 0o600);
+    await rename(temporary, path);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+
+export async function request(connection, path, method = "GET", body) {
+  // Keep the escape hatch inside management/v1, including after URL normalization.
+  const base = new URL(`${connection.apiUrl}/management/v1/`);
+  const url = new URL(`${connection.apiUrl}/management/v1${path}`);
+  if (
+    !path.startsWith("/") ||
+    path.startsWith("//") ||
+    url.origin !== base.origin ||
+    !url.pathname.startsWith(base.pathname) ||
+    /[\\#]/.test(path) ||
+    /%2e|%2f|%5c/i.test(path)
+  )
+    throw new Error(
+      "API path must stay within /management/v1, for example /quests.",
+    );
+  const token =
+    connection.token ??
+    process.env.RELAY_MANAGEMENT_TOKEN ??
+    (await savedToken(connection.apiUrl));
+  if (!token)
+    throw new Error(
+      "Not logged in. Run domino login, or set RELAY_MANAGEMENT_TOKEN for automation.",
+    );
+  const headers = new Headers({ Authorization: `Bearer ${token}` });
+  for (const key of ["organization", "project", "environment"]) {
+    if (connection[key]) headers.set(`X-Relay-${key}`, connection[key]);
+  }
+  if (body !== undefined) headers.set("Content-Type", "application/json");
+  const response = await fetch(url, {
+    method,
+    headers,
+    body: body === undefined ? undefined : JSON.stringify(body),
+    redirect: "error",
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (!response.ok) {
+    const result = await response.json().catch(() => null);
+    const error = new Error(
+      typeof result?.error === "string"
+        ? result.error
+        : `Request failed (${response.status})`,
+    );
+    error.status = response.status;
+    throw error;
+  }
+  if (response.status === 204) return null;
+  return response.json();
+}

package/cli/dev.mjs

@@ -0,0 +1,231 @@
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { createServer } from "node:http";
+import { watch } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { request } from "./connection.mjs";
+import { bundleProject, bundleCatalog, findProject } from "./project.mjs";
+
+async function listen(server, port = 0) {
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", resolve);
+  });
+  return server.address().port;
+}
+async function freePort() {
+  const server = createServer();
+  const port = await listen(server);
+  await new Promise((resolve) => server.close(resolve));
+  return port;
+}
+
+export async function dev(project, options) {
+  if (!project?.config.app)
+    throw new Error(
+      "Configure app scripts in relay.json before running domino dev.",
+    );
+  const root = dirname(project.path);
+  const require = createRequire(join(root, "package.json"));
+  const runtime = dirname(
+    require.resolve("@domino-sdk/relay-runtime/package.json"),
+  );
+  const wrangler = join(
+    dirname(require.resolve("wrangler/package.json")),
+    "bin/wrangler.js",
+  );
+  const apiPort = await freePort();
+  const appPort = Number(options.port ?? (await freePort()));
+  if (!Number.isInteger(appPort) || appPort < 1 || appPort > 65535)
+    throw new Error("Invalid app port.");
+  const origin = `http://127.0.0.1:${appPort}`;
+  const connection = {
+    apiUrl: `http://127.0.0.1:${apiPort}`,
+    organization: "local",
+    project: "campaign",
+    environment: "test",
+    token: randomBytes(32).toString("hex"),
+  };
+  const children = [];
+  let stopping = false;
+  let failure;
+  let watcher;
+  const control = createServer(async (req, res) => {
+    res.setHeader("Cache-Control", "no-store");
+    if (
+      req.method !== "POST" ||
+      req.url !== "/__domino/member" ||
+      req.headers.origin !== origin ||
+      req.headers["x-relay-csrf"] !== "1"
+    ) {
+      res.writeHead(403).end();
+      return;
+    }
+    req.resume();
+    try {
+      const response = await fetch(connection.apiUrl + "/v1/auth/exchange", {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${connection.token}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          organization: connection.organization,
+          project: connection.project,
+          environment: "test",
+          identity: { issuer: "local-preview", subject: "preview-member" },
+          role: "member",
+        }),
+      });
+      if (!response.ok) throw new Error("Local participant sign-in failed.");
+      const session = await response.json();
+      res.setHeader(
+        "Set-Cookie",
+        `relay_session=${session.token}; Path=/; HttpOnly; SameSite=Strict`,
+      );
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify({ signedIn: true }));
+    } catch {
+      res.writeHead(503).end();
+    }
+  });
+  const stop = () => {
+    stopping = true;
+    watcher?.close();
+    control.close();
+    for (const child of children) {
+      if (!child.pid) continue;
+      try {
+        if (process.platform === "win32") child.kill("SIGTERM");
+        else process.kill(-child.pid, "SIGTERM");
+      } catch (error) {
+        if (error.code !== "ESRCH") throw error;
+      }
+    }
+  };
+  const start = (command, args, extraEnv = {}) => {
+    const child = spawn(command, args, {
+      cwd: root,
+      env: { ...process.env, ...extraEnv },
+      stdio: "inherit",
+      detached: process.platform !== "win32",
+    });
+    children.push(child);
+    child.on("error", (error) => {
+      failure = error;
+      stop();
+    });
+    child.on("exit", (code) => {
+      if (!stopping) {
+        failure = new Error(`Development process exited (${code}).`);
+        stop();
+      }
+    });
+    return child;
+  };
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+  try {
+    const controlPort = await listen(control);
+    const vars = {
+      LOCAL_DEVELOPMENT: "true",
+      TEST_HOOKS: "false",
+      API_TOKEN: connection.token,
+      AUTH_ORGANIZATION: connection.organization,
+      AUTH_PROJECT: connection.project,
+      AUTH_ENVIRONMENT: "test",
+      AUTH_ORIGINS: origin,
+    };
+    start(
+      process.execPath,
+      [
+        wrangler,
+        "dev",
+        "--local",
+        "--ip",
+        "127.0.0.1",
+        "--port",
+        String(apiPort),
+        "--config",
+        join(runtime, "wrangler.jsonc"),
+        "--persist-to",
+        join(root, ".wrangler/domino"),
+        ...Object.entries(vars).flatMap(([key, value]) => [
+          "--var",
+          `${key}:${value}`,
+        ]),
+      ],
+      { WRANGLER_SEND_METRICS: "false" },
+    );
+    let ready = false;
+    for (let attempt = 0; attempt < 150 && !stopping; attempt++) {
+      try {
+        ready = (await fetch(connection.apiUrl + "/v1/auth/session")).ok;
+      } catch {
+        /* Runtime is starting. */
+      }
+      if (ready) break;
+      await delay(200);
+    }
+    if (!ready) throw failure ?? new Error("Local Relay did not start.");
+    await request(connection, "/projects", "POST", {
+      project: connection.project,
+      name: "Local campaign",
+    });
+    async function sync() {
+      const current = await findProject(project.path);
+      if (current.config.quests.length)
+        await request(
+          connection,
+          "/releases/batch",
+          "POST",
+          await bundleProject(current),
+        );
+      const catalog = await request(connection, "/catalog");
+      await request(connection, "/catalog/deploy", "POST", {
+        ...(await bundleCatalog(current)),
+        expectedRevision: catalog.revision,
+      });
+    }
+    await sync();
+    let dirty = false;
+    watcher = watch(root, { recursive: true }, (_, name) => {
+      if (
+        name &&
+        !/(^|[/\\])(node_modules|dist|\.git|\.domino|\.domino-build|\.wrangler)([/\\]|$)/.test(
+          name,
+        ) &&
+        /\.(ts|tsx|mjs|json)$/.test(name)
+      )
+        dirty = true;
+    });
+    start("pnpm", ["run", project.config.app.devScript], {
+      DOMINO_LOCAL_API: connection.apiUrl,
+      DOMINO_DEV_CONTROL: `http://127.0.0.1:${controlPort}`,
+      DOMINO_APP_PORT: String(appPort),
+    });
+    console.error(
+      `Local campaign: ${origin}\nPreview data stays in .wrangler/domino. Source changes update local quests.`,
+    );
+    while (!stopping) {
+      await delay(300);
+      if (dirty) {
+        dirty = false;
+        try {
+          await sync();
+          console.error("Local quests updated.");
+        } catch (error) {
+          console.error(`Local quest update failed: ${error.message}`);
+        }
+      }
+    }
+    if (failure) throw failure;
+    return { stopped: true };
+  } finally {
+    stop();
+    process.removeListener("SIGINT", stop);
+    process.removeListener("SIGTERM", stop);
+  }
+}

package/cli/device-login.mjs

@@ -0,0 +1,80 @@
+import { randomBytes, createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { saveToken } from "./connection.mjs";
+
+export function openBrowser(url) {
+  const [command, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["rundll32", ["url.dll,FileProtocolHandler", url]]
+        : ["xdg-open", [url]];
+  const child = spawn(command, args, { stdio: "ignore", detached: true });
+  child.on("error", () => {});
+  child.unref();
+}
+
+export async function browserLogin(connection, options) {
+  const verifier = randomBytes(32).toString("base64url");
+  async function post(path, input) {
+    const response = await fetch(`${connection.apiUrl}/cli/${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input),
+      redirect: "error",
+      signal: AbortSignal.timeout(30_000),
+    });
+    const value = await response.json();
+    if (!response.ok) throw new Error(value.error ?? "Browser sign-in failed");
+    return value;
+  }
+  const device = await post("device", {
+    challenge: createHash("sha256").update(verifier).digest("hex"),
+  });
+  if (
+    typeof device.verificationUrl !== "string" ||
+    typeof device.code !== "string" ||
+    typeof device.expiresAt !== "number"
+  )
+    throw new Error("Invalid sign-in response");
+  const url = new URL(device.verificationUrl);
+  if (
+    url.username ||
+    url.password ||
+    (url.protocol !== "https:" &&
+      !(
+        url.protocol === "http:" &&
+        ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)
+      ))
+  )
+    throw new Error("Unsafe sign-in URL");
+  process.stderr.write(
+    options.json
+      ? JSON.stringify({
+          event: "browser-login",
+          url: url.href,
+          code: device.code,
+        }) + "\n"
+      : `Open ${url.href}\nEnter code ${device.code} to connect this CLI.\n`,
+  );
+  if (!options.noBrowser) openBrowser(url.href);
+  while (Date.now() < device.expiresAt) {
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+    const result = await post("device/token", { id: device.id, verifier });
+    if (result.status === "pending") continue;
+    if (
+      result.status !== "approved" ||
+      typeof result.token !== "string" ||
+      !result.token.startsWith("dc_")
+    )
+      throw new Error("Invalid sign-in response");
+    await saveToken(connection.apiUrl, result.token);
+    return {
+      loggedIn: true,
+      apiUrl: connection.apiUrl,
+      organization: result.organization,
+      expiresAt: result.expiresAt,
+    };
+  }
+  throw new Error("Browser sign-in expired. Run domino login again.");
+}

package/cli/doctor.mjs

@@ -0,0 +1,156 @@
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { access } from "node:fs/promises";
+import { inspectAgentSkills } from "./agents.mjs";
+import { request } from "./connection.mjs";
+
+export async function diagnose({ project, connection, options }) {
+  const checks = [];
+  const root = project ? dirname(project.path) : process.cwd();
+  checks.push(
+    project
+      ? { id: "manifest", status: "ok", message: "Project manifest is valid." }
+      : {
+          id: "manifest",
+          status: "error",
+          message:
+            "No relay.json found. Use domino checkout for a hosted project, or domino init --project ID in an existing app.",
+        },
+  );
+
+  const agents = await inspectAgentSkills(root);
+  checks.push(
+    Object.values(agents).some((status) =>
+      ["installed", "modified"].includes(status),
+    )
+      ? {
+          id: "agent-skills",
+          status: "ok",
+          message:
+            "Project skill files are present. Agent discovery and customized instructions have not been verified.",
+        }
+      : {
+          id: "agent-skills",
+          status: "error",
+          message:
+            "Install project guidance with domino agents install. Rerunning restores missing files without replacing customized instructions.",
+        },
+  );
+
+  if (project) {
+    const entries = [...project.config.quests, ...project.config.questTypes];
+    const directories = new Set(
+      entries.map((entry) => dirname(resolve(root, entry.entry))),
+    );
+    if (!directories.size) directories.add(root);
+    for (const directory of directories) {
+      try {
+        createRequire(join(directory, "package.json")).resolve(
+          "@domino-sdk/relay/authoring",
+        );
+        checks.push({
+          id: "sdk",
+          status: "ok",
+          directory,
+          message:
+            "SDK imports resolve. Version compatibility and compilation have not been checked.",
+        });
+      } catch {
+        checks.push({
+          id: "sdk",
+          status: "error",
+          directory,
+          message:
+            "Install @domino-sdk/relay in the package that owns the quest modules using this app's package manager. Use the version supplied by the starter or the published @domino-sdk/relay package.",
+        });
+      }
+    }
+    for (const { entry } of entries) {
+      try {
+        await access(resolve(root, entry));
+        checks.push({
+          id: "entry",
+          status: "ok",
+          entry,
+          message: "Authored entry exists.",
+        });
+      } catch {
+        checks.push({
+          id: "entry",
+          status: "error",
+          entry,
+          message:
+            "Entry is missing or unreadable. Correct its path in relay.json or restore the module.",
+        });
+      }
+    }
+    if (project.config.app) {
+      for (const dependency of [
+        "@domino-sdk/relay-runtime/package.json",
+        "wrangler/package.json",
+      ]) {
+        try {
+          createRequire(join(root, "package.json")).resolve(dependency);
+          checks.push({
+            id: "local-preview-dependency",
+            status: "ok",
+            dependency,
+            message: "Local preview dependency resolves.",
+          });
+        } catch {
+          checks.push({
+            id: "local-preview-dependency",
+            status: "error",
+            dependency,
+            message:
+              "Install the starter dependencies before running domino dev.",
+          });
+        }
+      }
+    }
+  }
+
+  let remoteAccess = "not-checked";
+  if (options.remote && project) {
+    try {
+      const value = await request(connection, "/access");
+      const selected = value.projects.find(
+        (item) => item.project === connection.project,
+      );
+      if (
+        value.organization !== connection.organization ||
+        !selected?.environments.includes(connection.environment)
+      )
+        throw new Error(
+          "The signed-in account cannot access the selected organization, project, and environment.",
+        );
+      remoteAccess = "verified";
+      checks.push({
+        id: "remote-access",
+        status: "ok",
+        message:
+          "Management API verified project access. This does not verify participant sign-in or publication permission.",
+      });
+    } catch (error) {
+      remoteAccess = "failed";
+      checks.push({
+        id: "remote-access",
+        status: "error",
+        message: error.message,
+        next: "Check the selected scope and run domino login for this API, then retry domino doctor --remote.",
+      });
+    }
+  }
+  return {
+    directory: root,
+    healthy: checks.every((check) => check.status !== "error"),
+    scope: connection,
+    agents,
+    remoteAccess,
+    preview: project?.config.app
+      ? "static-app-configured"
+      : "use-existing-app-workflow",
+    checks,
+    next: "After setup, run the project's checks and verify a real participant action. Setup diagnostics do not prove preview or live readiness.",
+  };
+}