@terminus-ai/cli 0.0.1

package/bin/server-sandbox.mjs

@@ -0,0 +1,204 @@
+/**
+ * An app's server code, run the way the platform runs it: the platform's own
+ * harness (vendored byte for byte in vendor/appd/) in a fresh process whose
+ * sandbox is Node's permission model — the op reads only its own files,
+ * writes only its copy of server/, has no network and next to no
+ * environment, and nothing carries from one run to the next.
+ *
+ * `terminus dev` runs every op through here (dev-server-ops.mjs), and the
+ * compiler loads an entry through the same harness to read the ops it
+ * exports (`describeServerOps`), so both see server/ exactly as the
+ * platform does.
+ */
+
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { CliError } from "./client.mjs";
+
+const APPD_DIR = fileURLToPath(new URL("./vendor/appd/", import.meta.url));
+export const SERVER_PROTOCOL = JSON.parse(readFileSync(path.join(APPD_DIR, "server-protocol.json"), "utf8"));
+const NODE_HARNESS = readFileSync(path.join(APPD_DIR, "node-harness.mjs"), "utf8");
+const PYTHON_HARNESS = readFileSync(path.join(APPD_DIR, "python-harness.py"), "utf8");
+
+const RESULT_FILE = path.posix.basename(SERVER_PROTOCOL.result_path);
+const INVOCATION_FILE = path.posix.basename(SERVER_PROTOCOL.invocation_path);
+/** bashd keeps the first 64 KiB of stdout and 32 KiB of stderr. */
+const MAX_STDOUT_BYTES = 64 * 1024;
+const MAX_STDERR_BYTES = 32 * 1024;
+/** Loading an entry to read its ops runs its top-level code; this bounds it. */
+const DESCRIBE_TIMEOUT_MS = 10_000;
+const DESCRIBE_FILE = ".terminus_describe.js";
+
+/** Head-truncate to a byte budget, as bashd does (a split character decodes as U+FFFD). */
+function truncateUtf8(text, maxBytes) {
+  const bytes = Buffer.from(text, "utf8");
+  if (bytes.length <= maxBytes) return text;
+  return bytes.subarray(0, maxBytes).toString("utf8");
+}
+
+function collectOutput(stream, maxBytes) {
+  const chunks = [];
+  let kept = 0;
+  stream.on("data", (chunk) => {
+    if (kept >= maxBytes) return;
+    const piece = chunk.subarray(0, maxBytes - kept);
+    chunks.push(piece);
+    kept += piece.length;
+  });
+  return () => truncateUtf8(Buffer.concat(chunks).toString("utf8"), maxBytes);
+}
+
+/** Stop a run and the syscalls it started (it leads its own process group). */
+export function stopGroup(child) {
+  try {
+    process.kill(-child.pid, "SIGKILL");
+  } catch {
+    child.kill("SIGKILL");
+  }
+}
+
+/**
+ * One run of the harness. `program` is the server/ files ({path, bytes}),
+ * `entry` the entrypoint relative to server/, `invocation` {op, input, ctx}.
+ * `prepareHost(hostDir)` may place an `agentos-terminus` relay beside the
+ * sandbox (the node lane's syscalls); `running` tracks live processes.
+ * Answers {outcome: completed|failed|timed_out, output, logs, errorText,
+ * durationMs, unavailable} — `unavailable` when the runtime itself could not
+ * be started (no python3).
+ */
+export async function runServerHarness({ runtime, entry, program, invocation, timeoutMs, prepareHost = null, running = null }) {
+  const root = await realpath(await mkdtemp(path.join(os.tmpdir(), "terminus-server-op-")));
+  const vmDir = path.join(root, "vm");
+  const serverBase = path.join(vmDir, "server");
+  const hostDir = path.join(root, "host");
+  try {
+    await mkdir(serverBase, { recursive: true });
+    for (const file of program) {
+      const target = path.join(vmDir, ...file.path.split("/"));
+      await mkdir(path.dirname(target), { recursive: true });
+      await writeFile(target, file.bytes);
+    }
+    await writeFile(path.join(serverBase, INVOCATION_FILE), JSON.stringify(invocation));
+    let command;
+    let args;
+    let env;
+    if (runtime === "node") {
+      const harnessPath = path.join(vmDir, "harness.mjs");
+      await writeFile(harnessPath, NODE_HARNESS.replaceAll("__ENTRYPOINT__", entry));
+      // The sandbox has no network; say so in words that point at the syscall.
+      const denyNetwork = path.join(vmDir, "deny-network.mjs");
+      await writeFile(denyNetwork, [
+        "const refuse = () => { throw new TypeError(\"server code has no network — fetch through terminus.webFetch(url)\"); };",
+        "globalThis.fetch = async () => refuse();",
+        "globalThis.WebSocket = class WebSocket { constructor() { refuse(); } };",
+        "globalThis.EventSource = class EventSource { constructor() { refuse(); } };",
+        "",
+      ].join("\n"));
+      await mkdir(hostDir);
+      if (prepareHost) await prepareHost(hostDir);
+      command = process.execPath;
+      args = [
+        "--permission",
+        `--allow-fs-read=${vmDir}`,
+        `--allow-fs-write=${serverBase}`,
+        "--allow-child-process",
+        "--disable-warning=SecurityWarning",
+        "--import",
+        pathToFileURL(denyNetwork).href,
+        harnessPath,
+      ];
+      env = { PATH: hostDir, TERMINUS_SERVER_BASE: serverBase };
+    } else {
+      const harnessPath = path.join(vmDir, "harness.py");
+      await writeFile(harnessPath, PYTHON_HARNESS.replaceAll("__ENTRYPOINT__", entry));
+      command = "python3";
+      args = [harnessPath];
+      env = { PATH: process.env.PATH ?? "/usr/bin:/bin", TERMINUS_SERVER_BASE: serverBase };
+    }
+    const started = Date.now();
+    const child = spawn(command, args, { cwd: serverBase, env, stdio: ["ignore", "pipe", "pipe"], detached: true });
+    running?.add(child);
+    const stdout = collectOutput(child.stdout, MAX_STDOUT_BYTES);
+    const stderr = collectOutput(child.stderr, MAX_STDERR_BYTES);
+    const exit = await new Promise((resolve) => {
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        stopGroup(child);
+      }, timeoutMs);
+      child.once("error", (error) => {
+        clearTimeout(timer);
+        resolve({ code: 1, timedOut: false, spawnError: error });
+      });
+      child.once("close", (code) => {
+        clearTimeout(timer);
+        resolve({ code: code ?? 1, timedOut });
+      });
+    });
+    running?.delete(child);
+    let errorText = stderr().trim();
+    if (exit.spawnError) {
+      errorText = exit.spawnError.code === "ENOENT" && runtime === "python"
+        ? "python3 was not found — install Python 3 to run python server ops under terminus dev"
+        : String(exit.spawnError.message);
+    }
+    const outcome = exit.timedOut ? "timed_out" : exit.code === 0 ? "completed" : "failed";
+    if (outcome === "timed_out" && !errorText) errorText = `the op did not finish within ${timeoutMs} ms`;
+    let output = null;
+    if (outcome === "completed") {
+      try {
+        output = JSON.parse(await readFile(path.join(serverBase, RESULT_FILE), "utf8"));
+      } catch {
+        output = null;
+      }
+    }
+    // A runtime that never started is the tier's failure, not the op's.
+    const unavailable = Boolean(exit.spawnError);
+    return { outcome, output, logs: stdout(), errorText, durationMs: Date.now() - started, unavailable };
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The ops a Node entry exports — the functions on its `exports.ops` — read by
+ * loading it through the platform harness, exactly as a call would: a tiny
+ * probe beside it requires the entry with the harness's own `require` and
+ * returns the names.
+ */
+export async function describeServerOps(program, entrypoint) {
+  const entry = entrypoint.replace(/^server\//, "");
+  const probe = [
+    `const entry = require(${JSON.stringify(`./${entry}`)});`,
+    "exports.ops = {",
+    "  describe() {",
+    "    const ops = entry && entry.ops && typeof entry.ops === \"object\" ? entry.ops : {};",
+    "    return Object.keys(ops).filter((name) => typeof ops[name] === \"function\");",
+    "  },",
+    "};",
+    "",
+  ].join("\n");
+  const run = await runServerHarness({
+    runtime: "node",
+    entry: DESCRIBE_FILE,
+    program: [
+      ...program.filter((file) => file.path !== `server/${DESCRIBE_FILE}`),
+      { path: `server/${DESCRIBE_FILE}`, bytes: Buffer.from(probe) },
+    ],
+    invocation: { ctx: {}, input: null, op: "describe" },
+    timeoutMs: DESCRIBE_TIMEOUT_MS,
+  });
+  if (run.outcome !== "completed") {
+    // An error thrown while loading prints a source excerpt first; the
+    // message is the line that names the error.
+    const lines = run.errorText.split("\n").map((line) => line.trim()).filter(Boolean);
+    const reason = lines.find((line) => /^[A-Za-z]*Error\b/u.test(line)) ?? lines[0] ?? run.outcome;
+    throw new CliError(`${entrypoint} could not be loaded the way the platform loads it: ${reason}`);
+  }
+  return Array.isArray(run.output) ? run.output.filter((name) => typeof name === "string") : [];
+}

package/bin/servicedev.mjs

@@ -0,0 +1,425 @@
+// The `terminus dev` session for `kind: "service"` packages.
+//
+// A service's implementation is already deployed somewhere — the developer's
+// own infrastructure, a platform-internal endpoint, or a third-party API
+// reached with a stored key. What local development needs is a fast way to
+// exercise that deployment through the same lane production traffic takes.
+// This server does exactly that: it imports the package as the caller's
+// draft, serves the package's own test page from `dev/`, and relays
+// `POST /api/invoke/{operation}` through the platform's free draft-test lane
+// (a direct Ed25519-authorized call for public terminus_signed endpoints,
+// else the gateway test door). The page is authored by the service — anydoc
+// ships a drop-a-document surface, obscura a URL box — so the harness stays
+// generic.
+//
+// The security model mirrors bin/devserver.mjs: the user JWT never reaches
+// the page; a per-run random token is injected into the served HTML and
+// required on every /api/* call, and cross-origin browser pages are refused.
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import { watch } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+
+import { CliError, usageError } from "./client.mjs";
+import { connect } from "./http.mjs";
+import { importLinkedDraft, invokeDraftOperation, readAppPackage } from "./apps.mjs";
+import {
+  answerDevAbout,
+  assertDevPortRangeAvailable,
+  closeDevServer,
+  DEV_ABOUT_PATH,
+  devPortUnavailableError,
+  isLoopbackHost,
+  isLoopbackOrigin,
+  listenDevServer,
+  refuseForeignHost,
+  resolveDevPortRange,
+} from "./dev-ports.mjs";
+import { contentTypeFor, openWithPlatform, timingSafeTokenMatch } from "./devserver.mjs";
+
+const SERVICE_DEV_PORT = 4750;
+const PORT_ATTEMPTS = 50;
+// The gateway caps service requests at 8 MiB of raw bytes; the JSON envelope
+// form carries the same payload base64-encoded, so allow the expansion.
+const RAW_BODY_LIMIT = 8 * 1024 * 1024;
+const JSON_BODY_LIMIT = 12 * 1024 * 1024;
+const WATCHED_FILES = new Set(["terminus.json", "openapi.json", "README.md"]);
+
+async function readServicePackage(dir) {
+  const pkg = await readAppPackage(dir);
+  if (pkg.manifest.kind !== "service") {
+    throw new CliError(`terminus dev found kind '${pkg.manifest.kind}' where a service was expected`);
+  }
+  if (pkg.servicePackage.runtime.kind === "builtin") {
+    throw new CliError(
+      "this service runs inside the Terminus backend (runtime.kind 'builtin'); "
+        + "there is no endpoint to exercise locally — test it through the platform surfaces",
+    );
+  }
+  return pkg;
+}
+
+async function loadServiceState(dir, api, flags = {}) {
+  const pkg = await readServicePackage(dir);
+  // The dev relays calls through the service's draft, so the service has to
+  // exist on Terminus already; this refreshes that draft from the folder.
+  const imported = await importLinkedDraft(api, pkg, {
+    flags,
+    message: "Staged by terminus dev",
+  });
+  const appId = imported?.app?.id;
+  if (!appId) throw new CliError("the platform did not return an id for the imported service draft");
+  return { pkg, appId };
+}
+
+function serviceBoot(state, token) {
+  const service = state.pkg.servicePackage;
+  return {
+    token,
+    service: {
+      name: service.name,
+      version: service.version,
+      description: service.description,
+    },
+    operations: state.pkg.manifest.runtime.operations.map((operation) => ({
+      id: operation.id,
+      method: operation.method,
+      path: operation.path,
+      description: operation.description ?? "",
+      request_content_type: operation.request_content_type ?? null,
+      response_content_type: operation.response_content_type ?? null,
+      timeout_seconds: operation.timeout_seconds ?? 30,
+    })),
+  };
+}
+
+/** Inject the boot object without demanding a placeholder from page authors:
+ * right after <head> when the page has one, else ahead of everything.
+ *
+ * The page contract is host-agnostic: `window.__SERVICE_DEV__` carries
+ * `{ service, operations, invoke }`, and `invoke(operationId, { input,
+ * query, bytes, idempotencyKey })` returns the test-lane result. This host
+ * implements invoke as a fetch to its own /api doors; the admin console
+ * implements the same contract over postMessage from a sandboxed frame, so
+ * pages never hard-code a transport.
+ */
+function injectBoot(html, boot) {
+  const data = JSON.stringify(boot).replace(/</g, "\\u003c");
+  const script = `<script>(() => {
+  const boot = ${data};
+  const call = async (operationId, headers, body) => {
+    const target = new URL("api/invoke/" + encodeURIComponent(operationId), document.baseURI);
+    if (headers.query) {
+      for (const [key, value] of Object.entries(headers.query)) {
+        target.searchParams.set(key, String(value));
+      }
+    }
+    const response = await fetch(target, {
+      method: "POST",
+      headers: { ...headers.http, "x-dev-token": boot.token },
+      body,
+    });
+    const result = await response.json();
+    if (!response.ok) throw new Error(result.error ?? ("HTTP " + response.status));
+    return result;
+  };
+  boot.invoke = (operationId, request = {}) => {
+    const { input, query, bytes, idempotencyKey } = request;
+    if (bytes !== undefined) {
+      return call(operationId, { http: { "content-type": "application/octet-stream" }, query }, bytes);
+    }
+    return call(
+      operationId,
+      { http: { "content-type": "application/json" } },
+      JSON.stringify({
+        ...(input !== undefined ? { input } : {}),
+        ...(query ? { query } : {}),
+        ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
+      }),
+    );
+  };
+  window.__SERVICE_DEV__ = boot;
+})();</script>`;
+  const head = /<head[^>]*>/i.exec(html);
+  if (head) {
+    const cut = head.index + head[0].length;
+    return `${html.slice(0, cut)}${script}${html.slice(cut)}`;
+  }
+  return `${script}${html}`;
+}
+
+function safeDevAssetPath(devDir, pathname) {
+  const relative = decodeURIComponent(pathname).replace(/^\/+/, "") || "index.html";
+  const segments = relative.split("/");
+  if (segments.some((segment) => !segment || segment === "." || segment === ".."
+      || segment.includes("\\"))) {
+    return null;
+  }
+  return path.join(devDir, ...segments);
+}
+
+async function readBody(request, limit) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    size += chunk.length;
+    if (size > limit) throw new CliError("request body is too large for the service test lane");
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks, size);
+}
+
+function invokeEnvelope(request, url, bytes) {
+  const contentType = String(request.headers["content-type"] ?? "").toLowerCase();
+  if (contentType.startsWith("application/json")) {
+    let envelope = {};
+    if (bytes.length) {
+      try {
+        envelope = JSON.parse(bytes.toString("utf8"));
+      } catch {
+        throw new CliError("the invoke body is not valid JSON");
+      }
+    }
+    if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) {
+      throw new CliError("the invoke body must be a JSON object");
+    }
+    const body = { query: {} };
+    if (envelope.query !== undefined) {
+      if (!envelope.query || typeof envelope.query !== "object" || Array.isArray(envelope.query)) {
+        throw new CliError("invoke 'query' must be a JSON object");
+      }
+      body.query = envelope.query;
+    }
+    if (envelope.body_base64 != null) body.body_base64 = String(envelope.body_base64);
+    else if (envelope.input !== undefined) body.input = envelope.input;
+    if (envelope.idempotency_key) body.idempotency_key = String(envelope.idempotency_key);
+    return body;
+  }
+  // Any other content type is the operation's raw request body — the page
+  // posts file bytes directly and puts parameters in the query string.
+  if (bytes.length > RAW_BODY_LIMIT) {
+    throw new CliError("the file is larger than the 8 MiB service request limit");
+  }
+  const query = {};
+  for (const [key, value] of url.searchParams.entries()) {
+    if (key !== "token") query[key] = value;
+  }
+  return { query, ...(bytes.length ? { body_base64: bytes.toString("base64") } : {}) };
+}
+
+export async function startServiceDevServer({ commandArgs, dir, flags, api }) {
+  const pkg = await readServicePackage(dir);
+  const devDir = path.join(dir, "dev");
+  const indexPath = path.join(devDir, "index.html");
+  try {
+    const info = await stat(indexPath);
+    if (!info.isFile()) throw new Error("not a file");
+  } catch {
+    throw new CliError(
+      "this service package has no dev/index.html test page; add one (it is served "
+        + "locally and never uploaded) or test operations with 'terminus service test'",
+    );
+  }
+  // A busy --port is reported before the draft import, so it costs nothing on
+  // Terminus and says who holds the port.
+  const basePort = resolveDevPortRange(flags.port, 1, SERVICE_DEV_PORT);
+  if (flags.port !== undefined) {
+    await assertDevPortRangeAvailable({ basePort, commandArgs, count: 1, directory: dir });
+  }
+  const imported = await importLinkedDraft(api, pkg, {
+    flags,
+    message: "Staged by terminus dev",
+  });
+  const appId = imported?.app?.id;
+  if (!appId) throw new CliError("the platform did not return an id for the imported service draft");
+  let state = { pkg, appId };
+  const token = randomBytes(16).toString("hex");
+
+  const authorized = (request, url) => {
+    const presented = request.headers["x-dev-token"] ?? url.searchParams.get("token");
+    return timingSafeTokenMatch(token, presented) && isLoopbackOrigin(request);
+  };
+
+  const server = createServer(async (request, response) => {
+    // The page carries the dev token, which invokes the service on the
+    // developer's account.
+    if (!isLoopbackHost(request)) return refuseForeignHost(request, response);
+    const url = new URL(request.url ?? "/", "http://127.0.0.1");
+    try {
+      if (url.pathname === DEV_ABOUT_PATH) {
+        answerDevAbout(request, response, {
+          kind: "service",
+          app: state.pkg.id ?? state.pkg.manifest.slug,
+          directory: path.resolve(dir),
+        });
+        return;
+      }
+      if (request.method === "GET" && !url.pathname.startsWith("/api/")) {
+        const asset = safeDevAssetPath(devDir, url.pathname);
+        if (!asset) {
+          response.writeHead(404).end("not found");
+          return;
+        }
+        let bytes;
+        try {
+          bytes = await readFile(asset);
+        } catch {
+          response.writeHead(404).end("not found");
+          return;
+        }
+        if (asset === indexPath) {
+          const page = injectBoot(bytes.toString("utf8"), serviceBoot(state, token));
+          response.writeHead(200, {
+            "content-type": "text/html; charset=utf-8",
+            "cache-control": "no-store",
+          });
+          response.end(page);
+          return;
+        }
+        response.writeHead(200, {
+          "content-type": contentTypeFor(asset),
+          "cache-control": "no-store",
+        });
+        response.end(bytes);
+        return;
+      }
+      if (!url.pathname.startsWith("/api/")) {
+        response.writeHead(404).end("not found");
+        return;
+      }
+      if (!authorized(request, url)) {
+        response.writeHead(401, { "content-type": "application/json" });
+        response.end(JSON.stringify({ error: "missing or invalid dev token" }));
+        return;
+      }
+      if (request.method === "GET" && url.pathname === "/api/service") {
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify({ ...serviceBoot(state, token), app_id: state.appId }));
+        return;
+      }
+      if (request.method === "POST" && url.pathname === "/api/reload") {
+        state = await loadServiceState(dir, api, flags);
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify({ ok: true }));
+        return;
+      }
+      const invoke = /^\/api\/invoke\/([A-Za-z0-9][A-Za-z0-9_.-]{0,79})$/.exec(url.pathname);
+      if (request.method === "POST" && invoke) {
+        const operationId = invoke[1];
+        if (!state.pkg.manifest.runtime.operations.some((entry) => entry.id === operationId)) {
+          throw new CliError(`service operation '${operationId}' is not declared by OpenAPI`);
+        }
+        const bytes = await readBody(request, JSON_BODY_LIMIT);
+        const body = invokeEnvelope(request, url, bytes);
+        const result = await invokeDraftOperation(api, {
+          pkg: state.pkg,
+          appId: state.appId,
+          operationId,
+          body,
+        });
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(result));
+        return;
+      }
+      response.writeHead(404, { "content-type": "application/json" });
+      response.end(JSON.stringify({ error: "unknown dev endpoint" }));
+    } catch (error) {
+      const message = error instanceof CliError ? error.message : String(error?.message ?? error);
+      const status = error instanceof CliError ? 400 : 502;
+      if (!(error instanceof CliError)) {
+        console.error(`service dev error: ${message}`);
+      }
+      if (!response.headersSent) {
+        response.writeHead(status, { "content-type": "application/json" });
+      }
+      response.end(JSON.stringify({ error: message }));
+    }
+  });
+
+  let port = basePort;
+  let lastError = null;
+  for (let attempt = 0; attempt < (flags.port !== undefined ? 1 : PORT_ATTEMPTS); attempt += 1) {
+    try {
+      await listenDevServer(server, port);
+      lastError = null;
+      port = server.address().port;
+      break;
+    } catch (error) {
+      lastError = error;
+      if (error?.code !== "EADDRINUSE") throw error;
+      port += 1;
+    }
+  }
+  if (lastError && flags.port !== undefined) {
+    // Taken during the import, after the check above said it was free.
+    throw await devPortUnavailableError({
+      basePort,
+      commandArgs,
+      count: 1,
+      directory: dir,
+      failures: [{ port: basePort, error: lastError }],
+    });
+  }
+  if (lastError) {
+    throw new CliError(`no free port between ${basePort} and ${port - 1}; pick one with --port`);
+  }
+
+  // Contract edits re-import the draft so the next invocation tests what is
+  // on disk; the dev/ page itself is read per request and needs no watcher.
+  let reloadTimer = null;
+  let watcher = null;
+  try {
+    watcher = watch(dir, (_event, filename) => {
+      if (!filename || !WATCHED_FILES.has(String(filename))) return;
+      clearTimeout(reloadTimer);
+      reloadTimer = setTimeout(async () => {
+        try {
+          state = await loadServiceState(dir, api, flags);
+          console.log("service contract changed — draft re-imported");
+        } catch (error) {
+          console.error(`service contract reload failed: ${
+            error instanceof CliError ? error.message : error
+          }`);
+        }
+      }, 300);
+      if (typeof reloadTimer.unref === "function") reloadTimer.unref();
+    });
+  } catch {
+    watcher = null; // watching is a convenience; never fail the session for it
+  }
+
+  const close = async () => {
+    clearTimeout(reloadTimer);
+    watcher?.close();
+    await closeDevServer(server);
+  };
+  return {
+    server,
+    port,
+    token,
+    url: `http://127.0.0.1:${port}/`,
+    state: () => state,
+    close,
+  };
+}
+
+export async function serviceDevCommand(dir, flags, commandArgs = []) {
+  if (flags.remote) throw usageError("--remote does not apply to service packages");
+  if (flags.members) throw usageError("--members only applies to app packages");
+  if (flags.guest) throw usageError("--guest only applies to app packages");
+  const api = await connect(flags);
+  const started = await startServiceDevServer({ commandArgs, dir, flags, api });
+  const service = started.state().pkg.servicePackage;
+  console.log(`Service dev session: ${service.name}@${service.version} → ${started.url}`);
+  console.log(
+    "Draft imported; invocations relay through the free test lane against the deployed endpoint.",
+  );
+  if (!flags.no_open) await openWithPlatform(started.url);
+  await new Promise((resolve) => {
+    const stop = () => resolve();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+  await started.close();
+}