Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 69 additions & 0 deletions docs/V2_RELEASE_WO014.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# DIF-V2-WO-014 — Release V2: regressão integral, auditoria e deploy validado

**Issue:** #31 · **Branch:** `feat/dif-v2-wo-014` · **Base:** `main` `7c175e5`
**Status:** **BLOCKED** — código/testes/regressão prontos; o deploy validado não pode concluir sem migrations no Supabase hospedado. O Vercel já serve o código V2, mas o projeto hospedado ainda tem apenas o schema V1. O PR #70 mantém ferramentas/docs de release, sem merge/deploy.

## Pré-requisitos atendidos

- WO-001–013 e WO-015–021 **PROMOTED**, com checkpoints reconciliados; OPS 015–021 **PROMOTED** (`c7490e8`).
- `main` `7c175e5` com quality workflow docs-only PASS; o gate SonarCloud separado falhou nesse commit de docs por duplicação pré-existente, sem código novo. Code/test head V2 `f32cc97` com CI `44776291945` PASS; OPS `77d5626` com CI `44787029917` PASS.
- Unit **351 + 3 skipped**, PgTAP **247/247**, policy **36/41**, E2E **19/19**, Sonar/Socket PASS.
- Backup/restore local executado (41/41 contagens, SHA, join 768, QA 5/5).
- Worker/render local e ARM64 benchmark das WOs anteriores aprovados.
- Sem HIGH/CRITICAL conhecido; auditorias independentes finais de WO-021 e OPS **APPROVED WITH RESIDUALS**.

## Bloqueio atual (produção)

- `https://dif-studio.vercel.app/health` → 200; `/login` → 200; `/app`, `/app/series`, `/app/episodes` → 200 com owner real.
- `https://dif-studio.vercel.app/app/style` → **HTTP 500** para o owner; o projeto Supabase hospedado `zottgifcocnjguhmnezx` não tem as tabelas V2 (`GET /rest/v1/style_presets` → PGRST205).
- O workspace não tem Supabase PAT nem database password:
- `npx supabase projects list` → “Invalid access token”;
- não existe `C:\Users\csn19\.zcode\dif-secrets\supabase-pat.txt`;
- não há Vercel CLI autenticado (o deploy Vercel vem da integração Git).
- Sem credencial não é possível aplicar as **29 migrations V2** (`20261112170000`–`20261120132000`) nem executar o smoke de produção. Não há caminho DDL via PostgREST/anon.

## Como desbloquear

1. O owner fornece um PAT Supabase (`sbp_...`) em `C:\Users\csn19\.zcode\dif-secrets\supabase-pat.txt` **ou** roda `npx supabase login`/`link --project-ref zottgifcocnjguhmnezx` **ou** fornece a database password por arquivo privado.
2. Antes de aplicar, gerar backup do schema hospedado (Management API/`pg_dump`) e confirmar que o schema atual é V1.
3. Dry-run (não lê o PAT):
```sh
SUPABASE_PROJECT_REF=zottgifcocnjguhmnezx node scripts/apply-hosted-migrations.mjs
```
4. Executar via arquivo de PAT (não coloque o segredo no histórico do shell):
```sh
SUPABASE_PROJECT_REF=zottgifcocnjguhmnezx \
node scripts/apply-hosted-migrations.mjs --execute \
--token-file "C:/Users/csn19/.zcode/dif-secrets/supabase-pat.txt" \
--confirm-project zottgifcocnjguhmnezx
```
O script recusa schema V2 já presente sem ledger, exige confirmação explícita do projeto, grava um ledger privado por migration aplicada, aceita `--resume` apenas com ledger correspondente e compara o conjunto exato de 41 tabelas (não apenas a contagem). `--from` anterior a `20261112170000` exige `--allow-v1` explícito.
5. Smoke: crie `.env.smoke` (ignorado pelo Git) com `PUBLIC_SUPABASE_URL`, `PUBLIC_SUPABASE_PUBLISHABLE_KEY` e `EXPECTED_SUPABASE_PROJECT_REF=zottgifcocnjguhmnezx`; `npm run release:smoke` usa `--env-file-if-exists=.env.smoke`, valida dono configurado, boundaries anônimos e marcadores V2; depois owner login, `/app/style`, `/app/timeline`, upload R2, download privado, render worker, MP4 1080×1920, backup/rollback.
6. Só depois promover o checkpoint final para **APROVADO**.

Saída atual de `npm run release:smoke` (2026-11-20): health/login/boundaries PASS; **7 tabelas V2 ausentes** (`video_assets`, `video_edit_plans`, `render_jobs`, `cover_revisions`, `choice_end_cards`, `published_posts`, `style_presets`), exit 1. Chave inválida é FAIL explícito (não conta como tabela presente). O script é read-only e impede declarar release completa com schema V1.

## Script de migrations

`scripts/apply-hosted-migrations.mjs`:

- dry-run por padrão; `--execute` explícito;
- exige PAT `sbp_...` (env ou `--token-file`) e confirmação `--confirm-project` do ref;
- recusa schema V2 já presente sem ledger correspondente; aceita `--resume` com ledger por projeto;
- aplica somente migrations a partir de `--from` (default `20261112170000`), em ordem;
- rejeita `--from` anterior ao V2 sem `--allow-v1`;
- não imprime token nem SQL; falha com HTTP/status e trecho normalizado;
- compara o conjunto exato de tabelas (14 V1 + 27 V2 = 41), reportando faltantes/extras.

## Pendências humanas/operacionais

- Aceitação real do owner com episódio Flow 90–150 s, 15 clipes, narração, SFX/música, legendas, CTA/2 escolhas, MP4 revisado (QA humano de som/imagem).
- Configurar/validar envs R2 no Vercel Production e worker isolado autorizado.
- Backup hospedado antes das migrations e ensaio de rollback/roll-forward.
- Cloudinary secret rotation e smoke de mídia privada.

## Riscos

- V2 code em produção sem schema V2 deixa rotas novas em 500 (V1 core continua 200). Não declarar release completa.
- As migrations são majoritariamente aditivas (também incluem grants/constraints), mas devem ser aplicadas com backup, em ordem e com ledger; o script falha fechado.
- Sem Vercel CLI, rollback de alias depende do dashboard/integração Git.
71 changes: 71 additions & 0 deletions docs/evidence/wo-014/tests.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# DIF-V2-WO-014 — release evidence

Date: 2026-11-20 (America/Sao_Paulo)
Branch: `feat/dif-v2-wo-014` (base `main` `7c175e5`)

## Local/CI baseline

- `main` code/test head V2 `f32cc97`: CI `44776291945` PASS — unit **351+3**,
PgTAP **247/247**, policy 35/41, E2E **19/19**. OPS `77d5626` has quality + Sonar PASS.
The docs-only `7c175e5` passed the quality workflow; the separate SonarCloud gate failed
on pre-existing duplication, not new application code.
- OPS head `77d5626`: CI `44787029917` PASS — unit **351+3**, PgTAP **247/247**,
policy **36/41**, E2E **19/19**, Sonar PASS.
- `main` docs checkpoints: `3950ccb` (WO-021) and `7c175e5` (OPS) passed the quality
workflow; both are docs-only, and the separate SonarCloud gate failed on pre-existing
duplication rather than new application code.
- Backup/restore local: 41/41 table counts, SHA verified, join 768, QA 5/5,
metadata/coverage OK; media fail-closed for 3 absent temp MP4s.

## Production observations (2026-11-20)

Authenticated owner session against `https://dif-studio.vercel.app`:

| Route | Status |
| --- | --- |
| `/health` | 200 |
| `/login` | 200 |
| `/app` | 200 |
| `/app/series` | 200 |
| `/app/episodes` | 200 |
| `/app/timeline` | timed out / V2 data unavailable |
| `/app/style` | **500 Internal Error** |

Hosted Supabase `zottgifcocnjguhmnezx`:

- `GET /rest/v1/style_presets` → HTTP 404 `PGRST205` (table missing);
- same for `cover_revisions` and other V2 tables;
- V1 tables/services remain reachable through the app.

## Credential preflight

- `npx supabase projects list` → `Invalid access token`.
- No `supabase-pat.txt` in `C:\Users\csn19\.zcode\dif-secrets`.
- No Vercel CLI credentials; production deploys come from the Git integration.
- Therefore the 29 V2 migrations cannot be applied and the release is **BLOCKED**.

## Release smoke (2026-11-20)

`npm run release:smoke` against production:

- PASS: `/health`, `/login`, anonymous boundaries for media/video/health/style.
- FAIL: 7 V2 schema markers missing (`video_assets`, `video_edit_plans`, `render_jobs`,
`cover_revisions`, `choice_end_cards`, `published_posts`, `style_presets`).
- Exit 1. Invalid-key run also exits 1 with `Supabase publishable/anon key is invalid`;
regression tests cover invalid key, RLS-coded 401/403 and PGRST205.
- Production must not be declared V2-complete.

## Migration runner dry-run

`SUPABASE_PROJECT_REF=zottgifcocnjguhmnezx node scripts/apply-hosted-migrations.mjs`
lists **29 migrations** from `20261112170000` and performs no network write in
dry-run. `--execute` requires an owner PAT (`--token-file` or env) and `--confirm-project`,
writes an atomic ledger, refuses V2 markers without `--resume`, and compares the exact
41-table set.

## Not yet executed

- Hosted migration apply/backup and production smoke.
- Worker isolated deployment/authorization.
- Real owner 90–150 s Flow acceptance and human AV QA.
- R2 lifecycle/GC, remote restore, Auth restore.
2 changes: 2 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,8 @@
"test:e2e:local": "node scripts/test-local-e2e.mjs",
"check:r2": "node scripts/check-r2.mjs",
"backup:metadata": "node scripts/backup-metadata.mjs",
"db:apply-hosted": "node scripts/apply-hosted-migrations.mjs",
"release:smoke": "node --env-file-if-exists=.env.smoke scripts/release-smoke.mjs",
"restore:metadata": "node scripts/restore-metadata.mjs",
"retention": "node scripts/retention.mjs",
"audit:policy": "node scripts/audit-policy.mjs",
Expand Down
184 changes: 184 additions & 0 deletions scripts/apply-hosted-migrations.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,184 @@
#!/usr/bin/env node
// Applies the additive V2 migrations to the hosted Supabase project through the
// Management API. Dry-run is the default. For execution the owner supplies a PAT
// via env or --token-file and confirms the project ref:
// SUPABASE_ACCESS_TOKEN="$(cat <private>/supabase-pat.txt)" \
// SUPABASE_PROJECT_REF=... node scripts/apply-hosted-migrations.mjs \
// --execute --confirm-project <ref>
// Never prints the token or full SQL responses.
import { existsSync } from 'node:fs';
import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises';
import { homedir } from 'node:os';
import { dirname, isAbsolute, join } from 'node:path';
import process from 'node:process';

async function main() {

Check failure on line 15 in scripts/apply-hosted-migrations.mjs

View check run for this annotation

SonarQubeCloud / SonarCloud Code Analysis

Refactor this function to reduce its Cognitive Complexity from 28 to the 15 allowed.

See more on https://sonarcloud.io/project/issues?id=KayzenRoot_dep-instfinal&issues=AaH7aEl1KGlDiycmveaX&open=AaH7aEl1KGlDiycmveaX&pullRequest=70
const MIGRATION_DIR = 'supabase/migrations';
const DEFAULT_FROM = '20261112170000';
const V2_MARKERS = ['video_assets', 'video_edit_plans', 'render_jobs', 'style_presets'];

function option(name, fallback) {
const index = process.argv.indexOf(name);
return index >= 0 ? (process.argv[index + 1] ?? fallback) : fallback;
}

const from = option('--from', DEFAULT_FROM);
const execute = process.argv.includes('--execute');
const resume = process.argv.includes('--resume');
const allowV1 = process.argv.includes('--allow-v1');
const projectRef = process.env.SUPABASE_PROJECT_REF ?? '';
const tokenFile = option('--token-file', '');
const ledgerPath = option(
'--ledger',
join(homedir(), '.dif-studio', `hosted-migrations-${projectRef || 'unknown'}.json`),
);
const confirmProject = option('--confirm-project', '');

if (!/^\d{14}$/.test(from) || !/^[a-z0-9]{20}$/.test(projectRef))
throw new Error('Use --from YYYYMMDDHHMMSS and SUPABASE_PROJECT_REF (20 lowercase chars).');
if (from < DEFAULT_FROM && !allowV1)
throw new Error(
`--from before ${DEFAULT_FROM} requires --allow-v1 (V1 migrations are not idempotent).`,
);
if (!isAbsolute(ledgerPath)) throw new Error('--ledger must be an absolute path.');
if (tokenFile && !isAbsolute(tokenFile))
throw new Error('--token-file must be an absolute path.');

const allFiles = (await readdir(MIGRATION_DIR))
.filter((file) => file.endsWith('.sql'))
.sort((left, right) => left.localeCompare(right));
const files = allFiles.filter((file) => file.slice(0, 14) >= from);
if (files.length === 0) throw new Error('No migrations selected.');

async function expectedTableNames() {
const names = new Set();
for (const file of allFiles) {
const sql = await readFile(`${MIGRATION_DIR}/${file}`, 'utf8');

Check warning on line 56 in scripts/apply-hosted-migrations.mjs

View check run for this annotation

SonarQubeCloud / SonarCloud Code Analysis

Unexpected `await` inside a loop.

See more on https://sonarcloud.io/project/issues?id=KayzenRoot_dep-instfinal&issues=AaH7aEl1KGlDiycmveaY&open=AaH7aEl1KGlDiycmveaY&pullRequest=70
for (const match of sql.matchAll(/create table(?: if not exists)?\s+public\.(\w+)\s*\(/gi))
names.add(match[1]);
}
return names;
}

const expectedTables = await expectedTableNames();
if (!execute) {
console.log(
`Dry run: ${files.length} migrations from ${from} would be applied to ${projectRef}; ${expectedTables.size} public tables expected.`,
);
for (const file of files) console.log(`- ${file}`);
process.exit(0);
}

let token = process.env.SUPABASE_ACCESS_TOKEN ?? '';
if (!token && tokenFile) token = (await readFile(tokenFile, 'utf8')).trim();
if (!/^sbp_[A-Za-z0-9]+$/.test(token))
throw new Error('SUPABASE_ACCESS_TOKEN or --token-file must contain an owner PAT (sbp_...).');
if (confirmProject !== projectRef)
throw new Error(`Execution requires --confirm-project ${projectRef}.`);

let ledger = { projectRef, applied: [] };
if (existsSync(ledgerPath)) {
try {
const parsed = JSON.parse(await readFile(ledgerPath, 'utf8'));
if (parsed?.projectRef !== projectRef || !Array.isArray(parsed?.applied))
throw new Error('ledger does not belong to this project');
ledger = parsed;
} catch {
throw new Error(`Unreadable migration ledger at ${ledgerPath}; inspect before retrying.`);
}
}
console.log(`Target: ${projectRef}; ${files.length} migrations; ledger: ${ledgerPath}`);

async function query(sql) {
let response;
try {
response = await fetch(`https://api.supabase.com/v1/projects/${projectRef}/database/query`, {
method: 'POST',
headers: {
authorization: `Bearer ${token}`,
'content-type': 'application/json',
},
body: JSON.stringify({ query: sql }),
signal: AbortSignal.timeout(120_000),
});
} catch (cause) {
if (cause?.name === 'TimeoutError' || cause?.name === 'AbortError')
throw new Error('Management API timed out; inspect the project before retrying.', {
cause,
});
throw cause;
}
const text = await response.text();
if (!response.ok)
throw new Error(
`Management API HTTP ${response.status}: ${text.slice(0, 300).replaceAll(/\s+/g, ' ')}`,
);
try {
return JSON.parse(text);
} catch {
return text;
}
}

async function writeLedger() {
await mkdir(dirname(ledgerPath), { recursive: true, mode: 0o700 });
const temporary = `${ledgerPath}.tmp`;
await writeFile(temporary, JSON.stringify(ledger, null, 2), { mode: 0o600 });
await rename(temporary, ledgerPath);
}

await writeLedger();

const before = await query(
"select tablename from pg_tables where schemaname = 'public' order by tablename",
);
if (!Array.isArray(before))
throw new Error('Management API returned an unexpected table list; refusing to proceed.');
const present = new Set(before.map((row) => row.tablename));
const markers = V2_MARKERS.filter((table) => present.has(table));
if (markers.length > 0) {
if (!resume || ledger.applied.length === 0)
throw new Error(
`V2 schema already present (${markers.join(', ')}); use --resume only with a matching ledger, or inspect manually.`,
);
console.log(`Resuming from ledger with ${ledger.applied.length} applied migrations.`);
}

let appliedNow = 0;
let skipped = 0;
for (const file of files) {
if (ledger.applied.includes(file)) {
console.log(`SKIP ${file} (ledger)`);
skipped += 1;
continue;
}
const sql = await readFile(`${MIGRATION_DIR}/${file}`, 'utf8');

Check warning on line 155 in scripts/apply-hosted-migrations.mjs

View check run for this annotation

SonarQubeCloud / SonarCloud Code Analysis

Unexpected `await` inside a loop.

See more on https://sonarcloud.io/project/issues?id=KayzenRoot_dep-instfinal&issues=AaH6I__TXf_8hDfnBYgq&open=AaH6I__TXf_8hDfnBYgq&pullRequest=70
console.log(`Applying ${file}...`);
await query(sql);

Check warning on line 157 in scripts/apply-hosted-migrations.mjs

View check run for this annotation

SonarQubeCloud / SonarCloud Code Analysis

Unexpected `await` inside a loop.

See more on https://sonarcloud.io/project/issues?id=KayzenRoot_dep-instfinal&issues=AaH6I__TXf_8hDfnBYgr&open=AaH6I__TXf_8hDfnBYgr&pullRequest=70
ledger.applied.push(file);
await writeLedger();

Check warning on line 159 in scripts/apply-hosted-migrations.mjs

View check run for this annotation

SonarQubeCloud / SonarCloud Code Analysis

Unexpected `await` inside a loop.

See more on https://sonarcloud.io/project/issues?id=KayzenRoot_dep-instfinal&issues=AaH7aEl1KGlDiycmveaZ&open=AaH7aEl1KGlDiycmveaZ&pullRequest=70
appliedNow += 1;
console.log(`OK ${file}`);
}

const after = await query(
"select tablename from pg_tables where schemaname = 'public' order by tablename",
);
if (!Array.isArray(after))
throw new Error('Management API returned an unexpected post-apply table list.');
const actualTables = new Set(after.map((row) => row.tablename));
const missing = [...expectedTables].filter((table) => !actualTables.has(table));
const extra = [...actualTables].filter((table) => !expectedTables.has(table));
if (missing.length || extra.length)
throw new Error(
`Schema mismatch: missing=[${missing.join(', ')}], extra=[${extra.join(', ')}].`,
);
console.log(
`Applied ${appliedNow} new migrations (${skipped} skipped); ${actualTables.size} public tables match.`,
);
}

main().catch((cause) => {

Check warning on line 181 in scripts/apply-hosted-migrations.mjs

View check run for this annotation

SonarQubeCloud / SonarCloud Code Analysis

Prefer top-level await over using a promise chain.

See more on https://sonarcloud.io/project/issues?id=KayzenRoot_dep-instfinal&issues=AaH7aEl1KGlDiycmveaa&open=AaH7aEl1KGlDiycmveaa&pullRequest=70
console.error(`ERROR ${cause instanceof Error ? cause.message : String(cause)}`);
process.exitCode = 1;
});
23 changes: 23 additions & 0 deletions scripts/release-smoke-lib.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
/** Pure schema-probe classification shared by the release smoke and its tests. */
/** @param {number} status @param {any} body */
export function classifyKeyPreflight(status, body) {
if (
status === 401 &&
(!body?.code ||
String(body?.message ?? '')
.toLowerCase()
.includes('api key'))
)
return 'invalid';
if (status === 200) return 'valid';
if ([401, 403].includes(status) && body?.code === '42501') return 'valid';
return 'unknown';
}

/** @param {number} status @param {any} body */
export function classifyTableProbe(status, body) {
if (status === 200) return 'present';
if (status === 404 && body?.code === 'PGRST205') return 'missing';
if ([401, 403].includes(status) && body?.code === '42501') return 'present';
return 'unknown';
}
Loading