@knowzai/cli 0.4.0 → 0.5.0

package/dist/lib/runtime-status.js

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { observePlatformVersions } from './platform-lifecycle.js';
+function requirements(runtime) {
+    if (runtime.edition === 'selfhosted')
+        return [
+            { id: 'db', health: true },
+            { id: 'api', health: true },
+            { id: 'web', health: false },
+            ...(runtime.state.components?.mcp === false ? [] : [{ id: 'mcp', health: true }]),
+            ...(runtime.state.version.startsWith('0.15.')
+                ? [{ id: 'lmstudio-bridge', health: true }]
+                : []),
+        ];
+    const document = JSON.parse(readFileSync(join(runtime.paths.runtimeDir, 'runtime-contract.json'), 'utf8'));
+    const result = (document.services ?? [])
+        .filter((service) => service.required ||
+        (service.profile === 'mcp' && runtime.state.components?.mcp !== false) ||
+        (service.profile === 'public-site' && runtime.state.components?.publicSite))
+        .filter((service) => service.id !== 'object-storage' || runtime.state.storage === 'minio')
+        .map((service) => ({
+        id: service.id === 'object-storage' ? 'minio' : service.id,
+        health: service.health !== 'compose-process',
+    }));
+    if (!result.length)
+        throw new Error('Runtime contract has no required services. Restore the installed runtime contract.');
+    return result;
+}
+export function runtimeHealth(runtime, environment, rows) {
+    const checks = requirements(runtime).map((requirement) => {
+        const instances = rows.filter((row) => row.Service === requirement.id);
+        const ok = instances.length > 0 &&
+            instances.every((row) => row.State?.toLowerCase() === 'running' &&
+                (!requirement.health || row.Health?.toLowerCase() === 'healthy'));
+        return {
+            name: `Service ${requirement.id}`,
+            ok,
+            detail: instances.length
+                ? instances.map((row) => `${row.State ?? 'unknown'} ${row.Health ?? ''}`.trim()).join(', ')
+                : 'missing',
+        };
+    });
+    const versions = observePlatformVersions(runtime.state, {
+        ...environment,
+        KNOWZ_VERSION: (runtime.edition === 'selfhosted'
+            ? environment.KNOWZ_SELFHOSTED_VERSION
+            : environment.KNOWZ_VERSION) ?? '',
+    }, rows);
+    checks.push({
+        name: 'Runtime versions',
+        ok: versions.versionConsistent,
+        detail: `Installed ${runtime.state.version}; environment ${versions.versionSources.environment ?? 'missing'}; running ${JSON.stringify(versions.versionSources.running)}`,
+    });
+    if (runtime.hasHealthyState === false ||
+        (runtime.attemptStatus && runtime.attemptStatus !== 'ready')) {
+        checks.push({
+            name: 'Last attempt',
+            ok: false,
+            detail: `Last runtime attempt: ${runtime.attemptStatus ?? 'incomplete'}; ${runtime.hasHealthyState === false ? 'no verified installation has been committed' : 'the prior installed release is preserved'}. Retry setup or inspect runtime logs.`,
+        });
+    }
+    const allStopped = rows.length > 0 && rows.every((row) => row.State?.toLowerCase() !== 'running');
+    const status = rows.length === 0
+        ? 'missing'
+        : allStopped
+            ? 'stopped'
+            : checks.every((check) => check.ok)
+                ? 'ready'
+                : 'partial';
+    const attemptPath = join(runtime.paths.runtimeDir, 'attempt.json');
+    let desiredVersion;
+    if (existsSync(attemptPath)) {
+        try {
+            const attempted = JSON.parse(readFileSync(attemptPath, 'utf8'));
+            if (typeof attempted.version === 'string' &&
+                /^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/.test(attempted.version))
+                desiredVersion = attempted.version;
+        }
+        catch {
+            checks.push({
+                name: 'Last attempt',
+                ok: false,
+                detail: 'Invalid attempt metadata; inspect the runtime directory.',
+            });
+        }
+    }
+    const provider = providerReadiness(runtime, environment);
+    checks.push({ name: 'Provider configuration', ok: provider.configured, detail: provider.detail });
+    return {
+        status,
+        checks,
+        services: rows,
+        ...versions,
+        ...(desiredVersion ? { desiredVersion } : {}),
+        provider,
+    };
+}
+function providerReadiness(runtime, env) {
+    const mode = runtime.state.provider;
+    const required = mode === 'offline'
+        ? []
+        : mode === 'azure'
+            ? [
+                'AZURE_OPENAI_ENDPOINT',
+                runtime.edition === 'selfhosted' ? 'AZURE_OPENAI_APIKEY' : 'AZURE_OPENAI_API_KEY',
+            ]
+            : mode === 'gcp'
+                ? ['VERTEX__PROJECT', 'GCLOUD_ADC_PATH']
+                : runtime.edition === 'selfhosted'
+                    ? [
+                        'OPENAI_COMPAT_ENDPOINT',
+                        'OPENAI_COMPAT_CHAT_MODEL',
+                        'OPENAI_COMPAT_EMBEDDING_MODEL',
+                    ]
+                    : ['OPENAICOMPAT__ENDPOINT', 'OPENAICOMPAT__CHATMODEL', 'OPENAICOMPAT__EMBEDDINGMODEL'];
+    const missing = required.filter((key) => !env[key]?.trim());
+    return {
+        mode,
+        configured: missing.length === 0,
+        connectivity: 'not-checked',
+        detail: mode === 'offline'
+            ? env.KNOWZ_AI_DISABLED === 'true' ? 'AI is explicitly disabled by the host; knowledge storage remains available.' : 'No host AI provider is selected. Application configuration may override this; check Instance configuration for the active provider.'
+            : missing.length
+                ? `Missing provider settings: ${missing.join(', ')}. Reconfigure through knowz up.`
+                : 'Provider settings are present. Use the application connection test to verify provider connectivity.',
+    };
+}
+//# sourceMappingURL=runtime-status.js.map

package/dist/lib/runtime-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-status.js","sourceRoot":"","sources":["../../src/lib/runtime-status.ts"],"names":[],"mappings":"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"}

package/dist/lib/selfhosted-backup.d.ts

@@ -0,0 +1,37 @@
+import { type PlatformPaths, type ProcessRunner, type AsyncProcessRunner } from './platform-runtime.js';
+import type { EngineStatus } from './container-engine.js';
+interface RuntimeInput {
+    paths: PlatformPaths;
+    projectName: string;
+    engine?: EngineStatus;
+    runner: ProcessRunner | AsyncProcessRunner;
+    emit?: (line: string) => void;
+}
+export declare function runSelfHostedBackup(input: RuntimeInput & {
+    out?: string;
+    encrypt: boolean;
+    passphrase?: string;
+    cliVersion: string;
+}): Promise<{
+    archive: string;
+    encrypted: boolean;
+    warning: string;
+}>;
+export declare function runSelfHostedRestore(input: RuntimeInput & {
+    archive: string;
+    passphrase?: string;
+    yes: boolean;
+    isTty: boolean;
+    replaceExisting?: boolean;
+    confirmName?: () => Promise<string>;
+}): Promise<{
+    edition: "selfhosted";
+    version: string;
+    platformName: string;
+    integrityChecked: boolean;
+    healthPassed: boolean;
+    next: string;
+    warning: string;
+}>;
+export {};
+//# sourceMappingURL=selfhosted-backup.d.ts.map

package/dist/lib/selfhosted-backup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selfhosted-backup.d.ts","sourceRoot":"","sources":["../../src/lib/selfhosted-backup.ts"],"names":[],"mappings":"AA4BA,OAAO,EAML,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,UAAU,YAAY;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,aAAa,GAAG,kBAAkB,CAAC;IAC3C,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B;AA8ED,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,YAAY,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE;aAiDxE,MAAM;eAAa,OAAO;aAAW,MAAM;GAuOrE;AACD,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,YAAY,GAAG;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACrC;;;;;;;;GAkRF"}

package/dist/lib/selfhosted-backup.js

@@ -0,0 +1,446 @@
+import { preserveLegacySelfHostedKeyring } from './selfhosted-keyring.js';
+import { assertLocalEngineContext, readSavedLocalEngine } from './local-engine-context.js';
+import { acquireRuntimeLock } from './runtime-lock.js';
+import { withAnonymousRegistry } from './anonymous-registry.js';
+import { copyFileSync, existsSync, readFileSync, rmSync, statSync, writeFileSync, createReadStream, } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
+import { KnowzError, ExitCode, ensurePrivateDirectory, protectPrivatePath } from '@knowzai/core';
+import { createPrivateStaging, encryptStream, finalizePrivateArchive, executeBackupSteps, } from './platform-backup.js';
+import { SELFHOSTED_BACKUP_ARTIFACTS, withRuntimeBackup } from './runtime-backup-archive.js';
+import { resolvePackagedSelfHostedAssetsDir, resolveSelfHostedReleaseContract, } from './selfhosted-lifecycle.js';
+import { parseEnv, writePrivateFile, validateProjectName, validatePort, redactPlatformSecrets, } from './platform-runtime.js';
+const warning = 'This private backup contains knowledge, file data, user credentials, runtime secrets and the provider encryption keyring. Store it securely; use --encrypt for passphrase protection.';
+function runtime(input) {
+    validateProjectName(input.projectName);
+    if (!input.engine?.daemonReachable ||
+        !input.engine.composeFront ||
+        input.engine.engine === 'none')
+        throw new KnowzError('Start Docker Desktop or Podman with Compose before backup/restore.', ExitCode.Usage);
+    return input.engine;
+}
+function invocation(input, args, compose = true) {
+    const engine = runtime(input);
+    const front = engine.composeFront;
+    return {
+        command: compose ? front.command : engine.engine,
+        args: compose
+            ? [
+                ...front.baseArgs,
+                '--project-name',
+                `knowz-selfhosted-${input.projectName}`,
+                '--file',
+                input.paths.composeFile,
+                '--env-file',
+                input.paths.envFile,
+                ...args,
+            ]
+            : args,
+        options: {
+            cwd: existsSync(input.paths.runtimeDir) ? input.paths.runtimeDir : process.cwd(),
+            shell: false,
+            ...(front.env ? { env: front.env } : {}),
+        },
+    };
+}
+async function run(input, args, description, compose = true, secrets = []) {
+    const call = invocation(input, args, compose);
+    const result = !compose && args[0] === 'run' && args.includes('alpine:3.21')
+        ? await withAnonymousRegistry(call.options.env, async (env) => input.runner(call.command, call.args, { ...call.options, env }))
+        : await input.runner(call.command, call.args, call.options);
+    if (result.status !== 0)
+        throw new KnowzError(`${description} failed: ${redactPlatformSecrets(result.stderr || result.error?.message || 'container command failed', secrets)}`, ExitCode.Generic);
+    return result;
+}
+function release(version) {
+    const catalog = JSON.parse(readFileSync(join(resolvePackagedSelfHostedAssetsDir(), 'releases.json'), 'utf8'));
+    const contract = resolveSelfHostedReleaseContract(JSON.stringify(catalog), version);
+    if (contract.runtime.database !== 'postgres')
+        throw new KnowzError('Legacy MSSQL backup/restore is unsupported by this PostgreSQL adapter. Use the matching legacy tools; never restore SQL backups into PostgreSQL.', ExitCode.Usage);
+    return { contract, digests: catalog.releases.find((x) => x.version === version)?.digests ?? {} };
+}
+async function sha(path) {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return 'sha256:' + hash.digest('hex');
+}
+export async function runSelfHostedBackup(input) {
+    const state = JSON.parse(readFileSync(input.paths.stateFile, 'utf8'));
+    const metadata = release(state.version);
+    if (state.edition !== 'selfhosted' || state.name !== input.projectName)
+        throw new KnowzError('Runtime identity does not match selfhosted backup target.', ExitCode.Usage);
+    const env = parseEnv(readFileSync(input.paths.envFile, 'utf8'));
+    if (env.KNOWZ_SELFHOSTED_VERSION !== state.version)
+        throw new KnowzError('Runtime version and environment disagree; repair setup before backup.', ExitCode.Usage);
+    if (input.encrypt && !input.passphrase)
+        throw new KnowzError('A passphrase is required for --encrypt.', ExitCode.Auth);
+    const secrets = Object.entries(env)
+        .filter(([key]) => /password|secret|key|token/i.test(key))
+        .map(([, value]) => value)
+        .filter(Boolean);
+    const filename = `knowz-selfhosted-backup-${input.projectName}-${new Date().toISOString().replace(/[:.]/g, '-')}.tar.gz${input.encrypt ? '.enc' : ''}`;
+    let destination = resolve(input.out ?? filename);
+    if (existsSync(destination) && statSync(destination).isDirectory())
+        destination = join(destination, filename);
+    if (input.encrypt && !destination.endsWith('.enc'))
+        destination += '.enc';
+    if (existsSync(destination))
+        throw new KnowzError('Refusing to overwrite an existing backup.', ExitCode.Usage);
+    if (!existsSync(dirname(destination)))
+        throw new KnowzError('Backup destination directory does not exist.', ExitCode.Usage);
+    input = {
+        ...input,
+        engine: await assertLocalEngineContext(runtime(input), {
+            runner: input.runner,
+            savedEngine: readSavedLocalEngine(input.paths.stateFile),
+        }),
+    };
+    const unlock = acquireRuntimeLock(input.paths.runtimeDir);
+    try {
+        const staging = createPrivateStaging(input.paths.runtimeDir);
+        const plain = join(staging, 'result.tar.gz');
+        let writers = [];
+        let startedDb = false;
+        let attemptedDump = false;
+        let result;
+        let failure;
+        try {
+            for (const dir of ['pg', 'volumes', 'runtime'])
+                ensurePrivateDirectory(join(staging, dir));
+            const status = await run(input, ['ps', '--services', '--status', 'running'], 'inspect runtime', true, secrets);
+            const running = (status.stdout ?? '').trim().split(/\s+/);
+            const enabledServices = [
+                'db',
+                'api',
+                'web',
+                ...(state.components?.mcp === false ? [] : ['mcp']),
+            ];
+            const observedImages = {};
+            for (const service of enabledServices) {
+                const listed = await run(input, ['ps', '--all', '--quiet', service], `inspect ${service} identity`, true, secrets);
+                const id = (listed.stdout ?? '').trim();
+                if (!id)
+                    continue;
+                if (!/^[a-f0-9]{12,64}$/.test(id))
+                    throw new KnowzError('Ambiguous container identity; backup refused.', ExitCode.Usage);
+                const inspected = await run(input, ['inspect', id, '--format', '{"id":{{json .Image}},"reference":{{json .Config.Image}}}'], `inspect ${service} image`, false, secrets);
+                try {
+                    const image = JSON.parse(inspected.stdout ?? '');
+                    if (typeof image.id !== 'string' ||
+                        !/^sha256:[a-f0-9]{64}$/.test(image.id) ||
+                        typeof image.reference !== 'string' ||
+                        !/^[A-Za-z0-9][A-Za-z0-9./:@_-]+$/.test(image.reference))
+                        throw new Error();
+                    observedImages[service] = { id: image.id, reference: image.reference };
+                }
+                catch {
+                    throw new KnowzError('Cannot validate observed container image metadata; backup refused.', ExitCode.Usage);
+                }
+            }
+            writers = running.filter((x) => ['api', 'mcp'].includes(x));
+            if (writers.length)
+                await run(input, ['stop', ...writers], 'pause writers for consistent snapshot', true, secrets);
+            await preserveLegacySelfHostedKeyring({
+                name: input.projectName,
+                paths: input.paths,
+                engine: input.engine,
+                runner: input.runner,
+            });
+            if (!running.includes('db')) {
+                startedDb = true;
+                await run(input, ['up', '--detach', '--wait', 'db'], 'start database', true, secrets);
+            }
+            attemptedDump = true;
+            await run(input, [
+                'exec',
+                '-T',
+                'db',
+                'pg_dump',
+                '-U',
+                'knowz',
+                '-Fc',
+                '-f',
+                '/tmp/knowz-backup.dump',
+                'knowz_selfhosted',
+            ], 'dump selfhosted PostgreSQL', true, secrets);
+            await run(input, ['cp', 'db:/tmp/knowz-backup.dump', join(staging, 'pg/knowz_selfhosted.dump')], 'copy logical dump', true, secrets);
+            await run(input, ['exec', '-T', 'db', 'rm', '-f', '/tmp/knowz-backup.dump'], 'remove container dump', true, secrets);
+            for (const volume of ['knowz-file-storage', 'knowz-protected-keys'])
+                await run(input, [
+                    'run',
+                    '--rm',
+                    '-v',
+                    `knowz-selfhosted-${input.projectName}_${volume}:/src:ro`,
+                    '-v',
+                    `${staging}:/out`,
+                    'alpine:3.21',
+                    'tar',
+                    '-czf',
+                    `/out/volumes/${volume}.tar.gz`,
+                    '-C',
+                    '/src',
+                    '.',
+                ], `snapshot ${volume}`, false, secrets);
+            writePrivateFile(join(staging, 'runtime/.env'), readFileSync(input.paths.envFile, 'utf8'));
+            writePrivateFile(join(staging, 'runtime/state.json'), readFileSync(input.paths.stateFile, 'utf8'));
+            const checksums = {};
+            const sizes = {};
+            for (const file of SELFHOSTED_BACKUP_ARTIFACTS) {
+                checksums[file] = await sha(join(staging, file));
+                sizes[file] = statSync(join(staging, file)).size;
+            }
+            const manifest = {
+                formatVersion: 2,
+                schemaVersion: 2,
+                edition: 'selfhosted',
+                database: {
+                    engine: 'postgres',
+                    version: '16',
+                    schemaVersion: 'unknown',
+                    schemaVersionSource: 'not-observed',
+                },
+                runtime: {
+                    release: state.version,
+                    imageDigests: metadata.digests,
+                    imageDigestSource: 'release-catalog',
+                    enabledServices,
+                    observedImages,
+                },
+                platformName: input.projectName,
+                createdAt: new Date().toISOString(),
+                cliVersion: input.cliVersion,
+                encrypted: input.encrypt,
+                keyMaterial: 'runtime secrets and protected provider keyring included',
+                checksums,
+                sizes,
+            };
+            writeFileSync(join(staging, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n', {
+                mode: 0o600,
+            });
+            await executeBackupSteps([
+                {
+                    kind: 'fs',
+                    description: 'create selfhosted archive',
+                    invocation: {
+                        command: 'tar',
+                        args: [
+                            '--format=ustar',
+                            '-czf',
+                            plain,
+                            '-C',
+                            staging,
+                            'manifest.json',
+                            ...SELFHOSTED_BACKUP_ARTIFACTS,
+                        ],
+                        options: { cwd: staging, shell: false, env: { COPYFILE_DISABLE: '1' } },
+                    },
+                },
+            ], input.runner, secrets);
+            protectPrivatePath(plain);
+            if (input.encrypt)
+                await encryptStream(plain, destination, input.passphrase);
+            else
+                finalizePrivateArchive(plain, destination);
+            result = { archive: destination, encrypted: input.encrypt, warning };
+        }
+        catch (error) {
+            failure = error;
+        }
+        finally {
+            if (attemptedDump) {
+                try {
+                    await run(input, ['exec', '-T', 'db', 'rm', '-f', '/tmp/knowz-backup.dump'], 'remove any partial database dump', true, secrets);
+                }
+                catch {
+                    /* Preserve primary failure; original service state still needs recovery. */
+                }
+            }
+            try {
+                if (startedDb)
+                    await run(input, ['stop', 'db'], 'restore original stopped database state', true, secrets);
+                if (writers.length)
+                    await run(input, ['start', ...writers], 'resume original runtime writers', true, secrets);
+            }
+            catch (error) {
+                failure ??= error;
+            }
+            rmSync(staging, { recursive: true, force: true });
+        }
+        if (failure)
+            throw failure;
+        input.emit?.(warning);
+        return result;
+    }
+    finally {
+        unlock();
+    }
+}
+export async function runSelfHostedRestore(input) {
+    if (!input.yes && !input.isTty)
+        throw new KnowzError('Refusing restore without --yes in a non-interactive session.', ExitCode.Usage);
+    return withRuntimeBackup(input, async (backup, extracted) => {
+        const manifest = backup.manifest;
+        const database = manifest.database;
+        const recorded = manifest.runtime;
+        if (backup.edition !== 'selfhosted' ||
+            database?.engine !== 'postgres' ||
+            database?.version !== '16' ||
+            !recorded?.release)
+            throw new KnowzError('Cross-edition or incompatible database restore refused.', ExitCode.Usage);
+        const metadata = release(recorded.release);
+        const state = JSON.parse(readFileSync(join(extracted, 'runtime/state.json'), 'utf8'));
+        if (state.edition !== 'selfhosted' || state.version !== recorded.release)
+            throw new KnowzError('Archive state does not match its release/edition manifest.', ExitCode.Usage);
+        for (const port of Object.values(state.ports ?? {}))
+            validatePort(port);
+        if (!state.ports?.api || !state.ports.web || !state.ports.mcp)
+            throw new KnowzError('Archive runtime ports are invalid.', ExitCode.Usage);
+        const archivedEnv = readFileSync(join(extracted, 'runtime/.env'), 'utf8');
+        const env = parseEnv(archivedEnv);
+        if (env.KNOWZ_SELFHOSTED_VERSION !== state.version)
+            throw new KnowzError('Archive environment version is inconsistent.', ExitCode.Usage);
+        const occupied = existsSync(input.paths.runtimeDir);
+        if (occupied && !input.replaceExisting)
+            throw new KnowzError('Restore target is occupied. Restore into a new --name or stop it and explicitly use --replace-installation.', ExitCode.Usage);
+        if (occupied && existsSync(input.paths.stateFile)) {
+            const previous = JSON.parse(readFileSync(input.paths.stateFile, 'utf8'));
+            if (previous.edition !== 'selfhosted' || previous.version !== state.version)
+                throw new KnowzError('Replacing a different edition or database release is refused. Restore to a fresh isolated --name; do not downgrade an occupied database.', ExitCode.Usage);
+        }
+        input = {
+            ...input,
+            engine: await assertLocalEngineContext(runtime(input), {
+                runner: input.runner,
+                savedEngine: readSavedLocalEngine(input.paths.stateFile),
+            }),
+        };
+        const active = await run(input, [
+            'ps',
+            '--filter',
+            `label=com.docker.compose.project=knowz-selfhosted-${input.projectName}`,
+            '--format',
+            '{{.Names}}',
+        ], 'inspect target containers', false);
+        if (active.stdout?.trim())
+            throw new KnowzError('Target runtime is running; run knowz down first.', ExitCode.Usage);
+        const volumes = await run(input, [
+            'volume',
+            'ls',
+            '--filter',
+            `label=com.docker.compose.project=knowz-selfhosted-${input.projectName}`,
+            '--format',
+            '{{.Name}}',
+        ], 'inspect existing target volumes', false);
+        if (volumes.stdout?.trim() && !input.replaceExisting)
+            throw new KnowzError('Target has occupied runtime volumes; choose a new name or use --replace-installation.', ExitCode.Usage);
+        if (!input.yes && (await input.confirmName?.()) !== input.projectName)
+            throw new KnowzError('Restore confirmation did not match the runtime name.', ExitCode.Usage);
+        const unlock = acquireRuntimeLock(input.paths.runtimeDir);
+        try {
+            if (!occupied && (existsSync(input.paths.stateFile) || existsSync(input.paths.envFile)))
+                throw new KnowzError('Restore target changed during validation; retry with a new name.', ExitCode.Usage);
+            if (existsSync(input.paths.stateFile)) {
+                const current = JSON.parse(readFileSync(input.paths.stateFile, 'utf8'));
+                if (current.edition !== 'selfhosted' || current.version !== state.version)
+                    throw new KnowzError('Target identity changed during restore validation.', ExitCode.Usage);
+            }
+            input = {
+                ...input,
+                engine: await assertLocalEngineContext(runtime(input), {
+                    runner: input.runner,
+                    savedEngine: readSavedLocalEngine(input.paths.stateFile),
+                }),
+            };
+            const activeUnderLease = await run(input, [
+                'ps',
+                '--filter',
+                `label=com.docker.compose.project=knowz-selfhosted-${input.projectName}`,
+                '--format',
+                '{{.Names}}',
+            ], 'recheck stopped target under restore lock', false);
+            if (activeUnderLease.stdout?.trim())
+                throw new KnowzError('Target runtime is now running; stop it and retry restore.', ExitCode.Usage);
+            const volumesUnderLease = await run(input, [
+                'volume',
+                'ls',
+                '--filter',
+                `label=com.docker.compose.project=knowz-selfhosted-${input.projectName}`,
+                '--format',
+                '{{.Name}}',
+            ], 'recheck target volumes under restore lock', false);
+            if (volumesUnderLease.stdout?.trim() && !input.replaceExisting)
+                throw new KnowzError('Target acquired volumes during restore validation; select a fresh target.', ExitCode.Usage);
+            // Only the packaged reviewed compose contract is executed. Archive compose files are never executed.
+            ensurePrivateDirectory(input.paths.runtimeDir);
+            writePrivateFile(input.paths.envFile, archivedEnv);
+            copyFileSync(join(resolvePackagedSelfHostedAssetsDir(), metadata.contract.runtime.composeAsset), input.paths.composeFile);
+            const secrets = Object.entries(env)
+                .filter(([key]) => /password|secret|key|token/i.test(key))
+                .map(([, value]) => value)
+                .filter(Boolean);
+            let started = false;
+            try {
+                if (input.replaceExisting)
+                    await run(input, ['down', '--volumes', '--remove-orphans'], 'remove explicitly selected stopped runtime', true, secrets);
+                await run(input, ['up', '--detach', '--wait', 'db'], 'start restore database', true, secrets);
+                started = true;
+                await run(input, ['cp', join(extracted, 'pg/knowz_selfhosted.dump'), 'db:/tmp/knowz-restore.dump'], 'copy restore dump', true, secrets);
+                await run(input, [
+                    'exec',
+                    '-T',
+                    'db',
+                    'pg_restore',
+                    '--exit-on-error',
+                    '--clean',
+                    '--if-exists',
+                    '--no-owner',
+                    '-U',
+                    'knowz',
+                    '-d',
+                    'knowz_selfhosted',
+                    '/tmp/knowz-restore.dump',
+                ], 'restore PostgreSQL', true, secrets);
+                await run(input, ['exec', '-T', 'db', 'rm', '-f', '/tmp/knowz-restore.dump'], 'remove restore dump', true, secrets);
+                for (const volume of ['knowz-file-storage', 'knowz-protected-keys'])
+                    await run(input, [
+                        'run',
+                        '--rm',
+                        '-v',
+                        `knowz-selfhosted-${input.projectName}_${volume}:/dst`,
+                        '-v',
+                        `${extracted}:/in:ro`,
+                        'alpine:3.21',
+                        'sh',
+                        '-c',
+                        `tar -xzf /in/volumes/${volume}.tar.gz --no-same-owner -C /dst && chown -R 1654:1654 /dst`,
+                    ], `restore ${volume}`, false, secrets);
+                writePrivateFile(input.paths.stateFile, JSON.stringify({
+                    ...state,
+                    name: input.projectName,
+                    engine: input.engine,
+                    healthPassed: false,
+                    restoredAt: new Date().toISOString(),
+                    updatedAt: new Date().toISOString(),
+                }, null, 2) + '\n');
+            }
+            finally {
+                if (started)
+                    await run(input, ['stop', 'db'], 'leave restored runtime stopped', true, secrets);
+            }
+            return {
+                edition: 'selfhosted',
+                version: state.version,
+                platformName: input.projectName,
+                integrityChecked: true,
+                healthPassed: false,
+                next: `knowz up --edition selfhosted --name ${input.projectName}`,
+                warning: 'Runtime restored and left stopped. Start it, verify login and file hashes, then verify provider readiness.',
+            };
+        }
+        finally {
+            unlock();
+        }
+    });
+}
+//# sourceMappingURL=selfhosted-backup.js.map