@ductape/cli 0.2.23 → 0.3.0

package/dist/commands/migrate-codebase.js

@@ -0,0 +1,753 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { createProduct, getProduct } from '../lib/platform-api.js';
+import { requireWorkspaceContext } from '../lib/workspace-context.js';
+import { printJson } from '../lib/output.js';
+import { validateMigrationE2EBaseline } from './migration-e2e.js';
+import { writeMigrationJson } from '../lib/migration-artifact.js';
+const IGNORED_DIRECTORIES = new Set([
+    '.git', '.gradle', '.idea', '.next', '.nuget', '.turbo', '.venv',
+    'bin', 'build', 'coverage', 'dist', 'node_modules', 'obj', 'target', 'vendor',
+]);
+const TEXT_EXTENSIONS = new Set([
+    '.bzl', '.cs', '.csproj', '.env', '.go', '.gradle', '.java', '.js', '.json', '.jsx', '.kt',
+    '.graphql', '.groovy', '.md', '.prisma', '.properties', '.proto', '.sh', '.sql', '.tf', '.tfvars', '.toml',
+    '.ts', '.tsx', '.xml', '.yaml', '.yml',
+]);
+function walk(root) {
+    const files = [];
+    const visit = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+            if (entry.isDirectory() && IGNORED_DIRECTORIES.has(entry.name))
+                continue;
+            const fullPath = path.join(directory, entry.name);
+            if (entry.isDirectory())
+                visit(fullPath);
+            else if (entry.isFile())
+                files.push(fullPath);
+        }
+    };
+    visit(root);
+    return files;
+}
+function skippedSymlinks(root) {
+    const skipped = [];
+    const visit = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+            if (entry.isDirectory() && IGNORED_DIRECTORIES.has(entry.name))
+                continue;
+            const fullPath = path.join(directory, entry.name);
+            if (entry.isSymbolicLink())
+                skipped.push(relative(root, fullPath));
+            else if (entry.isDirectory())
+                visit(fullPath);
+        }
+    };
+    visit(root);
+    return skipped.sort();
+}
+function gitSubmodules(root) {
+    const file = path.join(root, '.gitmodules');
+    if (!fs.existsSync(file))
+        return [];
+    const result = [];
+    let current;
+    for (const line of fs.readFileSync(file, 'utf8').split(/\r?\n/)) {
+        const section = line.match(/^\s*\[submodule\s+"([^"]+)"\]\s*$/);
+        if (section) {
+            if (current?.path)
+                result.push({ name: current.name, path: current.path, url: current.url });
+            current = { name: section[1] };
+            continue;
+        }
+        const property = line.match(/^\s*(path|url)\s*=\s*(.+?)\s*$/);
+        if (current && property)
+            current[property[1]] = property[2];
+    }
+    if (current?.path)
+        result.push({ name: current.name, path: current.path, url: current.url });
+    return result;
+}
+function globPattern(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*\*/g, '::DOUBLE_STAR::')
+        .replace(/\*/g, '[^/]*')
+        .replace(/::DOUBLE_STAR::/g, '.*')
+        .replace(/\?/g, '[^/]');
+    return new RegExp(`^${escaped}$`);
+}
+function looksBinary(file) {
+    try {
+        const descriptor = fs.openSync(file, 'r');
+        const buffer = Buffer.alloc(8_192);
+        const length = fs.readSync(descriptor, buffer, 0, buffer.length, 0);
+        fs.closeSync(descriptor);
+        return buffer.subarray(0, length).includes(0);
+    }
+    catch {
+        return true;
+    }
+}
+function applyScanPolicy(root, files, opts) {
+    const included = [];
+    const exclusions = [];
+    const includeRules = opts.include.map(globPattern);
+    const excludeRules = opts.exclude.map(globPattern);
+    for (const file of files) {
+        const rel = relative(root, file);
+        let reason;
+        if (includeRules.length && !includeRules.some((rule) => rule.test(rel)))
+            reason = 'not matched by include policy';
+        else if (excludeRules.some((rule) => rule.test(rel)))
+            reason = 'matched exclude policy';
+        else if (fs.statSync(file).size > opts.maxFileBytes)
+            reason = `exceeds max_file_bytes (${opts.maxFileBytes})`;
+        else if (looksBinary(file))
+            reason = 'binary file';
+        if (reason)
+            exclusions.push({ file: rel, reason });
+        else
+            included.push(file);
+    }
+    return {
+        files: included,
+        policy: {
+            max_file_bytes: opts.maxFileBytes,
+            binary_files: 'exclude',
+            include_patterns: opts.include,
+            exclude_patterns: opts.exclude,
+            exclusions,
+        },
+    };
+}
+function relative(root, file) {
+    return path.relative(root, file).split(path.sep).join('/');
+}
+function readText(file) {
+    try {
+        if (fs.statSync(file).size > 2_000_000)
+            return '';
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+function slug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'app';
+}
+function isNotFoundError(error) {
+    const candidate = error;
+    const status = Number(candidate?.status ?? candidate?.statusCode ?? candidate?.response?.status);
+    return status === 404 || /\b404\b|not found|does not exist/i.test(String(candidate?.message ?? ''));
+}
+function detectLanguages(files) {
+    const found = new Set();
+    for (const file of files) {
+        const name = path.basename(file);
+        const ext = path.extname(file);
+        if (['.ts', '.tsx', '.js', '.jsx'].includes(ext) || name === 'package.json')
+            found.add('typescript');
+        if (ext === '.go' || name === 'go.mod')
+            found.add('go');
+        if (ext === '.java' || name === 'pom.xml' || name.startsWith('build.gradle'))
+            found.add('java');
+        if (ext === '.cs' || ext === '.csproj' || ext === '.sln')
+            found.add('dotnet');
+    }
+    return [...found];
+}
+function detectFrameworks(files, texts) {
+    const joined = [...texts.values()].join('\n');
+    const frameworks = new Set();
+    if (/@nestjs\/|from ['"]@nestjs/.test(joined))
+        frameworks.add('nestjs');
+    if (/express(?:['"/])|from ['"]express/.test(joined))
+        frameworks.add('express');
+    if (/org\.springframework|spring-boot/.test(joined))
+        frameworks.add('spring');
+    if (/Microsoft\.AspNetCore|WebApplication\.CreateBuilder/.test(joined))
+        frameworks.add('aspnet');
+    if (/github\.com\/gin-gonic\/gin/.test(joined))
+        frameworks.add('gin');
+    if (/github\.com\/labstack\/echo/.test(joined))
+        frameworks.add('echo');
+    if (files.some((file) => path.basename(file) === 'next.config.js' || path.basename(file) === 'next.config.ts'))
+        frameworks.add('nextjs');
+    if (/(?:from ['"]react['"]|["']react["']\s*:)/.test(joined))
+        frameworks.add('react');
+    if (/(?:from ['"]vue['"]|["']vue["']\s*:)/.test(joined))
+        frameworks.add('vue');
+    if (/(?:@angular\/core|angular\.json)/.test(joined))
+        frameworks.add('angular');
+    if (/(?:from ['"]svelte['"]|@sveltejs\/kit|svelte\.config)/.test(joined))
+        frameworks.add('svelte');
+    return [...frameworks];
+}
+function detectWorkspaceBoundaries(root, files) {
+    const relativeFiles = files.map((file) => relative(root, file));
+    const rules = [
+        ['bazel', (file) => /(?:^|\/)(?:WORKSPACE|WORKSPACE\.bazel|MODULE\.bazel|BUILD|BUILD\.bazel)$/.test(file)],
+        ['buck', (file) => /(?:^|\/)(?:BUCK|\.buckconfig)$/.test(file)],
+        ['pants', (file) => /(?:^|\/)(?:pants\.toml|pants)$/.test(file)],
+        ['nx', (file) => /(?:^|\/)(?:nx\.json|project\.json)$/.test(file)],
+        ['turborepo', (file) => /(?:^|\/)turbo\.json$/.test(file)],
+        ['maven', (file) => /(?:^|\/)pom\.xml$/.test(file)],
+        ['gradle', (file) => /(?:^|\/)(?:settings\.gradle(?:\.kts)?|build\.gradle(?:\.kts)?)$/.test(file)],
+        ['dotnet', (file) => /\.(?:sln|slnx|csproj)$/.test(file)],
+    ];
+    return rules.flatMap(([system, matches]) => {
+        const evidence = relativeFiles.filter(matches);
+        return evidence.length ? [{ system, evidence, requires_ai_review: true }] : [];
+    });
+}
+function detectWorkspaceUnits(root, files, boundaries) {
+    const boundaryFiles = boundaries.flatMap((boundary) => boundary.evidence);
+    const manifests = [
+        [/(?:^|\/)package\.json$/, 'node'],
+        [/(?:^|\/)go\.mod$/, 'go'],
+        [/(?:^|\/)pom\.xml$/, 'maven'],
+        [/(?:^|\/)build\.gradle(?:\.kts)?$/, 'gradle'],
+        [/\.(?:csproj|fsproj|vbproj)$/, 'dotnet'],
+        [/(?:^|\/)project\.json$/, 'nx'],
+    ];
+    return files.flatMap((file) => {
+        const manifest = relative(root, file);
+        const match = manifests.find(([pattern]) => pattern.test(manifest));
+        if (!match)
+            return [];
+        const directory = path.posix.dirname(manifest);
+        const nearest = boundaryFiles
+            .filter((candidate) => {
+            const boundaryDirectory = path.posix.dirname(candidate);
+            return boundaryDirectory === '.' || directory === boundaryDirectory || directory.startsWith(`${boundaryDirectory}/`);
+        })
+            .sort((a, b) => path.posix.dirname(b).length - path.posix.dirname(a).length)[0];
+        return [{
+                manifest,
+                kind: match[1],
+                ...(nearest ? { nearest_boundary: nearest } : {}),
+                ownership_status: 'contextual_review_required',
+            }];
+    });
+}
+function detectGeneratedSources(root, files) {
+    const headerPattern = /(?:code generated|auto[- ]generated|generated by|do not edit|swagger codegen|openapi generator|protoc)/i;
+    return files.flatMap((file) => {
+        const rel = relative(root, file);
+        const basename = path.basename(file);
+        const header = readText(file).slice(0, 2_000);
+        const pathEvidence = /(?:^|\/)(?:generated|gen|autogen)(?:\/|$)|\.g\.(?:cs|ts|java)$|\.generated\./i.test(rel);
+        const headerMatch = header.match(headerPattern)?.[0];
+        if (!pathEvidence && !headerMatch)
+            return [];
+        return [{
+                file: rel,
+                evidence: headerMatch ? `header marker: ${headerMatch}` : `generated-looking path/name: ${basename}`,
+                confidence: 'low',
+                requires_ai_review: true,
+            }];
+    });
+}
+function environmentFromFile(file) {
+    const name = path.basename(file).toLowerCase();
+    if (name.includes('production') || name.endsWith('.prod') || name.includes('.prd'))
+        return 'prd';
+    if (name.includes('staging') || name.includes('.stage'))
+        return 'stg';
+    if (name.includes('sandbox') || name.includes('.snd'))
+        return 'snd';
+    if (name.includes('test'))
+        return 'test';
+    if (name.includes('local') || name === '.env')
+        return 'local';
+    if (name.includes('development') || name.includes('.dev'))
+        return 'dev';
+    return 'unknown';
+}
+function detectSecrets(root, files) {
+    const secrets = [];
+    for (const file of files.filter((candidate) => path.basename(candidate).startsWith('.env'))) {
+        const environment = environmentFromFile(file);
+        for (const line of readText(file).split(/\r?\n/)) {
+            const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+            if (!match)
+                continue;
+            secrets.push({
+                key: match[1],
+                source: relative(root, file),
+                environment,
+                value: '[REDACTED]',
+            });
+        }
+    }
+    return secrets;
+}
+function detectSecretReferences(texts) {
+    const found = new Map();
+    const rules = [
+        ['github', /\$\{\{\s*secrets\.([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g],
+        ['gitlab', /\$\{?([A-Z][A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|KEY|CREDENTIAL)[A-Z0-9_]*)\}?/g],
+        ['jenkins', /\bcredentials\(\s*['"]([^'"]+)['"]\s*\)/g],
+        ['kubernetes', /\bsecretKeyRef\s*:\s*(?:\r?\n[ \t]+[^\n]*)*?\r?\n[ \t]+key\s*:\s*['"]?([A-Za-z0-9_.-]+)/g],
+        ['kubernetes', /\bremoteRef\s*:\s*(?:\r?\n[ \t]+[^\n]*)*?\r?\n[ \t]+key\s*:\s*['"]?([A-Za-z0-9_./-]+)/g],
+        ['spring', /\$\{([A-Za-z_][A-Za-z0-9_.-]*)(?::[^}]*)?\}/g],
+        ['dotnet', /(?:GetConnectionString\(\s*|Configuration\s*\[\s*)['"]([^'"]+)['"]/g],
+        ['dotnet', /<UserSecretsId>\s*([^<\r\n]+)\s*<\/UserSecretsId>/g],
+        ['terraform', /\bvar\.([A-Za-z_][A-Za-z0-9_]*)/g],
+        ['aws', /(?:secretsmanager|secret-id|secretId)[/:="'\s]+([A-Za-z0-9_./-]+)/gi],
+        ['gcp', /(?:secretmanager|secretVersion|secret-version)[/:="'\s]+([A-Za-z0-9_./-]+)/gi],
+        ['azure', /(?:vault\.azure\.net\/secrets\/|secretName\s*[:=]\s*['"])([A-Za-z0-9_.-]+)/gi],
+        ['docker', /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::?-[^}]*)?\}/g],
+        ['circleci', /\$\{?([A-Z][A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|KEY|CREDENTIAL)[A-Z0-9_]*)\}?/g],
+        ['azure_devops', /\$\(([A-Za-z_][A-Za-z0-9_.-]*(?:TOKEN|SECRET|PASSWORD|KEY|CREDENTIAL)[A-Za-z0-9_.-]*)\)/gi],
+    ];
+    for (const [source, text] of texts) {
+        for (const [system, pattern] of rules) {
+            const lower = source.toLowerCase();
+            const applicable = system === 'github' ? lower.includes('.github/workflows/') :
+                system === 'gitlab' ? lower.endsWith('.gitlab-ci.yml') || lower.endsWith('.gitlab-ci.yaml') :
+                    system === 'jenkins' ? /jenkinsfile|\.groovy$/.test(lower) :
+                        system === 'circleci' ? lower.includes('.circleci/') :
+                            system === 'azure_devops' ? /azure-pipelines.*\.ya?ml$/.test(lower) :
+                                system === 'spring' ? /application.*\.(?:properties|ya?ml)$|\.java$/.test(lower) :
+                                    system === 'dotnet' ? /\.(?:cs|csproj|fsproj|vbproj|json)$/.test(lower) :
+                                        system === 'terraform' ? /\.tf(?:vars)?$/.test(lower) :
+                                            system === 'docker' ? /docker-compose|compose\.ya?ml$|dockerfile/.test(lower) :
+                                                true;
+            if (!applicable)
+                continue;
+            for (const match of text.matchAll(pattern)) {
+                const key = match[1];
+                if (!key)
+                    continue;
+                const id = `${system}:${source}:${key}`;
+                found.set(id, {
+                    key,
+                    source,
+                    system,
+                    environment: environmentFromFile(source),
+                    value: '[NOT_READ]',
+                    requires_ai_review: true,
+                });
+            }
+        }
+        if (/kind\s*:\s*SealedSecret/i.test(text)) {
+            const block = text.match(/\bencryptedData\s*:\s*\r?\n((?:[ \t]+[A-Za-z0-9_.-]+\s*:[^\n]*\r?\n?)*)/i)?.[1] ?? '';
+            for (const line of block.split(/\r?\n/)) {
+                const key = line.match(/^\s+([A-Za-z0-9_.-]+)\s*:/)?.[1];
+                if (!key)
+                    continue;
+                found.set(`kubernetes:${source}:${key}`, {
+                    key, source, system: 'kubernetes', environment: environmentFromFile(source),
+                    value: '[NOT_READ]', requires_ai_review: true,
+                });
+            }
+        }
+    }
+    return [...found.values()];
+}
+function detectPotentialSecretExposures(texts) {
+    const findings = [];
+    const assignment = /\b(password|passwd|token|secret|api[_-]?key|private[_-]?key|connection[_-]?string)\b\s*[:=]\s*["'`]([^"'`\r\n]{8,})["'`]/ig;
+    for (const [source, text] of texts) {
+        for (const match of text.matchAll(assignment)) {
+            const candidate = match[2].trim();
+            if (/^(?:\$\{|\$Secret\{|process\.env|env\(|<|REDACTED|example|changeme)/i.test(candidate))
+                continue;
+            const label = match[1].toLowerCase();
+            const kind = label.includes('password') || label === 'passwd' ? 'password' :
+                label.includes('token') ? 'token' :
+                    label.includes('private') ? 'private_key' :
+                        label.includes('connection') ? 'connection_string' : 'secret';
+            findings.push({
+                source,
+                line: text.slice(0, match.index ?? 0).split(/\r?\n/).length,
+                kind,
+                fingerprint: crypto.createHash('sha256').update(candidate).digest('hex').slice(0, 16),
+                value: '[NOT_RETURNED]',
+                confidence: 'low',
+                requires_human_security_review: true,
+            });
+        }
+    }
+    return findings;
+}
+function normalizeEnvironment(value) {
+    const normalized = value.toLowerCase();
+    if (['production', 'prod', 'prd'].includes(normalized))
+        return 'prd';
+    if (['staging', 'stage', 'stg'].includes(normalized))
+        return 'stg';
+    if (['sandbox', 'snd'].includes(normalized))
+        return 'snd';
+    if (['development', 'develop', 'dev'].includes(normalized))
+        return 'dev';
+    if (['testing', 'test'].includes(normalized))
+        return 'test';
+    if (['local'].includes(normalized))
+        return 'local';
+    return undefined;
+}
+function detectEnvironments(root, files, texts, secrets) {
+    const found = new Set(secrets.map((item) => item.environment).filter((item) => item !== 'unknown'));
+    for (const file of files) {
+        const rel = relative(root, file).toLowerCase();
+        for (const token of rel.split(/[^a-z0-9]+/)) {
+            const env = normalizeEnvironment(token);
+            if (env)
+                found.add(env);
+        }
+    }
+    for (const text of texts.values()) {
+        for (const match of text.matchAll(/\b(?:DUCTAPE_ENV|NODE_ENV|ASPNETCORE_ENVIRONMENT|SPRING_PROFILES_ACTIVE|ENVIRONMENT)\s*[:=]\s*["']?([A-Za-z]+)["']?/gi)) {
+            const env = normalizeEnvironment(match[1]);
+            if (env)
+                found.add(env);
+        }
+    }
+    if (!found.size) {
+        found.add('snd');
+        found.add('prd');
+    }
+    return [...found];
+}
+function detectApis(texts) {
+    const found = new Map();
+    const urlPattern = /https?:\/\/([A-Za-z0-9.-]+)(?::\d+)?(\/[A-Za-z0-9_./?={}&%-]*)?/g;
+    for (const text of texts.values()) {
+        for (const match of text.matchAll(urlPattern)) {
+            const host = match[1].toLowerCase();
+            if (host === 'localhost' || host.startsWith('127.'))
+                continue;
+            const record = found.get(host) ?? { occurrences: 0, methods: new Set(), paths: new Set() };
+            record.occurrences += 1;
+            const context = text.slice(Math.max(0, (match.index ?? 0) - 100), (match.index ?? 0) + match[0].length + 100);
+            const method = context.match(/\b(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b/i)?.[1]?.toUpperCase();
+            if (method)
+                record.methods.add(method);
+            if (match[2])
+                record.paths.add(match[2].split('?')[0]);
+            found.set(host, record);
+        }
+    }
+    return [...found.entries()]
+        .sort((a, b) => b[1].occurrences - a[1].occurrences)
+        .map(([host, record]) => ({
+        host,
+        occurrences: record.occurrences,
+        methods: [...record.methods].sort(),
+        paths: [...record.paths].sort().slice(0, 50),
+        recommended_app_tag: slug(host.replace(/^api\./, '')),
+        confidence: 'low',
+        requires_ai_review: true,
+    }));
+}
+function detectDatabases(texts) {
+    const signatures = [
+        [/mongoose|mongodb(?:\+srv)?:\/\//i, 'mongodb'],
+        [/typeorm|sequelize|postgres(?:ql)?:\/\//i, 'postgresql'],
+        [/mysql2?|mysql:\/\//i, 'mysql'],
+        [/Microsoft\.EntityFrameworkCore|DbContext/i, 'entity-framework'],
+        [/org\.springframework\.data|JpaRepository|Hibernate/i, 'jpa'],
+        [/gorm\.io|database\/sql/i, 'go-sql'],
+    ];
+    const found = [];
+    for (const [file, text] of texts) {
+        for (const [pattern, kind] of signatures) {
+            if (pattern.test(text) && !found.some((item) => item.evidence === file && item.kind === kind)) {
+                found.push({ evidence: file, kind, confidence: 'low', requires_ai_review: true });
+            }
+        }
+    }
+    return found;
+}
+const FILE_REVIEW_CHECKLIST = [
+    'purpose and ownership',
+    'imports, dependencies, and callers',
+    'public interfaces, types, signatures, DTOs, event schemas, and serialized contracts',
+    'configuration and secret-name references',
+    'database reads, writes, transactions, schemas, and migrations',
+    'internal events, queues, schedules, and background work',
+    'external HTTP/API integrations and authentication',
+    'sessions, actor propagation, authorization, and privacy',
+    'cache, storage, notifications, graph, and vector usage',
+    'timeouts, retries, fallbacks, idempotency, and failure ownership',
+    'tests, invariants, public contracts, and shutdown behavior',
+    'functional behavior: inputs, outputs, validation, domain results, side effects, and externally visible behavior',
+    'frontend behavior where present: routes, render states, forms, accessibility, responsive layout, browser storage, authentication, SSR/hydration, realtime, analytics/privacy, performance, visual, and cross-browser behavior',
+    'happy-path and failure-path operational behavior that must remain equivalent',
+    'follow-up files that must be inspected before deciding',
+];
+function buildReviewQueue(root, files) {
+    return files
+        .filter((file) => {
+        const basename = path.basename(file);
+        return TEXT_EXTENSIONS.has(path.extname(file)) ||
+            basename.startsWith('.env') ||
+            ['Dockerfile', 'go.mod', 'pom.xml'].includes(basename) ||
+            basename.endsWith('.csproj') ||
+            basename.startsWith('build.gradle');
+    })
+        .map((file) => ({
+        file: relative(root, file),
+        review_status: 'pending',
+        inspect_for: FILE_REVIEW_CHECKLIST,
+        safety: path.basename(file).startsWith('.env') ? 'names_only' : 'normal',
+    }))
+        .sort((a, b) => a.file.localeCompare(b.file));
+}
+function buildPlan(source, files, scanPolicy, mode, destination, productTag, productName, databaseTag) {
+    const texts = new Map();
+    for (const file of files) {
+        const basename = path.basename(file);
+        if (basename.startsWith('.env')) {
+            // Secret files are parsed only by detectSecrets, which extracts names and discards values.
+            // Their contents must never influence hints that are returned to MCP.
+            texts.set(relative(source, file), '');
+        }
+        else if (TEXT_EXTENSIONS.has(path.extname(file)) ||
+            ['Dockerfile', 'Jenkinsfile'].includes(basename)) {
+            texts.set(relative(source, file), readText(file));
+        }
+    }
+    const migrations = files
+        .filter((file) => /(?:^|[/\\])(migrations?|flyway|liquibase|alembic)(?:[/\\]|$)/i.test(file))
+        .map((file) => relative(source, file));
+    const schemas = files
+        .filter((file) => /(?:schema\.(?:prisma|sql|json)|liquibase|changelog|dbcontext|entities?)/i.test(file))
+        .map((file) => relative(source, file));
+    const secrets = detectSecrets(source, files);
+    const environments = detectEnvironments(source, files, texts, secrets);
+    const apiCalls = detectApis(texts);
+    const migrationImports = migrations.map((migration, order) => ({
+        source: migration,
+        checksum: crypto.createHash('sha256').update(fs.readFileSync(path.join(source, migration))).digest('hex'),
+        order: order + 1,
+        status: 'manual_review_required',
+        reason: 'Ductape migrations must use portable reversible operations; source migrations are never executed or wrapped as raw SQL automatically.',
+    }));
+    const guidanceDirectory = path.join(destination, 'ductape', 'migration-guidance');
+    const planPath = path.join(guidanceDirectory, 'analysis.json');
+    const workspaceBoundaries = detectWorkspaceBoundaries(source, files);
+    return {
+        version: 2,
+        artifact_kind: 'ai_review_bootstrap',
+        authority: 'advisory_only',
+        source,
+        mode,
+        destination,
+        product: { tag: productTag, name: productName },
+        target_database: databaseTag,
+        languages: detectLanguages(files),
+        frameworks: detectFrameworks(files, texts),
+        workspace_boundaries: workspaceBoundaries,
+        workspace_units: detectWorkspaceUnits(source, files, workspaceBoundaries),
+        generated_source_hints: detectGeneratedSources(source, files),
+        scan_safety: {
+            symlinks_followed: false,
+            symlinks_skipped: skippedSymlinks(source),
+            git_submodules: gitSubmodules(source),
+        },
+        scan_policy: scanPolicy,
+        environments,
+        secrets,
+        secret_references: detectSecretReferences(texts),
+        potential_secret_exposures: detectPotentialSecretExposures(texts),
+        deterministic_hints: {
+            databases: detectDatabases(texts),
+            third_party_apis: apiCalls,
+        },
+        existing_migrations: migrations,
+        existing_schemas: schemas,
+        migration_imports: migrationImports,
+        conversion_warnings: [
+            'No schema or component decision was generated. The AI must inspect source context and record evidence before proposing assets.',
+        ],
+        review_queue: buildReviewQueue(source, files),
+        evidence_ledger_template: {
+            file: '',
+            purpose: '',
+            dependencies: [],
+            interfaces: [],
+            functional_parity_requirements: [],
+            operational_parity_requirements: [],
+            findings: [{
+                    kind: '',
+                    evidence: '',
+                    location: { start_line: 1, end_line: 1 },
+                    symbol: { kind: 'module', name: '' },
+                    classification: 'observed',
+                    confidence: 'low',
+                    requires_followup: [],
+                }],
+            decision: 'pending',
+        },
+        ai_working_standards: {
+            global: [
+                'Before migration inspection, create and pass the original project E2E suite, then bind its files, command, environment, and evidence in an immutable migration-e2e baseline.',
+                'Scanner findings are evidence, not implementation instructions.',
+                'The AI must inspect relevant source files and installed SDK APIs before editing.',
+                'The AI writes application code with normal editing tools; this planner never rewrites source code.',
+                'Do not change or invent public or internal interfaces, types, signatures, DTOs, event schemas, serialized formats, or error contracts unless the user explicitly authorizes that exact change.',
+                'Do not assume functionality from names, patterns, documentation, or scanner hints; trace implementations, callers, tests, configuration, and runtime effects.',
+                'Maintain full functional parity for inputs, outputs, validation, domain results, side effects, external contracts, and user-visible behavior.',
+                'Maintain full operational parity across successful behavior, failures, ordering, concurrency, transactions, retries, idempotency, authorization, observability, and shutdown.',
+                'If existing behavior is unclear, add or run characterization tests and report the uncertainty; never fabricate compatibility.',
+                'Preserve domain logic and public behavior unless the user explicitly authorizes a change.',
+                'Use Ductape Events for internal asynchronous boundaries and Apps/Actions for external APIs.',
+                'Propagate full sessions only for immediate work; use approved actor metadata or system context for durable work.',
+                'Make consumers idempotent and assign one bounded retry owner for each failure.',
+                'Build, test, rescan, reconcile assets, and smoke-test each migrated vertical slice.',
+                'The final migration gate must pass the exact original E2E command against the checksum-verified original suite.',
+            ],
+            languages: {
+                typescript: [
+                    'Inspect package exports and types before choosing @ductape/sdk or @ductape/nestjs APIs.',
+                    'Preserve dependency-injection boundaries and use canonical NestJS decorators when NestJS is present.',
+                    'Keep SDK lifecycle ownership explicit and close workers/connections during shutdown.',
+                ],
+                go: [
+                    'Propagate context.Context, cancellation, and typed errors through Ductape operations.',
+                    'Keep worker ownership and graceful shutdown explicit; do not hide goroutines in generated abstractions.',
+                ],
+                java: [
+                    'Preserve Spring dependency injection and transaction boundaries where present.',
+                    'Make executor ownership, cancellation, and asynchronous failure behavior explicit.',
+                ],
+                dotnet: [
+                    'Use dependency injection, configuration binding, hosted services, async/await, and CancellationToken.',
+                    'Preserve request scope and dispose SDK-owned resources through the host lifecycle.',
+                ],
+            },
+        },
+        output_paths: {
+            plan: planPath,
+            migration_evidence: path.join(guidanceDirectory, 'migration-evidence.json'),
+            review_ledger_template: path.join(guidanceDirectory, 'review-ledger.template.json'),
+            guide: path.join(guidanceDirectory, 'AI-MIGRATION-GUIDE.md'),
+        },
+        next_steps: [
+            'Preserve the passing original E2E baseline manifest as the acceptance oracle; never weaken or overwrite it during migration.',
+            `Ensure product "${productTag}" exists, then link the destination directory.`,
+            'Review detected environments and create missing product environments in Workbench.',
+            'Import selected local secret keys with the standalone CLI; never pass values through MCP.',
+            'Have the AI review every relevant file in review_queue, follow referenced files, and maintain an evidence ledger.',
+            'Only after contextual review may the AI propose a Ductape schema or component design.',
+            'Have the AI translate reviewed migration intent into reversible Ductape migrations; never execute evidence files.',
+            'Have the AI design one reusable Ductape App per external API and inspect every call site before editing.',
+            'Have the AI migrate one vertical slice, prove interface, functional, and operational parity, build, test, rescan, verify in snd, and report unresolved evidence.',
+        ],
+    };
+}
+function renderAiGuide(plan) {
+    const languageSections = plan.languages.map((language) => `### ${language}\n\n${plan.ai_working_standards.languages[language].map((rule) => `- ${rule}`).join('\n')}`).join('\n\n');
+    return `# Ductape AI Migration Guidance
+
+This directory contains advisory inspection artifacts. It contains no generated application code,
+no executable migrations, and no authoritative Ductape assets.
+
+## Mandatory boundary
+
+${plan.ai_working_standards.global.map((rule) => `- ${rule}`).join('\n')}
+
+## Detected language standards
+
+${languageSections || 'No supported server language was detected. The AI must inspect the repository before proceeding.'}
+
+## Workflow
+
+1. Before this plan, create missing project-level E2E tests, run them against the original codebase, and record a passing checksum-bound \`migration-e2e\` baseline.
+2. Use \`analysis.json.review_queue\` as a coverage queue, not as an architectural conclusion.
+3. Review each relevant file and record purpose, dependencies, observed evidence, uncertainty, and follow-up files.
+4. Follow callers, callees, wrappers, configuration, tests, and runtime entrypoints until each behavior is understood.
+5. Classify every ledger finding as observed, inferred, proposed, or confirmed.
+6. Treat deterministic hints as low-confidence navigation aids and verify them in source.
+7. Inspect installed SDK exports and types before proposing Ductape code.
+8. Produce a contextual migration map, including what must remain ordinary application code.
+9. Explain the design and flag ambiguous or destructive decisions.
+10. Edit code using normal AI coding tools, one vertical slice at a time.
+11. Build, test, re-review changed references, reconcile assets, and smoke-test in snd.
+12. As the final gate, run the exact original E2E command against the unchanged checksum-verified baseline suite, record final evidence, and require strict \`migration-e2e validate\`.
+
+Do not claim review coverage until every relevant queue entry is completed or explicitly excluded with a reason.
+`;
+}
+export function writeMigrationGuidance(plan) {
+    fs.mkdirSync(path.dirname(plan.output_paths.plan), { recursive: true });
+    writeMigrationJson(plan.output_paths.plan, plan, { createOnly: true });
+    writeMigrationJson(plan.output_paths.migration_evidence, plan.migration_imports, { createOnly: true });
+    writeMigrationJson(plan.output_paths.review_ledger_template, plan.evidence_ledger_template, { createOnly: true });
+    fs.writeFileSync(plan.output_paths.guide, renderAiGuide(plan));
+}
+export function inspectMigrationCodebase(opts) {
+    const source = path.resolve(opts.source);
+    if (!fs.statSync(source).isDirectory())
+        throw new Error(`Migration source is not a directory: ${source}`);
+    const mode = opts.mode ?? 'new-codebase';
+    if (mode !== 'in-place' && mode !== 'new-codebase') {
+        throw new Error(`Invalid migration mode "${mode}". Use in-place or new-codebase.`);
+    }
+    const destination = mode === 'in-place'
+        ? source
+        : path.resolve(opts.destination ?? `${source}-ductape`);
+    if (mode === 'new-codebase' && destination === source) {
+        throw new Error('new-codebase mode requires a destination different from the source');
+    }
+    const productTag = opts.product ?? slug(path.basename(source));
+    const productName = opts.name ?? path.basename(source);
+    const databaseTag = opts.database ?? `${productTag}-db`;
+    const maxFileBytes = opts.maxFileBytes ?? 2_000_000;
+    if (!Number.isSafeInteger(maxFileBytes) || maxFileBytes <= 0) {
+        throw new Error('maxFileBytes must be a positive integer.');
+    }
+    const scan = applyScanPolicy(source, walk(source), {
+        maxFileBytes,
+        include: opts.include ?? [],
+        exclude: opts.exclude ?? [],
+    });
+    return buildPlan(source, scan.files, scan.policy, mode, destination, productTag, productName, databaseTag);
+}
+export async function runMigrateCodebase(opts) {
+    const baseline = validateMigrationE2EBaseline(opts.e2eBaseline);
+    if (!baseline.ready) {
+        throw new Error(`Migration cannot start until the original E2E baseline is valid: ${baseline.blockers.join('; ')}`);
+    }
+    const plan = inspectMigrationCodebase({
+        source: opts.source ?? process.cwd(),
+        mode: opts.mode,
+        destination: opts.destination,
+        product: opts.product,
+        name: opts.name,
+        database: opts.database,
+        maxFileBytes: opts.maxFileBytes,
+        include: opts.include,
+        exclude: opts.exclude,
+    });
+    const productTag = plan.product.tag;
+    const productName = plan.product.name;
+    if (opts.ensureProduct) {
+        const context = requireWorkspaceContext({});
+        try {
+            const existing = await getProduct(context, { tag: productTag });
+            if (existing)
+                plan.product.exists = true;
+            else
+                throw Object.assign(new Error(`Product "${productTag}" was not found`), { status: 404 });
+        }
+        catch (error) {
+            if (!isNotFoundError(error))
+                throw error;
+            await createProduct(context, {
+                tag: productTag,
+                name: productName,
+                description: `Migrated from ${path.basename(plan.source)}`,
+            });
+            plan.product.created = true;
+        }
+    }
+    if (opts.write)
+        writeMigrationGuidance(plan);
+    printJson(plan, Boolean(opts.json));
+}