@domino-sdk/relay-cli 0.1.0 → 0.2.0

package/cli/doctor.mjs

@@ -1,6 +1,7 @@
 import { createRequire } from "node:module";
 import { dirname, join, resolve } from "node:path";
-import { access } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { access, readFile } from "node:fs/promises";
 import { inspectAgentSkills } from "./agents.mjs";
 import { request } from "./connection.mjs";
 
@@ -18,6 +19,54 @@ export async function diagnose({ project, connection, options }) {
         },
   );
 
+  const versions = {
+    cli: JSON.parse(
+      await readFile(new URL("../package.json", import.meta.url), "utf8"),
+    ).version,
+  };
+  let starterRecorded = false;
+  try {
+    const release = JSON.parse(
+      await readFile(join(root, ".domino/release.json"), "utf8"),
+    );
+    starterRecorded = true;
+    for (const pkg of release.packages) {
+      if (!/^\.domino\/[a-z]+\.tgz$/.test(pkg.archive))
+        throw new Error("Unexpected starter archive path.");
+      const digest = createHash("sha256")
+        .update(await readFile(join(root, pkg.archive)))
+        .digest("hex");
+      if (digest !== pkg.sha256 || pkg.version === "0.0.0")
+        throw new Error(
+          "Starter package integrity or version check failed. Restore the verified starter archives.",
+        );
+      versions[pkg.name] = pkg.version;
+    }
+    const lockfile = createHash("sha256")
+      .update(await readFile(join(root, "pnpm-lock.yaml")))
+      .digest("hex");
+    checks.push({
+      id: "starter-integrity",
+      status: "ok",
+      message: "Starter archives match their recorded versions and hashes.",
+      sourceCommit: release.sourceCommit,
+      modifiedSource: release.dirty,
+    });
+    if (lockfile !== release.lockfileSha256)
+      checks.push({
+        id: "starter-lockfile",
+        status: "warning",
+        message:
+          "Dependencies have changed since the starter was verified. Run the app checks and verify a participant action.",
+      });
+  } catch (error) {
+    if (error.code !== "ENOENT" || starterRecorded)
+      checks.push({
+        id: "starter-integrity",
+        status: "error",
+        message: error.message,
+      });
+  }
   const agents = await inspectAgentSkills(root);
   checks.push(
     Object.values(agents).some((status) =>
@@ -84,7 +133,7 @@ export async function diagnose({ project, connection, options }) {
         });
       }
     }
-    if (project.config.app) {
+    if (project.config.app && options.offline) {
       for (const dependency of [
         "@domino-sdk/relay-runtime/package.json",
         "wrangler/package.json",
@@ -111,6 +160,10 @@ export async function diagnose({ project, connection, options }) {
   }
 
   let remoteAccess = "not-checked";
+  let readiness = {
+    development: { status: "not-checked" },
+    staging: "not-checked",
+  };
   if (options.remote && project) {
     try {
       const value = await request(connection, "/access");
@@ -131,6 +184,33 @@ export async function diagnose({ project, connection, options }) {
         message:
           "Management API verified project access. This does not verify participant sign-in or publication permission.",
       });
+      const preflight = await request(connection, "/preflight");
+      readiness = {
+        development: preflight.development,
+        staging: preflight.staging,
+      };
+      if (project.config.app)
+        checks.push({
+          id: "shared-preview",
+          status:
+            preflight.development?.status === "configured" ? "ok" : "error",
+          message:
+            preflight.development?.status === "configured"
+              ? "Shared development hosting is configured. Run domino dev to verify the public connection."
+              : "A Domino operator must configure shared development hosting before domino dev can start.",
+          missing: preflight.development?.missing ?? [],
+        });
+      checks.push(
+        ...preflight.checks.map((check) =>
+          !project.config.app &&
+          ["cloud-builds", "repository", "hosted-test-auth"].includes(
+            check.id,
+          ) &&
+          check.status === "error"
+            ? { ...check, status: "warning" }
+            : check,
+        ),
+      );
     } catch (error) {
       remoteAccess = "failed";
       checks.push({
@@ -143,9 +223,16 @@ export async function diagnose({ project, connection, options }) {
   }
   return {
     directory: root,
+    versions,
     healthy: checks.every((check) => check.status !== "error"),
-    scope: connection,
+    scope: {
+      apiUrl: connection.apiUrl,
+      organization: connection.organization,
+      project: connection.project,
+      environment: connection.environment,
+    },
     agents,
+    readiness,
     remoteAccess,
     preview: project?.config.app
       ? "static-app-configured"

package/cli/skills/domino/SKILL.md

@@ -21,10 +21,14 @@ Choose the reference that matches the task:
 - For integration into an existing codebase, read [existing apps](references/existing-app.md).
 - For quest definitions, reusable types, collections, or publication, read [authoring](references/authoring.md).
 
-If no CLI is installed, use the project's documented package installation path. The current SDK and CLI are private packages distributed with standalone starter archives. Do not invent a public npm install command. Report the missing distribution if no package source is available.
+Before designing referrals, rankings, milestones, or rewards for another participant, run `domino capabilities --json`. Read `domino capabilities <id> --json` for the support boundary. Treat an unlisted capability as unknown and inspect its contract before promising it.
+
+For browser integration and submission recovery, read [participant API](references/participant-api.md). For referral campaigns, read [referrals](references/referrals.md). For startup, staging, or version failures, read [troubleshooting](references/troubleshooting.md).
+
+If no CLI is installed, install `@domino-sdk/relay-cli` and `@domino-sdk/relay` through the app's package manager. Starter archives pin the packages they were verified with; retain their lockfile and `.domino/release.json` when diagnosing compatibility.
 
 ## Verify the result
 
 Run the app's checks and exercise the requested participant action through the running app. Verify the resulting progress or completion state. Keep fixture-provider results distinct from real external verification.
 
-Return the working preview or local URL, what participant action you verified, and any remaining launch dependency. A successful build, installed skill, or healthy doctor result is not proof of participant behavior. Live publication requires human review in Console; hosted staging is a simulation.
+Return the working preview or local URL, what participant action you verified, and any remaining launch dependency. A successful build, installed skill, or healthy doctor result is not proof of participant behavior. Live publication requires human review in Console; hosted staging uses test data and real sign-in.

package/cli/skills/domino/references/hosted.md

@@ -6,7 +6,7 @@ For a failure after remote project creation, inspect the existing project's stat
 
 Install dependencies from the lockfile. The starter includes pinned SDK, CLI, and local-runtime archives in `.domino`; upgrade them through a platform package release rather than modifying their contents. Read CAMPAIGN.md for the owner's brief.
 
-Run `domino dev` for the isolated local runtime and participant app. Local preview identities and fixture providers simulate participation. Keep demonstration content separate from the owner's live catalog.
+Run `domino dev` to start the app with hosted test data and real sign-in. Share its HTTPS preview URL. The CLI prepares the tunnel connector automatically. The URL goes offline when development stops; use `domino stage` for a preview that stays online. Use `domino dev --offline --review-mode fixture-pass` only when you explicitly need an isolated runtime with simulated photo verification. This is not evidence that an external action happened.
 
 Use `domino check` and the app's build script to verify source. Exercise the requested participant flow in the running app before staging.
 
@@ -14,4 +14,4 @@ When the task includes sharing a preview, commit the intended changes and push u
 
 If stage submission loses its response, repeat the printed commit and request ID. Use `domino builds --json` and `domino logs <build-id> --json` to recover progress after disconnecting. A failed build leaves the previous preview active. Report the URL returned for the successful build rather than constructing one.
 
-Cloud staging supports the starter's static app contract. It does not host arbitrary SSR or customer Worker code. Staging uses separate simulated participant data and does not prove live provider readiness. Hosted app live activation remains a separate platform milestone.
+Cloud staging supports the starter's static app contract. It does not host arbitrary SSR or customer Worker code. New staging builds use the same project test data as development and real participant sign-in. Existing previews created before this update remain simulated until rebuilt. Test data does not imply that external provider operations are simulated. Hosted app live activation remains a separate platform milestone.

package/cli/skills/domino/references/participant-api.md

@@ -0,0 +1,28 @@
+# Participant API
+
+Create `createBrowserRelayClient({ baseUrl: "/relay" })` from `@domino-sdk/relay/browser`. The browser client uses cookies and durable submission recovery. The app's server must route `/relay` through the supported participant proxy. Keep management tokens on the server.
+
+## Sign in
+
+Call `relay.auth.providers()` to discover configured providers and email availability. For OAuth, call `relay.auth.start(provider, "sign-in")` and navigate to its returned `url`. For email, call `emailStart(email)`, then `emailVerify(challenge, code)` using the returned challenge. `auth.session()` returns the current session or null. `auth.signOut()` clears the session.
+
+## Display and complete quests
+
+Use `relay.quests.observe(listener)` for the participant's experience. Render the observation's state; dispose the observer when the view unmounts. Read `relay.quests.experience()` for a single snapshot. Open a returned QuestView with `await relay.quests.open(view)`.
+
+The controller's `kind` determines its input:
+
+| Kind   | Action                                                                |
+| ------ | --------------------------------------------------------------------- |
+| claim  | `submit()`                                                            |
+| photo  | `submit(file)` with a File                                            |
+| quiz   | `submit(answers)` with question IDs mapped to choice IDs              |
+| status | Observe only; staff and automatic actions are not participant buttons |
+
+Submission results are `submitted` with an attempt, or `quest-updated` with `latest`, `originalDraft`, and a compatible `draft`. On quest-updated, show the new requirements and ask the participant to submit again. Submission receipt is not completion: verification or human review can still be pending.
+
+## Recover without duplicate actions
+
+`controller.status()` returns `empty`, `needs-review`, `pending` with upload/claim stage, or `submitted` with attempt ID. `needs-review` means the saved draft needs the participant's review, not that a moderator is reviewing it. Use `resume()` to recover a saved operation after reload or a lost response. Use `relay.quests.retry(view)` only for a failed verification attempt. Do not invent a new submission to recover an uncertain response.
+
+Use `relay.me.observeProgress(listener)` for balances, completion and rewards. Dispose observers on unmount. Sign-in changes clear old participant observations. Render 401 as a sign-in request, 403 as an access issue, and transient failures with a retry that preserves the saved draft. IndexedDB and Web Locks must be available for durable browser submissions.

package/cli/skills/domino/references/referrals.md

@@ -0,0 +1,15 @@
+# Build a referral campaign
+
+Read `domino capabilities referrals --json` and `domino capabilities cross-participant-rewards --json` before committing to the reward design. Domino currently supports participant identity, quest completion, points for that participant, and human review. It does not implement referral attribution, inviter-targeted rewards, or queue ranking.
+
+## Supported division of work
+
+Your application backend owns a referral record with `inviteCode`, `inviterMemberId`, `inviteeMemberId`, `project`, `environment`, `createdAt`, and `status`. Generate opaque invite codes server-side. Authenticate both participants through their own sessions. Resolve the invitee from the verified session, never a browser-supplied member ID. Reject self-referrals and enforce a unique invitee attribution within the campaign. Record the terms and time of attribution so retries cannot replace the inviter.
+
+The participant app can capture an invite code from a landing URL and submit it to that backend after sign-in. Treat the captured code as a claim until validated. Your backend can present pending claims to a human reviewer. Keep attribution storage and review in the application until a supported Domino attribution contract exists.
+
+Domino can independently reward the invitee for a supported quest, such as joining the campaign. A Domino quest reward cannot credit the inviter instead. If inviter rewards are mandatory, build and operate an application-owned reward ledger with idempotent grants, or defer that part of the campaign. Do not describe manual attribution as automatic verification. Quiz answers are constrained choice evidence, not a general arbitrary JSON submission API.
+
+## Verify with real people
+
+Have two people sign in through the app and follow an invite. Verify the stored attribution, duplicate handling, and self-referral rejection. Check that the invitee's quest completion persists after refresh. Show the owner precisely which rewards Domino executes and which remain application-owned. A campaign is not complete if promised inviter rewards have no executor.

package/cli/skills/domino/references/troubleshooting.md

@@ -0,0 +1,11 @@
+# Development and staging diagnostics
+
+Start with `domino doctor --json`. Add `--remote` to verify project access, publication permission, hosting configuration and repository readiness. Configuration checks do not prove a successful build or real participant sign-in. If cloud hosting is missing, a Domino operator must configure it; changing quest code will not fix it.
+
+`domino check` runs the app's checks and bundles authored entries. `domino deploy --preview --environment test --json` validates the effective deployment against the server without publishing. Test and live data are separate; test does not imply external provider requests are fake.
+
+`domino stage` preflights hosting before inspecting the commit. If configured, commit and push the app, then stage the exact commit. Use `domino logs <build-id>` for build failures. Retry an uncertain build submission with the original request ID. Rebuilding cannot fix an unavailable hosting service.
+
+For compatibility reports, include `domino --version`, `.domino/release.json`, the lockfile, the command and its error. Exclude credentials and private participant data. Install the starter with its frozen lockfile. `release.json` records package versions and archive hashes; matching version strings alone do not establish that locally modified packages match.
+
+If development reports unknown catalog fields at `/releases/batch`, the CLI is using an obsolete startup contract. Upgrade to the corrected CLI. Complete deployment bundles belong at `/deployments/preview`, followed by `/deployments/publish` using the returned ID. Do not strip fields from a user's bundle as a permanent workaround.

package/cli.mjs

@@ -15,6 +15,7 @@ import { registerApiCommand } from "./cli/commands/api.mjs";
 import { registerStagingCommands } from "./cli/commands/staging.mjs";
 import { registerHostingCommands } from "./cli/commands/hosting.mjs";
 import { registerAgentCommands } from "./cli/commands/agents.mjs";
+import { registerDiscoveryCommands } from "./cli/commands/discovery.mjs";
 import { credentialHelper } from "./cli/git.mjs";
 
 const { version } = JSON.parse(
@@ -28,7 +29,9 @@ if (argv[0] === "credential-helper") {
     process.stdout.write(await credentialHelper(argv[1], input));
     process.exit(0);
   } catch {
-    process.stderr.write("Domino Git authentication failed. Run domino login.\n");
+    process.stderr.write(
+      "Domino Git authentication failed. Run domino login.\n",
+    );
     process.exit(1);
   }
 }
@@ -94,6 +97,7 @@ registerApiCommand(program);
 registerHostingCommands(program);
 registerStagingCommands(program);
 registerAgentCommands(program);
+registerDiscoveryCommands(program);
 
 try {
   await program.parseAsync(argv, { from: "user" });

package/dist/index.d.ts

@@ -32,6 +32,10 @@ declare const stageRequestSchema: z.ZodObject<{
     requestId: z.ZodString;
 }, z.core.$strict>;
 declare const buildIdentitySchema: z.ZodObject<{
+    runtime: z.ZodDefault<z.ZodEnum<{
+        simulation: "simulation";
+        "hosted-test": "hosted-test";
+    }>>;
     id: z.ZodString;
     repository: z.ZodString;
     organization: z.ZodString;
@@ -79,6 +83,37 @@ declare const buildArtifactsSchema: z.ZodObject<{
 }, z.core.$strict>;
 type BuildArtifacts = z.infer<typeof buildArtifactsSchema>;
 
+declare const developmentPreflightSchema: z.ZodObject<{
+    organization: z.ZodString;
+    project: z.ZodString;
+    environment: z.ZodEnum<{
+        test: "test";
+        live: "live";
+    }>;
+    staging: z.ZodEnum<{
+        blocked: "blocked";
+        configured: "configured";
+    }>;
+    development: z.ZodObject<{
+        status: z.ZodEnum<{
+            blocked: "blocked";
+            configured: "configured";
+        }>;
+        missing: z.ZodArray<z.ZodString>;
+        authentication: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    checks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodEnum<{
+            error: "error";
+            ok: "ok";
+        }>;
+        message: z.ZodString;
+        missing: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        issues: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+
 declare const environmentSchema: z.ZodEnum<{
     test: "test";
     live: "live";
@@ -99,7 +134,21 @@ declare const permissionSchema: z.ZodEnum<{
 }>;
 type Permission = z.infer<typeof permissionSchema>;
 declare const rolePermissions: Record<z.infer<typeof roleSchema>, Permission[]>;
+declare const projectSetupSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        new: "new";
+        existing: "existing";
+    }>;
+    brief: z.ZodString;
+}, z.core.$strict>;
 declare const projectSchema: z.ZodObject<{
+    setup: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            new: "new";
+            existing: "existing";
+        }>;
+        brief: z.ZodString;
+    }, z.core.$strict>>;
     id: z.ZodString;
     organization: z.ZodString;
     project: z.ZodString;
@@ -125,6 +174,13 @@ type Project = z.infer<typeof projectSchema>;
 declare const projectInputSchema: z.ZodObject<{
     project: z.ZodString;
     name: z.ZodString;
+    setup: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            new: "new";
+            existing: "existing";
+        }>;
+        brief: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 declare const grantSchema: z.ZodObject<{
     subject: z.ZodString;
@@ -144,6 +200,13 @@ declare const accessSchema: z.ZodObject<{
     admin: z.ZodBoolean;
     local: z.ZodBoolean;
     projects: z.ZodArray<z.ZodObject<{
+        setup: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodEnum<{
+                new: "new";
+                existing: "existing";
+            }>;
+            brief: z.ZodString;
+        }, z.core.$strict>>;
         id: z.ZodString;
         organization: z.ZodString;
         project: z.ZodString;
@@ -365,8 +428,8 @@ declare const pageSchema: z.ZodObject<{
                     none: "none";
                 }>;
                 actor: z.ZodOptional<z.ZodEnum<{
-                    member: "member";
                     staff: "staff";
+                    member: "member";
                 }>>;
             }, z.core.$strict>, z.ZodObject<{
                 kind: z.ZodLiteral<"automatic">;
@@ -554,7 +617,7 @@ declare const pageSchema: z.ZodObject<{
             trigger: {
                 kind: "manual";
                 input: "photo" | "quiz" | "none";
-                actor?: "member" | "staff" | undefined;
+                actor?: "staff" | "member" | undefined;
             } | {
                 kind: "automatic";
             };
@@ -935,8 +998,8 @@ declare const memberDetailSchema: z.ZodObject<{
                     none: "none";
                 }>;
                 actor: z.ZodOptional<z.ZodEnum<{
-                    member: "member";
                     staff: "staff";
+                    member: "member";
                 }>>;
             }, z.core.$strict>, z.ZodObject<{
                 kind: z.ZodLiteral<"automatic">;
@@ -1124,7 +1187,7 @@ declare const memberDetailSchema: z.ZodObject<{
             trigger: {
                 kind: "manual";
                 input: "photo" | "quiz" | "none";
-                actor?: "member" | "staff" | undefined;
+                actor?: "staff" | "member" | undefined;
             } | {
                 kind: "automatic";
             };
@@ -1396,8 +1459,8 @@ declare const memberDetailSchema: z.ZodObject<{
                     none: "none";
                 }>;
                 actor: z.ZodOptional<z.ZodEnum<{
-                    member: "member";
                     staff: "staff";
+                    member: "member";
                 }>>;
             }, z.core.$strict>, z.ZodObject<{
                 kind: z.ZodLiteral<"automatic">;
@@ -1646,7 +1709,7 @@ declare function createManagementClient(options: {
             baseRevision: number;
             releases: ({
                 quest: string;
-                runtimeVersion: 2 | 1;
+                runtimeVersion: 1 | 2;
                 title: string;
                 presentation: {
                     quiz?: {
@@ -2055,7 +2118,7 @@ declare function createManagementClient(options: {
             baseRevision: number;
             releases: ({
                 quest: string;
-                runtimeVersion: 2 | 1;
+                runtimeVersion: 1 | 2;
                 title: string;
                 presentation: {
                     quiz?: {
@@ -2665,7 +2728,7 @@ declare function createManagementClient(options: {
             })[];
             releases: ({
                 quest: string;
-                runtimeVersion: 2 | 1;
+                runtimeVersion: 1 | 2;
                 title: string;
                 presentation: {
                     quiz?: {
@@ -3275,7 +3338,7 @@ declare function createManagementClient(options: {
             })[];
             releases: ({
                 quest: string;
-                runtimeVersion: 2 | 1;
+                runtimeVersion: 1 | 2;
                 title: string;
                 presentation: {
                     quiz?: {
@@ -3679,7 +3742,7 @@ declare function createManagementClient(options: {
             };
             releases: ({
                 quest: string;
-                runtimeVersion: 2 | 1;
+                runtimeVersion: 1 | 2;
                 title: string;
                 presentation: {
                     quiz?: {
@@ -4027,7 +4090,7 @@ declare function createManagementClient(options: {
             };
             releases: ({
                 quest: string;
-                runtimeVersion: 2 | 1;
+                runtimeVersion: 1 | 2;
                 title: string;
                 presentation: {
                     quiz?: {
@@ -4577,6 +4640,10 @@ declare function createManagementClient(options: {
             color: string;
             permissions: ("read" | "publish" | "review" | "confirm" | "handover" | "inventory" | "access")[];
             environments: ("test" | "live")[];
+            setup?: {
+                mode: "new" | "existing";
+                brief: string;
+            } | undefined;
         }[];
     }>;
     createProject: (input: z.infer<typeof projectInputSchema>) => Promise<{
@@ -4589,6 +4656,10 @@ declare function createManagementClient(options: {
         color: string;
         permissions: ("read" | "publish" | "review" | "confirm" | "handover" | "inventory" | "access")[];
         environments: ("test" | "live")[];
+        setup?: {
+            mode: "new" | "existing";
+            brief: string;
+        } | undefined;
     }>;
     page: (page: string, query: Partial<ListQuery> & {
         detail?: string;
@@ -4693,7 +4764,7 @@ declare function createManagementClient(options: {
                 trigger: {
                     kind: "manual";
                     input: "photo" | "quiz" | "none";
-                    actor?: "member" | "staff" | undefined;
+                    actor?: "staff" | "member" | undefined;
                 } | {
                     kind: "automatic";
                 };
@@ -5170,7 +5241,7 @@ declare function createManagementClient(options: {
                 trigger: {
                     kind: "manual";
                     input: "photo" | "quiz" | "none";
-                    actor?: "member" | "staff" | undefined;
+                    actor?: "staff" | "member" | undefined;
                 } | {
                     kind: "automatic";
                 };
@@ -5721,4 +5792,4 @@ declare function createManagementClient(options: {
     }>;
 };
 
-export { type Access, type AuditRecord, type BuildArtifacts, type BuildIdentity, type BuildStatus, type ListQuery, type ManagementPage, type Permission, type Project, accessSchema, accountProfileSchema, assetPathSchema, auditRecordSchema, buildArtifactsSchema, buildIdentitySchema, buildPhaseSchema, buildStatusSchema, commitSchema, createManagementClient, createRepositorySchema, deviceApproveSchema, deviceRedeemSchema, deviceStartSchema, environmentSchema, grantSchema, inventorySchema, memberAccountSchema, memberDetailSchema, memberSchema, metricsSchema, operationInputSchema, operationSchema, pageSchema, permissionSchema, projectInputSchema, projectSchema, querySchema, readinessSchema, repositorySchema, rolePermissions, roleSchema, stageRequestSchema, stockInputSchema, tokenInputSchema, tokenSchema };
+export { type Access, type AuditRecord, type BuildArtifacts, type BuildIdentity, type BuildStatus, type ListQuery, type ManagementPage, type Permission, type Project, accessSchema, accountProfileSchema, assetPathSchema, auditRecordSchema, buildArtifactsSchema, buildIdentitySchema, buildPhaseSchema, buildStatusSchema, commitSchema, createManagementClient, createRepositorySchema, developmentPreflightSchema, deviceApproveSchema, deviceRedeemSchema, deviceStartSchema, environmentSchema, grantSchema, inventorySchema, memberAccountSchema, memberDetailSchema, memberSchema, metricsSchema, operationInputSchema, operationSchema, pageSchema, permissionSchema, projectInputSchema, projectSchema, projectSetupSchema, querySchema, readinessSchema, repositorySchema, rolePermissions, roleSchema, stageRequestSchema, stockInputSchema, tokenInputSchema, tokenSchema };