@vectle/cli 1.0.0 → 1.1.0

package/dist/setup.js

@@ -0,0 +1,629 @@
+import { randomBytes } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { closeSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { VectleApiError, VectleClient } from './client.js';
+import { consentPolicyDigest, renderAgentPolicy } from './agent-policy.js';
+import { ensureLegacyOriginBinding, legacySource, writeLegacyCompatibility } from './legacy-compat.js';
+import { chooseClient, integrationBindingDigest, loadIntegrationManifest, saveIntegrationManifest } from './integrations.js';
+import { deleteInstallationCredential, loadConfig, readCredential, readInstallationCredential, readTransientCredential, saveConfig, storeInstallationCredential, storeTransientCredential, deleteTransientCredential } from './store.js';
+import { availableSecureBackend, credentialAccountHandle, installationBackendName } from './secure-store.js';
+import { atomicWriteJson, ensureStateRoot, issueLocalId } from './state.js';
+import { canonicalStateRoot, legacyDefaultRoot, resolveSetupRoot, setupCommitPath, setupLockPath, setupStatePath, validateStateRoot, writeActiveRoot } from './locator.js';
+import { durableRuntimeForSetup } from './runtime.js';
+import { CLI_VERSION } from './constants.js';
+import { compareVersions } from './release.js';
+import { fetchReleaseManifest } from './release-manifest.js';
+import { rolloutDecision } from './rollout.js';
+import { createCodexAdapter } from './adapters/codex.js';
+import { createClaudeCodeAdapter } from './adapters/claude.js';
+import { createCursorAdapter } from './adapters/cursor.js';
+import { createVsCodeAdapter } from './adapters/vscode.js';
+export function setupCommandRequest(command, args) {
+    const option = (name) => {
+        const index = args.indexOf(name);
+        return index >= 0 ? args[index + 1] : undefined;
+    };
+    const positionals = args.slice(1).filter((item, index, values) => !item.startsWith('--') && (index === 0 || !values[index - 1]?.startsWith('--')));
+    const supported = new Set(['codex', 'claude_code', 'cursor', 'vscode', 'terminal', 'unknown', 'auto', 'all']);
+    const requested = command === 'connect' ? positionals[0] ?? option('--client') : option('--client');
+    if (command === 'connect' && (!requested || !['codex', 'claude_code', 'cursor', 'vscode'].includes(requested)))
+        throw new Error('connect_client_invalid');
+    return {
+        client: requested && supported.has(requested) ? requested : 'auto',
+        endpoint: option('--endpoint'),
+        requestedRoot: option('--state-root'),
+        allowCustomStateRoot: args.includes('--allow-custom-state-root'),
+        allowFileCredential: args.includes('--allow-file-credential'),
+        repair: command === 'connect' || args.includes('--repair'),
+        noOpen: args.includes('--no-open'),
+        deprecatedAlias: command === 'init' || command === 'connect',
+        legacyGlobal: command === 'init' && args.includes('--global'),
+    };
+}
+function adapterForClient(client, home) {
+    if (client === 'codex')
+        return createCodexAdapter({ home });
+    if (client === 'claude_code')
+        return createClaudeCodeAdapter({ home });
+    if (client === 'cursor')
+        return createCursorAdapter({ home });
+    if (client === 'vscode')
+        return createVsCodeAdapter({ home });
+    return undefined;
+}
+const sleepDefault = (milliseconds) => new Promise(resolve => setTimeout(resolve, milliseconds));
+function nowIso(now) { return new Date(now()).toISOString(); }
+function setupCommitId() { return `vsc_${randomBytes(16).toString('base64url')}`; }
+function safeRef(prefix) { return `${prefix}-${randomBytes(8).toString('hex')}`; }
+function writeSetupState(state) {
+    ensureStateRoot(state.state_root);
+    atomicWriteJson(setupStatePath(state.state_root), state);
+}
+function readSetupState(root) {
+    try {
+        const value = JSON.parse(readFileSync(setupStatePath(root), 'utf8'));
+        if (value.schema_version !== 'setup-state-v1' || typeof value.setup_commit_id !== 'string' || !/^vsc_[A-Za-z0-9_-]{22}$/u.test(value.setup_commit_id) || typeof value.state_root !== 'string' || canonicalStateRoot(value.state_root) !== canonicalStateRoot(root) || typeof value.phase !== 'string' || typeof value.status !== 'string' || typeof value.client_family !== 'string' || !Array.isArray(value.completed_steps))
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+function removeIfExists(path) { try {
+    unlinkSync(path);
+}
+catch { /* idempotent cleanup */ } }
+function acquireLock(root, now) {
+    ensureStateRoot(root);
+    const path = setupLockPath(root);
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const fd = openSync(path, 'wx', 0o600);
+            writeFileSync(fd, JSON.stringify({ schema_version: 'setup-lock-v1', pid: process.pid, started_at: nowIso(now) }));
+            closeSync(fd);
+            return;
+        }
+        catch {
+            try {
+                const age = now() - statSync(path).mtimeMs;
+                const raw = JSON.parse(readFileSync(path, 'utf8'));
+                let live = false;
+                if (typeof raw.pid === 'number' && raw.pid > 0 && raw.pid !== process.pid) {
+                    try {
+                        process.kill(raw.pid, 0);
+                        live = true;
+                    }
+                    catch {
+                        live = false;
+                    }
+                }
+                if (!live && age > 60_000)
+                    removeIfExists(path);
+            }
+            catch { /* a concurrent setup owns the lock */ }
+        }
+    }
+    throw new Error('setup_in_progress');
+}
+function writeCommit(root, commitId, generation, phase) {
+    atomicWriteJson(setupCommitPath(root), { schema_version: 'setup-commit-v1', setup_commit_id: commitId, generation, phase, state_root: canonicalStateRoot(root), targets: [] });
+}
+function safeError(error) {
+    if (error instanceof VectleApiError && error.body && typeof error.body === 'object' && typeof error.body.error === 'string') {
+        const code = String(error.body.error);
+        return /^[A-Za-z0-9_.-]{1,80}$/u.test(code) ? code : 'setup_failed';
+    }
+    if (error instanceof Error && /^[A-Za-z0-9_.-]{1,80}$/u.test(error.message))
+        return error.message;
+    return 'setup_failed';
+}
+function validAuthorized(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const record = value;
+    const installation = record.installation;
+    const setup = record.setup;
+    return record.schema_version === 'installation-token-authorized-v2'
+        && record.status === 'authorized'
+        && installation !== null && typeof installation === 'object'
+        && setup !== null && typeof setup === 'object'
+        && typeof setup.setup_attempt_id === 'string'
+        && /^vsa_[A-Za-z0-9_-]{22}$/u.test(String(setup.setup_attempt_id))
+        && typeof setup.setup_report_token === 'string'
+        && /^vctis_[A-Za-z0-9_-]{43}$/u.test(String(setup.setup_report_token));
+}
+function safeChecks(overrides = {}) {
+    const codes = ['runtime_durable', 'credential_stored', 'mcp_configured', 'policy_installed', 'approval_persistence', 'lifecycle_hook_configured', 'lifecycle_marker', 'server_smoke', 'client_smoke'];
+    return codes.map(code => ({ code, status: overrides[code] ?? (['mcp_configured', 'policy_installed', 'approval_persistence', 'lifecycle_hook_configured', 'lifecycle_marker'].includes(code) ? 'unsupported' : 'passed') }));
+}
+function projection(client, capability, checks, actions = [], limitations = [], serverHealthy = true) {
+    const full = capability === 'full_lifecycle';
+    const read = full ? 'automatic' : 'on_demand';
+    const share = full ? 'automatic_guard' : capability === 'disconnected' || capability === 'conflict' ? 'off' : 'explicit_only';
+    return {
+        client_family: client,
+        integration_capability: capability,
+        startup_invocation_policy: full ? 'automatic_guard' : capability === 'disconnected' || capability === 'conflict' ? 'off' : 'on_demand',
+        sharing_invocation_policy: share,
+        lookup_capability: serverHealthy ? read : 'unavailable',
+        updates_capability: serverHealthy ? (full ? 'automatic' : 'on_demand') : 'unavailable',
+        submission_capability: capability === 'disconnected' || capability === 'conflict' ? 'unavailable' : 'explicit_only',
+        correction_capability: capability === 'disconnected' || capability === 'conflict' ? 'unavailable' : 'explicit_only',
+        approval_read: full ? 'promptless' : capability === 'authorized_only' ? 'unavailable' : 'may_prompt',
+        approval_write: full ? 'promptless' : capability === 'authorized_only' ? 'unavailable' : 'may_prompt',
+        runtime_health: serverHealthy ? 'healthy' : 'server_unavailable',
+        actions_required: actions,
+        limitations,
+        checks,
+    };
+}
+function terminalProjection(client, serverHealthy) {
+    return projection(client, 'authorized_only', safeChecks({ mcp_configured: 'unsupported', policy_installed: 'unsupported', approval_persistence: 'unsupported', lifecycle_hook_configured: 'unsupported', lifecycle_marker: 'unsupported', client_smoke: serverHealthy ? 'passed' : 'failed', server_smoke: serverHealthy ? 'passed' : 'failed' }), [], ['lifecycle_unsupported'], serverHealthy);
+}
+function setupStatusFor(projectionValue) {
+    if (projectionValue.runtime_health === 'server_unavailable')
+        return 'failed';
+    if (projectionValue.actions_required.some(action => action === 'mcp_server_trust'))
+        return 'host_trust_required';
+    if (projectionValue.actions_required.some(action => action === 'lifecycle_hook_trust'))
+        return 'host_trust_required';
+    if (projectionValue.actions_required.some(action => action === 'client_restart'))
+        return 'ready_after_restart';
+    if (projectionValue.integration_capability === 'full_lifecycle' && projectionValue.checks.some(check => check.code === 'lifecycle_marker' && check.status === 'passed'))
+        return 'ready';
+    if (projectionValue.integration_capability === 'authorized_only' && projectionValue.client_family === 'terminal')
+        return 'ready';
+    if (projectionValue.limitations.length && projectionValue.actions_required.length === 0 && projectionValue.integration_capability !== 'conflict')
+        return 'partial';
+    return 'partial';
+}
+function result(stateRoot, selection, status, reasonCode, client, projectionValue, challenge) {
+    const actions = projectionValue?.actions_required ?? [];
+    const trustTargets = [actions.includes('mcp_server_trust') ? 'the Vectle MCP server' : null, actions.includes('lifecycle_hook_trust') ? 'the Vectle SessionStart hook' : null].filter(Boolean).join(' and ');
+    const action = actions.includes('repair')
+        ? `vectle setup${client && client !== 'unknown' ? ` --client ${client}` : ''} --repair`
+        : trustTargets
+            ? `Approve ${trustTargets} in ${client ?? 'the client'}${actions.includes('client_restart') ? ', then restart it and start a new session' : ''}.`
+            : actions.includes('client_restart')
+                ? `Restart ${client ?? 'the client'} and start a new session.`
+                : null;
+    return { schema_version: 'setup-result-v1', status, reason_code: reasonCode, state_root: stateRoot, client_family: client, selection, projection: projectionValue ? (({ checks: _checks, ...safe }) => safe)(projectionValue) : null, verification_uri_complete: challenge?.verification_uri_complete ?? null, user_code: challenge?.user_code ?? null, challenge_expires_at: challenge?.expires_at ?? null, next_action: reasonCode === 'client_choice_required' ? 'vectle setup --client <codex|claude_code|cursor|vscode|terminal>' : reasonCode ? 'vectle setup --repair' : action };
+}
+export function canReplaceExpiredChallenge(input) {
+    return input.serverStatus === 'expired' && !input.browserPreviewed;
+}
+async function serverSmoke(client, config, token) {
+    try {
+        await client.anonymousCapabilities(1_000, 'explicit');
+        if (!token || config.schema_version !== 'vectle-config-v2')
+            return true;
+        const session = await client.issueInstallationSession(token);
+        const access = session && typeof session === 'object' && typeof session.access_token === 'string' ? String(session.access_token) : null;
+        if (!access)
+            return false;
+        await new VectleClient(config, access).capabilities(1_000);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function verifyReleaseBeforeProvisioning(endpoint, stateRoot) {
+    const manifestVersion = compareVersions(CLI_VERSION, '1.1.0');
+    if (manifestVersion === null || manifestVersion < 0)
+        return null;
+    const result = await fetchReleaseManifest(endpoint, stateRoot);
+    if (!result.envelope)
+        throw new Error('release_manifest_unavailable');
+    const manifest = result.envelope.manifest;
+    const minimum = compareVersions(CLI_VERSION, manifest.minimum_supported_cli);
+    if (minimum === null || minimum < 0)
+        throw new Error('cli_version_unsupported');
+    if (manifest.blocked_artifacts.some(item => item.artifact_kind === 'cli_package' && item.version === CLI_VERSION && item.platform === 'any' && item.architecture === 'any'))
+        throw new Error('release_artifact_blocked');
+    const artifact = manifest.artifacts.find(item => item.artifact_kind === 'cli_package' && item.version === CLI_VERSION && item.platform === 'any' && item.architecture === 'any');
+    if (!artifact)
+        throw new Error('release_artifact_unlisted');
+    return manifest;
+}
+const CLIENT_ROLLOUT_FEATURE = {
+    codex: 'client_codex_lifecycle',
+    claude_code: 'client_claude_lifecycle',
+    cursor: 'client_cursor_lifecycle',
+    vscode: 'client_vscode_lifecycle',
+};
+const CAPABILITY_RANK = { authorized_only: 0, mcp_only: 1, policy_and_mcp: 2, full_lifecycle: 3 };
+const ADAPTER_CONFIG_SCHEMA_VERSION = 1;
+function installedCapabilityRank(capability) {
+    return capability in CAPABILITY_RANK ? CAPABILITY_RANK[capability] : -1;
+}
+export function shouldPreserveInstalledCapability(existing, decision) {
+    if (!existing || ['platform_unsupported', 'adapter_record_missing', 'adapter_record_ambiguous', 'client_version_unsupported'].includes(decision.reason))
+        return false;
+    return installedCapabilityRank(existing.integration_capability) > CAPABILITY_RANK[decision.capability];
+}
+function clientVersionInRange(version, minimum, maximum) {
+    const minimumResult = compareVersions(version, minimum);
+    const maximumResult = maximum ? compareVersions(version, maximum) : 0;
+    return minimumResult !== null && minimumResult >= 0 && (maximum === null || maximumResult !== null && maximumResult <= 0);
+}
+export function detectClientVersion(client) {
+    const command = { codex: 'codex', claude_code: 'claude', cursor: 'cursor', vscode: 'code' }[client];
+    try {
+        const output = execFileSync(command, ['--version'], { encoding: 'utf8', timeout: 1_000, maxBuffer: 4_096, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
+        return parseClientVersion(output);
+    }
+    catch {
+        return null;
+    }
+}
+export function parseClientVersion(output) {
+    const match = /(?:^|[^0-9A-Za-z.+-])((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)(?=$|[^0-9A-Za-z.+-])/u.exec(output.trim());
+    return match?.[1] ?? null;
+}
+export function adapterProvisioningDecision(input) {
+    const platform = input.platform ?? process.platform;
+    if (platform !== 'darwin' && platform !== 'linux' && platform !== 'win32')
+        return { capability: 'authorized_only', lifecycleEligible: false, reason: 'platform_unsupported' };
+    const platformRecords = input.manifest.adapters.filter(item => item.client_family === input.client && item.platform === platform && item.config_schema_version === ADAPTER_CONFIG_SCHEMA_VERSION);
+    const verifiedVersion = typeof input.clientVersion === 'string' && compareVersions(input.clientVersion, input.clientVersion) === 0 ? input.clientVersion : null;
+    if (platformRecords.length === 0)
+        return { capability: 'authorized_only', lifecycleEligible: false, reason: 'adapter_record_missing' };
+    const records = verifiedVersion ? platformRecords.filter(item => clientVersionInRange(verifiedVersion, item.minimum_client_version, item.maximum_client_version)) : platformRecords;
+    if (records.length === 0)
+        return { capability: 'authorized_only', lifecycleEligible: false, reason: 'client_version_unsupported' };
+    if (records.length !== 1)
+        return { capability: 'authorized_only', lifecycleEligible: false, reason: 'adapter_record_ambiguous' };
+    const record = records[0];
+    const lifecycleEligible = verifiedVersion !== null && rolloutDecision(input.config, CLIENT_ROLLOUT_FEATURE[input.client], input.manifest.rollouts[CLIENT_ROLLOUT_FEATURE[input.client]]);
+    const rolloutCeiling = lifecycleEligible ? 'full_lifecycle' : 'policy_and_mcp';
+    const capability = CAPABILITY_RANK[record.maximum_capability] <= CAPABILITY_RANK[rolloutCeiling] ? record.maximum_capability : rolloutCeiling;
+    return { capability, lifecycleEligible, reason: verifiedVersion === null ? 'client_version_unverified' : capability === record.maximum_capability ? 'manifest_capability' : 'lifecycle_rollout_ineligible' };
+}
+export async function runSetup(options = {}) {
+    const now = options.now ?? Date.now;
+    const config = { ...loadConfig(), ...(options.config ?? {}) };
+    const rootResolution = resolveSetupRoot({
+        requestedRoot: options.requestedRoot,
+        allowCustomStateRoot: options.allowCustomStateRoot || options.repair,
+        accountHome: options.home,
+        // VECTLE_CONFIG_DIR is a legacy migration candidate only when the loaded
+        // config actually came from that legacy root. It never silently selects a
+        // fresh v2 identity.
+        legacyRoot: config.config_source === 'legacy_v1' ? legacyDefaultRoot() : undefined,
+    });
+    const stateRoot = validateStateRoot(rootResolution.stateRoot, { allowCreate: true });
+    const selectionResult = chooseClient({ explicit: options.client ?? 'auto', trustedInvocation: options.trustedInvocation, home: options.home, manifest: loadIntegrationManifest(stateRoot) });
+    if (selectionResult.selection.status === 'choice_required')
+        return result(stateRoot, selectionResult.selection, 'client_choice_required', 'client_choice_required', null, null);
+    const requestedClient = options.client;
+    const selectedClient = selectionResult.selected?.client ?? (requestedClient === 'terminal' || requestedClient === 'unknown' ? requestedClient : 'terminal');
+    const profileLabel = selectionResult.selected?.profileLabel ?? 'default';
+    const adapter = options.adapter ?? adapterForClient(selectedClient, options.home);
+    const initialState = readSetupState(stateRoot);
+    acquireLock(stateRoot, now);
+    const resumableState = initialState && (initialState.status === 'in_progress'
+        || (options.repair && initialState.status === 'failed' && Boolean(initialState.challenge_id && initialState.device_code_ref && initialState.refresh_candidate_ref))) ? initialState : null;
+    let state = resumableState ?? { schema_version: 'setup-state-v1', setup_commit_id: setupCommitId(), generation: (initialState?.generation ?? 0) + 1, state_root: stateRoot, phase: 'inspect', status: 'in_progress', client_family: selectedClient, profile_label: profileLabel, challenge_id: null, device_code_ref: null, refresh_candidate_ref: null, setup_attempt_id: null, setup_report_ref: null, completed_steps: [], error_code: null, started_at: nowIso(now), updated_at: nowIso(now) };
+    const previousToken = readCredential();
+    const previousManifest = loadIntegrationManifest(stateRoot);
+    let credentialStored = false;
+    let credentialAttempted = false;
+    let configCommitted = false;
+    let manifestWritten = false;
+    let storedConfig = null;
+    let appliedEntry = null;
+    try {
+        writeSetupState(state);
+        writeCommit(stateRoot, state.setup_commit_id, state.generation, 'preparing');
+        const apiConfig = { ...config, endpoint: (options.endpoint ?? config.endpoint).replace(/\/$/u, ''), clientFamily: selectedClient, stateRoot };
+        // Resolve signed release eligibility before creating or consuming an
+        // authorization challenge. A release-control failure must not mint a
+        // credential that setup subsequently rolls back.
+        const releaseManifest = await verifyReleaseBeforeProvisioning(apiConfig.endpoint, stateRoot);
+        const setupRolloutSeed = config.rollout_seed ?? `seed-${randomBytes(12).toString('hex')}`;
+        const supportedClient = ['codex', 'claude_code', 'cursor', 'vscode'].includes(selectedClient) ? selectedClient : null;
+        const clientVersion = supportedClient ? (options.clientVersion === undefined ? detectClientVersion(supportedClient) : options.clientVersion) : null;
+        const provisioningDecision = releaseManifest && supportedClient
+            ? adapterProvisioningDecision({ manifest: releaseManifest, config: { rollout_seed: setupRolloutSeed }, client: supportedClient, clientVersion })
+            : null;
+        if (provisioningDecision && ['platform_unsupported', 'adapter_record_missing', 'adapter_record_ambiguous', 'client_version_unsupported'].includes(provisioningDecision.reason))
+            throw new Error(provisioningDecision.reason);
+        const client = options.clientApi ?? new VectleClient(apiConfig, readCredential());
+        const allowFile = Boolean(options.allowFileCredential) || process.env.VECTLE_ALLOW_FILE_CREDENTIAL === '1';
+        let currentToken = readCredential();
+        const legacyMigration = Boolean(currentToken && /^vctk_[A-Za-z0-9_-]{43}$/u.test(currentToken) && config.schema_version !== 'vectle-config-v2');
+        if (legacyMigration && currentToken) {
+            // A legacy credential is never sent until its exact source, selected
+            // legacy root, and compiled official origin have been pinned locally.
+            ensureLegacyOriginBinding({ token: currentToken, source: legacySource(config.credentialBackend), endpoint: apiConfig.endpoint });
+            writeLegacyCompatibility(config, 'legacy_v1');
+        }
+        let authorized = null;
+        let challengeForOutput;
+        state.phase = 'install_or_upgrade';
+        state.updated_at = nowIso(now);
+        writeSetupState(state);
+        const v2Installation = config.schema_version === 'vectle-config-v2' && config.installation ? config.installation : null;
+        if (v2Installation && currentToken && !options.repair) {
+            // A healthy v2 installation can be repaired/configured without asking
+            // for consent again. The adapter is the only part that may mutate host
+            // configuration, and it receives the frozen state root below.
+            authorized = { installation: v2Installation, setup: { setup_attempt_id: `vso_${randomBytes(16).toString('base64url')}`, setup_report_token: '', expires_at: new Date(now() + 30 * 60_000).toISOString() } };
+        }
+        else if (v2Installation && currentToken && options.repair) {
+            const operationId = issueLocalId('vai').replace(/^vai_/u, 'vso_');
+            const ref = safeRef('setup-report');
+            const candidate = `vctis_${randomBytes(32).toString('base64url')}`;
+            storeTransientCredential(candidate, apiConfig, 'setup_report', ref, new Date(now() + 30 * 60_000).toISOString(), allowFile);
+            state.phase = 'challenge';
+            state.setup_report_ref = ref;
+            state.updated_at = nowIso(now);
+            writeSetupState(state);
+            const attempt = await client.beginInstallationSetupAttempt({ setup_operation_id: operationId, setup_report_candidate: candidate, client_family: selectedClient });
+            if (typeof attempt.setup_attempt_id !== 'string')
+                throw new Error('setup_attempt_unavailable');
+            state.setup_attempt_id = attempt.setup_attempt_id;
+            state.phase = 'apply_client_config';
+            state.updated_at = nowIso(now);
+            writeSetupState(state);
+            authorized = { installation: v2Installation, setup: { setup_attempt_id: attempt.setup_attempt_id, setup_report_token: candidate, expires_at: String(attempt.expires_at ?? new Date(now() + 30 * 60_000).toISOString()) } };
+        }
+        else {
+            const challengeKind = v2Installation ? 'reconnect' : config.contributorId && currentToken ? 'upgrade' : 'fresh';
+            let deviceRef = state.device_code_ref;
+            let candidateRef = state.refresh_candidate_ref;
+            let deadline = now() + 30 * 60_000;
+            if (!state.challenge_id || !deviceRef || !candidateRef) {
+                const refreshCandidate = `vctir_${randomBytes(32).toString('base64url')}`;
+                candidateRef = safeRef('refresh');
+                storeTransientCredential(refreshCandidate, apiConfig, 'refresh', candidateRef, new Date(now() + 30 * 60_000).toISOString(), allowFile);
+                state.refresh_candidate_ref = candidateRef;
+                state.phase = 'challenge';
+                state.updated_at = nowIso(now);
+                writeSetupState(state);
+                const challenge = await client.createInstallationChallengeV2({ challenge_kind: challengeKind, client_family: selectedClient, consent_policy_digest: consentPolicyDigest(), automatic_lookup: true, automatic_sharing: true });
+                const deviceCode = typeof challenge.device_code === 'string' ? challenge.device_code : null;
+                const challengeId = typeof challenge.challenge_id === 'string' ? challenge.challenge_id : null;
+                if (!deviceCode || !challengeId)
+                    throw new Error('challenge_unavailable');
+                deviceRef = safeRef('device');
+                storeTransientCredential(deviceCode, apiConfig, 'device_code', deviceRef, String(challenge.expires_at), allowFile);
+                state.challenge_id = challengeId;
+                state.device_code_ref = deviceRef;
+                state.phase = 'wait_for_approval';
+                state.updated_at = nowIso(now);
+                writeSetupState(state);
+                challengeForOutput = { verification_uri_complete: typeof challenge.verification_uri_complete === 'string' ? challenge.verification_uri_complete : undefined, user_code: typeof challenge.user_code === 'string' ? challenge.user_code : undefined, expires_at: typeof challenge.expires_at === 'string' ? challenge.expires_at : undefined };
+                if (challengeForOutput.verification_uri_complete && !options.noOpen)
+                    options.openBrowser?.(challengeForOutput.verification_uri_complete);
+                deadline = Date.parse(String(challenge.expires_at));
+            }
+            else {
+                state.phase = 'wait_for_approval';
+                state.updated_at = nowIso(now);
+                writeSetupState(state);
+            }
+            const wait = options.sleep ?? sleepDefault;
+            while (now() < deadline) {
+                await wait(Math.max(2_000, Math.min(10_000, 5_000)));
+                const device = readTransientCredential(apiConfig, 'device_code', deviceRef);
+                const candidate = readTransientCredential(apiConfig, 'refresh', candidateRef);
+                if (!device || !candidate)
+                    throw new Error('setup_secret_unavailable');
+                const polled = await client.pollInstallationChallengeV2(device, candidate);
+                if (polled.status === 'authorization_pending' || polled.status === 'authorization_processing') {
+                    if (typeof polled.expires_at === 'string' && Number.isFinite(Date.parse(polled.expires_at)))
+                        deadline = Date.parse(polled.expires_at);
+                    continue;
+                }
+                if (!validAuthorized(polled)) {
+                    const serverStatus = typeof polled.status === 'string' ? polled.status : 'invalid_device_code';
+                    throw new Error(serverStatus === 'setup_declined' ? 'setup_declined' : serverStatus === 'expired' ? 'challenge_expired' : 'challenge_consume_conflict');
+                }
+                authorized = { installation: polled.installation, setup: polled.setup };
+                state.setup_attempt_id = polled.setup.setup_attempt_id;
+                state.setup_report_ref = safeRef('setup-report');
+                storeTransientCredential(polled.setup.setup_report_token, apiConfig, 'setup_report', state.setup_report_ref, polled.setup.expires_at, allowFile);
+                deleteTransientCredential(apiConfig, 'device_code', deviceRef);
+                break;
+            }
+            if (!authorized)
+                throw new Error('challenge_expired');
+        }
+        if (!authorized)
+            throw new Error('setup_authorization_missing');
+        state.phase = 'store_credential';
+        state.updated_at = nowIso(now);
+        writeSetupState(state);
+        writeCommit(stateRoot, state.setup_commit_id, state.generation, 'applying');
+        const pendingRefresh = state.refresh_candidate_ref ? readTransientCredential(apiConfig, 'refresh', state.refresh_candidate_ref) : null;
+        const serverInstallation = authorized.installation;
+        const supportCode = typeof serverInstallation.support_code === 'string' ? serverInstallation.support_code : '';
+        const approvedOrigin = typeof serverInstallation.approved_api_origin === 'string' ? serverInstallation.approved_api_origin : apiConfig.endpoint;
+        if (!/^vci_[A-Za-z0-9_-]{22}$/u.test(supportCode))
+            throw new Error('invalid_installation_binding');
+        const accountHandle = credentialAccountHandle(approvedOrigin, supportCode);
+        const selectedBackend = pendingRefresh
+            ? availableSecureBackend({ allowFileFallback: allowFile })
+            : null;
+        if (pendingRefresh && (!selectedBackend || selectedBackend === 'environment'))
+            throw new Error('secure_store_unavailable');
+        const installationBackend = v2Installation?.credential_backend ?? (selectedBackend ? installationBackendName(selectedBackend) : 'file');
+        const installation = {
+            support_code: supportCode,
+            approved_api_origin: approvedOrigin,
+            credential_backend: installationBackend,
+            credential_account_handle: accountHandle,
+            consent_version: 2,
+            consented_scopes: Array.isArray(serverInstallation.consented_scopes) ? [...serverInstallation.consented_scopes].sort() : [],
+            consent_policy_digest: typeof serverInstallation.consent_policy_digest === 'string' ? serverInstallation.consent_policy_digest : '',
+            approved_at: typeof serverInstallation.approved_at === 'string' ? serverInstallation.approved_at : '',
+            automatic_lookup: serverInstallation.automatic_lookup === true,
+            automatic_sharing: serverInstallation.automatic_sharing === true,
+        };
+        if (installation.consented_scopes.length !== 6 || !/^sha256:[0-9a-f]{64}$/u.test(installation.consent_policy_digest) || !Number.isFinite(Date.parse(installation.approved_at)))
+            throw new Error('invalid_installation_binding');
+        const nextConfig = { ...apiConfig, endpoint: approvedOrigin, schema_version: 'vectle-config-v2', installation, mode: config.mode === 'paused' || config.mode === 'read-only' ? config.mode : 'active', rollout_seed: setupRolloutSeed, config_source: 'v2' };
+        storedConfig = nextConfig;
+        if (pendingRefresh) {
+            credentialAttempted = true;
+            const backend = storeInstallationCredential(pendingRefresh, nextConfig, allowFile);
+            nextConfig.installation = { ...nextConfig.installation, credential_backend: backend };
+            currentToken = readInstallationCredential(nextConfig);
+            if (!currentToken)
+                throw new Error('secure_store_round_trip_failed');
+            credentialStored = true;
+        }
+        state.completed_steps.push('credential_stored');
+        state.phase = 'apply_client_config';
+        state.updated_at = nowIso(now);
+        writeSetupState(state);
+        let entry = null;
+        const runtime = durableRuntimeForSetup(stateRoot);
+        let checks = safeChecks({ runtime_durable: runtime.descriptor.durable ? 'passed' : 'failed', mcp_configured: selectedClient === 'terminal' || selectedClient === 'unknown' ? 'unsupported' : 'pending', policy_installed: selectedClient === 'terminal' || selectedClient === 'unknown' ? 'unsupported' : 'pending', client_smoke: selectedClient === 'terminal' || selectedClient === 'unknown' ? 'passed' : 'pending' });
+        let capability = selectedClient === 'terminal' || selectedClient === 'unknown' ? 'authorized_only' : 'authorized_only';
+        let actions = [];
+        let limitations = selectedClient === 'terminal' || selectedClient === 'unknown' ? ['lifecycle_unsupported'] : runtime.descriptor.durable ? ['lifecycle_unsupported'] : ['runtime_not_durable'];
+        let releaseVersionUnverified = false;
+        if (adapter && runtime.descriptor.durable && supportedClient) {
+            const decision = provisioningDecision
+                ?? (releaseManifest
+                    ? adapterProvisioningDecision({ manifest: releaseManifest, config: nextConfig, client: supportedClient, clientVersion })
+                    : { capability: 'full_lifecycle', lifecycleEligible: true, reason: 'legacy_cli' });
+            releaseVersionUnverified = decision.reason === 'client_version_unverified';
+            const adapterEntryId = selectionResult.selected?.adapterEntryId ?? issueLocalId('vai');
+            const existingEntry = previousManifest.entries.find(item => item.adapter_entry_id === adapterEntryId && item.client_family === supportedClient) ?? null;
+            if (shouldPreserveInstalledCapability(existingEntry, decision)) {
+                // A lower threshold or signed capability ceiling prevents new installs
+                // and widening. It never removes an already installed integration.
+                entry = existingEntry;
+            }
+            else if (decision.capability !== 'authorized_only') {
+                const binding = integrationBindingDigest(nextConfig, adapterEntryId);
+                const policyChecksum = renderAgentPolicy({ mode: nextConfig.mode ?? 'active', clientFamily: selectedClient, integrationCapability: decision.capability, approvedBehaviorCeiling: { consentVersion: 2, startupPulse: nextConfig.installation?.automatic_lookup ? 'automatic' : 'on_demand', sharingAndCorrection: nextConfig.installation?.automatic_sharing ? 'automatic' : 'explicit_only' }, approvalPersistence: { read: 'promptless', write: 'promptless' }, tools: { startupPulse: true, shareFinding: true, correctFinding: true } }).checksum;
+                const applied = await adapter.apply({ config: nextConfig, stateRoot, adapterEntryId, integrationBindingDigest: binding, policyChecksum, targetCapability: decision.capability });
+                entry = applied.entry;
+                checks = applied.checks;
+                actions = applied.actions ?? [];
+                limitations = applied.limitations ?? [];
+                capability = applied.capability ?? 'mcp_only';
+                appliedEntry = entry;
+                state.completed_steps.push('client_configured');
+                if (decision.capability !== 'mcp_only')
+                    state.completed_steps.push('policy_installed');
+            }
+        }
+        if (supportedClient && provisioningDecision?.capability === 'authorized_only' && !entry) {
+            checks = safeChecks({ runtime_durable: runtime.descriptor.durable ? 'passed' : 'failed', credential_stored: 'passed', mcp_configured: 'unsupported', policy_installed: 'unsupported', approval_persistence: 'unsupported', lifecycle_hook_configured: 'unsupported', lifecycle_marker: 'unsupported', client_smoke: 'passed' });
+            capability = 'authorized_only';
+            limitations = ['lifecycle_unsupported'];
+        }
+        state.phase = 'client_smoke_test';
+        state.updated_at = nowIso(now);
+        writeSetupState(state);
+        let verification = { clientSmoke: selectedClient === 'terminal' || selectedClient === 'unknown' || capability === 'authorized_only' ? 'passed' : 'failed', marker: 'unsupported', lifecycle: capability, actions: runtime.descriptor.durable ? [] : ['repair'], limitations };
+        if (adapter && entry)
+            verification = await adapter.verify({ config: nextConfig, entry });
+        capability = verification.lifecycle;
+        actions = verification.actions ?? actions;
+        limitations = verification.limitations ?? limitations;
+        if (releaseVersionUnverified && !limitations.includes('client_version_unverified'))
+            limitations.push('client_version_unverified');
+        checks = checks.map(check => check.code === 'client_smoke' ? { ...check, status: verification.clientSmoke } : check);
+        if (verification.marker !== 'unsupported')
+            checks = checks.map(check => check.code === 'lifecycle_marker' ? { ...check, status: verification.marker } : check);
+        const smokeClient = new VectleClient(nextConfig, currentToken ?? null);
+        state.phase = 'server_smoke_test';
+        state.updated_at = nowIso(now);
+        writeSetupState(state);
+        const serverHealthy = await serverSmoke(smokeClient, nextConfig, currentToken ?? pendingRefresh ?? null);
+        checks = checks.map(check => check.code === 'server_smoke' ? { ...check, status: serverHealthy ? 'passed' : 'failed' } : check);
+        const clientProjection = projection(selectedClient, capability, checks, actions, limitations, serverHealthy);
+        const status = setupStatusFor(clientProjection);
+        if (entry) {
+            const manifest = loadIntegrationManifest(stateRoot);
+            saveIntegrationManifest({ schema_version: 'integrations-v1', entries: [...manifest.entries.filter(item => item.adapter_entry_id !== entry.adapter_entry_id), entry] }, stateRoot);
+            manifestWritten = true;
+        }
+        state.phase = 'report_ready';
+        state.status = status;
+        state.updated_at = nowIso(now);
+        writeSetupState(state);
+        const reportRef = state.setup_report_ref;
+        const reportToken = reportRef ? readTransientCredential(apiConfig, 'setup_report', reportRef) : null;
+        if (reportToken && reportRef && state.setup_attempt_id) {
+            const report = { schema_version: 'installation-setup-report-v1', setup_attempt_id: state.setup_attempt_id, status, client: clientProjection };
+            const response = await smokeClient.reportInstallationSetup(reportToken, report);
+            if (!response || typeof response !== 'object')
+                throw new Error('setup_report_unavailable');
+            deleteTransientCredential(apiConfig, 'setup_report', reportRef);
+        }
+        if (state.refresh_candidate_ref)
+            deleteTransientCredential(apiConfig, 'refresh', state.refresh_candidate_ref);
+        if (legacyMigration)
+            writeLegacyCompatibility(config, 'upgraded_v2');
+        writeActiveRoot(stateRoot, { accountHome: options.home });
+        saveConfig(nextConfig);
+        configCommitted = true;
+        writeCommit(stateRoot, state.setup_commit_id, state.generation, 'committed');
+        state.phase = 'done';
+        state.status = status;
+        state.completed_steps.push('server_smoke', 'client_smoke', 'reported');
+        state.updated_at = nowIso(now);
+        writeSetupState(state);
+        removeIfExists(setupCommitPath(stateRoot));
+        removeIfExists(setupStatePath(stateRoot));
+        return result(stateRoot, selectionResult.selection, status, status === 'failed' ? 'service_unavailable' : null, selectedClient, clientProjection, challengeForOutput);
+    }
+    catch (error) {
+        if (!configCommitted) {
+            if (adapter?.rollback && appliedEntry) {
+                try {
+                    await adapter.rollback({ config: storedConfig ?? config, stateRoot, entry: appliedEntry });
+                }
+                catch { /* leave the safe repair state for the next explicit attempt */ }
+            }
+            if (manifestWritten) {
+                try {
+                    saveIntegrationManifest(previousManifest, stateRoot);
+                }
+                catch { /* repair can reconcile the manifest */ }
+            }
+            if ((credentialStored || credentialAttempted) && storedConfig?.installation) {
+                try {
+                    if (previousToken && config.schema_version === 'vectle-config-v2' && config.installation) {
+                        storeInstallationCredential(previousToken, config, true);
+                    }
+                    else {
+                        deleteInstallationCredential(storedConfig);
+                    }
+                }
+                catch { /* never turn a setup error into a credential-handling crash */ }
+            }
+        }
+        state.phase = 'rollback';
+        state.status = 'failed';
+        state.error_code = safeError(error);
+        state.updated_at = nowIso(now);
+        try {
+            writeSetupState(state);
+        }
+        catch { /* preserve primary failure */ }
+        return result(stateRoot, selectionResult.selection, 'failed', state.error_code, selectedClient, null, undefined);
+    }
+    finally {
+        removeIfExists(setupLockPath(stateRoot));
+    }
+}
+export function recoverSetup(root) {
+    const canonical = validateStateRoot(root, { allowCreate: false });
+    const state = readSetupState(canonical);
+    if (!state)
+        return { status: 'none', recovered: false };
+    removeIfExists(setupLockPath(canonical));
+    return { status: state.status, recovered: true, error_code: state.error_code };
+}
+export function setupStateForTests(root) { return readSetupState(root); }
+//# sourceMappingURL=setup.js.map