@domino-sdk/relay-cli 0.5.0 → 0.7.0

package/cli/prompts.mjs

@@ -0,0 +1,92 @@
+import { createInterface } from "node:readline/promises";
+
+export function canPrompt(
+  options,
+  input = process.stdin,
+  output = process.stderr,
+) {
+  return (
+    !options.json &&
+    options.interactive !== false &&
+    !process.env.CI &&
+    Boolean(input.isTTY && output.isTTY)
+  );
+}
+
+export async function promptText(
+  message,
+  {
+    defaultValue,
+    validate = (value) => (value ? undefined : "Enter a value."),
+  } = {},
+  { input = process.stdin, output = process.stderr } = {},
+) {
+  const prompt = createInterface({ input, output });
+  const controller = new AbortController();
+  const cancel = () => controller.abort();
+  prompt.on("SIGINT", cancel);
+  prompt.on("close", cancel);
+  try {
+    for (;;) {
+      const answer = (
+        await prompt.question(
+          `${message}${defaultValue === undefined ? "" : ` [${defaultValue}]`} (q to cancel): `,
+          { signal: controller.signal },
+        )
+      ).trim();
+      if (answer.toLowerCase() === "q") throw new Error("Selection cancelled.");
+      const value = answer || defaultValue || "";
+      const error = await validate(value);
+      if (!error) return value;
+      output.write(`${error}\n`);
+    }
+  } catch (error) {
+    if (controller.signal.aborted) throw new Error("Selection cancelled.");
+    throw error;
+  } finally {
+    prompt.close();
+  }
+}
+
+export async function promptSelect(
+  title,
+  choices,
+  { input = process.stdin, output = process.stderr } = {},
+) {
+  if (!choices.length)
+    throw new Error(`No choices available for ${title.toLowerCase()}.`);
+  output.write(`${title}:\n`);
+  choices.forEach((choice, index) =>
+    output.write(`  ${index + 1}. ${choice.label}\n`),
+  );
+  const answer = await promptText(
+    "Selection number",
+    {
+      validate: (value) =>
+        /^\d+$/.test(value) &&
+        Number(value) >= 1 &&
+        Number(value) <= choices.length
+          ? undefined
+          : `Enter a number from 1 to ${choices.length}.`,
+    },
+    { input, output },
+  );
+  return choices[Number(answer) - 1].value;
+}
+
+export async function confirmAction(options, details, io = {}) {
+  if (options.yes || !canPrompt(options, io.input, io.output)) return;
+  const output = io.output ?? process.stderr;
+  output.write(`${details}\n`);
+  const answer = await promptText(
+    "Continue?",
+    {
+      defaultValue: "no",
+      validate: (value) =>
+        /^(y|yes|n|no)$/i.test(value) ? undefined : "Enter yes or no.",
+    },
+    io,
+  );
+  if (!/^y(es)?$/i.test(answer))
+    throw new Error("Operation cancelled. Nothing was published.");
+}

package/cli/runtime.mjs

@@ -1,13 +1,15 @@
 import { findProject } from "./project.mjs";
+import { formatResult } from "./output.mjs";
+import { projectConnection } from "./select-project.mjs";
 import { apiUrl } from "./connection.mjs";
 
 // Share scope resolution and output across commands; build and HTTP modules stay independent.
-export function action(handler) {
+export function action(handler, { projectScope = false, environment } = {}) {
   return async (...args) => {
     const command = args.at(-1);
     const options = command.optsWithGlobals();
     const project = await findProject(options.config);
-    const connection = {};
+    let connection = {};
     const scopeSources = {};
     for (const key of ["apiUrl", "organization", "project", "environment"]) {
       const env =
@@ -27,19 +29,19 @@ export function action(handler) {
       !["test", "live"].includes(connection.environment)
     )
       throw new Error("Environment must be test or live.");
+    if (environment) connection.environment = environment;
+    if (projectScope) connection = await projectConnection(connection, options);
     const result = await handler(
       { options, project, connection, scopeSources },
       ...command.processedArgs,
     );
-    console.log(JSON.stringify(result, null, options.json ? undefined : 2));
+    console.log(formatResult(command.name(), result, options));
   };
 }
 
 export async function readStdin() {
   if (process.stdin.isTTY)
-    throw new Error(
-      "Pipe input to stdin; interactive prompts are not supported.",
-    );
+    throw new Error("Pipe input to stdin for this option.");
   let input = "";
   for await (const chunk of process.stdin) input += chunk;
   return input;

package/cli/select-project.mjs

@@ -0,0 +1,64 @@
+import { canPrompt, promptSelect } from "./prompts.mjs";
+import { request } from "./connection.mjs";
+
+export function promptProject(projects, io) {
+  return promptSelect(
+    "Choose a project",
+    projects.map((item) => ({
+      label: `${item.name && item.name !== item.project ? `${item.name} (${item.project})` : item.project}  [${item.environments.join(", ")}]${item.organization ? ` • ${item.organization}` : ""}`,
+      value: item,
+    })),
+    io,
+  );
+}
+
+export async function projectConnection(connection, options) {
+  if (connection.project) return connection;
+  const access = await request(connection, "/access");
+  const selected = await selectProject(access, connection, options);
+  return {
+    ...connection,
+    project: selected.project,
+    organization: selected.organization ?? access.organization,
+  };
+}
+
+export async function selectProject(
+  access,
+  connection,
+  options,
+  { interactive = canPrompt(options), choose = promptProject } = {},
+) {
+  const environment = connection.environment ?? "test";
+  const projects = access.projects.filter(
+    (item) =>
+      item.environments.includes(environment) &&
+      (!connection.organization ||
+        !item.organization ||
+        item.organization === connection.organization),
+  );
+  if (connection.project) {
+    const matches = projects.filter(
+      (item) => item.project === connection.project,
+    );
+    if (matches.length > 1)
+      throw new Error(
+        "This project identifier exists in multiple organizations. Select one with --organization ID.",
+      );
+    const selected = matches[0];
+    if (!selected)
+      throw new Error(
+        `No access to project ${connection.project} in ${environment}. Run domino whoami to list accessible projects.`,
+      );
+    return selected;
+  }
+  if (!projects.length)
+    throw new Error(
+      `No accessible projects in ${environment}. Create a project in Console or select another organization with --organization ID.`,
+    );
+  if (interactive) return choose(projects);
+  if (projects.length === 1) return projects[0];
+  throw new Error(
+    "Select an accessible project with --project ID. Run domino whoami to list projects, or run this command in a terminal to choose interactively.",
+  );
+}

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

@@ -25,6 +25,24 @@ curl -fsS https://snippets.domino.run/r/registry.json
 
 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.
 
+## Point ledger settings
+
+Use `settings.pointLedger({ label: "Point ledger", default: "community" })` for a points balance setting. The value is a stable ledger ID, passed to `points(settings.balance, settings.points)`. Console renders a searchable ledger picker. Create and edit names and descriptions in **Rewards → Point ledgers**, or use `management.pointLedgers.save({ id, name, description })` from a trusted backend. Names need not be unique. Never use a display name as an accounting key.
+
+Existing balance keys retain their IDs and history. Existing `settings.text` declarations should be changed to `settings.pointLedger` and deployed as a new type version; Console supports preserving values when upgrading from text to a ledger setting. Upgrade existing instances to that version to show the picker. Ledger metadata is project/environment-scoped and is not part of a deployment bundle; save the same ID in each target environment when sharing authored definitions.
+
+## 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.
+
+Omit the resource default until the operator chooses a value in Console. Its empty string represents missing configuration. Code-authored quests publish paused when any resource setting is empty. Publishing a configured value activates the code-authored quest; clearing it pauses the quest again. Console-created quests must have every required resource configured before activating. Existing operation-level pauses remain independent.
+
+Use `settings.datetime({ label, default: "2026-09-21T00:00:00+02:00" })` for an exact cutoff instant. Values normalize to UTC ISO timestamps. Console displays date and time with the operator's local timezone explicitly labeled. Offset-free timestamps and invalid calendar dates are rejected. This is not a date-only setting.
+
+Resource selections are checked on the backend for Console and CLI publication, including final deployment publication after preview. The selected resource must belong to the current connected integration and be usable by its bot. Lookup caches do not replace publication validation. A temporary provider outage rejects the new publication without changing the existing release. Deleted selections remain visible for the operator to replace.
+
+Replacing a text field with a resource or datetime field preserves Console overrides when their values pass the new validation. Keep the field key stable. Invalid overrides must be updated or reset explicitly; they are not silently discarded.
+
 ## Publish the authored resources
 
 Source owns reusable quest definitions, collection slots, and deployment defaults. Console owns operator-created quest instances, their placement, and custom setting values. Keep identifiers stable. Registering a new reusable type version does not upgrade existing instances.
@@ -103,16 +121,51 @@ For `defineReferral`, invitation qualification, fixed rewards, and selective inv
 
 ## Verify Discord membership
 
-Use the `discord-membership` snippet for a server membership check, with an optional role requirement. An organization administrator first connects the project's server in Console **Integrations**. Declare `integrations: ["discord"]` on the quest and call `await ctx.discord.member()` inside `evaluate`. There is no server ID setting. The result is `null` for absent membership, or `{ roles, joinedAt, pending }`. Author code decides eligibility and the quest's declared rewards.
+Use the `discord-membership` snippet for a server membership check, with an optional role requirement. An organization administrator first connects the project's server in Console **Integrations**. Declare `integrations: ["discord"]` on the quest and call `await ctx.discord.member()` inside `evaluate`. There is no server ID setting. The result is `null` for absent membership, or `{ userId, roles, joinedAt, pending, nickname, displayName, boostingSince }`. Author code decides eligibility and the quest's declared rewards.
 
 The platform supplies a read-only client bound to the project's configured server and the participant's Discord identity. Quest code cannot supply a user ID, server ID, access token, or arbitrary URL. Discord permission failures and outages fail verification; they are not evidence that the participant is ineligible. Bot access problems appear in Console Integrations. Participants signing in with Discord need no extra permission flow; members using another login link their Discord identity once.
 
 Successful reads, including absent membership, are stored with the account revision, integration revision, server, and observation time. Recovery reuses captured facts. Changing either connection invalidates unfinished reads. After a failed attempt, start a new submission if a connection changed. Membership screening (`pending`) and role requirements remain author decisions.
 
-The campaign starter includes participant identity controls. Existing apps use the same APIs through `createParticipantBackend`; see [participant API](participant-api.md#connected-accounts). The managed bot is configured by the platform, never by a quest author. Do not invent message, reaction, or write capabilities: `member` is the only Discord operation currently available. X remains unavailable.
+The campaign starter includes participant identity controls. Existing apps use the same APIs through `createParticipantBackend`; see [participant API](participant-api.md#connected-accounts). The managed bot is configured by the platform, never by a quest author. The injected Discord client supports `member()` and `message({ channelId, messageId })`. Automatic reaction additions arrive separately through observations; see the observation-triggered quest guidance below. Discord role grants are declared rewards, never evaluator writes. X remains unavailable.
 
 The release's `provider` setting selects the photo-check backend used by `ctx.review.photo`; it does not select the evaluator for Discord, quizzes, or other authored checks. `humanReview` allows quest code to return a review decision. It does not automatically route Discord failures to staff. The Discord membership snippet returns accept or reject decisions and leaves provider outages as errors.
 
+## Observation-triggered and repeatable quests
+
+Use `automatic({ source, type })` for authenticated external activity. `automatic()` without arguments retains prerequisite-based triggering. Manual and automatic triggers are exclusive. Automatic quests never expose participant claim or retry actions. Set `visibility: "hidden"` to omit a quest from participant lists while it continues earning rewards.
+
+Choose `once()` for one successful completion per participant, or `keyed(ctx => key)` for one per author-defined key. The key is scoped to the project, quest, and participant. It must remain stable across deployments. For announcement reactions use the message ID; for a daily manual quest derive the UTC date from `ctx.eligibleAt`. `completed(quest)` still means ever completed.
+
+An observation has `id`, `source`, `type`, `member`, `occurredAt`, `receivedAt`, and JSON `data`. The evaluator reads `ctx.observation`, which is null for manual and prerequisite-triggered work. `ctx.eligibleAt` is fixed when admitted. The source delivery ID deduplicates transport; it is not the completion key. Only an accepted completion consumes a key. Replaying rejected evidence does not reconsider it, but a new observation can try an unconsumed key.
+
+Declare budgets with `budget({ id, scope: "member" | "project", period: "day" | "lifetime", limit, cost })`. Use `cost: 1` for completion counts or `cost: { balance: "community" }` for the awarded points amount. Quests can share a named budget, with matching scope, period, and limit. All budget spends, the completion key, and rewards commit together. UTC-day budgets use the admitted eligibility day. An exhausted observation is rejected permanently; it does not roll into tomorrow. Concurrent valid awards commit in whichever order wins the transaction.
+
+Admission pins the release and prerequisite result. Pausing stops new admissions while accepted work finishes. Republication does not clear successful completion keys. Observation execution errors retry with capped backoff and retain the original evidence and release. Points accumulate per completion. Tier rewards retain their existing entitlement upgrade behavior; repeating a quest does not create a new consumable handover.
+
+Install `discord-announcements` for the first integration example. The source is `discord`, type `reaction.add`; parse its data with `discordReactionSchema`. Filter the configured channel, emoji, and `messagePublishedAt` in quest code. The Gateway captures the reaction addition; do not query current reactions to cancel it. Unseen replayed events with unknown timing are skipped and reported as coverage gaps. Manual Discord membership remains `ctx.discord.member()`. Use `discordRole(roleId)` for a declared role reward; no arbitrary Discord writes or X verification are exposed.
+
+A trusted customer backend uses a management key with `observe` permission and calls `management.observations.submit({ id, source: "backend:orders", type: "paid", member, occurredAt, data })`. Use the stable delivery ID on retries. The backend supplies a trusted project member ID and action time, never browser claims. Backend sources must start with `backend:` and cannot impersonate `discord`. This endpoint can grant real rewards through matching quests; keep its credential on the server.
+
+## Discord contribution and recognition snippets
+
+Install `discord-contribution` for channel participation and `discord-moderator-recognition` for moderator heart reactions. Use one snippet per capability; customize predicates in code.
+
+- `message.create` targets the message author. Parse with `discordMessageSchema`. Fields are `guildId`, `channelId`, `messageId`, `userId`, nullable `content`, nullable `replyTo`, and `publishedAt`. Bots and webhooks are excluded. Content needs the platform bot's privileged Message Content intent and `DISCORD_MESSAGE_CONTENT=true`; treat null as unavailable evidence.
+- `reaction.add` targets the reactor. `reaction.received` targets the message author. Parse either payload with `discordReactionSchema`, which adds nullable `messageAuthorId` and `actorRoles`. Authorization roles come from capture time.
+- `observation.member` is the beneficiary; optional `observation.actor` is `{ provider, subject }` identifying the external actor. The beneficiary owns prerequisites, completion keys, budgets and rewards. A moderator need not link a Relay account. Reject self-tips and key by message ID to prevent repeated recognition rewards.
+- `ctx.discord.message({ channelId, messageId })` is server-scoped and returns null for deleted messages. For manual authorship checks, compare message `userId` to a non-null `userId` from `ctx.discord.member()`. Older captured member facts can return null; fail closed. For automatic events, use the trusted observation identity. Captured reads survive evaluation retries.
+
+Daily budgets are caps, not counters or streaks. Multi-action progress remains a separate design proposal.
+
+## Discord role rewards
+
+Import `discordRole` from `@domino-sdk/relay/authoring`. Declare `rewards: [discordRole(roleId)]`. Install `discord-role-reward` for a complete prerequisite-gated example. Its resource setting uses `discord.roles({ assignable: true })`; ordinary eligibility roles use `discord.roles()`.
+
+The ledger commits one durable delivery per completion and role. Delivery retries separately from quest evaluation using an idempotent role assignment. Never write to Discord inside evaluate. Pending delivery is bound to the original account/server, so reconnecting a different identity cannot redirect it. Restoring the original connection and permissions permits recovery. The bot needs Manage Roles and a role above the target. Managed/everyone roles cannot be reward roles.
+
+Use `relay.me.rewardDeliveries()` for the current member or `management.rewardDeliveries(member?)` for operator inspection. Lists contain the latest 500 deliveries in the selected scope. Each record contains quest, completion, role, status, attempts and retry details. Participant UI should show pending/granted status without operator error details. Referral reward definitions still accept points and tier rewards; qualify a role-granting quest if composing them.
+
 ## Entry after app-owned pass verification
 
 Author the entry quest with `manual({ actor: "staff" })` and no evidence input. The participant app verifies its event pass on its server, resolves the signed-in member, and calls `POST /management/v1/passes/verify` with `{ provider, event, subject, member, quest }`. Use a server-only management key with `confirm` permission in the intended project and environment. Relay records unique pass ownership and submits the entry attempt; it does not decide whether the external ticket is valid. Repeating the same pass for the same member reuses the durable attempt. A different member cannot claim that pass, and one member cannot link a second pass for the same provider and event.

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

@@ -21,3 +21,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.
+
+For configurable point rewards, declare the balance setting with `settings.pointLedger` and pass its value to `points`. This gives operators a ledger picker in Console. Ledger IDs stay stable when display names change. Create ledger metadata under **Rewards → Point ledgers**, and use the same ID in each environment targeted by the app's definitions. Existing types using `settings.text` need a new type version and an instance upgrade to adopt the picker.

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

@@ -106,12 +106,23 @@ To choose a different identity, first call `relay.auth.disconnect("discord")`. T
 
 The campaign starter includes these account controls. Apps using `createParticipantBackend` retain their own login and use the same APIs. The adapter preserves OAuth binding cookies and its session during return navigation; the application's own login cookie must also support top-level OAuth returns. If the app session changes during consent, start connection again.
 
-After changing an account or integration during a failed attempt, use the quest controller's `discard()` to clear the saved failed submission, then submit again. The starter labels this **Start a new submission**. Discard is allowed only after a confirmed failed or rejected attempt. It keeps server history and cannot discard an active or accepted attempt. Use `resume()` when the connection has not changed to preserve captured facts.
+After changing an account or integration during a failed attempt, use the quest controller's `discard()` to clear the saved failed submission, then submit again. The starter labels this **Start a new submission**. Discard is allowed after a confirmed failed or rejected attempt. A keyed quest controller can also discard a confirmed accepted browser submission to begin another occurrence. Server history and completion keys remain intact. Active attempts cannot be discarded. Use `resume()` when the connection has not changed to preserve captured facts.
 
 ## Resource IDs
 
 Treat resource IDs as opaque strings and store the complete value. New generated IDs keep their resource prefix, such as `member_`, `session_`, or `attempt_`, followed by 22 random alphanumeric characters. Existing IDs remain valid. Do not parse the suffix as a UUID.
 
+
+## Repeatable and hidden quests
+
+Quest views include `completion`, `completionCount`, and `visibility`. For keyed quests, `completed` means at least one past completion; it is not terminal. Use `availability` for the current action and display the count separately. Filter hidden quests from participant lists and collections, including direct quest routes. The campaign starter does this. Visibility is not an authorization boundary.
+
+Automatic quests use status-only controllers. Never offer a manual claim or retry button, including after a previous completion or execution failure. Their admitted observations recover on the server. Keyed manual controllers may start another submission after a confirmed success; uncertain submissions still resume their original action ID.
+
+## Discord reward delivery
+
+Call `relay.me.rewardDeliveries()` to read role deliveries for the signed-in member. The backend route is `GET /v1/reward-deliveries`; it is available through the participant proxy and existing-app identity integration. The response contains the latest 500 deliveries for this member. Records include `quest`, `completion`, `roleId`, and `status` of `pending` or `delivered`. Display delivery independently of quest completion, since Discord can be temporarily unavailable after points have been awarded. Do not display internal `lastError` details to participants.
+
 ## 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.

package/cli.mjs

@@ -62,6 +62,7 @@ const program = new Command()
     "--config <file>",
     "Use this manifest instead of the nearest relay.json",
   )
+  .option("--no-interactive", "Disable terminal prompts")
   .option("--json", "Emit machine-readable JSON results and errors")
   .addHelpCommand("help [command]", "Display help for a command")
   .configureHelp({ showGlobalOptions: true })
@@ -87,7 +88,7 @@ Run domino doctor --json to see effective scope values and their sources.
 API default: https://relay.domino.run. Init defaults to test.
 Credentials: RELAY_MANAGEMENT_TOKEN > saved token for the API origin.
 Run domino login for browser sign-in. Live publication requires Console.
-Commands never prompt. Results go to stdout; errors go to stderr. Exit 1 on failure.`,
+Missing choices are prompted in a terminal. Deploy and stage ask for confirmation; --yes skips it. Use --no-interactive or --json to disable prompts. Results go to stdout; errors go to stderr. Exit 1 on failure.`,
   )
   .action(() => program.outputHelp());