spfn 0.3.0-beta.14 → 0.3.0-beta.15

package/README.md

@@ -685,6 +685,39 @@ Because the package is the app's, it is resolved **from the directory the comman
 Run `spfn ops token` from the app's root; running it elsewhere reports the package as
 missing, and the message names the directory it looked in.
 
+#### Can I call a surface from my own code?
+
+Yes — the client `spfn ops` runs on is a library export, `spfn/surface`, and it reaches any
+namespace a [`defineSurface`](../core/README.md#can-a-second-surface-sit-beside-_ops)
+serves, not only `/_ops`:
+
+```typescript
+import { createSurfaceClient } from 'spfn/surface';
+
+const client = createSurfaceClient({
+    appUrl: 'https://app.example',
+    namespace: '/_app',                               // manifest at /_app/_manifest
+    token: async () => issueToken(),                  // string | () => Promise<string>
+    onWarning: message => console.error(message),    // dropped commands; default: silent
+});
+
+const manifest = await client.manifest();
+const usage = client.describe(manifest, 'pageAdd');  // the --describe text
+const answer = await client.call('pageAdd', { params: {}, query: {}, body: { title: 'Hello' } });
+// answer: { status, body } — the app's answer, relayed
+```
+
+It keeps every check `spfn ops` makes: the manifest's shape, each command's path staying
+under `<namespace>/`, module metadata, and path parameters that would decode into a dot
+segment. `appUrl` must be https (`http` only against a loopback host) — refused when the
+client is created, with a thrown `Error`. A manifest request that does not answer 200
+throws a `SurfaceManifestError` carrying the `status`. The library prints nothing and does
+not load the CLI's terminal stack; `spfn ops` is this client on `/_ops` with its own
+printer.
+
+The `spfn` package has an `exports` map: `spfn` (the CLI's index), `spfn/surface`, and
+`spfn/package.json`. No other path inside the package is importable.
+
 ### `spfn kit`
 
 Install, verify and update a **Superfunction Kit** — a licensed product that ships as a

package/dist/index.js

@@ -949,7 +949,7 @@ import { dirname as dirname2, join as join10 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 function getCliVersion() {
   if (true) {
-    return "0.3.0-beta.14";
+    return "0.3.0-beta.15";
   }
   return fromPackageJson ?? (fromPackageJson = readPackageVersion());
 }
@@ -6339,80 +6339,23 @@ envCommand.command("audit").description("Find direct process.env reads and app e
 import { Command as Command15 } from "commander";
 import chalk36 from "chalk";
 
-// src/utils/ops/plain.ts
-function plain(value) {
-  return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "?");
-}
-
-// src/utils/ops/client.ts
-function joinUrl(appUrl, path5) {
-  return appUrl.replace(/\/+$/, "") + path5;
-}
-async function request(appUrl, token, method, path5, body) {
-  const response = await fetch(joinUrl(appUrl, path5), {
-    method,
-    headers: {
-      Authorization: `Bearer ${token}`,
-      ...body !== void 0 ? { "Content-Type": "application/json" } : {}
-    },
-    ...body !== void 0 ? { body: JSON.stringify(body) } : {}
-  });
-  const text = await response.text();
-  let parsed = text;
-  try {
-    parsed = text.length > 0 ? JSON.parse(text) : null;
-  } catch {
-  }
-  return { status: response.status, body: parsed };
-}
-async function fetchOpsManifest(appUrl, token) {
-  const { status, body } = await request(appUrl, token, "GET", "/_ops/_manifest");
-  if (status === 401 || status === 403) {
-    throw new Error("The app refused the ops token (check --token / SPFN_OPS_TOKEN / keychain).");
-  }
-  if (status === 404) {
-    throw new Error("No ops surface at this app (GET /_ops/_manifest answered 404). Mount one with createOpsRouter() and .packages([opsRouter]).");
-  }
-  if (status !== 200) {
-    throw new Error(`Manifest request failed with status ${status}.`);
-  }
-  const manifest = body;
-  if (manifest?.manifestVersion !== 1 || !Array.isArray(manifest.commands)) {
-    throw new Error("The manifest answer has an unknown shape.");
-  }
-  const modules = usableModules(manifest.modules);
-  return {
-    manifestVersion: 1,
-    ...manifest.modules !== void 0 ? { modules } : {},
-    commands: usableCommands(manifest.commands, new Set(modules.map((module) => module.id)))
-  };
-}
-var OPS_METHODS = /* @__PURE__ */ new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
-var OPS_EFFECTS = /* @__PURE__ */ new Set(["read", "write", "destructive"]);
-var MODULE_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
-var CONTRACT_VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)*$/;
-var MAX_ID_LENGTH = 64;
-var MAX_SOURCE_LENGTH = 128;
-var MAX_SUMMARY_LENGTH = 500;
-var MAX_SCOPES = 64;
-var MAX_SCOPE_LENGTH = 128;
-var OPS_PATH_PREFIX = "/_ops/";
-var OPS_PATH_BASE = "https://spfn.invalid";
-function unstableOpsPathBecause(path5) {
+// src/surface/command-path.ts
+var PATH_BASE = "https://spfn.invalid";
+function unstablePathBecause(path5, prefix) {
   let url;
   try {
-    url = new URL(path5, OPS_PATH_BASE);
+    url = new URL(path5, PATH_BASE);
   } catch {
     return "is not a valid URL path";
   }
-  if (url.origin !== OPS_PATH_BASE || url.search !== "" || url.hash !== "") {
+  if (url.origin !== PATH_BASE || url.search !== "" || url.hash !== "") {
     return "is not a plain absolute path";
   }
   if (url.pathname !== path5) {
     return "changes when URL-normalized";
   }
-  if (!url.pathname.startsWith(OPS_PATH_PREFIX)) {
-    return `is outside ${OPS_PATH_PREFIX}`;
+  if (!url.pathname.startsWith(prefix)) {
+    return `is outside ${prefix}`;
   }
   const slashCount = (path5.match(/\//g) ?? []).length;
   let decoded = path5;
@@ -6433,129 +6376,6 @@ function unstableOpsPathBecause(path5) {
   }
   return "uses too many percent-encoding layers";
 }
-function unusableBecause(command) {
-  if (typeof command?.name !== "string" || command.name.length === 0) {
-    return "it has no name";
-  }
-  if (typeof command.method !== "string" || !OPS_METHODS.has(command.method)) {
-    return `its method is ${JSON.stringify(command.method)}`;
-  }
-  if (typeof command.path !== "string") {
-    return `its path ${JSON.stringify(command.path)} is not a string`;
-  }
-  const pathReason = unstableOpsPathBecause(command.path);
-  if (pathReason !== null) {
-    return `its path ${JSON.stringify(command.path)} ${pathReason}`;
-  }
-  return null;
-}
-function usableCommands(commands, moduleIds) {
-  const usable = [];
-  for (const command of commands) {
-    const reason = unusableBecause(command);
-    if (reason !== null) {
-      console.error(`\u26A0\uFE0F  Ignoring an ops command the manifest announced: ${reason}.`);
-      continue;
-    }
-    const normalized = {
-      name: command.name,
-      method: command.method,
-      path: command.path,
-      input: isPlainObject(command.input) ? command.input : {}
-    };
-    const metadataReason = unusableModuleMetadataBecause(command, moduleIds);
-    if (metadataReason === null && command.module !== void 0) {
-      normalized.module = command.module;
-      normalized.summary = command.summary;
-      normalized.effect = command.effect;
-      normalized.scopes = [...command.scopes];
-    } else if (metadataReason !== null) {
-      normalized.metadataRejected = true;
-      console.error(
-        `\u26A0\uFE0F  Ignoring module metadata for ops command "${plain(command.name)}": ${metadataReason}. Calling it will require --yes.`
-      );
-    }
-    usable.push(normalized);
-  }
-  return usable;
-}
-function unusableModuleMetadataBecause(command, moduleIds) {
-  const carriesMetadata = command.module !== void 0 || command.summary !== void 0 || command.effect !== void 0 || command.scopes !== void 0;
-  if (!carriesMetadata) {
-    return null;
-  }
-  if (typeof command.module !== "string" || !moduleIds.has(command.module)) {
-    return "it names no usable module";
-  }
-  if (!command.name.startsWith(`${command.module}.`)) {
-    return "its qualified name does not start with the module id";
-  }
-  if (!command.path.startsWith(`${OPS_PATH_PREFIX}${command.module}/`)) {
-    return "its path is outside the module namespace";
-  }
-  if (typeof command.summary !== "string" || command.summary.length === 0 || command.summary.length > MAX_SUMMARY_LENGTH) {
-    return "its summary is missing or too long";
-  }
-  if (typeof command.effect !== "string" || !OPS_EFFECTS.has(command.effect)) {
-    return "its effect is unknown";
-  }
-  if (!Array.isArray(command.scopes) || command.scopes.length === 0 || command.scopes.length > MAX_SCOPES || command.scopes.some((scope) => typeof scope !== "string" || scope.length === 0 || scope.length > MAX_SCOPE_LENGTH)) {
-    return "its scopes are missing or invalid";
-  }
-  return null;
-}
-function usableModules(value) {
-  if (value === void 0) {
-    return [];
-  }
-  if (!Array.isArray(value)) {
-    console.error("\u26A0\uFE0F  Ignoring ops module metadata: modules is not an array.");
-    return [];
-  }
-  const modules = [];
-  const claimed = /* @__PURE__ */ new Set();
-  for (const raw of value) {
-    const reason = unusableModuleBecause(raw, claimed);
-    if (reason !== null) {
-      console.error(`\u26A0\uFE0F  Ignoring an ops module the manifest announced: ${reason}.`);
-      continue;
-    }
-    const module = raw;
-    claimed.add(module.id);
-    modules.push({
-      id: module.id,
-      source: module.source,
-      contractVersion: module.contractVersion,
-      summary: module.summary
-    });
-  }
-  return modules;
-}
-function unusableModuleBecause(value, claimed) {
-  if (!isPlainObject(value)) {
-    return "it is not an object";
-  }
-  const id = value.id;
-  if (typeof id !== "string" || id.length > MAX_ID_LENGTH || !MODULE_ID.test(id)) {
-    return "its id is invalid";
-  }
-  if (claimed.has(id)) {
-    return `id "${id}" is duplicated`;
-  }
-  if (typeof value.source !== "string" || value.source.length === 0 || value.source.length > MAX_SOURCE_LENGTH) {
-    return `module "${id}" has an invalid source`;
-  }
-  if (typeof value.contractVersion !== "string" || !CONTRACT_VERSION.test(value.contractVersion)) {
-    return `module "${id}" has an invalid contract version`;
-  }
-  if (typeof value.summary !== "string" || value.summary.length === 0 || value.summary.length > MAX_SUMMARY_LENGTH) {
-    return `module "${id}" has an invalid summary`;
-  }
-  return null;
-}
-function isPlainObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 function climbsOutOfItsSegment(value) {
   let decoded = value;
   for (let depth = 0; depth < 8; depth++) {
@@ -6575,10 +6395,10 @@ function climbsOutOfItsSegment(value) {
   }
   return true;
 }
-function buildCommandPath(command, params, query) {
-  const templateReason = unstableOpsPathBecause(command.path);
+function buildCommandPath(command, params, query, namespace) {
+  const templateReason = unstablePathBecause(command.path, `${namespace}/`);
   if (templateReason !== null) {
-    throw new Error(`Refusing ops command path ${JSON.stringify(command.path)} because it ${templateReason}.`);
+    throw new Error(`Refusing command path ${JSON.stringify(command.path)} because it ${templateReason}.`);
   }
   const path5 = command.path.replace(/:([A-Za-z0-9_]+)/g, (_match, name) => {
     const value = params[name];
@@ -6598,12 +6418,13 @@ function buildCommandPath(command, params, query) {
   const search = new URLSearchParams(query).toString();
   return search.length > 0 ? `${path5}?${search}` : path5;
 }
-async function invokeOpsCommand(appUrl, token, command, input) {
-  const path5 = buildCommandPath(command, input.params, input.query);
-  return await request(appUrl, token, command.method, path5, input.body);
+
+// src/surface/plain.ts
+function plain(value) {
+  return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "?");
 }
 
-// src/utils/ops/describe.ts
+// src/surface/describe.ts
 var SECTIONS = [
   { key: "params", label: "path parameters", flag: "--param" },
   { key: "query", label: "query parameters", flag: "--query" },
@@ -6695,7 +6516,7 @@ function renderSection(label, flag, rows) {
   }
   return lines;
 }
-function renderCommandUsage(command) {
+function renderCommandUsage(command, invoke) {
   const lines = [`${plain(command.name)}  ${command.method} ${plain(command.path)}`, ""];
   let described = false;
   if (command.summary) {
@@ -6720,8 +6541,10 @@ function renderCommandUsage(command) {
   if (!described) {
     lines.push("  Takes no input.", "");
   }
-  lines.push(`  Invoke: spfn ops call ${plain(command.name)}${exampleFlags(command)}`);
-  return lines.join("\n");
+  if (invoke !== void 0) {
+    lines.push(`  Invoke: ${invoke} ${plain(command.name)}${exampleFlags(command)}`);
+  }
+  return lines.join("\n").replace(/\n+$/, "");
 }
 function exampleFlags(command) {
   const parts = [];
@@ -6739,6 +6562,324 @@ function exampleFlags(command) {
   return parts.join("");
 }
 
+// src/surface/manifest-trust.ts
+function trustedManifest(body, reader) {
+  const manifest = body;
+  if (manifest?.manifestVersion !== 1 || !Array.isArray(manifest.commands)) {
+    throw new Error("The manifest answer has an unknown shape.");
+  }
+  const modules = usableModules(manifest.modules, reader);
+  return {
+    manifestVersion: 1,
+    ...manifest.modules !== void 0 ? { modules } : {},
+    commands: usableCommands(manifest.commands, new Set(modules.map((module) => module.id)), reader)
+  };
+}
+var METHODS = /* @__PURE__ */ new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+var EFFECTS = /* @__PURE__ */ new Set(["read", "write", "destructive"]);
+var MODULE_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+var CONTRACT_VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)*$/;
+var MAX_ID_LENGTH = 64;
+var MAX_SOURCE_LENGTH = 128;
+var MAX_SUMMARY_LENGTH = 500;
+var MAX_SCOPES = 64;
+var MAX_SCOPE_LENGTH = 128;
+function unusableBecause(command, reader) {
+  if (typeof command?.name !== "string" || command.name.length === 0) {
+    return "it has no name";
+  }
+  if (typeof command.method !== "string" || !METHODS.has(command.method)) {
+    return `its method is ${JSON.stringify(command.method)}`;
+  }
+  if (typeof command.path !== "string") {
+    return `its path ${JSON.stringify(command.path)} is not a string`;
+  }
+  const pathReason = unstablePathBecause(command.path, reader.prefix);
+  if (pathReason !== null) {
+    return `its path ${JSON.stringify(command.path)} ${pathReason}`;
+  }
+  return null;
+}
+function usableCommands(commands, moduleIds, reader) {
+  const usable = [];
+  for (const command of commands) {
+    const reason = unusableBecause(command, reader);
+    if (reason !== null) {
+      reader.warn(
+        `Ignoring a command the ${reader.namespace} manifest announced: ${reason}.`,
+        { kind: "command", reason }
+      );
+      continue;
+    }
+    const normalized = {
+      name: command.name,
+      method: command.method,
+      path: command.path,
+      input: isPlainObject(command.input) ? command.input : {}
+    };
+    const metadataReason = unusableModuleMetadataBecause(command, moduleIds, reader);
+    if (metadataReason === null && command.module !== void 0) {
+      normalized.module = command.module;
+      normalized.summary = command.summary;
+      normalized.effect = command.effect;
+      normalized.scopes = [...command.scopes];
+    } else if (metadataReason !== null) {
+      normalized.metadataRejected = true;
+      reader.warn(
+        `Ignoring module metadata for command "${plain(command.name)}": ${metadataReason}. Its effect is unknown, so treat it as destructive.`,
+        { kind: "metadata", command: command.name, reason: metadataReason }
+      );
+    }
+    usable.push(normalized);
+  }
+  return usable;
+}
+function unusableModuleMetadataBecause(command, moduleIds, reader) {
+  const carriesMetadata = command.module !== void 0 || command.summary !== void 0 || command.effect !== void 0 || command.scopes !== void 0;
+  if (!carriesMetadata) {
+    return null;
+  }
+  if (typeof command.module !== "string" || !moduleIds.has(command.module)) {
+    return "it names no usable module";
+  }
+  if (!command.name.startsWith(`${command.module}.`)) {
+    return "its qualified name does not start with the module id";
+  }
+  if (!command.path.startsWith(`${reader.prefix}${command.module}/`)) {
+    return "its path is outside the module namespace";
+  }
+  if (typeof command.summary !== "string" || command.summary.length === 0 || command.summary.length > MAX_SUMMARY_LENGTH) {
+    return "its summary is missing or too long";
+  }
+  if (typeof command.effect !== "string" || !EFFECTS.has(command.effect)) {
+    return "its effect is unknown";
+  }
+  if (!Array.isArray(command.scopes) || command.scopes.length === 0 || command.scopes.length > MAX_SCOPES || command.scopes.some((scope) => typeof scope !== "string" || scope.length === 0 || scope.length > MAX_SCOPE_LENGTH)) {
+    return "its scopes are missing or invalid";
+  }
+  return null;
+}
+function usableModules(value, reader) {
+  if (value === void 0) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    reader.warn("Ignoring module metadata: modules is not an array.", {
+      kind: "modules",
+      reason: "modules is not an array"
+    });
+    return [];
+  }
+  const modules = [];
+  const claimed = /* @__PURE__ */ new Set();
+  for (const raw of value) {
+    const reason = unusableModuleBecause(raw, claimed);
+    if (reason !== null) {
+      reader.warn(
+        `Ignoring a module the ${reader.namespace} manifest announced: ${reason}.`,
+        { kind: "module", reason }
+      );
+      continue;
+    }
+    const module = raw;
+    claimed.add(module.id);
+    modules.push({
+      id: module.id,
+      source: module.source,
+      contractVersion: module.contractVersion,
+      summary: module.summary
+    });
+  }
+  return modules;
+}
+function unusableModuleBecause(value, claimed) {
+  if (!isPlainObject(value)) {
+    return "it is not an object";
+  }
+  const id = value.id;
+  if (typeof id !== "string" || id.length > MAX_ID_LENGTH || !MODULE_ID.test(id)) {
+    return "its id is invalid";
+  }
+  if (claimed.has(id)) {
+    return `id "${id}" is duplicated`;
+  }
+  if (typeof value.source !== "string" || value.source.length === 0 || value.source.length > MAX_SOURCE_LENGTH) {
+    return `module "${id}" has an invalid source`;
+  }
+  if (typeof value.contractVersion !== "string" || !CONTRACT_VERSION.test(value.contractVersion)) {
+    return `module "${id}" has an invalid contract version`;
+  }
+  if (typeof value.summary !== "string" || value.summary.length === 0 || value.summary.length > MAX_SUMMARY_LENGTH) {
+    return `module "${id}" has an invalid summary`;
+  }
+  return null;
+}
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// src/surface/transport.ts
+function isLoopback(hostname3) {
+  return hostname3 === "localhost" || hostname3 === "127.0.0.1" || hostname3 === "[::1]" || hostname3.endsWith(".localhost");
+}
+function transportRefusalOf(url) {
+  if (url.protocol === "https:" || url.protocol === "http:" && isLoopback(url.hostname)) {
+    return null;
+  }
+  return url.protocol === "http:" ? "cleartext-http" : "not-http";
+}
+function parseAppUrl(appUrl) {
+  try {
+    return new URL(appUrl);
+  } catch {
+    return null;
+  }
+}
+function assertTransportSafe(appUrl) {
+  const url = parseAppUrl(appUrl);
+  if (url === null) {
+    throw new Error(`Invalid app URL: ${appUrl}`);
+  }
+  const refusal = transportRefusalOf(url);
+  if (refusal === "cleartext-http") {
+    throw new Error(`Refusing to talk to ${appUrl} over http: a credential would cross it in the clear. Use https. http is allowed only against localhost.`);
+  }
+  if (refusal === "not-http") {
+    throw new Error(`App URL must be https, got "${url.protocol}//". http is allowed only against localhost.`);
+  }
+}
+
+// src/surface/client.ts
+var NAMESPACE = /^(?:\/[A-Za-z0-9_-]+)+$/;
+var SurfaceManifestError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "SurfaceManifestError";
+  }
+};
+function joinUrl(appUrl, path5) {
+  return appUrl.replace(/\/+$/, "") + path5;
+}
+async function request(appUrl, token, method, path5, body) {
+  const response = await fetch(joinUrl(appUrl, path5), {
+    method,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      ...body !== void 0 ? { "Content-Type": "application/json" } : {}
+    },
+    ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+  });
+  const text = await response.text();
+  let parsed = text;
+  try {
+    parsed = text.length > 0 ? JSON.parse(text) : null;
+  } catch {
+  }
+  return { status: response.status, body: parsed };
+}
+function manifestRefusal(namespace, status) {
+  if (status === 401 || status === 403) {
+    return new SurfaceManifestError(`The app refused the token (GET ${namespace}/_manifest answered ${status}).`, status);
+  }
+  if (status === 404) {
+    return new SurfaceManifestError(`No surface at ${namespace} on this app (GET ${namespace}/_manifest answered 404).`, status);
+  }
+  return new SurfaceManifestError(`Manifest request failed with status ${status}.`, status);
+}
+function assertNamespace(namespace) {
+  if (typeof namespace !== "string" || !NAMESPACE.test(namespace)) {
+    throw new Error(
+      `Surface namespace ${JSON.stringify(namespace)} is invalid. Use an absolute path of [A-Za-z0-9_-] segments without a trailing slash, such as "/_app".`
+    );
+  }
+}
+function findCommand(manifest, name) {
+  const command = manifest.commands.find((candidate) => candidate.name === name);
+  if (!command) {
+    throw new Error(`Unknown command "${plain(name)}".`);
+  }
+  return command;
+}
+function createSurfaceClient(options) {
+  assertTransportSafe(options.appUrl);
+  assertNamespace(options.namespace);
+  const { appUrl, namespace } = options;
+  const token = async () => typeof options.token === "function" ? await options.token() : options.token;
+  const reader = { namespace, prefix: `${namespace}/`, warn: options.onWarning ?? (() => void 0) };
+  const manifest = async () => {
+    const { status, body } = await request(appUrl, await token(), "GET", `${namespace}/_manifest`);
+    if (status !== 200) {
+      throw manifestRefusal(namespace, status);
+    }
+    return trustedManifest(body, reader);
+  };
+  const invoke = async (command, input) => {
+    const path5 = buildCommandPath(command, input.params, input.query, namespace);
+    return await request(appUrl, await token(), command.method, path5, input.body);
+  };
+  return {
+    manifest,
+    invoke,
+    describe: (fetched, name) => renderCommandUsage(findCommand(fetched, name)),
+    call: async (name, input) => await invoke(findCommand(await manifest(), name), input)
+  };
+}
+
+// src/utils/ops/client.ts
+var OPS_NAMESPACE = "/_ops";
+function printOpsWarning(_message, warning) {
+  switch (warning.kind) {
+    case "command":
+      console.error(`\u26A0\uFE0F  Ignoring an ops command the manifest announced: ${warning.reason}.`);
+      break;
+    case "metadata":
+      console.error(
+        `\u26A0\uFE0F  Ignoring module metadata for ops command "${plain(warning.command)}": ${warning.reason}. Calling it will require --yes.`
+      );
+      break;
+    case "modules":
+      console.error(`\u26A0\uFE0F  Ignoring ops module metadata: ${warning.reason}.`);
+      break;
+    case "module":
+      console.error(`\u26A0\uFE0F  Ignoring an ops module the manifest announced: ${warning.reason}.`);
+      break;
+  }
+}
+function opsClient(appUrl, token) {
+  return createSurfaceClient({ appUrl, namespace: OPS_NAMESPACE, token, onWarning: printOpsWarning });
+}
+function inOpsTerms(error) {
+  if (!(error instanceof SurfaceManifestError)) {
+    return error;
+  }
+  if (error.status === 401 || error.status === 403) {
+    return new Error("The app refused the ops token (check --token / SPFN_OPS_TOKEN / keychain).");
+  }
+  if (error.status === 404) {
+    return new Error("No ops surface at this app (GET /_ops/_manifest answered 404). Mount one with createOpsRouter() and .packages([opsRouter]).");
+  }
+  return error;
+}
+async function fetchOpsManifest(appUrl, token) {
+  return await opsClient(appUrl, token).manifest().catch((error) => Promise.reject(inOpsTerms(error)));
+}
+function assertOpsCommandPath(command) {
+  const templateReason = unstablePathBecause(command.path, `${OPS_NAMESPACE}/`);
+  if (templateReason !== null) {
+    throw new Error(`Refusing ops command path ${JSON.stringify(command.path)} because it ${templateReason}.`);
+  }
+}
+async function invokeOpsCommand(appUrl, token, command, input) {
+  assertOpsCommandPath(command);
+  return await opsClient(appUrl, token).invoke(command, input);
+}
+
+// src/utils/ops/describe.ts
+function renderCommandUsage2(command) {
+  return renderCommandUsage(command, "spfn ops call");
+}
+
 // src/commands/ops/resolve.ts
 import chalk33 from "chalk";
 
@@ -6811,14 +6952,12 @@ function deleteOpsToken(account) {
 }
 
 // src/commands/ops/resolve.ts
-function isLoopback(hostname3) {
-  return hostname3 === "localhost" || hostname3 === "127.0.0.1" || hostname3 === "[::1]" || hostname3.endsWith(".localhost");
-}
-function assertTransportSafe(parsed, appUrl) {
-  if (parsed.protocol === "https:" || parsed.protocol === "http:" && isLoopback(parsed.hostname)) {
+function assertTransportSafe2(parsed, appUrl) {
+  const refusal = transportRefusalOf(parsed);
+  if (refusal === null) {
     return;
   }
-  if (parsed.protocol === "http:") {
+  if (refusal === "cleartext-http") {
     console.error(chalk33.red(`\u274C Refusing to talk to ${appUrl} over http.`));
     console.error(chalk33.gray("   An administrator password and an ops token cross this connection, and http sends both in the clear."));
     console.error(chalk33.gray("   Use https. http is allowed only against localhost."));
@@ -6841,7 +6980,7 @@ function resolveAppUrl(options) {
     console.error(chalk33.red(`\u274C Invalid app URL: ${appUrl}`));
     process.exit(1);
   }
-  assertTransportSafe(parsed, appUrl);
+  assertTransportSafe2(parsed, appUrl);
   return appUrl;
 }
 function appAccount(appUrl) {
@@ -7245,7 +7384,7 @@ async function callCommand(name, options) {
     process.exit(1);
   }
   if (options.describe) {
-    console.log(options.json ? JSON.stringify(command, null, 2) : renderCommandUsage(command));
+    console.log(options.json ? JSON.stringify(command, null, 2) : renderCommandUsage2(command));
     return;
   }
   if (destructiveConfirmationRequired(command, options.yes)) {