@endora-commerce/platform 0.100.0

package/dist/lifecycle/services/orchestrator.d.ts

@@ -0,0 +1,235 @@
+import type { EntityManager, MikroORM } from '@mikro-orm/postgresql';
+import type { IMigrator } from '@mikro-orm/core';
+import type { Redis } from 'ioredis';
+import type { ModuleListItem } from '@endora-commerce/contracts';
+import type { AuditPort } from '../../kernel/ports/audit.js';
+import type { LoadedManifestRegistry } from './manifest-loader.js';
+import type { MigrationOwnership } from './migration-ownership.js';
+export interface OrchestratorDeps {
+    orm: MikroORM;
+    redis: Redis;
+    em: () => EntityManager;
+    auditLog: AuditPort;
+    /**
+     * The loaded manifest registry — built once at boot or per CLI run.
+     *
+     * It carries the **lifecycle participants** as well as the manifests (feature
+     * 080, T036a / D-159): the two modules that keep a projection of the manifest
+     * set — `_i18n`'s `translation_bundles`, `admin_actions`' `module_actions` —
+     * declare a `lifecycleParticipant` in their `manifest.ts` and the orchestrator
+     * collects them from here. They used to arrive as two optional injected
+     * services, which only a composition root could supply, so an install from a
+     * terminal reconciled neither while the same install from `/platform/modules`
+     * reconciled both.
+     */
+    registry: LoadedManifestRegistry;
+    /**
+     * Who owns which migration — the input `uninstall --hard` reverts by.
+     *
+     * **Injected, and a design decision rather than an `await`** (feature 080,
+     * T033 / D-155.3(c)). This used to be a static `MIGRATION_REGISTRY` import,
+     * justified in its own comment by "the orchestrator must never pull in the
+     * ORM config" — which is right, and is why the merged value arrives as a
+     * value rather than as an `import` of anything async. The merge itself
+     * belongs to whoever composed the platform, because only a composition root
+     * knows which packages this instance installed; `composition.ts` passes
+     * `(await configuredMigrations()).ownership`.
+     *
+     * Omitting it **refuses** every hard uninstall, naming this field. It used to
+     * default to the committed core registry (`coreMigrationOwnership()`), which
+     * is a reach out of the platform into `backend/src/db` — the last thing
+     * standing between this file and the host package (D-160.11) — and the
+     * default was never the interesting half of that decision. The five `module:*`
+     * CLI scripts, which are the callers it existed for, now pass
+     * `coreMigrationOwnership()` themselves and say why in place: a platform
+     * command must not compose (D-157.2), so it answers for core modules and for
+     * nothing else, and a hard uninstall of a package module is refused from the
+     * terminal rather than reverting core's rows and leaving the package's
+     * behind. The refusal is the same one either way; what changed is that the
+     * host chooses it.
+     */
+    migrationOwnership?: MigrationOwnership;
+    /**
+     * How a migrator is obtained. Defaults to the ORM's own accessor; tests
+     * inject a stub here so a revert can be observed without touching schema.
+     */
+    migratorFor?: (orm: MikroORM) => Promise<IMigrator>;
+    /** Optional logger (Fastify request-logger compatible). Defaults to console. */
+    log?: {
+        info(msg: string): void;
+        warn(msg: string): void;
+        error(msg: string): void;
+    };
+}
+export interface InstallResult {
+    moduleId: string;
+    version: string;
+    state: 'installed' | 'already-installed';
+    appliedMigrations: string[];
+    settings: {
+        addedGroups: number;
+        addedSettings: number;
+        updatedGroups: number;
+        updatedSettings: number;
+    };
+    hookDurationMs: number;
+    totalDurationMs: number;
+}
+export interface UninstallResult {
+    moduleId: string;
+    hard: boolean;
+    state: 'uninstalled' | 'already-uninstalled';
+    removedSettings: number;
+    removedGroups: number;
+    revertedMigrations: string[];
+}
+export interface EnableResult {
+    moduleId: string;
+    state: 'installed' | 'already-enabled';
+}
+export interface DisableResult {
+    moduleId: string;
+    state: 'disabled' | 'already-disabled';
+    cascade: boolean;
+    cascaded: string[];
+}
+export declare class LifecycleError extends Error {
+    readonly kind: 'unknown-module' | 'missing-deps' | 'dependents-block' | 'wrong-state' | 'install-failed' | 'uninstall-failed' | 'manifest-cycle' | 'lock-busy' | 'non-deactivatable';
+    readonly details: Record<string, unknown>;
+    constructor(kind: 'unknown-module' | 'missing-deps' | 'dependents-block' | 'wrong-state' | 'install-failed' | 'uninstall-failed' | 'manifest-cycle' | 'lock-busy' | 'non-deactivatable', message: string, details?: Record<string, unknown>);
+}
+export declare class ModuleLifecycleOrchestrator {
+    private readonly deps;
+    private readonly log;
+    constructor(deps: OrchestratorDeps);
+    install(moduleId: string): Promise<InstallResult>;
+    uninstall(moduleId: string, opts?: {
+        hard: boolean;
+    }): Promise<UninstallResult>;
+    enable(moduleId: string): Promise<EnableResult>;
+    disable(moduleId: string, opts?: {
+        cascade: boolean;
+    }): Promise<DisableResult>;
+    /**
+     * The platform axis honours `nonDeactivatable` — D-36a item 3, issue #37.
+     *
+     * Until this existed nothing on this axis read the field for any module, so
+     * `module:disable auth` proceeded and the declaration was a comment that
+     * looked like a guard.
+     *
+     * It guards **every platform-axis withdrawal**: `disable` (the target and
+     * every member of a cascade) and, since D-69 / issue #145, `uninstall` on the
+     * soft and hard path alike. Uninstall is disable plus the settings sweep plus
+     * the schema revert, so the same declaration has to reach it.
+     *
+     * There is deliberately **no `--force`**. `uninstall --hard --force` guards
+     * data loss, a consequence an operator can weigh at the prompt; this guards
+     * a deployment that can no longer authenticate the operator who would undo
+     * it, which they cannot. If the declaration is wrong for a module, the fix is
+     * the manifest, which is reviewed. The operator axis already refuses the same
+     * flip (`activation.commands.ts`), so both axes agree.
+     *
+     * It reads the **manifest**, so a registry row with no manifest — an orphan —
+     * is not covered, deliberately: cleaning those up is the one job `uninstall`
+     * has that nothing else does. `test/unit/_lifecycle/orchestrator.test.ts`
+     * pins that carve-out.
+     */
+    /**
+     * Refuse an install whose arrival closes a dependency cycle, naming every
+     * member (feature 081, FR-012).
+     *
+     * A cycle is not thrown by `orderMigrations`: the manifest graph is the whole
+     * cross-module migration order now, and a manifest can arrive from an
+     * installed package, so refusing there would let one stranger's declaration
+     * stop a shop's own schema from migrating. It comes back as a diagnostic with
+     * three readers instead, and this is the third — the moment the loop would be
+     * *created* is the one moment where refusing costs nothing, because nothing
+     * downstream of it exists yet.
+     *
+     * The graph is the **installed** set plus the arriving module, and only a
+     * component holding the arriving module is refused: a loop between two other
+     * modules is somebody else's problem, and blocking every later install on it
+     * would reproduce the platform-wide stall the no-throw rule exists to
+     * prevent. It reuses `moduleDependencyCycles` rather than
+     * `ModuleDepGraph.hasCycle` — one walk, so the install refusal and the
+     * migration order cannot disagree about what a cycle is, and the operator
+     * reads the same member list in both. The walk is `dep-graph.ts`'s since
+     * D-160.11; `src/db/migration-order.ts` reads the same function and adds its
+     * own wording.
+     */
+    private assertInstallClosesNoCycle;
+    private assertDeactivatable;
+    status(): Promise<ModuleListItem[]>;
+    private acquireLock;
+    private upsertRegistration;
+    /** Set of moduleIds whose state is 'installed' OR 'disabled' (i.e. present, not removed). */
+    private installedSet;
+    /**
+     * Set of moduleIds that are currently ENABLED (state='installed'). Distinct
+     * from {@link installedSet}, which also counts disabled modules as present.
+     * Enabling a module requires every dependency to be enabled — a merely
+     * present-but-disabled dependency must NOT satisfy the check.
+     */
+    private enabledSet;
+    private installedDependentsOf;
+    /**
+     * Direct dependents over **both** kinds of edge — feature 073, FR-008.
+     *
+     * `registry.graph` is built from `manifest.dependencies` alone because it has
+     * to be a DAG: it computes the install order. That leaves out the handful of
+     * real port edges the manifests withhold for exactly that reason, and reading
+     * only the DAG here is what let the two presence axes disagree — the operator
+     * axis refuses to switch `price_lists` off under `catalog`, so this one must
+     * too, or the same platform answers the same question two ways depending on
+     * which door the operator used.
+     */
+    private gatingDependentsOf;
+    /** The modules that acknowledge a withheld port edge onto `moduleId`. */
+    private acknowledgedDependentsOf;
+    private migrator;
+    /**
+     * Revert the migrations a module owns, newest first.
+     *
+     * Ownership comes from an injected {@link MigrationOwnership} — a data-only
+     * value, because the orchestrator must never pull in the ORM config — and the
+     * migration name is always `cls.name`, which is exactly what
+     * `mikro_orm_migrations.name` stores. Ordering is ascending class name, which
+     * for a single module is the resolved execution order: `orderMigrations`
+     * emits a module's migrations contiguously and in ascending timestamp order,
+     * and the timestamp is the head of the name
+     * (specs/081-per-module-migration-order/contracts/ordering-algorithm.md,
+     * invariants J2 and J3).
+     *
+     * ## The empty case is two different answers, and only one of them is fine
+     *
+     * This used to warn and return `[]` whenever the filter came back empty, so
+     * an installed extension package — whose migrations reach the order at
+     * runtime and never reach the committed core registry (D-119/D-155) — **hard
+     * uninstalled to a warning and left its table in the database**. That is data
+     * left behind by an operation the operator believes removed it, on precisely
+     * the population the mechanism exists for (D-155.3(c)).
+     *
+     * So the two are separated at the seam that knows the difference:
+     * `migrationNamesFor` answers `[]` for *"this module owns no migration"* —
+     * ordinary, and 39 core modules are in it — and `null` for *"the registry I
+     * was handed cannot answer for this module"*. The first is logged; the second
+     * throws, because reverting nothing and reporting success is the one outcome
+     * a hard uninstall may not have.
+     *
+     * A failing revert still stops the loop rather than widening the gap.
+     */
+    /**
+     * The lifecycle participants this operation must run — or a refusal.
+     *
+     * The same two-answers distinction {@link revertMigrationsFor} makes, on the
+     * other half of the same operation. `[]` is *"I enumerated the modules and
+     * none keeps a projection of the manifest set"* and is an ordinary answer a
+     * fixture registry gives; `null` is *"I cannot enumerate them"*, and an
+     * install performed on that answer reconciles nothing and reports success —
+     * which is precisely the shape this task closed on the CLI side, so it is not
+     * re-introduced here as a default.
+     */
+    private participantsOrRefuse;
+    private revertMigrationsFor;
+}
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/lifecycle/services/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../../src/lifecycle/services/orchestrator.ts"],"names":[],"mappings":"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"}