@celilo/cli 1.14.0 → 2.0.0

package/src/services/static-content-converge.ts

@@ -0,0 +1,299 @@
+/**
+ * The static-content converge (openspec/changes/capability-owned-tables,
+ * stage 4 / design D10).
+ *
+ * `/srv/www` on the public_web provider stops being whatever the last
+ * hand-built ssh upload left there and becomes convergent state: every
+ * declared static route's release directory exists, `/srv/www/<slug>` points
+ * at the current one through an atomic symlink swap, and everything past the
+ * retention count is pruned. One Ansible converge makes the host match.
+ *
+ * Two callers, one code path:
+ *  - the `public_web` capability's publish (`convergeStaticContent` callback
+ *    injected by capability-loader), which runs the whole converge including
+ *    `executeAnsible`, so a publish returns only once the host matches; and
+ *  - the provider's OWN deploy (module-deploy), which writes the same release
+ *    set into its generated inventory and lets the deploy's existing
+ *    `executeAnsible` run the same role tasks — that is how a rebuilt host
+ *    recovers with no consumer involvement (design D10, task 4.5).
+ *
+ * The desired state is the declared `web_routes` release set plus the source
+ * directory core derived from `modules.source_path`. Nothing here writes into
+ * a module tree: reading a module's web root is safe, writing is what breaks
+ * `module verify` (celilo#1018, deliberately left to that thread).
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { and, eq, isNotNull } from 'drizzle-orm';
+import { stringify as stringifyYaml } from 'yaml';
+import type { DbClient } from '../db/client';
+import { moduleConfigs, modules, webRoutes } from '../db/schema';
+import { resolveModuleWebRoot } from '../module/web-root';
+import { parseStoredConfigValue } from './module-config';
+
+/** One content-hashed release the provider host must serve. */
+export interface StaticRelease {
+  /** The `/srv/www/<slug>` key. Independent of hostname on purpose. */
+  slug: string;
+  /** Content hash of the release — the release directory's suffix. */
+  contentHash: string;
+  /** Every FQDN served by this slug's routes (a slug spans hostnames). */
+  hostnames: string[];
+  /** Absolute celilo-mgr path core derived: `<module source_path>/site/dist`. */
+  sourceDir: string;
+}
+
+export interface StaticContentPlan {
+  releases: StaticRelease[];
+  /** How many release directories to keep per slug after a converge. */
+  retention: number;
+}
+
+/**
+ * Retention when the operator has not set one. Mirrors the manifest default
+ * declared on the provider module (`static_release_retention`); the manifest
+ * is the operator-facing source of truth, this only covers a provider whose
+ * manifest predates the variable.
+ */
+const DEFAULT_STATIC_RELEASE_RETENTION = 5;
+
+export interface StaticContentConvergeResult {
+  success: boolean;
+  error?: string;
+  /** The written vars file, repo-absolute — for logs and tests. */
+  varsPath?: string;
+}
+
+/**
+ * Where the converge's desired state lands inside the provider's generated
+ * project. `group_vars/all/` is the existing auto-load directory (it already
+ * holds `secrets.yml`), so no playbook change is needed to read it.
+ */
+export function staticContentVarsPath(generatedPath: string): string {
+  return join(generatedPath, 'ansible', 'inventory', 'group_vars', 'all', 'static_content.yml');
+}
+
+/**
+ * Resolve the retention count for the provider module.
+ *
+ * Operator config first (`static_release_retention` module config), then the
+ * manifest's declared default, then the constant above. ONE resolution — the
+ * role reads the variable bare and never carries a literal.
+ */
+export function resolveStaticContentRetention(db: DbClient, providerModuleId: string): number {
+  const configRow = db
+    .select()
+    .from(moduleConfigs)
+    .where(
+      and(
+        eq(moduleConfigs.moduleId, providerModuleId),
+        eq(moduleConfigs.key, 'static_release_retention'),
+      ),
+    )
+    .get();
+  if (configRow) {
+    const parsed = parseStoredConfigValue(configRow);
+    const count = typeof parsed === 'number' ? parsed : Number.parseInt(String(parsed), 10);
+    if (Number.isInteger(count) && count >= 1) return count;
+    throw new Error(
+      `static_release_retention for ${providerModuleId} must be a positive integer, got: ${String(parsed)}`,
+    );
+  }
+
+  const module = db.select().from(modules).where(eq(modules.id, providerModuleId)).get();
+  if (module) {
+    const manifest = module.manifestData as {
+      variables?: { owns?: Array<{ name?: string; default?: unknown }> };
+    } | null;
+    const declared = manifest?.variables?.owns?.find((v) => v?.name === 'static_release_retention');
+    const fallback = typeof declared?.default === 'number' ? declared.default : undefined;
+    if (typeof fallback === 'number' && Number.isInteger(fallback) && fallback >= 1)
+      return fallback;
+  }
+
+  return DEFAULT_STATIC_RELEASE_RETENTION;
+}
+
+/**
+ * Build the release set from the declared `web_routes` rows.
+ *
+ * Pure: reads the DB, decides nothing on the host (Rule 10.4). Grouping is by
+ * slug, NOT by route — one slug is one release directory, and a slug can span
+ * hostnames (lunacycle's two routes, both at `/`). A group that spans modules
+ * or disagrees with itself about the hash is a contradiction the converge
+ * cannot express, so it fails here with both rows named rather than silently
+ * converging one of them.
+ */
+export function planStaticContent(db: DbClient): StaticRelease[] {
+  const rows = db
+    .select()
+    .from(webRoutes)
+    .where(and(eq(webRoutes.type, 'static'), isNotNull(webRoutes.contentHash)))
+    .all();
+
+  const bySlug = new Map<string, typeof rows>();
+  for (const row of rows) {
+    const group = bySlug.get(row.slug) ?? [];
+    group.push(row);
+    bySlug.set(row.slug, group);
+  }
+
+  const releases: StaticRelease[] = [];
+  for (const [slug, group] of bySlug) {
+    const moduleIds = [...new Set(group.map((r) => r.moduleId))];
+    if (moduleIds.length > 1) {
+      throw new Error(
+        `Static route slug "${slug}" is claimed by ${moduleIds.length} modules (${moduleIds.join(', ')}). The slug is the release key — /srv/www/${slug} cannot serve two release sets. Fix the colliding modules' registered paths.`,
+      );
+    }
+    const moduleId = moduleIds[0];
+    if (!moduleId) continue;
+
+    const hashes = [...new Set(group.map((r) => r.contentHash))];
+    if (hashes.length > 1) {
+      throw new Error(
+        `Static route slug "${slug}" (module ${moduleId}) holds ${hashes.length} content hashes (${hashes.join(', ')}) — rows sharing a slug must share a release. Re-publish the module so every row carries the current hash.`,
+      );
+    }
+    const contentHash = hashes[0];
+    if (!contentHash) continue;
+
+    const sourceDir = resolveModuleWebRoot(moduleId, db);
+    if (!sourceDir) {
+      throw new Error(
+        `Static route slug "${slug}" belongs to module "${moduleId}", which is not installed — its release has no source to converge from.`,
+      );
+    }
+    if (!existsSync(sourceDir)) {
+      throw new Error(
+        `Static route slug "${slug}": no built site at ${sourceDir}. A module that serves a static site ships it at <module root>/site/dist. Redeploy the module.`,
+      );
+    }
+
+    releases.push({
+      slug,
+      contentHash,
+      hostnames: [...new Set(group.map((r) => r.hostname))].sort(),
+      sourceDir,
+    });
+  }
+
+  releases.sort((a, b) => a.slug.localeCompare(b.slug));
+  return releases;
+}
+
+/**
+ * The full desired state: the release set plus the retention count resolved
+ * for THIS provider module. The unit the vars file and the tests speak in.
+ */
+export function buildStaticContentPlan(db: DbClient, providerModuleId: string): StaticContentPlan {
+  return {
+    releases: planStaticContent(db),
+    retention: resolveStaticContentRetention(db, providerModuleId),
+  };
+}
+
+/**
+ * Render the vars file. Presentation function (Rule 10.1) — deterministic
+ * YAML, keyed by slug, carrying what 4.1 names: slug, content_hash, the
+ * hostnames served, and the source directory core derived.
+ */
+export function staticContentVarsYaml(plan: StaticContentPlan): string {
+  const vars = {
+    static_release_retention: plan.retention,
+    static_releases: plan.releases.map((r) => ({
+      slug: r.slug,
+      content_hash: r.contentHash,
+      hostnames: r.hostnames,
+      source_dir: r.sourceDir,
+    })),
+  };
+  const header =
+    '# Desired static-content state, generated by celilo (capability-owned-tables D10).\n' +
+    '# Hand edits are overwritten by the next converge. K = static_release_retention.\n';
+  return `${header}${stringifyYaml(vars, { lineWidth: 0, sortMapEntries: true })}`;
+}
+
+/**
+ * Plan the release set and write it into the provider's generated inventory.
+ *
+ * The shared half of both converge triggers: the capability's callback adds
+ * `executeAnsible` after this, and the provider's own deploy already runs it.
+ * Writing happens AFTER the deploy's staleness check (`refuseIfGeneratedIsStale`
+ * only inspects verbatim role assets), so an injected vars file never reads as
+ * a stale generation.
+ */
+export async function writeStaticContentVars(
+  db: DbClient,
+  providerModuleId: string,
+  generatedPath: string,
+): Promise<StaticContentConvergeResult> {
+  const varsPath = staticContentVarsPath(generatedPath);
+
+  const plan = buildStaticContentPlan(db, providerModuleId);
+
+  await mkdir(join(varsPath, '..'), { recursive: true });
+  await writeFile(varsPath, staticContentVarsYaml(plan), 'utf-8');
+  return { success: true, varsPath };
+}
+
+/**
+ * The full converge: plan, write the desired state, run Ansible against the
+ * provider's generated project.
+ *
+ * `generatedPath` must already exist — it is the project the provider's last
+ * deploy generated. If the project predates the converge role tasks, the
+ * written state would be read by nothing and the transfer would silently
+ * never happen, so the playbook is checked for the converge's own variable
+ * first and a stale project fails loudly with the redeploy that fixes it.
+ */
+export async function convergeStaticContent(
+  db: DbClient,
+  providerModuleId: string,
+): Promise<StaticContentConvergeResult> {
+  const module = db.select().from(modules).where(eq(modules.id, providerModuleId)).get();
+  if (!module) {
+    return { success: false, error: `Provider module '${providerModuleId}' is not installed` };
+  }
+  const generatedPath = join(module.sourcePath, 'generated');
+  if (!existsSync(generatedPath)) {
+    return {
+      success: false,
+      error:
+        `public_web provider '${providerModuleId}' has no generated deploy project at ${generatedPath}. ` +
+        `Run \`celilo module deploy ${providerModuleId}\` once, then retry the publish.`,
+    };
+  }
+
+  const written = await writeStaticContentVars(db, providerModuleId, generatedPath);
+
+  // A generated project that predates the converge role tasks would read the
+  // new vars file and converge nothing. `static_releases` appearing nowhere in
+  // the playbook is the tell. Generic string check — core names no module.
+  const playbookPath = join(generatedPath, 'ansible', 'playbook.yml');
+  if (
+    existsSync(playbookPath) &&
+    !readFileSync(playbookPath, 'utf-8').includes('static_releases')
+  ) {
+    return {
+      success: false,
+      error: `The generated project for '${providerModuleId}' predates the static-content converge (its playbook never reads static_releases). Redeploy the provider (\`celilo module deploy ${providerModuleId}\`) to regenerate it, then retry the publish.`,
+    };
+  }
+
+  const { executeAnsible } = await import('./deploy-ansible');
+  // Tag-scoped: the full playbook re-templates the bootstrap Caddyfile, which
+  // would replace the real config the provider's reconcile wrote and reload
+  // caddy into serving nothing. A publish converge touches /srv/www only.
+  const result = await executeAnsible(generatedPath, { tags: ['static_content'] });
+  if (!result.success) {
+    return {
+      success: false,
+      error: `Static-content converge failed on ${providerModuleId}: ${result.error ?? 'unknown error'}`,
+      varsPath: written.varsPath,
+    };
+  }
+  return { success: true, varsPath: written.varsPath };
+}