feat: refine ISAC design and prepare production deployment

scripts/environment-bootstrap-export.mjs

@@ -0,0 +1,54 @@
+import { spawnSync } from 'node:child_process';
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import process from 'node:process';
+
+const target = process.argv[2];
+if (!['staging', 'production'].includes(target)) {
+	console.error('Usage: node scripts/environment-bootstrap-export.mjs <staging|production> [output.json]');
+	process.exit(2);
+}
+const outputArgument = process.argv[3];
+const timestamp = new Date().toISOString().replaceAll(':', '-').replace(/\.\d{3}Z$/, 'Z');
+const outputPath = resolve(outputArgument || `./data/backups/shd-${target}-bootstrap-${timestamp}.json`);
+const temporaryBackupPath = `${outputPath}.database.json`;
+const databaseBackup = spawnSync(process.execPath, ['scripts/db-backup.mjs', temporaryBackupPath], {
+	cwd: process.cwd(),
+	stdio: 'inherit',
+	env: process.env
+});
+if (databaseBackup.error) throw databaseBackup.error;
+if (databaseBackup.status !== 0) throw new Error(`Database backup failed; no ${target} bootstrap bundle was created.`);
+
+async function collectFiles(directory, pattern) {
+	try {
+		const names = (await readdir(directory)).filter((name) => pattern.test(name)).sort();
+		return await Promise.all(names.map(async (name) => ({
+			name,
+			contentBase64: (await readFile(join(directory, name))).toString('base64')
+		})));
+	} catch (error) {
+		if (error?.code === 'ENOENT') return [];
+		throw error;
+	}
+}
+
+try {
+	const database = JSON.parse(await readFile(temporaryBackupPath, 'utf8'));
+	const avatars = await collectFiles(resolve(process.env.TDR_AVATAR_STORAGE_PATH || './data/avatars'), /^[0-9a-f-]{36}\.webp$/i);
+	const gameIcons = await collectFiles(resolve(process.env.TDR_GAME_ICON_STORAGE_PATH || './data/game-icons'), /^[a-z_]+-[0-9a-f-]{36}\.webp$/i);
+	const bundle = {
+		format: 'shd-build-environment-bootstrap',
+		version: 1,
+		target,
+		createdAt: new Date().toISOString(),
+		database,
+		files: { avatars, gameIcons }
+	};
+	await mkdir(dirname(outputPath), { recursive: true });
+	await writeFile(outputPath, `${JSON.stringify(bundle, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+	console.log(`${target} bootstrap bundle includes ${avatars.length} avatars and ${gameIcons.length} game-data icons.`);
+	console.log(`Bootstrap bundle: ${outputPath}`);
+} finally {
+	await rm(temporaryBackupPath, { force: true });
+}

scripts/environment-bootstrap-import.mjs

@@ -0,0 +1,115 @@
+import { connect } from '@tursodatabase/database';
+import { spawnSync } from 'node:child_process';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import process from 'node:process';
+
+const bundleArgument = process.argv.slice(2).find((argument) => !argument.startsWith('--'));
+const targetIndex = process.argv.indexOf('--target');
+const target = targetIndex >= 0 ? process.argv[targetIndex + 1] : '';
+const allowed = target === 'staging'
+	? process.env.ALLOW_STAGING_BOOTSTRAP === 'true'
+	: target === 'production'
+		? process.env.ALLOW_PRODUCTION_BOOTSTRAP === 'true'
+		: false;
+if (!bundleArgument || !process.argv.includes('--confirm-empty-target-replace') || !allowed) {
+	console.error('Environment bootstrap requires the matching ALLOW_*_BOOTSTRAP=true guard and:');
+	console.error('node scripts/environment-bootstrap-import.mjs <bundle.json> --target <staging|production> --confirm-empty-target-replace');
+	process.exit(2);
+}
+
+const bundlePath = resolve(bundleArgument);
+const bundle = JSON.parse(await readFile(bundlePath, 'utf8'));
+if (bundle?.format !== 'shd-build-environment-bootstrap' || bundle?.version !== 1 || bundle?.target !== target
+	|| bundle.database?.format !== 'shd-build-database-backup' || bundle.database?.version !== 1
+	|| !Array.isArray(bundle.database.tables) || !Array.isArray(bundle.files?.avatars)
+	|| !Array.isArray(bundle.files?.gameIcons)) {
+	throw new Error('The selected file is not a supported SHD.build bootstrap bundle for the selected target.');
+}
+for (const file of bundle.files.avatars) {
+	if (typeof file.name !== 'string' || !/^[0-9a-f-]{36}\.webp$/i.test(file.name) || typeof file.contentBase64 !== 'string') {
+		throw new Error('The bootstrap bundle contains an invalid avatar file.');
+	}
+}
+for (const file of bundle.files.gameIcons) {
+	if (typeof file.name !== 'string' || !/^[a-z_]+-[0-9a-f-]{36}\.webp$/i.test(file.name) || typeof file.contentBase64 !== 'string') {
+		throw new Error('The bootstrap bundle contains an invalid game-data icon file.');
+	}
+}
+
+const databasePath = resolve(process.env.TDR_DATABASE_PATH || `./data/shd-build-${target}.db`);
+const safetyBackup = spawnSync(process.execPath, ['scripts/db-backup.mjs'], {
+	cwd: process.cwd(),
+	stdio: 'inherit',
+	env: process.env
+});
+if (safetyBackup.error) throw safetyBackup.error;
+if (safetyBackup.status !== 0) throw new Error(`${target} safety backup failed; the target was not changed.`);
+
+const database = await connect(databasePath);
+for (const tableName of ['users', 'builds', 'audit_log', 'data_change_proposals']) {
+	const row = await (await database.prepare(`SELECT COUNT(*) AS count FROM "${tableName}"`)).get();
+	if (Number(row?.count ?? 0) > 0) {
+		throw new Error(`${target} bootstrap refused: target table "${tableName}" is not empty.`);
+	}
+}
+
+const targetTables = await (await database.prepare(`
+	SELECT name FROM sqlite_master
+	WHERE type='table' AND name NOT LIKE 'sqlite_%'
+	ORDER BY rowid
+`)).all();
+const targetNames = new Set(targetTables.map((row) => String(row.name)));
+const sourceNames = new Set(bundle.database.tables.map((table) => String(table.name)));
+for (const row of targetTables) {
+	if (!sourceNames.has(String(row.name))) {
+		throw new Error(`Bootstrap snapshot is missing target-schema table "${String(row.name)}".`);
+	}
+}
+const sourceOnlyTables = bundle.database.tables
+	.map((table) => String(table.name))
+	.filter((name) => !targetNames.has(name));
+if (sourceOnlyTables.length) {
+	console.log(`Skipping source-only legacy tables: ${sourceOnlyTables.join(', ')}`);
+}
+const quoteIdentifier = (identifier) => `"${String(identifier).replaceAll('"', '""')}"`;
+let restoredRows = 0;
+await database.exec('PRAGMA foreign_keys=OFF');
+await database.exec('BEGIN');
+try {
+	for (const row of [...targetTables].reverse()) {
+		await database.exec(`DELETE FROM ${quoteIdentifier(row.name)}`);
+	}
+	for (const table of bundle.database.tables.filter((candidate) => targetNames.has(candidate.name))) {
+		for (const row of table.rows) {
+			const columns = Object.keys(row);
+			if (!columns.length) continue;
+			const insert = await database.prepare(
+				`INSERT INTO ${quoteIdentifier(table.name)} (${columns.map(quoteIdentifier).join(', ')})
+				VALUES (${columns.map(() => '?').join(', ')})`
+			);
+			await insert.run(...columns.map((column) => row[column]));
+			restoredRows++;
+		}
+	}
+	await database.exec('COMMIT');
+} catch (error) {
+	await database.exec('ROLLBACK');
+	throw error;
+} finally {
+	await database.exec('PRAGMA foreign_keys=ON');
+}
+
+const avatarDirectory = resolve(process.env.TDR_AVATAR_STORAGE_PATH || './data/avatars');
+const gameIconDirectory = resolve(process.env.TDR_GAME_ICON_STORAGE_PATH || './data/game-icons');
+await mkdir(avatarDirectory, { recursive: true });
+await mkdir(gameIconDirectory, { recursive: true });
+for (const file of bundle.files.avatars) {
+	await writeFile(join(avatarDirectory, file.name), Buffer.from(file.contentBase64, 'base64'), { mode: 0o600 });
+}
+for (const file of bundle.files.gameIcons) {
+	await writeFile(join(gameIconDirectory, file.name), Buffer.from(file.contentBase64, 'base64'), { mode: 0o600 });
+}
+
+console.log(`Bootstrapped ${target} with ${restoredRows} database rows, ${bundle.files.avatars.length} avatars, and ${bundle.files.gameIcons.length} game-data icons.`);
+console.log(`Source bundle: ${bundlePath}`);