@sanoma-ai/workflows 0.7.1 → 0.8.0

package/src/paths.ts

@@ -1,5 +1,6 @@
-import { readdirSync, statSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { APP_NAME } from "./shared.ts";
 
 // Where an import may reach, as the lints and the data-file reader all decide it, the one walk up
 // the directories and the one walk down (`filesUnder`). Node's `path` and `fs` only, no parser:
@@ -45,3 +46,57 @@ export function filesUnder(dir: string, keep: (name: string) => boolean): string
     .filter((path) => !relative(dir, path).split(sep).includes("node_modules"))
     .toSorted();
 }
+
+/** Where a company's apps are, under its root: `apps/<app>/`. */
+export const APPS_DIR = "apps";
+
+/** Each directory's company root (the nearest one with a `sanoma.config.ts`, short of a `node_modules`), once found. */
+const roots = new Map<string, string>();
+
+/** Whether `dir` is a company's root: it holds a `sanoma.config.ts`. */
+const isCompany = (dir: string) => existsSync(join(dir, "sanoma.config.ts"));
+
+/**
+ * The app a file is in: `<app>` for a file under `<root>/apps/<app>/`, where the root is the
+ * nearest directory above it with a `sanoma.config.ts` (an app keeps its own `package.json`,
+ * and its own config when merged from a company's repo: then the company is the one whose
+ * `apps/` holds it; a `node_modules` ends the search: the file is a package's, not a company's);
+ * undefined for a file at the root or outside any company. `defineWorkflow` and `collection()` name what they declare by it.
+ */
+export function appOfFile(file: string | undefined): string | undefined {
+  if (file === undefined) return undefined;
+  const dir = dirname(resolve(file));
+  let root: string | null | undefined = roots.get(dir);
+  if (root === undefined) {
+    root =
+      upFrom<string | null>(dir, (d) => (basename(d) === "node_modules" ? null : isCompany(d) ? d : undefined)) ?? null;
+    // An app merged from a company's repo keeps that repo's config: the company is the one above.
+    if (root !== null && basename(dirname(root)) === APPS_DIR && isCompany(dirname(dirname(root)))) {
+      root = dirname(dirname(root));
+    }
+    // Found roots only: a directory that is no company's yet may become one (`sanoma` in an empty folder).
+    if (root !== null) roots.set(dir, root);
+  }
+  if (root === null) return undefined;
+  const [top, app, ...rest] = relative(root, file).split(sep);
+  return top === APPS_DIR && app !== undefined && rest.length && APP_NAME.test(app) ? app : undefined;
+}
+
+/** The apps' folders under `root` whose names are an `APP_NAME`, sorted: `apps/<app>/`, absolute. */
+export function appFolders(root: string): string[] {
+  const dir = join(root, APPS_DIR);
+  if (!isDirectory(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && APP_NAME.test(d.name))
+    .map((d) => join(dir, d.name))
+    .toSorted();
+}
+
+/** Where a kind of file is under `root`: `<root>/<kind>`, then each app's `apps/<app>/<kind>`, whether or not they exist. */
+export const kindDirs = (root: string, kind: string): string[] => [
+  join(root, kind),
+  ...appFolders(root).map((app) => join(app, kind)),
+];
+
+/** Where a company's scenarios are, under its root and each app's folder. */
+export const SCENARIOS_DIR = "scenarios";

package/src/resources.ts

@@ -1,5 +1,5 @@
 import { readFileSync, statSync } from "node:fs";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { dirname, relative, resolve, sep } from "node:path";
 import { parsed } from "./ast.ts";
 import {
   type DataFile,
@@ -11,7 +11,7 @@ import {
 } from "./datafile.ts";
 import { type Binding, type Bindings, LOCKFILE, readLockfile } from "./lockfile.ts";
 import { type Connector, VENDOR } from "./op.ts";
-import { filesUnder } from "./paths.ts";
+import { APPS_DIR, filesUnder, kindDirs } from "./paths.ts";
 import { peopleConnector, sanoma } from "./person.ts";
 import { wakeupOps } from "./wakeup-type.ts";
 import type { Span } from "./outline.ts";
@@ -28,6 +28,7 @@ import {
   personOf,
   principalOf,
   problemLine,
+  qualified,
   RUNTIME_AGENTS,
   VISITORS,
 } from "./shared.ts";
@@ -65,9 +66,9 @@ export interface DeclaredResource {
 export interface DeclaredCollection {
   /** `<file>#<export>`, as a resource's: `resources/data.ts#outbound`. */
   id: string;
-  /** `resources/data.ts`. */
+  /** `resources/data.ts`, or an app's `apps/<app>/resources/data.ts`. */
   file: string;
-  /** The collection's name, its operations' middle segment (`data.<name>.get`). */
+  /** The collection's name, its operations' middle segments (`data.<name>.get`): an app's with its app, `crm.contacts`. */
   name: string;
   /** Its `export const` statement, as UTF-16 offsets into the file's text. */
   span: Span;
@@ -119,7 +120,8 @@ const peopleRead = new Map<string, { stamp: string; read: DeclaredPeople }>();
 
 /** Each data file under `root` with its size and modification time: unchanged while the files are. */
 const filesStamp = (root: string) =>
-  dataFilesUnder(join(root, "resources"))
+  kindDirs(root, "resources")
+    .flatMap(dataFilesUnder)
     .map((path) => {
       // Gone since it was listed (an editor's save by rename): stamped as such, and read next time.
       const stat = statSync(path, { bigint: true, throwIfNoEntry: false });
@@ -134,6 +136,13 @@ const RESERVED_GROUPS: ReadonlyMap<string, string> = new Map([
   [ANONYMOUS, "who a public page runs as when nobody is signed in"],
 ]);
 
+/**
+ * A person, agent or group declared in an app's data file: refused, because the people are the
+ * company's, so neither the policy (`readPeople`) nor `describeConfig` counts it.
+ */
+export const inAppPeople = (r: DeclaredResource): boolean =>
+  r.vendor === "sanoma" && Object.hasOwn(sanoma, r.type) && r.file.startsWith(`${APPS_DIR}/`);
+
 /**
  * The people, agents and groups the data files under `root` declare (`sanoma.person`, `.agent`,
  * `.group`), read without running them, as `principalOf` takes them, with what is wrong in their
@@ -147,9 +156,16 @@ export function readPeople(root: string | undefined): DeclaredPeople {
   if (cached?.stamp === stamp) return cached.read;
   // With the wakeup's type, which the same constructors declare: read, and only the people's kept.
   const read = readDataFiles(root, [peopleConnector, wakeupOps], undefined, (source) => DECLARES_PEOPLE.test(source));
-  const people = read.resources.filter((r) => Object.hasOwn(sanoma, r.type));
+  const ofPeople = read.resources.filter((r) => Object.hasOwn(sanoma, r.type));
+  const people = ofPeople.filter((r) => !inAppPeople(r));
   // The people are never bound, so the lockfile's problems are not theirs.
   const own = read.problems.filter((p) => p.file !== LOCKFILE);
+  for (const r of ofPeople.filter(inAppPeople)) {
+    own.push({
+      file: r.file,
+      message: `${r.id} declares a ${r.type} in an app: the people are the company's, declared in resources/ at the root`,
+    });
+  }
   const ids = new Map<string, DeclaredResource>();
   for (const r of people) {
     if (r.type === "group") {
@@ -262,7 +278,8 @@ export function readDataFiles(
 
   const files = new Map<string, FileEntry>();
   const left = new Set<string>();
-  for (const path of dataFilesUnder(join(root, "resources"))) {
+  // The root's, then each app's: a data file imports only from its own `resources/`.
+  for (const [dir, path] of kindDirs(root, "resources").flatMap((d) => dataFilesUnder(d).map((p) => [d, p] as const))) {
     const rel = relative(root, path).split(sep).join("/");
     const source = readFileSync(path, "utf8");
     if (partial && !partial(source)) {
@@ -270,7 +287,7 @@ export function readDataFiles(
       continue;
     }
     const { program, problems: syntax, at } = parsed(source, path);
-    const data = readDataFile(program, path, join(root, "resources"));
+    const data = readDataFile(program, path, dir);
     const problem = (offset: number, message: string) => problems.push({ file: rel, ...at(offset), message });
     for (const p of syntax) problems.push({ file: rel, ...p });
     for (const p of data.problems) problem(p.start, p.message);
@@ -465,7 +482,8 @@ export function readDataFiles(
     data.collections.map((c) => ({
       id: `${rel}#${c.export}`,
       file: rel,
-      name: c.name,
+      // An app's, `apps/<app>/resources/data.ts`, is named with its app, as `collection()` names it.
+      name: qualified(rel.startsWith(`${APPS_DIR}/`) ? rel.split("/")[1] : undefined, c.name),
       span: [c.start, c.end] as Span,
     })),
   );

package/src/run.ts

@@ -71,6 +71,11 @@ export interface WorkerState {
   workflows: Map<string, WorkflowDefinition<any, any>>;
   /** Each workflow's outline, by name: read once when the worker starts, every run is held to it (`call_not_in_outline`). */
   outlines: Map<string, WorkflowOutline>;
+  /**
+   * Starts a run of the workflow `name` as `runId` (an id the run already has returns it): how a
+   * built-in starts another as its child, as the change run starts apply and drift.
+   */
+  startRun(name: string, runId: string, args: RunArgs): Promise<{ getResult(): Promise<unknown> }>;
   /**
    * Set when the worker stops, before DBOS shuts down. DBOS abandons a stopped worker's run
    * functions, which then fail as their next DBOS call finds the database closed. Such a failure,

package/src/scenario.ts

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, relative, sep } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 import type { ISupportCodeLibrary } from "@cucumber/cucumber/api";
@@ -33,6 +33,7 @@ import { fill, isBug, objectUnder, restOf, seedFrom, shapeOf } from "./fill.ts";
 import type { LedgerRecord } from "./ledger.ts";
 import type { Driver, Op } from "./op.ts";
 import { type OutlineNode, outlineWorkflow } from "./outline.ts";
+import { isDirectory, kindDirs, SCENARIOS_DIR } from "./paths.ts";
 import { isObject } from "./resource.ts";
 import { admit, type DeclaredPeople, readPeople } from "./resources.ts";
 import { memorySecrets } from "./secret.ts";
@@ -1231,6 +1232,15 @@ function featureFiles(dir: string): string[] {
     .toSorted();
 }
 
+/**
+ * A company's scenarios: the `.feature` files under `scenarios/` in `root`, then under each app's
+ * `apps/<app>/scenarios/`, relative to `root`, with `/` between directories.
+ */
+const scenarioFiles = (root: string): string[] =>
+  kindDirs(root, SCENARIOS_DIR).flatMap((dir) =>
+    isDirectory(dir) ? featureFiles(dir).map((file) => `${relative(root, dir).split(sep).join("/")}/${file}`) : [],
+  );
+
 /** What `loadScenarios` returns. */
 export interface LoadedScenarios {
   scenarios: Scenario[];
@@ -1383,8 +1393,8 @@ const loadedByScope = new WeakMap<
 >();
 
 /**
- * Every scenario in the `.feature` files under `scenarios` (a `file:` URL to a directory),
- * compiled by Cucumber, with an error for each file that does not compile and each name used
+ * Every scenario in the `.feature` files under `scenarios/` and each app's `apps/<app>/scenarios/`
+ * in `scenarios` (a `file:` URL to the root), each named by its path from there, compiled by Cucumber, with an error for each file that does not compile and each name used
  * twice. No directory, or none given, is no scenarios. Rejects when an operation's phrase names
  * a field it lacks. The files are compiled again only once one is added, removed or written
  * (its name, `mtimeMs` or size changes), or the people's data files change: until then each
@@ -1396,7 +1406,7 @@ export async function loadScenarios(scope: Scope): Promise<LoadedScenarios> {
   if (!existsSync(dir)) return { scenarios: [], errors: [] };
   // Built first, so a phrase naming a field its input lacks rejects even with no feature files.
   builtFor(scope);
-  const files = featureFiles(dir);
+  const files = scenarioFiles(dir);
   const stamp = JSON.stringify([
     dir,
     files.map((file) => {

package/src/scenarios.ts

@@ -6,7 +6,7 @@ import { type Check, check, drive, loadScenarios, type Scenario, type Scope } fr
 import { errorMessage } from "./shared.ts";
 import { startWorker } from "./worker.ts";
 
-export { type DemoState, demoState, reseed } from "./demo.ts";
+export { type DemoState, demoState, reseed, type SeedHalf } from "./demo.ts";
 
 /*
  * `@sanoma-ai/workflows/scenarios`: runs a config's scenarios as sandbox runs, with no test

package/src/sdk.ts

@@ -3,7 +3,7 @@ import { dirname, join } from "node:path";
 import type { CollectionEntry, ConfigDescription, OpEntry, WorkflowEntry } from "./describe.ts";
 import { isObject } from "./resource.ts";
 import { type CedarSchemaJson, SCHEMA_FILE, schemaText } from "./schema.ts";
-import { apiNameOf, DATA_VENDOR, problemLine } from "./shared.ts";
+import { apiNameOf, DATA_VENDOR, problemLine, writtenName } from "./shared.ts";
 
 // A company's generated SDK, `.sanoma/api.ts`: the types of a site's `api` from `sanoma/site`,
 // written from `describeConfig` (types and JSDoc only: `api` itself is one generic client). It
@@ -24,7 +24,7 @@ type Schema = Record<string, unknown>;
  * `.sanoma/api.ts` for a description: one record type per collection, and `CompanyApi` (not `Api`,
  * which inside `declare module "sanoma/site"` is the module's own), one member per
  * workflow (`apiNameOf`), per vendor of the operations a person may call directly (`OpEntry.direct`,
- * by resource) and `data` for the collections, each with its JSDoc; then `Register`'s
+ * by resource) and `data` for the collections (an app's under its name), each with its JSDoc; then `Register`'s
  * augmentation. Pure: the same description gives the same text. A workflow whose api name another
  * has, `describeConfig`'s problem on its entry, is left out, and its problem is in `problems`.
  */
@@ -46,9 +46,16 @@ export function generateApi(description: ConfigDescription): { source: string; p
     members.push(member(`${title}: the operations a person may call directly.`, vendor, block(resources)));
   }
   if (description.collections.length) {
-    const data = description.collections.map((c) =>
-      member(collectionDoc(c), c.name, `CollectionApi<${recordName(c)}>`),
-    );
+    // The root's by name, then each app's under its name: `api.data.crm.contacts`.
+    const collectionMember = (c: CollectionEntry) =>
+      member(collectionDoc(c), writtenName(c), `CollectionApi<${recordName(c)}>`);
+    const byApp = Map.groupBy(description.collections, (c) => c.app);
+    const data = [
+      ...(byApp.get(undefined) ?? []).map(collectionMember),
+      ...[...byApp]
+        .filter(([app]) => app !== undefined)
+        .map(([app, own]) => member(`The ${app} app's collections.`, app!, block(own.map(collectionMember)))),
+    ];
     members.push(member("The company's collections.", DATA_VENDOR, block(data)));
   }
   const source = [
@@ -127,8 +134,15 @@ const opMember = (op: OpEntry) =>
 const collectionDoc = (c: CollectionEntry) =>
   `${c.title ?? c.name}: the collection \`${c.name}\`, keyed by \`${c.key}\`.`;
 
-/** A collection's record type's name: `outbound` gives `OutboundRecord`, never `CompanyApi` nor an imported type's. */
-const recordName = (c: CollectionEntry) => `${c.name[0]!.toUpperCase()}${c.name.slice(1)}Record`;
+/**
+ * A collection's record type's name: `outbound` gives `OutboundRecord`, an app's `crm.contacts`
+ * `CrmContactsRecord`; never `CompanyApi` nor an imported type's.
+ */
+const recordName = (c: CollectionEntry) =>
+  `${c.name
+    .split(".")
+    .map((part) => `${part[0]!.toUpperCase()}${part.slice(1)}`)
+    .join("")}Record`;
 
 /**
  * A JSON Schema as a TypeScript type, for the kinds a start form draws (`fieldsOf` in the app):

package/src/shared.ts

@@ -22,12 +22,16 @@ export type { DeclaredResource, ResourceProblem } from "./resources.ts";
 export type { DriftField, DriftReport, DriftResult, DriftStatus } from "./drift.ts";
 export type { ApplyPlan, ApplyReport, ApplyResult, PlanAnswer, PlanStep } from "./apply.ts";
 export type { CredentialStatus } from "./env.ts";
-export type { ChangeEvent, ChangeFacts, ChangeReport, ChangeState } from "./change.ts";
+export type { ChangeDeploy, ChangeEvent, ChangeFacts, ChangeReport, ChangeState, ChangeVerified } from "./change.ts";
+export type { AvailableApp, AvailableApps } from "./apps-list.ts";
 
 // What a UI in the browser may use from the runtime, besides types: `@sanoma-ai/workflows/shared`.
 // Nothing here imports DBOS, Node or zod, so a browser bundle can carry it; the runtime uses the
 // same functions, so a page answers these questions the way a run does.
 
+// Sanoma's claims, data (`sanoma/claims` re-exports them).
+export * from "./claims.ts";
+
 /**
  * What a `ctx.sleep` without a `{ name }` is called, in its outline node and its ledger record
  * (`name`); a name given may not be it.
@@ -76,6 +80,36 @@ export function previewRequests(
 /** A site's folder name under `sites/`, its URL segment: what the app mounts and `readSites` reads. */
 export const SITE_NAME = /^[a-z][a-z0-9-]*$/;
 
+/**
+ * An app's folder name under `apps/`: a lowercase letter, then lowercase letters and digits. It
+ * prefixes the names of what the folder declares (`qualified`), and is a segment of `ctx.data`,
+ * `api.data` and a site's path, so it is an identifier and a URL segment alike.
+ */
+export const APP_NAME = /^[a-z][a-z0-9]*$/;
+
+/** A name declared under `apps/<app>/` as the runtime has it, `<app>.<name>`; one declared at the root as it is. */
+export const qualified = (app: string | undefined, name: string): string =>
+  app === undefined ? name : `${app}.${name}`;
+
+/** A workflow's or collection's name as its file writes it, `qualified`'s undone: without its app. */
+export const writtenName = ({ name, app }: { name: string; app?: string }): string =>
+  app === undefined ? name : name.slice(app.length + 1);
+
+/**
+ * A site's key: its folder's name at the root, `<app>/<site>` in an app, so its pages are under
+ * `/sites/<key>`. What `readSites` names a site by, and the app's build mounts it at.
+ */
+export const siteKey = (app: string | undefined, site: string): string => (app === undefined ? site : `${app}/${site}`);
+
+/** A site's key (`siteKey`): a `SITE_NAME`, or an `APP_NAME`, `/` and a `SITE_NAME`, as a host's `domains` names a site. */
+export const SITE_KEY = /^([a-z][a-z0-9]*\/)?[a-z][a-z0-9-]*$/;
+
+/** A site's folder, relative to the root, by its key: `sites/<name>`, or an app's `apps/<app>/sites/<name>`. */
+export function siteDir(key: string): string {
+  const [app, site] = key.split("/");
+  return site === undefined ? `sites/${key}` : `apps/${app}/sites/${site}`;
+}
+
 /**
  * A public site's language, as `defineSite({ locales })` names it: a BCP 47 language tag of a
  * language and subtags (`en`, `fr`, `pt-BR`), which is also its URL segment (`/pt-BR/…`) and a
@@ -101,7 +135,7 @@ export function domainsOf(text: string): Record<string, string> {
   const domains: Record<string, string> = {};
   for (const pair of text.split(",")) {
     const [site = "", domain = "", ...rest] = pair.trim().split("=");
-    if (!SITE_NAME.test(site) || !DOMAIN_NAME.test(domain) || rest.length || Object.hasOwn(domains, site)) {
+    if (!SITE_KEY.test(site) || !DOMAIN_NAME.test(domain) || rest.length || Object.hasOwn(domains, site)) {
       throw new Error(
         `SANOMA_DOMAINS has "${pair}": write <site>=<hostname>, each site once, such as www=sanoma.example`,
       );
@@ -211,6 +245,16 @@ export const CALL_WORKFLOW = "call";
  */
 export const CHANGE_WORKFLOW = "change";
 
+/**
+ * The draft a change's run is of: `change:<id>` (its first run) or `change:<id>~<n>` (a later
+ * one); undefined for any other run id.
+ */
+export const changeIdOf = (runId: string): string | undefined => CHANGE_RUN.exec(runId)?.[1];
+
+/** What a draft's id may be (`ChangeInput.id`), the part of its branch and its change's run ids after `draft/` and `change:`. */
+export const DRAFT_ID = /^[\w-]{1,64}$/;
+const CHANGE_RUN = new RegExp(`^change:(${DRAFT_ID.source.slice(1, -1)})(?:~\\d+)?$`);
+
 /** Opens a change: its draft's branch pushed and a pull request opened for it. */
 export const CHANGE_OPEN = "sanoma.change.open";
 /** Reports Sanoma's review of a change to its host (the `sanoma` commit status). */
@@ -221,6 +265,14 @@ export const CHANGE_MERGE = "sanoma.change.merge";
 export const CHANGE_CLOSE = "sanoma.change.close";
 /** The DBOS event a change run publishes its `ChangeState` on. */
 export const CHANGE_EVENT = "change";
+/**
+ * The `recv` topic a change run is told what happened to its change on (a `ChangeEvent`): never an
+ * approval's, whose topic is its id (`approval-<n>`).
+ */
+export const CHANGE_TOPIC = "change:event";
+
+/** Lists the apps on GitHub with Sanoma's claims: the one runtime operation a page may call (`isDirect`). */
+export const APPS_LIST = "sanoma.apps.list";
 
 /** The workflows the runtime adds itself, which a config's own may not be named: drift, apply, call and change. */
 export const BUILT_IN_WORKFLOWS: ReadonlySet<string> = new Set([
@@ -324,8 +376,10 @@ export const ANONYMOUS_PRINCIPAL: Principal = Object.freeze({ id: ANONYMOUS, gro
 export const WAKEUP_AGENT = "wakeup";
 /** The runtime's agent a scheduled run is started by (`trigger: { schedule }`): the policy decides its starts. */
 export const SCHEDULE_AGENT = "schedule";
+/** The runtime's agent that checks and deploys the hosts: drift's, and apply's after a push to `main` (`SanomaClient.remoteEvent`). */
+export const HOST_CHECK_AGENT = "host-check";
 /** The runtime's own agents (scenarios, the host check, scheduled runs, the wakeup's registration), declared whether a data file names them or not. */
-export const RUNTIME_AGENTS: readonly string[] = ["scenarios", "host-check", SCHEDULE_AGENT, WAKEUP_AGENT];
+export const RUNTIME_AGENTS: readonly string[] = ["scenarios", HOST_CHECK_AGENT, SCHEDULE_AGENT, WAKEUP_AGENT];
 
 /** The declared resources of one of the runtime's people types, by `desired`. */
 const peopleOfType = <T>(resources: readonly PeopleResource[], type: "person" | "agent" | "group") =>
@@ -467,10 +521,11 @@ export const credentialReady = ({ status, optional }: CredentialStatus): boolean
 
 /**
  * A workflow's name in a site's `api`: kebab-case made camelCase, `outbound-next` as
- * `api.outboundNext`. `describeConfig` reports two workflows that come out the same, or one that
+ * `api.outboundNext`, and an app's workflow one name with its app, `crm.follow-up` as
+ * `api.crmFollowUp`. `describeConfig` reports two workflows that come out the same, or one that
  * comes out as a vendor's id or `data`, as a problem on the workflow.
  */
-export const apiNameOf = (name: string): string => name.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
+export const apiNameOf = (name: string): string => name.replace(/[-.]([a-z0-9])/g, (_, c: string) => c.toUpperCase());
 
 /**
  * A workflow as a site's `api` has it (`api.<apiNameOf(name)>`), started as the person on the

package/src/sites.ts

@@ -1,11 +1,11 @@
 import { existsSync, readdirSync } from "node:fs";
-import { join, relative, sep } from "node:path";
+import { basename, join, relative, sep } from "node:path";
 import { childrenOf, type LintProblem, type Node, readSource, type SourceFile } from "./ast.ts";
 import { type CedarPolicySource, visitorPermits } from "./cedar.ts";
 import { keyName } from "./datafile.ts";
 import type { ConfigDescription } from "./describe.ts";
 import { stringValue, unwrap } from "./outline.ts";
-import { filesUnder, isDirectory } from "./paths.ts";
+import { APPS_DIR, appFolders, filesUnder, isDirectory } from "./paths.ts";
 import { START } from "./schema.ts";
 import {
   ANONYMOUS,
@@ -14,6 +14,7 @@ import {
   DATA_VENDOR,
   LOCALE,
   SITE_NAME,
+  siteKey,
   VISITORS,
   WORKFLOW_ACTION,
 } from "./shared.ts";
@@ -64,12 +65,16 @@ export interface SitePage {
   content?: string;
 }
 
-/** A site, `sites/<name>/`, and what it calls. */
+/** A site, `sites/<name>/` or an app's `apps/<app>/sites/<name>/`, and what it calls. */
 export interface SiteEntry {
-  /** Its folder's name, where it is mounted: `/sites/<name>`. */
+  /** Its folder's name, `<app>/<name>` for an app's (`siteKey`): where it is mounted, `/sites/<name>`. */
   name: string;
+  /** The app whose folder holds it (`apps/<app>/sites/`); absent for one at the root. */
+  app?: string;
   /** `defineSite({ title })` in its `site.ts`, when that is a string literal. */
   title?: string;
+  /** `defineSite({ icon })` in its `site.ts`: a Lucide icon's name, as written. */
+  icon?: string;
   /** `defineSite({ public: true })`: served to visitors, not people. */
   public?: true;
   /** `defineSite({ login })`, the connector whose login half signs visitors in, as written: one that names none is among `problems`. */
@@ -109,12 +114,14 @@ const PARAMS: ReadonlySet<string> = new Set(["params"]);
 const ROUTE_MAKERS: ReadonlySet<string> = new Set(["createFileRoute", "createLazyFileRoute"]);
 
 /**
- * The sites under `root`: each folder of `sites/` with a `routes/` whose name is a URL segment,
- * by name (as `@sanoma-ai/app/build`'s `sitesOf` mounts them). Reads `routes/**` and
+ * The sites under `root` (`sitesUnder`): each folder of `sites/`, then of each app's
+ * `apps/<app>/sites/`, with a `routes/` whose name is a URL segment, by key (as
+ * `@sanoma-ai/app/build`'s `sitesOf` mounts them). Reads `routes/**` and
  * `components/**` (`.ts` and `.tsx`, less tests and declarations) of each with oxc, never running
  * them: each page (`SitePage`, from a route's id), each `<RunForm workflow="…" />` and each use of `api`, both imported from `sanoma/site`,
  * called or passed on (`queryFn: api.data.leads.list`):
- * `api.<name>` and `api.<name>.<method>` are a workflow, `api.data.<collection>.<op>` a collection,
+ * `api.<name>` and `api.<name>.<method>` are a workflow, `api.data.<collection>.<op>` (an app's
+ * `api.data.<app>.<collection>.<op>`) a collection,
  * and `api.<vendor>.<resource>.<op>` an operation. A name that is not written out (a variable, a
  * template with holes, a computed member) is skipped, as is a use through a namespace import or a
  * destructured `api`. A call to what `description` does not have, or to an operation a page may
@@ -133,9 +140,11 @@ export function readSites(
   policies?: readonly CedarPolicySource[],
 ): SiteEntry[] {
   if (root === undefined) return [];
-  const dir = join(root, "sites");
   const workflows = new Set(description.workflows.map((wf) => wf.name));
   const collections = new Set(description.collections.map((c) => c.name));
+  // `api.data.<app>.<collection>` passed on as a value reads as a call of `<app>`'s method: it is none.
+  const isAppCollection = ({ kind, name, method }: Written) =>
+    kind === "collection" && collections.has(`${name}.${method}`);
   const ops = new Map(description.ops.map((op) => [op.id, op]));
   // A workflow's api name to its name: two of one api name are a problem on the workflows.
   const byApiName = new Map(description.workflows.map((wf) => [apiNameOf(wf.name), wf.name]));
@@ -193,11 +202,11 @@ export function readSites(
     return { call: { kind, target, via, ...at }, ...(problem && { problem }) };
   };
 
-  return siteNames(dir).map((name) => {
-    const read = readSiteFiles(root, name);
-    const resolved = read.flatMap(({ uses }) => uses.map(resolve));
+  return sitesUnder(root).map(({ name, app, dir }) => {
+    const read = readSiteFiles(root, dir);
+    const resolved = read.flatMap(({ uses }) => uses.filter((use) => !isAppCollection(use)).map(resolve));
     const pages = pagesOf(read);
-    const siteFile = `sites/${name}/site.ts`;
+    const siteFile = `${dir}/site.ts`;
     const { problems: optionProblems, ...options } = siteOptionsOf(join(root, siteFile), connectors);
     const calls = resolved.map((r) => r.call);
     const problems = [
@@ -212,7 +221,7 @@ export function readSites(
     const warnings = options.public
       ? read.flatMap(({ route, warning }) => (warning && !pages.get(route!.path)?.content ? [warning] : []))
       : [];
-    return { name, ...options, pages: sorted, calls, problems, warnings };
+    return { name, ...(app && { app }), ...options, pages: sorted, calls, problems, warnings };
   });
 }
 
@@ -225,9 +234,9 @@ function pagesOf(read: readonly { route?: SitePage }[]): Map<string, SitePage> {
   return pages;
 }
 
-/** Each of site `name`'s files under `root`, as `readSiteFile` reads it, by path. */
-const readSiteFiles = (root: string, name: string) =>
-  SITE_DIRS.flatMap((sub) => filesUnder(join(root, "sites", name, sub), isSource))
+/** Each file of the site in `dir` (relative to `root`), as `readSiteFile` reads it, by path. */
+const readSiteFiles = (root: string, dir: string) =>
+  SITE_DIRS.flatMap((sub) => filesUnder(join(root, dir, sub), isSource))
     .toSorted()
     .flatMap((path) => {
       const file = readSource(path);
@@ -241,8 +250,8 @@ const readSiteFiles = (root: string, name: string) =>
  */
 export function siteContentPages(root: string): Record<string, string> {
   return Object.fromEntries(
-    siteNames(join(root, "sites")).flatMap((name) =>
-      [...pagesOf(readSiteFiles(root, name)).values()].flatMap(({ path, content }) =>
+    sitesUnder(root).flatMap(({ dir }) =>
+      [...pagesOf(readSiteFiles(root, dir)).values()].flatMap(({ path, content }) =>
         content ? [[path, content]] : [],
       ),
     ),
@@ -257,13 +266,44 @@ export function siteContentPages(root: string): Record<string, string> {
 export function siteLocales(root: string): Record<string, string[]> {
   const none = new Set<string>();
   return Object.fromEntries(
-    siteNames(join(root, "sites")).flatMap((name) => {
-      const { locales } = siteOptionsOf(join(root, "sites", name, "site.ts"), { vendors: none, logins: none });
+    sitesUnder(root).flatMap(({ name, dir }) => {
+      const { locales } = siteOptionsOf(join(root, dir, "site.ts"), { vendors: none, logins: none });
       return locales ? [[name, locales]] : [];
     }),
   );
 }
 
+/**
+ * Each site's icon (`defineSite({ icon })`, a Lucide icon's name as written) under `root`, by name,
+ * for the sites whose `site.ts` gives one: the icons the app's build bundles (`virtual:sanoma/icons`).
+ * Read as `readSites` reads it, never run.
+ */
+export function siteIcons(root: string): Record<string, string> {
+  const none = new Set<string>();
+  return Object.fromEntries(
+    sitesUnder(root).flatMap(({ name, dir }) => {
+      const { icon } = siteOptionsOf(join(root, dir, "site.ts"), { vendors: none, logins: none });
+      return icon === undefined ? [] : [[name, icon]];
+    }),
+  );
+}
+
+/**
+ * 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`.
+ */
+export const sitesUnder = (root: string): { name: string; app?: string; dir: string }[] => [
+  ...siteNames(join(root, "sites")).map((name) => ({ name, dir: `sites/${name}` })),
+  ...appFolders(root).flatMap((folder) => {
+    const app = basename(folder);
+    return siteNames(join(folder, "sites")).map((name) => ({
+      name: siteKey(app, name),
+      app,
+      dir: `${APPS_DIR}/${app}/sites/${name}`,
+    }));
+  }),
+];
+
 /** The sites in `dir`: each folder with a `routes/` whose name is a URL segment, sorted. */
 const siteNames = (dir: string): string[] =>
   isDirectory(dir)
@@ -379,9 +419,12 @@ function contentKind(callee: Node, content: ReadonlySet<string>): string | undef
 function apiPath(member: Node, api: ReadonlySet<string>): Pick<Written, "kind" | "name" | "method"> | undefined {
   const path = memberPath(member, api);
   if (!path?.length) return undefined;
-  const [first, second, third] = path as [string, ...string[]];
+  const [first, second] = path as [string, ...string[]];
+  // `api.data.<collection>.<op>`, or an app's, `api.data.<app>.<collection>.<op>`.
   if (first === DATA_VENDOR)
-    return path.length === 3 ? { kind: "collection", name: second!, method: third } : undefined;
+    return path.length === 3 || path.length === 4
+      ? { kind: "collection", name: path.slice(1, -1).join("."), method: path.at(-1) }
+      : undefined;
   if (path.length === 3) return { kind: "op", name: path.join(".") };
   if (path.length > 2) return undefined;
   return { kind: "workflow", name: first, ...(second !== undefined && { method: second }) };
@@ -414,14 +457,14 @@ const unread = (what: string, as: string) => `${what} is read without running si
 /**
  * What `site.ts` says of its site, read without running it, and what is wrong there: its default
  * export must be `defineSite({ … })` written out, so it can be read at all; then `title` when it is
- * a string, `public`, `login` and `locales`, which must be literals. `login` is kept as written; one on a
+ * a string, `icon`, `public`, `login` and `locales`, which must be literals. `login` is kept as written; one on a
  * site that is not public, or naming no connector of the config with a login half, is a problem.
  * `locales` is kept only when it has no problem.
  */
 function siteOptionsOf(
   path: string,
   connectors: SiteConnectors,
-): Pick<SiteEntry, "title" | "public" | "login" | "locales"> & { problems: LintProblem[] } {
+): Pick<SiteEntry, "title" | "icon" | "public" | "login" | "locales"> & { problems: LintProblem[] } {
   const file = readSource(path);
   if (typeof file === "string") return { problems: [] };
   const problems: LintProblem[] = [...file.problems];
@@ -453,6 +496,8 @@ function siteOptionsOf(
     options?.properties.findLast((p: Node) => isWritten(p) && keyName(p.key) === name);
 
   const title = stringValue(property("title")?.value);
+  // Cosmetic: one that is not a string (tsc refuses it) is shown as none, never a problem that stops a site.
+  const icon = stringValue(property("icon")?.value);
   const publicAt = property("public");
   const flag = unwrap(publicAt?.value);
   const isPublic = flag?.type === "Literal" && flag.value === true;
@@ -495,6 +540,7 @@ function siteOptionsOf(
   if (localesMessage) problem(localesAt, localesMessage);
   return {
     ...(title !== undefined && { title }),
+    ...(icon !== undefined && { icon }),
     ...(isPublic && { public: true as const }),
     ...(login !== undefined && { login }),
     ...(localesAt && !localesMessage && isPublic && !loginAt && { locales }),