Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* PG/file store-backend facade backbone.
*
* PortOS has six near-identical storage dispatchers (pipeline series/issues,
* story builder, universe builder, catalog user-types, writers room) that each
* pick between a PostgreSQL backend (normal installs) and a file/escape-hatch
* backend (MEMORY_BACKEND=file or isTestRunner() — both UNSUPPORTED for
* production). They all reimplemented the same three pieces: the env predicate
* that chooses the backend, the promise-memoized lazy selection, and the PG
* bring-up sequence (health check → ensureSchema → one-time migration → import
* the leaf-I/O `db.js`). This module owns those pieces so no store copies them.
*
* What stays in each store: its own `makeFile` / `makePg` backend factories
* (the file layouts differ genuinely — collectionStore vs settings.json vs a
* bespoke on-disk JSON format) and its public facade surface.
*
* A second family of stores (Creative Director, Music Video, Sprites) dispatches
* to whole backend MODULES rather than built objects, and hand-rolled the same
* selector a third time (#2899). `createRecordStoreBackendSelector` below wraps
* this backbone for that shape.
*/
import { checkHealth, ensureSchema } from './db.js';
import { isTestRunner } from './runtimeEnv.js';
/**
* True when the file/escape-hatch backend should be used instead of PostgreSQL.
* Dev/test only — see the Storage backend policy in AGENTS.md.
*/
export function isFileBackend() {
return process.env.MEMORY_BACKEND === 'file' || isTestRunner();
}
/**
* Bring the PostgreSQL backend up and build it. Fail-fast on a missing DB (the
* boot gate may not have run ensureSchema yet — an early warm or a sync pull can
* call in first), so this is self-sufficient: it health-checks, brings the
* schema up (idempotent), runs the one-time marker-gated file→DB import, imports
* the leaf-I/O db module, and hands it to `makePg`.
*
* @param {object} opts
* @param {string} opts.requirement Error message thrown when the DB is unreachable.
* @param {() => Promise<void>} [opts.migrate] One-time file→DB import (optional).
* @param {() => Promise<object>} opts.loadDb Dynamic `import('./db.js')`.
* @param {(db: object) => object} opts.makePg Build the PG backend from the db module.
*/
export async function resolvePgBackend({ requirement, migrate, loadDb, makePg }) {
const health = await checkHealth();
if (!health.connected) throw new Error(requirement);
await ensureSchema();
if (migrate) await migrate();
const db = await loadDb();
return makePg(db);
}
/**
* Shared PG/file backend selector. Picks the file backend under the dev/test
* escape hatch and the PG backend otherwise, memoizing the SELECTION PROMISE
* (not just the result) so two concurrent first calls — e.g. the boot warm
* racing a sync pull — don't both import the PG module and run the migration
* twice. `makeFile` may be sync or async; `makePg` is async (usually wired to
* `resolvePgBackend`).
*
* @param {object} opts
* @param {() => object|Promise<object>} opts.makeFile Build the file backend.
* @param {() => Promise<object>} opts.makePg Build the PG backend.
* @param {() => boolean} [opts.isFile] Escape-hatch predicate (default `isFileBackend`).
* Overridden only by stores that use a stronger test-mode signal (see
* `createRecordStoreBackendSelector`'s `isTestMode`).
* @returns {{ getBackend: () => Promise<object>, getBackendName: () => (string|null), reset: () => void }}
*/
export function createPgFileFacade({ makeFile, makePg, isFile = isFileBackend }) {
let backend = null;
let selecting = null;
const getBackend = () => {
if (backend) return Promise.resolve(backend);
if (!selecting) {
selecting = Promise.resolve(isFile() ? makeFile() : makePg())
.then((b) => { backend = b; return b; })
.finally(() => { selecting = null; });
}
return selecting;
};
return {
getBackend,
getBackendName: () => backend?.name ?? null,
reset: () => { backend = null; selecting = null; },
};
}
/**
* Memoized backend selector for stores whose backends are whole MODULES
* (`import('./projectsFile.js')` vs `import('./projectsDB.js')`) rather than
* objects built from `db.js` — Creative Director, Music Video, Sprites (#2899),
* plus Artists, Tracks, Albums, Authors (#2909). Each had hand-rolled the
* identical dispatcher, and they had already drifted (differing error text,
* differing test-mode predicate).
*
* Same posture as `createPgFileFacade` (do NOT weaken it): the dev/test escape
* hatch selects the file backend with NO database contact at all; otherwise
* `resolvePgBackend` health-checks, runs the idempotent `ensureSchema()` (a store
* may be called before the boot DB gate, e.g. CD's boot recovery scan), runs the
* optional one-time migration, then loads the PG module.
*
* The default escape hatch is `isFileBackend()`: `MEMORY_BACKEND=file` or
* `isTestRunner()` (`NODE_ENV==='test'` OR `VITEST` is set). A store may pass
* `isTestMode` to replace that test signal; the file escape hatch is still
* OR-ed in. Sprites passes `isTestRunner`, which matches the default. Vitest
* always sets `VITEST`, so a suite that wants Postgres must clear it — setting
* `NODE_ENV` away from `test` is not enough.
*
* @param {object} opts
* @param {string} [opts.label] Store name used in the default unreachable-DB error.
* @param {() => Promise<object>} opts.loadFileBackend Loader for the file backend module.
* @param {() => Promise<object>} opts.loadDbBackend Loader for the PostgreSQL backend module.
* @param {string} [opts.requireDbMessage] Override for the unreachable-DB error message.
* @param {() => boolean} [opts.isTestMode] Test-mode predicate; when omitted the shared
* `isFileBackend()` (`MEMORY_BACKEND=file` OR `isTestRunner()`) is used as-is.
* @param {() => Promise<void>} [opts.onDbReady] One-time migration run after `ensureSchema()`
* and before the DB backend import (CD's legacy JSON → table import).
* @returns {{ selectBackend: () => Promise<object>, getBackendName: () => ('file'|'postgres'|null) }}
*/
export function createRecordStoreBackendSelector({
label,
loadFileBackend,
loadDbBackend,
requireDbMessage,
isTestMode,
onDbReady,
} = {}) {
if (typeof loadFileBackend !== 'function' || typeof loadDbBackend !== 'function') {
throw new Error('createRecordStoreBackendSelector requires loadFileBackend + loadDbBackend loader functions');
}
const requirement = requireDbMessage
|| `${label || 'This store'} requires PostgreSQL — run \`npm run setup:db\` (dev/test only: set MEMORY_BACKEND=file in .env)`;
let backendName = null;
const facade = createPgFileFacade({
isFile: isTestMode
? () => process.env.MEMORY_BACKEND === 'file' || isTestMode()
: isFileBackend,
makeFile: async () => {
const mod = await loadFileBackend();
backendName = 'file';
return mod;
},
makePg: async () => {
const mod = await resolvePgBackend({
requirement,
migrate: onDbReady,
loadDb: loadDbBackend,
makePg: (m) => m,
});
backendName = 'postgres';
return mod;
},
});
return {
selectBackend: facade.getBackend,
/** Name of the active backend, or null before first selection (diagnostics/tests). */
getBackendName: () => backendName,
/**
* Test seam — drop the memoized selection so a suite can re-select. Backs
* the `_reset<X>Backend()` exports the artists/tracks/albums/authors stores
* carry.
*/
reset: () => { facade.reset(); backendName = null; },
};
}