@ductape/cli 0.2.23 → 0.3.1

package/dist/commands/migration-secrets.js

@@ -0,0 +1,93 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { printJson } from '../lib/output.js';
+import { readMigrationJson, writeMigrationJson } from '../lib/migration-artifact.js';
+function read(file) {
+    return readMigrationJson(file);
+}
+function forbiddenValuePath(value, prefix = '') {
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index += 1) {
+            const found = forbiddenValuePath(value[index], `${prefix}[${index}]`);
+            if (found)
+                return found;
+        }
+    }
+    else if (value && typeof value === 'object') {
+        for (const [key, nested] of Object.entries(value)) {
+            if (/^(?:value|secret_value|private_key|access_token|password|credential)$/i.test(key)) {
+                return prefix ? `${prefix}.${key}` : key;
+            }
+            const found = forbiddenValuePath(nested, prefix ? `${prefix}.${key}` : key);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+export function initializeSecretMap(opts) {
+    const definition = read(opts.definition);
+    const forbidden = forbiddenValuePath(definition);
+    if (forbidden)
+        throw new Error(`Secret migration evidence must not contain value-bearing field: ${forbidden}`);
+    if (!Array.isArray(definition.classifications))
+        throw new Error('Definition requires classifications.');
+    const output = path.resolve(opts.output);
+    if (fs.existsSync(output))
+        throw new Error(`Secret migration map already exists: ${output}`);
+    const artifact = {
+        version: 1,
+        artifact_kind: 'ductape_secret_migration_map',
+        analysis: path.resolve(opts.analysis),
+        classifications: definition.classifications,
+    };
+    fs.mkdirSync(path.dirname(output), { recursive: true });
+    writeMigrationJson(output, artifact, { createOnly: true });
+    return { path: output };
+}
+export function validateSecretMap(file) {
+    const resolved = path.resolve(file);
+    const artifact = read(resolved);
+    const forbidden = forbiddenValuePath(artifact);
+    if (forbidden)
+        throw new Error(`Secret migration artifact contains forbidden value field: ${forbidden}`);
+    if (artifact.artifact_kind !== 'ductape_secret_migration_map')
+        throw new Error('Invalid secret migration map.');
+    const analysis = read(artifact.analysis);
+    const expected = [
+        ...(analysis.secrets ?? []).map((item) => ({ ...item, system: 'env' })),
+        ...(analysis.secret_references ?? []),
+    ];
+    const blockers = [];
+    for (const item of expected) {
+        const matches = artifact.classifications.filter((entry) => entry.key === item.key && entry.source === item.source && entry.system === item.system);
+        if (matches.length === 0)
+            blockers.push(`unclassified secret reference: ${item.system}:${item.source}:${item.key}`);
+        if (matches.length > 1)
+            blockers.push(`duplicate secret classification: ${item.system}:${item.source}:${item.key}`);
+    }
+    for (const entry of artifact.classifications) {
+        if (!expected.some((item) => item.key === entry.key && item.source === entry.source && item.system === entry.system)) {
+            blockers.push(`classification has no discovery evidence: ${entry.system}:${entry.source}:${entry.key}`);
+        }
+        if (!entry.environment || !entry.service || !entry.provider || !entry.rotation_owner ||
+            !entry.ductape_secret_tag || !entry.inventory_evidence) {
+            blockers.push(`classification incomplete: ${entry.system}:${entry.source}:${entry.key}`);
+        }
+        if (entry.inventory_action === 'blocked')
+            blockers.push(`secret inventory reconciliation blocked: ${entry.ductape_secret_tag}`);
+        if (!entry.rotation?.strategy?.length || !entry.rotation.validation?.length || !entry.rotation.rollback?.length) {
+            blockers.push(`rotation plan incomplete: ${entry.ductape_secret_tag}`);
+        }
+    }
+    return { artifact: resolved, ready: blockers.length === 0, references: expected.length, blockers };
+}
+export function runMigrationSecretsInit(opts) {
+    printJson(initializeSecretMap(opts), Boolean(opts.json));
+}
+export function runMigrationSecretsValidate(opts) {
+    const result = validateSecretMap(opts.file);
+    printJson(result, Boolean(opts.json));
+    if (opts.strict && !result.ready)
+        throw new Error('Secret migration map is not ready.');
+}

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

@@ -0,0 +1,132 @@
+interface SliceManifest {
+    version: 1;
+    artifact_kind: 'ductape_migration_slice';
+    tag: string;
+    name: string;
+    ledger: string;
+    files: string[];
+    surfaces: Array<'backend' | 'frontend' | 'worker'>;
+    product_boundary: {
+        product_tag: string;
+        services: string[];
+        environments: string[];
+        evidence: string;
+    };
+    sdk_capabilities: Array<{
+        language: 'typescript' | 'go' | 'java' | 'dotnet';
+        package: string;
+        version: string;
+        capability: string;
+        evidence: string;
+    }>;
+    interface_contracts: string[];
+    functional_requirements: string[];
+    operational_requirements: string[];
+    parity_evidence: Array<{
+        kind: 'characterization' | 'contract' | 'golden' | 'side_effect' | 'database_state' | 'event_order' | 'failure_injection' | 'load_concurrency' | 'shadow_comparison';
+        before: string;
+        after: string;
+        evidence: string;
+    }>;
+    frontend_parity: {
+        routes_navigation: string[];
+        rendered_states: string[];
+        forms_validation: string[];
+        accessibility: string[];
+        responsive_behavior: string[];
+        browser_storage: string[];
+        auth_transitions: string[];
+        ssr_hydration: string[];
+        realtime_reconnection: string[];
+        analytics_privacy: string[];
+        performance_budgets: string[];
+        visual_regression: string[];
+        cross_browser: string[];
+    };
+    required_assets: Array<{
+        kind: string;
+        tag: string;
+        action: 'reuse' | 'create' | 'update' | 'blocked';
+        inventory_evidence: string;
+    }>;
+    tests: string[];
+    failure_tests: string[];
+    runtime_evidence: string[];
+    smoke_checks: string[];
+    cutover_conditions: string[];
+    rollback_conditions: string[];
+    deployment_cutover: {
+        implementation_commit: string;
+        deployment_versions: Array<{
+            environment: string;
+            version: string;
+            evidence: string;
+        }>;
+        traffic: {
+            strategy: 'feature_flag' | 'dual_run' | 'percentage' | 'atomic';
+            feature_flag: string;
+            dual_run: boolean;
+            percentage: number;
+            evidence: string;
+        };
+        no_return_points: Array<{
+            description: string;
+            authorized: boolean;
+            mitigation: string;
+        }>;
+        observation: {
+            duration_minutes: number;
+            success_thresholds: string[];
+            evidence: string;
+        };
+        monitoring: {
+            dashboards: string[];
+            alerts: string[];
+            evidence: string;
+        };
+        rollback_rehearsal: {
+            environment: string;
+            executed_at: string;
+            status: 'passed' | 'failed';
+            evidence: string[];
+        };
+    };
+}
+export declare function initializeMigrationSlice(opts: {
+    ledger: string;
+    tag: string;
+    name: string;
+    files: string;
+    output?: string;
+}): {
+    path: string;
+    manifest: SliceManifest;
+};
+export declare function validateMigrationSlice(slicePath: string): {
+    slice: string;
+    tag: string;
+    ready: boolean;
+    files: number;
+    assets: number;
+    blockers: string[];
+};
+export declare function defineMigrationSlice(slicePath: string, dataPath: string): SliceManifest;
+export declare function runMigrationSliceInit(opts: {
+    ledger: string;
+    tag: string;
+    name: string;
+    files: string;
+    output?: string;
+    json?: boolean;
+}): void;
+export declare function runMigrationSliceValidate(opts: {
+    slice: string;
+    strict?: boolean;
+    json?: boolean;
+}): void;
+export declare function runMigrationSliceDefine(opts: {
+    slice: string;
+    data: string;
+    json?: boolean;
+}): void;
+export {};

package/dist/commands/migration-slice.js

@@ -0,0 +1,266 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { printJson } from '../lib/output.js';
+import { readMigrationJson, writeMigrationJson } from '../lib/migration-artifact.js';
+function readJson(file) {
+    return readMigrationJson(file);
+}
+function checksum(file) {
+    try {
+        return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+function safeTag(value) {
+    if (!/^[a-z0-9][a-z0-9_-]*$/.test(value)) {
+        throw new Error('Slice tag must contain lowercase letters, digits, hyphens, or underscores.');
+    }
+    return value;
+}
+export function initializeMigrationSlice(opts) {
+    const ledgerPath = path.resolve(opts.ledger);
+    const ledger = readJson(ledgerPath);
+    const files = readJson(path.resolve(opts.files));
+    if (!Array.isArray(files) || !files.every((file) => typeof file === 'string') || files.length === 0) {
+        throw new Error('Slice files must be a non-empty JSON array of repository-relative paths.');
+    }
+    const known = new Set(ledger.entries.map((entry) => entry.file));
+    for (const file of files) {
+        if (!known.has(file))
+            throw new Error(`Slice file is not present in the review ledger: ${file}`);
+    }
+    const tag = safeTag(opts.tag);
+    const output = path.resolve(opts.output ?? path.join(path.dirname(ledgerPath), 'slices', `${tag}.json`));
+    if (fs.existsSync(output))
+        throw new Error(`Migration slice already exists: ${output}`);
+    const manifest = {
+        version: 1,
+        artifact_kind: 'ductape_migration_slice',
+        tag,
+        name: opts.name,
+        ledger: ledgerPath,
+        files,
+        surfaces: [],
+        product_boundary: { product_tag: '', services: [], environments: [], evidence: '' },
+        sdk_capabilities: [],
+        interface_contracts: [],
+        functional_requirements: [],
+        operational_requirements: [],
+        parity_evidence: [],
+        frontend_parity: {
+            routes_navigation: [], rendered_states: [], forms_validation: [], accessibility: [],
+            responsive_behavior: [], browser_storage: [], auth_transitions: [], ssr_hydration: [],
+            realtime_reconnection: [], analytics_privacy: [], performance_budgets: [],
+            visual_regression: [], cross_browser: [],
+        },
+        required_assets: [],
+        tests: [],
+        failure_tests: [],
+        runtime_evidence: [],
+        smoke_checks: [],
+        cutover_conditions: [],
+        rollback_conditions: [],
+        deployment_cutover: {
+            implementation_commit: '',
+            deployment_versions: [],
+            traffic: { strategy: 'atomic', feature_flag: '', dual_run: false, percentage: 0, evidence: '' },
+            no_return_points: [],
+            observation: { duration_minutes: 0, success_thresholds: [], evidence: '' },
+            monitoring: { dashboards: [], alerts: [], evidence: '' },
+            rollback_rehearsal: { environment: '', executed_at: '', status: 'failed', evidence: [] },
+        },
+    };
+    fs.mkdirSync(path.dirname(output), { recursive: true });
+    writeMigrationJson(output, manifest, { createOnly: true });
+    return { path: output, manifest };
+}
+function parityComplete(value) {
+    return (value.status === 'verified' && value.evidence.length > 0) ||
+        (value.status === 'not_applicable' && Boolean(value.reason?.trim()));
+}
+export function validateMigrationSlice(slicePath) {
+    const resolved = path.resolve(slicePath);
+    const slice = readJson(resolved);
+    if (slice.artifact_kind !== 'ductape_migration_slice')
+        throw new Error('Invalid migration slice manifest.');
+    const ledger = readJson(slice.ledger);
+    const blockers = [];
+    if (!slice.files.length)
+        blockers.push('slice has no files');
+    for (const file of slice.files) {
+        const entry = ledger.entries.find((candidate) => candidate.file === file);
+        if (!entry) {
+            blockers.push(`${file}: missing from review ledger`);
+            continue;
+        }
+        if (entry.status !== 'reviewed')
+            blockers.push(`${file}: review status is ${entry.status}`);
+        if (!entry.reviewed_checksum || checksum(path.join(ledger.source, file)) !== entry.reviewed_checksum) {
+            blockers.push(`${file}: review is stale`);
+        }
+        if (!parityComplete(entry.interface_parity))
+            blockers.push(`${file}: interface parity incomplete`);
+        if (!parityComplete(entry.functional_parity))
+            blockers.push(`${file}: functional parity incomplete`);
+        if (!parityComplete(entry.operational_parity))
+            blockers.push(`${file}: operational parity incomplete`);
+    }
+    for (const [field, values] of [
+        ['surfaces', slice.surfaces],
+        ['sdk_capabilities', slice.sdk_capabilities],
+        ['interface_contracts', slice.interface_contracts],
+        ['functional_requirements', slice.functional_requirements],
+        ['operational_requirements', slice.operational_requirements],
+        ['parity_evidence', slice.parity_evidence],
+        ['tests', slice.tests],
+        ['failure_tests', slice.failure_tests],
+        ['runtime_evidence', slice.runtime_evidence],
+        ['smoke_checks', slice.smoke_checks],
+        ['cutover_conditions', slice.cutover_conditions],
+        ['rollback_conditions', slice.rollback_conditions],
+    ]) {
+        if (!Array.isArray(values) || values.length === 0)
+            blockers.push(`${field}: at least one entry is required`);
+    }
+    if (slice.surfaces?.includes('frontend')) {
+        for (const [concern, evidence] of Object.entries(slice.frontend_parity ?? {})) {
+            if (!Array.isArray(evidence) || evidence.length === 0) {
+                blockers.push(`frontend_parity.${concern}: evidence is required`);
+            }
+        }
+        const requiredFrontend = [
+            'routes_navigation', 'rendered_states', 'forms_validation', 'accessibility',
+            'responsive_behavior', 'browser_storage', 'auth_transitions', 'ssr_hydration',
+            'realtime_reconnection', 'analytics_privacy', 'performance_budgets',
+            'visual_regression', 'cross_browser',
+        ];
+        for (const concern of requiredFrontend) {
+            if (!Array.isArray(slice.frontend_parity?.[concern])) {
+                blockers.push(`frontend_parity.${concern}: concern is missing`);
+            }
+        }
+    }
+    if (!slice.product_boundary?.product_tag ||
+        !slice.product_boundary.services?.length ||
+        !slice.product_boundary.environments?.length ||
+        !slice.product_boundary.evidence) {
+        blockers.push('product_boundary: product_tag, services, environments, and evidence are required');
+    }
+    for (const capability of slice.sdk_capabilities ?? []) {
+        if (!capability.language || !capability.package || !capability.version ||
+            !capability.capability || !capability.evidence) {
+            blockers.push('sdk_capabilities: every entry requires language, package, version, capability, and evidence');
+        }
+    }
+    for (const asset of slice.required_assets ?? []) {
+        if (!asset.kind || !asset.tag || !asset.inventory_evidence) {
+            blockers.push(`asset ${asset.tag || '<unknown>'}: kind, tag, and inventory_evidence are required`);
+        }
+        if (asset.action === 'blocked')
+            blockers.push(`asset ${asset.kind}:${asset.tag}: reconciliation is blocked`);
+    }
+    if (!Array.isArray(slice.required_assets) || slice.required_assets.length === 0) {
+        blockers.push('required_assets: at least one reconciled Ductape asset is required');
+    }
+    const cutover = slice.deployment_cutover;
+    if (!cutover?.implementation_commit?.trim() || !cutover.deployment_versions?.length) {
+        blockers.push('deployment_cutover: implementation commit and deployment versions are required');
+    }
+    else {
+        for (const deployment of cutover.deployment_versions) {
+            if (!deployment.environment?.trim() || !deployment.version?.trim() || !deployment.evidence?.trim()) {
+                blockers.push('deployment_cutover.deployment_versions: environment, version, and evidence are required');
+            }
+        }
+    }
+    if (!cutover?.traffic?.evidence?.trim() || cutover.traffic.percentage < 0 || cutover.traffic.percentage > 100 ||
+        (cutover.traffic.strategy === 'feature_flag' && !cutover.traffic.feature_flag?.trim())) {
+        blockers.push('deployment_cutover.traffic: valid strategy, percentage, feature flag when applicable, and evidence are required');
+    }
+    if (!Array.isArray(cutover?.no_return_points) || !cutover.no_return_points.length ||
+        cutover.no_return_points.some((point) => !point.description?.trim() || !point.mitigation?.trim())) {
+        blockers.push('deployment_cutover.no_return_points: explicit descriptions and mitigations are required');
+    }
+    if (!cutover?.observation || cutover.observation.duration_minutes <= 0 ||
+        !cutover.observation.success_thresholds?.length || !cutover.observation.evidence?.trim()) {
+        blockers.push('deployment_cutover.observation: duration, success thresholds, and evidence are required');
+    }
+    if (!cutover?.monitoring?.dashboards?.length || !cutover.monitoring.alerts?.length ||
+        !cutover.monitoring.evidence?.trim()) {
+        blockers.push('deployment_cutover.monitoring: dashboard, alerts, and evidence are required');
+    }
+    if (!cutover?.rollback_rehearsal || cutover.rollback_rehearsal.status !== 'passed' ||
+        !cutover.rollback_rehearsal.environment?.trim() || !cutover.rollback_rehearsal.executed_at?.trim() ||
+        !cutover.rollback_rehearsal.evidence?.length) {
+        blockers.push('deployment_cutover.rollback_rehearsal: passing executed rehearsal evidence is required');
+    }
+    return {
+        slice: resolved,
+        tag: slice.tag,
+        ready: blockers.length === 0,
+        files: slice.files.length,
+        assets: slice.required_assets.length,
+        blockers,
+    };
+}
+export function defineMigrationSlice(slicePath, dataPath) {
+    const resolved = path.resolve(slicePath);
+    const slice = readJson(resolved);
+    if (slice.artifact_kind !== 'ductape_migration_slice')
+        throw new Error('Invalid migration slice manifest.');
+    const data = readJson(path.resolve(dataPath));
+    for (const field of [
+        'surfaces',
+        'sdk_capabilities',
+        'interface_contracts', 'functional_requirements', 'operational_requirements',
+        'parity_evidence', 'required_assets', 'tests', 'failure_tests', 'runtime_evidence', 'smoke_checks',
+        'cutover_conditions', 'rollback_conditions',
+    ]) {
+        if (data[field] !== undefined) {
+            if (!Array.isArray(data[field]))
+                throw new Error(`${field} must be an array.`);
+            slice[field] = data[field];
+        }
+    }
+    if (data.product_boundary !== undefined)
+        slice.product_boundary = data.product_boundary;
+    if (data.frontend_parity !== undefined)
+        slice.frontend_parity = data.frontend_parity;
+    if (data.deployment_cutover !== undefined)
+        slice.deployment_cutover = data.deployment_cutover;
+    for (const asset of slice.required_assets) {
+        if (!['reuse', 'create', 'update', 'blocked'].includes(asset.action)) {
+            throw new Error(`Invalid asset reconciliation action for ${asset.kind}:${asset.tag}`);
+        }
+    }
+    if (!slice.product_boundary ||
+        !Array.isArray(slice.product_boundary.services) ||
+        !Array.isArray(slice.product_boundary.environments)) {
+        throw new Error('product_boundary must include services and environments arrays.');
+    }
+    writeMigrationJson(resolved, slice, { backup: true });
+    return slice;
+}
+export function runMigrationSliceInit(opts) {
+    const result = initializeMigrationSlice(opts);
+    printJson({ path: result.path, tag: result.manifest.tag, files: result.manifest.files.length }, Boolean(opts.json));
+}
+export function runMigrationSliceValidate(opts) {
+    const result = validateMigrationSlice(opts.slice);
+    printJson(result, Boolean(opts.json));
+    if (opts.strict && !result.ready) {
+        throw new Error('Migration slice is not ready: resolve every reported blocker before cutover.');
+    }
+}
+export function runMigrationSliceDefine(opts) {
+    const manifest = defineMigrationSlice(opts.slice, opts.data);
+    printJson({
+        slice: path.resolve(opts.slice),
+        tag: manifest.tag,
+        assets: manifest.required_assets.length,
+        tests: manifest.tests.length,
+    }, Boolean(opts.json));
+}

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

@@ -0,0 +1,12 @@
+export declare function validateMigrationVerification(file: string): {
+    file: string;
+    ready: boolean;
+    categories: number;
+    requirements: number;
+    blockers: string[];
+};
+export declare function runMigrationVerificationValidate(opts: {
+    file: string;
+    strict?: boolean;
+    json?: boolean;
+}): void;