@domino-sdk/relay-cli 0.1.0 → 0.2.0

package/cli/agents.mjs

@@ -10,6 +10,9 @@ const resources = [
   "references/hosted.md",
   "references/existing-app.md",
   "references/authoring.md",
+  "references/participant-api.md",
+  "references/referrals.md",
+  "references/troubleshooting.md",
 ];
 
 async function skillFiles(agent) {

package/cli/capabilities.json

@@ -0,0 +1,82 @@
+{
+  "format": 1,
+  "capabilities": [
+    {
+      "id": "identity",
+      "support": "native",
+      "description": "Real email and configured OAuth sign-in; identities and sessions are scoped to a project and environment.",
+      "entrypoints": [
+        "auth.providers",
+        "auth.start",
+        "auth.emailStart",
+        "auth.emailVerify",
+        "auth.session"
+      ],
+      "evidence": ["tests/auth.test.mjs", "tests/email-auth.test.mjs"]
+    },
+    {
+      "id": "quests",
+      "support": "native",
+      "description": "Claim, photo, quiz, staff and automatic quests; immutable releases pin attempts and promised rewards.",
+      "entrypoints": ["quests.experience", "quests.observe", "quests.open"],
+      "evidence": ["tests/quest-catalog.test.mjs", "tests/submissions.test.mjs"]
+    },
+    {
+      "id": "points",
+      "support": "native",
+      "description": "Award points to the participant completing a quest. The server applies completion and rewards; the browser cannot write balances.",
+      "entrypoints": ["points", "decision.accept", "me.observeProgress"],
+      "evidence": ["tests/journey.test.mjs"]
+    },
+    {
+      "id": "review",
+      "support": "native",
+      "description": "Queue a quest attempt for an authorized human reviewer. Review decisions and reward execution remain server-owned.",
+      "entrypoints": ["decision.review"],
+      "evidence": ["tests/photo-review.test.mjs"]
+    },
+    {
+      "id": "milestones",
+      "support": "composed",
+      "description": "Compose same-participant completion prerequisites with requires: [completed(quest)]. Arbitrary aggregate thresholds and cross-participant conditions need application logic.",
+      "entrypoints": ["completed", "automatic", "defineQuest"],
+      "evidence": ["tests/availability.test.mjs"]
+    },
+    {
+      "id": "referrals",
+      "support": "own-backend",
+      "description": "No native referral attribution service. Your backend must issue invite codes, attribute the authenticated invitee, deduplicate claims and prevent self-referrals. A URL parameter alone is not verified attribution.",
+      "entrypoints": [],
+      "reference": "referrals",
+      "evidence": [
+        "packages/sdk/src/authoring.ts",
+        "packages/sdk/src/schema.ts"
+      ]
+    },
+    {
+      "id": "cross-participant-rewards",
+      "support": "unsupported",
+      "description": "Quest rewards target the completing participant. There is no supported inviter-targeted reward operation. Do not promise automatic inviter points; an application-owned reward ledger requires its own implementation.",
+      "entrypoints": [],
+      "reference": "referrals",
+      "evidence": [
+        "packages/sdk/src/authoring.ts",
+        "packages/sdk/src/schema.ts"
+      ]
+    },
+    {
+      "id": "rankings",
+      "support": "own-backend",
+      "description": "No participant leaderboard or referral queue ranking API. Build an authorized backend projection with explicit privacy and tie-breaking rules; never expose management credentials in a browser.",
+      "entrypoints": [],
+      "evidence": ["packages/sdk/src/index.ts"]
+    },
+    {
+      "id": "wallet-verification",
+      "support": "native",
+      "description": "Connect a wallet and verify supported Solana balances. This reads a real network; it does not send assets or execute payouts.",
+      "entrypoints": ["wallet.connection", "wallet.challenge", "wallet.verify"],
+      "evidence": ["tests/wallet.test.mjs"]
+    }
+  ]
+}

package/cli/commands/agents.mjs

@@ -36,6 +36,7 @@ export function registerAgentCommands(program) {
     .description(
       "Inspect local agent setup without changing files or running app code",
     )
+    .option("--offline", "Check dependencies for the isolated local runtime")
     .option(
       "--remote",
       "Also verify access to the selected project through the management API",

package/cli/commands/discovery.mjs

@@ -0,0 +1,45 @@
+import { readFile } from "node:fs/promises";
+import { action } from "../runtime.mjs";
+
+const references = ["participant-api", "referrals", "troubleshooting"];
+export function registerDiscoveryCommands(program) {
+  program
+    .command("capabilities")
+    .description("Discover supported Domino features and their limitations")
+    .argument("[id]", "Capability identifier")
+    .action(
+      action(async (_, id) => {
+        const catalog = JSON.parse(
+          await readFile(
+            new URL("../capabilities.json", import.meta.url),
+            "utf8",
+          ),
+        );
+        if (!id) return catalog;
+        const capability = catalog.capabilities.find((item) => item.id === id);
+        if (!capability)
+          throw new Error(
+            `Unknown capability. Choose: ${catalog.capabilities.map((item) => item.id).join(", ")}`,
+          );
+        return capability;
+      }),
+    );
+  program
+    .command("reference")
+    .description("Read a compact task or SDK reference bundled with this CLI")
+    .argument("[topic]", references.join(", "))
+    .action(
+      action(async (_, topic) => {
+        if (!topic) return { topics: references };
+        if (!references.includes(topic))
+          throw new Error(`Choose: ${references.join(", ")}`);
+        return {
+          topic,
+          markdown: await readFile(
+            new URL(`../skills/domino/references/${topic}.md`, import.meta.url),
+            "utf8",
+          ),
+        };
+      }),
+    );
+}

package/cli/commands/hosting.mjs

@@ -1,3 +1,5 @@
+import { Option } from "commander";
+import { connectedDev } from "../connected-dev.mjs";
 import { dirname, resolve } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
@@ -41,9 +43,30 @@ export function registerHostingCommands(program) {
     );
   program
     .command("dev")
-    .description("Run the campaign and an isolated local Relay runtime")
+    .description(
+      "Run your app with hosted test data and a shareable HTTPS preview",
+    )
+    .option("--offline", "Use an isolated local runtime without shared hosting")
+    .addOption(
+      new Option(
+        "--review-mode <mode>",
+        "Explicit photo-review simulation for --offline only",
+      ).choices([
+        "fixture-pass",
+        "fixture-fail",
+        "fixture-unclear",
+        "fixture-error",
+      ]),
+    )
+    .option("--cloudflared <path>", "Path to the Cloudflare Tunnel connector")
     .option("--port <port>", "App development server port")
-    .action(action(({ project, options }) => dev(project, options)));
+    .action(
+      action(({ project, connection, options }) =>
+        options.offline
+          ? dev(project, options)
+          : connectedDev(project, connection, options),
+      ),
+    );
   program
     .command("create")
     .description("Create a hosted campaign repository and check it out locally")

package/cli/commands/staging.mjs

@@ -24,6 +24,15 @@ export function registerStagingCommands(program) {
           throw new Error(
             "Cloud staging currently supports static campaign checkouts with app.kind=static in relay.json. This project is not configured for cloud staging. SSR Worker apps use the Cloudflare Worker deployment workflow.",
           );
+        const scoped = { ...connection, environment: "test" };
+        const preflight = await request(scoped, "/preflight");
+        if (preflight.staging !== "configured")
+          throw new Error(
+            preflight.checks
+              .filter((check) => check.status === "error")
+              .map((check) => check.message)
+              .join("\n"),
+          );
         const cwd = dirname(project.path);
         if (
           !options.commit &&
@@ -36,7 +45,6 @@ export function registerStagingCommands(program) {
           options.commit ?? (await runGit(["rev-parse", "HEAD"], { cwd }));
         if (!/^[a-f0-9]{40}$/.test(commit))
           throw new Error("Use a full 40-character commit SHA.");
-        const scoped = { ...connection, environment: "test" };
         const requestId = options.requestId ?? randomUUID();
         process.stderr.write(`Build request ${requestId}\n`);
         let build;

package/cli/connected-dev.mjs

@@ -0,0 +1,223 @@
+import { createInterface } from "node:readline";
+import { previewConnector } from "./connector.mjs";
+import { spawn } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { watch } from "node:fs";
+import { createServer } from "node:net";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { request } from "./connection.mjs";
+import { developmentSync } from "./development-sync.mjs";
+
+export async function connectedDev(project, connection, options) {
+  if (options.reviewMode)
+    throw new Error(
+      "--review-mode requires --offline. Hosted test uses real providers.",
+    );
+  if (!project?.config.app)
+    throw new Error("Configure the app's dev script in relay.json first.");
+  if (connection.environment !== "test")
+    throw new Error("domino dev uses test data. Select --environment test.");
+  const preflight = await request(connection, "/preflight");
+  if (preflight.development?.status !== "configured")
+    throw new Error(
+      "Hosted development is not configured. Run domino doctor --remote --json; a Domino operator must enable previews and test sign-in.",
+    );
+  const root = dirname(project.path);
+  const connector = await previewConnector(options.cloudflared);
+  await new Promise((resolve, reject) => {
+    const check = spawn(connector, ["--version"], { stdio: "ignore" });
+    check.on("error", () =>
+      reject(
+        new Error(
+          "Install cloudflared to run a shared preview, or pass --cloudflared PATH.",
+        ),
+      ),
+    );
+    check.on("exit", (code) =>
+      code === 0 ? resolve() : reject(new Error("cloudflared could not run.")),
+    );
+  });
+  // Stored in ignored runtime state, distinct for each checkout/worktree.
+  const stateDirectory = join(root, ".wrangler", "domino");
+  await mkdir(stateDirectory, { recursive: true });
+  const workspaceFile = join(stateDirectory, "workspace-id");
+  try {
+    await writeFile(workspaceFile, randomUUID(), { flag: "wx", mode: 0o600 });
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+  }
+  const workspace = (await readFile(workspaceFile, "utf8")).trim();
+  if (!/^[a-f0-9-]{36}$/.test(workspace))
+    throw new Error("Invalid development workspace identity.");
+  const socket = createServer();
+  await new Promise((resolve, reject) => {
+    socket.once("error", reject);
+    socket.listen(0, "127.0.0.1", resolve);
+  });
+  const port = Number(options.port ?? socket.address().port);
+  await new Promise((resolve) => socket.close(resolve));
+  if (!Number.isInteger(port) || port < 1 || port > 65535)
+    throw new Error("Invalid app port.");
+  const generation = randomUUID();
+  const lease = { workspace, generation };
+  const children = [];
+  let stopping = false,
+    failure,
+    watcher,
+    session;
+  const stop = () => {
+    stopping = true;
+    watcher?.close();
+    for (const child of children) {
+      if (!child.pid) continue;
+      try {
+        process.platform === "win32"
+          ? child.kill("SIGTERM")
+          : process.kill(-child.pid, "SIGTERM");
+      } catch (error) {
+        if (error.code !== "ESRCH") failure ??= error;
+      }
+    }
+  };
+  const start = (command, args, extraEnv = {}) => {
+    const safeEnv = Object.fromEntries(
+      Object.entries(process.env).filter(
+        ([key]) =>
+          !key.startsWith("RELAY_") &&
+          !key.startsWith("CLOUDFLARE_") &&
+          key !== "TUNNEL_TOKEN",
+      ),
+    );
+    const child = spawn(command, args, {
+      cwd: root,
+      env: { ...safeEnv, ...extraEnv },
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: process.platform !== "win32",
+    });
+    for (const stream of [child.stdout, child.stderr]) {
+      createInterface({ input: stream }).on("line", (line) => {
+        const publicLine =
+          session && extraEnv.DOMINO_APP_PORT
+            ? line
+                .replaceAll(`http://127.0.0.1:${port}`, session.url)
+                .replaceAll(`http://localhost:${port}`, session.url)
+            : line;
+        process.stderr.write(publicLine + "\n");
+      });
+    }
+    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 {
+    session = await request(connection, "/development/session", "POST", {
+      ...lease,
+      port,
+    });
+    const sync = developmentSync(connection, project.path);
+    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_APP_PORT: String(port),
+      DOMINO_PREVIEW_ORIGIN: session.url,
+    });
+    let appReady = false;
+    for (let attempt = 0; attempt < 150 && !stopping; attempt++) {
+      try {
+        const response = await fetch(`http://127.0.0.1:${port}`, {
+          signal: AbortSignal.timeout(1000),
+        });
+        appReady = response.ok;
+        await response.body?.cancel();
+      } catch {}
+      if (appReady) break;
+      await delay(200);
+    }
+    if (!appReady)
+      throw (
+        failure ?? new Error("The app did not start. Check its dev script.")
+      );
+    // Token is inherited only by the connector, never the app or command arguments.
+    start(
+      connector,
+      ["tunnel", "--no-autoupdate", "--loglevel", "warn", "run"],
+      {
+        TUNNEL_TOKEN: session.token,
+      },
+    );
+    let reachable = false;
+    for (let attempt = 0; attempt < 60 && !stopping; attempt++) {
+      if (attempt % 15 === 0)
+        await request(connection, "/development/session", "PUT", lease);
+      try {
+        const response = await fetch(session.url, {
+          signal: AbortSignal.timeout(2000),
+        });
+        reachable = response.ok;
+        await response.body?.cancel();
+      } catch {}
+      if (reachable) break;
+      await delay(1000);
+    }
+    if (!reachable)
+      throw (
+        failure ??
+        new Error(
+          "The shared preview could not be reached. Check tunnel connectivity and preview DNS/TLS configuration.",
+        )
+      );
+    process.stderr.write(
+      `Preview: ${session.url}\nUses this project's hosted test data and real sign-in. Keep this terminal running. Use domino stage for a preview that stays online.\n`,
+    );
+    let renewed = Date.now();
+    while (!stopping) {
+      await delay(300);
+      if (Date.now() - renewed > 25_000) {
+        await request(connection, "/development/session", "PUT", lease);
+        renewed = Date.now();
+      }
+      if (dirty) {
+        dirty = false;
+        try {
+          if (await sync()) console.error("Hosted test quests updated.");
+        } catch (error) {
+          console.error(`Quest update failed: ${error.message}`);
+        }
+      }
+    }
+    if (failure) throw failure;
+    return { stopped: true, previewUrl: session.url };
+  } finally {
+    stop();
+    if (session)
+      await request(connection, "/development/session", "DELETE", lease).catch(
+        () =>
+          console.error("Preview cleanup will finish when its lease expires."),
+      );
+    process.removeListener("SIGINT", stop);
+    process.removeListener("SIGTERM", stop);
+  }
+}

package/cli/connector.mjs

@@ -0,0 +1,109 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import {
+  mkdir,
+  mkdtemp,
+  readFile,
+  writeFile,
+  chmod,
+  rename,
+  rm,
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const version = "2026.9.1";
+const distributions = {
+  "darwin-x64": [
+    "cloudflared-darwin-amd64.tgz",
+    "ff0d3b51d5ff70eceef89d6b32145fee985018a2174596a5dbe405e2766e2ac4",
+  ],
+  "darwin-arm64": [
+    "cloudflared-darwin-arm64.tgz",
+    "c27ab8fd0aa489449e3d201eb02f957ef460a13b613662928b1b23394bf1bcfe",
+  ],
+  "linux-x64": [
+    "cloudflared-linux-amd64",
+    "03f1f25d1cc93b9ad6c60569d44060bc4f17ed97075760ed8cfca4b12dcd68cc",
+  ],
+  "linux-arm64": [
+    "cloudflared-linux-arm64",
+    "3d97437c71848bd8df68041e12436b484a661d95073ea1937f01a845ce88faa3",
+  ],
+  "win32-x64": [
+    "cloudflared-windows-amd64.exe",
+    "2837888cc0f5d58f15b6dc478376de90b4d3ba5241c7947455d1e0a0df429712",
+  ],
+};
+export async function previewConnector(override) {
+  if (override) return override;
+  const platform = `${process.platform}-${process.arch}`;
+  const distribution = distributions[platform];
+  if (!distribution)
+    throw new Error(
+      `No bundled connector for ${platform}. Install cloudflared and pass --cloudflared PATH.`,
+    );
+  const directory = join(
+    process.env.RELAY_CONFIG_DIR ?? join(homedir(), ".config/domino"),
+    "connectors",
+    version,
+    platform,
+  );
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const executable = join(
+    directory,
+    process.platform === "win32" ? "cloudflared.exe" : "cloudflared",
+  );
+  try {
+    const expected = (await readFile(executable + ".sha256", "utf8")).trim();
+    if (
+      createHash("sha256")
+        .update(await readFile(executable))
+        .digest("hex") === expected
+    )
+      return executable;
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  process.stderr.write(`Preparing preview connector ${version}...\n`);
+  const temporary = await mkdtemp(join(directory, ".install-"));
+  try {
+    const [asset, digest] = distribution;
+    const response = await fetch(
+      `https://github.com/cloudflare/cloudflared/releases/download/${version}/${asset}`,
+      { signal: AbortSignal.timeout(120000) },
+    );
+    if (!response.ok)
+      throw new Error(
+        `Connector download failed (${response.status}). Retry domino dev.`,
+      );
+    const archive = Buffer.from(await response.arrayBuffer());
+    if (createHash("sha256").update(archive).digest("hex") !== digest)
+      throw new Error(
+        "Connector checksum mismatch. Download was not installed.",
+      );
+    const downloaded = join(temporary, asset);
+    await writeFile(downloaded, archive, { mode: 0o600 });
+    let binary = downloaded;
+    if (asset.endsWith(".tgz")) {
+      await promisify(execFile)("tar", [
+        "-xzf",
+        downloaded,
+        "-C",
+        temporary,
+        "cloudflared",
+      ]);
+      binary = join(temporary, "cloudflared");
+    }
+    await chmod(binary, 0o700);
+    const binaryHash = createHash("sha256")
+      .update(await readFile(binary))
+      .digest("hex");
+    await rename(binary, executable);
+    await writeFile(executable + ".sha256", binaryHash, { mode: 0o600 });
+    return executable;
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+}

package/cli/dev.mjs

@@ -6,7 +6,7 @@ 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";
+import { developmentSync } from "./development-sync.mjs";
 
 async function listen(server, port = 0) {
   await new Promise((resolve, reject) => {
@@ -27,6 +27,10 @@ export async function dev(project, options) {
     throw new Error(
       "Configure app scripts in relay.json before running domino dev.",
     );
+  if (options.reviewMode)
+    console.error(
+      `Offline photo review uses ${options.reviewMode}; no external verification is performed.`,
+    );
   const root = dirname(project.path);
   const require = createRequire(join(root, "package.json"));
   const runtime = dirname(
@@ -174,21 +178,7 @@ export async function dev(project, options) {
       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,
-      });
-    }
+    const sync = developmentSync(connection, project.path, options.reviewMode);
     await sync();
     let dirty = false;
     watcher = watch(root, { recursive: true }, (_, name) => {
@@ -202,6 +192,7 @@ export async function dev(project, options) {
         dirty = true;
     });
     start("pnpm", ["run", project.config.app.devScript], {
+      VITE_DOMINO_OFFLINE: "true",
       DOMINO_LOCAL_API: connection.apiUrl,
       DOMINO_DEV_CONTROL: `http://127.0.0.1:${controlPort}`,
       DOMINO_APP_PORT: String(appPort),
@@ -214,8 +205,7 @@ export async function dev(project, options) {
       if (dirty) {
         dirty = false;
         try {
-          await sync();
-          console.error("Local quests updated.");
+          if (await sync()) console.error("Local quests updated.");
         } catch (error) {
           console.error(`Local quest update failed: ${error.message}`);
         }

package/cli/development-sync.mjs

@@ -0,0 +1,28 @@
+import { request } from "./connection.mjs";
+import { bundleProject, findProject } from "./project.mjs";
+
+/** Frontend edits must not create new quest releases in the shared test project. */
+export function developmentSync(connection, projectPath, reviewMode) {
+  let published;
+  return async () => {
+    const project = await findProject(projectPath);
+    const payload = await bundleProject(project);
+    if (reviewMode) {
+      for (const release of payload.releases) release.provider = reviewMode;
+      for (const type of payload.types) type.provider = reviewMode;
+    }
+    const signature = JSON.stringify(payload);
+    if (signature === published) return false;
+    const preview = await request(
+      connection,
+      "/deployments/preview",
+      "POST",
+      payload,
+    );
+    await request(connection, "/deployments/publish", "POST", {
+      id: preview.id,
+    });
+    published = signature;
+    return true;
+  };
+}