spfn 0.3.0-beta.13 → 0.3.0-beta.15

package/dist/surface.js

@@ -0,0 +1,497 @@
+// src/surface/command-path.ts
+var PATH_BASE = "https://spfn.invalid";
+function unstablePathBecause(path, prefix) {
+  let url;
+  try {
+    url = new URL(path, PATH_BASE);
+  } catch {
+    return "is not a valid URL path";
+  }
+  if (url.origin !== PATH_BASE || url.search !== "" || url.hash !== "") {
+    return "is not a plain absolute path";
+  }
+  if (url.pathname !== path) {
+    return "changes when URL-normalized";
+  }
+  if (!url.pathname.startsWith(prefix)) {
+    return `is outside ${prefix}`;
+  }
+  const slashCount = (path.match(/\//g) ?? []).length;
+  let decoded = path;
+  for (let depth = 0; depth < 8; depth++) {
+    let next;
+    try {
+      next = decodeURIComponent(decoded);
+    } catch {
+      return "contains malformed percent encoding";
+    }
+    if (next.includes("\\") || (next.match(/\//g) ?? []).length !== slashCount || next.split("/").some((segment) => segment === "." || segment === "..")) {
+      return "contains encoded path separators or dot segments";
+    }
+    if (next === decoded) {
+      return null;
+    }
+    decoded = next;
+  }
+  return "uses too many percent-encoding layers";
+}
+function climbsOutOfItsSegment(value) {
+  let decoded = value;
+  for (let depth = 0; depth < 8; depth++) {
+    if (decoded.split(/[/\\]/).some((part) => part === "." || part === "..")) {
+      return true;
+    }
+    let next;
+    try {
+      next = decodeURIComponent(decoded);
+    } catch {
+      return false;
+    }
+    if (next === decoded) {
+      return false;
+    }
+    decoded = next;
+  }
+  return true;
+}
+function buildCommandPath(command, params, query, namespace) {
+  const templateReason = unstablePathBecause(command.path, `${namespace}/`);
+  if (templateReason !== null) {
+    throw new Error(`Refusing command path ${JSON.stringify(command.path)} because it ${templateReason}.`);
+  }
+  const path = command.path.replace(/:([A-Za-z0-9_]+)/g, (_match, name) => {
+    const value = params[name];
+    if (value === void 0) {
+      throw new Error(`Missing path parameter "${name}" (pass --param ${name}=<value>).`);
+    }
+    if (value === "") {
+      throw new Error(`Path parameter "${name}" cannot be empty.`);
+    }
+    if (climbsOutOfItsSegment(value)) {
+      throw new Error(
+        `Path parameter "${name}" contains dot segments and cannot be sent: ${JSON.stringify(value)}.`
+      );
+    }
+    return encodeURIComponent(value);
+  });
+  const search = new URLSearchParams(query).toString();
+  return search.length > 0 ? `${path}?${search}` : path;
+}
+
+// src/surface/plain.ts
+function plain(value) {
+  return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "?");
+}
+
+// src/surface/describe.ts
+var SECTIONS = [
+  { key: "params", label: "path parameters", flag: "--param" },
+  { key: "query", label: "query parameters", flag: "--query" },
+  { key: "body", label: "body fields", flag: "--data" }
+];
+function isSchema(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+var MAX_SCHEMA_DEPTH = 12;
+function typeName(schema) {
+  if (Array.isArray(schema.enum)) {
+    return schema.enum.every((v) => typeof v === "string") ? "string" : "value";
+  }
+  const variants = schema.anyOf ?? schema.oneOf;
+  if (Array.isArray(variants)) {
+    const names = variants.filter(isSchema).map(typeName).filter((name) => name !== "null");
+    return [...new Set(names)].join("|") || "value";
+  }
+  const type = schema.type;
+  if (Array.isArray(type)) {
+    return type.filter((t) => t !== "null").join("|") || "value";
+  }
+  if (type === "array") {
+    return isSchema(schema.items) ? `${typeName(schema.items)}[]` : "array";
+  }
+  return typeof type === "string" ? type : "value";
+}
+function constraintNotes(schema) {
+  const notes = [];
+  if (Array.isArray(schema.enum)) {
+    notes.push(`one of: ${schema.enum.map((v) => String(v)).join(", ")}`);
+  }
+  const min = schema.minimum ?? schema.minLength ?? schema.minItems;
+  const max = schema.maximum ?? schema.maxLength ?? schema.maxItems;
+  if (min !== void 0 && max !== void 0) {
+    notes.push(`${min}\u2013${max}`);
+  } else if (min !== void 0) {
+    notes.push(`min ${min}`);
+  } else if (max !== void 0) {
+    notes.push(`max ${max}`);
+  }
+  if (typeof schema.format === "string") {
+    notes.push(schema.format);
+  }
+  if (typeof schema.pattern === "string") {
+    notes.push(`matches ${schema.pattern}`);
+  }
+  if (schema.default !== void 0) {
+    notes.push(`default ${JSON.stringify(schema.default)}`);
+  }
+  if (typeof schema.description === "string" && schema.description.length > 0) {
+    notes.push(schema.description);
+  }
+  return notes;
+}
+function collectFields(schema, prefix = "", depth = 0) {
+  const properties = isSchema(schema.properties) ? schema.properties : {};
+  const required = Array.isArray(schema.required) ? schema.required : [];
+  const rows = [];
+  for (const [name, raw] of Object.entries(properties)) {
+    if (!isSchema(raw)) {
+      continue;
+    }
+    const path = prefix ? `${prefix}.${plain(name)}` : plain(name);
+    const nested = isSchema(raw.properties) && depth < MAX_SCHEMA_DEPTH ? collectFields(raw, path, depth + 1) : [];
+    if (nested.length > 0) {
+      rows.push(...nested);
+      continue;
+    }
+    rows.push({
+      name: path,
+      type: plain(typeName(raw)),
+      requirement: required.includes(name) ? "required" : "optional",
+      notes: plain(constraintNotes(raw).join(", "))
+    });
+  }
+  return rows;
+}
+function pad(value, width) {
+  return value + " ".repeat(Math.max(0, width - value.length));
+}
+function renderSection(label, flag, rows) {
+  const nameWidth = Math.max(...rows.map((r) => r.name.length));
+  const typeWidth = Math.max(...rows.map((r) => r.type.length));
+  const lines = [`  ${label} (${flag})`];
+  for (const row of rows) {
+    const notes = row.notes.length > 0 ? `  ${row.notes}` : "";
+    lines.push(`    ${pad(row.name, nameWidth)}  ${pad(row.type, typeWidth)}  ${pad(row.requirement, 8)}${notes}`.trimEnd());
+  }
+  return lines;
+}
+function renderCommandUsage(command, invoke) {
+  const lines = [`${plain(command.name)}  ${command.method} ${plain(command.path)}`, ""];
+  let described = false;
+  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)"}`, "");
+  }
+  for (const section of SECTIONS) {
+    const schema = command.input[section.key];
+    if (!isSchema(schema)) {
+      continue;
+    }
+    const rows = collectFields(schema);
+    if (rows.length === 0) {
+      continue;
+    }
+    lines.push(...renderSection(section.label, section.flag, rows), "");
+    described = true;
+  }
+  if (!described) {
+    lines.push("  Takes no input.", "");
+  }
+  if (invoke !== void 0) {
+    lines.push(`  Invoke: ${invoke} ${plain(command.name)}${exampleFlags(command)}`);
+  }
+  return lines.join("\n").replace(/\n+$/, "");
+}
+function exampleFlags(command) {
+  const parts = [];
+  for (const section of SECTIONS) {
+    const schema = command.input[section.key];
+    if (!isSchema(schema)) {
+      continue;
+    }
+    const [first] = collectFields(schema);
+    if (!first) {
+      continue;
+    }
+    parts.push(section.key === "body" ? ` --data '{"${first.name}": ...}'` : ` ${section.flag} ${first.name}=<value>`);
+  }
+  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(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname.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, path) {
+  return appUrl.replace(/\/+$/, "") + path;
+}
+async function request(appUrl, token, method, path, body) {
+  const response = await fetch(joinUrl(appUrl, path), {
+    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 path = buildCommandPath(command, input.params, input.query, namespace);
+    return await request(appUrl, await token(), command.method, path, input.body);
+  };
+  return {
+    manifest,
+    invoke,
+    describe: (fetched, name) => renderCommandUsage(findCommand(fetched, name)),
+    call: async (name, input) => await invoke(findCommand(await manifest(), name), input)
+  };
+}
+export {
+  SurfaceManifestError,
+  assertTransportSafe,
+  buildCommandPath,
+  createSurfaceClient,
+  isLoopback,
+  joinUrl,
+  plain,
+  renderCommandUsage,
+  transportRefusalOf
+};

package/package.json

@@ -1,12 +1,25 @@
 {
   "name": "spfn",
-  "version": "0.3.0-beta.13",
+  "version": "0.3.0-beta.15",
   "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": {
     "spfn": "bin/spfn.js"
   },
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./surface": {
+      "types": "./dist/surface.d.ts",
+      "import": "./dist/surface.js",
+      "require": "./dist/surface.js"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist",
     "bin"