scripts/backfill-document-storage-paths.ts
Rama main · réplica de lectura del repositorio original.
#!/usr/bin/env npx tsx
/**
* ============================================================================
* !! DESTRUCTIVE. READ THIS BEFORE YOU RUN ANYTHING. !!
* ============================================================================
*
* This script MOVES räkenskapsinformation. The objects it touches are kvitton,
* leverantorsfakturor and kontoutdrag held under the Bokforingslagen 7 kap 2 §
* SEVEN-YEAR RETENTION requirement. Losing one is a legal incident, not a bug.
*
* * ALWAYS run against STAGING first and confirm the counts there.
* * NEVER point this at .env.local. That file targets the REAL customer
* database. Pass --env <file> explicitly and read the banner it prints.
* * The default mode is --dry-run. Moving data requires the explicit
* --apply flag. Removing the source copies requires --apply AND
* --delete-source, which should be a SEPARATE run, days after --apply,
* once the app has been observed serving the new keys.
*
* ============================================================================
* WHAT IT DOES (Phase B of the 3-phase rollout)
* ============================================================================
*
* Phase A (migration 20260726092000_documents_bucket_company_scope.sql) added
* company-scoped storage policies for the key layout
*
* documents/{companyId}/{userId}/{timestamp}_{filename}
*
* and switched lib/core/documents/document-service.ts to write that layout.
* Legacy objects still sit at
*
* documents/{userId}/{timestamp}_{filename}
*
* where the RLS policy can only scope on auth.uid(), so a removed company
* member keeps read access to everything they ever uploaded.
*
* This script re-homes those legacy objects. Rows are grouped by storage key
* first: document_attachments.storage_path has NO unique constraint, so
* several rows can point at one object, and the object may only be released
* once every one of those rows has been repointed. Per source key, in order:
*
* 1. resolve the owning company_id(s) from document_attachments
* 2. skip rows whose storage_path is already company-scoped (idempotent /
* resumable)
* 3. COPY the object to the company-scoped key(s) (never move, never
* rename; one copy per owning company)
* 4. VERIFY each new key is readable and byte-identical (SHA-256 compared
* against document_attachments.sha256_hash when present, otherwise
* against the source bytes)
* 5. only then UPDATE storage_path for EVERY row on that key, checking the
* row count of each UPDATE: a row deleted between fetch and migrate
* must not count as migrated, or the fresh scoped copy would resurrect
* an erased document (a copy no row ended up pointing at is rolled
* back; the source is never touched by that rollback)
* 6. only with --delete-source, and only after 3-5 succeeded for ALL rows
* on the key AND the live table confirms zero rows still reference it,
* remove the legacy object
*
* A --delete-source run additionally SWEEPS rows that an earlier --apply run
* already repointed: their legacy key is derived from the scoped one (the
* forward mapping is a pure prefix insertion, so the inverse is exact), the
* scoped copy is re-verified (readable + hash), the live table is checked
* for remaining references, and only then is the leftover legacy object
* removed. Without this sweep the documented two-step workflow (--apply
* first, --delete-source days later) would be a no-op: after --apply no row
* carries a legacy pointer any more, yet every legacy object still sits in
* storage, readable by its uploader (including ex-members: the exact hole
* Phase A exists to close).
*
* The source is NEVER deleted before the new key has been confirmed readable
* and every referencing row repointed. A failure at any step logs the
* document id and the script continues to the next object; it never aborts
* the run on a single bad document.
*
* ============================================================================
* PHASE C GATE
* ============================================================================
*
* The final summary prints two counters:
*
* legacy_prefix_remaining rows still pointing at a legacy key
* legacy_objects_remaining legacy objects still present in storage for
* rows that are already company-scoped (found by
* the storage-level sweep, which runs read-only
* in every mode)
*
* Phase C (the migration that drops `documents_select_own` /
* `documents_insert_own`) may only be applied when a --dry-run of this
* script reports BOTH counters at 0. Dropping those policies earlier makes
* every un-migrated document unreadable to everyone except the service role,
* and leftover legacy objects would stay uploader-readable forever.
*
* ============================================================================
* USAGE
* ============================================================================
*
* # 1. Inspect. Changes nothing. This is the default.
* npx tsx scripts/backfill-document-storage-paths.ts --env .env.staging.local
*
* # 2. Copy + verify + repoint. Leaves the legacy objects in place.
* npx tsx scripts/backfill-document-storage-paths.ts --env .env.staging.local --apply
*
* # 3. Days later, after the app has been observed serving new keys:
* # migrates any stragglers, then sweeps the already-migrated rows and
* # removes their verified leftover legacy objects.
* npx tsx scripts/backfill-document-storage-paths.ts --env .env.staging.local --apply --delete-source
*
* Flags:
* --env <file> dotenv file to load. REQUIRED. No default: an implicit
* .env.local would point at production.
* --apply actually copy/verify/repoint. Without it: dry run.
* --delete-source additionally remove legacy objects whose every row has
* a verified company-scoped copy. Requires --apply.
* --company <uuid> restrict the run to one company. Use this for the first
* production batch.
* --limit <n> process at most n documents this run (resumable: run
* again to continue). A shared-key group is never split,
* so the last group may overshoot the limit. Also caps
* how many leftover legacy objects a --delete-source
* sweep removes.
* --yes skip the interactive confirmation prompt.
*/
import { createHash } from 'node:crypto'
import { basename, resolve } from 'node:path'
import { createInterface } from 'node:readline/promises'
import { config } from 'dotenv'
import { createClient, type SupabaseClient } from '@supabase/supabase-js'
const BUCKET = 'documents'
const PATH_ROOT = 'documents'
const PAGE_SIZE = 500
// ---------------------------------------------------------------------------
// Argument parsing
// ---------------------------------------------------------------------------
function flagValue(name: string): string | undefined {
const idx = process.argv.indexOf(`--${name}`)
if (idx === -1) return undefined
const value = process.argv[idx + 1]
if (!value || value.startsWith('--')) {
console.error(`--${name} requires a value`)
process.exit(1)
}
return value
}
const envFile = flagValue('env')
const apply = process.argv.includes('--apply')
const deleteSource = process.argv.includes('--delete-source')
const skipPrompt = process.argv.includes('--yes')
const onlyCompany = flagValue('company')
const limitRaw = flagValue('limit')
const limit = limitRaw ? Number.parseInt(limitRaw, 10) : Number.POSITIVE_INFINITY
if (!envFile) {
console.error(
'Refusing to run without an explicit --env <file>. An implicit .env.local ' +
'points at the PRODUCTION database. Example: --env .env.staging.local',
)
process.exit(1)
}
// Refuse .env.local no matter how the path is spelled ('./.env.local', an
// absolute path, backslashes on Windows): normalize before comparing. An
// exact string compare here was trivially bypassed by './.env.local'. The
// check runs BEFORE config() so the production env file is never even read.
if (basename(resolve(envFile)).toLowerCase() === '.env.local') {
console.error(
'REFUSING: .env.local points at the production database. If you really ' +
'intend to run against production, copy the credentials into an ' +
'explicitly named file (e.g. .env.production.backfill) so the intent ' +
'is recorded in the command line.',
)
process.exit(1)
}
if (deleteSource && !apply) {
console.error('--delete-source requires --apply.')
process.exit(1)
}
if (limitRaw && (!Number.isFinite(limit) || limit <= 0)) {
console.error('--limit must be a positive integer.')
process.exit(1)
}
config({ path: envFile })
const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL
const serviceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY
if (!supabaseUrl || !serviceRoleKey) {
console.error(`Missing NEXT_PUBLIC_SUPABASE_URL or SUPABASE_SERVICE_ROLE_KEY in ${envFile}`)
process.exit(1)
}
// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------
interface DocumentRow {
id: string
company_id: string | null
storage_path: string | null
file_name: string | null
mime_type: string | null
sha256_hash: string | null
}
interface Failure {
documentId: string
storagePath: string | null
step: string
reason: string
}
/** All rows (possibly from several companies) that share one legacy key. */
interface PathGroup {
sourcePath: string
rows: DocumentRow[]
}
// ---------------------------------------------------------------------------
// Path helpers.
//
// Deliberately duplicated from lib/core/documents/document-service.ts instead
// of imported: this script runs standalone under tsx and must not drag the
// service module's Next.js/event-bus imports into a plain node process. Keep
// the two in sync if the layout ever changes again.
// ---------------------------------------------------------------------------
function isCompanyScoped(storagePath: string, companyId: string): boolean {
return storagePath.startsWith(`${PATH_ROOT}/${companyId}/`)
}
function isLegacyDocumentPath(storagePath: string): boolean {
return storagePath.startsWith(`${PATH_ROOT}/`)
}
function companyScopedPath(storagePath: string, companyId: string): string | null {
if (isCompanyScoped(storagePath, companyId)) return null
if (!isLegacyDocumentPath(storagePath)) return null
return `${PATH_ROOT}/${companyId}/${storagePath.slice(`${PATH_ROOT}/`.length)}`
}
/**
* Inverse of companyScopedPath: derive the legacy key a company-scoped key
* was (or would have been) migrated from. The forward mapping is a pure
* prefix insertion, so the inverse is exact. Returns null when the key is
* not company-scoped for the given company.
*/
function legacyPathFor(storagePath: string, companyId: string): string | null {
const prefix = `${PATH_ROOT}/${companyId}/`
if (!storagePath.startsWith(prefix)) return null
return `${PATH_ROOT}/${storagePath.slice(prefix.length)}`
}
function sha256Hex(buffer: ArrayBuffer): string {
return createHash('sha256').update(Buffer.from(buffer)).digest('hex')
}
// ---------------------------------------------------------------------------
// Safety banner + confirmation
// ---------------------------------------------------------------------------
function projectRef(url: string): string {
try {
return new URL(url).hostname.split('.')[0] ?? url
} catch {
return url
}
}
async function confirmOrExit(): Promise<void> {
const ref = projectRef(supabaseUrl!)
console.log('')
console.log('='.repeat(78))
console.log(' documents bucket backfill: legacy uploader-scoped keys -> company-scoped')
console.log('='.repeat(78))
console.log(` env file : ${envFile}`)
console.log(` supabase project: ${ref}`)
console.log(` mode : ${apply ? 'APPLY (writes data)' : 'DRY RUN (no changes)'}`)
console.log(` delete source : ${deleteSource ? 'YES (legacy objects removed)' : 'no'}`)
console.log(` company filter : ${onlyCompany ?? '(all companies)'}`)
console.log(` limit : ${Number.isFinite(limit) ? limit : '(none)'}`)
console.log('='.repeat(78))
console.log('')
if (!apply || skipPrompt) return
const rl = createInterface({ input: process.stdin, output: process.stdout })
const answer = await rl.question(
`Type the project ref (${ref}) to proceed, anything else to abort: `,
)
rl.close()
if (answer.trim() !== ref) {
console.error('Aborted.')
process.exit(1)
}
}
// ---------------------------------------------------------------------------
// Data access
// ---------------------------------------------------------------------------
/**
* Page through document_attachments. PostgREST caps a single response at
* 1000 rows, so never rely on an unbounded select here.
*/
async function fetchAllDocuments(supabase: SupabaseClient): Promise<DocumentRow[]> {
const rows: DocumentRow[] = []
let from = 0
for (;;) {
let query = supabase
.from('document_attachments')
.select('id, company_id, storage_path, file_name, mime_type, sha256_hash')
.not('storage_path', 'is', null)
// created_at alone is not unique: without the id tiebreaker, rows
// sharing a timestamp can be skipped or duplicated across .range()
// pages, and a skipped row silently stays on the legacy key.
.order('created_at', { ascending: true })
.order('id', { ascending: true })
.range(from, from + PAGE_SIZE - 1)
if (onlyCompany) query = query.eq('company_id', onlyCompany)
const { data, error } = await query
if (error) throw new Error(`Failed to page document_attachments: ${error.message}`)
if (!data || data.length === 0) break
rows.push(...(data as DocumentRow[]))
if (data.length < PAGE_SIZE) break
from += PAGE_SIZE
}
return rows
}
async function objectExists(supabase: SupabaseClient, path: string): Promise<boolean> {
const segments = path.split('/')
const name = segments.pop()!
const folder = segments.join('/')
const { data, error } = await supabase.storage.from(BUCKET).list(folder, { search: name })
// Surface list failures instead of treating them as "missing": a transient
// error must never make a leftover object look already-swept.
if (error) throw new Error(`Failed to list ${folder}: ${error.message}`)
return !!data?.some((entry) => entry.name === name)
}
/**
* Authoritative check that at least one document_attachments row still points
* at the given storage key. Deliberately queries the LIVE table rather than
* this run's in-memory snapshot: a --company or --limit window, a
* NULL-company row, or a concurrent writer must never be able to hide a row
* whose only object the key is.
*/
async function pathStillReferenced(supabase: SupabaseClient, path: string): Promise<boolean> {
const { data, error } = await supabase
.from('document_attachments')
.select('id')
.eq('storage_path', path)
.limit(1)
if (error) throw new Error(`Failed to check references for ${path}: ${error.message}`)
return (data?.length ?? 0) > 0
}
/**
* Remove a legacy object, but only when the live table confirms zero rows
* still reference it. Every caller has already verified a company-scoped
* copy for every row that pointed here; this function is the ONLY place the
* script deletes a legacy source object. Returns true when the object was
* actually removed.
*/
async function removeLegacySourceIfUnreferenced(
supabase: SupabaseClient,
legacyPath: string,
): Promise<boolean> {
try {
if (await pathStillReferenced(supabase, legacyPath)) {
console.warn(` [${legacyPath}] source kept: still referenced by at least one row`)
return false
}
} catch (err) {
console.warn(
` [${legacyPath}] source kept: reference check failed: ${
err instanceof Error ? err.message : String(err)
}`,
)
return false
}
const { error: removeError } = await supabase.storage.from(BUCKET).remove([legacyPath])
if (removeError) {
console.warn(` [${legacyPath}] source not removed: ${removeError.message}`)
return false
}
return true
}
// ---------------------------------------------------------------------------
// Per-object migration (all rows sharing one legacy key, together)
// ---------------------------------------------------------------------------
interface TargetState {
targetPath: string
copyHash: string
uploadedThisRun: boolean
repointed: number
}
async function migrateGroup(
supabase: SupabaseClient,
group: PathGroup,
failures: Failure[],
): Promise<{ migratedRows: number; failedRows: number; sourceRemoved: boolean }> {
const { sourcePath, rows } = group
const fail = (row: DocumentRow, step: string, reason: string) => {
failures.push({ documentId: row.id, storagePath: sourcePath, step, reason })
}
// ---- 3. COPY (never move: the source must survive until step 6).
// Downloaded once per key: several rows can share the object. ------------
const { data: sourceBlob, error: downloadError } = await supabase.storage
.from(BUCKET)
.download(sourcePath)
if (downloadError || !sourceBlob) {
const reason = downloadError?.message ?? 'no data returned'
for (const row of rows) fail(row, 'download-source', reason)
return { migratedRows: 0, failedRows: rows.length, sourceRemoved: false }
}
const sourceBytes = await sourceBlob.arrayBuffer()
const sourceHash = sha256Hex(sourceBytes)
// One scoped target per company referencing this source key: rows from
// different companies sharing one object each get their own copy.
const companies = [...new Set(rows.map((row) => row.company_id!))]
const targets = new Map<string, TargetState>()
for (const companyId of companies) {
const companyRows = rows.filter((row) => row.company_id === companyId)
const targetPath = companyScopedPath(sourcePath, companyId)!
let uploadedThisRun = false
try {
// An already-present target means a previous run got this far: fall
// through to verification rather than failing on the upsert:false
// conflict.
if (!(await objectExists(supabase, targetPath))) {
const { error: uploadError } = await supabase.storage
.from(BUCKET)
.upload(targetPath, sourceBytes, {
contentType: companyRows[0]!.mime_type ?? 'application/octet-stream',
upsert: false,
})
if (uploadError) {
for (const row of companyRows) fail(row, 'upload-copy', uploadError.message)
continue
}
uploadedThisRun = true
}
} catch (err) {
const reason = err instanceof Error ? err.message : String(err)
for (const row of companyRows) fail(row, 'upload-copy', reason)
continue
}
// ---- 4. VERIFY the new key is readable, once per target --------------
const { data: copyBlob, error: verifyError } = await supabase.storage
.from(BUCKET)
.download(targetPath)
if (verifyError || !copyBlob) {
const reason = verifyError?.message ?? 'copy not readable at the new key'
for (const row of companyRows) fail(row, 'verify-readable', reason)
continue
}
targets.set(companyId, {
targetPath,
copyHash: sha256Hex(await copyBlob.arrayBuffer()),
uploadedThisRun,
repointed: 0,
})
}
let migratedRows = 0
for (const row of rows) {
const target = targets.get(row.company_id!)
if (!target) continue // upload/readability failure already recorded above
// The stored hash is the strongest reference; fall back to the source
// bytes for rows written before sha256_hash was populated.
const expectedHash = row.sha256_hash ?? sourceHash
if (target.copyHash !== expectedHash) {
fail(row, 'verify-hash', `copy hash ${target.copyHash} does not match expected ${expectedHash}`)
continue
}
// ---- 5. Repoint the DB, only now that the copy is proven. The row
// count matters: a row deleted between fetch and migrate makes this a
// 0-row UPDATE, which must NOT count as migrated (the scoped copy would
// resurrect an erased document). ---------------------------------------
const { data: updated, error: updateError } = await supabase
.from('document_attachments')
.update({ storage_path: target.targetPath })
.eq('id', row.id)
.select('id')
if (updateError) {
fail(row, 'update-pointer', updateError.message)
continue
}
if (!updated || updated.length === 0) {
fail(row, 'update-pointer', 'no row matched: deleted between fetch and migrate')
continue
}
target.repointed++
migratedRows++
}
// Roll back any scoped copy created THIS RUN that no row ended up pointing
// at, so it cannot linger as an unreferenced resurrected duplicate. Safe:
// the copy is seconds old, the live table confirms nothing references it,
// and the SOURCE object is never touched here.
for (const target of targets.values()) {
if (!target.uploadedThisRun || target.repointed > 0) continue
try {
if (await pathStillReferenced(supabase, target.targetPath)) continue
const { error: cleanupError } = await supabase.storage
.from(BUCKET)
.remove([target.targetPath])
if (cleanupError) {
console.warn(
` [${target.targetPath}] unreferenced fresh copy not rolled back: ${cleanupError.message}`,
)
}
} catch (err) {
console.warn(
` [${target.targetPath}] unreferenced fresh copy not rolled back: ${
err instanceof Error ? err.message : String(err)
}`,
)
}
}
const failedRows = rows.length - migratedRows
// ---- 6. Optional source removal, strictly last: only when EVERY row on
// this key is repointed, and the live table double-checks that. ----------
let sourceRemoved = false
if (deleteSource && failedRows === 0) {
sourceRemoved = await removeLegacySourceIfUnreferenced(supabase, sourcePath)
}
return { migratedRows, failedRows, sourceRemoved }
}
// ---------------------------------------------------------------------------
// Storage-level sweep over rows that are ALREADY company-scoped
// ---------------------------------------------------------------------------
interface SweepResult {
/** Distinct derived legacy keys whose object still exists in storage. */
keysWithLeftovers: number
objectsRemoved: number
}
/**
* An --apply run repoints rows and leaves the legacy objects behind, so a
* later --delete-source run can no longer find them through the pointers:
* it has to derive each legacy key from the scoped one (legacyPathFor) and
* check storage directly. For every derived key whose object still exists:
*
* - without --delete-source: count it (input to the Phase C gate)
* - with --delete-source: verify the scoped copy is readable and matches
* the expected hash for EVERY row mapping to the key, confirm via the
* live table that no row still references the key, and only then remove
* it (capped by --limit).
*/
async function sweepLegacyObjects(
supabase: SupabaseClient,
scopedRows: DocumentRow[],
skipKeys: Set<string>,
failures: Failure[],
deleteBudget: number,
): Promise<SweepResult> {
// Group scoped rows by derived legacy key: several rows (even from
// different companies) can map to one key, and the key may only be removed
// when every one of them has a verified scoped copy.
const byLegacyKey = new Map<string, DocumentRow[]>()
for (const row of scopedRows) {
const legacyKey = legacyPathFor(row.storage_path!, row.company_id!)
if (!legacyKey) continue
if (skipKeys.has(legacyKey)) continue // handled by this run's migration phase
const list = byLegacyKey.get(legacyKey)
if (list) list.push(row)
else byLegacyKey.set(legacyKey, [row])
}
const result: SweepResult = { keysWithLeftovers: 0, objectsRemoved: 0 }
for (const [legacyKey, rows] of byLegacyKey) {
let counted = false
try {
// Most keys belong to uploads born company-scoped: no legacy object
// ever existed for them, and this check is all they cost.
if (!(await objectExists(supabase, legacyKey))) continue
result.keysWithLeftovers++
counted = true
if (!deleteSource) continue // report-only: feeds legacy_objects_remaining
if (result.objectsRemoved >= deleteBudget) continue
// VERIFY: every row mapping to this key must have a readable scoped
// copy with the expected hash before the legacy object may go.
let allVerified = true
let legacyHash: string | null = null
for (const row of rows) {
const { data: copyBlob, error: copyError } = await supabase.storage
.from(BUCKET)
.download(row.storage_path!)
if (copyError || !copyBlob) {
failures.push({
documentId: row.id,
storagePath: legacyKey,
step: 'sweep-verify-readable',
reason: copyError?.message ?? 'scoped copy not readable',
})
allVerified = false
break
}
const copyHash = sha256Hex(await copyBlob.arrayBuffer())
let expectedHash = row.sha256_hash
if (!expectedHash) {
// No stored hash: the legacy bytes themselves are the reference.
if (legacyHash === null) {
const { data: legacyBlob, error: legacyError } = await supabase.storage
.from(BUCKET)
.download(legacyKey)
if (legacyError || !legacyBlob) {
failures.push({
documentId: row.id,
storagePath: legacyKey,
step: 'sweep-download-legacy',
reason: legacyError?.message ?? 'legacy object listed but not readable',
})
allVerified = false
break
}
legacyHash = sha256Hex(await legacyBlob.arrayBuffer())
}
expectedHash = legacyHash
}
if (copyHash !== expectedHash) {
failures.push({
documentId: row.id,
storagePath: legacyKey,
step: 'sweep-verify-hash',
reason: `scoped copy hash ${copyHash} does not match expected ${expectedHash}`,
})
allVerified = false
break
}
}
if (!allVerified) continue // stays counted as a leftover; gate stays closed
if (await removeLegacySourceIfUnreferenced(supabase, legacyKey)) {
console.log(
` [sweep] removed ${legacyKey} (${rows.length} row(s) verified at scoped keys)`,
)
result.objectsRemoved++
}
} catch (err) {
// Unknown state: count the key as remaining so the gate stays closed.
if (!counted) result.keysWithLeftovers++
failures.push({
documentId: rows[0]!.id,
storagePath: legacyKey,
step: 'sweep-unexpected',
reason: err instanceof Error ? err.message : String(err),
})
}
}
return result
}
// ---------------------------------------------------------------------------
// Main
// ---------------------------------------------------------------------------
async function main(): Promise<void> {
await confirmOrExit()
const supabase = createClient(supabaseUrl!, serviceRoleKey!, {
auth: { persistSession: false, autoRefreshToken: false },
})
const rows = await fetchAllDocuments(supabase)
const alreadyScoped: DocumentRow[] = []
const candidates: DocumentRow[] = []
const unmapped: DocumentRow[] = []
for (const row of rows) {
if (!row.storage_path) continue
if (!row.company_id) {
unmapped.push(row)
continue
}
if (isCompanyScoped(row.storage_path, row.company_id)) {
alreadyScoped.push(row)
} else if (isLegacyDocumentPath(row.storage_path)) {
candidates.push(row)
} else {
// Shapes this backfill deliberately does not touch, e.g. the MCP
// audit-package keys `{userId}/audit-packages/...` and the demo-seed
// `{userId}/{companyId}/inbox/...` keys. They are not covered by the
// documents_*_company policies and are not document_attachments
// underlag in the BFL sense.
unmapped.push(row)
}
}
// Group the legacy rows by source key: storage_path has no unique
// constraint, so several rows can share one object. The object is copied
// once, ALL its rows are repointed, and only then may the source go;
// migrating rows one by one deleted the source after the first row and
// stranded every later row on a dead pointer.
const groupsByPath = new Map<string, DocumentRow[]>()
for (const row of candidates) {
const list = groupsByPath.get(row.storage_path!)
if (list) list.push(row)
else groupsByPath.set(row.storage_path!, [row])
}
const groups: PathGroup[] = [...groupsByPath.entries()].map(([sourcePath, groupRows]) => ({
sourcePath,
rows: groupRows,
}))
console.log(`document_attachments rows with a storage_path : ${rows.length}`)
console.log(` already company-scoped : ${alreadyScoped.length}`)
console.log(
` legacy prefix, need migration : ${candidates.length} (${groups.length} distinct objects)`,
)
console.log(` outside the documents/ layout (skipped) : ${unmapped.length}`)
console.log('')
if (unmapped.length > 0) {
console.log('Skipped rows (first 20):')
for (const row of unmapped.slice(0, 20)) {
console.log(` ${row.id} company=${row.company_id ?? 'NULL'} path=${row.storage_path}`)
}
console.log('')
}
// --limit caps processed rows, but a shared-key group is never split:
// repointing only some of a key's rows would let a later --delete-source
// remove an object the remaining rows still need.
const batch: PathGroup[] = []
let batchRows = 0
for (const group of groups) {
if (batchRows >= limit) break
batch.push(group)
batchRows += group.rows.length
}
const failures: Failure[] = []
let migratedRows = 0
let sourcesRemoved = 0
// Groups fully migrated this run whose legacy object was (deliberately or
// not) left in storage: they count as leftover legacy objects below.
let sourcesKept = 0
if (!apply) {
console.log('DRY RUN: nothing was changed. Planned moves (first 20):')
const preview = batch.flatMap((group) => group.rows).slice(0, 20)
for (const row of preview) {
console.log(` ${row.id}`)
console.log(` from ${row.storage_path}`)
console.log(` to ${companyScopedPath(row.storage_path!, row.company_id!)}`)
}
console.log('')
} else {
for (const [index, group] of batch.entries()) {
const progress = `${index + 1}/${batch.length}`
const rowCount = group.rows.length
console.log(
`[${progress}] ${group.sourcePath} (${rowCount} row${rowCount === 1 ? '' : 's'})`,
)
try {
const outcome = await migrateGroup(supabase, group, failures)
migratedRows += outcome.migratedRows
if (outcome.failedRows === 0) {
if (outcome.sourceRemoved) sourcesRemoved++
else sourcesKept++
}
} catch (err) {
// Never abort the run on one bad object.
const reason = err instanceof Error ? err.message : String(err)
for (const row of group.rows) {
failures.push({
documentId: row.id,
storagePath: group.sourcePath,
step: 'unexpected',
reason,
})
}
}
}
}
// Storage-level sweep over already-migrated rows. Without it, an --apply
// run followed by a later --delete-source run finds zero legacy POINTERS
// and deletes nothing, while every legacy OBJECT still sits in the bucket
// readable by its uploader. Read-only unless --delete-source; the keys
// this run already handled as migration sources are skipped.
console.log('')
console.log(
`Sweeping ${alreadyScoped.length} already-scoped row(s) for leftover legacy objects` +
(deleteSource ? ' (verify + delete)...' : ' (read-only)...'),
)
const batchSourcePaths = new Set(batch.map((group) => group.sourcePath))
const sweep = await sweepLegacyObjects(
supabase,
alreadyScoped,
batchSourcePaths,
failures,
limit,
)
const legacyRowsRemaining = candidates.length - migratedRows
const legacyObjectsRemaining =
sweep.keysWithLeftovers - sweep.objectsRemoved + sourcesKept
console.log('')
console.log('='.repeat(78))
console.log(` rows migrated : ${migratedRows}`)
console.log(` failures : ${failures.length}`)
console.log(` legacy objects removed : ${sourcesRemoved + sweep.objectsRemoved}`)
console.log(` legacy_prefix_remaining : ${legacyRowsRemaining}`)
console.log(` legacy_objects_remaining : ${legacyObjectsRemaining}`)
console.log('='.repeat(78))
if (failures.length > 0) {
console.log('')
console.log('Failures (document id / step / reason):')
for (const failure of failures) {
console.log(` ${failure.documentId} [${failure.step}] ${failure.reason}`)
console.log(` path: ${failure.storagePath}`)
}
}
// The gate needs BOTH counters at zero: rows still on legacy pointers make
// documents unreadable after Phase C, and leftover legacy objects keep the
// uploader-scoped read hole open.
const gateOpen =
legacyRowsRemaining === 0 && legacyObjectsRemaining === 0 && failures.length === 0
console.log('')
if (gateOpen) {
console.log(
apply
? 'PHASE C GATE: OPEN. Re-run with --dry-run to confirm, then apply the Phase C migration.'
: 'PHASE C GATE: OPEN. Zero legacy-prefix rows and zero leftover legacy objects; the Phase C migration may be applied.',
)
} else {
const next =
legacyRowsRemaining > 0
? 'Run with --apply until legacy_prefix_remaining reaches 0.'
: legacyObjectsRemaining > 0
? 'Run with --apply --delete-source to remove the leftover legacy objects.'
: 'Resolve the failures above and re-run.'
console.log(
`PHASE C GATE: CLOSED. Do NOT drop documents_select_own / documents_insert_own yet. ${next}`,
)
}
// Non-zero exit on failures so a CI/ops wrapper notices, but only AFTER the
// full report has been printed.
if (failures.length > 0) process.exitCode = 1
}
main().catch((err) => {
console.error(err)
process.exit(1)
})