@spacefast/common 0.2.1 → 0.4.1

package/dist/contracts/zero-types.js

@@ -0,0 +1,263 @@
+/**
+ * The module `sf zero types` writes into a Zero project.
+ *
+ * Three things a project's types depend on live in the platform rather than in
+ * the project's own source, and each one is only knowable by asking: the
+ * content model the live version compiled, the Ability catalog that version
+ * publishes alongside the engine's own sets, and the database schema the broker
+ * validates against. A capsule author can read all three from the dashboard and
+ * retype them by hand; this prints them instead.
+ *
+ * The output is self-contained on purpose — no imports, because it lands in
+ * someone else's project where a dependency on `@spacefast/common` would be an
+ * imposition. That is the same rule `contentModelSdkModule` follows, and its
+ * output is embedded here verbatim rather than re-derived: it already prints
+ * exactly the content-model half of this file.
+ */
+import { createHash } from "node:crypto";
+import { contentModelSdkModule, printContentModelSchema } from "./content-model-sdk.js";
+import { contentAbilityTypeName } from "./content-model.js";
+/** Zero manages these three on every row; a capsule cannot declare them. */
+const MANAGED_ROW_COLUMNS = [
+    ["id", "string"],
+    ["createdAt", "string"],
+    ["updatedAt", "string"],
+];
+const JSON_VALUE_TYPE = "ZeroJsonValue";
+function tableTypeName(name) {
+    return `${contentAbilityTypeName(name)}Row`;
+}
+function columnType(column) {
+    const base = column.type === "json"
+        ? JSON_VALUE_TYPE
+        : column.type === "string"
+            ? "string"
+            : column.type === "number"
+                ? "number"
+                : "boolean";
+    return column.nullable ? `${base} | null` : base;
+}
+function propertyKey(name) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+/**
+ * The row type for one table, as a reader gets it back.
+ *
+ * The managed columns lead because they are on every row and the capsule never
+ * declared them, so a reader who did not write this table still knows what is
+ * there. The physical names the deployment assigns — the `sf_<space>_<table>_…`
+ * rewriting the control plane does — deliberately do not appear: they are
+ * plumbing, and a generated type that leaked them would break on a rename that
+ * changes nothing about the data.
+ */
+function printTable(table) {
+    const members = [
+        ...MANAGED_ROW_COLUMNS.map(([name, type]) => `  readonly ${name}: ${type};`),
+        ...table.columns.map((column) => `  readonly ${propertyKey(column.name)}: ${columnType(column)};`),
+    ];
+    return [
+        `/** A row of the \`${table.name}\` table. */`,
+        `export type ${tableTypeName(table.name)} = {`,
+        ...members,
+        "};",
+        "",
+    ];
+}
+/** How the catalog spells an Ability's authorization requirement in a doc comment. */
+function requirementSentence(ability) {
+    return ability.requires.kind === "wordpress"
+        ? `Requires the WordPress capability \`${ability.requires.capability}\`.`
+        : ability.requires.capabilities.length === 0
+            ? "Requires no Grant capability."
+            : `Requires the Grant ${ability.requires.capabilities.length === 1 ? "capability" : "capabilities"} ${ability.requires.capabilities.map((capability) => `\`${capability}\``).join(", ")}.`;
+}
+function printAbilityCatalog(abilities) {
+    if (abilities.length === 0) {
+        return [
+            "/** This Space publishes no Abilities. */",
+            "export type ZeroAbilityCatalog = Readonly<Record<string, never>>;",
+            "",
+            "export const zeroAbilityCatalog = {} as const;",
+            "",
+        ];
+    }
+    // The catalog keys every entry by product id, in both the type and the value.
+    // Two rows under one id would emit a duplicate key that fails to compile, so
+    // refuse to print a broken module and name the id instead. The control plane
+    // rejects a content Ability that collides with a platform one at compile, so
+    // reaching this is a malformed catalog rather than ordinary input.
+    const seenIds = new Set();
+    for (const ability of abilities) {
+        if (seenIds.has(ability.id)) {
+            throw new Error(`The Ability catalog lists ${JSON.stringify(ability.id)} twice.`);
+        }
+        seenIds.add(ability.id);
+    }
+    const lines = [
+        "/**",
+        " * Every Ability this Space publishes, keyed by product id.",
+        " *",
+        " * Two origins are merged here and both are callable the same way. The",
+        " * `zero-wp-users` and `zero-storage` sets come from the runtime engine and are",
+        " * there whatever the capsule declares; the `zero-content` set was compiled from",
+        " * the capsule and moves with a rollback.",
+        " */",
+        "export type ZeroAbilityCatalog = {",
+    ];
+    for (const ability of abilities) {
+        const requires = ability.requires.kind === "wordpress"
+            ? `{ readonly kind: "wordpress"; readonly capability: ${JSON.stringify(ability.requires.capability)} }`
+            : `{ readonly kind: "grant"; readonly capabilities: readonly [${ability.requires.capabilities.map((capability) => JSON.stringify(capability)).join(", ")}] }`;
+        lines.push(`  /** ${requirementSentence(ability)} */`, `  ${JSON.stringify(ability.id)}: {`, `    readonly input: ${ability.inputSchema === null ? "unknown" : printContentModelSchema(ability.inputSchema)};`, `    readonly output: ${ability.outputSchema === null ? "unknown" : printContentModelSchema(ability.outputSchema)};`, `    readonly mode: ${JSON.stringify(ability.mode)};`, `    readonly requires: ${requires};`, "  };");
+    }
+    lines.push("};", "");
+    lines.push("/** The same catalog as a value, for dispatching by name. */", "export const zeroAbilityCatalog = {", ...abilities.map((ability) => `  ${JSON.stringify(ability.id)}: ${JSON.stringify({
+        name: ability.name,
+        category: ability.category,
+        mode: ability.mode,
+        requires: ability.requires,
+    })},`), "} as const;", "");
+    return lines;
+}
+/**
+ * The WordPress REST route each resource kind answers on.
+ *
+ * A declared collection's items are `post` rows carrying a collection taxonomy
+ * term, which is why it reads `wp/v2/posts` and is narrowed by the term rather
+ * than by a post type of its own.
+ */
+const CONTENT_READ_ROUTES = {
+    posts: "wp/v2/posts",
+    pages: "wp/v2/pages",
+    media: "wp/v2/media",
+    collection: "wp/v2/posts",
+};
+/** The collection taxonomy the content-model kernel registers on `post`. */
+const CONTENT_COLLECTION_TAXONOMY = "zero_collection";
+/**
+ * The term a collection's items carry, spelled exactly as
+ * `spacefast_content_model_collection_term_slug()` mints it. Two places compute
+ * this and they must agree, so the rule is restated here rather than guessed:
+ * `sf-<first 16 hex of sha256(spaceId)>-<resource id with . and _ as ->`.
+ */
+function collectionTermSlug(spaceId, resourceId) {
+    const hash = createHash("sha256").update(spaceId).digest("hex").slice(0, 16);
+    return `sf-${hash}-${resourceId.replaceAll(".", "-").replaceAll("_", "-")}`;
+}
+/**
+ * The reads an island or a capsule makes against this Space's own content.
+ *
+ * Printed as plain object literals, not as calls into the SDK: this module
+ * lands in someone else's project and imports nothing. What each entry returns
+ * is structurally a `ZeroQueryOptions`, so `useQuery(content.posts.list())` is
+ * the same line whether it runs in an island on a content page or in a capsule
+ * SPA — one data layer, two backends.
+ */
+function printContentReads(source) {
+    const resources = source.contentModel?.wordpress.resources ?? [];
+    if (resources.length === 0)
+        return [];
+    const lines = [
+        "/**",
+        " * Reads against this Space's own content, over its WordPress REST surface.",
+        " *",
+        " * Same-origin and credential-less: a `publicRead` resource answers an",
+        " * anonymous reader, and one that is not needs a session. Pass any parameters",
+        " * WordPress accepts (`per_page`, `search`, `slug`, …).",
+        " */",
+        "export const content = {",
+    ];
+    for (const resource of resources) {
+        const route = CONTENT_READ_ROUTES[resource.kind];
+        const term = resource.kind === "collection" && source.space !== null
+            ? collectionTermSlug(source.space.id, resource.id)
+            : null;
+        if (resource.kind === "collection" && term === null) {
+            // Without a Space there is no term to name, and a read that fetched every
+            // post while claiming to be one collection would be worse than absent.
+            lines.push(`  // \`${resource.id}\` is a collection; its term is Space-scoped, so run`, "  // `sf zero types` against a Space to generate its read.");
+            continue;
+        }
+        const params = term === null
+            ? "...params"
+            : `${JSON.stringify(CONTENT_COLLECTION_TAXONOMY)}: ${JSON.stringify(term)}, ...params`;
+        lines.push(`  ${propertyKey(resource.name)}: {`, `    /** ${resource.label}. ${resource.publicRead
+            ? "publicRead: an anonymous reader may make this call."
+            : "Not publicRead: this call needs a session that may read it."} */`, "    list: (params: Readonly<Record<string, string | number | boolean>> = {}) => ({", `      name: "content:content.${resource.id}.list",`, `      args: [{ route: ${JSON.stringify(route)}, params: { ${params} } }],`, "    }),", "  },");
+    }
+    lines.push("} as const;", "");
+    return lines;
+}
+function header(source) {
+    const origin = source.space === null
+        ? "Generated by `sf zero types` from this project's local capsule compile."
+        : `Generated by \`sf zero types\` from the space ${source.space.slug} (${source.space.id}).`;
+    const lines = ["// GENERATED FILE — DO NOT EDIT.", "//", `// ${origin}`];
+    if (source.versionId !== null) {
+        lines.push(`// Live version: ${source.versionId}`);
+    }
+    if (source.contentModel !== null) {
+        lines.push(`// Content model revision: ${source.contentModel.revision}`);
+    }
+    lines.push("//", "// Regenerate: sf zero types", "// Verify in CI: sf zero types --check", "");
+    return lines;
+}
+/**
+ * Prints the whole `zero-types` module.
+ *
+ * Section order follows what a reader reaches for: the content model first
+ * because it is what most capsules are written against, then the Ability
+ * catalog that says what may be called and by whom, then the database rows.
+ */
+export function zeroTypesModule(source) {
+    const sections = [header(source).join("\n")];
+    sections.push(source.contentModel === null
+        ? [
+            "// ── Content model ─────────────────────────────────────────────────────────",
+            "//",
+            "// This Space's live version declares no content model, so there are no",
+            "// content Abilities and no content types to generate.",
+            "",
+        ].join("\n")
+        : [
+            "// ── Content model ─────────────────────────────────────────────────────────",
+            "",
+            contentModelSdkModule(source.contentModel),
+            "",
+            ...printContentReads(source),
+        ].join("\n"));
+    sections.push([
+        "// ── Ability catalog ───────────────────────────────────────────────────────",
+        "",
+        ...printAbilityCatalog(source.abilities),
+    ].join("\n"));
+    const dbLines = [
+        "// ── Database ──────────────────────────────────────────────────────────────",
+        "",
+    ];
+    if (source.tables.some((table) => table.columns.some((column) => column.type === "json"))) {
+        dbLines.push("/** What a `json` column holds. */", `export type ${JSON_VALUE_TYPE} =`, "  | string", "  | number", "  | boolean", "  | null", `  | readonly ${JSON_VALUE_TYPE}[]`, `  | { readonly [key: string]: ${JSON_VALUE_TYPE} };`, "");
+    }
+    if (source.tables.length === 0) {
+        dbLines.push("/** This capsule declares no tables. */", "export type ZeroTables = Readonly<Record<string, never>>;", "");
+    }
+    else {
+        // Distinct table names can flatten onto one row-type identifier (`user_posts`
+        // and `user__posts` both give `UserPostsRow`), which would emit a duplicate
+        // `export type` that fails to compile. Refuse to print it and name the tables.
+        const seenTypeNames = new Map();
+        for (const table of source.tables) {
+            const typeName = tableTypeName(table.name);
+            const collided = seenTypeNames.get(typeName);
+            if (collided !== undefined) {
+                throw new Error(`Tables \`${collided}\` and \`${table.name}\` both generate the row type \`${typeName}\`.`);
+            }
+            seenTypeNames.set(typeName, table.name);
+        }
+        for (const table of source.tables)
+            dbLines.push(...printTable(table));
+        dbLines.push("/** Every table this capsule declares, keyed by its capsule name. */", "export type ZeroTables = {", ...source.tables.map((table) => `  readonly ${propertyKey(table.name)}: ${tableTypeName(table.name)};`), "};", "");
+    }
+    sections.push(dbLines.join("\n"));
+    return sections.join("\n");
+}