@aopslabs/aops 0.2.0

package/dist/lib/community-repo-discovery.js

@@ -0,0 +1,252 @@
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { TextDecoder } from 'node:util';
+const RELEASE_DIRECTORY = 'release';
+const RELEASE_MANIFEST = 'release.json';
+const MAX_RELEASE_MANIFEST_BYTES = 1024 * 1024;
+const MAX_RELEASE_VERSION_LENGTH = 256;
+const PUBLIC_SOURCE_REPOSITORY = 'git+https://github.com/eeemzs/aops-community';
+const RELEASE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?$/;
+const UTF8 = new TextDecoder('utf-8', { fatal: true });
+function fail(code, detail) {
+    throw new Error(detail ? `${code}:${detail}` : code);
+}
+function isCanonicalReleaseVersion(value) {
+    if (typeof value !== 'string' || value.length > MAX_RELEASE_VERSION_LENGTH)
+        return false;
+    const match = value.match(RELEASE_VERSION);
+    if (!match)
+        return false;
+    for (const component of match.slice(1, 4)) {
+        if (!Number.isSafeInteger(Number(component)))
+            return false;
+    }
+    for (const identifier of String(match[4] ?? '').split('.')) {
+        if (/^\d+$/.test(identifier) && !Number.isSafeInteger(Number(identifier)))
+            return false;
+    }
+    return true;
+}
+function lstatOrFail(candidate, code) {
+    try {
+        return lstatSync(candidate);
+    }
+    catch {
+        return fail(code, candidate);
+    }
+}
+function canonicalPath(candidate, code) {
+    try {
+        return realpathSync.native(candidate);
+    }
+    catch {
+        return fail(code, candidate);
+    }
+}
+function lstatBigIntOrFail(candidate, code) {
+    try {
+        return lstatSync(candidate, { bigint: true });
+    }
+    catch {
+        return fail(code, candidate);
+    }
+}
+function sameEntryIdentity(left, right) {
+    return left.dev === right.dev
+        && left.ino === right.ino
+        && left.mode === right.mode
+        && left.size === right.size
+        && left.mtimeNs === right.mtimeNs;
+}
+function entrySnapshot(realPath, stat) {
+    return Object.freeze({
+        realPath,
+        device: stat.dev.toString(),
+        inode: stat.ino.toString(),
+        mode: stat.mode.toString(),
+        size: stat.size.toString(),
+        modifiedNanoseconds: stat.mtimeNs.toString(),
+    });
+}
+function captureEntry(lexicalPath, expectedKind, missingCode, kindCode = expectedKind === 'directory' ? 'community_repo_not_directory' : 'community_repo_marker_not_file') {
+    const before = lstatBigIntOrFail(lexicalPath, missingCode);
+    if (before.isSymbolicLink())
+        fail('community_repo_reparse_refused', lexicalPath);
+    if (expectedKind === 'directory' ? !before.isDirectory() : !before.isFile()) {
+        fail(kindCode, lexicalPath);
+    }
+    const resolved = canonicalPath(lexicalPath, 'community_repo_realpath_failed');
+    const after = lstatBigIntOrFail(lexicalPath, 'community_repo_snapshot_changed');
+    const physical = lstatBigIntOrFail(resolved, 'community_repo_snapshot_changed');
+    if (!sameEntryIdentity(before, after) || !sameEntryIdentity(after, physical)) {
+        fail('community_repo_snapshot_changed', lexicalPath);
+    }
+    return entrySnapshot(resolved, after);
+}
+function parseReleaseIdentity(content) {
+    if (content.byteLength === 0 || content.byteLength > MAX_RELEASE_MANIFEST_BYTES) {
+        fail('community_repo_marker_size_invalid');
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(UTF8.decode(content));
+    }
+    catch {
+        fail('community_repo_marker_json_invalid');
+    }
+    if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+        fail('community_repo_marker_identity_invalid');
+    }
+    const candidate = manifest;
+    if (candidate.schemaVersion !== 1
+        || !isCanonicalReleaseVersion(candidate.releaseVersion)
+        || candidate.source?.repository !== PUBLIC_SOURCE_REPOSITORY)
+        fail('community_repo_marker_identity_invalid');
+    return Object.freeze({
+        schemaVersion: 1,
+        releaseVersion: candidate.releaseVersion,
+        sourceRepository: PUBLIC_SOURCE_REPOSITORY,
+    });
+}
+function assertManifestSnapshotSize(snapshot) {
+    let size;
+    try {
+        size = BigInt(snapshot.size);
+    }
+    catch {
+        return fail('community_repo_marker_size_invalid');
+    }
+    if (size <= 0n || size > BigInt(MAX_RELEASE_MANIFEST_BYTES)) {
+        fail('community_repo_marker_size_invalid');
+    }
+}
+function sameSnapshot(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function pathIdentity(candidate) {
+    const normalized = path.normalize(candidate);
+    return process.platform === 'win32' ? normalized.toLocaleLowerCase('en-US') : normalized;
+}
+function pathsEqual(left, right) {
+    return pathIdentity(left) === pathIdentity(right);
+}
+function isConfined(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+function validateRepoRoot(candidate, source) {
+    const lexicalRoot = path.resolve(candidate);
+    const lexicalReleaseDir = path.join(lexicalRoot, RELEASE_DIRECTORY);
+    const lexicalManifestPath = path.join(lexicalReleaseDir, RELEASE_MANIFEST);
+    const rootSnapshot = captureEntry(lexicalRoot, 'directory', 'community_repo_missing');
+    const releaseSnapshot = captureEntry(lexicalReleaseDir, 'directory', 'community_repo_marker_missing', 'community_repo_release_not_directory');
+    const manifestBeforeRead = captureEntry(lexicalManifestPath, 'file', 'community_repo_marker_missing');
+    const repoRoot = rootSnapshot.realPath;
+    const releaseDir = releaseSnapshot.realPath;
+    const manifestPath = manifestBeforeRead.realPath;
+    const expectedReleaseDir = path.join(repoRoot, RELEASE_DIRECTORY);
+    const expectedManifestPath = path.join(expectedReleaseDir, RELEASE_MANIFEST);
+    if (!pathsEqual(lexicalRoot, repoRoot) ||
+        !pathsEqual(releaseDir, expectedReleaseDir) ||
+        !pathsEqual(manifestPath, expectedManifestPath) ||
+        !isConfined(repoRoot, releaseDir) ||
+        !isConfined(releaseDir, manifestPath)) {
+        fail('community_repo_marker_escape', lexicalManifestPath);
+    }
+    assertManifestSnapshotSize(manifestBeforeRead);
+    const manifestBytes = readFileSync(manifestPath);
+    const manifestAfterRead = captureEntry(lexicalManifestPath, 'file', 'community_repo_marker_missing');
+    if (!sameSnapshot(manifestBeforeRead, manifestAfterRead)) {
+        fail('community_repo_snapshot_changed', lexicalManifestPath);
+    }
+    const releaseIdentity = parseReleaseIdentity(manifestBytes);
+    return {
+        repoRoot,
+        releaseDir,
+        manifestPath,
+        source,
+        verification: 'candidate-requires-signed-release-verification',
+        releaseIdentity,
+        snapshot: Object.freeze({
+            schemaVersion: 1,
+            root: rootSnapshot,
+            release: releaseSnapshot,
+            manifest: manifestAfterRead,
+            manifestByteLength: manifestBytes.byteLength,
+            manifestSha256: `sha256:${createHash('sha256').update(manifestBytes).digest('hex')}`,
+        }),
+    };
+}
+function markerCanBeInspected(candidateRoot) {
+    try {
+        lstatSync(path.join(candidateRoot, RELEASE_DIRECTORY, RELEASE_MANIFEST));
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return false;
+        return fail('community_repo_marker_inspection_failed', path.join(candidateRoot, RELEASE_DIRECTORY, RELEASE_MANIFEST));
+    }
+}
+function resolveDiscoveryStart(cwd) {
+    const lexicalCwd = path.resolve(cwd);
+    const cwdStat = lstatOrFail(lexicalCwd, 'community_repo_cwd_missing');
+    if (!cwdStat.isDirectory())
+        fail('community_repo_cwd_not_directory', lexicalCwd);
+    return canonicalPath(lexicalCwd, 'community_repo_cwd_realpath_failed');
+}
+function discoverCommunityRepo(cwd) {
+    let cursor = resolveDiscoveryStart(cwd);
+    const matches = new Map();
+    while (true) {
+        if (markerCanBeInspected(cursor)) {
+            const match = validateRepoRoot(cursor, 'discovered');
+            matches.set(pathIdentity(match.repoRoot), match);
+        }
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    if (matches.size === 0)
+        fail('community_repo_not_found', cwd);
+    if (matches.size > 1) {
+        fail('community_repo_ambiguous', [...matches.values()].map((match) => match.repoRoot).join(','));
+    }
+    return matches.values().next().value;
+}
+export function resolveCommunityRepo(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    if (options.repo !== undefined) {
+        if (typeof options.repo !== 'string' || options.repo.trim() === '')
+            fail('community_repo_explicit_invalid');
+        const explicitCandidate = path.isAbsolute(options.repo) ? options.repo : path.resolve(cwd, options.repo);
+        return validateRepoRoot(explicitCandidate, 'explicit');
+    }
+    return discoverCommunityRepo(cwd);
+}
+export function assertCommunityRepoCandidateCurrent(resolution) {
+    if (!resolution
+        || resolution.verification !== 'candidate-requires-signed-release-verification'
+        || resolution.snapshot?.schemaVersion !== 1)
+        fail('community_repo_candidate_invalid');
+    const currentRoot = captureEntry(resolution.repoRoot, 'directory', 'community_repo_snapshot_changed');
+    const currentRelease = captureEntry(resolution.releaseDir, 'directory', 'community_repo_snapshot_changed', 'community_repo_snapshot_changed');
+    const currentManifestBeforeRead = captureEntry(resolution.manifestPath, 'file', 'community_repo_snapshot_changed', 'community_repo_snapshot_changed');
+    assertManifestSnapshotSize(currentManifestBeforeRead);
+    const manifestBytes = readFileSync(resolution.manifestPath);
+    const currentManifestAfterRead = captureEntry(resolution.manifestPath, 'file', 'community_repo_snapshot_changed', 'community_repo_snapshot_changed');
+    const manifestSha256 = `sha256:${createHash('sha256').update(manifestBytes).digest('hex')}`;
+    const releaseIdentity = parseReleaseIdentity(manifestBytes);
+    if (!sameSnapshot(resolution.snapshot.root, currentRoot)
+        || !sameSnapshot(resolution.snapshot.release, currentRelease)
+        || !sameSnapshot(resolution.snapshot.manifest, currentManifestBeforeRead)
+        || !sameSnapshot(currentManifestBeforeRead, currentManifestAfterRead)
+        || manifestBytes.byteLength !== resolution.snapshot.manifestByteLength
+        || manifestSha256 !== resolution.snapshot.manifestSha256
+        || JSON.stringify(releaseIdentity) !== JSON.stringify(resolution.releaseIdentity))
+        fail('community_repo_snapshot_changed');
+    return resolution;
+}

package/dist/lib/community-setup-server-env.js

@@ -0,0 +1,203 @@
+import { statSync } from 'node:fs';
+import { banner, logInfo, logSuccess } from '@aopslabs/xf-cli-ui';
+import { readAopsServerEnvFileContent, writeAopsServerEnvFileContent, } from '@aopslabs/aops-runtime-config';
+import { promptPassword } from '../utils/prompts.js';
+import { buildServerBootstrapEnvMap, buildServerBootstrapPreset, parseDotEnvAssignments, upsertServerBootstrapBlock, validateServerBootstrapEnv, } from './server-bootstrap.js';
+import { ExternalPostgresProbeError, probeExternalPostgresConnection, } from './setup-external-postgres.js';
+const MAX_POSTGRES_URL_BYTES = 4_096;
+function normalizeNonEmpty(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    return normalized || undefined;
+}
+function resolveServerEnvAuthProvider(requested, existing) {
+    const explicit = normalizeNonEmpty(requested);
+    const configured = explicit ?? normalizeNonEmpty(existing.AOPS_AUTH_PROVIDER);
+    if (configured) {
+        if (configured === 'trusted-local')
+            return configured;
+        if (configured === 'authv2-jwt-session' || configured === 'remote-session') {
+            throw new Error('setup_server_env_local_auth_retired:rerun_with_--auth_trusted-local_then_use_a_remote-session_target');
+        }
+        throw new Error('setup_server_env_auth_provider_invalid:use_trusted-local');
+    }
+    return 'trusted-local';
+}
+export function resolvePromptedPostgresUrl(promptedValue, savedValue) {
+    return normalizeNonEmpty(promptedValue) ?? savedValue;
+}
+function validatePostgresUrl(value) {
+    if (/\0|\r|\n/.test(value) || Buffer.byteLength(value, 'utf8') > MAX_POSTGRES_URL_BYTES) {
+        throw new Error('setup_server_env_postgres_url_invalid');
+    }
+    try {
+        const parsed = new URL(value);
+        if (!['postgres:', 'postgresql:'].includes(parsed.protocol) || !parsed.hostname || !parsed.pathname) {
+            throw new Error('invalid');
+        }
+    }
+    catch {
+        throw new Error('setup_server_env_postgres_url_invalid');
+    }
+    return value;
+}
+function connectionTestFailure(tlsPolicy, error) {
+    const safe = error instanceof ExternalPostgresProbeError
+        ? error
+        : error instanceof Error && error.message.startsWith('setup_server_env_postgres_url_')
+            ? new ExternalPostgresProbeError(error.message, 'database')
+            : new ExternalPostgresProbeError('setup_external_postgres_connection_failed', 'unknown');
+    return Object.freeze({
+        schemaVersion: 1,
+        mutationFree: true,
+        ok: false,
+        action: 'setup.server-env.test-connection',
+        status: 'failed',
+        tlsPolicy,
+        category: safe.category,
+        code: safe.message,
+    });
+}
+export async function runCommunitySetupServerEnvConnectionTest(options = {}, dependencies = {}) {
+    const tlsPolicy = options.postgresTls ?? 'require';
+    const environmentUrl = normalizeNonEmpty(process.env.AOPS_PG_URL)
+        ?? normalizeNonEmpty(process.env.AOPS_REPO_URL);
+    const candidate = normalizeNonEmpty(options.repoUrl) ?? environmentUrl;
+    let result;
+    try {
+        let probeOptions;
+        if (candidate) {
+            probeOptions = {
+                repoUrl: validatePostgresUrl(candidate),
+                tlsPolicy,
+                timeoutMs: options.timeoutMs,
+            };
+        }
+        else {
+            const snapshot = readAopsServerEnvFileContent(process.env, options.envPath);
+            const existing = parseDotEnvAssignments(snapshot.content);
+            const savedUrl = normalizeNonEmpty(existing.AOPS_PG_URL);
+            const legacySavedUrl = normalizeNonEmpty(existing.AOPS_REPO_URL);
+            if (savedUrl) {
+                validatePostgresUrl(savedUrl);
+                probeOptions = {
+                    configRef: snapshot.path,
+                    tlsPolicy,
+                    timeoutMs: options.timeoutMs,
+                };
+            }
+            else if (legacySavedUrl) {
+                probeOptions = {
+                    repoUrl: validatePostgresUrl(legacySavedUrl),
+                    tlsPolicy,
+                    timeoutMs: options.timeoutMs,
+                };
+            }
+            else {
+                throw new ExternalPostgresProbeError('setup_server_env_postgres_url_required:configure_or_use_AOPS_PG_URL', 'database');
+            }
+        }
+        const probe = await (dependencies.probe ?? probeExternalPostgresConnection)(probeOptions);
+        result = Object.freeze({
+            schemaVersion: 1,
+            mutationFree: true,
+            ok: true,
+            action: 'setup.server-env.test-connection',
+            status: 'ready',
+            tlsPolicy: probe.tlsPolicy,
+            transport: probe.transport,
+            serverMajor: probe.serverMajor,
+        });
+    }
+    catch (error) {
+        result = connectionTestFailure(tlsPolicy, error);
+    }
+    if (options.json)
+        console.log(JSON.stringify(result, null, 2));
+    else if (!options.skipBanner) {
+        if (result.ok)
+            logSuccess(`PostgreSQL ${result.serverMajor} connection is ready.`);
+        else
+            logInfo(`PostgreSQL connection test failed: ${result.code}`);
+    }
+    return result;
+}
+export async function runCommunitySetupServerEnv(options = {}) {
+    const snapshot = readAopsServerEnvFileContent(process.env, options.envPath);
+    const existing = parseDotEnvAssignments(snapshot.content);
+    const existingUrl = normalizeNonEmpty(existing.AOPS_PG_URL)
+        ?? normalizeNonEmpty(existing.AOPS_REPO_URL);
+    const environmentUrl = normalizeNonEmpty(process.env.AOPS_PG_URL)
+        ?? normalizeNonEmpty(process.env.AOPS_REPO_URL);
+    let repoUrl = normalizeNonEmpty(options.repoUrl) ?? environmentUrl ?? existingUrl;
+    if (!options.repoUrl && !options.yes && !options.json) {
+        if (!options.skipBanner)
+            banner('AOPS Community Server Environment');
+        const savedUrl = repoUrl;
+        const promptedUrl = await promptPassword({
+            message: existingUrl || environmentUrl
+                ? 'External PostgreSQL URL [saved: ********] (press Enter to keep):'
+                : 'External PostgreSQL URL:',
+            validate: (value) => {
+                if (!value.trim() && savedUrl)
+                    return true;
+                try {
+                    validatePostgresUrl(value.trim());
+                    return true;
+                }
+                catch {
+                    return 'A PostgreSQL URL is required.';
+                }
+            },
+        });
+        repoUrl = resolvePromptedPostgresUrl(promptedUrl, savedUrl);
+    }
+    if (!repoUrl) {
+        throw new Error('setup_server_env_postgres_url_required:use_interactive_prompt_or_AOPS_PG_URL');
+    }
+    repoUrl = validatePostgresUrl(repoUrl);
+    const authProvider = resolveServerEnvAuthProvider(options.auth, existing);
+    const preset = buildServerBootstrapPreset({
+        authProvider,
+        repoUrl,
+        existing,
+    });
+    const env = buildServerBootstrapEnvMap(preset);
+    const validation = validateServerBootstrapEnv(env, {
+        authProvider: preset.authProvider,
+        repoUrl,
+    });
+    if (!validation.ok || validation.repoDialect !== 'pg') {
+        throw new Error('setup_server_env_postgres_validation_failed');
+    }
+    const content = upsertServerBootstrapBlock({
+        existingContent: snapshot.content,
+        env,
+        authProvider: preset.authProvider,
+        repoUrl,
+    });
+    const updated = content !== snapshot.content;
+    const permissionsRepaired = snapshot.exists &&
+        process.platform !== 'win32' &&
+        (statSync(snapshot.path).mode & 0o777) !== 0o600;
+    const envPath = updated || permissionsRepaired
+        ? writeAopsServerEnvFileContent(content, process.env, options.envPath)
+        : snapshot.path;
+    const result = Object.freeze({
+        ok: true,
+        action: 'setup.server-env',
+        envPath,
+        repoDialect: 'pg',
+        authProvider: preset.authProvider,
+        updated,
+        permissionsRepaired,
+    });
+    if (options.json)
+        console.log(JSON.stringify(result, null, 2));
+    else if (!options.skipBanner) {
+        logSuccess(updated ? 'Global AOPS server environment is ready.' : 'Global AOPS server environment was already ready.');
+        logInfo(`Host env: ${envPath}`);
+    }
+    return result;
+}

package/dist/lib/external-url.js

@@ -0,0 +1,110 @@
+import { spawn } from 'node:child_process';
+const externalOpenRuntime = Object.freeze({
+    spawn,
+    handoffTimeoutMs: 1_500,
+});
+function assertLocalHttpUrl(value) {
+    const parsed = new URL(value);
+    const localHosts = new Set(['127.0.0.1', 'localhost', '[::1]']);
+    if (!['http:', 'https:'].includes(parsed.protocol) ||
+        !localHosts.has(parsed.hostname) ||
+        parsed.username || parsed.password) {
+        throw new Error('aops_external_url_refused:only_loopback_http_urls_are_allowed');
+    }
+    return parsed.href;
+}
+function assertHttpsOrigin(value) {
+    const parsed = new URL(value);
+    if (parsed.protocol !== 'https:' ||
+        parsed.username ||
+        parsed.password ||
+        (parsed.pathname !== '/' && parsed.pathname !== '') ||
+        parsed.search ||
+        parsed.hash) {
+        throw new Error('aops_external_origin_refused:https_origin_required');
+    }
+    return parsed.origin;
+}
+function assertSameOriginHttpsUrl(value, expectedOrigin) {
+    const origin = assertHttpsOrigin(expectedOrigin);
+    const parsed = new URL(value);
+    if (parsed.protocol !== 'https:' ||
+        parsed.origin !== origin ||
+        parsed.username ||
+        parsed.password ||
+        parsed.hash) {
+        throw new Error('aops_external_url_refused:same_origin_https_url_required');
+    }
+    return parsed.href;
+}
+function resolveOpenInvocation(url, platform) {
+    if (platform === 'win32')
+        return { command: 'explorer.exe', args: [url] };
+    if (platform === 'darwin')
+        return { command: 'open', args: [url] };
+    return { command: 'xdg-open', args: [url] };
+}
+export function resolveExternalOpenInvocation(value, platform = process.platform) {
+    return resolveOpenInvocation(assertLocalHttpUrl(value), platform);
+}
+export function resolveApprovedHttpsOpenInvocation(value, expectedOrigin, platform = process.platform) {
+    return resolveOpenInvocation(assertSameOriginHttpsUrl(value, expectedOrigin), platform);
+}
+async function waitForSpawn(child) {
+    await new Promise((resolve, reject) => {
+        const onSpawn = () => {
+            child.off('error', onError);
+            resolve();
+        };
+        const onError = (error) => {
+            child.off('spawn', onSpawn);
+            reject(error);
+        };
+        child.once('spawn', onSpawn);
+        child.once('error', onError);
+    });
+}
+async function observeImmediateOpenFailure(child, timeoutMs) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        return { exitCode: child.exitCode, signal: child.signalCode };
+    }
+    return new Promise((resolve, reject) => {
+        const finish = (result) => {
+            clearTimeout(timer);
+            child.off('exit', onExit);
+            child.off('error', onError);
+            resolve(result);
+        };
+        const onExit = (exitCode, signal) => finish({ exitCode, signal });
+        const onError = (error) => {
+            clearTimeout(timer);
+            child.off('exit', onExit);
+            reject(error);
+        };
+        const timer = setTimeout(() => finish(null), timeoutMs);
+        child.once('exit', onExit);
+        child.once('error', onError);
+    });
+}
+export async function openExternalUrl(value, runtime = externalOpenRuntime) {
+    const invocation = resolveExternalOpenInvocation(value);
+    await openInvocation(invocation, runtime);
+}
+export async function openApprovedHttpsUrl(value, expectedOrigin, runtime = externalOpenRuntime) {
+    const invocation = resolveApprovedHttpsOpenInvocation(value, expectedOrigin);
+    await openInvocation(invocation, runtime);
+}
+async function openInvocation(invocation, runtime) {
+    const child = runtime.spawn(invocation.command, invocation.args, {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+    });
+    await waitForSpawn(child);
+    const immediateExit = await observeImmediateOpenFailure(child, runtime.handoffTimeoutMs);
+    if (immediateExit && immediateExit.exitCode !== 0) {
+        throw new Error(`aops_external_open_failed:${immediateExit.exitCode ?? immediateExit.signal ?? 'unknown'}`);
+    }
+    if (!immediateExit)
+        child.unref();
+}

package/dist/lib/official-catalog-gateway.js

@@ -0,0 +1,108 @@
+import { assertOfficialCatalogReceiptV1, assertOfficialCatalogSnapshotV1, OFFICIAL_CATALOG_SCOPE_V1, OFFICIAL_CATALOG_TOOL_IDS_V1, OfficialCatalogError, } from './official-catalog.js';
+import { invokeHostedToolWithApiState, unwrapHostedToolResult } from '../utils/agent-gateway.js';
+import { createCliApiClientFromOptions } from '../utils/api.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function unwrapData(value) {
+    let current = value;
+    for (let depth = 0; depth < 4; depth += 1) {
+        if (!isRecord(current))
+            break;
+        if (Object.prototype.hasOwnProperty.call(current, 'response')) {
+            current = current.response;
+            continue;
+        }
+        if (Object.prototype.hasOwnProperty.call(current, 'data')) {
+            current = current.data;
+            continue;
+        }
+        break;
+    }
+    return current;
+}
+function remoteError(toolId, error) {
+    return new OfficialCatalogError('catalog_adapter_unavailable', `The server does not expose the required official-catalog operation: ${toolId}.`, {
+        toolId,
+        dependency: 'Agentspace official-catalog composite operation',
+        cause: error instanceof Error ? error.message : String(error),
+    });
+}
+export function createOfficialCatalogGatewayAdapterV1(invoke) {
+    return Object.freeze({
+        async inspect() {
+            const toolId = OFFICIAL_CATALOG_TOOL_IDS_V1.inspect;
+            try {
+                const result = unwrapData(await invoke(toolId, { scope: OFFICIAL_CATALOG_SCOPE_V1 }, {
+                    preview: false,
+                    apply: false,
+                    confirm: false,
+                }));
+                assertOfficialCatalogSnapshotV1(result);
+                return result;
+            }
+            catch (error) {
+                if (error instanceof OfficialCatalogError && error.code !== 'catalog_adapter_unavailable')
+                    throw error;
+                throw remoteError(toolId, error);
+            }
+        },
+        async reconcile(plan, mode) {
+            const toolId = OFFICIAL_CATALOG_TOOL_IDS_V1.reconcile;
+            try {
+                const result = unwrapData(await invoke(toolId, { plan }, {
+                    preview: mode === 'preview',
+                    apply: mode === 'apply',
+                    confirm: false,
+                    idempotencyKey: plan.idempotencyKey,
+                }));
+                if (mode === 'preview')
+                    return result;
+                const receipt = result;
+                assertOfficialCatalogReceiptV1(receipt, 'reconcile');
+                return receipt;
+            }
+            catch (error) {
+                if (error instanceof OfficialCatalogError && error.code !== 'catalog_adapter_unavailable')
+                    throw error;
+                throw remoteError(toolId, error);
+            }
+        },
+        async rollback(request, mode) {
+            const toolId = OFFICIAL_CATALOG_TOOL_IDS_V1.rollback;
+            try {
+                const result = unwrapData(await invoke(toolId, { request }, {
+                    preview: mode === 'preview',
+                    apply: mode === 'apply',
+                    confirm: mode === 'apply',
+                    idempotencyKey: request.idempotencyKey,
+                }));
+                if (mode === 'preview')
+                    return result;
+                const receipt = result;
+                assertOfficialCatalogReceiptV1(receipt, 'rollback');
+                return receipt;
+            }
+            catch (error) {
+                if (error instanceof OfficialCatalogError && error.code !== 'catalog_adapter_unavailable')
+                    throw error;
+                throw remoteError(toolId, error);
+            }
+        },
+    });
+}
+export async function createHostedOfficialCatalogAdapterV1(options = {}) {
+    const apiState = await createCliApiClientFromOptions(options);
+    return createOfficialCatalogGatewayAdapterV1(async (toolId, input, envelope) => {
+        const payload = await invokeHostedToolWithApiState(apiState, {
+            ...options,
+            toolId,
+            input,
+            preview: envelope.preview,
+            apply: envelope.apply,
+            confirm: envelope.confirm,
+            idempotencyKey: envelope.idempotencyKey,
+        });
+        return unwrapHostedToolResult(payload);
+    });
+}