@sanoma-ai/workflows 0.11.2 → 0.11.4

package/src/host.ts

@@ -47,6 +47,15 @@ export const wakeUrlOf = (outputs: HostOutputs): string => outputs.wakeUrl ?? ou
  * A resource type's `host`: the fields it takes the runtime's inputs in, by dotted path into its
  * declared fields, and how its state reads as `HostOutputs`. A host is drifted when
  * `outputs(state).revision` differs from what `sanoma.source.resolve` says `ref` is now.
+ *
+ * A host that `derives` (`cloudflare.host`, `cloud.host`) is declared with the decisions only: its
+ * name, its `hostname` and the `database` it runs on. Apply fills the rest before it plans
+ * (`deriveHosts`): `image` from the installed `sanoma`, `source` and `ref` from the repository the
+ * app runs from and its default branch (each declarable as an override), `secrets` (markers only,
+ * never a value) and `domains` from the decisions, the config and the sites, which a data file may
+ * not declare; the port is the image's (`RUNTIME_PORT`). One that does not derive is declared
+ * whole, its `secrets` and `port` named in its data file (`docker.container`, the deprecated
+ * `cloudflare.container`).
  */
 export interface HostSpec {
   capabilities: HostCapabilities;
@@ -57,12 +66,16 @@ export interface HostSpec {
     ref: string;
     /**
      * The secrets it passes the runtime (`SANOMA_DATABASE_URL`, `SANOMA_SECRETS_KEY`): a write-only
-     * field. Absent for a host that binds its own bootstrap (`bindsBootstrap`).
+     * field. Absent for a host that binds its own bootstrap (`bindsBootstrap`). A host that derives
+     * has it filled by apply, never declared.
      */
     secrets?: string;
-    /** The port the app listens on. */
-    port: string;
-    /** A public site's domain, by site name: the app serves each site at the root of its domain (`SANOMA_DOMAINS`). */
+    /** The port the app listens on, for a host that does not derive: one that does runs the image's, `RUNTIME_PORT`. */
+    port?: string;
+    /**
+     * A public site's domain, by site name: the app serves each site at the root of its domain
+     * (`SANOMA_DOMAINS`). A host that derives has it filled from the sites' `domain`, never declared.
+     */
     domains?: string;
     /**
      * The hostname the app is served at. A host with one reports `url` as `https://<hostname>` (its
@@ -70,6 +83,22 @@ export interface HostSpec {
      * as `wakeUrl`, where its wakeup reaches it. It is never one of `domains`' values.
      */
     hostname?: string;
+    /**
+     * The runtime image, for a host that derives: the installed `sanoma`'s (`runtimeImage`) when a
+     * data file leaves it out, an override otherwise.
+     */
+    image?: string;
+    /**
+     * A reference to the declared database the host runs the company on (`database: store`), for a
+     * host that derives: apply gives the host that database's URL, as `SANOMA_DATABASE_URL`.
+     */
+    database?: string;
+    /**
+     * The host's name, for a host that derives: the repository's name (`owner/<name>`, made a
+     * name of lower-case letters, digits and dashes) when a data file leaves it out. Its type's
+     * `find` gives `UNNAMED` until apply fills it.
+     */
+    name?: string;
   };
   /**
    * The field apply fills with the commit `ref` resolves to, before it plans: hidden, as a data
@@ -81,9 +110,26 @@ export interface HostSpec {
    * tokens) and binds it itself, as Sanoma Cloud's does: such a type takes no `secrets`.
    */
   bindsBootstrap?: boolean;
+  /**
+   * True for a host whose declaration says only the decisions (see above): apply derives its
+   * image, source, ref, secrets and domains, and a data file may not declare `secrets` or `domains`.
+   */
+  derives?: boolean;
   outputs: (state: Record<string, unknown>) => HostOutputs;
 }
 
+/** The runtime image a host runs, tagged with the installed `sanoma`'s version: GitHub's registry. */
+export const RUNTIME_IMAGE = "ghcr.io/sanoma-ai/runtime";
+
+/** The runtime image of `sanoma` at `version`: `ghcr.io/sanoma-ai/runtime:<version>`. */
+export const runtimeImage = (version: string): string => `${RUNTIME_IMAGE}:${version}`;
+
+/** A deriving host's identity before apply names it after its repository (`HostSpec.inputs.name`): never sent to a vendor. */
+export const UNNAMED = "(the repository's name)";
+
+/** The port the runtime image's app listens on (its `PORT`): a host that derives runs it there. */
+export const RUNTIME_PORT = 3000;
+
 const LIFETIMES: readonly HostLifetime[] = ["long-lived", "stops-when-quiet"];
 
 /** True when `schema` has a field at the dotted `path`, looking through optional, nullable and default wrappers. */
@@ -108,7 +154,9 @@ function unwrap(schema: z.ZodType): z.ZodType {
  * Throws what is wrong with a resource type's `host`: an input or `revision` that names no field,
  * `secrets` that is not write-only, missing (unless the host binds its own bootstrap) or given
  * beside `bindsBootstrap`, a `revision` that is write-only, an unknown lifetime, a type apply
- * cannot change (not `writable`).
+ * cannot change (not `writable`); for a host that does not derive, no `port`, or an `image`, a
+ * `database` or a `name` (inputs of a host that derives); for one that does, a `port` (it runs the image's),
+ * or a `database` that is not write-only (it stands for a URL, and is never compared).
  */
 export function checkHost(
   what: string,
@@ -131,7 +179,55 @@ export function checkHost(
   } else if (secrets === undefined || !type.fields.writeOnly.includes(secrets)) {
     problems.push("inputs.secrets must be a write-only field, unless the host binds its own bootstrap");
   }
+  if (host.derives) {
+    if (host.inputs?.port !== undefined)
+      problems.push("inputs.port is not taken by a host that derives: it runs the image's");
+    const database = host.inputs?.database;
+    if (database !== undefined && !type.fields.writeOnly.includes(database)) {
+      problems.push("inputs.database must be a write-only field: it stands for the database's URL, never compared");
+    }
+  } else {
+    if (host.inputs?.port === undefined) problems.push("inputs.port names the port, unless the host derives");
+    for (const input of ["image", "database", "name"] as const) {
+      if (host.inputs?.[input] !== undefined) problems.push(`inputs.${input} is taken by a host that derives only`);
+    }
+  }
   if (type.fields.writeOnly.includes(host.revision)) problems.push("revision must not be write-only: drift reads it");
   if (typeof host.outputs !== "function") problems.push("outputs must be a function of the state");
   if (problems.length) throw new Error(`${what}: its host: ${problems.join("; ")}`);
 }
+
+/** The id apply gives the deploy key it declares for the host `hostId`: `resources/sanoma/infra.ts#host.sourceKey`. */
+export const sourceKeyId = (hostId: string) => `${hostId}.sourceKey`;
+
+/**
+ * The lockfile keys that are a deriving host's deploy key (`sourceKeyId`) among `resources`: never
+ * an orphan, whether or not apply declares the key this read (before its source key is stored, or
+ * where the store does not hold it), so apply never deletes the key a host clones with.
+ */
+export function sourceKeyIds(
+  resources: readonly { id: string; vendor: string; type: string }[],
+  types: ReadonlyMap<string, { host?: HostSpec }>,
+): Set<string> {
+  return new Set(
+    resources.filter((r) => types.get(`${r.vendor}.${r.type}`)?.host?.derives).map((r) => sourceKeyId(r.id)),
+  );
+}
+
+/**
+ * For a host that derives its domains (`inputs.domains`) from the sites: the domains its state
+ * says are attached, `<domain> (<site>)`, when no site declares one, which a change would detach
+ * (a data file of before declared them on the host). Empty otherwise: once a site declares a
+ * domain, the declared ones are attached and the dropped ones detached.
+ */
+export function detaching(host: HostSpec, desired: Record<string, unknown>, state: Record<string, unknown>): string[] {
+  const path = host.inputs.domains;
+  if (!host.derives || path === undefined) return [];
+  const at = (value: Record<string, unknown>) =>
+    path.split(".").reduce<unknown>((o, key) => (o as Record<string, unknown> | null | undefined)?.[key], value);
+  const declared = at(desired);
+  if (declared && typeof declared === "object" && Object.keys(declared).length) return [];
+  const attached = at(state);
+  if (!attached || typeof attached !== "object") return [];
+  return Object.entries(attached as Record<string, unknown>).map(([site, domain]) => `${String(domain)} (${site})`);
+}

package/src/index.ts

@@ -59,6 +59,7 @@ export {
   type ResourceFields,
   type ResourceOps,
   type ResourceSpec,
+  valueAt,
   withoutWriteOnly,
 } from "./resource.ts";
 export { type DnsRecord, dnsRecord } from "./dns.ts";
@@ -67,6 +68,7 @@ export {
   defineConfig,
   envWakeup,
   type Login,
+  readRootSnapshot,
   resolveConfig,
   resolveDatabaseUrl,
   type ResolvedConfig,
@@ -189,6 +191,7 @@ export {
   type Draft,
   draftBranch,
   type DraftDiff,
+  defaultBranch,
   draftOf,
   type HostEnforcement,
   type PullRequest,
@@ -203,7 +206,23 @@ export {
   type SourceHost,
 } from "./source.ts";
 export type { HostCapabilities, HostLifetime, HostOutputs, HostSpec } from "./host.ts";
-export { wakeUrlOf } from "./host.ts";
+export { RUNTIME_IMAGE, RUNTIME_PORT, runtimeImage, sourceKeyId, UNNAMED, wakeUrlOf } from "./host.ts";
+export {
+  cloneUrl,
+  deriveHosts,
+  type HostFacts,
+  hostFacts,
+  DEPLOY_KEY_TITLE,
+  DEPLOY_KEY_TYPE,
+  GITHUB_APP,
+  githubRepository,
+  HOST_SIGNING_KEY,
+  installedSanoma,
+  originUrl,
+  SOURCE_KEY,
+  sourceRepository,
+  wokenBy,
+} from "./host-derive.ts";
 export {
   checkDatabase,
   type DatabaseCapabilities,
@@ -242,6 +261,11 @@ export {
 } from "./client.ts";
 // A raw DBOS client on the runtime's database, for tests and tools that read DBOS directly.
 export { dbosClient } from "./db.ts";
+// The runtime bundled where a company's files are not (the Cloudflare host's Worker): the root's
+// people, policies and app name as data, Cedar's web build, and a database it only checks.
+export { type RootSnapshot, useRootSnapshot } from "./bundled.ts";
+export { checkPreparedOnly } from "./db.ts";
+export { type CedarWasm, useCedarWasm } from "./schema.ts";
 // Also at `@sanoma-ai/workflows/shared`, which a browser bundle can import.
 export {
   AGENTS,
@@ -320,7 +344,7 @@ export {
 export { checkSecretStore, type SecretStoreCheck } from "./secret-store-check.ts";
 
 export { postgresSecretStore } from "./credentials.ts";
-export { deploymentKey, signingKeyFor } from "./deployment-key.ts";
+export { deploymentKey, keyBytes, signingKeyFor } from "./deployment-key.ts";
 
 export {
   defineConnection,

package/src/load.ts

@@ -89,7 +89,8 @@ const registry = ((globalThis as Record<symbol, unknown>)[Symbol.for("sanoma.loa
   made: new WeakMap(),
 }) as Registry;
 
-const require = createRequire(import.meta.url);
+/** This module's `require`, made on first use: a bundle with no file URL (the Cloudflare host's Worker) never loads a file. */
+let require: NodeJS.Require | undefined;
 
 /** Where `value` was made, when a company file made it with a constructor the loader served. */
 export const madeOf = (value: unknown): Made | undefined =>
@@ -205,7 +206,9 @@ function loadOne(gen: Generation, file: string, rel: string): Loaded {
   if (done) return done;
   let loaded: Loaded;
   try {
-    const { ns } = require(`${SCHEME}${gen.id}/${pathToFileURL(file).href}`) as { ns: Record<string, unknown> };
+    const { ns } = (require ??= createRequire(import.meta.url))(`${SCHEME}${gen.id}/${pathToFileURL(file).href}`) as {
+      ns: Record<string, unknown>;
+    };
     loaded = { exports: Object.entries(ns) };
   } catch (error) {
     // A file that imports one that threw throws the same object: reported once, where it was thrown.

package/src/resource.ts

@@ -131,6 +131,13 @@ export interface ResourceSpec<S extends z.ZodObject = z.ZodObject> {
    * Supabase project's health, until it is healthy, then its database URL stored.
    */
   afterCreate?: readonly AfterCreate[];
+  /**
+   * The ids (`<vendor>.<type>`) this type was known by before a rename: a lockfile binding under
+   * one of them binds a declaration of this type to the same object, so a rename recreates nothing
+   * (`cloudflare.host`, formerly `cloudflare.container`). Apply writes the new id with its next
+   * change to that binding.
+   */
+  formerly?: readonly string[];
 }
 
 /** One operation apply calls after a create (`ResourceSpec.afterCreate`). */
@@ -352,11 +359,20 @@ export interface Resource<
       Required<
         Omit<
           ResourceSpec<S>,
-          "identity" | "find" | "writable" | "host" | "wakeup" | "database" | "stateless" | "afterCreate" | "vendorless"
+          | "identity"
+          | "find"
+          | "writable"
+          | "host"
+          | "wakeup"
+          | "database"
+          | "stateless"
+          | "afterCreate"
+          | "vendorless"
+          | "formerly"
         >
       >
     >,
-    Readonly<Pick<ResourceSpec<S>, "identity" | "find" | "host" | "wakeup" | "database" | "afterCreate">> {
+    Readonly<Pick<ResourceSpec<S>, "identity" | "find" | "host" | "wakeup" | "database" | "afterCreate" | "formerly">> {
   (
     desired: Declaring<z.input<S>, R>,
     options?: { connection?: ConnectionRef<Id extends `${infer V}.${string}` ? V : string> },
@@ -836,6 +852,20 @@ export function defineResource<
     if (host && pathsIn(desired, new Set([host.revision])).length) {
       throw new Error(`${what}: leave out ${host.revision}: apply sets it from ${host.inputs.ref}`);
     }
+    // A host that derives is given its secrets and its sites' domains: a data file names neither.
+    if (host?.derives) {
+      const { secrets, domains } = host.inputs;
+      if (secrets !== undefined && pathsIn(desired, new Set([secrets])).length) {
+        throw new Error(
+          `${what}: leave out ${secrets}: apply gives the host its database's URL, its keys and the connections it deploys with, and no secret is written in a file`,
+        );
+      }
+      if (domains !== undefined && pathsIn(desired, new Set([domains])).length) {
+        throw new Error(
+          `${what}: leave out ${domains}: a public site's domain is declared on the site, \`defineSite({ public: true, domain })\`, and the host attaches it`,
+        );
+      }
+    }
     const vendors = pathsIn(desired, owned);
     if (vendors.length) {
       throw new Error(
@@ -874,6 +904,7 @@ export function defineResource<
     stateless: spec.stateless ?? host !== undefined,
     vendorless: spec.vendorless ?? false,
     ...(spec.afterCreate && { afterCreate: spec.afterCreate }),
+    ...(spec.formerly?.length && { formerly: Object.freeze([...spec.formerly]) }),
     ops,
     // A symbol, so `defineConnector` tells a resource type from a group of operations.
     [RESOURCE]: true as const,

package/src/resources.ts

@@ -9,6 +9,7 @@ import { APPS_DIR, COLLECTIONS_FILE, filesUnder, kindDirs, relPath } from "./pat
 import { peopleConnector, sanoma } from "./person.ts";
 import { wakeupOps } from "./wakeup-type.ts";
 import { DECLARED, type Declared, isDeclared, isObject, type Resource, resourceTypesOf } from "./resource.ts";
+import { rootSnapshot } from "./bundled.ts";
 import { Principal } from "./define.ts";
 import { NotAdmittedError } from "./errors.ts";
 import {
@@ -89,10 +90,12 @@ export const peopleSources = (root: string): ReadonlySet<string> => filesRead(pe
  * Only the files that may declare them (`mayDeclarePeople`) are loaded, with the people's and the
  * wakeup's constructors, which the same `sanoma` declares; loaded again only when one of them
  * changed (by its size and time), so a new colleague is admitted once their file is saved, and a
- * request costs a `stat` per file.
+ * request costs a `stat` per file. A root with a bundled snapshot (`useRootSnapshot`) answers its people.
  */
 export function readPeople(root: string | undefined): DeclaredPeople {
   if (root === undefined) return { people: [], problems: [] };
+  const bundled = rootSnapshot(root);
+  if (bundled) return bundled.people;
   const loaded = peopleLoad(root);
   const cached = peopleRead.get(loaded);
   if (cached) return cached;
@@ -356,7 +359,7 @@ function declarationsOf(
     const why =
       value.connection !== undefined && binding.connection?.$connection !== value.connection.$connection
         ? `${id} changes the connection of a bound resource: explicitly unbind it before selecting another account`
-        : binding.type !== value[DECLARED]
+        : binding.type !== value[DECLARED] && !types.get(value[DECLARED])?.formerly?.includes(binding.type)
           ? `${id} is bound to a ${binding.type} in ${LOCKFILE}, but declares a ${value[DECLARED]}`
           : first !== undefined
             ? `${id} is bound to the same ${object} as ${first} in ${LOCKFILE}: bind each object once`

package/src/schema.ts

@@ -19,11 +19,24 @@ import { CHANGE_MERGE, DATA_VENDOR, EFFECTS, groupNamesOf, type PeopleResource,
 // resolved config and the people, in memory for the evaluator, and written as text to
 // `.sanoma/schema.cedarschema` for the policies' author.
 
-const require = createRequire(import.meta.url);
-let wasm: typeof import("@cedar-policy/cedar-wasm/nodejs") | undefined;
+/** Cedar's bindings: its builds (`/nodejs`, `/web`) export the same functions. */
+export type CedarWasm = typeof import("@cedar-policy/cedar-wasm/nodejs");
+let wasm: CedarWasm | undefined;
 
-/** `@cedar-policy/cedar-wasm`'s Node build, loaded (synchronously, once) on first use, so a process that never decides with Cedar never loads it. */
-export const cedarWasm = () => (wasm ??= require("@cedar-policy/cedar-wasm/nodejs") as typeof wasm)!;
+/**
+ * `@cedar-policy/cedar-wasm`'s Node build, loaded (synchronously, once) on first use, so a process
+ * that never decides with Cedar never loads it; or the build `useCedarWasm` gave.
+ */
+export const cedarWasm = (): CedarWasm =>
+  (wasm ??= createRequire(import.meta.url)("@cedar-policy/cedar-wasm/nodejs") as CedarWasm);
+
+/**
+ * From now on, Cedar is `bindings`: its web build, initialised, where the Node build cannot load
+ * (the Cloudflare host's Worker, which bundles the runtime).
+ */
+export function useCedarWasm(bindings: CedarWasm): void {
+  wasm = bindings;
+}
 
 /** The schema as Cedar's JSON format has it. */
 export type CedarSchemaJson = SchemaJson<string>;

package/src/shared.ts

@@ -141,6 +141,26 @@ export const domainsText = (domains: Readonly<Record<string, string>>): string =
     .map((site) => `${site}=${domains[site]}`)
     .join(",");
 
+/**
+ * Where a hosted container answers, with its instance token (`SANOMA_WAKEUP_TOKEN`), the bundle
+ * of its public sites that a host's Worker serves: the Cloudflare host downloads it at a deploy.
+ */
+export const SITES_BUNDLE_PATH = "/__sanoma/sites-bundle";
+/** The header every answer of that route carries: a runtime without the route answers without it. */
+export const SITES_BUNDLE_HEADER = "x-sanoma-sites-bundle";
+
+/** What that route answers: what a host's Worker runs a company's public sites from (`buildWorker` in `@sanoma-ai/app/build`). */
+export interface SitesBundle {
+  /** The sites it serves, by key: public, with a domain and no login. */
+  sites: string[];
+  /** The main module, among `modules`. */
+  mainModule: string;
+  /** The Worker's modules, by name relative to the main module, each base64. */
+  modules: { name: string; type: "esm" | "wasm" | "text" | "data"; content: string }[];
+  /** The Worker's static assets, by path from `/`, each base64: the client build and the prerendered pages. */
+  assets: { path: string; content: string }[];
+}
+
 /** Where a host with a `hostname` serves the app (`HostSpec`'s `hostname`): `https://<hostname>`. */
 export const hostnameUrl = (hostname: string): string => `https://${hostname}`;
 

package/src/sites.ts

@@ -15,6 +15,7 @@ import {
   apiNameOf,
   BUILT_IN_WORKFLOWS,
   DATA_VENDOR,
+  DOMAIN_NAME,
   LOCALE,
   SITE_NAME,
   siteKey,
@@ -129,7 +130,9 @@ export function readSites(
     const read = readSiteFiles(root, dir);
     const resolved = read.flatMap(({ uses }) => uses.filter((use) => !isAppCollection(use)).map(resolve));
     const pages = pagesOf(read);
-    const { problems: optionProblems, ...options } = siteDefinitionOf(root, dir, connectors);
+    // Its declared domain is the production host's to attach (`siteDomains`): where the site answers
+    // is `domain`, which only the app sets, from the `SANOMA_DOMAINS` that host hands it.
+    const { problems: optionProblems, domain: _declared, ...options } = siteDefinitionOf(root, dir, connectors);
     const calls = resolved.map((r) => r.call);
     const problems = [
       ...resolved.flatMap(({ call, problem }) => {
@@ -225,6 +228,21 @@ export function siteIcons(root: string): Record<string, string> {
   );
 }
 
+/**
+ * Each public site's domain (`defineSite({ public: true, domain })`) under `root`, by name, for
+ * the sites whose `site.ts` gives one without a problem there: what the production host attaches
+ * and hands the app as `SANOMA_DOMAINS` (`deriveHosts`). Loaded as `readSites` loads it.
+ */
+export function siteDomains(root: string): Record<string, string> {
+  const none = new Set<string>();
+  return Object.fromEntries(
+    sitesUnder(root).flatMap(({ name, dir }) => {
+      const { domain } = siteDefinitionOf(root, dir, { vendors: none, logins: none });
+      return domain === undefined ? [] : [[name, domain]];
+    }),
+  );
+}
+
 /**
  * The sites under `root`, by key (`siteKey`): each folder of `sites/` with a `routes/` whose name
  * is a URL segment, then each app's `apps/<app>/sites/`, with its folder relative to `root`.
@@ -427,10 +445,14 @@ const SiteDefinitionSchema = z.strictObject({
   public: z.boolean().optional(),
   login: z.string().optional(),
   locales: z.array(z.string()).optional(),
+  domain: z
+    .string()
+    .regex(DOMAIN_NAME, "a host name of two labels or more, lower case, such as `www.acme.example`")
+    .optional(),
 });
 
 /** What `site.ts` says of who may see a site: read together or not at all. */
-const ACCESS = ["public", "login", "locales"];
+const ACCESS = ["public", "login", "locales", "domain"];
 
 /**
  * What the site in `dir` (relative to `root`) says of itself in its `site.ts`, loaded
@@ -445,6 +467,8 @@ function siteDefinitionOf(
   dir: string,
   connectors: SiteConnectors,
 ): Pick<SiteEntry, "at" | "title" | "icon" | "public" | "login" | "locales"> & {
+  /** `defineSite({ domain })`, kept only on a public site. */
+  domain?: string;
   problems: (ResourceProblem & { file: string })[];
 } {
   const file = `${dir}/site.ts`;
@@ -474,7 +498,7 @@ function siteDefinitionOf(
     );
     if (!parsed.success) return { problems };
   }
-  const { title, icon, public: isPublic, login, locales } = parsed.data;
+  const { title, icon, public: isPublic, login, locales, domain } = parsed.data;
   const loginProblem = (): string | undefined => {
     if (!isPublic) return "a login is for a public site: add `public: true`, or remove `login`";
     if (!connectors.vendors.has(login!)) return `login names "${login}", which is not a connector in sanoma.config.ts`;
@@ -496,6 +520,11 @@ function siteDefinitionOf(
   };
   const localesMessage = locales && localesProblem(locales);
   if (localesMessage) problems.push(problem(localesMessage));
+  const domainMessage =
+    domain !== undefined && !isPublic
+      ? "a domain is for a public site: add `public: true`, or remove `domain`"
+      : undefined;
+  if (domainMessage) problems.push(problem(domainMessage));
   return {
     at: { file, export: "default" },
     ...(title !== undefined && { title }),
@@ -503,6 +532,7 @@ function siteDefinitionOf(
     ...(isPublic && { public: true as const }),
     ...(login !== undefined && { login }),
     ...(locales && !localesMessage && { locales }),
+    ...(domain !== undefined && !domainMessage && { domain }),
     problems,
   };
 }

package/src/source.ts

@@ -130,7 +130,8 @@ export interface CheckResult {
 
 /**
  * The built-in operation `sanoma.source.resolve`: the commit `ref` names in the repository at
- * `url` now, by `git ls-remote` (a branch first, then a tag, peeled; a full commit id is itself).
+ * `url` now, by `git ls-remote` (a branch first, then a tag, peeled; a full commit id is itself),
+ * and the ref; with no `ref`, the repository's default branch (its `HEAD`) and the commit it names.
  * Apply calls it to fill a host's revision before it plans, and drift to see a merge. `resolveConfig`
  * registers it when a connector declares a host type.
  */
@@ -139,10 +140,11 @@ export const sourceOps = defineConnector("sanoma", {
     resolve: {
       effect: "read",
       idempotent: true,
-      description: "Resolve a branch or tag of a git repository to the commit it names now",
-      input: z.object({ url: z.string().min(1), ref: z.string().min(1) }),
-      output: z.object({ revision: z.string() }),
-      target: ({ url, ref }: { url: string; ref: string }) => `${url}#${ref}`,
+      description:
+        "Resolve a branch or tag of a git repository, its default branch by default, to the commit it names now",
+      input: z.object({ url: z.string().min(1), ref: z.string().min(1).optional() }),
+      output: z.object({ revision: z.string(), ref: z.string() }),
+      target: ({ url, ref }: { url: string; ref?: string }) => `${url}#${ref ?? "HEAD"}`,
     },
   },
 });
@@ -151,7 +153,10 @@ export const SOURCE_RESOLVE = "sanoma.source.resolve" satisfies typeof sourceOps
 
 /** The driver of `sanoma.source.resolve`: git on this machine, with its own credential helpers. */
 export const sourceDriver = defineDriver(sourceOps, {
-  source: { resolve: async ({ url, ref }) => ({ revision: await resolveRevision(url, ref) }) },
+  source: {
+    resolve: async ({ url, ref }) =>
+      ref === undefined ? defaultBranch(url) : { revision: await resolveRevision(url, ref), ref },
+  },
 });
 
 const COMMIT = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
@@ -159,20 +164,20 @@ const COMMIT = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
 /**
  * The fake of `sanoma.source.resolve`, which a sandbox run calls (`sandboxDrivers`): no git and no
  * network, a full commit id is itself as the driver has it, and any other ref the SHA-1 of
- * `<url>#<ref>`, so a scenario's revisions are the same on every run.
+ * `<url>#<ref>`, so a scenario's revisions are the same on every run; the default branch is `main`.
  */
 export const fakeSourceDriver = defineDriver(sourceOps, {
   source: {
-    resolve: async ({ url, ref }) => ({
+    resolve: async ({ url, ref = "main" }) => ({
       revision: COMMIT.test(ref) ? ref : createHash("sha1").update(`${url}#${ref}`).digest("hex"),
+      ref,
     }),
   },
 });
 
-/** The commit `ref` (a branch, a tag, `HEAD`, a full ref or a commit id) names in the repository at `url`. */
-export async function resolveRevision(url: string, ref: string): Promise<string> {
-  if (COMMIT.test(ref)) return ref;
-  const { stdout } = await promisify(execFile)("git", ["ls-remote", "--", url, ref, `${ref}^{}`], {
+/** `git ls-remote` of `patterns` in the repository at `url`, with `options`, never prompting for credentials. */
+async function lsRemote(url: string, patterns: string[], options: string[] = []): Promise<string> {
+  const { stdout } = await promisify(execFile)("git", ["ls-remote", ...options, "--", url, ...patterns], {
     // Never a prompt for credentials: a repository that needs them and has none fails.
     env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
     timeout: 30_000,
@@ -182,6 +187,24 @@ export async function resolveRevision(url: string, ref: string): Promise<string>
       cause: err,
     });
   });
+  return stdout;
+}
+
+/** The default branch of the repository at `url` (the branch its `HEAD` names) and the commit it names now. */
+export async function defaultBranch(url: string): Promise<{ revision: string; ref: string }> {
+  const stdout = await lsRemote(url, ["HEAD"], ["--symref"]);
+  const branch = /^ref: refs\/heads\/(\S+)\tHEAD$/m.exec(stdout)?.[1];
+  const revision = /^([0-9a-f]{40,64})\tHEAD$/m.exec(stdout)?.[1];
+  if (!branch || !revision) {
+    throw new DriverError(`${url} names no default branch`, { retryable: false, vendorCode: "no_such_ref" });
+  }
+  return { revision, ref: branch };
+}
+
+/** The commit `ref` (a branch, a tag, `HEAD`, a full ref or a commit id) names in the repository at `url`. */
+export async function resolveRevision(url: string, ref: string): Promise<string> {
+  if (COMMIT.test(ref)) return ref;
+  const stdout = await lsRemote(url, [ref, `${ref}^{}`]);
   const refs = new Map(
     stdout.split("\n").flatMap((line) => {
       const [sha, name] = line.split("\t");

package/src/wakeup-type.ts

@@ -15,7 +15,7 @@ import { defineResource } from "./resource.ts";
  * The host types a wakeup may name: each one a data file declares a wakeup for. A new host type
  * is added here. `testhost.app` is `@sanoma-ai/testing`'s, for the conformance kits.
  */
-const HOSTS = ["cloudflare.container", "docker.container", "testhost.app"] as const;
+const HOSTS = ["cloudflare.host", "cloudflare.container", "docker.container", "testhost.app"] as const;
 
 /** An instance of the wakeup service, as `GET /wakeup/instances/{id}` shows it. */
 const wakeupSchema = z.object({