fix(documents): backfill CLI --port arg guard

--port without a value (or with a --flag value) previously silently
fell back to all-ports mode because process.argv[indexOf+1] was
undefined. Now exits 1 with an explicit error. Hardens the script
before it gets wired into deploy in Task 17.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

scripts/backfill-document-folders.ts

@@ -49,9 +49,7 @@ export async function runBackfill(opts: BackfillOptions = {}): Promise<void> {
     await db.transaction(async (tx) => {
       // Serialize concurrent runs on a per-port lock so two simultaneous
       // backfills can't race on folder inserts.
-      await tx.execute(
-        sql`SELECT pg_advisory_xact_lock(hashtext(${portId})::bigint)`,
-      );
+      await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtext(${portId})::bigint)`);
 
       // ── Step 1: Ensure system roots exist for this port ──────────────────
       await ensureSystemRoots(portId, systemUser);
@@ -108,11 +106,7 @@ export async function runBackfill(opts: BackfillOptions = {}): Promise<void> {
           .update(files)
           .set(update)
           .where(
-            and(
-              eq(files.id, d.signedFileId),
-              eq(files.portId, portId),
-              isNull(matchingFkColumn),
-            ),
+            and(eq(files.id, d.signedFileId), eq(files.portId, portId), isNull(matchingFkColumn)),
           );
       }
 
@@ -156,19 +150,24 @@ export async function runBackfill(opts: BackfillOptions = {}): Promise<void> {
 // is the standard guard. The test suite imports `runBackfill` as a named
 // export; the CLI invocation hits this block and runs main().
 
-async function main(): Promise<void> {
+if (require.main === module) {
   const portIdArg = process.argv.indexOf('--port');
-  const portId = portIdArg !== -1 ? process.argv[portIdArg + 1] : undefined;
-
-  await runBackfill({ portId });
+  let portId: string | undefined;
+  if (portIdArg !== -1) {
+    const next = process.argv[portIdArg + 1];
+    if (!next || next.startsWith('--')) {
+      logger.error('--port requires a value');
+      process.exit(1);
+    }
+    portId = next;
+  }
+  runBackfill({ portId })
+    .then(() => {
       // eslint-disable-next-line no-console
       console.log('Backfill complete');
       process.exit(0);
-}
-
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-if (require.main === module) {
-  main().catch((err) => {
+    })
+    .catch((err) => {
       logger.error({ err }, 'Backfill failed');
       process.exit(1);
     });