@knowzai/cli 0.1.0

package/dist/lib/platform-lifecycle.js

@@ -0,0 +1,725 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, } from 'node:fs';
+import { join } from 'node:path';
+import { isIP } from 'node:net';
+import { fileURLToPath } from 'node:url';
+import { buildPlatformEnvironment, buildPlatformPlan, composeFailureError, createPlatformState, executeComposeInvocations, executeComposeInvocationsAsync, nodeAsyncProcessRunner, nodeProcessRunner, parseEnv, planComposeInvocations, PLATFORM_PROVIDERS, PLATFORM_SECRET_KEYS, redactPlatformSecrets, renderEnv, resolvePlatformPaths, serializePlatformState, writePrivateFile, } from './platform-runtime.js';
+import { engineCheckSlice, loginCommandFor, resolveEngineStatus, runEngineProbes, runEngineProbesAsync, } from './container-engine.js';
+import { withSpinner } from './ui.js';
+const AMBIENT_ENV_KEYS = [
+    'KNOWZ_VERSION',
+    'KNOWZ_PROVIDER',
+    'BIND_ADDRESS',
+    'PUBLIC_API_URL',
+    'PUBLIC_WEB_ORIGIN',
+    'PUBLIC_MCP_URL',
+    'PUBLIC_SITE_URL',
+    'KNOWZ_COMPONENTS',
+    'KNOWZ__CLOUDPROVIDER__AI',
+    'KNOWZ__CLOUDPROVIDER__DOCINTELLIGENCE',
+    'KNOWZ__CLOUDPROVIDER__VISION',
+    'KNOWZ__CLOUDPROVIDER__TRANSCRIPTION',
+    'API_PORT',
+    'WEB_PORT',
+    'MCP_PORT',
+    'PUBLIC_SITE_PORT',
+    'STORAGE_PROVIDER',
+    'AZURE_OPENAI_ENDPOINT',
+    'AZURE_OPENAI_API_KEY',
+    'GCLOUD_ADC_PATH',
+    'VERTEX__PROJECT',
+    'VERTEX__REGION',
+    'VERTEX__CHATMODEL',
+    'VERTEX__EMBEDDINGMODEL',
+    'VERTEX__EMBEDDINGDIMENSIONS',
+    'OPENAICOMPAT__ENDPOINT',
+    'OPENAICOMPAT__APIKEY',
+    'OPENAICOMPAT__CHATMODEL',
+    'OPENAICOMPAT__EMBEDDINGMODEL',
+    'OPENAICOMPAT__EMBEDDINGDIMENSIONS',
+    'EMBEDDING_DIMENSIONS',
+];
+function profilesForComponents(components) {
+    return [
+        ...(components?.mcp === false ? [] : ['mcp']),
+        ...(components?.publicSite === true ? ['public-site'] : []),
+    ];
+}
+export function resolvePackagedAssetsDir(moduleUrl = import.meta.url) {
+    return fileURLToPath(new URL('../../assets/portable', moduleUrl));
+}
+function readTextIfPresent(path) {
+    return existsSync(path) ? readFileSync(path, 'utf8') : undefined;
+}
+function parseState(path) {
+    const contents = readTextIfPresent(path);
+    if (contents === undefined)
+        return undefined;
+    let state;
+    try {
+        state = JSON.parse(contents);
+    }
+    catch {
+        throw new Error(`Platform state is invalid JSON: ${path}`);
+    }
+    if (typeof state !== 'object' ||
+        state === null ||
+        !('schemaVersion' in state) ||
+        state.schemaVersion !== 1 ||
+        !('name' in state) ||
+        typeof state.name !== 'string' ||
+        !('version' in state) ||
+        typeof state.version !== 'string' ||
+        !('provider' in state) ||
+        typeof state.provider !== 'string') {
+        throw new Error(`Platform state has an unsupported shape: ${path}`);
+    }
+    return state;
+}
+function requireInitialized(name, configDir) {
+    const paths = resolvePlatformPaths(name, configDir);
+    const state = parseState(paths.stateFile);
+    if (!state || !existsSync(paths.composeFile) || !existsSync(paths.envFile)) {
+        throw new Error(`Platform '${name}' is not initialized. Run \`knowz platform up\` first.`);
+    }
+    if (state.name !== name)
+        throw new Error(`Platform state name does not match '${name}'.`);
+    return { paths, state };
+}
+/**
+ * Best-effort state rebuilt from the rendered .env when state.json is missing/unreadable.
+ * Only the project name + compose file + env file are load-bearing for a Compose teardown;
+ * the rest is display metadata, so unknown fields degrade to defaults.
+ */
+function reconstructStateFromEnv(name, paths) {
+    const env = existsSync(paths.envFile) ? parseEnv(readFileSync(paths.envFile, 'utf8')) : {};
+    const provider = PLATFORM_PROVIDERS.includes(env.KNOWZ_PROVIDER ?? '')
+        ? env.KNOWZ_PROVIDER
+        : 'offline';
+    return {
+        schemaVersion: 1,
+        name,
+        version: env.KNOWZ_VERSION ?? 'unknown',
+        provider,
+        storage: env.STORAGE_PROVIDER === 'FileSystem' ? 'filesystem' : 'minio',
+        imageFlavor: env.KNOWZ_FLAVOR === '-gcp' ? '-gcp' : '',
+        axes: { ai: undefined, docIntelligence: 'None', vision: 'None', transcription: 'None' },
+        ports: { api: 5000, web: 3000, mcp: 3001, publicSite: 3002 },
+        serviceUrls: {
+            api: env.PUBLIC_API_URL ?? '',
+            web: env.PUBLIC_WEB_ORIGIN ?? '',
+            mcp: env.PUBLIC_MCP_URL ?? '',
+            publicSite: env.PUBLIC_SITE_URL ?? '',
+        },
+        components: {
+            mcp: env.KNOWZ_COMPONENTS === undefined || env.KNOWZ_COMPONENTS.split(',').includes('mcp'),
+            publicSite: env.KNOWZ_COMPONENTS?.split(',').includes('public-site') ?? false,
+        },
+        updatedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Teardown-tolerant resolver for `down`/`destroy`. A failed or partial `up` can leave the
+ * containers running with an absent/corrupt state.json; as long as the compose file + env
+ * exist we still let the CLI stop them (reconciling a minimal state from disk) rather than
+ * refusing with "not initialized" and forcing the user to raw docker.
+ */
+function resolveTeardownTarget(name, configDir) {
+    const paths = resolvePlatformPaths(name, configDir);
+    if (!existsSync(paths.composeFile) || !existsSync(paths.envFile)) {
+        throw new Error(`Platform '${name}' is not initialized. Run \`knowz platform up\` first.`);
+    }
+    let state;
+    try {
+        state = parseState(paths.stateFile);
+    }
+    catch {
+        state = undefined; // corrupt state.json — reconcile from the env instead of blocking teardown
+    }
+    if (state && state.name !== name)
+        throw new Error(`Platform state name does not match '${name}'.`);
+    return { paths, state: state ?? reconstructStateFromEnv(name, paths) };
+}
+function pickAmbientEnvironment(ambient) {
+    const selected = {};
+    for (const key of AMBIENT_ENV_KEYS) {
+        const value = ambient[key];
+        if (value !== undefined)
+            selected[key] = value;
+    }
+    return selected;
+}
+function integerFromEnvironment(value, label) {
+    if (value === undefined || value.trim() === '')
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed))
+        throw new Error(`Invalid ${label}: expected an integer.`);
+    return parsed;
+}
+function axisFromEnvironment(value) {
+    return value;
+}
+/**
+ * A persisted public URL is only reused across reruns when it's an explicit REMOTE URL
+ * (custom host). A loopback URL (`http://localhost:<port>`) is derived from the port, so drop
+ * it here and let it re-derive from the CURRENT port — otherwise a `--*-port` change on a
+ * re-up would keep announcing the stale old-port URL in the banner / `--open` / "sign in at"
+ * (NEW-MED). Malformed values are dropped so a bad persisted value can't poison the plan.
+ */
+function preservedPublicUrl(value) {
+    if (value === undefined || value.trim() === '')
+        return undefined;
+    let host;
+    try {
+        host = new URL(value).hostname.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+    const loopback = host === 'localhost' || host.endsWith('.localhost') || (isIP(host) === 4 && host.startsWith('127.'));
+    return loopback ? undefined : value;
+}
+function secretValues(environment) {
+    const exactKeys = new Set(PLATFORM_SECRET_KEYS);
+    return Object.entries(environment)
+        .filter(([key, value]) => value.length > 0 && (exactKeys.has(key) || /(api[_-]?key|password|secret|token|credential)/i.test(key)))
+        .map(([, value]) => value);
+}
+function installAssets(paths, assetsDir) {
+    const composeSource = join(assetsDir, 'docker-compose.yml');
+    const contractSource = join(assetsDir, 'runtime-contract.json');
+    const postgresSource = join(assetsDir, 'postgres-initdb');
+    if (!existsSync(composeSource) || !existsSync(contractSource) || !existsSync(postgresSource)) {
+        throw new Error(`Portable runtime assets are incomplete: ${assetsDir}`);
+    }
+    mkdirSync(paths.runtimeDir, { recursive: true, mode: 0o700 });
+    cpSync(composeSource, paths.composeFile);
+    cpSync(contractSource, join(paths.runtimeDir, 'runtime-contract.json'));
+    rmSync(paths.postgresInitDir, { recursive: true, force: true });
+    cpSync(postgresSource, paths.postgresInitDir, { recursive: true });
+}
+function backupRuntimeAssets(paths) {
+    const backupDir = join(paths.runtimeDir, '.upgrade-backup');
+    rmSync(backupDir, { recursive: true, force: true });
+    mkdirSync(backupDir, { recursive: true, mode: 0o700 });
+    cpSync(paths.composeFile, join(backupDir, 'docker-compose.yml'));
+    const contractPath = join(paths.runtimeDir, 'runtime-contract.json');
+    if (existsSync(contractPath))
+        cpSync(contractPath, join(backupDir, 'runtime-contract.json'));
+    if (existsSync(paths.postgresInitDir)) {
+        cpSync(paths.postgresInitDir, join(backupDir, 'postgres-initdb'), { recursive: true });
+    }
+    return backupDir;
+}
+function restoreRuntimeAssets(paths, backupDir) {
+    cpSync(join(backupDir, 'docker-compose.yml'), paths.composeFile);
+    const contractBackup = join(backupDir, 'runtime-contract.json');
+    const contractPath = join(paths.runtimeDir, 'runtime-contract.json');
+    if (existsSync(contractBackup))
+        cpSync(contractBackup, contractPath);
+    else
+        rmSync(contractPath, { force: true });
+    rmSync(paths.postgresInitDir, { recursive: true, force: true });
+    const postgresBackup = join(backupDir, 'postgres-initdb');
+    if (existsSync(postgresBackup))
+        cpSync(postgresBackup, paths.postgresInitDir, { recursive: true });
+    rmSync(backupDir, { recursive: true, force: true });
+}
+function formatReadyOutput(state, paths, verb) {
+    return [
+        `Knowz platform '${state.name}' ${verb} (${state.version}, ${state.provider}, flavor ${state.imageFlavor || 'default'}).`,
+        `Web: ${state.serviceUrls.web}`,
+        `API: ${state.serviceUrls.api}`,
+        `MCP: ${state.serviceUrls.mcp}`,
+        `Runtime: ${paths.runtimeDir}`,
+        `Next: sign in at ${state.serviceUrls.web} with ADMIN_USERNAME/ADMIN_PASSWORD from ${paths.envFile}; use SUPERADMIN_PASSPHRASE at ${state.serviceUrls.web}/superadmin.`,
+        `Then create a self-hosted API key and pipe it to: knowz login --self-hosted --api-url ${state.serviceUrls.api} --key-stdin`,
+    ].join('\n');
+}
+function processOutput(results, knownSecrets) {
+    return redactPlatformSecrets(results
+        .flatMap((result) => [result.stdout, result.stderr])
+        .filter((value) => Boolean(value?.trim()))
+        .join('\n')
+        .trim(), knownSecrets);
+}
+function sanitizedProcessResults(results, knownSecrets) {
+    return results.map((result) => ({
+        status: result.status,
+        stdout: result.stdout === undefined ? undefined : redactPlatformSecrets(result.stdout, knownSecrets),
+        stderr: result.stderr === undefined ? undefined : redactPlatformSecrets(result.stderr, knownSecrets),
+        error: result.error === undefined
+            ? undefined
+            : new Error(redactPlatformSecrets(result.error.message, knownSecrets)),
+    }));
+}
+/**
+ * Run `docker login` with the token on stdin only (never argv, never disk). The
+ * token is added to `knownSecrets` by the caller so any echoed output is redacted.
+ */
+async function authenticateRegistry(login, runner, knownSecrets, cwd, engine) {
+    const loginFront = loginCommandFor(engine);
+    const result = await Promise.resolve(runner(loginFront.command, login.args, {
+        cwd,
+        shell: false,
+        input: login.stdin,
+        ...(loginFront.env ? { env: loginFront.env } : {}),
+    }));
+    if (result.error || result.status !== 0) {
+        const detail = result.stderr || result.stdout || result.error?.message || `exit status ${String(result.status)}`;
+        throw new Error(`Docker registry login failed: ${redactPlatformSecrets(detail.trim(), knownSecrets)}`);
+    }
+}
+function processFailed(result) {
+    return result.error !== undefined || result.status !== 0;
+}
+function missingPreloadedRefs(refs, result) {
+    const detail = `${result.stderr ?? ''}\n${result.stdout ?? ''}`;
+    const named = refs.filter((ref) => detail.includes(ref));
+    return named.length > 0 ? named : [...refs];
+}
+async function assertPreloadedImagesPresent(input, paths, imageSource, engine, runner, knownSecrets) {
+    const [config] = planComposeInvocations(input.action, paths, input.name, {
+        composeFile: imageSource.composeFile,
+        projectDir: imageSource.projectDir,
+        composePlan: 'config-up',
+        engine,
+    });
+    if (!config)
+        throw new Error('Preloaded image preflight could not plan Compose config.');
+    const configResult = await Promise.resolve(runner(config.command, [...config.args, '--images'], config.options));
+    if (processFailed(configResult))
+        throw composeFailureError(configResult, knownSecrets);
+    const refs = [...new Set((configResult.stdout ?? '').split(/\s+/).filter(Boolean))].sort();
+    if (refs.length === 0) {
+        throw new Error('Preloaded image preflight could not derive any image references from Compose.');
+    }
+    const engineFront = loginCommandFor(engine);
+    const inspectResult = await Promise.resolve(runner(engineFront.command, ['image', 'inspect', ...refs], {
+        cwd: paths.runtimeDir,
+        shell: false,
+        ...(engineFront.env ? { env: engineFront.env } : {}),
+    }));
+    if (processFailed(inspectResult)) {
+        const missing = missingPreloadedRefs(refs, inspectResult);
+        throw new Error(`Preloaded platform images are missing: ${missing.join(', ')}. Load the release image bundle with load-image-bundle.sh (normally via knowz-image-load.service), or use docker load, then retry.`);
+    }
+}
+export function spinnerTextFor(invocation) {
+    if (invocation.args.includes('config'))
+        return 'Validating configuration…';
+    if (invocation.args.includes('pull'))
+        return 'Pulling images (first run can take a few minutes)…';
+    if (invocation.args.includes('build'))
+        return 'Building images…';
+    if (invocation.args.includes('up'))
+        return 'Starting services…';
+    return 'Running docker compose…';
+}
+export async function applyPlatform(input, dependencies = {}, imageSource = {}) {
+    const paths = resolvePlatformPaths(input.name, input.configDir);
+    let previousState;
+    try {
+        previousState = parseState(paths.stateFile);
+    }
+    catch (error) {
+        // `up` is the repair path for an otherwise complete runtime whose state
+        // file was interrupted/corrupted. Reconstruct only secret-free metadata
+        // from the private env; upgrades stay strict because rollback needs the
+        // authoritative prior state.
+        if (input.action !== 'up' || !existsSync(paths.composeFile) || !existsSync(paths.envFile))
+            throw error;
+        previousState = reconstructStateFromEnv(input.name, paths);
+    }
+    if (input.action === 'upgrade' && !previousState) {
+        throw new Error(`Platform '${input.name}' is not initialized. Run \`knowz platform up\` first.`);
+    }
+    const previousEnvContents = readTextIfPresent(paths.envFile);
+    const existingEnvironment = previousEnvContents === undefined ? {} : parseEnv(previousEnvContents);
+    const ambient = pickAmbientEnvironment(dependencies.ambientEnv ?? process.env);
+    const configurationAmbient = input.action === 'upgrade' ? {} : ambient;
+    const environmentFallback = { ...existingEnvironment, ...configurationAmbient };
+    const bindAddress = configurationAmbient.BIND_ADDRESS ?? existingEnvironment.BIND_ADDRESS;
+    if (bindAddress !== undefined && isIP(bindAddress) !== 4) {
+        throw new Error('Platform bind address must be an IPv4 address such as 127.0.0.1 or 0.0.0.0.');
+    }
+    const requestedVersion = input.version ?? ambient.KNOWZ_VERSION;
+    if (input.action === 'upgrade' && !requestedVersion) {
+        throw new Error('A new platform version is required for upgrade. Pass --version or set KNOWZ_VERSION.');
+    }
+    const version = requestedVersion ?? existingEnvironment.KNOWZ_VERSION ?? previousState?.version;
+    if (!version)
+        throw new Error('Platform version is required. Pass --version or set KNOWZ_VERSION.');
+    if (input.action === 'upgrade' && version === previousState?.version) {
+        throw new Error(`Platform '${input.name}' already uses ${version}; choose a different pinned version.`);
+    }
+    if (input.action === 'up' && previousState !== undefined && version !== previousState.version) {
+        throw new Error(`Platform '${input.name}' uses ${previousState.version}; run \`knowz platform upgrade --version ${version}\` to change versions.`);
+    }
+    const provider = input.provider ?? configurationAmbient.KNOWZ_PROVIDER ?? previousState?.provider ?? 'offline';
+    const plan = buildPlatformPlan({
+        name: input.name,
+        configDir: input.configDir,
+        version,
+        provider,
+        storage: input.storage,
+        ports: {
+            api: input.ports?.api ??
+                integerFromEnvironment(configurationAmbient.API_PORT ?? existingEnvironment.API_PORT, 'API port'),
+            web: input.ports?.web ??
+                integerFromEnvironment(configurationAmbient.WEB_PORT ?? existingEnvironment.WEB_PORT, 'web port'),
+            mcp: input.ports?.mcp ??
+                integerFromEnvironment(configurationAmbient.MCP_PORT ?? existingEnvironment.MCP_PORT, 'MCP port'),
+            publicSite: input.ports?.publicSite ??
+                integerFromEnvironment(configurationAmbient.PUBLIC_SITE_PORT ?? existingEnvironment.PUBLIC_SITE_PORT, 'public site port'),
+        },
+        publicUrls: {
+            api: input.publicUrls?.api ?? configurationAmbient.PUBLIC_API_URL ?? preservedPublicUrl(existingEnvironment.PUBLIC_API_URL),
+            web: input.publicUrls?.web ??
+                configurationAmbient.PUBLIC_WEB_ORIGIN ??
+                preservedPublicUrl(existingEnvironment.PUBLIC_WEB_ORIGIN),
+            mcp: input.publicUrls?.mcp ?? configurationAmbient.PUBLIC_MCP_URL ?? preservedPublicUrl(existingEnvironment.PUBLIC_MCP_URL),
+            publicSite: input.publicUrls?.publicSite ??
+                configurationAmbient.PUBLIC_SITE_URL ??
+                preservedPublicUrl(existingEnvironment.PUBLIC_SITE_URL),
+        },
+        // Per-FIELD fallback, not per-object. `platformApplyInputFromFlags` always emits a DEFINED
+        // components object whose values are `undefined` when the flags were absent, so an
+        // object-level `??` never falls back and the empty object always wins. That silently
+        // re-enabled a deselected MCP on the next plain `knowz up` — an operator's decision to shut
+        // a listening surface off must survive later applies (R7). SEC-001.
+        components: {
+            mcp: input.components?.mcp ??
+                (configurationAmbient.KNOWZ_COMPONENTS === undefined
+                    ? previousState?.components?.mcp
+                    : configurationAmbient.KNOWZ_COMPONENTS.split(',').includes('mcp')),
+            publicSite: input.components?.publicSite ??
+                (configurationAmbient.KNOWZ_COMPONENTS === undefined
+                    ? previousState?.components?.publicSite
+                    : configurationAmbient.KNOWZ_COMPONENTS.split(',').includes('public-site')),
+        },
+        embeddingDimensions: input.embeddingDimensions ??
+            integerFromEnvironment(configurationAmbient.EMBEDDING_DIMENSIONS ?? existingEnvironment.EMBEDDING_DIMENSIONS, 'embedding dimensions'),
+        requestedFlavor: input.requestedFlavor,
+        axes: {
+            ai: input.axes?.ai ??
+                axisFromEnvironment(configurationAmbient.KNOWZ__CLOUDPROVIDER__AI ?? existingEnvironment.KNOWZ__CLOUDPROVIDER__AI),
+            docIntelligence: input.axes?.docIntelligence ??
+                axisFromEnvironment(configurationAmbient.KNOWZ__CLOUDPROVIDER__DOCINTELLIGENCE ??
+                    existingEnvironment.KNOWZ__CLOUDPROVIDER__DOCINTELLIGENCE),
+            vision: input.axes?.vision ??
+                axisFromEnvironment(configurationAmbient.KNOWZ__CLOUDPROVIDER__VISION ?? existingEnvironment.KNOWZ__CLOUDPROVIDER__VISION),
+            transcription: input.axes?.transcription ??
+                axisFromEnvironment(configurationAmbient.KNOWZ__CLOUDPROVIDER__TRANSCRIPTION ??
+                    existingEnvironment.KNOWZ__CLOUDPROVIDER__TRANSCRIPTION),
+        },
+        azure: input.azure,
+        gcp: input.gcp,
+        openAiCompatible: input.openAiCompatible,
+        existingEnv: environmentFallback,
+    });
+    if (bindAddress !== undefined &&
+        bindAddress !== '127.0.0.1' &&
+        Object.entries(plan.publicUrls).some(([key, value]) => {
+            if (key === 'publicSite' && !plan.components.publicSite)
+                return false;
+            const host = new URL(value).hostname.toLowerCase();
+            return host === 'localhost' || host.endsWith('.localhost') || host.startsWith('127.');
+        })) {
+        throw new Error('Explicit non-local public API, web, and MCP URLs are required for a non-loopback bind address.');
+    }
+    const environment = buildPlatformEnvironment(plan, existingEnvironment, {
+        randomBytes: dependencies.randomBytes,
+        orgName: input.orgName,
+        superAdminPassphrase: input.superAdminPassphrase,
+    });
+    if (imageSource.registry === null)
+        delete environment.KNOWZ_REGISTRY;
+    else if (imageSource.registry !== undefined)
+        environment.KNOWZ_REGISTRY = imageSource.registry;
+    if (bindAddress !== undefined)
+        environment.BIND_ADDRESS = bindAddress;
+    const knownSecrets = imageSource.login
+        ? [...secretValues(environment), imageSource.login.stdin]
+        : secretValues(environment);
+    const runner = dependencies.runner ?? nodeAsyncProcessRunner;
+    const engine = dependencies.engine ?? resolveEngineStatus(await runEngineProbesAsync(runner), process.platform, process.env);
+    const progress = dependencies.progress ?? (process.stdout.isTTY
+        ? withSpinner
+        : async (_text, run) => run());
+    const state = createPlatformState(plan, dependencies.now);
+    state.imageMode = imageSource.composePlan === 'config-build-up'
+        ? 'build'
+        : imageSource.composePlan === 'config-up'
+            ? 'preloaded'
+            : 'pull';
+    const freshInstall = previousState === undefined;
+    let processResults;
+    const backupDir = previousState === undefined ? undefined : backupRuntimeAssets(paths);
+    try {
+        installAssets(paths, dependencies.assetsDir ?? resolvePackagedAssetsDir());
+        writePrivateFile(paths.envFile, renderEnv(environment));
+        // Persist state BEFORE bringing the stack up on a fresh install, so that a failed
+        // `up --wait` still leaves a teardownable runtime (compose file + env + state) — the
+        // CLI can then `knowz down`/`platform reset` the containers `up` may have started
+        // instead of the user reaching for raw docker. Upgrades keep write-after-success below
+        // (their prior state.json already makes teardown work, and rollback must not advance it).
+        if (freshInstall)
+            writePrivateFile(paths.stateFile, serializePlatformState(state));
+        if (imageSource.composePlan === 'config-up') {
+            await assertPreloadedImagesPresent(input, paths, imageSource, engine, runner, knownSecrets);
+        }
+        if (imageSource.login) {
+            await authenticateRegistry(imageSource.login, runner, knownSecrets, paths.runtimeDir, engine);
+        }
+        processResults = await executeComposeInvocationsAsync(planComposeInvocations(input.action, paths, input.name, {
+            composeFile: imageSource.composeFile,
+            projectDir: imageSource.projectDir,
+            composePlan: imageSource.composePlan,
+            engine,
+            profiles: [
+                ...(plan.components.mcp ? ['mcp'] : []),
+                ...(plan.components.publicSite ? ['public-site'] : []),
+            ],
+        }), runner, knownSecrets, (invocation, run) => progress(spinnerTextFor(invocation), run));
+    }
+    catch (error) {
+        if (backupDir !== undefined)
+            restoreRuntimeAssets(paths, backupDir);
+        if (previousEnvContents !== undefined) {
+            writePrivateFile(paths.envFile, previousEnvContents);
+        }
+        // Fresh install: intentionally leave env + state + assets on disk so down/reset can
+        // clean up an orphaned stack from a failed `up`. A retry `up` at the same version
+        // reruns idempotently; `reset` tears it down.
+        throw error;
+    }
+    if (backupDir !== undefined)
+        rmSync(backupDir, { recursive: true, force: true });
+    writePrivateFile(paths.stateFile, serializePlatformState(state));
+    return {
+        paths,
+        state,
+        processResults: sanitizedProcessResults(processResults, knownSecrets),
+        output: formatReadyOutput(state, paths, input.action === 'upgrade' ? 'upgraded' : 'started'),
+    };
+}
+export function runPlatformLifecycle(action, input, dependencies = {}) {
+    // down/destroy must be able to clean up an orphaned stack from a failed `up`, so they
+    // tolerate a missing/corrupt state.json; status/logs still require a healthy runtime.
+    const { paths, state } = action === 'down' || action === 'destroy'
+        ? resolveTeardownTarget(input.name, input.configDir)
+        : requireInitialized(input.name, input.configDir);
+    const environment = parseEnv(readFileSync(paths.envFile, 'utf8'));
+    const knownSecrets = secretValues(environment);
+    const runner = dependencies.runner ?? nodeProcessRunner;
+    const engine = dependencies.engine ?? resolveEngineStatus(runEngineProbes(runner), process.platform, process.env);
+    const processResults = executeComposeInvocations(planComposeInvocations(action, paths, input.name, {
+        confirmed: input.confirmed,
+        follow: input.follow,
+        tail: input.tail,
+        engine,
+        ...(action === 'status' || action === 'logs'
+            ? { profiles: profilesForComponents(state.components) }
+            : {}),
+    }), runner, knownSecrets);
+    let output = processOutput(processResults, knownSecrets);
+    let versionSources;
+    let versionConsistent;
+    if (action === 'status') {
+        const rows = parseComposePsRows(processResults[0]?.stdout ?? '');
+        ({ versionSources, versionConsistent } = observePlatformVersions(state, environment, rows));
+        output = rows.map((row) => [row.Service ?? 'unknown', row.State ?? 'unknown', row.Health].filter(Boolean).join(' ')).join('\n');
+    }
+    if (action === 'destroy')
+        rmSync(paths.runtimeDir, { recursive: true, force: true });
+    return {
+        paths,
+        state,
+        processResults: sanitizedProcessResults(processResults, knownSecrets),
+        output,
+        destroyed: action === 'destroy',
+        ...(versionSources ? { versionSources, versionConsistent } : {}),
+    };
+}
+function doctorCheckName(id) {
+    switch (id) {
+        case 'docker-cli': return 'Docker';
+        case 'docker-compose': return 'Docker Compose';
+        case 'docker-daemon': return 'Docker daemon';
+        case 'podman-cli': return 'Podman';
+        case 'compose-v2': return 'Docker Compose v2';
+        case 'podman-machine': return 'Podman machine';
+        case 'podman-socket': return 'Podman socket';
+        default: return 'Container engine';
+    }
+}
+function doctorChecks(engine) {
+    return engineCheckSlice(engine).map((check) => ({
+        name: doctorCheckName(check.id),
+        ok: check.ok,
+        detail: check.ok
+            ? check.label
+            : [check.message, check.remedy].filter(Boolean).join(' '),
+    }));
+}
+const KNOWZ_APPLICATION_SERVICES = new Set(['api', 'worker', 'web', 'mcp', 'public-site']);
+const IMAGE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+function imageVersion(image) {
+    const lastSlash = image.lastIndexOf('/');
+    const tagSeparator = image.lastIndexOf(':');
+    if (tagSeparator <= lastSlash)
+        return undefined;
+    const tag = image.slice(tagSeparator + 1).replace(/-portable(?:-gcp)?$/, '');
+    return IMAGE_VERSION.test(tag) ? tag : undefined;
+}
+export function observePlatformVersions(state, environment, rows) {
+    const running = {};
+    const unparsedApplicationImages = [];
+    for (const row of rows) {
+        const service = row.Service?.toLowerCase();
+        if (!service || !KNOWZ_APPLICATION_SERVICES.has(service) || row.State?.toLowerCase() !== 'running')
+            continue;
+        const version = row.Image ? imageVersion(row.Image) : undefined;
+        if (version)
+            running[service] = version;
+        else
+            unparsedApplicationImages.push(service);
+    }
+    const environmentVersion = environment.KNOWZ_VERSION?.trim() || undefined;
+    const observed = [state.version, environmentVersion, ...Object.values(running)]
+        .filter((value) => Boolean(value));
+    return {
+        versionSources: {
+            state: state.version,
+            environment: environmentVersion,
+            running,
+            unparsedApplicationImages: unparsedApplicationImages.sort(),
+        },
+        versionConsistent: Boolean(environmentVersion) &&
+            unparsedApplicationImages.length === 0 &&
+            new Set(observed).size === 1,
+    };
+}
+function versionDetail(sources) {
+    const running = Object.entries(sources.running)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([service, version]) => `${service}=${version}`)
+        .join(', ') || 'none observed';
+    const warning = sources.unparsedApplicationImages.length > 0
+        ? `; warning: unparseable application images for ${sources.unparsedApplicationImages.join(', ')}`
+        : '';
+    return `state=${sources.state}; env=${sources.environment ?? 'missing'}; running=${running}${warning}`;
+}
+function requiredComposeServices(paths, components) {
+    const contractPath = join(paths.runtimeDir, 'runtime-contract.json');
+    let contract;
+    try {
+        contract = JSON.parse(readFileSync(contractPath, 'utf8'));
+    }
+    catch {
+        throw new Error(`Portable runtime contract is invalid: ${contractPath}`);
+    }
+    const required = (contract.services ?? [])
+        .filter((service) => {
+        if (typeof service.id !== 'string')
+            return false;
+        if (service.required === true)
+            return true;
+        if (service.profile === 'mcp')
+            return components?.mcp !== false;
+        if (service.profile === 'public-site')
+            return components?.publicSite === true;
+        return false;
+    })
+        .map((service) => ({
+        service: service.id === 'object-storage' ? 'minio' : service.id,
+        health: service.health ?? 'compose-process',
+    }));
+    if (required.length === 0)
+        throw new Error('Portable runtime contract declares no required services.');
+    return required;
+}
+function parseComposePsRows(output) {
+    try {
+        const parsed = JSON.parse(output);
+        return Array.isArray(parsed) ? parsed : [parsed];
+    }
+    catch {
+        try {
+            return output
+                .split(/\r?\n/)
+                .filter((line) => line.trim().length > 0)
+                .map((line) => JSON.parse(line));
+        }
+        catch {
+            throw new Error('Docker Compose returned invalid JSON service status.');
+        }
+    }
+}
+function validateComposeHealth(paths, state, result) {
+    const rows = parseComposePsRows(result.stdout ?? '');
+    const byService = new Map(rows.map((row) => [row.Service, row]));
+    const required = requiredComposeServices(paths, state.components);
+    for (const requirement of required) {
+        const service = requirement.service;
+        const row = byService.get(service);
+        if (!row)
+            throw new Error(`Required portable service '${service}' is missing.`);
+        if (row.State?.toLowerCase() !== 'running') {
+            throw new Error(`Required portable service '${service}' is ${row.State || 'not running'}.`);
+        }
+        if (requirement.health !== 'compose-process' && row.Health?.toLowerCase() !== 'healthy') {
+            throw new Error(`Required portable service '${service}' is ${row.Health || 'not healthy'}.`);
+        }
+    }
+    return `${required.length}/${required.length} required services running`;
+}
+export function runPlatformDoctor(input, dependencies = {}) {
+    const runner = dependencies.runner ?? nodeProcessRunner;
+    const engine = dependencies.engine ?? resolveEngineStatus(runEngineProbes(runner), process.platform, process.env);
+    const checks = doctorChecks(engine);
+    const paths = resolvePlatformPaths(input.name, input.configDir);
+    const state = parseState(paths.stateFile);
+    if (!state) {
+        return {
+            initialized: false,
+            checks,
+            output: `${checks.map((check) => `${check.name}: ${check.detail}`).join('\n')}\nRuntime: not initialized`,
+        };
+    }
+    if (checks.some((check) => !check.ok)) {
+        return {
+            initialized: true,
+            checks,
+            state,
+            output: checks.map((check) => `${check.name}: ${check.detail}`).join('\n'),
+        };
+    }
+    const initialized = requireInitialized(input.name, input.configDir);
+    const environment = parseEnv(readFileSync(initialized.paths.envFile, 'utf8'));
+    const knownSecrets = secretValues(environment);
+    const results = executeComposeInvocations(planComposeInvocations('doctor', initialized.paths, input.name, {
+        engine,
+        profiles: profilesForComponents(initialized.state.components),
+    }), runner, knownSecrets);
+    // A successful `compose config` is a validation signal; never return its rendered environment.
+    const composeDetail = validateComposeHealth(initialized.paths, initialized.state, results[1] ?? { status: null });
+    checks.push({ name: 'Runtime Compose', ok: true, detail: composeDetail || 'configuration and service status are valid' });
+    const rows = parseComposePsRows(results[1]?.stdout ?? '');
+    const versions = observePlatformVersions(initialized.state, environment, rows);
+    checks.push({
+        name: 'Runtime Versions',
+        ok: versions.versionConsistent,
+        detail: versionDetail(versions.versionSources),
+    });
+    return {
+        initialized: true,
+        checks,
+        state: initialized.state,
+        versionSources: versions.versionSources,
+        versionConsistent: versions.versionConsistent,
+        output: checks.map((check) => `${check.name}: ${check.detail}`).join('\n'),
+    };
+}
+//# sourceMappingURL=platform-lifecycle.js.map