@ductape/cli 0.3.0 → 0.3.1

package/dist/commands/db-migrate.js

@@ -11,15 +11,41 @@ async function getAppliedTags(proxy, dbContext) {
         const result = await proxy.execute('migration.history', [], dbContext);
         const list = Array.isArray(result)
             ? result
-            : Array.isArray(result.data)
+            : result !== null
+                && typeof result === 'object'
+                && Array.isArray(result.data)
                 ? result.data
-                : [];
-        return list.map((r) => r.tag ?? '').filter(Boolean);
+                : null;
+        if (!Array.isArray(list)) {
+            throw new Error('migration.history returned an invalid response instead of a history array');
+        }
+        return list.map((entry, index) => {
+            if (entry === null || typeof entry !== 'object' || typeof entry.tag !== 'string') {
+                throw new Error(`migration.history returned an invalid entry at index ${index}`);
+            }
+            return entry.tag;
+        });
     }
-    catch {
-        return [];
+    catch (error) {
+        throw new Error(`Could not read migration history for ${dbContext.product}/${dbContext.database}:${dbContext.env}. ` +
+            'Migration state is unknown; no migrations were classified as pending.', { cause: error });
     }
 }
+function getMigrationResult(response, migrationTag) {
+    if (response === null || typeof response !== 'object')
+        return null;
+    const result = response[migrationTag];
+    if (result === null || typeof result !== 'object')
+        return null;
+    const success = result.success;
+    if (typeof success !== 'boolean')
+        return null;
+    const error = result.error;
+    return {
+        success,
+        ...(typeof error === 'string' ? { error } : {}),
+    };
+}
 export async function runDbMigrate(opts) {
     const found = findProjectConfig();
     if (!found)
@@ -59,13 +85,26 @@ export async function runDbMigrate(opts) {
             }
             process.stdout.write(`  Applying ${migration.tag}... `);
             try {
-                await proxy.execute('migration.run', [[migration]], dbContext);
+                const response = await proxy.execute('migration.run', [[migration]], dbContext);
+                const migrationResult = getMigrationResult(response, migration.tag);
+                if (migrationResult && !migrationResult.success) {
+                    throw new Error(migrationResult.error ?? 'SDK reported an unsuccessful migration');
+                }
+                // A successful HTTP response is not proof that the migration was
+                // recorded. Verify history before claiming success, including when
+                // talking to older proxies that serialize Map results as `{}`.
+                const appliedAfterRun = await getAppliedTags(proxy, dbContext);
+                if (!appliedAfterRun.includes(migration.tag)) {
+                    throw new Error('the operation returned without error, but the migration tag is absent from migration history');
+                }
                 console.log('done');
                 totalApplied++;
             }
             catch (err) {
-                console.log('failed');
-                fail(`Migration "${migration.tag}" failed: ${err instanceof Error ? err.message : String(err)}`);
+                console.log('unverified');
+                fail(`Migration "${migration.tag}" could not be verified: ` +
+                    `${err instanceof Error ? err.message : String(err)}. ` +
+                    'Do not rerun it until the live schema and migration history have been inspected.');
             }
         }
     }

package/dist/commands/migrate-codebase.d.ts

@@ -4,6 +4,18 @@ interface MigrationPlan {
     version: 2;
     artifact_kind: 'ai_review_bootstrap';
     authority: 'advisory_only';
+    execution_provenance?: {
+        mcp_client?: {
+            name: string;
+            version: string;
+            source: 'mcp_initialize_handshake';
+            trust: 'protocol_asserted_unverified';
+        };
+        ai_model: {
+            status: 'unavailable';
+            reason: 'MCP does not provide a server-verifiable model identity';
+        };
+    };
     source: string;
     mode: MigrationMode;
     destination: string;
@@ -172,5 +184,7 @@ export declare function runMigrateCodebase(opts: {
     ensureProduct?: boolean;
     write?: boolean;
     json?: boolean;
+    mcpClientName?: string;
+    mcpClientVersion?: string;
 }): Promise<void>;
 export {};

package/dist/commands/migrate-codebase.js

@@ -288,17 +288,26 @@ function detectSecretReferences(texts) {
     const found = new Map();
     const rules = [
         ['github', /\$\{\{\s*secrets\.([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g],
+        ['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],
+        ['gitlab', /\bvault\s*:\s*['"]?([A-Za-z0-9_./@-]+)/g],
         ['jenkins', /\bcredentials\(\s*['"]([^'"]+)['"]\s*\)/g],
+        ['jenkins', /\bcredentialsId\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],
+        ['kubernetes', /\b(?:secretName|secretProviderClass)\s*:\s*['"]?([A-Za-z0-9_.-]+)/g],
+        ['kubernetes', /\bsecretRef\s*:\s*(?:\r?\n[ \t]+[^\n]*)*?\r?\n[ \t]+name\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],
+        ['aws', /\{\{resolve:(?:secretsmanager|ssm-secure):([^}:]+)/gi],
+        ['aws', /arn:aws:secretsmanager:[^:\s]+:[^:\s]+:secret:([A-Za-z0-9_./+=@-]+)/gi],
         ['gcp', /(?:secretmanager|secretVersion|secret-version)[/:="'\s]+([A-Za-z0-9_./-]+)/gi],
+        ['gcp', /projects\/[^/\s]+\/secrets\/([A-Za-z0-9_-]+)/gi],
         ['azure', /(?:vault\.azure\.net\/secrets\/|secretName\s*[:=]\s*['"])([A-Za-z0-9_.-]+)/gi],
+        ['azure', /@Microsoft\.KeyVault\(\s*SecretUri=https:\/\/[^/\s]+\.vault\.azure\.net\/secrets\/([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],
@@ -727,6 +736,20 @@ export async function runMigrateCodebase(opts) {
     });
     const productTag = plan.product.tag;
     const productName = plan.product.name;
+    if (opts.mcpClientName && opts.mcpClientVersion) {
+        plan.execution_provenance = {
+            mcp_client: {
+                name: opts.mcpClientName,
+                version: opts.mcpClientVersion,
+                source: 'mcp_initialize_handshake',
+                trust: 'protocol_asserted_unverified',
+            },
+            ai_model: {
+                status: 'unavailable',
+                reason: 'MCP does not provide a server-verifiable model identity',
+            },
+        };
+    }
     if (opts.ensureProduct) {
         const context = requireWorkspaceContext({});
         try {

package/dist/commands/migration-artifact.d.ts

@@ -1,20 +1,15 @@
+type JsonSchema = {
+    $schema: string;
+    title: string;
+    type: 'object';
+    required: string[];
+    properties: Record<string, unknown>;
+    additionalProperties: boolean;
+};
 export declare const MIGRATION_ARTIFACT_SCHEMAS: {
     version: number;
-    artifacts: {
-        $schema: string;
-        title: string;
-        type: string;
-        required: string[];
-        properties: {
-            version: {
-                const: number;
-            };
-            artifact_kind: {
-                const: string;
-            };
-        };
-        additionalProperties: boolean;
-    }[];
+    artifacts: JsonSchema[];
+    definitions: JsonSchema[];
 };
 export declare function runMigrationArtifactValidate(opts: {
     file: string;
@@ -30,3 +25,4 @@ export declare function runMigrationArtifactMigrate(opts: {
     json?: boolean;
 }): void;
 export declare function runMigrationArtifactSchemas(json?: boolean): void;
+export {};

package/dist/commands/migration-artifact.js

@@ -1,39 +1,92 @@
 import path from 'node:path';
 import { printJson } from '../lib/output.js';
 import { migrateMigrationJson, readMigrationJson, recoverMigrationJson, } from '../lib/migration-artifact.js';
+const objectSchema = (title, required, properties = {}) => ({
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    title,
+    type: 'object',
+    required,
+    properties,
+    additionalProperties: true,
+});
+const artifact = (kind, required) => objectSchema(kind, ['version', 'artifact_kind', ...required], { version: { const: 1 }, artifact_kind: { const: kind } });
 export const MIGRATION_ARTIFACT_SCHEMAS = {
-    version: 1,
+    version: 2,
     artifacts: [
-        'ai_migration_review_ledger',
-        'ductape_migration_slice',
-        'ductape_migration_portfolio',
-        'ductape_migration_partition_proposal',
-        'ductape_migration_e2e_baseline',
-        'ductape_migration_generated_vendor_evidence',
-        'ductape_migration_assurance',
-        'ductape_migration_verification_matrix',
-        'ductape_database_baseline',
-        'ductape_database_data',
-        'ductape_database_cutover',
-        'ductape_review_ledger_signature',
-    ].map((artifact_kind) => ({
-        $schema: 'https://json-schema.org/draft/2020-12/schema',
-        title: artifact_kind,
-        type: 'object',
-        required: ['version', 'artifact_kind'],
-        properties: {
-            version: { const: 1 },
-            artifact_kind: { const: artifact_kind },
-        },
-        additionalProperties: true,
-    })),
+        artifact('ai_review_bootstrap', ['authority', 'source', 'mode', 'destination', 'review_queue']),
+        artifact('ai_migration_review_ledger', ['source', 'entries']),
+        artifact('ductape_migration_slice', ['tag', 'name', 'ledger', 'files', 'surfaces', 'product_boundary']),
+        artifact('ductape_migration_portfolio', ['ledger', 'partitions', 'slices', 'cross_slice_contracts']),
+        artifact('ductape_migration_partition_proposal', ['authority', 'ledger', 'limits', 'partitions']),
+        artifact('ductape_migration_e2e_baseline', ['source', 'created_at', 'command', 'suite', 'baseline', 'final']),
+        artifact('ductape_migration_generated_vendor_evidence', ['analysis', 'generated', 'vendor']),
+        artifact('ductape_migration_assurance', [
+            'session_flows', 'feature_resilience', 'third_party_calls', 'components',
+            'provider_migrations', 'runtime', 'sdk_matrix',
+        ]),
+        artifact('ductape_migration_verification_matrix', ['categories']),
+        artifact('ductape_database_baseline', [
+            'migration_id', 'database_tag', 'owners', 'providers', 'schema_snapshots',
+            'structural_comparison',
+        ]),
+        artifact('ductape_database_data', [
+            'migration_id', 'transformations', 'batching', 'checkpoints', 'idempotency',
+            'resume_strategy', 'validation', 'reconciliation',
+        ]),
+        artifact('ductape_database_cutover', [
+            'migration_id', 'phases', 'expand', 'backfill', 'dual_compatibility', 'contract',
+            'deployment_order', 'migration_locking', 'backup', 'restore_test', 'rollback',
+        ]),
+        artifact('ductape_review_ledger_signature', [
+            'ledger', 'ledger_sha256', 'algorithm', 'key_id', 'signature', 'signed_at',
+        ]),
+        artifact('ductape_service_product_map', ['analysis', 'mappings', 'assets', 'promotions']),
+        artifact('ductape_secret_migration_map', ['analysis', 'classifications']),
+        artifact('ductape_sdk_capability_matrix', ['authority', 'unsupported_policy', 'sdks']),
+    ],
+    definitions: [
+        objectSchema('migration_e2e_definition', ['command', 'suite_files', 'baseline']),
+        objectSchema('migration_e2e_final_evidence', ['command', 'status', 'evidence', 'environment', 'suite_root']),
+        objectSchema('migration_slice_definition', [
+            'surfaces', 'product_boundary', 'sdk_capabilities', 'interface_contracts',
+            'functional_requirements', 'operational_requirements', 'parity_evidence',
+            'frontend_parity', 'required_assets', 'tests', 'failure_tests', 'runtime_evidence',
+            'smoke_checks', 'cutover_conditions', 'rollback_conditions', 'deployment_cutover',
+        ]),
+        objectSchema('migration_portfolio_definition', ['partitions', 'slices', 'cross_slice_contracts']),
+        objectSchema('migration_database_definition', ['baseline', 'data', 'cutover']),
+        objectSchema('migration_product_map_definition', ['mappings', 'assets', 'promotions']),
+        objectSchema('migration_secret_map_definition', ['classifications']),
+        objectSchema('migration_generated_vendor_definition', ['generated', 'vendor']),
+        objectSchema('migration_review_record_definition', [
+            'purpose', 'dependencies', 'interfaces', 'functional_parity_requirements',
+            'operational_parity_requirements', 'findings',
+        ]),
+        objectSchema('migration_assurance_definition', [
+            'version', 'artifact_kind', 'session_flows', 'feature_resilience', 'third_party_calls',
+            'components', 'provider_migrations', 'runtime', 'sdk_matrix',
+        ]),
+        objectSchema('migration_verification_definition', ['version', 'artifact_kind', 'categories']),
+        objectSchema('migration_environment_inventory', ['environments']),
+    ],
 };
 export function runMigrationArtifactValidate(opts) {
     const value = readMigrationJson(opts.file);
-    const schema = MIGRATION_ARTIFACT_SCHEMAS.artifacts.find((candidate) => candidate.properties.artifact_kind.const === value.artifact_kind);
-    if (!schema || value.version !== 1)
+    const schema = MIGRATION_ARTIFACT_SCHEMAS.artifacts.find((candidate) => candidate.properties.artifact_kind?.const === value.artifact_kind);
+    if (!schema || value.version !== 1) {
         throw new Error('[ARTIFACT_VERSION_UNSUPPORTED] Unknown artifact kind or version.');
-    printJson({ file: path.resolve(opts.file), valid: true, artifact_kind: value.artifact_kind, version: value.version }, Boolean(opts.json));
+    }
+    const missing = schema.required.filter((field) => !(field in value) || value[field] == null);
+    if (missing.length) {
+        throw new Error(`[ARTIFACT_SCHEMA_INVALID] Missing required fields: ${missing.join(', ')}`);
+    }
+    printJson({
+        file: path.resolve(opts.file),
+        valid: true,
+        artifact_kind: value.artifact_kind,
+        version: value.version,
+        schema_catalog_version: MIGRATION_ARTIFACT_SCHEMAS.version,
+    }, Boolean(opts.json));
 }
 export function runMigrationArtifactRecover(opts) {
     recoverMigrationJson(opts.file);

package/dist/commands/migration-capabilities.d.ts

@@ -0,0 +1,53 @@
+export type SupportedLanguage = 'typescript' | 'go' | 'java' | 'dotnet';
+export declare const SDK_CAPABILITY_MATRIX: {
+    readonly version: 1;
+    readonly artifact_kind: "ductape_sdk_capability_matrix";
+    readonly authority: "source_verified_catalog";
+    readonly generated_from: "repository source; update and test this catalog with every supported SDK release";
+    readonly unsupported_policy: {
+        readonly rule: "Never infer cross-language parity or synthesize a missing API.";
+        readonly action: "Inspect the installed package exports, record the capability as unsupported, and stop for an approved fallback.";
+    };
+    readonly sdks: readonly [{
+        readonly language: "typescript";
+        readonly package: "@ductape/sdk";
+        readonly version: "0.1.101";
+        readonly status: "supported";
+        readonly source_version: "sdk/ts/package.json";
+        readonly public_surface_evidence: "sdk/ts/src/index.ts";
+        readonly capabilities: readonly ["actions", "agents", "cache", "cloud", "databases", "events", "features", "graphs", "imports", "jobs", "logs", "models", "notifications", "products", "resilience", "secrets", "sessions", "storage", "vectors", "warehouse"];
+        readonly lifecycle: readonly ["await asynchronous operations", "close/disconnect owned clients during application shutdown"];
+    }, {
+        readonly language: "go";
+        readonly package: "github.com/ductape/ductape/sdk/go";
+        readonly version: "v0.0.1";
+        readonly status: "supported";
+        readonly source_version: "sdk/go git tag v0.0.1";
+        readonly public_surface_evidence: "sdk/go/ductape";
+        readonly capabilities: readonly ["actions", "agents", "cache", "cloud", "databases", "events", "features", "graphs", "imports", "jobs", "logs", "models", "notifications", "products", "resilience", "secrets", "sessions", "storage", "vectors", "warehouse"];
+        readonly lifecycle: readonly ["propagate context.Context cancellation", "close owned clients during application shutdown"];
+    }, {
+        readonly language: "java";
+        readonly package: "app.ductape:ductape-sdk";
+        readonly version: "0.1.9-SNAPSHOT";
+        readonly status: "supported-source-snapshot";
+        readonly source_version: "sdk/java/build.gradle";
+        readonly public_surface_evidence: "sdk/java/src/main/java/app/ductape/sdk/Ductape.java";
+        readonly capabilities: readonly ["actions", "agents", "cache", "cloud", "databases", "events", "features", "graphs", "imports", "jobs", "logs", "models", "notifications", "products", "resilience", "secrets", "sessions", "storage", "vectors", "warehouse"];
+        readonly lifecycle: readonly ["propagate interruption/cancellation", "close owned clients during application shutdown"];
+    }, {
+        readonly language: "dotnet";
+        readonly package: "Ductape.Sdk";
+        readonly version: "0.1.12";
+        readonly status: "supported";
+        readonly source_version: "sdk/dotnet/src/Ductape.Sdk/Ductape.Sdk.csproj";
+        readonly public_surface_evidence: "sdk/dotnet/src/Ductape.Sdk/Ductape.cs";
+        readonly capabilities: readonly ["actions", "agents", "cache", "cloud", "databases", "events", "features", "graphs", "imports", "jobs", "logs", "models", "notifications", "products", "resilience", "secrets", "sessions", "storage", "vectors", "warehouse"];
+        readonly lifecycle: readonly ["propagate CancellationToken", "dispose owned clients during application shutdown"];
+    }];
+};
+export declare function runMigrationCapabilities(opts: {
+    language?: SupportedLanguage;
+    version?: string;
+    json?: boolean;
+}): void;

package/dist/commands/migration-capabilities.js

@@ -0,0 +1,66 @@
+import { printJson } from '../lib/output.js';
+const COMMON_RUNTIME_CAPABILITIES = [
+    'actions', 'agents', 'cache', 'cloud', 'databases', 'events', 'features',
+    'graphs', 'imports', 'jobs', 'logs', 'models', 'notifications', 'products',
+    'resilience', 'secrets', 'sessions', 'storage', 'vectors', 'warehouse',
+];
+export const SDK_CAPABILITY_MATRIX = {
+    version: 1,
+    artifact_kind: 'ductape_sdk_capability_matrix',
+    authority: 'source_verified_catalog',
+    generated_from: 'repository source; update and test this catalog with every supported SDK release',
+    unsupported_policy: {
+        rule: 'Never infer cross-language parity or synthesize a missing API.',
+        action: 'Inspect the installed package exports, record the capability as unsupported, and stop for an approved fallback.',
+    },
+    sdks: [
+        {
+            language: 'typescript',
+            package: '@ductape/sdk',
+            version: '0.1.101',
+            status: 'supported',
+            source_version: 'sdk/ts/package.json',
+            public_surface_evidence: 'sdk/ts/src/index.ts',
+            capabilities: [...COMMON_RUNTIME_CAPABILITIES],
+            lifecycle: ['await asynchronous operations', 'close/disconnect owned clients during application shutdown'],
+        },
+        {
+            language: 'go',
+            package: 'github.com/ductape/ductape/sdk/go',
+            version: 'v0.0.1',
+            status: 'supported',
+            source_version: 'sdk/go git tag v0.0.1',
+            public_surface_evidence: 'sdk/go/ductape',
+            capabilities: [...COMMON_RUNTIME_CAPABILITIES],
+            lifecycle: ['propagate context.Context cancellation', 'close owned clients during application shutdown'],
+        },
+        {
+            language: 'java',
+            package: 'app.ductape:ductape-sdk',
+            version: '0.1.9-SNAPSHOT',
+            status: 'supported-source-snapshot',
+            source_version: 'sdk/java/build.gradle',
+            public_surface_evidence: 'sdk/java/src/main/java/app/ductape/sdk/Ductape.java',
+            capabilities: [...COMMON_RUNTIME_CAPABILITIES],
+            lifecycle: ['propagate interruption/cancellation', 'close owned clients during application shutdown'],
+        },
+        {
+            language: 'dotnet',
+            package: 'Ductape.Sdk',
+            version: '0.1.12',
+            status: 'supported',
+            source_version: 'sdk/dotnet/src/Ductape.Sdk/Ductape.Sdk.csproj',
+            public_surface_evidence: 'sdk/dotnet/src/Ductape.Sdk/Ductape.cs',
+            capabilities: [...COMMON_RUNTIME_CAPABILITIES],
+            lifecycle: ['propagate CancellationToken', 'dispose owned clients during application shutdown'],
+        },
+    ],
+};
+export function runMigrationCapabilities(opts) {
+    const sdks = SDK_CAPABILITY_MATRIX.sdks.filter((sdk) => (!opts.language || sdk.language === opts.language) &&
+        (!opts.version || sdk.version === opts.version));
+    if (!sdks.length) {
+        throw new Error(`No supported SDK capability matrix matches ${opts.language ?? '*'}@${opts.version ?? '*'}.`);
+    }
+    printJson({ ...SDK_CAPABILITY_MATRIX, sdks }, Boolean(opts.json));
+}

package/dist/commands/migration-database.d.ts

@@ -1,3 +1,8 @@
+export declare const REQUIRED_DATABASE_FIELDS: {
+    readonly baseline: readonly ["database_tag", "owners", "providers", "code_schema_evidence", "migration_history_evidence", "applied_history_evidence", "live_snd_schema_evidence", "proposed_schema_evidence", "drift", "objects", "security", "topology", "compatibility", "performance_baseline"];
+    readonly data: readonly ["transformations", "batching", "checkpoints", "idempotency", "resume_strategy", "validation", "reconciliation", "failure_recovery", "pii_controls", "retention", "seed_data"];
+    readonly cutover: readonly ["phases", "expand", "backfill", "dual_compatibility", "contract", "deployment_order", "migration_locking", "backup", "restore_test", "rollback", "irreversible_changes", "monitoring", "reconciliation", "approval"];
+};
 export declare function initDatabaseMigration(opts: {
     definition: string;
     output: string;

package/dist/commands/migration-database.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { printJson } from '../lib/output.js';
 import { readMigrationJson, writeMigrationJson } from '../lib/migration-artifact.js';
-const REQUIRED = {
+export const REQUIRED_DATABASE_FIELDS = {
     baseline: ['database_tag', 'owners', 'providers', 'code_schema_evidence', 'migration_history_evidence', 'applied_history_evidence', 'live_snd_schema_evidence', 'proposed_schema_evidence', 'drift', 'objects', 'security', 'topology', 'compatibility', 'performance_baseline'],
     data: ['transformations', 'batching', 'checkpoints', 'idempotency', 'resume_strategy', 'validation', 'reconciliation', 'failure_recovery', 'pii_controls', 'retention', 'seed_data'],
     cutover: ['phases', 'expand', 'backfill', 'dual_compatibility', 'contract', 'deployment_order', 'migration_locking', 'backup', 'restore_test', 'rollback', 'irreversible_changes', 'monitoring', 'reconciliation', 'approval'],
@@ -47,7 +47,7 @@ export function validateDatabaseMigration(directory) {
         if (artifact.version !== 1 || artifact.artifact_kind !== `ductape_database_${name}`) {
             blockers.push(`${name}: unsupported artifact version or kind`);
         }
-        for (const field of missing(artifact, REQUIRED[name]))
+        for (const field of missing(artifact, REQUIRED_DATABASE_FIELDS[name]))
             blockers.push(`${name}.${field}: evidence required`);
         if (!text(artifact.migration_id))
             blockers.push(`${name}.migration_id: required for cross-artifact consistency`);

package/dist/index.js

@@ -39,13 +39,18 @@ import { runMigrationGeneratedInit, runMigrationGeneratedValidate, } from './com
 import { runMigrationAssuranceValidate } from './commands/migration-assurance.js';
 import { runMigrationVerificationValidate } from './commands/migration-verification.js';
 import { runMigrationArtifactMigrate, runMigrationArtifactRecover, runMigrationArtifactSchemas, runMigrationArtifactValidate, } from './commands/migration-artifact.js';
+import { runMigrationCapabilities } from './commands/migration-capabilities.js';
+import { structuredMigrationError } from './lib/migration-artifact.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '../package.json'), 'utf8'));
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function wrap(fn) {
     return (...args) => {
-        Promise.resolve(fn(...args)).catch((err) => {
-            console.error(err instanceof Error ? err.message : err);
+        Promise.resolve().then(() => fn(...args)).catch((err) => {
+            const command = process.argv[2] ?? '';
+            console.error(command === 'migrate-codebase' || command.startsWith('migration-')
+                ? structuredMigrationError(err)
+                : err instanceof Error ? err.message : err);
             process.exit(1);
         });
     };
@@ -171,6 +176,8 @@ program
     .option('--exclude <patterns>', 'Comma-separated repository-relative glob patterns')
     .option('--ensure-product', 'Create the product when it does not exist')
     .option('--write', 'Write redacted advisory artifacts only; never writes application code or executable assets')
+    .option('--mcp-client-name <name>', 'Protocol-asserted MCP client name (unverified)', undefined)
+    .option('--mcp-client-version <version>', 'Protocol-asserted MCP client version (unverified)', undefined)
     .option('--json', 'JSON output')
     .action(wrap((opts) => runMigrateCodebase({
     source: opts.source,
@@ -186,6 +193,8 @@ program
     ensureProduct: Boolean(opts.ensureProduct),
     write: Boolean(opts.write),
     json: Boolean(opts.json),
+    mcpClientName: opts.mcpClientName,
+    mcpClientVersion: opts.mcpClientVersion,
 })));
 const migrationE2E = program
     .command('migration-e2e')
@@ -240,6 +249,17 @@ program
     strict: Boolean(opts.strict),
     json: Boolean(opts.json),
 })));
+program
+    .command('migration-capabilities')
+    .description('Print the source-verified capability matrix for supported SDK language/version pairs')
+    .option('--language <language>', 'typescript | go | java | dotnet')
+    .option('--version <version>', 'Exact supported SDK version')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationCapabilities({
+    language: opts.language,
+    version: opts.version,
+    json: Boolean(opts.json),
+})));
 program
     .command('migration-verification')
     .description('Validate cited automation evidence for large-repo, parity, frontend, database, and asset migration')

package/dist/lib/migration-artifact.d.ts

@@ -1,4 +1,10 @@
 export type MigrationArtifactErrorCode = 'ARTIFACT_TOO_LARGE' | 'ARTIFACT_INVALID_JSON' | 'ARTIFACT_SECRET_MATERIAL' | 'ARTIFACT_LOCKED' | 'ARTIFACT_EXISTS' | 'ARTIFACT_VERSION_UNSUPPORTED' | 'ARTIFACT_RECOVERY_FAILED';
+export declare const MIGRATION_ERROR_CODES: {
+    readonly validation: "MIGRATION_VALIDATION_FAILED";
+    readonly configuration: "MIGRATION_CONFIGURATION_INVALID";
+    readonly external: "MIGRATION_EXTERNAL_OPERATION_FAILED";
+};
+export declare function structuredMigrationError(error: unknown): string;
 export declare class MigrationArtifactError extends Error {
     readonly code: MigrationArtifactErrorCode;
     constructor(code: MigrationArtifactErrorCode, message: string);

package/dist/lib/migration-artifact.js

@@ -1,5 +1,16 @@
 import fs from 'node:fs';
 import path from 'node:path';
+export const MIGRATION_ERROR_CODES = {
+    validation: 'MIGRATION_VALIDATION_FAILED',
+    configuration: 'MIGRATION_CONFIGURATION_INVALID',
+    external: 'MIGRATION_EXTERNAL_OPERATION_FAILED',
+};
+export function structuredMigrationError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/^\[[A-Z0-9_]+\]/.test(message))
+        return message;
+    return `[${MIGRATION_ERROR_CODES.validation}] ${message}`;
+}
 export class MigrationArtifactError extends Error {
     code;
     constructor(code, message) {
@@ -37,8 +48,8 @@ export function readMigrationJson(file, maxBytes = 5_000_000) {
     try {
         value = JSON.parse(fs.readFileSync(resolved, 'utf8'));
     }
-    catch (error) {
-        throw new MigrationArtifactError('ARTIFACT_INVALID_JSON', `${resolved}: ${error instanceof Error ? error.message : String(error)}`);
+    catch {
+        throw new MigrationArtifactError('ARTIFACT_INVALID_JSON', `${resolved}: JSON parsing failed; parser context is intentionally suppressed to prevent evidence leakage.`);
     }
     inspect(value);
     return value;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Ductape CLI — local platform, login, link projects, and manage resources via the proxy (Workbench-compatible)",
   "type": "module",
   "main": "dist/index.js",