@softure-ai/core 0.0.0-stage → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SOFTURE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,244 @@
-# Temporary Holding Version
+# @softure-ai/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Status:** wave 0 · implemented in FD-3 (`core-contract`), 0.1.5, prepared for its first release (the owner's tag, `scripts/release/README.md`).
+
+The contract every SOFTURE module stands on. Standard:
+[docs/02-module-standard.md](../../docs/02-module-standard.md). Sources in FIRE_TRACKER: the
+`{ ok, error }` action results, `src/lib/safe-error.ts` and `src/lib/plural.ts`.
+
+## 1. What it provides
+
+The app configuration (`defineSoftureConfig`), the module contract (`defineModule`), `Result`
+with namespaced error codes, an injectable `Clock`, `pl`/`en` messages with partial overrides,
+and `safeError`. `@softure-ai/core/cli` loads the app's config for the modules' command-line tools.
+
+## 2. Installation
+
+```bash
+npm install @softure-ai/core
+```
+
+Node ≥ 22, ESM only. The only runtime dependency is `zod`.
+
+## 3. Configuration
+
+```ts
+interface SoftureConfigInput {
+  database?: { url: string } | null; // required once any module has a dbSchema
+  locale: "en" | "pl";
+  timezone: string;                  // IANA zone, e.g. "Europe/Warsaw"
+  appOrigin: string;                 // http(s) origin without a path
+  modules: SoftureModule[];          // a module is enabled by being listed
+}
+```
+
+```ts
+// softure.config.ts
+import { defineSoftureConfig } from "@softure-ai/core";
+import { registerSoftureConfig } from "@softure-ai/core/next";
+import { notes } from "@softure-ai/notes";
+
+const config = defineSoftureConfig({
+  database: { url: process.env.DATABASE_URL ?? "" },
+  locale: "pl",
+  timezone: "Europe/Warsaw",
+  appOrigin: process.env.APP_ORIGIN ?? "http://localhost:3000",
+  modules: [notes({ limit: 10, routes: { list: "/my-notes" }, messages: { en: { list: { title: "My notes" } } } })],
+});
+
+registerSoftureConfig(config);
+export default config;
+```
+
+`defineSoftureConfig` throws `SoftureConfigError` with every problem listed (`issues`): an
+unknown locale or zone, an origin with a path, a module listed twice, two modules on one database
+schema, a required dependency missing, a dependency outside its version range (also an optional
+one, when listed), a dependency cycle, or a module with a `dbSchema` and no `database`.
+
+A command that never connects loads the config inside `withDatabaseOptional(() => import(...))`:
+there a missing, `null` or empty `database.url` gives `database: null` instead of a refusal, also when
+a module has a `dbSchema`; a real URL is kept and every other check still runs. The flag is scoped to
+that one load, and Node keeps a module's first evaluation, so a process loads the config one way.
+
+`getModule(config, id)` finds an enabled module; `sortModulesByDependencies(modules)` returns the
+migration order (dependencies first, listed order otherwise).
+
+**Defining a module** (in a module package):
+
+```ts
+import { defineModule, resolveMigrationsDir } from "@softure-ai/core";
+import { z } from "zod";
+import { en } from "./messages/en.js";
+import { pl } from "./messages/pl.js";
+
+export const notes = defineModule({
+  manifest: {
+    id: "notes", version: "0.1.0", dependsOn: { auth: "^0.1.0" }, dbSchema: "notes",
+    tables: ["notes"], env: [], switches: ["notes.read_only"], routes: { list: "/notes" },
+    mount: [], privacy: { exports: true, deletes: true },
+  },
+  messages: { en, pl },
+  options: z.object({ limit: z.number().int().positive().default(100) }),
+  migrations: { dir: resolveMigrationsDir(import.meta.url, "../migrations/") },
+  privacy: { exportUserData, deleteUserData },
+  health: checkNotesReady, // optional: (context) => Promise<Result<undefined>>
+  // switchReader: optional, only for the app's switch provider (section 7)
+  // siteUrls: optional, only for the app's site URL provider (section 7)
+});
+```
+
+- `resolveMigrationsDir(import.meta.url, "../migrations/")` gives the folder's `file:` URL. Do not
+  write `new URL("../migrations/", import.meta.url)` in a module: Next.js (Turbopack) treats that
+  literal form as an asset import and fails the app's `next build` on a folder, also from
+  `node_modules` (measured in identity ID-1).
+- The manifest is checked against `moduleManifestSchema` when the package is imported; a
+  `dbSchema` needs `migrations`, and each privacy flag needs its function (and only then).
+- The returned factory takes the module's options plus two reserved keys: `routes` (new paths
+  for known route names) and `messages` (partial copy per locale). It throws
+  `SoftureConfigError` naming the module and every invalid field.
+- **`module.json`** is the JSON projection of the TS manifest, which is the source of truth at
+  runtime. A module's test keeps them equal:
+  `expect(JSON.parse(readFileSync("module.json", "utf8"))).toEqual(toModuleJson(notes))`.
+- Version ranges in `dependsOn`: `x.y.z`, `^x.y.z`, `~x.y.z`, `*`, each optionally ending in `?`
+  (optional dependency). Caret follows npm on `0.x`: `^0.1.0` is `>=0.1.0 <0.2.0`.
+
+## 4. Mounting
+
+`@softure-ai/core/next` holds the config registry for server actions and route handlers shipped
+in module packages, which cannot import the app's `softure.config.ts`:
+
+- `registerSoftureConfig(config)`: call it in `softure.config.ts`, and import that file from
+  `instrumentation.ts` (it runs at server start) and from the root layout (`next build` prerenders
+  static pages without running instrumentation);
+- `getSoftureConfig()`: read it inside package code; it throws when nothing was registered;
+- `clearSoftureConfig()`: for tests.
+
+Confirmed by identity ID-1 (`next-actions-spike`): a server action, a route handler and a server
+component page shipped in a package all read the registered config, in `next dev` and in
+`next build && next start`, installed as a packed copy or linked from the workspace. The rules for
+package-shipped Next code are in docs/02 §8. `createSoftureHandlers` and `softureMiddleware` come
+with the first module that mounts routes.
+
+`@softure-ai/core/cli` is how a module's command-line tool (`softure migrate`, `softure-mail`,
+`softure-blog`) finds the app's config, so the lookup and its messages live once:
+
+- `takeConfigOption(argv)`: takes `--config <file>` or `--config=<file>` out of the arguments;
+- `loadAppConfig({ cwd, configPath, appScript })`: imports the `--config` file, or the first of
+  `DEFAULT_CONFIG_FILES` (`softure.config.{ts,mts,js,mjs}`) in `cwd`; when Node cannot import it, the
+  problem names `appScript.runner` and the `appScript.packageName` README;
+- `findDefaultConfig(cwd)` and `loadConfig(path, appScript, { database })`: the two halves on their own;
+- `database: "optional"` (default `"required"`) on both loaders: for a command that never connects
+  (`softure-blog check`), the import runs inside `withDatabaseOptional`.
+
+Each returns `{ ok: true, … }` or `{ ok: false, problem }`; the tool prefixes the problem with its name.
+Node only: the root entry has no `node:` imports.
+
+## 5. Migrations and tables
+
+None. Core owns no database schema. A module points at its SQL folder with
+`migrations: { dir: resolveMigrationsDir(import.meta.url, "../migrations/") }`; `@softure-ai/db`
+(FD-4) applies the files.
+
+## 6. Environment variables
+
+None. Core reads no environment variables; the app passes values into `defineSoftureConfig`.
+
+## 7. Switches
+
+None of its own. Modules declare theirs in `manifest.switches`, each prefixed with the module id
+(`notes.read_only`); the `feature-switches` module manages them.
+
+Core holds the **switch-reader contract**, so a module can read a switch without importing the
+module that stores them (feature-switches depends on auth, so auth could not import it back):
+
+```ts
+import { readSwitch } from "@softure-ai/core";
+
+const reading = await readSwitch(ctx, "notes.read_only");
+const isReadOnly = reading.kind === "value" ? reading.isEnabled : getNotesOptions(ctx.config).readOnly;
+```
+
+- `readSwitch(ctx, name)` asks the enabled module that passed `switchReader` to `defineModule`
+  and returns `SwitchReading`: `{ kind: "value", isEnabled }`, or `{ kind: "undeclared" }` when no
+  module provides a reader or the app did not define that switch there. On `undeclared` the module
+  uses its own default.
+- A `SwitchReader` is `(context, name) => Promise<SwitchReading>`. It resolves read failures itself
+  (a fail mode) and never throws for an unknown name. `@softure-ai/feature-switches` is the provider.
+- `defineSoftureConfig` refuses two enabled modules that provide a reader; `findSwitchReader(config)`
+  returns the one there is, or `null`.
+- `readSwitch` caches nothing: each call is one read by the provider. Ask once per request.
+
+Core also holds the **site-URL contract**, so a module can declare the absolute URLs of its pages
+(canonical, Open Graph, JSON-LD, feeds) by the app's canonical rule without importing the module that
+owns it (`@softure-ai/seo` is optional for the blog, and a bundler resolves every `import()`):
+
+```ts
+import { getSiteUrls } from "@softure-ai/core";
+
+const urls = getSiteUrls(config);
+urls.getCanonicalUrl("/notes/first"); // a page: the provider's host and trailing-slash rule
+`${urls.origin}/notes/feed.xml`;      // a file: on the site's origin as it is
+```
+
+- `getSiteUrls(config)` asks the enabled module that passed `siteUrls` to `defineModule` (a
+  `SiteUrlProvider`, `(config) => SiteUrls`); `@softure-ai/seo` is the provider. Without one, `origin`
+  is `appOrigin` and `getCanonicalUrl(path)` appends the path to it unchanged.
+- `getCanonicalUrl` takes a path starting with a single `/` and throws for anything else.
+- `defineSoftureConfig` refuses two enabled modules that provide site URLs; `findSiteUrlProvider(config)`
+  returns the one there is, or `null`.
+
+## 8. Appearance
+
+None. Tokens, slots and styles live in `@softure-ai/ui`.
+
+## 9. Copy
+
+- `LOCALES` is `["en", "pl"]`; every module ships both dictionaries complete (`pl.ts` is typed
+  `typeof en`).
+- `mergeMessages(defaults, overrides)` applies partial overrides per locale; unknown keys and a
+  string in place of a group are ignored.
+- `formatMessage("{count} of {total}", { count, total })` fills placeholders; a missing value
+  stays visible as `{name}`.
+- `selectPlural(locale, count, { one, few, many, other })` uses `Intl.PluralRules`.
+- `getMessage(dictionary, "errors.unexpected")` reads a dotted path.
+- Core's own keys (`coreMessages`): `errors.database_failed`, `errors.unexpected`, the copy for
+  the `core.database_failed` and `core.unexpected` codes.
+
+**Errors as values.** `Result<T, E>` is `{ ok: true, value } | { ok: false, error }`, built with
+`ok(value)` / `ok()` and `err("module.code")`. Codes are namespaced by module id
+(`` `${string}.${string}` ``); the UI translates them through messages.
+`safeError(error)` turns a caught error into `core.database_failed` (a Drizzle `Failed query:` or a
+bare SQL statement) or `core.unexpected`, so no SQL or parameter reaches a caller.
+`errorLogLabel(error)` gives a log line with the error class and SQLSTATE only, never the text.
+
+**Time.** Server code receives a `Clock` (`ModuleContext.clock`) instead of calling `new Date()`.
+`systemClock` is the real one; `createTestClock(start)` has `advance(ms)` and `set(date)`.
+A whole test run can also move to another day without code changes: `TEST_TODAY=YYYY-MM-DD` with the
+`@softure-ai/testing/vitest-setup` setup file shifts the global `Date` (and so `systemClock`) to that
+day while time keeps running ([`@softure-ai/testing`](../testing/README.md)).
+
+## 10. Hooks
+
+`ModuleContext` is what every server function of a module receives: `{ db, clock, config }`
+(`db` is typed by `@softure-ai/db`). Request scope (cookies, headers) stays in `next/`.
+
+`health` (optional) is the module's readiness probe, a `HealthCheck`:
+`(context: ModuleContext) => Promise<Result<undefined>>`. `GET /api/health` of `@softure-ai/ops`
+runs it for every enabled module that has one; `ok()` is healthy, an `Err` or a throw is not.
+Keep it to one cheap query.
+
+## 11. GDPR
+
+Core collects nothing. It defines the contributor contract a module implements:
+`exportUserData(context, userId)` returning `Result<unknown>` and
+`deleteUserData(context, userId)` returning `Result<undefined>`, present exactly when the
+manifest's `privacy.exports` / `privacy.deletes` flag is true. The `privacy` module runs them.
+
+## 12. Limitations
+
+- The registry in `next/` is provisional until ID-1.
+- Versions are plain `x.y.z`; pre-release versions and range forms beyond `^`, `~`, exact and `*`
+  are rejected.
+- Route maps mix mounted paths and redirect targets, so two modules may share a path; mount
+  collisions are left to `softure doctor`.
+- No date or number formatting helpers yet; apps use `Intl` with `config.locale` and `config.timezone`.

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+export { DEFAULT_CONFIG_FILES, findDefaultConfig, loadAppConfig, loadConfig, takeConfigOption, type AppScriptHint, type ConfigLoadResult, type ConfigOptionResult, type DatabaseRequirement, type LoadAppConfigOptions, type LoadConfigOptions, } from "./load-config.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC"}

package/dist/cli/index.js

@@ -0,0 +1,4 @@
+// `@softure-ai/core/cli`: the config loading shared by the modules' command-line tools. Node only;
+// the root entry stays free of `node:` imports.
+export { DEFAULT_CONFIG_FILES, findDefaultConfig, loadAppConfig, loadConfig, takeConfigOption, } from "./load-config.js";
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,gDAAgD;AAChD,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,gBAAgB,GAOjB,MAAM,kBAAkB,CAAC"}

package/dist/cli/load-config.d.ts

@@ -0,0 +1,49 @@
+import type { SoftureConfig } from "../config.js";
+/** The file names looked up in the working directory when no `--config` is given, in this order. */
+export declare const DEFAULT_CONFIG_FILES: readonly string[];
+/** The function and package an app script calls when Node cannot import the config file. */
+export interface AppScriptHint {
+    /** e.g. `runMigrateCli`. */
+    readonly runner: string;
+    /** e.g. `@softure-ai/db`, whose README shows the app script. */
+    readonly packageName: string;
+}
+export type ConfigOptionResult = {
+    readonly ok: true;
+    readonly configPath: string | undefined;
+    readonly argv: string[];
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+export type ConfigLoadResult = {
+    readonly ok: true;
+    readonly config: SoftureConfig;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+/**
+ * Whether the command needs the config's database. `"optional"` is for a command that never connects
+ * (`softure-blog check`): a missing or empty URL then loads as `database: null` (see `withDatabaseOptional`).
+ */
+export type DatabaseRequirement = "required" | "optional";
+export interface LoadConfigOptions {
+    /** Default `"required"`. */
+    readonly database?: DatabaseRequirement;
+}
+export interface LoadAppConfigOptions extends LoadConfigOptions {
+    readonly cwd: string;
+    /** The `--config` value, relative to `cwd`; `undefined` looks up `DEFAULT_CONFIG_FILES`. */
+    readonly configPath: string | undefined;
+    readonly appScript: AppScriptHint;
+}
+/** Takes `--config <file>` or `--config=<file>` out of the arguments and keeps the rest in order. */
+export declare function takeConfigOption(argv: readonly string[]): ConfigOptionResult;
+/** The first of `DEFAULT_CONFIG_FILES` that exists in `cwd`, as an absolute path. */
+export declare function findDefaultConfig(cwd: string): string | undefined;
+/** The config the file exports (default or `config`), or why it could not be used. */
+export declare function loadConfig(path: string, appScript: AppScriptHint, options?: LoadConfigOptions): Promise<ConfigLoadResult>;
+/** Loads the `--config` file, or the default one found in `cwd`. */
+export declare function loadAppConfig(options: LoadAppConfigOptions): Promise<ConfigLoadResult>;
+//# sourceMappingURL=load-config.d.ts.map

package/dist/cli/load-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-config.d.ts","sourceRoot":"","sources":["../../src/cli/load-config.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAGlD,oGAAoG;AACpG,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAA2F,CAAC;AAE9I,4FAA4F;AAC5F,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GACvF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD,MAAM,MAAM,gBAAgB,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExI;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,UAAU,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CACzC;AAED,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,4FAA4F;IAC5F,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;CACnC;AAED,qGAAqG;AACrG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB,CAiB5E;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEjE;AAED,sFAAsF;AACtF,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiBnI;AAED,oEAAoE;AACpE,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAS5F"}

package/dist/cli/load-config.js

@@ -0,0 +1,73 @@
+// How a module's command-line tool (`softure migrate`, `softure-mail`, `softure-blog`) finds and loads
+// the app's `softure.config.*`. The file is loaded with a dynamic import, so it must be one Node can
+// run itself: `.js`/`.mjs`, or `.ts` where Node strips types (Node >= 22.18; relative imports then
+// need `.ts` extensions). Anything else uses an app script that passes the config to the command.
+// Every problem is returned without the tool's name; each tool prefixes its own.
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { withDatabaseOptional } from "../database-requirement.js";
+/** The file names looked up in the working directory when no `--config` is given, in this order. */
+export const DEFAULT_CONFIG_FILES = ["softure.config.ts", "softure.config.mts", "softure.config.js", "softure.config.mjs"];
+/** Takes `--config <file>` or `--config=<file>` out of the arguments and keeps the rest in order. */
+export function takeConfigOption(argv) {
+    const rest = [];
+    let configPath;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index] ?? "";
+        if (arg === "--config") {
+            const value = argv[index + 1];
+            if (value === undefined || value.startsWith("--"))
+                return { ok: false, problem: "--config needs a file path" };
+            configPath = value;
+            index += 1;
+        }
+        else if (arg.startsWith("--config=")) {
+            configPath = arg.slice("--config=".length);
+        }
+        else {
+            rest.push(arg);
+        }
+    }
+    return { ok: true, configPath, argv: rest };
+}
+/** The first of `DEFAULT_CONFIG_FILES` that exists in `cwd`, as an absolute path. */
+export function findDefaultConfig(cwd) {
+    return DEFAULT_CONFIG_FILES.map((name) => resolve(cwd, name)).find((path) => existsSync(path));
+}
+/** The config the file exports (default or `config`), or why it could not be used. */
+export async function loadConfig(path, appScript, options = {}) {
+    if (!existsSync(path))
+        return { ok: false, problem: `config file ${path} does not exist` };
+    const importConfig = () => import(pathToFileURL(path).href);
+    let exported;
+    try {
+        exported = await (options.database === "optional" ? withDatabaseOptional(importConfig) : importConfig());
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            problem: `cannot load ${path}: ${reason}. If Node cannot run this file, call ${appScript.runner} from an app script (see the ${appScript.packageName} README).`,
+        };
+    }
+    const config = exported.default ?? exported.config;
+    return isConfigLike(config)
+        ? { ok: true, config }
+        : { ok: false, problem: `${path} must export (default or as "config") the result of defineSoftureConfig` };
+}
+/** Loads the `--config` file, or the default one found in `cwd`. */
+export async function loadAppConfig(options) {
+    const path = options.configPath === undefined ? findDefaultConfig(options.cwd) : resolve(options.cwd, options.configPath);
+    if (path === undefined) {
+        return {
+            ok: false,
+            problem: `no config found; looked for ${DEFAULT_CONFIG_FILES.join(", ")} in ${options.cwd}; pass --config <file>`,
+        };
+    }
+    return loadConfig(path, options.appScript, { database: options.database ?? "required" });
+}
+function isConfigLike(value) {
+    return typeof value === "object" && value !== null && "modules" in value && Array.isArray(value.modules) && "database" in value;
+}
+//# sourceMappingURL=load-config.js.map

package/dist/cli/load-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-config.js","sourceRoot":"","sources":["../../src/cli/load-config.ts"],"names":[],"mappings":"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"}

package/dist/clock.d.ts

@@ -0,0 +1,15 @@
+export interface Clock {
+    /** The current instant. Every call returns a new `Date`, so callers may mutate it. */
+    now(): Date;
+}
+/** A clock a test moves by hand. */
+export interface TestClock extends Clock {
+    /** Moves the clock forward (or back, with a negative value) by `milliseconds`. */
+    advance(milliseconds: number): void;
+    /** Moves the clock to `instant`. */
+    set(instant: Date): void;
+}
+/** The real wall clock. */
+export declare const systemClock: Clock;
+export declare function createTestClock(start: Date): TestClock;
+//# sourceMappingURL=clock.d.ts.map

package/dist/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,KAAK;IACpB,sFAAsF;IACtF,GAAG,IAAI,IAAI,CAAC;CACb;AAED,oCAAoC;AACpC,MAAM,WAAW,SAAU,SAAQ,KAAK;IACtC,kFAAkF;IAClF,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,oCAAoC;IACpC,GAAG,CAAC,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;CAC1B;AAED,2BAA2B;AAC3B,eAAO,MAAM,WAAW,EAAE,KAEzB,CAAC;AAEF,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,GAAG,SAAS,CAYtD"}

package/dist/clock.js

@@ -0,0 +1,26 @@
+// Time is injected, never read from the global `Date` inside module logic, so tests control it
+// (docs/02-module-standard.md §9, FIRE_TRACKER's `now` convention).
+/** The real wall clock. */
+export const systemClock = {
+    now: () => new Date(),
+};
+export function createTestClock(start) {
+    let current = readTime(start);
+    return {
+        now: () => new Date(current),
+        advance: (milliseconds) => {
+            current += milliseconds;
+        },
+        set: (instant) => {
+            current = readTime(instant);
+        },
+    };
+}
+function readTime(instant) {
+    const time = instant.getTime();
+    if (Number.isNaN(time)) {
+        throw new RangeError("createTestClock: invalid start date");
+    }
+    return time;
+}
+//# sourceMappingURL=clock.js.map

package/dist/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,oEAAoE;AAepE,2BAA2B;AAC3B,MAAM,CAAC,MAAM,WAAW,GAAU;IAChC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE;CACtB,CAAC;AAEF,MAAM,UAAU,eAAe,CAAC,KAAW;IACzC,IAAI,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAE9B,OAAO;QACL,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC;QAC5B,OAAO,EAAE,CAAC,YAAY,EAAE,EAAE;YACxB,OAAO,IAAI,YAAY,CAAC;QAC1B,CAAC;QACD,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE;YACf,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,OAAa;IAC7B,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAC/B,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,UAAU,CAAC,qCAAqC,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/config-error.d.ts

@@ -0,0 +1,12 @@
+export declare class SoftureConfigError extends Error {
+    readonly name = "SoftureConfigError";
+    /** One line per problem: `<path>: <what is wrong>`. */
+    readonly issues: readonly string[];
+    constructor(subject: string, issues: readonly string[]);
+}
+/** Formats zod issues as `<path>: <message>` lines, with an optional path prefix. */
+export declare function formatIssues(issues: readonly {
+    readonly path: readonly PropertyKey[];
+    readonly message: string;
+}[], prefix?: string): string[];
+//# sourceMappingURL=config-error.d.ts.map

package/dist/config-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-error.d.ts","sourceRoot":"","sources":["../src/config-error.ts"],"names":[],"mappings":"AAIA,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAkB,IAAI,wBAAwB;IAE9C,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;gBAEvB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE;CAIvD;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,EACtF,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,EAAE,CAKV"}

package/dist/config-error.js

@@ -0,0 +1,20 @@
+// A configuration that cannot work: an invalid module manifest, invalid module options or an
+// invalid app config. It is thrown at startup (docs/02-module-standard.md §7), because the app
+// cannot run with it; every issue is listed at once so one restart shows all of them.
+export class SoftureConfigError extends Error {
+    name = "SoftureConfigError";
+    /** One line per problem: `<path>: <what is wrong>`. */
+    issues;
+    constructor(subject, issues) {
+        super(`Invalid SOFTURE configuration in ${subject}:\n${issues.map((issue) => `- ${issue}`).join("\n")}`);
+        this.issues = issues;
+    }
+}
+/** Formats zod issues as `<path>: <message>` lines, with an optional path prefix. */
+export function formatIssues(issues, prefix) {
+    return issues.map((issue) => {
+        const path = [prefix, ...issue.path.map(String)].filter((part) => part !== undefined && part !== "").join(".");
+        return path === "" ? issue.message : `${path}: ${issue.message}`;
+    });
+}
+//# sourceMappingURL=config-error.js.map

package/dist/config-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-error.js","sourceRoot":"","sources":["../src/config-error.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,+FAA+F;AAC/F,sFAAsF;AAEtF,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IACzB,IAAI,GAAG,oBAAoB,CAAC;IAE9C,uDAAuD;IAC9C,MAAM,CAAoB;IAEnC,YAAY,OAAe,EAAE,MAAyB;QACpD,KAAK,CAAC,oCAAoC,OAAO,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACzG,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,qFAAqF;AACrF,MAAM,UAAU,YAAY,CAC1B,MAAsF,EACtF,MAAe;IAEf,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QAC1B,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/G,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IACnE,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,39 @@
+import { type Locale } from "./i18n.js";
+import type { AnySoftureModule } from "./module.js";
+import { type Result } from "./result.js";
+export interface SoftureConfig {
+    /** `null` when the app has no database; required as soon as a module has a `dbSchema`. */
+    readonly database: {
+        readonly url: string;
+    } | null;
+    readonly locale: Locale;
+    /** IANA time zone used for every date shown or computed per calendar day. */
+    readonly timezone: string;
+    /** Scheme, host and port of the app, without a path: `https://app.example.com`. */
+    readonly appOrigin: string;
+    /** Enabled modules, in the order the app listed them. */
+    readonly modules: readonly AnySoftureModule[];
+}
+/** What the app writes in `softure.config.ts`. */
+export interface SoftureConfigInput {
+    readonly database?: {
+        readonly url: string;
+    } | null;
+    readonly locale: Locale;
+    readonly timezone: string;
+    readonly appOrigin: string;
+    readonly modules: readonly AnySoftureModule[];
+}
+/**
+ * Validates the app configuration and returns it frozen. Throws `SoftureConfigError` listing
+ * every problem: an app with an invalid configuration must not start.
+ */
+export declare function defineSoftureConfig(input: SoftureConfigInput): SoftureConfig;
+/** The enabled module with this id, or `undefined` when the app did not list it. */
+export declare function getModule(config: SoftureConfig, id: string): AnySoftureModule | undefined;
+/**
+ * The modules with every listed dependency before its dependents (the migration order); ties
+ * keep the listed order. Dependencies that are not listed are ignored here.
+ */
+export declare function sortModulesByDependencies(modules: readonly AnySoftureModule[]): Result<AnySoftureModule[], "core.dependency_cycle">;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAKA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAGnD,MAAM,WAAW,aAAa;IAC5B,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC/C;AAED,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC/C;AAeD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,CAkB5E;AAED,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,MAAM,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAEzF;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,SAAS,gBAAgB,EAAE,GACnC,MAAM,CAAC,gBAAgB,EAAE,EAAE,uBAAuB,CAAC,CAGrD"}