@domino-sdk/relay-cli 0.6.0 → 0.8.0

package/cli/commands/hosting.mjs

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { Option } from "commander";
 import { connectedDev } from "../connected-dev.mjs";
 import { dirname, resolve } from "node:path";
@@ -20,6 +21,12 @@ export function registerHostingCommands(program) {
     .action(
       action(async ({ project }) => {
         if (!project) throw new Error("No relay.json found.");
+        const { migrationPlan } = await import("../migrate.mjs");
+        const { diagnostics } = await migrationPlan(project.path);
+        if (diagnostics.some((item) => item.severity === "error")) {
+          process.exitCode = 1;
+          return { checked: false, diagnostics };
+        }
         if (project.config.app) {
           try {
             await promisify(execFile)(
@@ -34,10 +41,12 @@ export function registerHostingCommands(program) {
         const bundle = await bundleProject(project, { allowEmpty: true });
         return {
           checked: true,
+          diagnostics,
           quests: bundle.releases.length,
           leaderboards: bundle.leaderboards.length,
           referrals: bundle.referrals.length,
           types: bundle.types.length,
+          pointLedgers: bundle.pointLedgers.length,
           collections: bundle.collections.length,
         };
       }),
@@ -119,13 +128,21 @@ export function registerHostingCommands(program) {
         }
         if (!organization)
           throw new Error("Select an organization with --organization ID.");
+        const created = await request(
+          { ...connection, organization },
+          "/projects",
+          "POST",
+          {
+            actionId: randomUUID(),
+            name,
+          },
+        );
         const scoped = {
           ...connection,
           organization,
-          project: name,
+          project: created.project,
           environment: "test",
         };
-        await request(scoped, "/projects", "POST", { project: name, name });
         const repository = await request(scoped, "/repository", "POST", {
           starter: "campaign",
         });

package/cli/commands/project.mjs

@@ -4,16 +4,19 @@ import { action } from "../runtime.mjs";
 import { confirmAction } from "../prompts.mjs";
 import { selectProject } from "../select-project.mjs";
 import { request } from "../connection.mjs";
-import { initialize, bundleProject } from "../project.mjs";
+import { initialize, bundleProject, findProjectFile } from "../project.mjs";
+
+import { formatResult } from "../output.mjs";
 
 function summary(value) {
   return {
     deployment: value.id,
     revision: value.revision ?? value.baseRevision,
     releases: value.releases.map(
-      ({ id, quest, title, createdAt, configuration, values }) => ({
+      ({ id, quest, key, title, createdAt, configuration, values }) => ({
         id,
         quest,
+        key,
         title,
         createdAt,
         deploymentDefaults: configuration.defaults,
@@ -24,10 +27,12 @@ function summary(value) {
     ),
     types: value.types.map((t) => ({
       id: t.id,
+      key: t.key,
       version: t.version,
       title: t.definition.title,
     })),
     collections: value.collections,
+    pointLedgers: value.pointLedgers,
     supportedInteractions: value.supportedInteractions,
     leaderboards: value.leaderboards,
     referrals: value.referrals,
@@ -87,7 +92,7 @@ ${detail}`,
     );
     if (options.preview) return { status: "preview", ...summary(preview) };
     await confirmPublication(
-      `Deployment ${preview.id}: ${preview.releases.length} quests, ${preview.types.length} types, ${preview.collections.length} collections, ${preview.leaderboards.length} leaderboards, ${preview.referrals.length} referral programs.`,
+      `Deployment ${preview.id}: ${preview.releases.length} quests, ${preview.types.length} types, ${preview.collections.length} collections, ${preview.pointLedgers?.length ?? 0} point ledgers, ${preview.leaderboards.length} leaderboards, ${preview.referrals.length} referral programs.`,
     );
     return publish(connection, preview.id);
   }
@@ -98,6 +103,7 @@ ${detail}`,
       file: options.out,
       quests: payload.releases.length,
       types: payload.types.length,
+      pointLedgers: payload.pointLedgers.length,
       collections: payload.collections.length,
       leaderboards: payload.leaderboards.length,
       referrals: payload.referrals.length,
@@ -107,6 +113,22 @@ ${detail}`,
 }
 
 export function registerProjectCommands(program) {
+  program
+    .command("migrate")
+    .description(
+      "Preview an offline authoring migration without changing resource names",
+    )
+    .option("--write", "Apply the displayed source and manifest changes")
+    .action(async (_, command) => {
+      const options = command.optsWithGlobals();
+      const path = await findProjectFile(options.config);
+      if (!path) throw new Error("No relay.json found. Pass --config FILE.");
+      const { migrate } = await import("../migrate.mjs");
+      const result = await migrate(path, options.write);
+      if (result.blocked) process.exitCode = 1;
+      console.log(formatResult("migrate", result, options));
+    });
+
   program
     .command("init")
     .description("Link an existing project without generating starter data")

package/cli/dev.mjs

@@ -1,3 +1,4 @@
+import { once } from "node:events";
 import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import { createServer } from "node:http";
@@ -53,6 +54,7 @@ export async function dev(project, options) {
     token: randomBytes(32).toString("hex"),
   };
   const children = [];
+  const expectedStops = new WeakSet();
   let stopping = false;
   let failure;
   let watcher;
@@ -122,7 +124,7 @@ export async function dev(project, options) {
       stop();
     });
     child.on("exit", (code) => {
-      if (!stopping) {
+      if (!stopping && !expectedStops.has(child)) {
         failure = new Error(`Development process exited (${code}).`);
         stop();
       }
@@ -142,42 +144,62 @@ export async function dev(project, options) {
       AUTH_ENVIRONMENT: "test",
       AUTH_ORIGINS: origin,
     };
-    start(
-      process.execPath,
-      [
-        wrangler,
-        "dev",
-        "--local",
-        "--ip",
-        "127.0.0.1",
-        "--port",
-        String(apiPort),
-        "--config",
-        join(runtime, "wrangler.jsonc"),
-        "--persist-to",
-        join(root, ".wrangler/domino"),
-        ...Object.entries(vars).flatMap(([key, value]) => [
-          "--var",
-          `${key}:${value}`,
-        ]),
-      ],
-      { WRANGLER_SEND_METRICS: "false" },
-    );
-    let ready = false;
-    for (let attempt = 0; attempt < 150 && !stopping; attempt++) {
-      try {
-        ready = (await fetch(connection.apiUrl + "/v1/auth/session")).ok;
-      } catch {
-        /* Runtime is starting. */
+    const startApi = () =>
+      start(
+        process.execPath,
+        [
+          wrangler,
+          "dev",
+          "--local",
+          "--ip",
+          "127.0.0.1",
+          "--port",
+          String(apiPort),
+          "--config",
+          join(runtime, "wrangler.jsonc"),
+          "--persist-to",
+          join(root, ".wrangler/domino"),
+          ...Object.entries(vars).flatMap(([key, value]) => [
+            "--var",
+            `${key}:${value}`,
+          ]),
+        ],
+        { WRANGLER_SEND_METRICS: "false" },
+      );
+    let api = startApi();
+    const waitReady = async () => {
+      let ready = false;
+      for (let attempt = 0; attempt < 150 && !stopping; attempt++) {
+        try {
+          ready = (await fetch(connection.apiUrl + "/v1/auth/session")).ok;
+        } catch {
+          /* Runtime is starting. */
+        }
+        if (ready) break;
+        await delay(200);
       }
-      if (ready) break;
-      await delay(200);
+      if (!ready) throw failure ?? new Error("Local Relay did not start.");
+    };
+    await waitReady();
+    const access = await request(connection, "/access");
+    const legacy = access.projects.find((p) => p.project === "campaign");
+    const local =
+      legacy ??
+      (await request(connection, "/projects", "POST", {
+        actionId: "offline-campaign-v1",
+        name: "Local campaign",
+      }));
+    if (local.project !== connection.project) {
+      connection.project = local.project;
+      vars.AUTH_PROJECT = local.project;
+      expectedStops.add(api);
+      const exited = once(api, "exit");
+      if (process.platform === "win32") api.kill("SIGTERM");
+      else process.kill(-api.pid, "SIGTERM");
+      await exited;
+      api = startApi();
+      await waitReady();
     }
-    if (!ready) throw failure ?? new Error("Local Relay did not start.");
-    await request(connection, "/projects", "POST", {
-      project: connection.project,
-      name: "Local campaign",
-    });
     const sync = developmentSync(connection, project.path, options.reviewMode);
     await sync();
     let dirty = false;

package/cli/migrate.mjs

@@ -0,0 +1,399 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve } from "node:path";
+import ts from "typescript";
+import { createTwoFilesPatch } from "diff";
+import { discoverEntries } from "./discovery.mjs";
+
+const helpers = new Set([
+  "defineQuest",
+  "defineQuestType",
+  "defineTieredReward",
+  "defineLeaderboard",
+  "defineReferral",
+]);
+const excluded =
+  /(^|[/\\])(node_modules|dist|build|out|coverage|\.git|\.next|\.domino|\.domino-build|\.wrangler|\.artifacts)([/\\]|$)/;
+const fieldName = (node) =>
+  node.name && (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name))
+    ? node.name.text
+    : undefined;
+const property = (node, name) =>
+  node.properties.find((p) => fieldName(p) === name);
+const valueOf = (node) =>
+  ts.isPropertyAssignment(node)
+    ? node.initializer
+    : ts.isShorthandPropertyAssignment(node)
+      ? node.name
+      : undefined;
+
+/** Inspect syntax only. Never import or execute a project's modules. */
+export async function migrationPlan(path) {
+  const root = dirname(path);
+  const manifestText = await readFile(path, "utf8");
+  const manifest = JSON.parse(manifestText);
+  const diagnostics = [];
+  const changes = [];
+  const references = new Map();
+  const project = {
+    path,
+    config: {
+      ...manifest,
+      quests: manifest.quests ?? [],
+      questTypes: manifest.questTypes ?? [],
+    },
+  };
+  const entries = [
+    ...(await discoverEntries(project, "quests")),
+    ...(await discoverEntries(project, "questTypes")),
+    ...(manifest.leaderboards ?? []),
+    ...(manifest.referrals ?? []),
+  ];
+  const configPath = ts.findConfigFile(root, ts.sys.fileExists);
+  const config = configPath
+    ? ts.readConfigFile(configPath, ts.sys.readFile)
+    : null;
+  const options =
+    config && !config.error
+      ? ts.parseJsonConfigFileContent(
+          config.config,
+          ts.sys,
+          dirname(configPath),
+        ).options
+      : {};
+  const program = ts.createProgram(
+    entries.map((entry) => resolve(root, entry.entry)),
+    { ...options, allowJs: true, noEmit: true },
+  );
+  const files = program
+    .getSourceFiles()
+    .filter((source) => {
+      const local = relative(root, source.fileName);
+      return (
+        !source.isDeclarationFile &&
+        !local.startsWith("..") &&
+        !excluded.test(local)
+      );
+    })
+    .map((source) => source.fileName)
+    .sort();
+  const checker = program.getTypeChecker();
+  function diagnostic(source, node, code, severity, message, suggestion) {
+    const position = source.getLineAndCharacterOfPosition(
+      node.getStart(source),
+    );
+    const item = {
+      code,
+      severity,
+      file: relative(root, source.fileName),
+      line: position.line + 1,
+      column: position.character + 1,
+      message,
+      suggestion,
+    };
+    diagnostics.push(item);
+    return item;
+  }
+  function importedName(expression) {
+    if (ts.isIdentifier(expression)) {
+      const declaration =
+        checker.getSymbolAtLocation(expression)?.declarations?.[0];
+      if (!declaration || !ts.isImportSpecifier(declaration)) return;
+      const imported = declaration.parent.parent.parent;
+      if (
+        ts.isImportDeclaration(imported) &&
+        /^@domino-sdk\/relay(?:\/authoring)?$/.test(
+          imported.moduleSpecifier.text,
+        )
+      )
+        return (declaration.propertyName ?? declaration.name).text;
+    }
+    if (ts.isPropertyAccessExpression(expression)) {
+      const declaration = checker.getSymbolAtLocation(expression.expression)
+        ?.declarations?.[0];
+      if (!declaration || !ts.isNamespaceImport(declaration)) return;
+      const imported = declaration.parent.parent;
+      if (
+        ts.isImportDeclaration(imported) &&
+        /^@domino-sdk\/relay(?:\/authoring)?$/.test(
+          imported.moduleSpecifier.text,
+        )
+      )
+        return expression.name.text;
+    }
+  }
+  function literal(node, depth = 0) {
+    if (!node || depth > 8) return;
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+      return node.text;
+    if (
+      ts.isParenthesizedExpression(node) ||
+      ts.isAsExpression(node) ||
+      ts.isSatisfiesExpression(node)
+    )
+      return literal(node.expression, depth + 1);
+    if (ts.isIdentifier(node)) {
+      const declaration = checker.getSymbolAtLocation(node)?.valueDeclaration;
+      if (
+        declaration &&
+        ts.isVariableDeclaration(declaration) &&
+        declaration.parent.flags & ts.NodeFlags.Const
+      )
+        return literal(declaration.initializer, depth + 1);
+    }
+  }
+  function ledger(source, node) {
+    const name = literal(node);
+    if (name === undefined) {
+      diagnostic(
+        source,
+        node,
+        "LEDGER_REFERENCE_DYNAMIC",
+        "warning",
+        "This ledger reference cannot be determined without running code.",
+        "Verify that the selected ledger already exists, or declare its stable key in relay.json pointLedgers.",
+      );
+    } else if (
+      /^[\w-]+$/.test(name) &&
+      !/^ledger_[A-Za-z0-9]{22}$/.test(name)
+    ) {
+      if (!references.has(name)) references.set(name, { source, node });
+    }
+  }
+  for (const file of files) {
+    const source = program.getSourceFile(file);
+    if (!source) continue;
+    const edits = [];
+    function visit(node) {
+      if (ts.isCallExpression(node)) {
+        const name = importedName(node.expression);
+        const argument = node.arguments[0];
+        if (name === "points" && argument) ledger(source, argument);
+        if (helpers.has(name)) {
+          if (
+            !argument ||
+            !ts.isObjectLiteralExpression(argument) ||
+            argument.properties.some(ts.isSpreadAssignment)
+          ) {
+            diagnostic(
+              source,
+              node,
+              "AUTHORING_IDENTITY_DYNAMIC",
+              "warning",
+              "This declaration uses an indirect object or spread; it was left unchanged.",
+              "Keep the existing authoring name and replace id with key in the defining object. Legacy id remains supported.",
+            );
+          } else {
+            const id = property(argument, "id");
+            const key = property(argument, "key");
+            if (id && key) {
+              const oldValue = literal(valueOf(id));
+              const newValue = literal(valueOf(key));
+              if (
+                oldValue === undefined ||
+                newValue === undefined ||
+                oldValue !== newValue
+              ) {
+                diagnostic(
+                  source,
+                  key,
+                  "AUTHORING_IDENTITY_CONFLICT",
+                  "error",
+                  "Both id and key are present and cannot be proven equal.",
+                  "Keep the original id value as key and remove id. Do not choose a new name for an existing resource.",
+                );
+              } else {
+                const index = argument.properties.indexOf(id);
+                const next = argument.properties[index + 1];
+                const previous = argument.properties[index - 1];
+                edits.push({
+                  start: id.getStart(source),
+                  end: id.end,
+                  text: "",
+                });
+                const scanner = ts.createScanner(
+                  ts.ScriptTarget.Latest,
+                  true,
+                  ts.LanguageVariant.Standard,
+                  source.text,
+                );
+                scanner.setTextPos(next ? id.end : (previous?.end ?? id.end));
+                if (scanner.scan() === ts.SyntaxKind.CommaToken)
+                  edits.push({
+                    start: scanner.getTokenPos(),
+                    end: scanner.getTextPos(),
+                    text: "",
+                  });
+                diagnostic(
+                  source,
+                  id,
+                  "AUTHORING_ID_DEPRECATED",
+                  "warning",
+                  "id repeats the authoring key.",
+                  "Run domino migrate --write to remove the redundant alias.",
+                );
+              }
+            } else if (id) {
+              edits.push({
+                start: id.name.getStart(source),
+                end: id.name.end,
+                text: ts.isShorthandPropertyAssignment(id) ? "key: id" : "key",
+              });
+              diagnostic(
+                source,
+                id,
+                "AUTHORING_ID_DEPRECATED",
+                "warning",
+                "id is supported as an authoring key alias.",
+                "Run domino migrate --write to rename it to key without changing its value.",
+              );
+            } else if (!key) {
+              diagnostic(
+                source,
+                argument,
+                "AUTHORING_KEY_MISSING",
+                "error",
+                "This declaration has no authoring key.",
+                "Add a stable key. For an existing resource, use its original authoring id value.",
+              );
+            }
+            function balances(child) {
+              if (
+                ts.isPropertyAssignment(child) &&
+                fieldName(child) === "balance"
+              ) {
+                const object = child.parent;
+                const parent = object.parent;
+                const kind = ts.isObjectLiteralExpression(object)
+                  ? property(object, "kind")
+                  : undefined;
+                const isPointReward =
+                  kind && literal(valueOf(kind)) === "points";
+                const isBudgetCost =
+                  ts.isPropertyAssignment(parent) &&
+                  fieldName(parent) === "cost";
+                const isBonus =
+                  name === "defineReferral" &&
+                  ts.isArrayLiteralExpression(parent) &&
+                  ts.isPropertyAssignment(parent.parent) &&
+                  fieldName(parent.parent) === "bonuses";
+                if (
+                  (name === "defineLeaderboard" && object === argument) ||
+                  isPointReward ||
+                  isBudgetCost ||
+                  isBonus
+                )
+                  ledger(source, child.initializer);
+              }
+              ts.forEachChild(child, balances);
+            }
+            balances(argument);
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+    visit(source);
+    let after = source.text;
+    for (const edit of edits.sort((a, b) => b.start - a.start))
+      after = after.slice(0, edit.start) + edit.text + after.slice(edit.end);
+    if (after !== source.text)
+      changes.push({ path: file, before: source.text, after });
+  }
+  const jsonSource = ts.parseJsonText(path, manifestText);
+  const jsonObject = jsonSource.statements[0]?.expression;
+  const collectionNodes =
+    jsonObject && property(jsonObject, "collections")?.initializer?.elements;
+  let manifestChanged = false;
+  for (const [index, collection] of (manifest.collections ?? []).entries()) {
+    if (
+      !collection ||
+      typeof collection !== "object" ||
+      collection.id === undefined
+    )
+      continue;
+    const node = collectionNodes?.[index] ?? jsonObject;
+    if (collection.key !== undefined && collection.key !== collection.id) {
+      diagnostic(
+        jsonSource,
+        node,
+        "AUTHORING_IDENTITY_CONFLICT",
+        "error",
+        "Collection id and key differ.",
+        "Keep the original id value as key and remove id.",
+      );
+    } else {
+      diagnostic(
+        jsonSource,
+        node,
+        "AUTHORING_ID_DEPRECATED",
+        "warning",
+        "Collection id is supported as an authoring key alias.",
+        "Run domino migrate --write to rename it to key.",
+      );
+      collection.key = collection.id;
+      delete collection.id;
+      manifestChanged = true;
+    }
+  }
+  const declared = new Set(
+    (manifest.pointLedgers ?? []).map((ledger) => ledger.key),
+  );
+  for (const [key, { source, node }] of references) {
+    if (declared.has(key)) continue;
+    diagnostic(
+      source,
+      node,
+      "LEDGER_DECLARATION_MISSING",
+      "warning",
+      `Ledger ${JSON.stringify(key)} has no local declaration. It must already exist remotely or be declared before publication.`,
+      "Run domino migrate to review a pointLedgers declaration, or keep using the existing remote ledger.",
+    );
+    manifest.pointLedgers ??= [];
+    manifest.pointLedgers.push({ key, name: key });
+    manifestChanged = true;
+  }
+  if (manifestChanged)
+    changes.push({
+      path,
+      before: manifestText,
+      after: JSON.stringify(manifest, null, 2) + "\n",
+    });
+  return { diagnostics, changes };
+}
+
+export async function migrate(path, write = false) {
+  const plan = await migrationPlan(path);
+  const blocked = plan.diagnostics.some((item) => item.severity === "error");
+  if (write && !blocked) {
+    // Refuse stale plans before touching any file.
+    for (const change of plan.changes)
+      if ((await readFile(change.path, "utf8")) !== change.before)
+        throw new Error(
+          `File changed during migration: ${change.path}. Run domino migrate again.`,
+        );
+    for (const change of plan.changes)
+      await writeFile(change.path, change.after);
+  }
+  return {
+    applied: write && !blocked,
+    blocked,
+    files: plan.changes.map((change) => relative(dirname(path), change.path)),
+    diff: plan.changes
+      .map((change) => {
+        const name = relative(dirname(path), change.path);
+        return createTwoFilesPatch(
+          `a/${name}`,
+          `b/${name}`,
+          change.before,
+          change.after,
+        );
+      })
+      .join("\n"),
+    diagnostics: plan.diagnostics,
+    next: blocked
+      ? "Resolve the reported conflicts, then run domino migrate again."
+      : write
+        ? "Review the diff, then run domino check --json."
+        : "Review the diff. Run domino migrate --write to apply it.",
+  };
+}

package/cli/output.mjs

@@ -44,6 +44,16 @@ export function formatDetails(value, indent = "") {
 export function formatResult(command, result, options = {}) {
   if (options.json || command === "api")
     return JSON.stringify(result, null, options.json ? undefined : 2);
+  if (command === "migrate")
+    return [
+      result.diff || "No automatic changes needed.",
+      formatDetails({
+        applied: result.applied,
+        blocked: result.blocked,
+        diagnostics: result.diagnostics,
+        next: result.next,
+      }),
+    ].join("\n");
   if (command === "logs") return result.logs.trimEnd();
   if (command === "reference" && result.markdown)
     return result.markdown.trimEnd();
@@ -66,6 +76,7 @@ export function formatResult(command, result, options = {}) {
       result: "Bundle ready",
       quests: result.releases.length,
       types: result.types.length,
+      pointLedgers: result.pointLedgers.length,
       collections: result.collections.length,
       leaderboards: result.leaderboards.length,
       referrals: result.referrals.length,