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

package/dist/template/src/core/services.ts

@@ -0,0 +1,242 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Core's service list — the default export a manifest's `services` loader is
+// expected to provide (MASTER.md §11). Adding a service to core means adding
+// it to the array it already lives in; forgetting to register it is not a
+// separate mistake anyone can make.
+import authServices from "@/core/auth/service";
+import { enterPlayground } from "@/core/demo/playground";
+import { getHostUpdateStatus, requestHostUpdate } from "@/core/update/host";
+import twoFactorServices from "@/core/auth/two-factor";
+import sessionManagementServices from "@/core/auth/session-management/service";
+import magicLinkServices from "@/core/auth/magic-links/service";
+import resetServices from "@/core/auth/reset";
+// What a merge and an erasure mean for a run. Imported for the side effect:
+// `core/runs` owns the table, so it owns the obligations that come with a
+// `contact_id`, and something loaded at boot has to make the registration.
+import "@/core/runs/spine";
+import agentServices from "@/core/agents/service";
+import agentExecution from "@/core/agents/execution";
+import agentWrites from "@/core/agents/writes";
+import agentPlaybookServices from "@/core/agents/playbooks";
+import agentPlaybookEvents from "@/core/agents/playbook-events";
+import agentPlaybookSchedules from "@/core/agents/playbook-schedule";
+import apiKeyServices from "@/core/apikeys/service";
+import attestationServices from "@/core/attestations/service";
+import connectionServices from "@/core/connections/service";
+import connectionGrantServices from "@/core/connections/grants";
+import calendarOAuthServices from "@/core/connections/calendar-oauth";
+import calendarSyncServices from "@/core/connections/calendar-sync";
+import mailReadOAuthServices from "@/core/connections/mail-read-oauth";
+import mailImportServices from "@/core/connections/mail-import";
+import calendarBusyServices from "@/core/connections/busy";
+import briefingServices from "@/core/briefing/service";
+import briefingContributorServices from "@/core/briefing/contributors";
+import briefingPlaybookSection from "@/core/briefing/playbook-section";
+import contactServices from "@/core/contacts/service";
+import customFieldServices from "@/core/contacts/custom-fields";
+import duplicateServices from "@/core/contacts/duplicates";
+import organizationServices from "@/core/contacts/organizations";
+import relationshipServices from "@/core/contacts/relationships";
+import privacyServices from "@/core/privacy/service";
+import mediaConsentServices from "@/core/privacy/media-consent";
+import { customerSignInStatus, requestCustomerSignIn } from "@/core/portal/sign-in";
+import { myRecord, actOnMyRecord } from "@/core/portal/record-service";
+import portalServices from "@/core/portal/service";
+import doctorServices from "@/core/doctor/service";
+import eventServices from "@/core/events/service";
+import outboxServices from "@/core/events/outbox-service";
+import i18nServices from "@/core/i18n/service";
+import jobServices from "@/core/jobs/service";
+import guidanceServices from "@/core/guidance/service";
+import demoServices from "@/core/demo/service";
+import demoFixtureServices from "@/core/demo/fixtures";
+import invitationServices from "@/core/invitations/service";
+import locationServices from "@/core/locations/service";
+import coverageServices from "@/core/locations/coverage";
+import mailServices from "@/core/mail/service";
+import mailOAuthServices from "@/core/mail/oauth";
+import mediaServices from "@/core/media/service";
+import notificationServices from "@/core/notifications/service";
+import taskServices from "@/core/tasks/service";
+import noteServices from "@/core/notes/service";
+import segmentServices from "@/core/segments/service";
+import scoringServices from "@/core/scoring/service";
+import searchServices from "@/core/search/service";
+import retentionServices from "@/core/retention/service";
+import entitlementServices from "@/core/entitlements/service";
+import paywallServices from "@/core/paywalls/service";
+import viewServices from "@/core/views/service";
+import contactImportServices from "@/core/import/contacts-service";
+import signupContactImportServices from "@/core/import/signup-contact-service";
+import messagingServices from "@/core/messaging/service";
+import inboxServices from "@/core/messaging/inbox";
+import smsServices from "@/core/messaging/sms";
+import chatServices from "@/core/messaging/chat";
+import schedulingServices from "@/core/scheduling/service";
+import availabilityServices from "@/core/scheduling/availability-service";
+import bookingServices from "@/core/scheduling/bookings";
+import resolverServices from "@/core/scheduling/resolver-service";
+import audienceServices from "@/core/scheduling/audiences";
+import calendarFeedServices from "@/core/scheduling/ics-service";
+import waitlistServices from "@/core/scheduling/waitlist";
+import requirementServices from "@/core/scheduling/requirements";
+import reminderServices from "@/core/scheduling/reminders";
+import roleServices from "@/core/roles/service";
+import cspServices from "@/core/security/csp-reports";
+import seoServices from "@/core/seo/service";
+import settingsServices from "@/core/settings/service";
+import webhookServices from "@/core/webhooks/service";
+import contributeServices from "@/core/contribute/service";
+import designServices from "@/core/design/service";
+import pluginServices from "@/core/plugins/service";
+import importServices from "@/core/import/service";
+import portabilityServices from "@/core/portability/service";
+import provenanceServices from "@/core/provenance/service";
+import updateSeamServices from "@/core/update/service";
+import catalogueServices from "@/core/catalogue/service";
+import type { Service } from "@/core/service";
+import type { EventDeliveryContext } from "@/core/events";
+
+const services: Service[] = [
+  enterPlayground,
+  getHostUpdateStatus,
+  requestHostUpdate,
+  ...authServices,
+  ...twoFactorServices,
+  ...sessionManagementServices,
+  ...magicLinkServices,
+  ...resetServices,
+  ...agentServices,
+  ...agentExecution,
+  ...agentWrites,
+  ...agentPlaybookServices,
+  ...agentPlaybookEvents,
+  ...agentPlaybookSchedules,
+  ...apiKeyServices,
+  ...attestationServices,
+  ...connectionServices,
+  ...connectionGrantServices,
+  ...calendarOAuthServices,
+  ...calendarSyncServices,
+  ...mailReadOAuthServices,
+  ...mailImportServices,
+  ...calendarBusyServices,
+  ...taskServices,
+  ...noteServices,
+  ...segmentServices,
+  ...scoringServices,
+  ...searchServices,
+  ...retentionServices,
+  ...entitlementServices,
+  ...paywallServices,
+  ...viewServices,
+  ...contactImportServices,
+  ...signupContactImportServices,
+  ...messagingServices,
+  ...inboxServices,
+  ...smsServices,
+  ...chatServices,
+  ...briefingServices,
+  ...briefingContributorServices,
+  ...briefingPlaybookSection,
+  ...contactServices,
+  ...customFieldServices,
+  ...duplicateServices,
+  ...organizationServices,
+  ...relationshipServices,
+  ...privacyServices,
+  ...mediaConsentServices,
+  ...coverageServices,
+  ...portalServices,
+  myRecord,
+  actOnMyRecord,
+  customerSignInStatus,
+  requestCustomerSignIn,
+  ...doctorServices,
+  ...eventServices,
+  ...outboxServices,
+  ...i18nServices,
+  ...jobServices,
+  ...guidanceServices,
+  ...demoServices,
+  ...demoFixtureServices,
+  ...invitationServices,
+  ...locationServices,
+  ...mailServices,
+  ...mailOAuthServices,
+  ...mediaServices,
+  ...notificationServices,
+  ...schedulingServices,
+  ...availabilityServices,
+  ...bookingServices,
+  ...resolverServices,
+  ...audienceServices,
+  ...calendarFeedServices,
+  ...waitlistServices,
+  ...requirementServices,
+  ...reminderServices,
+  ...roleServices,
+  ...cspServices,
+  ...seoServices,
+  ...settingsServices,
+  ...webhookServices,
+  ...contributeServices,
+  ...designServices,
+  ...pluginServices,
+  ...importServices,
+  ...portabilityServices,
+  ...provenanceServices,
+  ...updateSeamServices,
+  ...catalogueServices,
+];
+
+export default services;
+
+/**
+ * Every committed event, offered to the owner's webhooks (§11's bus).
+ *
+ * Failures are swallowed by the bus itself, which is right here: an endpoint
+ * being unreachable must not fail the mutation that produced the event, and
+ * the delivery row already records what happened.
+ */
+export async function onAnyEvent(
+  payload: unknown,
+  eventName: string,
+  context?: EventDeliveryContext,
+): Promise<void> {
+  const { fanOut } = await import("@/core/webhooks/service");
+  const { fanOutEventNotification } = await import("@/core/notifications/service");
+  const { startEventPlaybooks } = await import("@/core/agents/playbook-events");
+  const { mirrorForBookingEvent } = await import("@/core/scheduling/writeback");
+  const { offerForBookingEvent } = await import("@/core/scheduling/waitlist");
+  const { linkSignedWaiver } = await import("@/core/scheduling/requirements");
+  const { convertOnAccepted } = await import("@/modules/quotes/conversion");
+  const { scoreForEvent } = await import("@/core/scoring/service");
+  await Promise.all([
+    fanOut(eventName, payload, context?.eventId),
+    fanOutEventNotification(eventName, payload, context?.eventId),
+    startEventPlaybooks(eventName, payload),
+    // Writing a booking to somebody's Google calendar is a consequence of the
+    // booking having committed, not part of making it (C6.06). An upstream
+    // write cannot be rolled back, so it must not happen inside a transaction
+    // that might still fail.
+    mirrorForBookingEvent(eventName, payload),
+    // A freed seat is only genuinely free once the cancellation has committed
+    // (C6.08). Offering it from inside the mutation would promise somebody a
+    // slot that a rollback then un-frees.
+    offerForBookingEvent(eventName, payload),
+    // Contracts must not know what a booking is (§11's dependency direction),
+    // so scheduling listens for the signature rather than contracts calling in.
+    linkSignedWaiver(eventName, payload),
+    // An accepted quote becomes work once the acceptance has committed
+    // (C6.13). Converting inside it would mean a brief failure in invoicing
+    // rolled back the fact that the customer said yes.
+    convertOnAccepted(eventName, payload),
+    // Points are a consequence of something having happened (C7.05), so they
+    // are awarded here rather than inside the mutation: a scoring bug must not
+    // be able to roll back a quote acceptance. The outbox id is what makes a
+    // redelivery cost nothing instead of doubling somebody's score.
+    scoreForEvent(eventName, payload, context?.eventId),
+  ]);
+}

package/dist/template/src/core/settings/defaults.ts

@@ -0,0 +1,129 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Smart defaults for first boot (MASTER.md §13 step 3): the owner picks a
+// country and the currency, timezone, units and week start follow. They stay
+// editable — the point is that nobody should have to answer five questions
+// when one implies the rest.
+//
+// A starting set, not a world atlas. Adding a country is one row here, and the
+// list is ordered by where a one-person creative business is most likely to be
+// reading this. Timezone is the most common business zone, not the only one.
+
+export interface CountryDefaults {
+  code: string;
+  currency: string;
+  timezone: string;
+  units: "metric" | "imperial";
+  /** 0 = Sunday, matching Date#getDay. */
+  firstDayOfWeek: number;
+  locales: string[];
+}
+
+export const COUNTRY_DEFAULTS: readonly CountryDefaults[] = [
+  { code: "CA", currency: "CAD", timezone: "America/Toronto", units: "metric", firstDayOfWeek: 0, locales: ["en", "fr-CA"] },
+  { code: "US", currency: "USD", timezone: "America/New_York", units: "imperial", firstDayOfWeek: 0, locales: ["en"] },
+  { code: "GB", currency: "GBP", timezone: "Europe/London", units: "metric", firstDayOfWeek: 1, locales: ["en"] },
+  { code: "IE", currency: "EUR", timezone: "Europe/Dublin", units: "metric", firstDayOfWeek: 1, locales: ["en"] },
+  { code: "AU", currency: "AUD", timezone: "Australia/Sydney", units: "metric", firstDayOfWeek: 1, locales: ["en"] },
+  { code: "NZ", currency: "NZD", timezone: "Pacific/Auckland", units: "metric", firstDayOfWeek: 1, locales: ["en"] },
+  { code: "FR", currency: "EUR", timezone: "Europe/Paris", units: "metric", firstDayOfWeek: 1, locales: ["fr"] },
+  { code: "DE", currency: "EUR", timezone: "Europe/Berlin", units: "metric", firstDayOfWeek: 1, locales: ["de"] },
+  { code: "ES", currency: "EUR", timezone: "Europe/Madrid", units: "metric", firstDayOfWeek: 1, locales: ["es"] },
+  { code: "IT", currency: "EUR", timezone: "Europe/Rome", units: "metric", firstDayOfWeek: 1, locales: ["it"] },
+  { code: "NL", currency: "EUR", timezone: "Europe/Amsterdam", units: "metric", firstDayOfWeek: 1, locales: ["nl"] },
+  { code: "PT", currency: "EUR", timezone: "Europe/Lisbon", units: "metric", firstDayOfWeek: 1, locales: ["pt"] },
+  { code: "SE", currency: "SEK", timezone: "Europe/Stockholm", units: "metric", firstDayOfWeek: 1, locales: ["sv"] },
+  { code: "NO", currency: "NOK", timezone: "Europe/Oslo", units: "metric", firstDayOfWeek: 1, locales: ["nb"] },
+  { code: "DK", currency: "DKK", timezone: "Europe/Copenhagen", units: "metric", firstDayOfWeek: 1, locales: ["da"] },
+  { code: "CH", currency: "CHF", timezone: "Europe/Zurich", units: "metric", firstDayOfWeek: 1, locales: ["de", "fr"] },
+  { code: "MX", currency: "MXN", timezone: "America/Mexico_City", units: "metric", firstDayOfWeek: 0, locales: ["es"] },
+  { code: "BR", currency: "BRL", timezone: "America/Sao_Paulo", units: "metric", firstDayOfWeek: 0, locales: ["pt"] },
+  { code: "JP", currency: "JPY", timezone: "Asia/Tokyo", units: "metric", firstDayOfWeek: 0, locales: ["ja"] },
+  { code: "SG", currency: "SGD", timezone: "Asia/Singapore", units: "metric", firstDayOfWeek: 1, locales: ["en"] },
+  { code: "ZA", currency: "ZAR", timezone: "Africa/Johannesburg", units: "metric", firstDayOfWeek: 1, locales: ["en"] },
+];
+
+export const DEFAULT_COUNTRY = "CA";
+
+/**
+ * Every zone and currency the platform knows, not the handful above.
+ *
+ * The list above exists to *suggest* a default from a country; it must never
+ * be the list a business can choose from. A Canadian photographer is as likely
+ * to be in Vancouver as Toronto, and a select whose options omit the value it
+ * was given silently falls back to its first option — which is how a business
+ * in Vancouver quietly became one in Johannesburg the first time this screen
+ * was opened with real data.
+ */
+export const ALL_TIMEZONES: readonly string[] =
+  Intl.supportedValuesOf("timeZone");
+
+export const ALL_CURRENCIES: readonly string[] =
+  Intl.supportedValuesOf("currency");
+
+/**
+ * The options for a select, guaranteed to contain the value it is showing.
+ * Belt and braces for lists that are curated rather than exhaustive — a
+ * stored value must always be selectable, even if it predates the list.
+ */
+export function withCurrent(
+  options: readonly string[],
+  current: string | undefined,
+): string[] {
+  if (!current || options.includes(current)) return [...options];
+  return [current, ...options];
+}
+
+export function defaultsFor(code: string): CountryDefaults {
+  return (
+    COUNTRY_DEFAULTS.find((c) => c.code === code) ??
+    COUNTRY_DEFAULTS.find((c) => c.code === DEFAULT_COUNTRY)!
+  );
+}
+
+/**
+ * Country names in the reader's language, from the platform rather than a
+ * hardcoded English list — "Deutschland" for a German owner (§4.9).
+ */
+export function countryName(code: string, locale = "en"): string {
+  try {
+    return (
+      new Intl.DisplayNames([locale], { type: "region" }).of(code) ?? code
+    );
+  } catch {
+    return code;
+  }
+}
+
+export function currencyName(code: string, locale = "en"): string {
+  try {
+    return (
+      new Intl.DisplayNames([locale], { type: "currency" }).of(code) ?? code
+    );
+  } catch {
+    return code;
+  }
+}
+
+/**
+ * schema.org business types the owner picks from (§13 step 2). This choice
+ * drives the JSON-LD on every public page, so it is identity rather than
+ * decoration — a Photographer and a HairSalon emit different structured data.
+ *
+ * Values only. What each one is *called* is copy, so it lives in the message
+ * catalogs under `business.type.<value>` and is translated where a locale
+ * exists — the schema.org identifier is the same in every language, and the
+ * word for it is not.
+ */
+export const BUSINESS_TYPES = [
+  "LocalBusiness",
+  "Photographer",
+  "ProfessionalService",
+  "HomeAndConstructionBusiness",
+  "HealthAndBeautyBusiness",
+  "HairSalon",
+  "FoodEstablishment",
+  "Store",
+  "EntertainmentBusiness",
+  "EducationalOrganization",
+] as const;

package/dist/template/src/core/settings/read.ts

@@ -0,0 +1,24 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Request-scoped reads of the business profile.
+//
+// One render pass asks for the business several times over: the layout wants
+// the site name, `generateMetadata` wants it for the title and Open Graph, and
+// the page itself wants the tagline. Those are three components doing their
+// own jobs correctly — none of them should have to know what the others
+// fetched — and three identical queries per request is the price.
+//
+// React's `cache()` is the seam that removes the price without removing the
+// independence: the first caller in a request runs the service, the rest get
+// the same promise, and nothing has to thread a value down through props.
+//
+// It wraps the service rather than replacing it. Permission checks, audit and
+// the transaction are all still the service layer's (§11); this only decides
+// how often a request asks.
+import { cache } from "react";
+import { getBusiness } from "@/core/settings/service";
+
+const ANONYMOUS = { kind: "anonymous" } as const;
+
+/** The business profile, fetched at most once per request. */
+export const currentBusiness = cache(() => getBusiness.call({}, ANONYMOUS));

package/dist/template/src/core/settings/schema.ts

@@ -0,0 +1,81 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Business identity and module toggles (MASTER.md §4.8, §13). One deploy is
+// one business (§2 principle 1), so the profile is a genuine singleton and the
+// database says so — a second row is not "unlikely", it is rejected.
+//
+// These are known fields, so they are columns. jsonb here would be the shadow
+// store §2 principle 12 forbids; it is reserved for the per-module config
+// below, whose shape only that module knows.
+import { sql } from "drizzle-orm";
+import {
+  boolean,
+  check,
+  integer,
+  jsonb,
+  pgTable,
+  text,
+  timestamp,
+} from "drizzle-orm/pg-core";
+import { createdAtColumn, updatedAtColumn } from "@/core/db/columns";
+
+export const businessProfile = pgTable(
+  "business_profile",
+  {
+    /** Always 1. Single-tenant is a constraint here, not a convention. */
+    id: integer("id").primaryKey().default(1),
+    name: text("name").notNull(),
+    tagline: text("tagline"),
+    /**
+     * schema.org type the owner picks in setup (§13 step 2) — Photographer,
+     * HairSalon, ProfessionalService… It drives the JSON-LD every public page
+     * emits, so it is identity, not decoration.
+     */
+    schemaType: text("schema_type").notNull().default("LocalBusiness"),
+    /** ISO-3166-1 alpha-2. Tax follows location, not locale (§4.9). */
+    country: text("country").notNull(),
+    /** BCP-47. Unprefixed in URLs; others are path-prefixed (§4.9). */
+    defaultLocale: text("default_locale").notNull().default("en"),
+    enabledLocales: text("enabled_locales")
+      .array()
+      .notNull()
+      .default(sql`'{"en"}'`),
+    /** ISO-4217. Money is never auto-converted at charge time (§4.9). */
+    baseCurrency: text("base_currency").notNull(),
+    /** IANA zone. Store UTC, display here (§4.9 timezone discipline). */
+    timezone: text("timezone").notNull(),
+    units: text("units", { enum: ["metric", "imperial"] })
+      .notNull()
+      .default("metric"),
+    /** 0 = Sunday, matching Date#getDay, so no translation layer is needed. */
+    firstDayOfWeek: integer("first_day_of_week").notNull().default(1),
+    /** Set once the wizard finishes; /setup locks itself after this (§13). */
+    setupCompletedAt: timestamp("setup_completed_at", { withTimezone: true }),
+    createdAt: createdAtColumn(),
+    updatedAt: updatedAtColumn(),
+  },
+  (t) => [
+    check("business_profile_singleton", sql`${t.id} = 1`),
+    check(
+      "business_profile_country_alpha2",
+      sql`${t.country} ~ '^[A-Z]{2}$'`,
+    ),
+    check(
+      "business_profile_currency_alpha3",
+      sql`${t.baseCurrency} ~ '^[A-Z]{3}$'`,
+    ),
+    check(
+      "business_profile_first_day",
+      sql`${t.firstDayOfWeek} between 0 and 6`,
+    ),
+  ],
+);
+
+export const moduleSettings = pgTable("module_settings", {
+  /** The module's manifest name — one row per module, so it is the key. */
+  module: text("module").primaryKey(),
+  enabled: boolean("enabled").notNull().default(true),
+  /** Validated against the module's settingsSchema (§11) before write. */
+  config: jsonb("config").notNull().default({}),
+  updatedAt: updatedAtColumn(),
+});