@aopslabs/aops 0.2.0

package/dist/lib/official-catalog.js

@@ -0,0 +1,364 @@
+import { createHash } from 'node:crypto';
+export const OFFICIAL_CATALOG_SCOPE_V1 = Object.freeze({
+    schemaVersion: 1,
+    slug: 'aops-official-catalog',
+    kind: 'agentspace-skill-catalog',
+    owner: 'aops-community-setup',
+    reserved: true,
+});
+export const OFFICIAL_CATALOG_META_KEY_V1 = 'aopsOfficialCatalog';
+export const OFFICIAL_CATALOG_TOOL_IDS_V1 = Object.freeze({
+    inspect: 'agentspace.official-catalog.inspect',
+    reconcile: 'agentspace.official-catalog.reconcile',
+    rollback: 'agentspace.official-catalog.rollback',
+});
+export const OFFICIAL_CATALOG_NO_ACTIVATION_EFFECTS_V1 = Object.freeze([]);
+export class OfficialCatalogError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = 'OfficialCatalogError';
+        this.code = code;
+        this.details = details;
+    }
+}
+function fail(code, message, details) {
+    throw new OfficialCatalogError(code, message, details);
+}
+function nonEmpty(value, label) {
+    if (typeof value !== 'string' || !value.trim())
+        fail('catalog_snapshot_invalid', `${label} must be non-empty.`);
+    return value;
+}
+function compareUtf8(left, right) {
+    return Buffer.compare(Buffer.from(left, 'utf8'), Buffer.from(right, 'utf8'));
+}
+function stableObject(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableObject).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record).sort(compareUtf8).map((key) => `${JSON.stringify(key)}:${stableObject(record[key])}`).join(',')}}`;
+}
+function sha256(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+function sortedMap(input) {
+    return Object.freeze(Object.fromEntries(Object.entries(input).sort(([left], [right]) => compareUtf8(left, right))));
+}
+function assertCurrentVersionMap(value, code, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        fail(code, `${label} must be an object map.`);
+    }
+    for (const [name, recordId] of Object.entries(value)) {
+        if (!name.trim() || (recordId !== null && (typeof recordId !== 'string' || !recordId.trim()))) {
+            fail(code, `${label} contains an invalid name or version record id.`);
+        }
+    }
+}
+export function assertOfficialCatalogSnapshotV1(snapshot) {
+    if (snapshot.schemaVersion !== 1 ||
+        snapshot.scopeSlug !== OFFICIAL_CATALOG_SCOPE_V1.slug ||
+        (snapshot.state !== 'absent' && snapshot.state !== 'ready') ||
+        !Number.isSafeInteger(snapshot.catalogRevision) ||
+        snapshot.catalogRevision < 0 ||
+        !Array.isArray(snapshot.versions)) {
+        fail('catalog_snapshot_invalid', 'Official catalog snapshot does not match schemaVersion 1.');
+    }
+    assertCurrentVersionMap(snapshot.currentVersionMap, 'catalog_snapshot_invalid', 'currentVersionMap');
+    if (snapshot.state === 'absent') {
+        if (snapshot.scopeId !== null ||
+            snapshot.projectId !== null ||
+            snapshot.catalogRevision !== 0 ||
+            Object.keys(snapshot.currentVersionMap).length !== 0 ||
+            snapshot.versions.length !== 0 ||
+            snapshot.lastReceiptId !== null) {
+            fail('catalog_scope_conflict', 'An absent reserved catalog snapshot contains server-owned state.');
+        }
+        return;
+    }
+    nonEmpty(snapshot.scopeId, 'scopeId');
+    nonEmpty(snapshot.projectId, 'projectId');
+    for (const [name, recordId] of Object.entries(snapshot.currentVersionMap)) {
+        nonEmpty(name, 'currentVersionMap.name');
+        if (recordId !== null)
+            nonEmpty(recordId, `currentVersionMap.${name}`);
+    }
+    const recordIds = new Set();
+    const identities = new Set();
+    for (const version of snapshot.versions) {
+        if (version.status !== 'published' ||
+            version.inert !== true ||
+            !/^[a-f0-9]{64}$/.test(version.packageSha256) ||
+            !/^[a-f0-9]{64}$/.test(version.releaseSetSha256)) {
+            fail('catalog_snapshot_invalid', 'Reserved catalog version metadata is incomplete or untrusted.');
+        }
+        for (const [label, value] of Object.entries({
+            recordId: version.recordId,
+            skillId: version.skillId,
+            name: version.name,
+            versionId: version.versionId,
+        }))
+            nonEmpty(value, label);
+        if (recordIds.has(version.recordId))
+            fail('catalog_snapshot_invalid', 'Catalog snapshot repeats a version record id.');
+        const identity = `${version.name}\0${version.versionId}`;
+        if (identities.has(identity))
+            fail('catalog_snapshot_invalid', 'Catalog snapshot repeats a logical package version.');
+        recordIds.add(version.recordId);
+        identities.add(identity);
+    }
+    for (const [name, recordId] of Object.entries(snapshot.currentVersionMap)) {
+        if (recordId === null)
+            continue;
+        const selected = snapshot.versions.find((entry) => entry.recordId === recordId);
+        if (!selected || selected.name !== name) {
+            fail('catalog_scope_conflict', 'Reserved current-version mapping points outside its catalog snapshot.', { name });
+        }
+    }
+}
+function utf8Content(bytes, label) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        fail('catalog_release_invalid', `Official catalog package file is not valid UTF-8: ${label}.`);
+    }
+}
+export function buildOfficialCatalogPackageImports(inputs) {
+    const releaseSetSha256 = inputs[0]?.releaseSetSha256;
+    const identities = new Set();
+    const digests = new Set();
+    const packages = inputs.map((input) => {
+        if (!releaseSetSha256 || input.releaseSetSha256 !== releaseSetSha256 || input.releaseTrustClass !== 'signed-community-release') {
+            fail('catalog_release_invalid', 'Official catalog packages must share one signature-verified Community release set.');
+        }
+        if (input.packageRef.origin !== 'reserved-catalog' || input.manifest.assetKind !== 'skill-package') {
+            fail('catalog_release_invalid', 'Official catalog input is not an inert reserved-catalog package.');
+        }
+        const identity = `${input.manifest.name}\0${input.manifest.versionId}`;
+        if (identities.has(identity) || digests.has(input.manifest.packageSha256)) {
+            fail('catalog_release_invalid', 'Official catalog release repeats a package identity or digest.');
+        }
+        identities.add(identity);
+        digests.add(input.manifest.packageSha256);
+        const rows = new Map(input.manifest.files.map((row) => [row.path, row]));
+        const files = input.transferFiles.map((file) => {
+            const row = rows.get(file.path);
+            if (!row)
+                fail('catalog_release_invalid', 'Verified transfer contains a file outside its manifest.');
+            return Object.freeze({
+                path: file.path,
+                sha256: row.sha256,
+                byteLength: row.byteLength,
+                content: utf8Content(file.bytes, `${input.manifest.name}/${file.path}`),
+            });
+        }).sort((left, right) => compareUtf8(left.path, right.path));
+        return Object.freeze({
+            name: input.manifest.name,
+            version: input.manifest.version,
+            versionId: input.manifest.versionId,
+            packageSha256: input.manifest.packageSha256,
+            manifestSha256: input.manifestSha256,
+            entryFile: input.manifest.entryFile,
+            manifest: input.manifest,
+            files: Object.freeze(files),
+            meta: Object.freeze({
+                [OFFICIAL_CATALOG_META_KEY_V1]: Object.freeze({
+                    schemaVersion: 1,
+                    scopeSlug: OFFICIAL_CATALOG_SCOPE_V1.slug,
+                    source: 'signed-community-release',
+                    releaseSetSha256: input.releaseSetSha256,
+                    manifestSha256: input.manifestSha256,
+                    packageSha256: input.manifest.packageSha256,
+                    inert: true,
+                }),
+            }),
+        });
+    });
+    return Object.freeze(packages.sort((left, right) => compareUtf8(`${left.name}\0${left.versionId}`, `${right.name}\0${right.versionId}`)));
+}
+export function buildOfficialCatalogReconcilePlan(options) {
+    assertOfficialCatalogSnapshotV1(options.snapshot);
+    const releaseSetSha256 = options.packages[0]?.meta.aopsOfficialCatalog.releaseSetSha256;
+    if (!releaseSetSha256 || !/^[a-f0-9]{64}$/.test(releaseSetSha256)) {
+        fail('catalog_release_invalid', 'A non-empty signed official catalog package set is required.');
+    }
+    if (options.packages.some((entry) => entry.meta.aopsOfficialCatalog.releaseSetSha256 !== releaseSetSha256)) {
+        fail('catalog_release_invalid', 'Official catalog reconcile cannot mix release sets.');
+    }
+    const existingByIdentity = new Map(options.snapshot.versions.map((entry) => [`${entry.name}\0${entry.versionId}`, entry]));
+    const desiredPackageVersionMap = {};
+    const actions = [];
+    for (const packageInput of options.packages) {
+        desiredPackageVersionMap[packageInput.name] = packageInput.versionId;
+        const existing = existingByIdentity.get(`${packageInput.name}\0${packageInput.versionId}`);
+        if (existing && (existing.packageSha256 !== packageInput.packageSha256 ||
+            existing.releaseSetSha256 !== releaseSetSha256)) {
+            fail('catalog_package_conflict', 'A reserved catalog version identity already exists with different signed provenance.', {
+                name: packageInput.name,
+                versionId: packageInput.versionId,
+            });
+        }
+        if (!existing) {
+            actions.push(Object.freeze({
+                name: packageInput.name,
+                action: 'append-version',
+                versionId: packageInput.versionId,
+                packageSha256: packageInput.packageSha256,
+                existingRecordId: null,
+            }));
+            continue;
+        }
+        actions.push(Object.freeze({
+            name: packageInput.name,
+            action: options.snapshot.currentVersionMap[packageInput.name] === existing.recordId ? 'unchanged' : 'set-current',
+            versionId: packageInput.versionId,
+            packageSha256: packageInput.packageSha256,
+            existingRecordId: existing.recordId,
+        }));
+    }
+    for (const name of Object.keys(options.snapshot.currentVersionMap).sort(compareUtf8)) {
+        if (Object.prototype.hasOwnProperty.call(desiredPackageVersionMap, name))
+            continue;
+        desiredPackageVersionMap[name] = null;
+        actions.push(Object.freeze({
+            name,
+            action: options.snapshot.currentVersionMap[name] === null ? 'unchanged' : 'clear-current',
+            versionId: null,
+            packageSha256: null,
+            existingRecordId: options.snapshot.currentVersionMap[name] ?? null,
+        }));
+    }
+    actions.sort((left, right) => compareUtf8(`${left.name}\0${left.action}`, `${right.name}\0${right.action}`));
+    const expectedCurrentVersionMap = sortedMap(options.snapshot.currentVersionMap);
+    const desired = sortedMap(desiredPackageVersionMap);
+    const idempotencyKey = options.idempotencyKey?.trim() || `official-catalog-reconcile-v1:${sha256(stableObject({
+        releaseSetSha256,
+        catalogRevision: options.snapshot.catalogRevision,
+        lastReceiptId: options.snapshot.lastReceiptId,
+        desired,
+    }))}`;
+    return Object.freeze({
+        schemaVersion: 1,
+        kind: 'aops-official-catalog-reconcile-plan-v1',
+        scope: OFFICIAL_CATALOG_SCOPE_V1,
+        releaseSetSha256,
+        expectedCatalogRevision: options.snapshot.catalogRevision,
+        expectedPreviousReceiptId: options.snapshot.lastReceiptId,
+        expectedCurrentVersionMap,
+        desiredPackageVersionMap: desired,
+        packages: Object.freeze([...options.packages]),
+        actions: Object.freeze(actions),
+        mutationRequired: actions.some((entry) => entry.action !== 'unchanged'),
+        activationEffects: OFFICIAL_CATALOG_NO_ACTIVATION_EFFECTS_V1,
+        historyDeleteCount: 0,
+        idempotencyKey,
+    });
+}
+export function buildOfficialCatalogRollbackRequest(options) {
+    assertOfficialCatalogSnapshotV1(options.snapshot);
+    const receiptId = nonEmpty(options.receiptId, 'receiptId');
+    const idempotencyKey = options.idempotencyKey?.trim() || `official-catalog-rollback-v1:${sha256(stableObject({
+        receiptId,
+        catalogRevision: options.snapshot.catalogRevision,
+        lastReceiptId: options.snapshot.lastReceiptId,
+    }))}`;
+    return Object.freeze({
+        schemaVersion: 1,
+        kind: 'aops-official-catalog-rollback-request-v1',
+        scope: OFFICIAL_CATALOG_SCOPE_V1,
+        receiptId,
+        expectedCatalogRevision: options.snapshot.catalogRevision,
+        idempotencyKey,
+        deleteHistory: false,
+        activationEffects: OFFICIAL_CATALOG_NO_ACTIVATION_EFFECTS_V1,
+    });
+}
+export function assertOfficialCatalogReceiptV1(receipt, operation) {
+    if (receipt.schemaVersion !== 1 ||
+        receipt.kind !== 'aops-official-catalog-receipt-v1' ||
+        receipt.operation !== operation ||
+        receipt.scopeSlug !== OFFICIAL_CATALOG_SCOPE_V1.slug ||
+        receipt.historyDeleteCount !== 0 ||
+        !Array.isArray(receipt.activationEffects) ||
+        receipt.activationEffects.length !== 0 ||
+        !Number.isSafeInteger(receipt.catalogRevision) ||
+        receipt.catalogRevision < 1 ||
+        !/^[a-f0-9]{64}$/.test(receipt.releaseSetSha256) ||
+        !Array.isArray(receipt.packageSha256) ||
+        receipt.packageSha256.some((digest) => !/^[a-f0-9]{64}$/.test(digest)) ||
+        !Number.isFinite(Date.parse(receipt.createdAt)))
+        fail('catalog_apply_result_invalid', 'Official catalog operation returned an invalid receipt.');
+    for (const [label, value] of Object.entries({
+        receiptId: receipt.receiptId,
+        scopeId: receipt.scopeId,
+        projectId: receipt.projectId,
+    }))
+        nonEmpty(value, label);
+    assertCurrentVersionMap(receipt.priorCurrentVersionMap, 'catalog_apply_result_invalid', 'priorCurrentVersionMap');
+    assertCurrentVersionMap(receipt.currentVersionMap, 'catalog_apply_result_invalid', 'currentVersionMap');
+    if (receipt.previousReceiptId !== null)
+        nonEmpty(receipt.previousReceiptId, 'previousReceiptId');
+    if (new Set(receipt.packageSha256).size !== receipt.packageSha256.length) {
+        fail('catalog_apply_result_invalid', 'Official catalog receipt repeats a package digest.');
+    }
+}
+export async function reconcileOfficialCatalog(options) {
+    if (!options.adapter)
+        fail('catalog_adapter_unavailable', 'Agentspace official-catalog operations are not available in this server build.');
+    const snapshot = await options.adapter.inspect();
+    const plan = buildOfficialCatalogReconcilePlan({
+        snapshot,
+        packages: options.packages,
+        idempotencyKey: options.idempotencyKey,
+    });
+    if (options.mode === 'preview' || !plan.mutationRequired)
+        return plan;
+    const receipt = await options.adapter.reconcile(plan, 'apply');
+    assertOfficialCatalogReceiptV1(receipt, 'reconcile');
+    if (receipt.releaseSetSha256 !== plan.releaseSetSha256) {
+        fail('catalog_apply_result_invalid', 'Official catalog receipt release digest differs from the verified plan.');
+    }
+    if (receipt.catalogRevision !== plan.expectedCatalogRevision + 1 ||
+        receipt.previousReceiptId !== plan.expectedPreviousReceiptId ||
+        stableObject(receipt.priorCurrentVersionMap) !== stableObject(plan.expectedCurrentVersionMap)) {
+        fail('catalog_apply_result_invalid', 'Official catalog receipt does not prove the accepted compare-and-swap baseline.');
+    }
+    const expectedDigests = [...new Set(plan.packages.map((entry) => entry.packageSha256))].sort(compareUtf8);
+    const receiptDigests = [...receipt.packageSha256].sort(compareUtf8);
+    if (stableObject(receiptDigests) !== stableObject(expectedDigests)) {
+        fail('catalog_apply_result_invalid', 'Official catalog receipt package digests differ from the signed reconcile plan.');
+    }
+    if (stableObject(Object.keys(receipt.currentVersionMap).sort(compareUtf8)) !== stableObject(Object.keys(plan.desiredPackageVersionMap).sort(compareUtf8))) {
+        fail('catalog_apply_result_invalid', 'Official catalog receipt current-map keys differ from the reserved reconcile plan.');
+    }
+    return receipt;
+}
+export async function rollbackOfficialCatalog(options) {
+    if (!options.adapter)
+        fail('catalog_adapter_unavailable', 'Agentspace official-catalog operations are not available in this server build.');
+    const snapshot = await options.adapter.inspect();
+    const request = buildOfficialCatalogRollbackRequest({
+        snapshot,
+        receiptId: options.receiptId,
+        idempotencyKey: options.idempotencyKey,
+    });
+    if (options.mode === 'preview') {
+        const preview = await options.adapter.rollback(request, 'preview');
+        if (stableObject(preview) !== stableObject(request)) {
+            fail('catalog_apply_result_invalid', 'Official catalog rollback preview changed the fail-closed local request.');
+        }
+        return preview;
+    }
+    const receipt = await options.adapter.rollback(request, 'apply');
+    assertOfficialCatalogReceiptV1(receipt, 'rollback');
+    if (receipt.catalogRevision !== snapshot.catalogRevision + 1 ||
+        receipt.previousReceiptId !== snapshot.lastReceiptId ||
+        stableObject(receipt.priorCurrentVersionMap) !== stableObject(snapshot.currentVersionMap)) {
+        fail('catalog_apply_result_invalid', 'Official catalog rollback receipt does not prove the accepted compare-and-swap baseline.');
+    }
+    return receipt;
+}

package/dist/lib/server-bootstrap.js

@@ -0,0 +1,240 @@
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { resolveAopsConfigDir } from '@aopslabs/aops-host-registration';
+import { getDefaultAopsSqliteRepoUrl, inferAopsRepoDialect, } from '@aopslabs/aops-runtime-config';
+export const DEFAULT_AUTH_PROVIDER = 'trusted-local';
+export const DEFAULT_LOCAL_PRINCIPAL_ID = '00000000-0000-4000-8000-000000000001';
+export const DEFAULT_LOCAL_PRINCIPAL_FULL_NAME = 'AOPS Local Operator';
+export const DEFAULT_LOCAL_PRINCIPAL_ROLES = 'admin';
+export const DEFAULT_LOCAL_PRINCIPAL_PERMISSIONS = '*';
+export const BOOTSTRAP_BLOCK_START = '# >>> AOPS bootstrap >>>';
+export const BOOTSTRAP_BLOCK_END = '# <<< AOPS bootstrap <<<';
+const MANAGED_KEYS = [
+    'AOPS_AUTH_PROVIDER',
+    'AOPS_REPO_URL',
+    'AOPS_SQLITE_URL',
+    'AOPS_PG_URL',
+    'DOCMAN_REPO_URL',
+    'DOCMAN_SQLITE_URL',
+    'DOCMAN_PG_URL',
+    'AOPS_RUNNER_WEBHOOK_SECRET',
+    'JWT_SECRET',
+    'JWT_ENC_SECRET',
+    'AOPS_ADMIN_KEY',
+    'AOPS_LOCAL_PRINCIPAL_ID',
+    'AOPS_LOCAL_PRINCIPAL_EMAIL',
+    'AOPS_LOCAL_PRINCIPAL_FULL_NAME',
+    'AOPS_LOCAL_PRINCIPAL_ROLES',
+    'AOPS_LOCAL_PRINCIPAL_PERMISSIONS',
+];
+const MANAGED_KEY_SET = new Set(MANAGED_KEYS);
+const FILEMAN_MANAGED_KEYS = [
+    'FILEMAN_REPO_URL',
+    'FILEMAN_SQLITE_URL',
+    'FILEMAN_PG_URL',
+];
+export function getDefaultFilemanSqliteRepoUrl(processEnv = process.env) {
+    return pathToFileURL(path.join(resolveAopsConfigDir(processEnv), 'fileman.aops.sqlite')).href;
+}
+function normalizeNonEmpty(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function stripWrappingQuotes(value) {
+    if (value.length < 2)
+        return value;
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function extractAssignmentKey(line) {
+    const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+    return match?.[1];
+}
+function quoteEnvValue(value) {
+    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value))
+        return value;
+    return JSON.stringify(value);
+}
+export function normalizeAuthProvider(value, fallback = DEFAULT_AUTH_PROVIDER) {
+    const normalized = normalizeNonEmpty(value)?.toLowerCase();
+    if (!normalized)
+        return fallback;
+    if (normalized === 'trusted-local' || normalized === 'trusted_local' || normalized === 'trusted') {
+        return 'trusted-local';
+    }
+    if (normalized === 'authv2-jwt-session' || normalized === 'authv2_jwt_session' ||
+        normalized === 'jwt-session' || normalized === 'jwt_session' ||
+        normalized === 'session' || normalized === 'remote-session') {
+        throw new Error('community_local_auth_provider_retired:use_trusted-local_or_configure_a_remote-session_target');
+    }
+    return fallback;
+}
+export function createRandomSecret(bytes = 24) {
+    return randomBytes(bytes).toString('hex');
+}
+export function parseDotEnvAssignments(content) {
+    const assignments = {};
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const match = rawLine.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
+        if (!match)
+            continue;
+        const [, key, rawValue] = match;
+        assignments[key] = stripWrappingQuotes(String(rawValue).trim());
+    }
+    return assignments;
+}
+function resolveExistingRepoUrl(existing) {
+    return (normalizeNonEmpty(existing.AOPS_REPO_URL) ??
+        normalizeNonEmpty(existing.AOPS_SQLITE_URL) ??
+        normalizeNonEmpty(existing.AOPS_PG_URL));
+}
+export function buildServerBootstrapPreset(params) {
+    const existing = params.existing ?? {};
+    const processEnv = params.processEnv ?? process.env;
+    const authProvider = normalizeAuthProvider(params.authProvider ?? existing.AOPS_AUTH_PROVIDER);
+    const repoUrl = normalizeNonEmpty(params.repoUrl) ??
+        resolveExistingRepoUrl(existing) ??
+        getDefaultAopsSqliteRepoUrl(processEnv);
+    return {
+        authProvider,
+        repoUrl,
+        webhookSecret: normalizeNonEmpty(existing.AOPS_RUNNER_WEBHOOK_SECRET) ?? createRandomSecret(24),
+        localPrincipalId: normalizeNonEmpty(existing.AOPS_LOCAL_PRINCIPAL_ID) ?? DEFAULT_LOCAL_PRINCIPAL_ID,
+        localPrincipalEmail: normalizeNonEmpty(existing.AOPS_LOCAL_PRINCIPAL_EMAIL) ?? '',
+        localPrincipalFullName: normalizeNonEmpty(existing.AOPS_LOCAL_PRINCIPAL_FULL_NAME) ??
+            DEFAULT_LOCAL_PRINCIPAL_FULL_NAME,
+        localPrincipalRoles: normalizeNonEmpty(existing.AOPS_LOCAL_PRINCIPAL_ROLES) ?? DEFAULT_LOCAL_PRINCIPAL_ROLES,
+        localPrincipalPermissions: normalizeNonEmpty(existing.AOPS_LOCAL_PRINCIPAL_PERMISSIONS) ??
+            DEFAULT_LOCAL_PRINCIPAL_PERMISSIONS,
+    };
+}
+export function buildServerBootstrapEnvMap(preset, options = {}) {
+    const repoDialect = inferAopsRepoDialect(preset.repoUrl);
+    const env = {
+        AOPS_REPO_URL: preset.repoUrl,
+        DOCMAN_REPO_URL: preset.repoUrl,
+        AOPS_AUTH_PROVIDER: preset.authProvider,
+        AOPS_RUNNER_WEBHOOK_SECRET: preset.webhookSecret,
+    };
+    if (repoDialect === 'sqlite') {
+        env.AOPS_SQLITE_URL = preset.repoUrl;
+        env.DOCMAN_SQLITE_URL = preset.repoUrl;
+    }
+    else {
+        env.AOPS_PG_URL = preset.repoUrl;
+        env.DOCMAN_PG_URL = preset.repoUrl;
+    }
+    if (options.includeFileman) {
+        const filemanRepoUrl = normalizeNonEmpty(options.filemanRepoUrl) ??
+            getDefaultFilemanSqliteRepoUrl(options.processEnv ?? process.env);
+        env.FILEMAN_REPO_URL = filemanRepoUrl;
+        env.FILEMAN_SQLITE_URL = filemanRepoUrl;
+    }
+    env.AOPS_LOCAL_PRINCIPAL_ID = preset.localPrincipalId;
+    env.AOPS_LOCAL_PRINCIPAL_FULL_NAME = preset.localPrincipalFullName;
+    env.AOPS_LOCAL_PRINCIPAL_ROLES = preset.localPrincipalRoles;
+    env.AOPS_LOCAL_PRINCIPAL_PERMISSIONS = preset.localPrincipalPermissions;
+    if (normalizeNonEmpty(preset.localPrincipalEmail)) {
+        env.AOPS_LOCAL_PRINCIPAL_EMAIL = preset.localPrincipalEmail;
+    }
+    return env;
+}
+export function renderServerBootstrapBlock(env, options) {
+    const authProvider = options?.authProvider ?? DEFAULT_AUTH_PROVIDER;
+    const repoUrl = options?.repoUrl ?? getDefaultAopsSqliteRepoUrl(process.env);
+    const repoDialect = inferAopsRepoDialect(repoUrl);
+    const includeFileman = options?.includeFileman === true ||
+        Boolean(normalizeNonEmpty(env.FILEMAN_REPO_URL) ?? normalizeNonEmpty(env.FILEMAN_SQLITE_URL));
+    const lines = [
+        BOOTSTRAP_BLOCK_START,
+        '# Managed by aops-cli setup server-env',
+        '# Storage target and auth provider live in the host-owned local env boundary.',
+        `# Effective auth provider: ${authProvider}`,
+        `# Effective repository dialect: ${repoDialect}`,
+        `# Effective repository target: ${repoUrl}`,
+        '',
+        '# Canonical storage target',
+        `AOPS_REPO_URL=${quoteEnvValue(env.AOPS_REPO_URL ?? repoUrl)}`,
+        repoDialect === 'sqlite'
+            ? `AOPS_SQLITE_URL=${quoteEnvValue(env.AOPS_SQLITE_URL ?? repoUrl)}`
+            : `AOPS_PG_URL=${quoteEnvValue(env.AOPS_PG_URL ?? repoUrl)}`,
+        `DOCMAN_REPO_URL=${quoteEnvValue(env.DOCMAN_REPO_URL ?? repoUrl)}`,
+        repoDialect === 'sqlite'
+            ? `DOCMAN_SQLITE_URL=${quoteEnvValue(env.DOCMAN_SQLITE_URL ?? repoUrl)}`
+            : `DOCMAN_PG_URL=${quoteEnvValue(env.DOCMAN_PG_URL ?? repoUrl)}`,
+    ];
+    if (includeFileman) {
+        const filemanRepoUrl = normalizeNonEmpty(env.FILEMAN_REPO_URL) ??
+            normalizeNonEmpty(env.FILEMAN_SQLITE_URL) ??
+            getDefaultFilemanSqliteRepoUrl(process.env);
+        lines.push('', '# Fileman plugin-owned storage (explicit opt-in)', '# Fileman remains plugin-owned; this avoids implicit fileman:sqlite:auto resolution.', `FILEMAN_REPO_URL=${quoteEnvValue(filemanRepoUrl)}`, `FILEMAN_SQLITE_URL=${quoteEnvValue(env.FILEMAN_SQLITE_URL ?? filemanRepoUrl)}`);
+    }
+    lines.push('', '# Trusted-local auth and host-owned runtime secrets', `AOPS_AUTH_PROVIDER=${quoteEnvValue(env.AOPS_AUTH_PROVIDER)}`, `AOPS_RUNNER_WEBHOOK_SECRET=${quoteEnvValue(env.AOPS_RUNNER_WEBHOOK_SECRET)}`);
+    lines.push('', '# Trusted-local principal', `AOPS_LOCAL_PRINCIPAL_ID=${quoteEnvValue(env.AOPS_LOCAL_PRINCIPAL_ID)}`, `AOPS_LOCAL_PRINCIPAL_FULL_NAME=${quoteEnvValue(env.AOPS_LOCAL_PRINCIPAL_FULL_NAME)}`, `AOPS_LOCAL_PRINCIPAL_ROLES=${quoteEnvValue(env.AOPS_LOCAL_PRINCIPAL_ROLES)}`, `AOPS_LOCAL_PRINCIPAL_PERMISSIONS=${quoteEnvValue(env.AOPS_LOCAL_PRINCIPAL_PERMISSIONS)}`);
+    if (normalizeNonEmpty(env.AOPS_LOCAL_PRINCIPAL_EMAIL)) {
+        lines.push(`AOPS_LOCAL_PRINCIPAL_EMAIL=${quoteEnvValue(env.AOPS_LOCAL_PRINCIPAL_EMAIL)}`);
+    }
+    lines.push('', BOOTSTRAP_BLOCK_END);
+    return `${lines.join('\n')}\n`;
+}
+function stripManagedAssignments(content, extraManagedKeys = []) {
+    const managedKeys = extraManagedKeys.length > 0
+        ? new Set([...MANAGED_KEY_SET, ...extraManagedKeys])
+        : MANAGED_KEY_SET;
+    const lines = content.split(/\r?\n/);
+    const kept = lines.filter((line) => {
+        const key = extractAssignmentKey(line);
+        return !(key && managedKeys.has(key));
+    });
+    return kept.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+}
+export function upsertServerBootstrapBlock(params) {
+    const block = renderServerBootstrapBlock(params.env, {
+        authProvider: params.authProvider,
+        repoUrl: params.repoUrl,
+        includeFileman: params.includeFileman,
+    }).trimEnd();
+    const existingContent = params.existingContent ?? '';
+    const start = existingContent.indexOf(BOOTSTRAP_BLOCK_START);
+    const end = existingContent.indexOf(BOOTSTRAP_BLOCK_END);
+    if (start >= 0 && end >= start) {
+        const before = existingContent.slice(0, start).trimEnd();
+        const after = existingContent.slice(end + BOOTSTRAP_BLOCK_END.length).trimStart();
+        return [before, block, after].filter(Boolean).join('\n\n').trimEnd() + '\n';
+    }
+    const base = stripManagedAssignments(existingContent, params.includeFileman ? FILEMAN_MANAGED_KEYS : []);
+    return [base, block].filter(Boolean).join('\n\n').trimEnd() + '\n';
+}
+export function validateServerBootstrapEnv(assignments, options = {}) {
+    const processEnv = options.processEnv ?? process.env;
+    const authProvider = normalizeAuthProvider(options.authProvider ?? assignments.AOPS_AUTH_PROVIDER);
+    const repoUrl = normalizeNonEmpty(options.repoUrl) ??
+        resolveExistingRepoUrl(assignments) ??
+        getDefaultAopsSqliteRepoUrl(processEnv);
+    const repoDialect = inferAopsRepoDialect(repoUrl);
+    const errors = [];
+    const warnings = [];
+    if (!normalizeNonEmpty(repoUrl)) {
+        errors.push('AOPS runtime storage target is missing.');
+    }
+    if (!normalizeNonEmpty(assignments.AOPS_RUNNER_WEBHOOK_SECRET)) {
+        warnings.push('AOPS_RUNNER_WEBHOOK_SECRET is missing. Public webhook ingress will stay disabled.');
+    }
+    return {
+        ok: errors.length === 0,
+        authProvider,
+        repoUrl,
+        repoDialect,
+        errors,
+        warnings,
+    };
+}