@knowzai/cli 0.1.0

package/dist/lib/platform-runtime.js

@@ -0,0 +1,866 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { randomBytes as cryptoRandomBytes } from 'node:crypto';
+import { accessSync, chmodSync, mkdirSync, writeFileSync, constants as fsConstants } from 'node:fs';
+import { homedir } from 'node:os';
+import { isIP } from 'node:net';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { validateCloudAiKeyFormat } from '@knowzai/core';
+import { assertPortableEmbeddingSupported } from './embedding-guard.js';
+import { KNOWZ_CLOUD_ENDPOINT, PLATFORM_PROVIDERS, PROVIDER_PRESETS, } from './provider-presets.js';
+export { PLATFORM_PROVIDERS } from './provider-presets.js';
+export const PLATFORM_STORAGE_MODES = ['minio', 'filesystem'];
+const PROJECT_NAME = /^[a-z0-9][a-z0-9_-]{0,62}$/;
+const RELEASE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const ENV_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const DEFAULT_PORTS = { api: 5000, web: 3000, mcp: 3001, publicSite: 3002 };
+const DEFAULT_EMBEDDING_DIMENSIONS = 1536;
+export const PLATFORM_SECRET_KEYS = [
+    'PG_PASSWORD',
+    'MINIO_ROOT_PASSWORD',
+    'MINIO_APP_SECRET_KEY',
+    'JWT_SECRET',
+    'ADMIN_PASSWORD',
+    'MCP_SERVICE_KEY',
+    'INTERNAL_API_KEY',
+    'SUPERADMIN_PASSPHRASE',
+];
+const MANAGED_PROVIDER_KEYS = [
+    'KNOWZ__CLOUDPROVIDER',
+    'KNOWZ__CLOUDPROVIDER__AI',
+    'KNOWZ__CLOUDPROVIDER__DOCINTELLIGENCE',
+    'KNOWZ__CLOUDPROVIDER__VISION',
+    'KNOWZ__CLOUDPROVIDER__TRANSCRIPTION',
+    '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_PROVIDER',
+    'EMBEDDING_MODEL_NAME',
+    'EMBEDDING_DIMENSIONS',
+];
+export function validateProjectName(name) {
+    if (!PROJECT_NAME.test(name)) {
+        throw new Error('Invalid platform project name. Use 1-63 lowercase letters, digits, hyphens, or underscores.');
+    }
+    return name;
+}
+export function validateVersion(version) {
+    if (!RELEASE_VERSION.test(version) || version.length > 80) {
+        throw new Error('Invalid platform version. Use a pinned SemVer such as 1.2.3 or 1.2.3-rc.1 (without v/latest/build metadata).');
+    }
+    return version;
+}
+export function validatePort(port, label = 'platform') {
+    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+        throw new Error(`Invalid ${label} port: expected an integer from 1 through 65535.`);
+    }
+    return port;
+}
+export function validateEmbeddingDimensions(dimensions) {
+    if (!Number.isInteger(dimensions) || dimensions < 1 || dimensions > 65_536) {
+        throw new Error('Invalid embedding dimension: expected an integer from 1 through 65536.');
+    }
+    return dimensions;
+}
+export function validateProviderPreset(provider) {
+    if (!PLATFORM_PROVIDERS.includes(provider)) {
+        throw new Error(`Invalid platform provider '${provider}'. Expected ${PLATFORM_PROVIDERS.join(', ')}.`);
+    }
+    return provider;
+}
+export function validateStorageMode(storage) {
+    if (!PLATFORM_STORAGE_MODES.includes(storage)) {
+        throw new Error('Invalid platform storage. Expected minio or filesystem.');
+    }
+    return storage;
+}
+function resolveStorageMode(storage, existingEnv) {
+    if (storage !== undefined)
+        return validateStorageMode(storage);
+    const existing = existingEnv.STORAGE_PROVIDER?.trim().toLowerCase();
+    if (!existing || existing === 'minio' || existing === 'minios3')
+        return 'minio';
+    if (existing === 'filesystem')
+        return 'filesystem';
+    throw new Error(`Invalid existing platform storage '${existingEnv.STORAGE_PROVIDER}'.`);
+}
+export function resolvePlatformPaths(name, configDir) {
+    const projectName = validateProjectName(name);
+    const root = resolve(configDir ?? process.env.KNOWZ_CONFIG_DIR ?? join(homedir(), '.knowz'));
+    const runtimeDir = join(root, 'platform', projectName);
+    return {
+        runtimeDir,
+        composeFile: join(runtimeDir, 'docker-compose.yml'),
+        envFile: join(runtimeDir, '.env'),
+        stateFile: join(runtimeDir, 'state.json'),
+        postgresInitDir: join(runtimeDir, 'postgres-initdb'),
+    };
+}
+function parseAxis(value, allowNone, label) {
+    const normalized = value.trim().toLowerCase();
+    const axis = normalized === 'azure'
+        ? 'Azure'
+        : normalized === 'gcp'
+            ? 'Gcp'
+            : normalized === 'openaicompat' || normalized === 'openai-compatible' || normalized === 'openai-compat'
+                ? 'OpenAiCompat'
+                : normalized === 'none' || normalized === 'off'
+                    ? 'None'
+                    : undefined;
+    if (!axis || (!allowNone && axis === 'None')) {
+        throw new Error(`Invalid ${label} provider axis '${value}'.`);
+    }
+    return axis;
+}
+function defaultAxes(provider) {
+    return { ...PROVIDER_PRESETS[provider].defaultAxes };
+}
+function resolveAxes(provider, overrides) {
+    const axes = defaultAxes(provider);
+    if (overrides?.ai !== undefined)
+        axes.ai = parseAxis(overrides.ai, false, 'AI');
+    if (overrides?.docIntelligence !== undefined) {
+        axes.docIntelligence = parseAxis(overrides.docIntelligence, true, 'document intelligence');
+    }
+    if (overrides?.vision !== undefined)
+        axes.vision = parseAxis(overrides.vision, true, 'vision');
+    if (overrides?.transcription !== undefined) {
+        axes.transcription = parseAxis(overrides.transcription, true, 'transcription');
+    }
+    return axes;
+}
+function present(value) {
+    return value !== undefined && value.trim().length > 0;
+}
+function envOr(value, env, key) {
+    return value !== undefined ? value.trim() : env[key]?.trim();
+}
+function numberOr(value, env, key) {
+    if (value !== undefined)
+        return value;
+    const raw = env[key];
+    if (!present(raw))
+        return undefined;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : Number.NaN;
+}
+function defaultPathReadable(path) {
+    try {
+        accessSync(path, fsConstants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function validateHttpsEndpoint(endpoint, label) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new Error(`${label} endpoint must be an absolute URL.`);
+    }
+    if (url.protocol !== 'https:')
+        throw new Error(`${label} endpoint must use HTTPS.`);
+    if (isLinkLocalOrMetadataHost(url.hostname)) {
+        throw new Error(`${label} endpoint must not use a link-local or metadata host.`);
+    }
+    if (url.username || url.password)
+        throw new Error(`${label} endpoint must not contain credentials.`);
+    if (url.search || url.hash)
+        throw new Error(`${label} endpoint must not contain a query or fragment.`);
+    return url;
+}
+export function validateOpenAiCompatibleEndpoint(endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new Error('OpenAI-compatible endpoint must be an absolute HTTP(S) URL.');
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error('OpenAI-compatible endpoint must use HTTP or HTTPS.');
+    }
+    const host = url.hostname.toLowerCase();
+    if (isLinkLocalOrMetadataHost(host)) {
+        throw new Error('OpenAI-compatible endpoint must not use a link-local or metadata host.');
+    }
+    const localPlaintext = host === 'localhost' ||
+        host.endsWith('.localhost') ||
+        host === 'host.docker.internal' ||
+        (isIP(host) === 4 && host.startsWith('127.')) ||
+        host === '[::1]' ||
+        host === '::1';
+    if (url.protocol === 'http:' && !localPlaintext) {
+        throw new Error('Remote plaintext OpenAI-compatible endpoints are forbidden; use HTTPS or a loopback/localhost endpoint.');
+    }
+    if (url.username || url.password)
+        throw new Error('OpenAI-compatible endpoint must not contain credentials.');
+    if (url.search || url.hash)
+        throw new Error('OpenAI-compatible endpoint must not contain a query or fragment.');
+    return url;
+}
+function usesProvider(axes, provider) {
+    return Object.values(axes).includes(provider);
+}
+function resolvePorts(input) {
+    const ports = {
+        api: validatePort(input?.api ?? DEFAULT_PORTS.api, 'API'),
+        web: validatePort(input?.web ?? DEFAULT_PORTS.web, 'web'),
+        mcp: validatePort(input?.mcp ?? DEFAULT_PORTS.mcp, 'MCP'),
+        publicSite: validatePort(input?.publicSite ?? DEFAULT_PORTS.publicSite, 'public site'),
+    };
+    if (new Set(Object.values(ports)).size !== Object.values(ports).length) {
+        throw new Error('Platform public ports must be unique.');
+    }
+    return ports;
+}
+function isIpv4LinkLocal(host) {
+    if (isIP(host) !== 4)
+        return false;
+    const [first, second] = host.split('.').map(Number);
+    return first === 169 && second === 254;
+}
+function mappedIpv4Host(host) {
+    const prefix = '::ffff:';
+    if (!host.startsWith(prefix))
+        return undefined;
+    const suffix = host.slice(prefix.length);
+    if (isIP(suffix) === 4)
+        return suffix;
+    const match = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(suffix);
+    if (!match)
+        return undefined;
+    const upper = Number.parseInt(match[1], 16);
+    const lower = Number.parseInt(match[2], 16);
+    return `${upper >>> 8}.${upper & 0xff}.${lower >>> 8}.${lower & 0xff}`;
+}
+function isLinkLocalOrMetadataHost(hostname) {
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    if (host === 'metadata.google.internal' || host.endsWith('.metadata.google.internal') ||
+        host === 'metadata.goog' || host.endsWith('.metadata.goog'))
+        return true;
+    if (isIpv4LinkLocal(host))
+        return true;
+    if (isIP(host) === 6) {
+        const mappedHost = mappedIpv4Host(host);
+        if (mappedHost && isIpv4LinkLocal(mappedHost))
+            return true;
+        const firstHextet = Number.parseInt(host.split(':')[0] ?? '', 16);
+        if (Number.isFinite(firstHextet) && (firstHextet & 0xffc0) === 0xfe80)
+            return true;
+    }
+    return false;
+}
+export function validatePublicUrl(value, label, originOnly = false) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`${label} must be an absolute HTTP(S) URL.`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`${label} must use HTTP or HTTPS.`);
+    }
+    const host = url.hostname.toLowerCase();
+    if (isLinkLocalOrMetadataHost(host))
+        throw new Error(`${label} must not use a link-local or metadata host.`);
+    const local = host === 'localhost' || host.endsWith('.localhost') || (isIP(host) === 4 && host.startsWith('127.'));
+    if (url.protocol === 'http:' && !local)
+        throw new Error(`${label} must use HTTPS for a non-local host.`);
+    if (url.username || url.password)
+        throw new Error(`${label} must not contain credentials.`);
+    if (url.search || url.hash)
+        throw new Error(`${label} must not contain a query or fragment.`);
+    if (originOnly && url.pathname !== '/') {
+        throw new Error(`${label} must be an origin without a path.`);
+    }
+    return value.replace(/\/$/, '');
+}
+function resolvePublicUrls(input, ports) {
+    return {
+        api: validatePublicUrl(input?.api ?? `http://localhost:${ports.api}`, 'Public API URL'),
+        web: validatePublicUrl(input?.web ?? `http://localhost:${ports.web}`, 'Public web origin', true),
+        mcp: validatePublicUrl(input?.mcp ?? `http://localhost:${ports.mcp}`, 'Public MCP URL'),
+        publicSite: validatePublicUrl(input?.publicSite ?? `http://localhost:${ports.publicSite}`, 'Public site origin', true),
+    };
+}
+export function buildPlatformPlan(input, dependencies = {}) {
+    const name = validateProjectName(input.name);
+    const version = validateVersion(input.version);
+    const provider = validateProviderPreset(input.provider);
+    const preset = PROVIDER_PRESETS[provider];
+    const storage = resolveStorageMode(input.storage, input.existingEnv ?? {});
+    const axes = resolveAxes(provider, input.axes);
+    const ports = resolvePorts(input.ports);
+    const publicUrls = resolvePublicUrls(input.publicUrls, ports);
+    const components = {
+        mcp: input.components?.mcp ?? true,
+        publicSite: input.components?.publicSite ?? false,
+    };
+    const existing = input.existingEnv ?? {};
+    const explicitOpenAi = Object.fromEntries(Object.entries(input.openAiCompatible ?? {}).filter(([, value]) => value !== undefined));
+    const openAiCompatible = preset.optionsFamily === 'openAiCompatible'
+        ? { ...(preset.prefill ?? {}), ...explicitOpenAi }
+        : explicitOpenAi;
+    if (provider === 'knowz-cloud' &&
+        input.openAiCompatible?.endpoint !== undefined &&
+        input.openAiCompatible.endpoint.trim().replace(/\/$/, '') !== KNOWZ_CLOUD_ENDPOINT) {
+        throw new Error(`Knowz Cloud endpoint is locked to ${KNOWZ_CLOUD_ENDPOINT}.`);
+    }
+    const providerEnv = {
+        KNOWZ__CLOUDPROVIDER: preset.masterProvider,
+        KNOWZ__CLOUDPROVIDER__DOCINTELLIGENCE: axes.docIntelligence,
+        KNOWZ__CLOUDPROVIDER__VISION: axes.vision,
+        KNOWZ__CLOUDPROVIDER__TRANSCRIPTION: axes.transcription,
+    };
+    if (axes.ai !== undefined)
+        providerEnv.KNOWZ__CLOUDPROVIDER__AI = axes.ai;
+    const openAiDimensions = numberOr(openAiCompatible.embeddingDimensions, existing, 'OPENAICOMPAT__EMBEDDINGDIMENSIONS');
+    const gcpDimensions = numberOr(input.gcp?.embeddingDimensions, existing, 'VERTEX__EMBEDDINGDIMENSIONS');
+    const azureDimensions = input.azure?.embeddingDimensions;
+    const globalFromEnv = numberOr(undefined, existing, 'EMBEDDING_DIMENSIONS');
+    const selectedDimensions = input.embeddingDimensions ??
+        (axes.ai === 'OpenAiCompat'
+            ? openAiDimensions
+            : axes.ai === 'Gcp'
+                ? gcpDimensions
+                : axes.ai === 'Azure'
+                    ? azureDimensions
+                    : undefined) ??
+        globalFromEnv ??
+        DEFAULT_EMBEDDING_DIMENSIONS;
+    const embeddingDimensions = validateEmbeddingDimensions(selectedDimensions);
+    if (usesProvider(axes, 'Azure')) {
+        const endpoint = envOr(input.azure?.endpoint, existing, 'AZURE_OPENAI_ENDPOINT');
+        const apiKey = envOr(input.azure?.apiKey, existing, 'AZURE_OPENAI_API_KEY');
+        if (!present(endpoint))
+            throw new Error('Azure provider requires an Azure OpenAI endpoint.');
+        validateHttpsEndpoint(endpoint, 'Azure OpenAI');
+        if (!present(apiKey))
+            throw new Error('Azure provider requires an Azure OpenAI API key.');
+        providerEnv.AZURE_OPENAI_ENDPOINT = normalizeAzureOpenAiEndpoint(endpoint);
+        providerEnv.AZURE_OPENAI_API_KEY = apiKey;
+    }
+    if (usesProvider(axes, 'Gcp')) {
+        const project = envOr(input.gcp?.project, existing, 'VERTEX__PROJECT');
+        const region = envOr(input.gcp?.region, existing, 'VERTEX__REGION') ?? 'us-central1';
+        const adcPath = envOr(input.gcp?.adcPath, existing, 'GCLOUD_ADC_PATH');
+        if (!present(project))
+            throw new Error('GCP provider requires a Vertex project.');
+        if (!present(adcPath) || !isAbsolute(adcPath)) {
+            throw new Error('GCP provider requires an absolute, readable ADC path.');
+        }
+        if (!(dependencies.pathReadable ?? defaultPathReadable)(adcPath)) {
+            throw new Error('GCP ADC path is not readable.');
+        }
+        if (axes.ai === 'Gcp' &&
+            gcpDimensions !== undefined &&
+            validateEmbeddingDimensions(gcpDimensions) !== embeddingDimensions) {
+            throw new Error('Vertex and global embedding dimensions must be equal.');
+        }
+        providerEnv.GCLOUD_ADC_PATH = adcPath;
+        providerEnv.VERTEX__PROJECT = project;
+        providerEnv.VERTEX__REGION = region;
+        providerEnv.VERTEX__EMBEDDINGDIMENSIONS = String(embeddingDimensions);
+        const chatModel = envOr(input.gcp?.chatModel, existing, 'VERTEX__CHATMODEL');
+        const embeddingModel = envOr(input.gcp?.embeddingModel, existing, 'VERTEX__EMBEDDINGMODEL');
+        if (present(chatModel))
+            providerEnv.VERTEX__CHATMODEL = chatModel;
+        if (present(embeddingModel))
+            providerEnv.VERTEX__EMBEDDINGMODEL = embeddingModel;
+    }
+    if (usesProvider(axes, 'OpenAiCompat')) {
+        const endpoint = provider === 'knowz-cloud'
+            ? KNOWZ_CLOUD_ENDPOINT
+            : envOr(openAiCompatible.endpoint, existing, 'OPENAICOMPAT__ENDPOINT');
+        const apiKey = envOr(openAiCompatible.apiKey, existing, 'OPENAICOMPAT__APIKEY');
+        const chatModel = envOr(openAiCompatible.chatModel, existing, 'OPENAICOMPAT__CHATMODEL');
+        const embeddingModel = envOr(openAiCompatible.embeddingModel, existing, 'OPENAICOMPAT__EMBEDDINGMODEL');
+        if (!present(endpoint))
+            throw new Error('OpenAI-compatible provider requires an endpoint.');
+        validateOpenAiCompatibleEndpoint(endpoint);
+        if (provider === 'knowz-cloud') {
+            if (!present(apiKey)) {
+                throw new Error('Knowz Cloud requires an AI key. Run `knowz activate --scope cloud-ai` for this platform.');
+            }
+            if (!validateCloudAiKeyFormat(apiKey).ok) {
+                throw new Error('Knowz Cloud requires a valid kzai_ AI credential. Run `knowz activate --scope cloud-ai`.');
+            }
+        }
+        if (axes.ai === 'OpenAiCompat') {
+            if (!present(chatModel))
+                throw new Error('OpenAI-compatible provider requires a chat model.');
+            if (!present(embeddingModel))
+                throw new Error('OpenAI-compatible provider requires an embedding model.');
+            if (openAiDimensions === undefined) {
+                throw new Error('OpenAI-compatible provider requires embedding dimensions.');
+            }
+            if (validateEmbeddingDimensions(openAiDimensions) !== embeddingDimensions) {
+                throw new Error('OpenAI-compatible and global embedding dimensions must be equal.');
+            }
+        }
+        providerEnv.OPENAICOMPAT__ENDPOINT = endpoint;
+        providerEnv.OPENAICOMPAT__APIKEY = apiKey ?? '';
+        if (present(chatModel))
+            providerEnv.OPENAICOMPAT__CHATMODEL = chatModel;
+        if (present(embeddingModel))
+            providerEnv.OPENAICOMPAT__EMBEDDINGMODEL = embeddingModel;
+        if (axes.ai === 'OpenAiCompat') {
+            providerEnv.OPENAICOMPAT__EMBEDDINGDIMENSIONS = String(embeddingDimensions);
+        }
+    }
+    const imageFlavor = usesProvider(axes, 'Gcp') ? '-gcp' : '';
+    if (input.requestedFlavor !== undefined && input.requestedFlavor !== imageFlavor) {
+        throw new Error(`Requested image flavor '${input.requestedFlavor || '(default)'}' conflicts with provider axes.`);
+    }
+    providerEnv.EMBEDDING_DIMENSIONS = String(embeddingDimensions);
+    if (axes.ai === 'OpenAiCompat') {
+        providerEnv.EMBEDDING_PROVIDER = 'OpenAiCompat';
+        providerEnv.EMBEDDING_MODEL_NAME = providerEnv.OPENAICOMPAT__EMBEDDINGMODEL ?? '';
+    }
+    else if (axes.ai === 'Gcp') {
+        providerEnv.EMBEDDING_PROVIDER = 'Vertex';
+        providerEnv.EMBEDDING_MODEL_NAME = providerEnv.VERTEX__EMBEDDINGMODEL ?? 'google/gemini-embedding-001';
+    }
+    else if (axes.ai === 'Azure') {
+        providerEnv.EMBEDDING_PROVIDER = 'AzureOpenAI';
+        providerEnv.EMBEDDING_MODEL_NAME = input.azure?.embeddingModel ?? existing.EMBEDDING_MODEL_NAME ?? 'text-embedding-3-small';
+    }
+    else {
+        providerEnv.EMBEDDING_PROVIDER = 'Stub';
+        providerEnv.EMBEDDING_MODEL_NAME = 'text-embedding-3-small';
+    }
+    // Fail-fast BEFORE any boot when a portable Azure embedding model would produce vectors that
+    // don't match the pgvector column dimension (the transport never truncates). Both the CLI-flag
+    // path and the --ui setup plan flow through here. See FEAT_PortableEmbeddingGuardrails.
+    assertPortableEmbeddingSupported({
+        aiProvider: axes.ai,
+        model: providerEnv.EMBEDDING_MODEL_NAME,
+        dimensions: embeddingDimensions,
+    });
+    return {
+        name,
+        version,
+        provider,
+        storage,
+        imageFlavor,
+        axes,
+        ports,
+        publicUrls,
+        components,
+        embeddingDimensions,
+        paths: resolvePlatformPaths(name, input.configDir),
+        providerEnv,
+    };
+}
+export function parseEnv(contents) {
+    const env = {};
+    for (const rawLine of contents.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const assignment = line.startsWith('export ') ? line.slice(7).trim() : line;
+        const separator = assignment.indexOf('=');
+        if (separator < 1)
+            continue;
+        const key = assignment.slice(0, separator).trim();
+        if (!ENV_KEY.test(key))
+            continue;
+        const rawValue = assignment.slice(separator + 1).trim();
+        if (rawValue.length >= 2 &&
+            ((rawValue.startsWith('"') && rawValue.endsWith('"')) ||
+                (rawValue.startsWith("'") && rawValue.endsWith("'")))) {
+            const unquoted = rawValue.slice(1, -1);
+            env[key] = rawValue.startsWith('"')
+                ? unquoted.replace(/\\n/g, '\n').replace(/\\r/g, '\r').replace(/\\"/g, '"').replace(/\\\\/g, '\\')
+                : unquoted;
+        }
+        else {
+            env[key] = rawValue;
+        }
+    }
+    return env;
+}
+function renderEnvValue(value) {
+    if (/^[A-Za-z0-9_./:@+-]*$/.test(value))
+        return value;
+    return JSON.stringify(value);
+}
+export function renderEnv(env) {
+    return `${Object.keys(env)
+        .sort((left, right) => left.localeCompare(right))
+        .map((key) => `${key}=${renderEnvValue(env[key] ?? '')}`)
+        .join('\n')}\n`;
+}
+function isMissingSecret(value) {
+    return !present(value) || /^<CHANGE_ME/i.test(value);
+}
+function generateSecret(randomBytes) {
+    return Buffer.from(randomBytes(32)).toString('base64url');
+}
+const ADMIN_UPPER = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+const ADMIN_LOWER = 'abcdefghijklmnopqrstuvwxyz';
+const ADMIN_DIGITS = '0123456789';
+const ADMIN_SPECIAL = '-_';
+/**
+ * Mint a dotenv/Compose-safe password that always satisfies the platform's
+ * IsPasswordStrong policy. Rejection sampling avoids modulo bias while the
+ * injectable byte source keeps the policy property directly testable.
+ */
+export function generateAdminPassword(randomBytes = cryptoRandomBytes) {
+    const base = Buffer.from(randomBytes(12)).toString('base64url');
+    let pool = new Uint8Array();
+    let cursor = 0;
+    const uniformIndex = (upperExclusive) => {
+        const acceptedRange = 256 - (256 % upperExclusive);
+        while (true) {
+            if (cursor >= pool.length) {
+                pool = randomBytes(64);
+                cursor = 0;
+                if (pool.length === 0)
+                    throw new Error('Random byte source returned no data.');
+            }
+            const value = pool[cursor++];
+            if (value < acceptedRange)
+                return value % upperExclusive;
+        }
+    };
+    const pick = (alphabet) => alphabet[uniformIndex(alphabet.length)];
+    const chars = [
+        pick(ADMIN_UPPER),
+        pick(ADMIN_LOWER),
+        pick(ADMIN_DIGITS),
+        pick(ADMIN_SPECIAL),
+        ...base,
+    ];
+    for (let index = chars.length - 1; index > 0; index -= 1) {
+        const swap = uniformIndex(index + 1);
+        [chars[index], chars[swap]] = [chars[swap], chars[index]];
+    }
+    return chars.join('');
+}
+export function buildPlatformEnvironment(plan, existingEnv = {}, dependencies = {}) {
+    const env = { ...existingEnv };
+    for (const key of MANAGED_PROVIDER_KEYS)
+        delete env[key];
+    Object.assign(env, plan.providerEnv, {
+        KNOWZ_VERSION: plan.version,
+        KNOWZ_FLAVOR: plan.imageFlavor,
+        API_PORT: String(plan.ports.api),
+        WEB_PORT: String(plan.ports.web),
+        MCP_PORT: String(plan.ports.mcp),
+        PUBLIC_SITE_PORT: String(plan.ports.publicSite),
+        PUBLIC_API_URL: plan.publicUrls.api,
+        PUBLIC_WEB_ORIGIN: plan.publicUrls.web,
+        PUBLIC_MCP_URL: plan.publicUrls.mcp,
+        PUBLIC_SITE_URL: plan.publicUrls.publicSite,
+        KNOWZ_COMPONENTS: [
+            ...(plan.components.mcp ? ['mcp'] : []),
+            ...(plan.components.publicSite ? ['public-site'] : []),
+        ].join(','),
+        PG_USER: env.PG_USER || 'knowz',
+        MINIO_ROOT_USER: env.MINIO_ROOT_USER || 'knowzminio',
+        MINIO_APP_ACCESS_KEY: env.MINIO_APP_ACCESS_KEY || 'knowzapp',
+        MINIO_BUCKET: env.MINIO_BUCKET || 'knowz-portable',
+        ADMIN_USERNAME: env.ADMIN_USERNAME || 'admin@knowz.local',
+        STORAGE_PROVIDER: plan.storage === 'filesystem' ? 'FileSystem' : 'MinioS3',
+    });
+    if (dependencies.orgName?.trim())
+        env.PLATFORM_ORG_NAME = dependencies.orgName.trim();
+    if (dependencies.superAdminPassphrase)
+        env.SUPERADMIN_PASSPHRASE = dependencies.superAdminPassphrase;
+    const randomBytes = dependencies.randomBytes ?? cryptoRandomBytes;
+    for (const key of PLATFORM_SECRET_KEYS) {
+        if (isMissingSecret(env[key])) {
+            env[key] = key === 'ADMIN_PASSWORD'
+                ? generateAdminPassword(randomBytes)
+                : generateSecret(randomBytes);
+        }
+    }
+    return env;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Redacts exact known values first, then common key/value secret assignments. */
+export function redactPlatformSecrets(text, knownSecrets = []) {
+    let redacted = text;
+    for (const secret of [...knownSecrets].filter((value) => value.length >= 4).sort((a, b) => b.length - a.length)) {
+        redacted = redacted.replace(new RegExp(escapeRegExp(secret), 'g'), '[REDACTED]');
+    }
+    return redacted.replace(/\b(api[_-]?key|token|password|passwd|pwd|secret|credential|passphrase)\s*[:=]\s*["']?[^\s,"']{8,}["']?/gi, (_match, key) => `${key}=[REDACTED]`);
+}
+export function createPlatformState(plan, now = () => new Date()) {
+    return {
+        schemaVersion: 1,
+        name: plan.name,
+        version: plan.version,
+        provider: plan.provider,
+        storage: plan.storage,
+        imageFlavor: plan.imageFlavor,
+        axes: { ...plan.axes },
+        ports: { ...plan.ports },
+        serviceUrls: { ...plan.publicUrls },
+        components: { ...plan.components },
+        imageMode: 'pull',
+        updatedAt: now().toISOString(),
+    };
+}
+export function serializePlatformState(state) {
+    const json = JSON.stringify(state, null, 2);
+    if (/"[^"]*(?:apiKey|password|secret|token|credential|passphrase|pgDsn)[^"]*"\s*:/i.test(json)) {
+        throw new Error('Refusing to serialize secret-bearing platform state.');
+    }
+    return `${json}\n`;
+}
+export function writePrivateFile(filePath, contents) {
+    mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+    writeFileSync(filePath, contents, { encoding: 'utf8', mode: 0o600 });
+    chmodSync(filePath, 0o600);
+}
+function composeInvocation(paths, projectName, actionArgs, override = {}, engine) {
+    if (engine?.engine === 'none') {
+        throw new Error('No container engine is available. Install Docker Desktop or Podman Desktop, then retry.');
+    }
+    if (engine && !engine.composeFront) {
+        throw new Error('Install the Docker Compose v2 plugin or standalone `docker-compose` binary (https://docs.docker.com/compose/install/), then retry.');
+    }
+    const front = engine?.composeFront ?? { command: 'docker', baseArgs: ['compose'] };
+    const profiles = override.profiles ?? [];
+    return {
+        command: front.command,
+        args: [
+            ...front.baseArgs,
+            '--project-name',
+            validateProjectName(projectName),
+            '--file',
+            override.composeFile ?? paths.composeFile,
+            ...profiles.flatMap((profile) => ['--profile', profile]),
+            '--env-file',
+            paths.envFile,
+            ...actionArgs,
+        ],
+        options: {
+            cwd: override.projectDir ?? paths.runtimeDir,
+            shell: false,
+            ...(front.env ? { env: { ...front.env } } : {}),
+        },
+    };
+}
+export function planComposeInvocations(action, paths, projectName, options = {}) {
+    switch (action) {
+        case 'up':
+        case 'upgrade': {
+            const override = {
+                composeFile: options.composeFile,
+                projectDir: options.projectDir,
+                profiles: options.profiles ?? ['mcp'],
+            };
+            const composePlan = options.composePlan ?? 'config-pull-up';
+            const acquisition = composePlan === 'config-build-up'
+                ? 'build'
+                : composePlan === 'config-pull-up'
+                    ? 'pull'
+                    : undefined;
+            return [
+                composeInvocation(paths, projectName, ['config'], override, options.engine),
+                ...(acquisition
+                    ? [composeInvocation(paths, projectName, [acquisition], override, options.engine)]
+                    : []),
+                composeInvocation(paths, projectName, ['up', '--detach', '--remove-orphans', '--wait'], override, options.engine),
+            ];
+        }
+        case 'status':
+            return [composeInvocation(paths, projectName, ['ps', '--all', '--format', 'json'], {
+                    profiles: options.profiles,
+                }, options.engine)];
+        case 'doctor':
+            return [
+                composeInvocation(paths, projectName, ['config'], { profiles: options.profiles }, options.engine),
+                composeInvocation(paths, projectName, ['ps', '--all', '--format', 'json'], {
+                    profiles: options.profiles,
+                }, options.engine),
+            ];
+        case 'logs': {
+            const tail = options.tail ?? 100;
+            if (!Number.isInteger(tail) || tail < 0 || tail > 100_000)
+                throw new Error('Invalid Compose log tail count.');
+            return [
+                composeInvocation(paths, projectName, [
+                    'logs',
+                    '--tail',
+                    String(tail),
+                    ...(options.follow ? ['--follow'] : []),
+                ], { profiles: options.profiles }, options.engine),
+            ];
+        }
+        case 'down':
+            return [composeInvocation(paths, projectName, ['down', '--remove-orphans'], {}, options.engine)];
+        case 'destroy':
+            if (!options.confirmed)
+                throw new Error('Destroy requires explicit confirmation with --yes.');
+            return [composeInvocation(paths, projectName, ['down', '--volumes', '--remove-orphans'], {}, options.engine)];
+    }
+}
+export const nodeProcessRunner = (command, args, options) => {
+    const hasInput = options.input !== undefined;
+    const result = spawnSync(command, [...args], {
+        cwd: options.cwd,
+        shell: false,
+        encoding: 'utf8',
+        input: options.input,
+        env: options.env ? { ...process.env, ...options.env } : undefined,
+        stdio: hasInput ? ['pipe', 'pipe', 'pipe'] : ['inherit', 'pipe', 'pipe'],
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        error: result.error,
+    };
+};
+export const nodeAsyncProcessRunner = (command, args, options) => new Promise((resolveResult) => {
+    const hasInput = options.input !== undefined;
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const settle = (result) => {
+        if (settled)
+            return;
+        settled = true;
+        resolveResult(result);
+    };
+    try {
+        const child = spawn(command, [...args], {
+            cwd: options.cwd,
+            shell: false,
+            env: options.env ? { ...process.env, ...options.env } : undefined,
+            stdio: hasInput ? ['pipe', 'pipe', 'pipe'] : ['inherit', 'pipe', 'pipe'],
+        });
+        child.stdout?.setEncoding('utf8');
+        child.stderr?.setEncoding('utf8');
+        child.stdout?.on('data', (chunk) => { stdout += chunk; });
+        child.stderr?.on('data', (chunk) => { stderr += chunk; });
+        child.once('error', (error) => settle({ status: null, stdout, stderr, error }));
+        child.once('close', (status) => settle({ status, stdout, stderr }));
+        if (hasInput)
+            child.stdin?.end(options.input);
+    }
+    catch (error) {
+        settle({ status: null, stdout, stderr, error: error });
+    }
+});
+export const ARM64_RETRY_NOTICE = 'ℹ  No native arm64 image for this version yet — running under amd64 emulation (normal on Apple Silicon, just a little slower).\n';
+export const ARM64_RETRY_EXPECTATION = '⏳ Pulling images and starting services — the first run can take a minute or two.\n';
+export function shouldRetryWithAmd64(result) {
+    return Boolean((result.error || result.status !== 0) &&
+        /no matching manifest for linux\/arm64/i.test(result.stderr ?? result.stdout ?? ''));
+}
+export function composeFailureError(result, knownSecrets) {
+    const detail = result.stderr || result.stdout || result.error?.message || `exit status ${String(result.status)}`;
+    const missingVar = /required variable (\w+) is missing a value/i.exec(detail)?.[1];
+    if (missingVar) {
+        return new Error(`The portable stack needs an auto-generated secret (${missingVar}) that isn't in your .env yet. ` +
+            `Re-run this command — the CLI generates any missing secret before starting. ` +
+            `If it keeps failing, your global 'knowz' is from an older build: rebuild it (in cli/: 'pnpm -r build') or reinstall the CLI, then retry.`);
+    }
+    return new Error(`Docker Compose failed: ${redactPlatformSecrets(detail.trim(), knownSecrets)}`);
+}
+function isPodmanInvocation(invocation) {
+    return invocation.command === 'podman' || invocation.options.env?.DOCKER_HOST !== undefined;
+}
+function invocationFailureError(invocation, result, knownSecrets, retriedForAmd64) {
+    const failure = composeFailureError(result, knownSecrets);
+    if (!retriedForAmd64 || !isPodmanInvocation(invocation))
+        return failure;
+    return new Error('Podman amd64 emulation may require machine-level configuration. On Apple Silicon, try ' +
+        '`podman machine set --rosetta` (or re-initialize the machine); see FEAT_PodmanEmulationConfig. ' +
+        failure.message);
+}
+export function executeComposeInvocations(invocations, runner = nodeProcessRunner, knownSecrets = []) {
+    const results = [];
+    for (const invocation of invocations) {
+        let retriedForAmd64 = false;
+        let result = runner(invocation.command, invocation.args, { ...invocation.options, shell: false });
+        if (shouldRetryWithAmd64(result)) {
+            retriedForAmd64 = true;
+            // Release images may be published amd64-only; on ARM hosts Docker refuses
+            // them outright. Retry once forcing amd64 so Docker Desktop runs them under
+            // Rosetta/QEMU emulation. Harmless once multi-arch images ship (the native
+            // pull succeeds and this branch never runs).
+            process.stderr.write(ARM64_RETRY_NOTICE + ARM64_RETRY_EXPECTATION);
+            result = runner(invocation.command, invocation.args, {
+                ...invocation.options,
+                shell: false,
+                env: { ...invocation.options.env, DOCKER_DEFAULT_PLATFORM: 'linux/amd64' },
+            });
+        }
+        results.push(result);
+        if (result.error || result.status !== 0) {
+            throw invocationFailureError(invocation, result, knownSecrets, retriedForAmd64);
+        }
+    }
+    return results;
+}
+export async function executeComposeInvocationsAsync(invocations, runner = nodeAsyncProcessRunner, knownSecrets = [], wrapStep) {
+    const results = [];
+    for (const invocation of invocations) {
+        let retriedForAmd64 = false;
+        const run = async () => {
+            let result = await Promise.resolve(runner(invocation.command, invocation.args, { ...invocation.options, shell: false }));
+            if (shouldRetryWithAmd64(result)) {
+                retriedForAmd64 = true;
+                process.stderr.write(ARM64_RETRY_NOTICE);
+                result = await Promise.resolve(runner(invocation.command, invocation.args, {
+                    ...invocation.options,
+                    shell: false,
+                    env: { ...invocation.options.env, DOCKER_DEFAULT_PLATFORM: 'linux/amd64' },
+                }));
+            }
+            return result;
+        };
+        const result = wrapStep ? await wrapStep(invocation, run) : await run();
+        results.push(result);
+        if (result.error || result.status !== 0) {
+            throw invocationFailureError(invocation, result, knownSecrets, retriedForAmd64);
+        }
+    }
+    return results;
+}
+/**
+ * Azure portals hand out several endpoint spellings for the same resource —
+ * the base form, and the newer v1-surface forms ending in /openai/v1 or /v1.
+ * The portable runtime and probes append their own /openai/deployments/...
+ * paths, so those suffixes must be stripped or every call 404s. Only known
+ * Azure OpenAI hosts are normalized; custom gateways keep their paths.
+ */
+export function normalizeAzureOpenAiEndpoint(endpoint) {
+    try {
+        const url = new URL(endpoint);
+        const host = url.hostname.toLowerCase();
+        if (!host.endsWith('.openai.azure.com') && !host.endsWith('.cognitiveservices.azure.com'))
+            return endpoint;
+        const path = url.pathname.replace(/\/+$/, '');
+        if (path === '' || path === '/openai' || path === '/openai/v1' || path === '/v1') {
+            return url.origin;
+        }
+        return endpoint;
+    }
+    catch {
+        return endpoint;
+    }
+}
+//# sourceMappingURL=platform-runtime.js.map