create-freeholder 0.0.0-bootstrap.0 → 0.2.0-beta.2

package/dist/template/src/core/update/policy.ts

@@ -0,0 +1,111 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Update policy: windows in business timezone, security-auto defaults (C10.08).
+import { channelReceives, type ReleaseChannel } from "./channels";
+import type { APPLY_LEVELS, POLICY_CHANNELS } from "./schema";
+
+export type PolicyChannel = (typeof POLICY_CHANNELS)[number];
+export type ApplyLevel = (typeof APPLY_LEVELS)[number];
+
+export const DEFAULT_UPDATE_WINDOW = {
+  days: ["tue", "wed", "thu"] as string[],
+  start: "03:00",
+};
+export const WINDOW_LENGTH_MINUTES = 120;
+
+export interface UpdatePolicy {
+  channel: PolicyChannel;
+  applyLevel: ApplyLevel;
+  window: { days: string[]; start: string };
+  drain: boolean;
+  notifyChannels: string[];
+  keepSnapshots: number;
+  lastCheckedAt: Date | null;
+  pausedUntil: Date | null;
+}
+
+export const DEFAULT_UPDATE_POLICY: UpdatePolicy = {
+  channel: "security",
+  applyLevel: "security",
+  window: { ...DEFAULT_UPDATE_WINDOW, days: [...DEFAULT_UPDATE_WINDOW.days] },
+  drain: true,
+  notifyChannels: ["email", "sms"],
+  keepSnapshots: 5,
+  lastCheckedAt: null,
+  pausedUntil: null,
+};
+
+export function policyReceives(channel: PolicyChannel, offered: ReleaseChannel): boolean {
+  if (channel === "off") return false;
+  return channelReceives(channel, offered);
+}
+
+function parseStartMinutes(start: string): number | null {
+  const match = /^([01]?\d|2[0-3]):([0-5]\d)$/.exec(start.trim());
+  if (!match) return null;
+  return Number(match[1]) * 60 + Number(match[2]);
+}
+
+export function zonedMinutes(now: Date, timeZone: string): { weekday: string; minutes: number } {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    weekday: "short",
+    hour: "2-digit",
+    minute: "2-digit",
+    hourCycle: "h23",
+  }).formatToParts(now);
+  const weekday = (parts.find((part) => part.type === "weekday")?.value ?? "Sun").slice(0, 3).toLowerCase();
+  const hour = Number(parts.find((part) => part.type === "hour")?.value ?? "0");
+  const minute = Number(parts.find((part) => part.type === "minute")?.value ?? "0");
+  return { weekday, minutes: hour * 60 + minute };
+}
+
+/** Skip rather than force: outside the window is a no, not a later retry here. */
+export function inUpdateWindow(
+  now: Date,
+  timeZone: string,
+  window: { days: string[]; start: string } = DEFAULT_UPDATE_WINDOW,
+): boolean {
+  const start = parseStartMinutes(window.start);
+  if (start === null || window.days.length === 0) return false;
+  const { weekday, minutes } = zonedMinutes(now, timeZone);
+  if (!window.days.includes(weekday)) return false;
+  const elapsed = (minutes - start + 24 * 60) % (24 * 60);
+  return elapsed < WINDOW_LENGTH_MINUTES;
+}
+
+export function isPaused(policy: UpdatePolicy, now: Date): boolean {
+  return policy.pausedUntil !== null && policy.pausedUntil.getTime() > now.getTime();
+}
+
+/**
+ * Security-auto default: only security-channel releases apply themselves.
+ * Feature (stable/edge) updates are offered and need approval.
+ */
+export function shouldAutoApply(
+  policy: UpdatePolicy,
+  release: { channel: ReleaseChannel },
+  now: Date,
+  timeZone: string,
+): boolean {
+  if (policy.channel === "off" || isPaused(policy, now)) return false;
+  if (!policyReceives(policy.channel, release.channel)) return false;
+  if (!inUpdateWindow(now, timeZone, policy.window)) return false;
+  if (policy.applyLevel === "none") return false;
+  if (policy.applyLevel === "security") return release.channel === "security";
+  if (policy.applyLevel === "patch") return release.channel === "security";
+  return true;
+}
+
+export function requiresApproval(
+  policy: UpdatePolicy,
+  release: { channel: ReleaseChannel },
+): boolean {
+  if (policy.channel === "off") return false;
+  if (!policyReceives(policy.channel, release.channel)) return false;
+  if (policy.applyLevel === "none") return true;
+  if (policy.applyLevel === "security" || policy.applyLevel === "patch") {
+    return release.channel !== "security";
+  }
+  return false;
+}

package/dist/template/src/core/update/preflight.ts

@@ -0,0 +1,258 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Update preflight (MASTER.md §39.4, C10.05). Honest about what it cannot know.
+import { randomUUID } from "node:crypto";
+import { statfs } from "node:fs/promises";
+import { sql } from "drizzle-orm";
+import postgres from "postgres";
+import { pluginFitsPlatform } from "@freeholder/plugin-kit";
+import { db } from "@/core/db";
+import { databaseUrl, env } from "@/core/env";
+import { installedPlugins } from "@/core/plugins/schema";
+import instanceConfig from "../../../freeholder.config";
+import { inspectCoreFiles } from "./integrity";
+import { verifyReleaseFeed, type VerifiedRelease } from "./feed";
+import { THIS_RELEASE } from "./this-release";
+
+export type PreflightVerdict = "ok" | "warn" | "fail";
+
+export interface PreflightStep {
+  id: string;
+  verdict: PreflightVerdict;
+  detail: string;
+}
+
+export interface PreflightReport {
+  ok: boolean;
+  estimatedDowntimeMs: number;
+  steps: PreflightStep[];
+}
+
+const SNAPSHOT_BYTES = 256 * 1024 * 1024;
+
+function quoteIdent(name: string): string {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new Error(`Refusing to quote identifier ${name}`);
+  }
+  return `"${name}"`;
+}
+
+function step(id: string, verdict: PreflightVerdict, detail: string): PreflightStep {
+  return { id, verdict, detail };
+}
+
+export function pluginCompatibility(
+  plugins: { name: string; freeholder: string }[],
+  platformVersion: string,
+): PreflightStep {
+  const broken = plugins.filter((plugin) => !pluginFitsPlatform(plugin.freeholder, platformVersion));
+  if (broken.length === 0) {
+    return step(
+      "plugins",
+      "ok",
+      plugins.length === 0
+        ? "No plugins are installed."
+        : `All ${plugins.length} installed plugin${plugins.length === 1 ? "" : "s"} fit ${platformVersion}.`,
+    );
+  }
+  return step(
+    "plugins",
+    "fail",
+    `Cannot apply ${platformVersion}: ${broken.map((plugin) => `${plugin.name} needs ${plugin.freeholder}`).join("; ")}.`,
+  );
+}
+
+export async function environmentPreflight(): Promise<PreflightStep[]> {
+  const steps: PreflightStep[] = [];
+  try {
+    const disk = await statfs(process.cwd());
+    const free = Number(disk.bavail) * Number(disk.bsize);
+    steps.push(
+      free >= SNAPSHOT_BYTES
+        ? step("disk", "ok", `Free disk is enough for a snapshot (${Math.round(free / 1024 / 1024)} MiB).`)
+        : step(
+            "disk",
+            "fail",
+            `Free disk is ${Math.round(free / 1024 / 1024)} MiB; a snapshot needs about ${SNAPSHOT_BYTES / 1024 / 1024} MiB.`,
+          ),
+    );
+  } catch (error) {
+    steps.push(
+      step("disk", "warn", `Could not measure free disk (${error instanceof Error ? error.message : String(error)}).`),
+    );
+  }
+
+  try {
+    const [row] = await db().execute<{ version: string }>(
+      sql`select current_setting('server_version') as version`,
+    );
+    const major = Number.parseInt(row?.version ?? "0", 10);
+    steps.push(
+      major >= 15
+        ? step("postgres", "ok", `Postgres ${row?.version}.`)
+        : step("postgres", "fail", `Postgres ${row?.version} is below 15.`),
+    );
+  } catch (error) {
+    steps.push(
+      step("postgres", "fail", `Could not read Postgres version (${error instanceof Error ? error.message : String(error)}).`),
+    );
+  }
+
+  try {
+    const rows = await db().execute<{ extname: string }>(sql`select extname from pg_extension`);
+    const names = rows.map((row) => row.extname);
+    steps.push(
+      names.includes("plpgsql")
+        ? step("extensions", "ok", `Extensions: ${names.join(", ") || "none"}.`)
+        : step("extensions", "fail", "Required extension plpgsql is missing."),
+    );
+  } catch (error) {
+    steps.push(
+      step("extensions", "warn", `Could not list extensions (${error instanceof Error ? error.message : String(error)}).`),
+    );
+  }
+
+  const e = env();
+  const storage = e.FREEHOLDER_STORAGE ?? instanceConfig.adapters.storage;
+  if (storage === "local" && e.NODE_ENV === "production" && e.FREEHOLDER_UNSAFE_LOCAL_STORAGE !== "1") {
+    steps.push(step("adapters", "fail", "Uploads are on local disk in production, which does not survive a rebuild."));
+  } else {
+    steps.push(step("adapters", "ok", `Storage adapter is ${storage}.`));
+  }
+  return steps;
+}
+
+export async function shadowMigration(extraSql: string[] = []): Promise<{ ok: boolean; ms: number; detail: string }> {
+  const schema = `preflight_${randomUUID().replaceAll("-", "").slice(0, 16)}`;
+  const conn = postgres(databaseUrl(), { max: 1, connect_timeout: 5, onnotice: () => {} });
+  const started = Date.now();
+  try {
+    await conn.unsafe(`CREATE SCHEMA ${quoteIdent(schema)}`);
+    const tables = await conn<{ tablename: string }[]>`
+      SELECT tablename FROM pg_tables WHERE schemaname = 'public'
+    `;
+    for (const { tablename } of tables) {
+      await conn.unsafe(
+        `CREATE TABLE ${quoteIdent(schema)}.${quoteIdent(tablename)} (LIKE public.${quoteIdent(tablename)} INCLUDING DEFAULTS INCLUDING IDENTITY)`,
+      );
+    }
+    await conn.unsafe(`SET search_path TO ${quoteIdent(schema)}`);
+    for (const statement of extraSql) {
+      await conn.unsafe(statement);
+    }
+    const ms = Date.now() - started;
+    return {
+      ok: true,
+      ms,
+      detail: `Shadow schema cloned ${tables.length} tables in ${ms} ms.`,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      ms: Date.now() - started,
+      detail: `Shadow migration failed: ${error instanceof Error ? error.message : String(error)}.`,
+    };
+  } finally {
+    try {
+      await conn.unsafe(`DROP SCHEMA IF EXISTS ${quoteIdent(schema)} CASCADE`);
+    } catch {
+      // The report already carries the dry-run error if the clone failed.
+    }
+    await conn.end({ timeout: 5 });
+  }
+}
+
+export async function runPreflight(input: {
+  feed?: unknown;
+  targetVersion?: string;
+  extraSql?: string[];
+  root?: string;
+}): Promise<PreflightReport> {
+  const steps: PreflightStep[] = [];
+  let target: Pick<VerifiedRelease, "version" | "pluginApi" | "digest"> = {
+    version: THIS_RELEASE.version,
+    pluginApi: THIS_RELEASE.pluginApi,
+    digest: "",
+  };
+
+  if (input.feed !== undefined) {
+    try {
+      const verified = verifyReleaseFeed(input.feed);
+      const latest = verified.releases[0];
+      if (!latest) {
+        steps.push(step("signature", "fail", "The signed feed contains no releases."));
+      } else {
+        target = latest;
+        steps.push(
+          step(
+            "signature",
+            "ok",
+            `Feed signed by ${verified.keyId}. Target ${latest.version} digest ${latest.digest}.`,
+          ),
+        );
+      }
+    } catch (error) {
+      steps.push(
+        step(
+          "signature",
+          "fail",
+          error instanceof Error ? error.message : "The release feed is not signed by a trusted key.",
+        ),
+      );
+    }
+  } else {
+    steps.push(
+      step("signature", "fail", "No signed release feed supplied; candidate authenticity has not been verified."),
+    );
+  }
+
+  const plugins = await db()
+    .select({ name: installedPlugins.name, freeholder: installedPlugins.freeholder })
+    .from(installedPlugins);
+  steps.push(pluginCompatibility(plugins, input.targetVersion ?? target.pluginApi));
+
+  const core = await inspectCoreFiles({
+    root: input.root ?? process.cwd(),
+    expectedDigest: env().FREEHOLDER_CORE_DIGEST ?? (target.digest || null),
+    hash: Boolean(env().FREEHOLDER_CORE_DIGEST || target.digest),
+  });
+  if (core.matches === false) {
+    steps.push(
+      step(
+        "drift",
+        "fail",
+        "Replaceable core does not match the release digest. This instance is a fork; updates will not overwrite owner code.",
+      ),
+    );
+  } else if (core.modified.length > 0) {
+    steps.push(
+      step(
+        "drift",
+        "warn",
+        `${core.modified.length} core file${core.modified.length === 1 ? " was" : "s were"} edited. The fork lane is the supported path.`,
+      ),
+    );
+  } else {
+    steps.push(step("drift", "ok", "No unsupported live core-file edits detected."));
+  }
+
+  steps.push(...(await environmentPreflight()));
+
+  const shadow = await shadowMigration(input.extraSql ?? []);
+  steps.push(step("migrations", shadow.ok ? "ok" : "fail", shadow.detail));
+  steps.push(
+    step(
+      "downtime",
+      shadow.ok ? "ok" : "fail",
+      shadow.ok
+        ? `Estimated downtime from the dry run is ${shadow.ms} ms.`
+        : "Downtime cannot be estimated because the shadow migration failed.",
+    ),
+  );
+
+  return {
+    ok: steps.every((item) => item.verdict !== "fail"),
+    estimatedDowntimeMs: shadow.ok ? shadow.ms : 0,
+    steps,
+  };
+}

package/dist/template/src/core/update/release-declaration.json

@@ -0,0 +1,19 @@
+{
+  "version": "0.2.0-beta.2",
+  "channel": "edge",
+  "minFromVersion": "0.1.0",
+  "schemaRisk": "breaking",
+  "cvss": null,
+  "severity": "none",
+  "manualSteps": [
+    {
+      "id": "backup-database-and-objects",
+      "summary": "Before updating, save a database archive, all original and variant object bytes, the current immutable image pin, and private recovery keys; verify the archive and object checksums."
+    },
+    {
+      "id": "rehearse-upgrade-and-recovery",
+      "summary": "Restore the backup and object bytes into an isolated instance and verify publishing, file delivery and health. If the update fails, restore that database and objects and run the previous image before reopening traffic."
+    }
+  ],
+  "pluginApi": "0.1.0"
+}

package/dist/template/src/core/update/release-validation.d.mts

@@ -0,0 +1,5 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+import type { ReleaseMetadata, Severity } from "./release";
+export function severityForCvss(cvss: number): Severity;
+export function validateReleaseMetadata(input: unknown): ReleaseMetadata;

package/dist/template/src/core/update/release-validation.mjs

@@ -0,0 +1,29 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// One metadata validator for the running image and its publication (C10.02).
+import { RELEASE_VERSION, compareReleaseVersions } from "./release-version.mjs";
+
+export function severityForCvss(cvss) {
+  return cvss <= 0 ? "none" : cvss < 4 ? "low" : cvss < 7 ? "medium" : cvss < 9 ? "high" : "critical";
+}
+
+export function validateReleaseMetadata(input) {
+  const invalid = (field) => { throw new Error(`${field} is missing or invalid. Compatibility, schema risk, CVSS and manual steps must be declared; the updater will not infer them from a version number.`); };
+  if (!input || typeof input !== "object" || Array.isArray(input)) invalid("metadata");
+  for (const field of ["version", "minFromVersion", "pluginApi"]) {
+    if (typeof input[field] !== "string" || !RELEASE_VERSION.test(input[field])) invalid(field);
+  }
+  if (!["stable", "security", "edge"].includes(input.channel)) invalid("channel");
+  if (!["compatible", "breaking"].includes(input.schemaRisk)) invalid("schemaRisk");
+  if (input.cvss !== null && (typeof input.cvss !== "number" || !Number.isFinite(input.cvss) || input.cvss < 0 || input.cvss > 10)) invalid("cvss");
+  if (!["none", "low", "medium", "high", "critical"].includes(input.severity)) invalid("severity");
+  if (!Array.isArray(input.manualSteps) || input.manualSteps.some((step) => !step || typeof step.id !== "string" || !step.id.trim() || typeof step.summary !== "string" || !step.summary.trim())) invalid("manualSteps");
+  if (compareReleaseVersions(input.minFromVersion, input.version) > 0) throw new Error(`minFromVersion ${input.minFromVersion} is after version ${input.version}, so nothing could apply this release.`);
+  if (input.version.includes("-") && input.channel !== "edge") throw new Error("A prerelease belongs to edge; stable and security releases require a final version.");
+  if (input.cvss === null && input.severity !== "none") throw new Error("severity without a CVSS score is incomplete. Declare both, or neither.");
+  if (input.cvss !== null && severityForCvss(input.cvss) !== input.severity) throw new Error(`severity ${input.severity} does not match CVSS ${input.cvss}. Declare the NVD band that score actually falls in.`);
+  if (input.channel === "security" && (input.cvss === null || input.cvss <= 0)) throw new Error("A security-channel release must include a CVSS score. The updater will not treat a patch version as a security fix.");
+  if (input.channel === "security" && input.schemaRisk === "breaking") throw new Error("A security-channel release cannot break schema. Security patches are backports of fixes, not a place for contract changes.");
+  const { version, channel, minFromVersion, schemaRisk, cvss, severity, manualSteps, pluginApi } = input;
+  return { version, channel, minFromVersion, schemaRisk, cvss, severity, manualSteps, pluginApi };
+}

package/dist/template/src/core/update/release-version.d.mts

@@ -0,0 +1,4 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+export const RELEASE_VERSION: RegExp;
+export function compareReleaseVersions(a: string, b: string): number | null;

package/dist/template/src/core/update/release-version.mjs

@@ -0,0 +1,36 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Published SemVer identities, shared by runtime and release tooling (C10.02).
+const numeric = "(?:0|[1-9][0-9]*)";
+const identifier = `(?:${numeric}|[0-9]*[A-Za-z-][0-9A-Za-z-]*)`;
+export const RELEASE_VERSION = new RegExp(`^${numeric}\\.${numeric}\\.${numeric}(?:-${identifier}(?:\\.${identifier})*)?$`);
+
+function compareIdentifier(a, b) {
+  const aNumeric = /^[0-9]+$/.test(a);
+  const bNumeric = /^[0-9]+$/.test(b);
+  if (aNumeric && bNumeric) return a.length - b.length || (a < b ? -1 : a > b ? 1 : 0);
+  if (aNumeric !== bNumeric) return aNumeric ? -1 : 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+export function compareReleaseVersions(a, b) {
+  if (!RELEASE_VERSION.test(a) || !RELEASE_VERSION.test(b)) return null;
+  const [aCore, aPre] = a.split(/-(.*)/s);
+  const [bCore, bPre] = b.split(/-(.*)/s);
+  const left = aCore.split(".");
+  const right = bCore.split(".");
+  for (let i = 0; i < 3; i += 1) {
+    const order = compareIdentifier(left[i], right[i]);
+    if (order) return order;
+  }
+  if (!aPre || !bPre) return aPre ? -1 : bPre ? 1 : 0;
+  const aParts = aPre.split(".");
+  const bParts = bPre.split(".");
+  for (let i = 0; i < Math.max(aParts.length, bParts.length); i += 1) {
+    if (aParts[i] === undefined) return -1;
+    if (bParts[i] === undefined) return 1;
+    const order = compareIdentifier(aParts[i], bParts[i]);
+    if (order) return order;
+  }
+  return 0;
+}

package/dist/template/src/core/update/release.ts

@@ -0,0 +1,97 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Machine-readable release metadata (MASTER.md §39.2, C10.02). Compatibility,
+// schema risk, CVSS and manual steps are declared; the updater never infers
+// them from a version number.
+import { z } from "zod";
+import { RELEASE_VERSION, compareReleaseVersions } from "./release-version.mjs";
+import { validateReleaseMetadata } from "./release-validation.mjs";
+export { severityForCvss } from "./release-validation.mjs";
+import {
+  RELEASE_CHANNELS,
+  type ReleaseChannel,
+} from "./channels";
+
+export const SEVERITIES = ["none", "low", "medium", "high", "critical"] as const;
+export type Severity = (typeof SEVERITIES)[number];
+
+export const SCHEMA_RISKS = ["compatible", "breaking"] as const;
+export type SchemaRisk = (typeof SCHEMA_RISKS)[number];
+
+export interface ManualStep {
+  id: string;
+  summary: string;
+}
+
+export interface ReleaseMetadata {
+  version: string;
+  channel: ReleaseChannel;
+  minFromVersion: string;
+  schemaRisk: SchemaRisk;
+  cvss: number | null;
+  severity: Severity;
+  manualSteps: ManualStep[];
+  pluginApi: string;
+}
+
+export class ReleaseMetadataError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ReleaseMetadataError";
+  }
+}
+
+const semver = z
+  .string()
+  .regex(RELEASE_VERSION, "must be a SemVer release version");
+
+export const releaseMetadataSchema = z.object({
+  version: semver,
+  channel: z.enum(RELEASE_CHANNELS),
+  minFromVersion: semver,
+  schemaRisk: z.enum(SCHEMA_RISKS),
+  cvss: z.number().min(0).max(10).nullable(),
+  severity: z.enum(SEVERITIES),
+  manualSteps: z.array(
+    z.object({
+      id: z.string().min(1),
+      summary: z.string().min(1),
+    }),
+  ),
+  pluginApi: semver,
+});
+
+function refuse(message: string): never {
+  throw new ReleaseMetadataError(message);
+}
+
+export function parseReleaseMetadata(input: unknown): ReleaseMetadata {
+  try {
+    return validateReleaseMetadata(input);
+  } catch (error) {
+    refuse(error instanceof Error ? error.message : String(error));
+  }
+}
+
+export function canApplyFrom(
+  fromVersion: string,
+  release: ReleaseMetadata,
+): { ok: boolean; reason: string } {
+  if (!RELEASE_VERSION.test(fromVersion)) {
+    return { ok: false, reason: `"${fromVersion}" is not semver, so this release cannot be applied from it.` };
+  }
+  const order = compareReleaseVersions(fromVersion, release.minFromVersion);
+  if (order === null) {
+    return { ok: false, reason: `"${fromVersion}" is not semver, so this release cannot be applied from it.` };
+  }
+  if (order < 0) {
+    return {
+      ok: false,
+      reason: `This release can be applied from ${release.minFromVersion}, not from ${fromVersion}.`,
+    };
+  }
+  return {
+    ok: true,
+    reason: `This release can be applied from ${fromVersion}.`,
+  };
+}