@vectle/cli 1.0.0 → 1.1.0

package/dist/setup.d.ts

@@ -0,0 +1,159 @@
+import { VectleClient } from './client.js';
+import { chooseClient, type IntegrationManifestEntry, type SupportedClientFamily } from './integrations.js';
+import { type ClientFamily, type VectleConfig } from './store.js';
+import { type ReleaseManifest } from './release-manifest.js';
+export type SetupCheck = {
+    code: 'runtime_durable' | 'credential_stored' | 'mcp_configured' | 'policy_installed' | 'approval_persistence' | 'lifecycle_hook_configured' | 'lifecycle_marker' | 'server_smoke' | 'client_smoke';
+    status: 'passed' | 'pending' | 'failed' | 'unsupported';
+};
+export type SetupPhase = 'inspect' | 'acquire_lock' | 'install_or_upgrade' | 'challenge' | 'wait_for_approval' | 'store_credential' | 'apply_client_config' | 'apply_agent_policy' | 'client_smoke_test' | 'server_smoke_test' | 'report_ready' | 'done' | 'rollback';
+export type SetupTerminalStatus = 'ready' | 'ready_after_restart' | 'host_trust_required' | 'host_approval_may_repeat' | 'partial' | 'failed';
+type SetupState = {
+    schema_version: 'setup-state-v1';
+    setup_commit_id: string;
+    generation: number;
+    state_root: string;
+    phase: SetupPhase;
+    status: SetupTerminalStatus | 'in_progress';
+    client_family: ClientFamily;
+    profile_label: string;
+    challenge_id: string | null;
+    device_code_ref: string | null;
+    refresh_candidate_ref: string | null;
+    setup_attempt_id: string | null;
+    setup_report_ref: string | null;
+    completed_steps: string[];
+    error_code: string | null;
+    started_at: string;
+    updated_at: string;
+};
+export type SetupClientProjection = {
+    client_family: ClientFamily;
+    integration_capability: 'full_lifecycle' | 'policy_and_mcp' | 'mcp_only' | 'authorized_only' | 'disconnected' | 'conflict';
+    startup_invocation_policy: 'automatic_guard' | 'on_demand' | 'off';
+    sharing_invocation_policy: 'automatic_guard' | 'explicit_only' | 'off';
+    lookup_capability: 'automatic' | 'on_demand' | 'unavailable';
+    updates_capability: 'automatic' | 'on_demand' | 'unavailable';
+    submission_capability: 'automatic' | 'explicit_only' | 'unavailable';
+    correction_capability: 'automatic' | 'explicit_only' | 'unavailable';
+    approval_read: 'promptless' | 'may_prompt' | 'unavailable';
+    approval_write: 'promptless' | 'may_prompt' | 'unavailable';
+    runtime_health: 'healthy' | 'lookup_degraded' | 'updates_degraded' | 'auth_degraded' | 'server_unavailable' | 'unchecked';
+    actions_required: Array<'mcp_server_trust' | 'lifecycle_hook_trust' | 'client_restart' | 'repair'>;
+    limitations: Array<'host_approval_may_repeat' | 'lifecycle_unsupported' | 'cloud_not_covered' | 'client_version_unverified' | 'runtime_not_durable' | 'managed_policy_block'>;
+    checks: SetupCheck[];
+};
+export type SetupResult = {
+    schema_version: 'setup-result-v1';
+    status: SetupTerminalStatus | 'client_choice_required' | 'in_progress';
+    reason_code: string | null;
+    state_root: string;
+    client_family: ClientFamily | null;
+    selection: ReturnType<typeof chooseClient>['selection'];
+    projection: Omit<SetupClientProjection, 'checks'> | null;
+    verification_uri_complete: string | null;
+    user_code: string | null;
+    challenge_expires_at: string | null;
+    next_action: string | null;
+};
+export type SetupAdapter = {
+    client: SupportedClientFamily;
+    profileLabel?: string;
+    apply: (input: {
+        config: VectleConfig;
+        stateRoot: string;
+        adapterEntryId: string;
+        integrationBindingDigest: `sha256:${string}`;
+        policyChecksum: `sha256:${string}`;
+        targetCapability: 'mcp_only' | 'policy_and_mcp' | 'full_lifecycle';
+    }) => Promise<{
+        entry: IntegrationManifestEntry;
+        checks: SetupCheck[];
+        actions?: SetupClientProjection['actions_required'];
+        limitations?: SetupClientProjection['limitations'];
+        capability?: SetupClientProjection['integration_capability'];
+    }>;
+    verify: (input: {
+        config: VectleConfig;
+        entry: IntegrationManifestEntry;
+    }) => Promise<{
+        clientSmoke: 'passed' | 'failed';
+        marker: 'passed' | 'pending' | 'unsupported';
+        lifecycle: 'full_lifecycle' | 'policy_and_mcp' | 'mcp_only' | 'authorized_only';
+        actions?: SetupClientProjection['actions_required'];
+        limitations?: SetupClientProjection['limitations'];
+    }>;
+    rollback?: (input: {
+        config: VectleConfig;
+        stateRoot: string;
+        entry: IntegrationManifestEntry;
+    }) => Promise<void>;
+};
+export type SetupOptions = {
+    client?: ClientFamily | 'auto' | 'all';
+    endpoint?: string;
+    requestedRoot?: string;
+    allowCustomStateRoot?: boolean;
+    allowFileCredential?: boolean;
+    repair?: boolean;
+    noOpen?: boolean;
+    json?: boolean;
+    trustedInvocation?: SupportedClientFamily;
+    home?: string;
+    config?: VectleConfig;
+    clientApi?: VectleClient;
+    adapter?: SetupAdapter;
+    sleep?: (milliseconds: number) => Promise<void>;
+    now?: () => number;
+    openBrowser?: (url: string) => void;
+    clientVersion?: string | null;
+};
+export declare function setupCommandRequest(command: 'setup' | 'init' | 'connect', args: string[]): {
+    client: ClientFamily | "auto" | "all" | undefined;
+    endpoint: string | undefined;
+    requestedRoot: string | undefined;
+    allowCustomStateRoot: boolean;
+    allowFileCredential: boolean;
+    repair: boolean;
+    noOpen: boolean;
+    deprecatedAlias: boolean;
+    legacyGlobal: boolean;
+};
+export declare function canReplaceExpiredChallenge(input: {
+    serverStatus: 'expired' | 'pending' | 'approved' | 'denied' | 'consumed';
+    browserPreviewed: boolean;
+}): boolean;
+declare const CAPABILITY_RANK: {
+    readonly authorized_only: 0;
+    readonly mcp_only: 1;
+    readonly policy_and_mcp: 2;
+    readonly full_lifecycle: 3;
+};
+type ProvisionableCapability = keyof typeof CAPABILITY_RANK;
+type AdapterProvisioningDecision = {
+    capability: ProvisionableCapability;
+    lifecycleEligible: boolean;
+    reason: 'platform_unsupported' | 'adapter_record_missing' | 'adapter_record_ambiguous' | 'client_version_unsupported' | 'client_version_unverified' | 'manifest_capability' | 'lifecycle_rollout_ineligible' | 'legacy_cli';
+};
+export declare function shouldPreserveInstalledCapability(existing: IntegrationManifestEntry | null, decision: AdapterProvisioningDecision): boolean;
+export declare function detectClientVersion(client: SupportedClientFamily): string | null;
+export declare function parseClientVersion(output: string): string | null;
+export declare function adapterProvisioningDecision(input: {
+    manifest: ReleaseManifest;
+    config: Pick<VectleConfig, 'rollout_seed'>;
+    client: SupportedClientFamily;
+    platform?: NodeJS.Platform;
+    clientVersion?: string | null;
+}): AdapterProvisioningDecision;
+export declare function runSetup(options?: SetupOptions): Promise<SetupResult>;
+export declare function recoverSetup(root: string): {
+    status: "none";
+    recovered: boolean;
+    error_code?: undefined;
+} | {
+    status: SetupTerminalStatus | "in_progress";
+    recovered: boolean;
+    error_code: string | null;
+};
+export declare function setupStateForTests(root: string): SetupState | null;
+export {};