@neetru/cli 2.28.7 → 2.28.8

package/dist/commands/db-move.d.ts

@@ -0,0 +1,204 @@
+export type RelocationState = 'planning' | 'provisioning_target' | 'replicating' | 'verifying_target' | 'quiescing_source' | 'final_sync' | 'cutover' | 'observing' | 'draining_source' | 'done' | 'resume_source' | 'rolling_back' | 'rolling_back_post' | 'rolled_back' | 'needs_attention' | 'failed';
+/** Ordem "pra frente" do caminho feliz — usada só pra exibir progresso. */
+export declare const FORWARD_STATES: RelocationState[];
+/** Estados terminais de SUCESSO (o único ponto onde "movido" pode ser dito). */
+export declare const TERMINAL_SUCCESS: ReadonlySet<RelocationState>;
+/** Estados terminais de FALHA/rollback (produto seguiu/voltou pra origem). */
+export declare const TERMINAL_FAILURE: ReadonlySet<RelocationState>;
+/**
+ * Estado terminal de HALT fail-closed (iteração 2). O Core PARA a máquina aqui
+ * quando detecta drift de ledger ou um destroy recusado por INV-DESTROY. NÃO é
+ * sucesso nem "voltou pra origem" — é "parou e precisa de gente", e o dado NÃO
+ * foi destruído (fail-closed). Poll NUNCA pode tratar isto como `running` (senão
+ * ficaria pendurado até o timeout).
+ */
+export declare const TERMINAL_ATTENTION: ReadonlySet<RelocationState>;
+/**
+ * Estados em que o cutover PODE já ter trocado o ledger pro destino (o "vivo"
+ * pode estar no destino). `cutover` entra aqui por ser AMBÍGUO — durante ele a
+ * troca do ledger pode ou não ter acontecido; tratamos como pós por segurança
+ * (mensagem cuidadosa, nunca afirmar "ledger intocado"). Usado pelo `abort`
+ * pra escolher a mensagem correta (pré vs pós-cutover).
+ */
+export declare const POST_CUTOVER_STATES: ReadonlySet<RelocationState>;
+/** True se o estado já pode ter o ledger apontando pro destino (pós-cutover). */
+export declare function isPostCutoverState(s: RelocationState): boolean;
+/** Rótulos PT-BR de cada estado da máquina (progresso ostensivo). */
+export declare const STATE_LABELS: Record<RelocationState, string>;
+export interface VerifyReport {
+    tables?: Array<{
+        name: string;
+        srcRows: number;
+        dstRows: number;
+        ok: boolean;
+    }>;
+    checksumOk?: boolean;
+}
+/** Doc de migração como o Core devolve no GET de status. */
+export interface RelocationMigration {
+    id: string;
+    state: RelocationState;
+    dbId: string;
+    productId?: string;
+    engine?: string;
+    sourceServerId: string;
+    targetServerId: string;
+    manualCutover?: boolean;
+    healthGatePassedAt?: string | null;
+    observeOkAt?: string | null;
+    verifyReport?: VerifyReport | null;
+    previousServerId?: string | null;
+    /** Iteração 2: cutover atômico registrou a troca de ledger. */
+    cutoverCommitted?: boolean;
+    cutoverAt?: string | null;
+    /**
+     * Iteração 2: onde o LEDGER (`product_databases/{dbId}`) aponta AGORA — a única
+     * verdade de quem é o "vivo". O CLI NUNCA infere a posição do dado do `state`;
+     * lê daqui. Ausente = o Core não expôs; o CLI cai pra source/target conforme
+     * o estado, mas nunca afirma segurança sem confirmação terminal.
+     */
+    live?: {
+        serverId?: string | null;
+        endpoint?: string | null;
+    } | null;
+    reason?: string;
+    lastError?: {
+        code: string;
+        message: string;
+        at?: string;
+    } | null;
+    updatedAt?: string;
+}
+/**
+ * Resposta do POST .../abort (iteração 2). O Core deriva tudo do doc+ledger e
+ * responde de forma idempotente. `dataSafe` é a afirmação AUTORITATIVA do Core
+ * de que nenhum dado vivo foi/será destruído; `live.serverId` é pra onde o
+ * ledger aponta. O CLI só afirma segurança quando ISTO confirma — nunca por
+ * conta própria.
+ */
+export interface RelocateAbortResponse {
+    ok: boolean;
+    state: RelocationState;
+    live?: {
+        serverId?: string | null;
+    } | null;
+    dataSafe?: boolean;
+}
+export type RelocationPhase = 'running' | 'success' | 'failure' | 'await_confirm' | 'attention';
+/**
+ * Classifica o estado de uma migração numa das FASES que o CLI trata.
+ * `await_confirm`: manual-cutover pausado em `verifying_target` com o health-gate
+ * já verde — o Core está esperando `db move confirm`.
+ * `attention`: HALT fail-closed (`needs_attention`) — parou, precisa de gente,
+ * nada destruído. É TERMINAL para o poll (não pode ser confundido com `running`).
+ *
+ * Função pura — não toca rede/relógio. É o coração testável do driver de watch.
+ */
+export declare function classifyRelocation(m: RelocationMigration): {
+    phase: RelocationPhase;
+    label: string;
+};
+/** Linhas humanas do verifyReport (contagem por tabela origem vs destino). */
+export declare function formatVerifyReportLines(report?: VerifyReport | null): string[];
+/** Valida o teto duro de quiesce (guardrail INV-1). Retorna erro ou null. */
+export declare function validateMaxQuiesceMs(raw?: string | number): {
+    value: number;
+    error?: string;
+};
+declare const VALID_STRATEGIES: readonly ["snapshot_quiesce", "logical_stream"];
+export type ReplicationStrategy = (typeof VALID_STRATEGIES)[number];
+export type AbortOutcome = 'reverted_safe' | 'needs_attention' | 'failed' | 'pending';
+/**
+ * Classifica o desfecho TERMINAL de um abort a partir do doc de migração.
+ *
+ * REGRA DE SEGURANÇA (iteração 2): o CLI só pode afirmar "nenhum dado perdido"
+ * quando o Core CONFIRMA um estado terminal + o ledger aponta pra um servidor
+ * que tem os dados. Nunca infere segurança do `state` sozinho, nunca antes do
+ * terminal. Um abort que para em `needs_attention` NÃO é "tudo certo" — é HALT
+ * (nada destruído, mas precisa de gente); afirmar all-clear ali seria mentir.
+ *
+ * Função pura — é o núcleo testável do relatório de abort.
+ */
+export declare function classifyAbortTerminal(m: RelocationMigration): {
+    outcome: AbortOutcome;
+    /** O CLI PODE afirmar que os dados vivos estão seguros/intactos? */
+    dataSafe: boolean;
+    /** Onde o ledger aponta agora (a única verdade de quem é o vivo). */
+    liveServerId?: string;
+};
+export interface DbMoveStartOptions {
+    /** Slug (ou id) do produto cujo banco será movido. */
+    product?: string;
+    /** dbId explícito (pdb_…) — dispensa a resolução por produto. */
+    db?: string;
+    /** Ambiente pra desambiguar quando o produto tem >1 banco. */
+    env?: string;
+    /** VM destino (serverId) — obrigatório. */
+    to?: string;
+    /** Motivo (vai pro audit). Obrigatório fora de --dry-run. */
+    reason?: string;
+    strategy?: string;
+    manualCutover?: boolean;
+    maxQuiesceMs?: string;
+    dryRun?: boolean;
+    /** Acompanha a máquina de estados até um estado terminal (default true). */
+    watch?: boolean;
+    yes?: boolean;
+    mfaToken?: string;
+    json?: boolean;
+    /** Somente testes: intervalo entre polls (ms). Default 4000. */
+    pollIntervalMs?: number;
+    /** Somente testes: teto do wall-clock do poll (ms). Default 30min. */
+    pollTimeoutMs?: number;
+}
+export declare function runDbMoveStart(opts: DbMoveStartOptions): Promise<void>;
+/**
+ * Acompanha a máquina de estados até um estado terminal (done/rolled_back/failed)
+ * ou até a pausa de manual-cutover. Reporta SUCESSO só em `done`.
+ * Usado por `runDbMoveStart` (com --watch) e por `runDbMoveConfirm`.
+ */
+export declare function pollRelocation(migrationId: string, opts: {
+    json?: boolean;
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+}): Promise<void>;
+export declare function runDbMoveStatus(migrationId: string, opts?: {
+    json?: boolean;
+}): Promise<void>;
+export declare function runDbMoveConfirm(migrationId: string, opts?: {
+    mfa?: string;
+    json?: boolean;
+    watch?: boolean;
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+}): Promise<void>;
+export declare function runDbMoveAbort(migrationId: string, opts?: {
+    reason?: string;
+    yes?: boolean;
+    mfaToken?: string;
+    json?: boolean;
+    watch?: boolean;
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+}): Promise<void>;
+/**
+ * Descomissiona (dropa) a ORIGEM de uma relocação JÁ concluída. É o ÚNICO caminho
+ * que destrói a origem, e por design é SEPARADO, explícito, gated por MFA e —
+ * client-side — recusado se o ledger ainda NÃO aponta pro destino (i.e., o move
+ * não terminou / foi revertido). Isto é o espelho-CLI da INV-DESTROY: nunca pedir
+ * o drop de um servidor que o ledger diz ser o vivo. O Core é a autoridade final
+ * (re-checa live==target + grace + INV-DESTROY), mas falhamos cedo e claro.
+ */
+export declare function runDbMoveDecommission(migrationId: string, opts?: {
+    reason?: string;
+    yes?: boolean;
+    mfaToken?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function runDbWhere(opts?: {
+    product?: string;
+    db?: string;
+    env?: string;
+    json?: boolean;
+}): Promise<void>;
+export {};