@sanoma-ai/workflows 0.11.3 → 0.11.5

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";
@@ -190,6 +191,7 @@ export {
   type Draft,
   draftBranch,
   type DraftDiff,
+  defaultBranch,
   draftOf,
   type HostEnforcement,
   type PullRequest,
@@ -204,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,
@@ -326,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/kms-secrets.ts

@@ -295,11 +295,40 @@ export function kmsPostgresStore(options: KmsPostgresOptions): SecretStore | Sec
     capabilities,
     validate: (namespace) =>
       safe(async () => {
-        const address = { namespace, path: "__validation__" },
-          version = randomUUID();
-        const envelope = await seal(address, "validation", version);
-        await open(address, { envelope, version, updated_by: "validation", updated_at: new Date() });
-        await (await database()).query("SELECT version FROM sanoma_kms.secrets WHERE company=$1 LIMIT 0", [company]);
+        const address = { namespace, path: `__validation__/${randomUUID()}` },
+          version = randomUUID(),
+          value = randomUUID();
+        const envelope = await seal(address, value, version);
+        const db = await database();
+        const scope = [company, namespace, address.path, version];
+        let removed = false;
+        try {
+          const created = await db.query(
+            "INSERT INTO sanoma_kms.secrets(company,namespace,path,version,envelope,updated_by) VALUES($1,$2,$3,$4,$5,'validation') ON CONFLICT(company,namespace,path) DO NOTHING RETURNING version",
+            [...scope, JSON.stringify(envelope)],
+          );
+          if (created.rowCount !== 1) throw new SecretStoreError("conflict");
+          const updated = await db.query(
+            "UPDATE sanoma_kms.secrets SET envelope=$5,version=$4,updated_by='validation',updated_at=now() WHERE company=$1 AND namespace=$2 AND path=$3 AND version=$4 RETURNING version",
+            [...scope, JSON.stringify(envelope)],
+          );
+          if (updated.rowCount !== 1) throw new SecretStoreError("unavailable");
+          const stored = await db.query<Row>(
+            "SELECT version,envelope,updated_by,updated_at FROM sanoma_kms.secrets WHERE company=$1 AND namespace=$2 AND path=$3 AND version=$4",
+            scope,
+          );
+          if (!stored.rows[0] || (await open(address, stored.rows[0])).value !== value)
+            throw new SecretStoreError("invalid_value");
+        } finally {
+          // Also clean up a committed INSERT whose response was lost. The random address and
+          // exact version prevent one concurrent probe from deleting another probe or a secret.
+          const cleanup = await db.query(
+            "DELETE FROM sanoma_kms.secrets WHERE company=$1 AND namespace=$2 AND path=$3 AND version=$4",
+            scope,
+          );
+          removed = cleanup.rowCount === 1;
+        }
+        if (!removed) throw new SecretStoreError("unavailable");
         // Own-key usability only. Cross-company authorization requires live IAM proof with another existing key.
       }),
     read: (address) =>

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`). */
@@ -209,7 +216,8 @@ export interface Declared<Id extends string = string, T = State> {
   readonly connection?: ConnectionRef;
   /**
    * Where it names another resource: the field's dotted path (a list item's with its index,
-   * `teams.0`) to that resource's `<vendor>.<type>:<name>`.
+   * `teams.0`) to that resource's `<vendor>.<type>:<name>`, or its `<vendor>.<type>` alone when it
+   * has no identity (then `desired` holds nothing there).
    */
   readonly refs: Readonly<Record<string, string>>;
 }
@@ -352,11 +360,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> },
@@ -812,10 +829,16 @@ export function defineResource<
         const types = [wants.type].flat();
         if (!types.includes(id))
           throw new Error(`${what}: ${at} names a resource of type ${types.join(" or ")}, not ${id} (${value.name})`);
-        if (value.name === undefined)
-          throw new Error(`${what}: ${at} names a ${id}, which has no identity to name it by`);
-        if (wants.from !== undefined) unjudged.add(at);
-        refs[at] = `${id}:${value.name}`;
+        // A resource with no identity (a Neon project) stands for nothing a vendor could read: only
+        // a field the runtime consumes by the reference itself may name it, a host's database
+        // (`refs`, `deriveHosts`) or one that takes its state (`from`); `desired` holds nothing there.
+        if (value.name === undefined && path !== host?.inputs.database && wants.from === undefined) {
+          throw new Error(
+            `${what}: ${at} names a ${id}, which has no identity to name it by: only a host's database or a \`from\` reference may`,
+          );
+        }
+        if (wants.from !== undefined || value.name === undefined) unjudged.add(at);
+        refs[at] = value.name === undefined ? id : `${id}:${value.name}`;
         return value.name;
       }
       if (Array.isArray(value)) {
@@ -836,6 +859,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 +911,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

@@ -359,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/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({