@domino-sdk/relay-cli 0.6.0 → 0.8.0

package/cli/project.mjs

@@ -1,3 +1,7 @@
+import {
+  pointLedgerDeclarationSchema,
+  collectionSlotDeclarationSchema,
+} from "@domino-sdk/relay";
 import { hostedAppSchema } from "@domino-sdk/relay-cli";
 import { readFile, writeFile, mkdir, access } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
@@ -84,16 +88,8 @@ export const projectSchema = z
       )
       .max(50)
       .default([]),
-    collections: z
-      .array(
-        z
-          .object({
-            id: z.string().regex(/^[\w-]+$/),
-            title: z.string().min(1).max(120),
-          })
-          .strict(),
-      )
-      .default([]),
+    pointLedgers: z.array(pointLedgerDeclarationSchema).max(50).default([]),
+    collections: z.array(collectionSlotDeclarationSchema).default([]),
     supportedInteractions: z
       .array(z.enum(["photo", "quiz", "claim", "staff", "automatic"]))
       .min(1)
@@ -129,7 +125,28 @@ export async function readJson(path) {
 
 async function loadProject(path) {
   const raw = await readJson(path);
-  const config = projectSchema.parse(raw);
+  const parsed = projectSchema.safeParse(raw);
+  if (!parsed.success) {
+    const details = parsed.error.issues.map((issue) => ({
+      code:
+        issue.path[0] === "collections"
+          ? "COLLECTION_DECLARATION_INVALID"
+          : "MANIFEST_INVALID",
+      severity: "error",
+      file: path,
+      path: issue.path,
+      message: issue.message,
+      suggestion:
+        issue.path[0] === "collections"
+          ? "Run domino migrate to inspect collection keys. Keep the original id value as key."
+          : "Correct this field in relay.json, then rerun domino check --json.",
+    }));
+    throw Object.assign(new Error(`Invalid project manifest: ${path}`), {
+      code: "MANIFEST_INVALID",
+      details,
+    });
+  }
+  const config = parsed.data;
   const scopeSources = Object.fromEntries(
     ["apiUrl", "organization", "project", "environment"].map((key) => [
       key,
@@ -165,13 +182,14 @@ async function loadProject(path) {
   return { path, config, scopeSources };
 }
 
-export async function findProject(path) {
-  if (path) return loadProject(resolve(path));
+export async function findProjectFile(path) {
+  if (path) return resolve(path);
   let dir = process.cwd();
   while (true) {
     const path = join(dir, "relay.json");
     try {
-      return await loadProject(path);
+      await access(path);
+      return path;
     } catch (error) {
       if (error.code !== "ENOENT") throw error;
     }
@@ -179,6 +197,10 @@ export async function findProject(path) {
     dir = dirname(dir);
   }
 }
+export async function findProject(path) {
+  const file = await findProjectFile(path);
+  return file ? loadProject(file) : null;
+}
 
 export async function bundleProject(project, { allowEmpty = false } = {}) {
   const quests = await discoverEntries(project, "quests");
@@ -228,6 +250,7 @@ export async function bundleProject(project, { allowEmpty = false } = {}) {
     types.push({ ...artifact, provider: type.provider });
   }
   const catalog = {
+    pointLedgers: project.config.pointLedgers,
     types,
     collections: project.config.collections,
     ...(project.config.supportedInteractions
@@ -250,6 +273,7 @@ export async function bundleProject(project, { allowEmpty = false } = {}) {
   );
   if (
     !allowEmpty &&
+    !catalog.pointLedgers.length &&
     !referrals.length &&
     !releases.length &&
     !leaderboards.length &&
@@ -258,7 +282,7 @@ export async function bundleProject(project, { allowEmpty = false } = {}) {
     !catalog.supportedInteractions
   )
     throw new Error(
-      "No resources configured. Add files matching discover in relay.json, or configure quests, questTypes, leaderboards, referrals, collections, or supportedInteractions.",
+      "No resources configured. Add files matching discover in relay.json, or configure quests, questTypes, pointLedgers, leaderboards, referrals, collections, or supportedInteractions.",
     );
   return { releases, leaderboards, referrals, ...catalog };
 }

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

@@ -20,11 +20,55 @@ curl -fsS https://snippets.domino.run/r/registry.json
    ```
 
    Preserve existing customized files; adapt those in place when the recipe is already installed. Use the project's package manager equivalent when it is not pnpm.
-3. Read the installed `docs/snippets/<name>.md`. Adapt the source to the requested behavior, choose unique IDs for new quests, and configure settings, rewards, and verification prerequisites. Keep existing quest IDs stable and verification source out of the browser bundle.
+3. Read the installed `docs/snippets/<name>.md`. Adapt the source to the requested behavior, choose unique authoring keys for new quests, and configure settings, rewards, and verification prerequisites. Keep existing authoring keys stable and verification source out of the browser bundle.
 4. Confirm the source matches `discover` in `relay.json`. Move it to a matching directory for custom layouts, or add an explicit entry if discovery is disabled or unsupported by the installed CLI. Run the project's checks and `domino build --json`, then exercise the requested participant behavior using the verification workflow in the Domino skill. Installation only copies source; publication is a separate step below.
 
 If no recipe fits or the catalog is unavailable, author with the installed SDK declarations and existing project examples. Report an unavailable catalog as unchecked, rather than claiming no matching snippet exists. Snippets are editable starting points; check compatibility with the project's installed SDK before changing package versions.
 
+## Upgrade existing authoring code
+
+Existing `id` properties on authoring declarations still work as aliases for `key`. They name source declarations; they do not choose server resource IDs. Keep the original value when migrating. Providing different `id` and `key` values fails. New code should use `key`.
+
+Run these commands from the project directory after upgrading the SDK and CLI:
+
+```sh
+domino migrate
+domino migrate --write
+domino check --json
+```
+
+`migrate` previews a diff without writing files or contacting Domino. `--write` applies the changes. It renames authoring identity properties and collection declarations, and proposes `pointLedgers` entries for statically known ledger keys. Existing server IDs are not renamed. Review proposed ledger names before deploying. You may keep referencing a ledger that already exists remotely without adding a local declaration.
+
+The migration follows configured and discovered entry modules and their local imports. It recognizes SDK import aliases and namespace imports, preserves nested tier and rule IDs, and does not execute source. Indirect objects, spreads, and dynamic ledger references receive manual instructions. It does not rewrite dependencies, unconfigured source, or files outside the project directory. Resolve conflicts before applying; a conflicting identity prevents all writes. Repeating the command after a completed migration produces no further diff.
+
+`domino check --json` includes a `diagnostics` array with `code`, `severity`, `file`, `line`, `column`, `message`, and `suggestion` for source findings. `AUTHORING_ID_DEPRECATED` is a non-blocking migration warning. `AUTHORING_IDENTITY_CONFLICT` and `AUTHORING_KEY_MISSING` fail the check. Dynamic references and missing local ledger declarations are warnings because the selected ledger may already exist remotely. Manifest validation errors appear on stderr with `code: "MANIFEST_INVALID"` and field paths in `details`. Agents should follow the reported suggestion and rerun the check; never invent a replacement key for an existing resource.
+
+## Resource IDs and authoring keys
+
+Use the IDs returned by Domino when referencing projects, quests, point ledgers, rewards, and inventory items. Creation requests do not accept a new resource's ID. The server assigns an opaque, prefixed ID. Existing stored IDs remain valid after upgrade.
+
+In source, give `defineQuest`, `defineQuestType`, `defineTieredReward`, `defineLeaderboard`, and `defineReferral` a stable `key`. Collection declarations in `relay.json` also use `key`. Domino maps each key to a resource ID within the project and environment. Redeploying the same key updates the same resource; changing the key creates another resource. Display titles are independent of identity. Quest prerequisites can reference authoring keys, and participant quest and collection lookups accept keys or returned IDs.
+
+Create point ledgers in Console **Rewards → Point ledgers → New ledger**, with `management.points.createLedger({ name, description })`, or declare them in `relay.json`:
+
+```json
+{
+  "pointLedgers": [
+    { "key": "community", "name": "XP", "description": "Lifetime progress" }
+  ]
+}
+```
+
+Merge this property into the existing manifest. Then use `points("community", 100)` or the returned ledger ID. A deployment previews ledger declarations with the other resources and publishes them together. An unknown ledger reference fails validation instead of creating a balance. `management.points.ledgers()` lists the available ledgers.
+
+For a selectable ledger, use `settings.resource({ label: "Point ledger", source: pointLedgers() })`. Import `pointLedgers` from `@domino-sdk/relay/authoring`. An empty selection keeps a quest inactive until an operator chooses a ledger.
+
+The management SDK's `createProject`, `points.createLedger`, `inventory.createItem`, and `catalog.allocateQuest` helpers generate an `actionId` when omitted. They retry one uncertain network or server failure with that same key. If creation still fails, `CreationError.actionId` lets you retry the same input explicitly. For retries across process restarts, generate and persist an action ID before calling the helper. Direct HTTP creation requests still require `actionId`.
+
+Use `actionId` to make a creation request retryable. Reuse the same action ID and payload after an uncertain response; a different payload with the same action ID fails. The action ID is not the resource ID. Provider subjects, observation delivery IDs, completion keys, and nested quiz, tier, budget, and referral-rule keys keep their own scopes.
+
+For pickup inventory, supply a label for each new variant and omit `item`; saving returns its assigned item ID. Reuse that ID to share existing stock. For standalone stock, type a name in the Console Stock item picker and choose **Create item “NAME”**, or use `management.inventory.createItem({ name })`. Both return a server-assigned item ID. Stock adjustments accept existing item IDs only.
+
 ## Resource and date/time settings
 
 Use `settings.resource({ label, source: discord.channels() })` for a Discord channel selector. Import `discord` alongside `settings` from `@domino-sdk/relay/authoring`. The connected project integration supplies the server; never add a guild ID setting. Filter with `discord.channels({ types: ["announcement"] })` when only announcement channels qualify. The default includes text and announcement channels. Resource values are stable IDs, not labels.
@@ -53,13 +97,13 @@ Fixture providers simulate verification. `workers-ai` requires a configured serv
 
 ## Leaderboard definitions
 
-Default-export `defineLeaderboard({ id, title, balance, score, access, group })` from `@domino-sdk/relay/authoring`. Add `{ "entry": "src/leaderboard.ts" }` to `leaderboards` in `relay.json`; optional `exportName` selects a named export. Deploy through the existing project bundle workflow. Definitions and standings previews appear in Console Releases before live publication.
+Default-export `defineLeaderboard({ key, title, balance, score, access, group })` from `@domino-sdk/relay/authoring`. Add `{ "entry": "src/leaderboard.ts" }` to `leaderboards` in `relay.json`; optional `exportName` selects a named export. Deploy through the existing project bundle workflow. Definitions and standings previews appear in Console Releases before live publication.
 
 ```ts
 import { defineLeaderboard } from "@domino-sdk/relay/authoring";
 
 export default defineLeaderboard({
-  id: "weekly",
+  key: "weekly",
   title: "Weekly contributors",
   balance: "community",
   access: "participants",
@@ -84,7 +128,7 @@ import { createManagementClient } from "@domino-sdk/relay-cli";
 const management = createManagementClient({
   baseUrl: "https://relay.domino.run",
   organization: "my-organization",
-  project: "community",
+  project: process.env.DOMINO_PROJECT_ID!,
   environment: "test",
   getToken: async () => process.env.DOMINO_MANAGEMENT_KEY!,
 });
@@ -167,3 +211,5 @@ Author the entry quest with `manual({ actor: "staff" })` and no evidence input.
 ## Hosted server applications
 
 Quest discovery and private resource artifacts work the same way for static and Worker apps. Keep quest definitions outside the public asset directory. For server-rendered applications, configure the Worker module output and browser asset output separately in `relay.json`; see [hosted apps](hosted.md). With `app.routing="transparent"`, hosting reserves no paths. Omitting the setting preserves legacy routing. The starter owns its `/relay/*` proxy as ordinary application code; custom handlers can take precedence.
+
+Ledger names can repeat. Edit names and descriptions in Console, or call `management.pointLedgers.save({ id, name, description })` to update an existing ledger. `settings.pointLedger` also renders a searchable picker; existing text settings need a new type version and instance upgrade.

package/cli/skills/domino/references/existing-app.md

@@ -6,6 +6,8 @@ Inspect the app's framework, package manager, workspace boundaries, authenticati
 
 Use the Domino project selected by the user. If no remote project exists, create it in Console. `domino create` provisions a hosted repository and is not the existing-app integration path.
 
+Use the project ID returned by Console. Domino assigns it when the project is created; the project name is a separate display label. Do not invent a project ID or derive it from the name.
+
 From the intended package or project root, run `domino init --project <id>` to create relay.json and RELAY.md. Init verifies access and does not install packages or generate sample quests. If these files already exist, inspect the existing connection and continue from it. Init deliberately refuses to overwrite them.
 
 Run `domino agents install` to install this guidance for both Codex and Claude, or select one with `--agent codex` or `--agent claude`. The installer leaves existing AGENTS.md and CLAUDE.md files intact. It can resume missing files, but stops before replacing customized Domino guidance.
@@ -21,3 +23,5 @@ An organization administrator creates an identity integration in Console Setting
 Mount the adapter at `/relay/*` and use `createBrowserRelayClient({ baseUrl: "/relay" })`. Verify a signed-in session, one participant action, and that logging out of the application removes access. The adapter checks application authentication on every request and derives project scope from the integration key. No custom fetch wrapper or browser project headers are needed.
 
 Read [authoring](authoring.md) when adding quests or collection slots. Run the app's normal checks and development server. Use its existing preview deployment process when available. `domino deploy` publishes Domino behavior; it does not deploy the app. `domino stage` requires a supported Domino-hosted static repository, so it is not a general deployment command for existing apps.
+
+When upgrading an existing integration, run `domino migrate` to inspect authoring changes, apply them with `domino migrate --write`, and run `domino check --json`. Keep existing authoring names. Legacy `id` remains accepted as an alias for `key`; do not recreate projects or replace stored IDs to perform this upgrade. See [authoring upgrades](authoring.md#upgrade-existing-authoring-code) for diagnostics and manual cases.

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

@@ -126,3 +126,7 @@ Call `relay.me.rewardDeliveries()` to read role deliveries for the signed-in mem
 ## Removed demo shortcuts
 
 `auth.demoSignIn` and the campaign template endpoint are no longer supported. Use managed sign-in or a registered identity integration. The platform participant `me.linkPass` route remains unconfigured. An app can handle that route itself and verify a pass on its server, then call `POST /management/v1/passes/verify` with a server-only management key carrying `confirm` permission. Send `{ provider, event, subject, member, quest }` and the usual organization, project, and environment headers. Resolve the member from the authenticated participant session, never from browser input. The quest must be staff-confirmed with no evidence. Relay binds ownership uniquely per provider/event in that project, preserves the authenticated management actor, and retries the same entry attempt. There is no built-in event-code verifier.
+
+## Resource references
+
+Store returned resource IDs as opaque strings. A quest's `quest` field and a collection's `id` are server-assigned. Authored resources also expose their stable `key`; `relay.quests.get(key)` and `relay.quests.collection(key)` resolve it. Console-created quests have no authoring key, so use their returned IDs. Continue supplying stable action IDs for retries; those values do not become resource IDs.

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

@@ -8,7 +8,7 @@ Run `domino capabilities referrals --json` against the installed release. Native
 import { defineReferral, points } from "@domino-sdk/relay/authoring";
 
 export default defineReferral({
-  id: "friends",
+  key: "friends",
   title: "Invite friends",
   qualification: { kind: "quest", quest: "welcome" },
   rewards: { inviter: [points("community", 25)] },