@domino-sdk/relay-cli 0.3.0 → 0.5.0

package/cli/capabilities.json

@@ -12,7 +12,25 @@
         "auth.emailVerify",
         "auth.session"
       ],
-      "evidence": ["tests/auth.test.mjs", "tests/email-auth.test.mjs"]
+      "evidence": [
+        "tests/auth.test.mjs",
+        "tests/email-auth.test.mjs"
+      ]
+    },
+    {
+      "id": "connected-accounts",
+      "support": "native",
+      "description": "Operators connect a Discord server and install the managed bot in Console Integrations. Participants sign in with Discord or link its identity. Declare integrations: [discord] and use ctx.discord.member() without a server ID. Captured membership and role reads survive recovery. No messages, writes, or X verification.",
+      "entrypoints": [
+        "auth.accounts",
+        "auth.start",
+        "auth.disconnect"
+      ],
+      "reference": "authoring",
+      "evidence": [
+        "tests/connected-accounts.test.mjs",
+        "apps/api/src/provider-registry.ts"
+      ]
     },
     {
       "id": "identity-exchange",
@@ -49,38 +67,45 @@
     {
       "id": "milestones",
       "support": "composed",
-      "description": "Compose same-participant completion prerequisites with requires: [completed(quest)]. Arbitrary aggregate thresholds and cross-participant conditions need application logic.",
+      "description": "Compose same-participant completion prerequisites with requires: [completed(quest)]. Referral programs support milestones based on distinct qualified friends. Other aggregate thresholds 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": [],
+      "support": "native",
+      "description": "Project-scoped invitation codes, immutable inviter attribution, configurable signup, quest or external qualification, fixed rewards and distinct-friend milestones. Selective one-level inviter bonuses add points without reducing invitee awards. Code-defined rules publish through reviewed project deployments.",
+      "entrypoints": [
+        "defineReferral",
+        "referrals.list",
+        "referrals.summary",
+        "referrals.accept",
+        "referrals.history"
+      ],
       "reference": "referrals",
-      "evidence": [
-        "packages/sdk/src/authoring.ts",
-        "packages/sdk/src/schema.ts"
-      ]
+      "evidence": ["tests/referrals.test.mjs", "packages/sdk/src/referrals.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": [],
+      "support": "native",
+      "description": "Referral programs can reward inviter and invitee independently and award a selective percentage of eligible points to the inviter. Bonuses accumulate fractions and support limits, suspension and correction recovery. Arbitrary participant-to-participant transfers and multi-level commissions are not supported.",
+      "entrypoints": ["defineReferral", "referrals.summary"],
       "reference": "referrals",
-      "evidence": [
-        "packages/sdk/src/authoring.ts",
-        "packages/sdk/src/schema.ts"
-      ]
+      "evidence": ["tests/referrals.test.mjs", "apps/api/src/referrals.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"]
+      "support": "native",
+      "description": "Publish project-scoped points leaderboards through project deployments. Read paginated standings, your rank, and nearby competitors with shared tie ranks. Code defines balance, earned, or net calculations and time windows. Public access is explicit; participant rows use board-specific aliases. Scoped management APIs supply external points, corrections, groups, and exclusions. Referral bonus points contribute to their named balance. Cross-project balances, finalized results, and rank-based prizes are separate work.",
+      "entrypoints": [
+        "defineLeaderboard",
+        "leaderboards.list",
+        "leaderboards.standings"
+      ],
+      "evidence": [
+        "tests/leaderboards.test.mjs",
+        "packages/sdk/src/leaderboards.ts"
+      ]
     },
     {
       "id": "wallet-verification",

package/cli/commands/discovery.mjs

@@ -1,11 +1,18 @@
 import { readFile } from "node:fs/promises";
 import { action } from "../runtime.mjs";
 
-const references = ["participant-api", "referrals", "troubleshooting"];
+const references = [
+  "authoring",
+  "participant-api",
+  "referrals",
+  "troubleshooting",
+];
 export function registerDiscoveryCommands(program) {
   program
     .command("capabilities")
-    .description("Discover supported Domino features and their limitations")
+    .description(
+      "Read this CLI release's bundled capability catalog (not a server probe)",
+    )
     .argument("[id]", "Capability identifier")
     .action(
       action(async (_, id) => {
@@ -15,13 +22,25 @@ export function registerDiscoveryCommands(program) {
             "utf8",
           ),
         );
-        if (!id) return catalog;
+        const { version } = JSON.parse(
+          await readFile(
+            new URL("../../package.json", import.meta.url),
+            "utf8",
+          ),
+        );
+        const provenance = {
+          kind: "bundled-catalog",
+          cliVersion: version,
+          serverVerified: false,
+          note: "Describes this CLI release. Scope flags do not make it project-specific. Verify the deployed contract before treating missing or conflicting entries as unsupported.",
+        };
+        if (!id) return { ...catalog, provenance };
         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;
+        return { ...capability, provenance };
       }),
     );
   program

package/cli/commands/hosting.mjs

@@ -7,7 +7,7 @@ import { action } from "../runtime.mjs";
 import { request } from "../connection.mjs";
 import { checkout, requireNewDirectory } from "../git.mjs";
 import { dev } from "../dev.mjs";
-import { bundleCatalog, bundleProject } from "../project.mjs";
+import { bundleProject } from "../project.mjs";
 
 export function registerHostingCommands(program) {
   program
@@ -29,15 +29,14 @@ export function registerHostingCommands(program) {
             throw new Error(error.stdout || error.stderr || error.message);
           }
         }
-        const quests = project.config.quests.length
-          ? await bundleProject(project)
-          : { releases: [] };
-        const catalog = await bundleCatalog(project);
+        const bundle = await bundleProject(project, { allowEmpty: true });
         return {
           checked: true,
-          quests: quests.releases.length,
-          types: catalog.types.length,
-          collections: catalog.collections.length,
+          quests: bundle.releases.length,
+          leaderboards: bundle.leaderboards.length,
+          referrals: bundle.referrals.length,
+          types: bundle.types.length,
+          collections: bundle.collections.length,
         };
       }),
     );

package/cli/commands/project.mjs

@@ -1,4 +1,5 @@
-import { writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
 import { action } from "../runtime.mjs";
 import { request } from "../connection.mjs";
 import { initialize, bundleProject } from "../project.mjs";
@@ -26,6 +27,8 @@ function summary(value) {
     })),
     collections: value.collections,
     supportedInteractions: value.supportedInteractions,
+    leaderboards: value.leaderboards,
+    referrals: value.referrals,
   };
 }
 async function publish(connection, id) {
@@ -74,12 +77,15 @@ async function build({ project, connection, options }, deploy) {
     return publish(connection, preview.id);
   }
   if (options.out) {
+    await mkdir(dirname(options.out), { recursive: true });
     await writeFile(options.out, JSON.stringify(payload, null, 2) + "\n");
     return {
       file: options.out,
       quests: payload.releases.length,
       types: payload.types.length,
       collections: payload.collections.length,
+      leaderboards: payload.leaderboards.length,
+      referrals: payload.referrals.length,
     };
   }
   return payload;

package/cli/commands/staging.mjs

@@ -20,9 +20,9 @@ export function registerStagingCommands(program) {
       action(async ({ connection, project, options }) => {
         if (!project)
           throw new Error("Run stage inside a hosted campaign checkout.");
-        if (project.config.app?.kind !== "static")
+        if (!project.config.app)
           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.",
+            "Configure app.kind as static or worker in relay.json before staging.",
           );
         const scoped = { ...connection, environment: "test" };
         const preflight = await request(scoped, "/preflight");

package/cli/connected-dev.mjs

@@ -22,7 +22,7 @@ export async function connectedDev(project, connection, options) {
   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.",
+      "Hosted development is not configured. Run domino doctor --remote --json; a Domino operator must enable preview hosting.",
     );
   const root = dirname(project.path);
   const connector = await previewConnector(options.cloudflared);
@@ -126,6 +126,7 @@ export async function connectedDev(project, connection, options) {
     session = await request(connection, "/development/session", "POST", {
       ...lease,
       port,
+      routing: project.config.app.routing,
     });
     const sync = developmentSync(connection, project.path);
     await sync();
@@ -143,6 +144,7 @@ export async function connectedDev(project, connection, options) {
     start("pnpm", ["run", project.config.app.devScript], {
       DOMINO_APP_PORT: String(port),
       DOMINO_PREVIEW_ORIGIN: session.url,
+      DOMINO_PARTICIPANT_API: connection.apiUrl,
     });
     let appReady = false;
     for (let attempt = 0; attempt < 150 && !stopping; attempt++) {
@@ -190,7 +192,7 @@ export async function connectedDev(project, connection, options) {
         )
       );
     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`,
+      `Preview: ${session.url}\nKeep this terminal running. Use domino stage for a preview that stays online.\n`,
     );
     let renewed = Date.now();
     while (!stopping) {

package/cli/discovery.mjs

@@ -0,0 +1,62 @@
+import { glob } from "node:fs/promises";
+import { dirname, relative, resolve } from "node:path";
+
+export const defaultDiscovery = {
+  quests: ["quests/**/*.quest.ts"],
+  questTypes: ["quests/**/*.quest-type.ts"],
+};
+
+// These directories contain dependencies, build output, or local runtime data.
+const excluded =
+  /(^|[/\\])(node_modules|dist|\.git|\.domino|\.domino-build|\.wrangler|\.artifacts)([/\\]|$)/;
+
+export async function discoverEntries(project, kind) {
+  const root = dirname(project.path);
+  const discovery = project.config.discover;
+  const entries = new Map();
+  const key = (entry) =>
+    JSON.stringify([resolve(root, entry.entry), entry.exportName ?? "default"]);
+
+  for (const entry of project.config[kind]) {
+    const identity = key(entry);
+    if (entries.has(identity))
+      throw new Error(`Duplicate ${kind} entry: ${entry.entry}`);
+    entries.set(identity, entry);
+  }
+
+  if (discovery) {
+    const paths = [];
+    for await (const file of glob(discovery[kind], {
+      cwd: root,
+      withFileTypes: true,
+      exclude: (file) =>
+        excluded.test(relative(root, resolve(file.parentPath, file.name))),
+    })) {
+      if (file.isFile()) paths.push(resolve(file.parentPath, file.name));
+    }
+    for (const path of paths.sort()) {
+      const entry = {
+        entry: path,
+        exportName: "default",
+        provider: discovery.provider,
+        ...(kind === "quests" ? { settings: {} } : {}),
+      };
+      // Explicit entries customize a discovered default export without adding it twice.
+      const explicit = entries.get(key(entry));
+      entries.set(
+        key(entry),
+        explicit
+          ? {
+              ...explicit,
+              exportName: "default",
+              provider: explicit.provider ?? discovery.provider,
+            }
+          : entry,
+      );
+    }
+  }
+  return [...entries.values()].map((entry) => ({
+    ...entry,
+    provider: entry.provider ?? "workers-ai",
+  }));
+}

package/cli/doctor.mjs

@@ -4,10 +4,13 @@ import { createHash } from "node:crypto";
 import { access, readFile } from "node:fs/promises";
 import { inspectAgentSkills } from "./agents.mjs";
 import { request } from "./connection.mjs";
+import { discoverEntries } from "./discovery.mjs";
+import { packageManager } from "./package-manager.mjs";
 
-export async function diagnose({ project, connection, options }) {
+export async function diagnose({ project, connection, options, scopeSources }) {
   const checks = [];
   const root = project ? dirname(project.path) : process.cwd();
+  const manager = await packageManager(root);
   checks.push(
     project
       ? { id: "manifest", status: "ok", message: "Project manifest is valid." }
@@ -87,7 +90,12 @@ export async function diagnose({ project, connection, options }) {
   );
 
   if (project) {
-    const entries = [...project.config.quests, ...project.config.questTypes];
+    const entries = [
+      ...(await discoverEntries(project, "quests")),
+      ...(await discoverEntries(project, "questTypes")),
+      ...project.config.leaderboards,
+      ...project.config.referrals,
+    ];
     const directories = new Set(
       entries.map((entry) => dirname(resolve(root, entry.entry))),
     );
@@ -164,6 +172,13 @@ export async function diagnose({ project, connection, options }) {
     development: { status: "not-checked" },
     staging: "not-checked",
   };
+  if (options.remote && !project)
+    checks.push({
+      id: "remote-access",
+      status: "warning",
+      message:
+        "Remote access was not checked because no relay.json was found. This does not diagnose a failed checkout. Use its checkout error details; do not install skills in the parent directory to repair remote access.",
+    });
   if (options.remote && project) {
     try {
       const value = await request(connection, "/access");
@@ -232,6 +247,8 @@ export async function diagnose({ project, connection, options }) {
       project: connection.project,
       environment: connection.environment,
     },
+    scopeSources,
+    packageManager: manager,
     agents,
     readiness,
     remoteAccess,
@@ -239,6 +256,10 @@ export async function diagnose({ project, connection, options }) {
       ? "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.",
+    next:
+      checks.some((check) => check.id === "sdk" && check.status === "error") &&
+      manager.installCommand
+        ? `Run ${manager.installCommand} in ${root} and wait for it to finish before rerunning doctor. Then verify a participant action.`
+        : "After setup, run the project's checks and verify a real participant action. Setup diagnostics do not prove preview or live readiness.",
   };
 }

package/cli/git.mjs

@@ -3,6 +3,7 @@ import { access, mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { apiUrl, request, savedToken } from "./connection.mjs";
+import { packageManager } from "./package-manager.mjs";
 
 export function runGit(args, { cwd, input, env = {} } = {}) {
   return new Promise((resolve, reject) => {
@@ -20,11 +21,13 @@ export function runGit(args, { cwd, input, env = {} } = {}) {
       stderr += data;
     });
     child.on("error", reject);
-    child.on("close", (code) =>
-      code === 0
-        ? resolve(stdout.trim())
-        : reject(new Error(`Git failed (${code}): ${stderr.trim()}`)),
-    );
+    child.on("close", (code) => {
+      if (code === 0) return resolve(stdout.trim());
+      const error = new Error(`Git failed (${code}): ${stderr.trim()}`);
+      error.exitCode = code;
+      error.gitCommand = args[0];
+      reject(error);
+    });
     child.stdin.end(input);
   });
 }
@@ -86,7 +89,7 @@ export async function requireNewDirectory(directory) {
 export async function checkout(connection, repository, directory) {
   if (repository.status !== "ready")
     throw new Error(
-      "Repository provisioning is incomplete. Retry domino create.",
+      `Repository provisioning is incomplete (status: ${repository.status}). Inspect the existing project in Console, then retry domino checkout. Do not create a replacement project.`,
     );
   const remote = new URL(repository.remote);
   if (
@@ -152,14 +155,42 @@ export async function checkout(connection, repository, directory) {
         environment: "test",
       }) + "\n",
     );
+    const manager = await packageManager(root);
     return {
       directory: root,
       remote: repository.remote,
-      next: "Install dependencies with pnpm install, then run domino dev.",
+      packageManager: manager,
+      scopeFile: resolve(root, ".git/domino.json"),
+      next: manager.installCommand
+        ? `In ${root}, run ${manager.installCommand} and wait for success. Then run the project's installed domino doctor --remote --json before domino dev.`
+        : "Read package.json and install with the project's declared package manager and lockfile. Wait for success before running the installed domino doctor --remote --json.",
     };
   } catch (error) {
     // This directory was created exclusively by this operation and has no user edits.
     await rm(root, { recursive: true, force: true });
+    if (error.gitCommand) {
+      error.code = "CHECKOUT_GIT_FAILED";
+      error.details = {
+        phase: error.gitCommand,
+        exitCode: error.exitCode,
+        classification: /repository not found/i.test(error.message)
+          ? "repository-unavailable"
+          : /authentication failed|401|403/i.test(error.message)
+            ? "access-denied"
+            : "git-failure",
+        repositoryStatus: repository.status,
+        organization: repository.organization,
+        project: repository.project,
+        remote: repository.remote,
+      };
+      error.message += ` Repository API reported ${repository.status}; Git ${error.gitCommand} failed.`;
+      error.message +=
+        error.gitCommand === "fetch"
+          ? " This does not establish whether provisioning, access, or transport caused the failure. Retry checkout once with the same scope; if it repeats, share these diagnostics with the operator."
+          : " Resolve the Git error above before retrying checkout.";
+      error.message +=
+        " Do not recreate the project or install dependencies in its parent directory.";
+    }
     throw error;
   }
 }

package/cli/package-manager.mjs

@@ -0,0 +1,31 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+// Only generate a runnable command for a validated, exact package-manager pin.
+// Never interpolate arbitrary package.json content into a suggested shell command.
+export async function packageManager(directory) {
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(join(directory, "package.json"), "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return { declared: null, installCommand: null };
+    return {
+      declared: null,
+      installCommand: null,
+      error:
+        "Cannot read package.json. Restore valid JSON before installing dependencies.",
+    };
+  }
+  const declared =
+    typeof pkg?.packageManager === "string" ? pkg.packageManager : null;
+  const pin =
+    /^(pnpm|npm)@(\d+\.\d+\.\d+(?:-[\w.-]+)?)(?:\+sha\d+\.[a-fA-F0-9]+)?$/.exec(
+      declared ?? "",
+    );
+  if (!pin) return { declared, installCommand: null };
+  const [, name, version] = pin;
+  const install = name === "pnpm" ? "install --frozen-lockfile" : "ci";
+  const runner = `npx --yes ${name}@${version}`;
+  return { declared, installCommand: `${runner} ${install}` };
+}