feat: implement robustness guards

scripts/guards/api-route-contract-guard.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+import fs from 'fs'
+import path from 'path'
+import process from 'process'
+import { pathToFileURL } from 'url'
+
+const root = process.cwd()
+const apiDir = path.join(root, 'src', 'app', 'api')
+
+export const API_HANDLER_ALLOWLIST = new Set([
+  'src/app/api/auth/[...nextauth]/route.ts',
+  'src/app/api/files/[...path]/route.ts',
+  'src/app/api/system/boot-id/route.ts',
+])
+
+export const PUBLIC_ROUTE_ALLOWLIST = new Set([
+  'src/app/api/auth/[...nextauth]/route.ts',
+  'src/app/api/auth/register/route.ts',
+  'src/app/api/cos/image/route.ts',
+  'src/app/api/files/[...path]/route.ts',
+  'src/app/api/storage/sign/route.ts',
+  'src/app/api/system/boot-id/route.ts',
+])
+
+const AUTH_CALL_PATTERNS = [
+  /\brequireUserAuth\s*\(/,
+  /\brequireProjectAuth\s*\(/,
+  /\brequireProjectAuthLight\s*\(/,
+]
+
+function fail(title, details = []) {
+  process.stderr.write(`\n[api-route-contract-guard] ${title}\n`)
+  for (const detail of details) {
+    process.stderr.write(`  - ${detail}\n`)
+  }
+  process.exit(1)
+}
+
+function walk(dir, out = []) {
+  if (!fs.existsSync(dir)) return out
+  const entries = fs.readdirSync(dir, { withFileTypes: true })
+  for (const entry of entries) {
+    if (entry.name === '.git' || entry.name === '.next' || entry.name === 'node_modules') continue
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      walk(fullPath, out)
+      continue
+    }
+    if (entry.name === 'route.ts') out.push(fullPath)
+  }
+  return out
+}
+
+function toRel(fullPath) {
+  return path.relative(root, fullPath).split(path.sep).join('/')
+}
+
+function hasApiHandlerWrapper(content) {
+  return /\bapiHandler\s*\(/.test(content)
+}
+
+function hasRequiredAuth(content) {
+  return AUTH_CALL_PATTERNS.some((pattern) => pattern.test(content))
+}
+
+export function inspectRouteContract(relPath, content) {
+  const violations = []
+
+  if (!API_HANDLER_ALLOWLIST.has(relPath) && !hasApiHandlerWrapper(content)) {
+    violations.push(`${relPath} missing apiHandler wrapper`)
+  }
+
+  if (!PUBLIC_ROUTE_ALLOWLIST.has(relPath) && !hasRequiredAuth(content)) {
+    violations.push(`${relPath} missing requireUserAuth/requireProjectAuth/requireProjectAuthLight`)
+  }
+
+  return violations
+}
+
+export function findApiRouteContractViolations(scanRoot = root) {
+  const routesRoot = path.join(scanRoot, 'src', 'app', 'api')
+  return walk(routesRoot)
+    .map((fullPath) => {
+      const relPath = path.relative(scanRoot, fullPath).split(path.sep).join('/')
+      const content = fs.readFileSync(fullPath, 'utf8')
+      return inspectRouteContract(relPath, content)
+    })
+    .flat()
+}
+
+export function main() {
+  if (!fs.existsSync(apiDir)) {
+    fail('Missing src/app/api directory')
+  }
+
+  const violations = walk(apiDir)
+    .map((fullPath) => {
+      const relPath = toRel(fullPath)
+      const content = fs.readFileSync(fullPath, 'utf8')
+      return inspectRouteContract(relPath, content)
+    })
+    .flat()
+
+  if (violations.length > 0) {
+    fail('Found API route contract violations', violations)
+  }
+
+  process.stdout.write(
+    `[api-route-contract-guard] OK routes=${walk(apiDir).length} public=${PUBLIC_ROUTE_ALLOWLIST.size} apiHandlerExceptions=${API_HANDLER_ALLOWLIST.size}\n`,
+  )
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main()
+}

scripts/guards/image-reference-normalization-guard.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+import fs from 'fs'
+import path from 'path'
+import process from 'process'
+import { pathToFileURL } from 'url'
+
+const root = process.cwd()
+const handlersDir = path.join(root, 'src', 'lib', 'workers', 'handlers')
+
+export const NORMALIZATION_HELPER_ALLOWLIST = new Set([
+  'src/lib/workers/handlers/image-task-handler-shared.ts',
+])
+
+const ACCEPTED_NORMALIZATION_MARKERS = [
+  /\bnormalizeReferenceImagesForGeneration\s*\(/,
+  /\bnormalizeToBase64ForGeneration\s*\(/,
+  /\bgenerateLabeledImageToCos\s*\(/,
+]
+
+function fail(title, details = []) {
+  process.stderr.write(`\n[image-reference-normalization-guard] ${title}\n`)
+  for (const detail of details) {
+    process.stderr.write(`  - ${detail}\n`)
+  }
+  process.exit(1)
+}
+
+function walk(dir, out = []) {
+  if (!fs.existsSync(dir)) return out
+  const entries = fs.readdirSync(dir, { withFileTypes: true })
+  for (const entry of entries) {
+    if (entry.name === '.git' || entry.name === '.next' || entry.name === 'node_modules') continue
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      walk(fullPath, out)
+      continue
+    }
+    if (entry.name.endsWith('.ts')) out.push(fullPath)
+  }
+  return out
+}
+
+function toRel(fullPath) {
+  return path.relative(root, fullPath).split(path.sep).join('/')
+}
+
+function usesGenerationReferenceImages(content) {
+  return /\bresolveImageSourceFromGeneration\s*\(/.test(content) && /\breferenceImages\s*:/.test(content)
+}
+
+function hasNormalizationMarker(content) {
+  return ACCEPTED_NORMALIZATION_MARKERS.some((pattern) => pattern.test(content))
+}
+
+export function inspectImageReferenceNormalization(relPath, content) {
+  if (NORMALIZATION_HELPER_ALLOWLIST.has(relPath)) return []
+  if (!usesGenerationReferenceImages(content)) return []
+  if (hasNormalizationMarker(content)) return []
+  return [
+    `${relPath} uses resolveImageSourceFromGeneration with referenceImages but does not reference normalizeReferenceImagesForGeneration/normalizeToBase64ForGeneration/generateLabeledImageToCos`,
+  ]
+}
+
+export function findImageReferenceNormalizationViolations(scanRoot = root) {
+  const scanDir = path.join(scanRoot, 'src', 'lib', 'workers', 'handlers')
+  return walk(scanDir)
+    .map((fullPath) => {
+      const relPath = path.relative(scanRoot, fullPath).split(path.sep).join('/')
+      const content = fs.readFileSync(fullPath, 'utf8')
+      return inspectImageReferenceNormalization(relPath, content)
+    })
+    .flat()
+}
+
+export function main() {
+  if (!fs.existsSync(handlersDir)) {
+    fail('Missing src/lib/workers/handlers directory')
+  }
+
+  const handlerFiles = walk(handlersDir)
+  const violations = handlerFiles
+    .map((fullPath) => {
+      const relPath = toRel(fullPath)
+      const content = fs.readFileSync(fullPath, 'utf8')
+      return inspectImageReferenceNormalization(relPath, content)
+    })
+    .flat()
+
+  if (violations.length > 0) {
+    fail('Found image reference normalization violations', violations)
+  }
+
+  process.stdout.write(
+    `[image-reference-normalization-guard] OK handlers=${handlerFiles.length} allowlist=${NORMALIZATION_HELPER_ALLOWLIST.size}\n`,
+  )
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main()
+}

scripts/guards/task-submit-compensation-guard.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+import fs from 'fs'
+import path from 'path'
+import process from 'process'
+import { pathToFileURL } from 'url'
+
+const root = process.cwd()
+const apiDir = path.join(root, 'src', 'app', 'api')
+const CREATE_PATTERN = /\.\s*create\s*\(/
+const SUBMIT_TASK_PATTERN = /\bsubmitTask\s*\(/
+const ROLLBACK_PATTERN = /rollback|compensat/i
+
+function fail(title, details = []) {
+  process.stderr.write(`\n[task-submit-compensation-guard] ${title}\n`)
+  for (const detail of details) {
+    process.stderr.write(`  - ${detail}\n`)
+  }
+  process.exit(1)
+}
+
+function walk(dir, out = []) {
+  if (!fs.existsSync(dir)) return out
+  const entries = fs.readdirSync(dir, { withFileTypes: true })
+  for (const entry of entries) {
+    if (entry.name === '.git' || entry.name === '.next' || entry.name === 'node_modules') continue
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      walk(fullPath, out)
+      continue
+    }
+    if (entry.name === 'route.ts') out.push(fullPath)
+  }
+  return out
+}
+
+function toRel(fullPath) {
+  return path.relative(root, fullPath).split(path.sep).join('/')
+}
+
+export function inspectTaskSubmitCompensation(relPath, content) {
+  if (!CREATE_PATTERN.test(content)) return []
+  if (!SUBMIT_TASK_PATTERN.test(content)) return []
+  if (ROLLBACK_PATTERN.test(content)) return []
+  return [
+    `${relPath} creates data before submitTask without explicit rollback/compensation marker`,
+  ]
+}
+
+export function findTaskSubmitCompensationViolations(scanRoot = root) {
+  const routesRoot = path.join(scanRoot, 'src', 'app', 'api')
+  return walk(routesRoot)
+    .map((fullPath) => {
+      const relPath = path.relative(scanRoot, fullPath).split(path.sep).join('/')
+      const content = fs.readFileSync(fullPath, 'utf8')
+      return inspectTaskSubmitCompensation(relPath, content)
+    })
+    .flat()
+}
+
+export function main() {
+  if (!fs.existsSync(apiDir)) {
+    fail('Missing src/app/api directory')
+  }
+
+  const routeFiles = walk(apiDir)
+  const violations = routeFiles
+    .map((fullPath) => {
+      const relPath = toRel(fullPath)
+      const content = fs.readFileSync(fullPath, 'utf8')
+      return inspectTaskSubmitCompensation(relPath, content)
+    })
+    .flat()
+
+  if (violations.length > 0) {
+    fail('Found create+submitTask routes without compensation marker', violations)
+  }
+
+  process.stdout.write(`[task-submit-compensation-guard] OK routes=${routeFiles.length}\n`)
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main()
+}