@domino-sdk/relay-cli 0.1.0

package/README.md

@@ -0,0 +1,14 @@
+# Domino CLI
+
+Connect a project to Domino, install agent instructions, and build and deploy quests.
+
+```sh
+pnpm add -D @domino-sdk/relay-cli
+pnpm exec domino --help
+pnpm exec domino agents install
+pnpm exec domino doctor
+```
+
+The package includes project skills for Codex and Claude Code. `agents install` preserves existing instructions and customized skill files.
+
+Requires Node.js 24. Proprietary software; `UNLICENSED`.

package/cli/agents.mjs

@@ -0,0 +1,111 @@
+import { lstat, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+const locations = {
+  codex: ".agents/skills/domino",
+  claude: ".claude/skills/domino",
+};
+const resources = [
+  "SKILL.md",
+  "references/hosted.md",
+  "references/existing-app.md",
+  "references/authoring.md",
+];
+
+async function skillFiles(agent) {
+  const agents = agent === "both" ? Object.keys(locations) : [agent];
+  if (agents.some((name) => !Object.hasOwn(locations, name)))
+    throw new Error("Choose codex, claude, or both.");
+  const files = [];
+  for (const resource of resources) {
+    const content = await readFile(
+      new URL(`./skills/domino/${resource}`, import.meta.url),
+      "utf8",
+    );
+    for (const name of agents)
+      files.push({ path: `${locations[name]}/${resource}`, content });
+  }
+  return files;
+}
+
+// Check the whole destination before creating files. Never follow a project's
+// skill-directory symlinks or replace another author's instructions.
+async function existingFile(root, path) {
+  const parts = path.split("/");
+  let current = root;
+  for (const [index, part] of parts.entries()) {
+    current = join(current, part);
+    let info;
+    try {
+      info = await lstat(current);
+    } catch (error) {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    }
+    if (info.isSymbolicLink())
+      throw new Error(`Refusing to write through symlink ${current}.`);
+    if (index < parts.length - 1 && !info.isDirectory())
+      throw new Error(`Expected a directory at ${current}.`);
+    if (index === parts.length - 1 && !info.isFile())
+      throw new Error(`Expected a file at ${current}.`);
+  }
+  return readFile(current, "utf8");
+}
+
+export async function installAgentSkills(directory, agent = "both") {
+  const root = await realpath(resolve(directory));
+  const files = await skillFiles(agent);
+  const created = [];
+  const unchanged = [];
+  for (const file of files) {
+    const existing = await existingFile(root, file.path);
+    if (existing === null) created.push(file.path);
+    else if (existing === file.content) unchanged.push(file.path);
+    else
+      throw new Error(
+        `Refusing to overwrite ${join(root, file.path)}. Preserve your changes and reconcile this file with the installed CLI's Domino skill before retrying.`,
+      );
+  }
+  for (const file of files.filter((file) => created.includes(file.path))) {
+    // Recheck before each write so retries can adopt files from another install.
+    const existing = await existingFile(root, file.path);
+    if (existing === file.content) continue;
+    if (existing !== null)
+      throw new Error(`Refusing to overwrite ${join(root, file.path)}.`);
+    await mkdir(dirname(join(root, file.path)), { recursive: true });
+    await writeFile(join(root, file.path), file.content, { flag: "wx" });
+  }
+  return {
+    directory: root,
+    agent,
+    created,
+    unchanged,
+    next: "Open your agent in this project and ask it to use the Domino skill. Run domino doctor --json to inspect setup; add --remote to verify project access.",
+  };
+}
+
+export async function inspectAgentSkills(directory) {
+  const result = {};
+  for (const agent of Object.keys(locations)) {
+    let found = 0;
+    let modified = false;
+    for (const file of await skillFiles(agent)) {
+      try {
+        const content = await readFile(join(directory, file.path), "utf8");
+        found++;
+        if (content !== file.content) modified = true;
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+    result[agent] =
+      found === 0
+        ? "missing"
+        : found !== resources.length
+          ? "incomplete"
+          : modified
+            ? "modified"
+            : "installed";
+  }
+  return result;
+}

package/cli/commands/agents.mjs

@@ -0,0 +1,50 @@
+import { Option } from "commander";
+import { dirname } from "node:path";
+import { action } from "../runtime.mjs";
+import { installAgentSkills } from "../agents.mjs";
+import { diagnose } from "../doctor.mjs";
+
+export function registerAgentCommands(program) {
+  program
+    .command("agents")
+    .description("Set up project instructions for your coding agent")
+    .command("install")
+    .description(
+      "Install Domino skills without replacing existing instructions",
+    )
+    .option(
+      "--directory <path>",
+      "Project root (defaults to the linked project or current directory)",
+    )
+    .addOption(
+      new Option("--agent <name>", "Agent to configure")
+        .choices(["codex", "claude", "both"])
+        .default("both"),
+    )
+    .action(
+      action(({ project, options }) =>
+        installAgentSkills(
+          options.directory ??
+            (project ? dirname(project.path) : process.cwd()),
+          options.agent,
+        ),
+      ),
+    );
+
+  program
+    .command("doctor")
+    .description(
+      "Inspect local agent setup without changing files or running app code",
+    )
+    .option(
+      "--remote",
+      "Also verify access to the selected project through the management API",
+    )
+    .action(
+      action(async (context) => {
+        const result = await diagnose(context);
+        if (!result.healthy) process.exitCode = 1;
+        return result;
+      }),
+    );
+}

package/cli/commands/api.mjs

@@ -0,0 +1,34 @@
+import { Argument } from "commander";
+import { action, readStdin } from "../runtime.mjs";
+import { request } from "../connection.mjs";
+import { readJson } from "../project.mjs";
+
+export function registerApiCommand(program) {
+  program
+    .command("api")
+    .description("Call a /management/v1 route")
+    .addArgument(
+      new Argument("<method>", "HTTP method").choices([
+        "GET",
+        "POST",
+        "PUT",
+        "DELETE",
+        "PATCH",
+      ]),
+    )
+    .argument("<path>", "Path within /management/v1, for example /quests")
+    .argument("[file]", "JSON body file, or - for stdin")
+    .action(
+      action(async ({ connection }, method, path, file) => {
+        if (method === "GET" && file)
+          throw new Error("GET does not accept a body file.");
+        const body =
+          file === "-"
+            ? JSON.parse(await readStdin())
+            : file
+              ? await readJson(file)
+              : undefined;
+        return request(connection, path, method, body);
+      }),
+    );
+}

package/cli/commands/auth.mjs

@@ -0,0 +1,60 @@
+import { action, readStdin } from "../runtime.mjs";
+import { request, saveToken, savedToken } from "../connection.mjs";
+import { browserLogin } from "../device-login.mjs";
+
+export function registerAuthCommands(program) {
+  program
+    .command("login")
+    .description("Sign in through Console, or verify and save a personal token")
+    .option("--no-browser", "Print the sign-in URL without opening a browser")
+    .option(
+      "--token-stdin",
+      "Read the token from stdin instead of RELAY_MANAGEMENT_TOKEN",
+    )
+    .action(
+      action(async ({ connection, options }) => {
+        const token = (
+          options.tokenStdin
+            ? await readStdin()
+            : process.env.RELAY_MANAGEMENT_TOKEN
+        )?.trim();
+        if (!token && !options.tokenStdin)
+          return browserLogin(connection, {
+            ...options,
+            noBrowser: options.browser === false,
+          });
+        if (!token) throw new Error("Provide a personal token on stdin.");
+        const access = await request({ ...connection, token }, "/access");
+        await saveToken(connection.apiUrl, token);
+        return {
+          loggedIn: true,
+          apiUrl: connection.apiUrl,
+          actor: access.actor,
+        };
+      }),
+    );
+
+  program
+    .command("logout")
+    .description(
+      "Sign out and revoke a saved CLI session; remove saved personal tokens",
+    )
+    .action(
+      action(async ({ connection }) => {
+        const token = await savedToken(connection.apiUrl);
+        if (token?.startsWith("dc_"))
+          await request({ ...connection, token }, "/cli/session", "DELETE");
+        await saveToken(connection.apiUrl, null);
+        return {
+          loggedOut: true,
+          apiUrl: connection.apiUrl,
+          note: "Saved credential removed. Environment tokens remain active. Revoke tokens in Console Settings.",
+        };
+      }),
+    );
+
+  program
+    .command("whoami")
+    .description("Show identity and accessible projects")
+    .action(action(({ connection }) => request(connection, "/access")));
+}

package/cli/commands/hosting.mjs

@@ -0,0 +1,91 @@
+import { dirname, resolve } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { action } from "../runtime.mjs";
+import { request } from "../connection.mjs";
+import { checkout, requireNewDirectory } from "../git.mjs";
+import { dev } from "../dev.mjs";
+import { bundleCatalog, bundleProject } from "../project.mjs";
+
+export function registerHostingCommands(program) {
+  program
+    .command("check")
+    .description(
+      "Check the local app and bundle quest definitions without publishing",
+    )
+    .action(
+      action(async ({ project }) => {
+        if (!project) throw new Error("No relay.json found.");
+        if (project.config.app) {
+          try {
+            await promisify(execFile)(
+              "pnpm",
+              ["run", project.config.app.checkScript],
+              { cwd: dirname(project.path), maxBuffer: 10 * 1024 * 1024 },
+            );
+          } catch (error) {
+            throw new Error(error.stdout || error.stderr || error.message);
+          }
+        }
+        const quests = project.config.quests.length
+          ? await bundleProject(project)
+          : { releases: [] };
+        const catalog = await bundleCatalog(project);
+        return {
+          checked: true,
+          quests: quests.releases.length,
+          types: catalog.types.length,
+          collections: catalog.collections.length,
+        };
+      }),
+    );
+  program
+    .command("dev")
+    .description("Run the campaign and an isolated local Relay runtime")
+    .option("--port <port>", "App development server port")
+    .action(action(({ project, options }) => dev(project, options)));
+  program
+    .command("create")
+    .description("Create a hosted campaign repository and check it out locally")
+    .argument("<name>", "Project identifier")
+    .option("--directory <path>", "Local directory (defaults to project name)")
+    .action(
+      action(async ({ connection, options }, name) => {
+        if (!/^[a-zA-Z0-9_-]+$/.test(name))
+          throw new Error(
+            "Use letters, numbers, underscores, or hyphens for the project name.",
+          );
+        const directory = resolve(options.directory ?? name);
+        await requireNewDirectory(directory);
+        const access = await request(connection, "/access");
+        const organization = connection.organization || access.organization;
+        if (!organization)
+          throw new Error("Select an organization with --organization.");
+        const scoped = {
+          ...connection,
+          organization,
+          project: name,
+          environment: "test",
+        };
+        await request(scoped, "/projects", "POST", { project: name, name });
+        const repository = await request(scoped, "/repository", "POST", {
+          starter: "campaign",
+        });
+        return checkout(scoped, repository, directory);
+      }),
+    );
+  program
+    .command("checkout")
+    .description(
+      "Recover or clone a hosted campaign with Domino Git authentication",
+    )
+    .argument("<project>")
+    .option("--directory <path>", "Local directory (defaults to project name)")
+    .action(
+      action(async ({ connection, options }, project) => {
+        const scoped = { ...connection, project, environment: "test" };
+        const repository = await request(scoped, "/repository");
+        return checkout(scoped, repository, options.directory ?? project);
+      }),
+    );
+}

package/cli/commands/inspect.mjs

@@ -0,0 +1,47 @@
+import { InvalidArgumentError } from "commander";
+import { action } from "../runtime.mjs";
+import { request } from "../connection.mjs";
+
+function integerBetween(min, max) {
+  return (value) => {
+    if (!/^\d+$/.test(value) || Number(value) < min || Number(value) > max)
+      throw new InvalidArgumentError(
+        `Expected an integer between ${min} and ${max}.`,
+      );
+    return Number(value);
+  };
+}
+
+export function registerInspectCommands(program) {
+  program
+    .command("status")
+    .description("Show the project overview")
+    .action(action(({ connection }) => request(connection, "/overview")));
+
+  for (const [name, description] of [
+    ["quests", "List current quests"],
+    ["releases", "List release history"],
+  ]) {
+    program
+      .command(name)
+      .description(description)
+      .option("--limit <number>", "Page size (1–100)", integerBetween(1, 100))
+      .option(
+        "--offset <number>",
+        "Page offset (0–1000000)",
+        integerBetween(0, 1000000),
+      )
+      .option("--filter <value>", "Filter the collection")
+      .option("--q <text>", "Search the collection")
+      .action(
+        action(({ connection, options }) => {
+          const query = new URLSearchParams();
+          for (const key of ["limit", "offset", "filter", "q"]) {
+            if (options[key] !== undefined)
+              query.set(key, String(options[key]));
+          }
+          return request(connection, `/${name}?${query}`);
+        }),
+      );
+  }
+}

package/cli/commands/project.mjs

@@ -0,0 +1,160 @@
+import { writeFile } from "node:fs/promises";
+import { action } from "../runtime.mjs";
+import { request } from "../connection.mjs";
+import { initialize, bundleProject } from "../project.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,
+        title,
+        createdAt,
+        deploymentDefaults: configuration.defaults,
+        customValues: configuration.overrides,
+        preservedFromOlderRelease: configuration.preserved,
+        effectiveSettings: values,
+      }),
+    ),
+    types: value.types.map((t) => ({
+      id: t.id,
+      version: t.version,
+      title: t.definition.title,
+    })),
+    collections: value.collections,
+    supportedInteractions: value.supportedInteractions,
+  };
+}
+async function publish(connection, id) {
+  try {
+    const result = await request(connection, "/deployments/publish", "POST", {
+      id,
+    });
+    return { status: "published", ...summary(result) };
+  } catch (error) {
+    if (error.status === undefined || error.status >= 500)
+      throw new Error(
+        `Publication of ${id} was not confirmed. Retry with domino deploy --resume ${id}. ${error.message}`,
+      );
+    throw error;
+  }
+}
+async function build({ project, connection, options }, deploy) {
+  if (!project)
+    throw new Error(
+      "No relay.json found. Run domino init or pass --config FILE.",
+    );
+  if (options.resume && (options.preview || options.dryRun || options.out))
+    throw new Error(
+      "--resume publishes an existing preview; do not combine it with --preview, --dry-run, or --out.",
+    );
+  if (options.preview && options.dryRun)
+    throw new Error(
+      "Choose --preview for a server preview or --dry-run for an offline bundle.",
+    );
+  if (options.out && deploy)
+    throw new Error("--out requires build or deploy --dry-run.");
+  if (deploy && !options.preview && connection.environment === "live")
+    throw new Error(
+      "Live publication requires Console approval. Run deploy --dry-run --out deployment.json, then import the project deployment in Console.",
+    );
+  if (options.resume) return publish(connection, options.resume);
+  const payload = await bundleProject(project);
+  if (deploy) {
+    const preview = await request(
+      connection,
+      "/deployments/preview",
+      "POST",
+      payload,
+    );
+    if (options.preview) return { status: "preview", ...summary(preview) };
+    return publish(connection, preview.id);
+  }
+  if (options.out) {
+    await writeFile(options.out, JSON.stringify(payload, null, 2) + "\n");
+    return {
+      file: options.out,
+      quests: payload.releases.length,
+      types: payload.types.length,
+      collections: payload.collections.length,
+    };
+  }
+  return payload;
+}
+
+export function registerProjectCommands(program) {
+  program
+    .command("init")
+    .description("Link an existing project without generating starter data")
+    .argument("[directory]", "Existing project directory", ".")
+    .option(
+      "--entry <path>",
+      "Register an existing quest entry, relative to the target directory (repeatable)",
+      (entry, previous = []) => [...previous, entry],
+    )
+    .action(
+      action(async ({ connection, options }, directory) => {
+        const access = await request(connection, "/access");
+        const selected = connection.project
+          ? access.projects.find((item) => item.project === connection.project)
+          : access.projects.length === 1
+            ? access.projects[0]
+            : null;
+        if (!selected)
+          throw new Error(
+            "Select an accessible project with --project ID. Run domino whoami to list projects; create projects in Console.",
+          );
+        const environment = connection.environment ?? "test";
+        if (!selected.environments.includes(environment))
+          throw new Error(`No access to ${environment} for this project.`);
+        return initialize(directory, {
+          ...connection,
+          organization: access.organization,
+          project: selected.project,
+          environment,
+          quests: (options.entry ?? []).map((entry) => ({
+            entry,
+            settings: {},
+            provider: "workers-ai",
+          })),
+        });
+      }),
+    );
+
+  program
+    .command("build")
+    .description(
+      "Bundle all configured quests, reusable types, and collection slots without publishing",
+    )
+    .option(
+      "--out <file>",
+      "Write the complete project bundle to a file instead of stdout",
+    )
+    .action(action((context) => build(context, false)));
+
+  program
+    .command("deploy")
+    .description(
+      "Atomically deploy quests, reusable types, and collection slots, preserving Console-owned settings and placement",
+    )
+    .option(
+      "--dry-run",
+      "Build locally only; does not preview Relay custom values",
+    )
+    .option(
+      "--resume <id>",
+      "Publish an existing preview or recover its committed receipt",
+    )
+    .option(
+      "--preview",
+      "Resolve the full deployment against Relay without publishing",
+    )
+    .option(
+      "--out <file>",
+      "Write the combined bundle for Console approval (requires --dry-run)",
+    )
+    .action(action((context) => build(context, !context.options.dryRun)));
+}

package/cli/commands/staging.mjs

@@ -0,0 +1,94 @@
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { action } from "../runtime.mjs";
+import { request } from "../connection.mjs";
+import { runGit } from "../git.mjs";
+
+export function registerStagingCommands(program) {
+  program
+    .command("stage")
+    .description(
+      "Build a pushed commit in the cloud and deploy its staging preview",
+    )
+    .option("--commit <sha>", "Exact pushed commit (defaults to local HEAD)")
+    .option(
+      "--request-id <uuid>",
+      "Resume a previously submitted build request",
+    )
+    .option("--no-wait", "Return the build ID without waiting")
+    .action(
+      action(async ({ connection, project, options }) => {
+        if (!project)
+          throw new Error("Run stage inside a hosted campaign checkout.");
+        if (project.config.app?.kind !== "static")
+          throw new Error(
+            "Cloud staging currently supports static campaign checkouts with app.kind=static in relay.json. This project is not configured for cloud staging. SSR Worker apps use the Cloudflare Worker deployment workflow.",
+          );
+        const cwd = dirname(project.path);
+        if (
+          !options.commit &&
+          (await runGit(["status", "--porcelain"], { cwd }))
+        )
+          throw new Error(
+            "Commit your changes before staging. Only pushed commits are built.",
+          );
+        const commit =
+          options.commit ?? (await runGit(["rev-parse", "HEAD"], { cwd }));
+        if (!/^[a-f0-9]{40}$/.test(commit))
+          throw new Error("Use a full 40-character commit SHA.");
+        const scoped = { ...connection, environment: "test" };
+        const requestId = options.requestId ?? randomUUID();
+        process.stderr.write(`Build request ${requestId}\n`);
+        let build;
+        try {
+          build = await request(scoped, "/builds", "POST", {
+            commit,
+            requestId,
+          });
+        } catch (error) {
+          throw new Error(
+            `${error.message}\nRetry with --commit ${commit} --request-id ${requestId}`,
+          );
+        }
+        if (options.wait === false) return build;
+        let last = "";
+        for (;;) {
+          const current = await request(scoped, `/builds/${build.id}`);
+          const progress = `${current.phase}: ${current.message}`;
+          if (progress !== last) {
+            process.stderr.write(progress + "\n");
+            last = progress;
+          }
+          if (current.phase === "ready")
+            return { id: build.id, commit, stagingUrl: current.stagingUrl };
+          if (current.phase === "failed")
+            throw new Error(
+              `${current.message}\nInspect with domino logs ${build.id}`,
+            );
+          await new Promise((resolve) => setTimeout(resolve, 3000));
+        }
+      }),
+    );
+  program
+    .command("builds")
+    .description("List recent cloud builds for this campaign")
+    .action(
+      action(({ connection }) =>
+        request({ ...connection, environment: "test" }, "/builds"),
+      ),
+    );
+  program
+    .command("logs")
+    .description("Read retained cloud build logs")
+    .argument("<id>", "Build ID")
+    .action(
+      action(({ connection }, id) => {
+        if (!/^[a-f0-9-]{36}$/.test(id))
+          throw new Error("Expected a build UUID.");
+        return request(
+          { ...connection, environment: "test" },
+          `/builds/${id}/logs`,
+        );
+      }),
+    );
+}