spfn 0.3.0-beta.15 → 0.3.0-beta.16

package/README.md

@@ -635,6 +635,12 @@ spfn ops list --module ledger                         # just that module's comma
 spfn ops call ledger.compact --yes                    # effect=destructive needs this
 ```
 
+An app's own command can carry an effect and a summary too, declared on its route with
+`.effect()` and `.summary()`; `spfn ops list` and `--describe` show them, and an app command
+announcing `read` or `write` needs no `--yes`. A CLI at 0.3.0-beta.15 or older does not
+know app commands carry them: it warns that such a command "names no usable module" and
+asks for `--yes` on it, so upgrade the CLI together with `@spfn/core`.
+
 `spfn ops call` refuses a command the app declared `effect: destructive` unless `--yes` is
 given. It refuses the same way when the app announced module metadata this CLI could not
 validate: the effect is then unknown rather than absent, and an unknown effect is not
@@ -707,8 +713,10 @@ const answer = await client.call('pageAdd', { params: {}, query: {}, body: { tit
 // 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
+Each command carries the `effect` and `summary` the app declared, so your code can tell a
+read from a write before it calls; `call()` itself makes no decision on them. It keeps
+every check `spfn ops` makes: the manifest's shape, each command's path staying under
+`<namespace>/`, module and command 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

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.15";
+    return "0.3.0-beta.16";
   }
   return fromPackageJson ?? (fromPackageJson = readPackageVersion());
 }
@@ -6522,10 +6522,7 @@ function renderCommandUsage(command, invoke) {
   if (command.summary) {
     lines.push(`  ${plain(command.summary)}`, "");
   }
-  if (command.effect || command.scopes) {
-    lines.push(`  Effect: ${command.effect ?? "unknown"}`);
-    lines.push(`  Scopes: ${command.scopes?.map(plain).join(", ") || "(not declared)"}`, "");
-  }
+  lines.push(...metadataLines(command));
   for (const section of SECTIONS) {
     const schema = command.input[section.key];
     if (!isSchema(schema)) {
@@ -6546,6 +6543,16 @@ function renderCommandUsage(command, invoke) {
   }
   return lines.join("\n").replace(/\n+$/, "");
 }
+function metadataLines(command) {
+  if (!command.effect && !command.scopes) {
+    return [];
+  }
+  const lines = [`  Effect: ${command.effect ?? "unknown"}`];
+  if (command.module !== void 0 || command.scopes !== void 0) {
+    lines.push(`  Scopes: ${command.scopes?.map(plain).join(", ") || "(not declared)"}`);
+  }
+  return [...lines, ""];
+}
 function exampleFlags(command) {
   const parts = [];
   for (const section of SECTIONS) {
@@ -6611,34 +6618,66 @@ function usableCommands(commands, moduleIds, reader) {
       );
       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);
+    usable.push(withMetadata(command, moduleIds, reader));
   }
   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;
+function withMetadata(command, moduleIds, reader) {
+  const normalized = {
+    name: command.name,
+    method: command.method,
+    path: command.path,
+    input: isPlainObject(command.input) ? command.input : {}
+  };
+  if (command.module !== void 0 || command.scopes !== void 0) {
+    return withModuleMetadata(normalized, command, moduleIds, reader);
+  }
+  return withAppMetadata(normalized, command, reader);
+}
+function withModuleMetadata(normalized, command, moduleIds, reader) {
+  const reason = unusableModuleMetadataBecause(command, moduleIds, reader);
+  if (reason !== null) {
+    return rejectedMetadata(normalized, "module", reason, reader);
+  }
+  return {
+    ...normalized,
+    module: command.module,
+    summary: command.summary,
+    effect: command.effect,
+    scopes: [...command.scopes]
+  };
+}
+function withAppMetadata(normalized, command, reader) {
+  const reason = unusableAppMetadataBecause(command);
+  if (reason !== null) {
+    return rejectedMetadata(normalized, "command", reason, reader);
   }
+  return {
+    ...normalized,
+    ...command.summary !== void 0 ? { summary: command.summary } : {},
+    ...command.effect !== void 0 ? { effect: command.effect } : {}
+  };
+}
+function rejectedMetadata(normalized, metadata, reason, reader) {
+  reader.warn(
+    `Ignoring ${metadata} metadata for command "${plain(normalized.name)}": ${reason}. Its effect is unknown, so treat it as destructive.`,
+    { kind: "metadata", command: normalized.name, metadata, reason }
+  );
+  return { ...normalized, metadataRejected: true };
+}
+function unusableAppMetadataBecause(command) {
+  if (command.summary !== void 0 && !isUsableSummary(command.summary)) {
+    return "its summary is empty or too long";
+  }
+  if (command.effect !== void 0 && !EFFECTS.has(command.effect)) {
+    return "its effect is unknown";
+  }
+  return null;
+}
+function isUsableSummary(summary) {
+  return typeof summary === "string" && summary.length > 0 && summary.length <= MAX_SUMMARY_LENGTH;
+}
+function unusableModuleMetadataBecause(command, moduleIds, reader) {
   if (typeof command.module !== "string" || !moduleIds.has(command.module)) {
     return "it names no usable module";
   }
@@ -6648,7 +6687,7 @@ function unusableModuleMetadataBecause(command, moduleIds, reader) {
   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) {
+  if (!isUsableSummary(command.summary)) {
     return "its summary is missing or too long";
   }
   if (typeof command.effect !== "string" || !EFFECTS.has(command.effect)) {
@@ -6835,7 +6874,7 @@ function printOpsWarning(_message, warning) {
       break;
     case "metadata":
       console.error(
-        `\u26A0\uFE0F  Ignoring module metadata for ops command "${plain(warning.command)}": ${warning.reason}. Calling it will require --yes.`
+        `\u26A0\uFE0F  Ignoring ${warning.metadata ?? "module"} metadata for ops command "${plain(warning.command)}": ${warning.reason}. Calling it will require --yes.`
       );
       break;
     case "modules":

package/dist/surface.d.ts

@@ -57,13 +57,18 @@ interface SurfaceResponse {
  * terminal.
  */
 
-/** What the client dropped from a manifest, and why. */
+/**
+ * What the client dropped from a manifest, and why. A `metadata` warning says
+ * whose rules refused it: a module command's, or an app command's own
+ * `effect` and `summary`.
+ */
 type SurfaceWarning = {
     kind: 'command';
     reason: string;
 } | {
     kind: 'metadata';
     command: string;
+    metadata?: 'module' | 'command';
     reason: string;
 } | {
     kind: 'modules';

package/dist/surface.js

@@ -181,10 +181,7 @@ function renderCommandUsage(command, invoke) {
   if (command.summary) {
     lines.push(`  ${plain(command.summary)}`, "");
   }
-  if (command.effect || command.scopes) {
-    lines.push(`  Effect: ${command.effect ?? "unknown"}`);
-    lines.push(`  Scopes: ${command.scopes?.map(plain).join(", ") || "(not declared)"}`, "");
-  }
+  lines.push(...metadataLines(command));
   for (const section of SECTIONS) {
     const schema = command.input[section.key];
     if (!isSchema(schema)) {
@@ -205,6 +202,16 @@ function renderCommandUsage(command, invoke) {
   }
   return lines.join("\n").replace(/\n+$/, "");
 }
+function metadataLines(command) {
+  if (!command.effect && !command.scopes) {
+    return [];
+  }
+  const lines = [`  Effect: ${command.effect ?? "unknown"}`];
+  if (command.module !== void 0 || command.scopes !== void 0) {
+    lines.push(`  Scopes: ${command.scopes?.map(plain).join(", ") || "(not declared)"}`);
+  }
+  return [...lines, ""];
+}
 function exampleFlags(command) {
   const parts = [];
   for (const section of SECTIONS) {
@@ -270,34 +277,66 @@ function usableCommands(commands, moduleIds, reader) {
       );
       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);
+    usable.push(withMetadata(command, moduleIds, reader));
   }
   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;
+function withMetadata(command, moduleIds, reader) {
+  const normalized = {
+    name: command.name,
+    method: command.method,
+    path: command.path,
+    input: isPlainObject(command.input) ? command.input : {}
+  };
+  if (command.module !== void 0 || command.scopes !== void 0) {
+    return withModuleMetadata(normalized, command, moduleIds, reader);
+  }
+  return withAppMetadata(normalized, command, reader);
+}
+function withModuleMetadata(normalized, command, moduleIds, reader) {
+  const reason = unusableModuleMetadataBecause(command, moduleIds, reader);
+  if (reason !== null) {
+    return rejectedMetadata(normalized, "module", reason, reader);
+  }
+  return {
+    ...normalized,
+    module: command.module,
+    summary: command.summary,
+    effect: command.effect,
+    scopes: [...command.scopes]
+  };
+}
+function withAppMetadata(normalized, command, reader) {
+  const reason = unusableAppMetadataBecause(command);
+  if (reason !== null) {
+    return rejectedMetadata(normalized, "command", reason, reader);
+  }
+  return {
+    ...normalized,
+    ...command.summary !== void 0 ? { summary: command.summary } : {},
+    ...command.effect !== void 0 ? { effect: command.effect } : {}
+  };
+}
+function rejectedMetadata(normalized, metadata, reason, reader) {
+  reader.warn(
+    `Ignoring ${metadata} metadata for command "${plain(normalized.name)}": ${reason}. Its effect is unknown, so treat it as destructive.`,
+    { kind: "metadata", command: normalized.name, metadata, reason }
+  );
+  return { ...normalized, metadataRejected: true };
+}
+function unusableAppMetadataBecause(command) {
+  if (command.summary !== void 0 && !isUsableSummary(command.summary)) {
+    return "its summary is empty or too long";
+  }
+  if (command.effect !== void 0 && !EFFECTS.has(command.effect)) {
+    return "its effect is unknown";
   }
+  return null;
+}
+function isUsableSummary(summary) {
+  return typeof summary === "string" && summary.length > 0 && summary.length <= MAX_SUMMARY_LENGTH;
+}
+function unusableModuleMetadataBecause(command, moduleIds, reader) {
   if (typeof command.module !== "string" || !moduleIds.has(command.module)) {
     return "it names no usable module";
   }
@@ -307,7 +346,7 @@ function unusableModuleMetadataBecause(command, moduleIds, reader) {
   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) {
+  if (!isUsableSummary(command.summary)) {
     return "its summary is missing or too long";
   }
   if (typeof command.effect !== "string" || !EFFECTS.has(command.effect)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spfn",
-  "version": "0.3.0-beta.15",
+  "version": "0.3.0-beta.16",
   "description": "Scaffold a full-stack TypeScript backend onto a Next.js app built with an AI coding agent: auth, database, typed routes and codegen, one fixed vertical slice per feature",
   "type": "module",
   "bin": {