@devtrack-solution/codesdd 1.2.2 → 1.2.4-rc3

package/dist/core/sdd/upgrade-to-codesdd.d.ts

@@ -0,0 +1,45 @@
+import { type SddMigrationAssessment } from './migrate.js';
+import { buildSddContractConfig } from './contract.js';
+export interface UpgradeToCodeSddReadinessReport {
+    status: 'ready' | 'needs-upgrade' | 'blocked';
+    assessment: SddMigrationAssessment;
+    blockers: string[];
+    warnings: string[];
+    planned_steps: string[];
+}
+export interface UpgradeToCodeSddManifest {
+    manifest_version: 1;
+    transaction_id: string;
+    mode: 'apply';
+    created_at: string;
+    readiness: UpgradeToCodeSddReadinessReport;
+    backup_root: string;
+    backed_up_paths: string[];
+    migration_messages: string[];
+    sdd_contract: ReturnType<typeof buildSddContractConfig>;
+}
+export interface UpgradeToCodeSddResult {
+    mode: 'dry-run' | 'apply';
+    readiness: UpgradeToCodeSddReadinessReport;
+    manifest?: UpgradeToCodeSddManifest;
+    manifest_path?: string;
+}
+export interface UpgradeToCodeSddRollbackResult {
+    transaction_id: string;
+    restored_paths: string[];
+    skipped_paths: string[];
+    manifest_path: string;
+    reason: string;
+}
+export declare class UpgradeToCodeSddCommand {
+    execute(projectRoot: string, options?: {
+        dryRun?: boolean;
+        apply?: boolean;
+        yes?: boolean;
+    }): Promise<UpgradeToCodeSddResult>;
+    rollback(projectRoot: string, transactionId: string, options?: {
+        reason?: string;
+    }): Promise<UpgradeToCodeSddRollbackResult>;
+}
+export declare function formatUpgradeToCodeSddReadiness(report: UpgradeToCodeSddReadinessReport): string;
+//# sourceMappingURL=upgrade-to-codesdd.d.ts.map

package/dist/core/sdd/upgrade-to-codesdd.js

@@ -0,0 +1,179 @@
+import { createHash } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import { access, cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { assessSddMigration, SddMigrateCommand } from './migrate.js';
+import { buildSddContractConfig } from './contract.js';
+function timestampToken(value = new Date()) {
+    return value.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+}
+function createTransactionId(projectRoot, value = new Date()) {
+    const suffix = createHash('sha1').update(`${projectRoot}:${value.toISOString()}`).digest('hex').slice(0, 8).toUpperCase();
+    return `UPG-${timestampToken(value)}-${suffix}`;
+}
+async function pathExists(targetPath) {
+    try {
+        await access(targetPath, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function upgradeRoot(projectRoot) {
+    return path.join(projectRoot, '.sdd', 'reports', 'upgrade-to-codesdd');
+}
+function manifestPath(projectRoot, transactionId) {
+    return path.join(upgradeRoot(projectRoot), `${transactionId}-manifest.json`);
+}
+function backupRoot(projectRoot, transactionId) {
+    return path.join(upgradeRoot(projectRoot), transactionId, 'backups');
+}
+function backupCandidates(projectRoot) {
+    return [
+        '.sdd/config.yaml',
+        '.sdd/state',
+        '.sdd/active',
+        '.sdd/planned',
+        '.sdd/archived',
+    ].map((entry) => path.join(projectRoot, entry));
+}
+function toProjectRelative(projectRoot, targetPath) {
+    return path.relative(projectRoot, targetPath).replace(/\\/g, '/');
+}
+function backupDestination(projectRoot, root, targetPath) {
+    return path.join(root, toProjectRelative(projectRoot, targetPath));
+}
+async function writeJson(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+}
+async function readJson(filePath) {
+    return JSON.parse(await readFile(filePath, 'utf-8'));
+}
+async function createBackups(projectRoot, transactionId) {
+    const root = backupRoot(projectRoot, transactionId);
+    const backedUp = [];
+    for (const candidate of backupCandidates(projectRoot)) {
+        if (!(await pathExists(candidate)))
+            continue;
+        const destination = backupDestination(projectRoot, root, candidate);
+        await mkdir(path.dirname(destination), { recursive: true });
+        await cp(candidate, destination, { recursive: true });
+        backedUp.push(toProjectRelative(projectRoot, candidate));
+    }
+    return backedUp;
+}
+function buildReadiness(assessment) {
+    const blockers = [];
+    if (assessment.currentVersion > assessment.targetVersion) {
+        blockers.push(`state_version=${assessment.currentVersion} is newer than supported target ${assessment.targetVersion}`);
+    }
+    const warnings = [...assessment.reasons];
+    const plannedSteps = [
+        'create transaction backup under .sdd/reports/upgrade-to-codesdd',
+        'run canonical SDD migration to CodeSDD state contract',
+        'write upgrade manifest with readiness and migration messages',
+        'allow rollback by transaction id while backup artifacts are present',
+    ];
+    return {
+        status: blockers.length > 0 ? 'blocked' : assessment.needsMigration ? 'needs-upgrade' : 'ready',
+        assessment,
+        blockers,
+        warnings,
+        planned_steps: plannedSteps,
+    };
+}
+export class UpgradeToCodeSddCommand {
+    async execute(projectRoot, options) {
+        const root = path.resolve(projectRoot);
+        const assessment = await assessSddMigration(root);
+        const readiness = buildReadiness(assessment);
+        if (!options?.apply || options.dryRun) {
+            return { mode: 'dry-run', readiness };
+        }
+        if (!options.yes) {
+            throw new Error('upgrade-to-codesdd apply requires --yes for transactional mutation.');
+        }
+        if (readiness.blockers.length > 0) {
+            throw new Error(`upgrade-to-codesdd blocked: ${readiness.blockers.join(' | ')}`);
+        }
+        const transactionId = createTransactionId(root);
+        const backedUpPaths = await createBackups(root, transactionId);
+        const migration = await new SddMigrateCommand().execute(root, { radToEpic: true });
+        const manifest = {
+            manifest_version: 1,
+            transaction_id: transactionId,
+            mode: 'apply',
+            created_at: new Date().toISOString(),
+            readiness,
+            backup_root: toProjectRelative(root, backupRoot(root, transactionId)),
+            backed_up_paths: backedUpPaths,
+            migration_messages: migration.messages,
+            sdd_contract: buildSddContractConfig(),
+        };
+        const manifestFile = manifestPath(root, transactionId);
+        await writeJson(manifestFile, manifest);
+        return {
+            mode: 'apply',
+            readiness,
+            manifest,
+            manifest_path: toProjectRelative(root, manifestFile),
+        };
+    }
+    async rollback(projectRoot, transactionId, options) {
+        const root = path.resolve(projectRoot);
+        if (!/^UPG-\d{8}T\d{6}Z-[A-F0-9]{8}$/.test(transactionId)) {
+            throw new Error('Invalid upgrade transaction id. Expected UPG-YYYYMMDDTHHMMSSZ-XXXXXXXX.');
+        }
+        const manifestFile = manifestPath(root, transactionId);
+        const manifest = await readJson(manifestFile);
+        const restoredPaths = [];
+        const skippedPaths = [];
+        for (const relativePath of manifest.backed_up_paths) {
+            const backupPath = path.join(root, manifest.backup_root, relativePath);
+            const targetPath = path.join(root, relativePath);
+            if (!(await pathExists(backupPath))) {
+                skippedPaths.push(relativePath);
+                continue;
+            }
+            await rm(targetPath, { recursive: true, force: true });
+            await mkdir(path.dirname(targetPath), { recursive: true });
+            await cp(backupPath, targetPath, { recursive: true });
+            restoredPaths.push(relativePath);
+        }
+        await writeJson(path.join(upgradeRoot(root), `${transactionId}-rollback.json`), {
+            transaction_id: transactionId,
+            rolled_back_at: new Date().toISOString(),
+            reason: options?.reason || 'Rollback requested.',
+            restored_paths: restoredPaths,
+            skipped_paths: skippedPaths,
+        });
+        return {
+            transaction_id: transactionId,
+            restored_paths: restoredPaths,
+            skipped_paths: skippedPaths,
+            manifest_path: toProjectRelative(root, manifestFile),
+            reason: options?.reason || 'Rollback requested.',
+        };
+    }
+}
+export function formatUpgradeToCodeSddReadiness(report) {
+    const lines = [
+        `Status: ${report.status}`,
+        `State version: ${report.assessment.currentVersion} -> ${report.assessment.targetVersion}`,
+        `Needs migration: ${report.assessment.needsMigration ? 'yes' : 'no'}`,
+    ];
+    if (report.blockers.length > 0) {
+        lines.push('Blockers:');
+        lines.push(...report.blockers.map((item) => `- ${item}`));
+    }
+    if (report.warnings.length > 0) {
+        lines.push('Warnings:');
+        lines.push(...report.warnings.map((item) => `- ${item}`));
+    }
+    lines.push('Planned steps:');
+    lines.push(...report.planned_steps.map((item) => `- ${item}`));
+    return lines.join('\n');
+}
+//# sourceMappingURL=upgrade-to-codesdd.js.map

package/dist/core/sdd/views.js

@@ -147,18 +147,35 @@ ${rows.length > 0 ? rows.join('\n') : '| - | - | No items | - | - |'}
 }
 function renderFinalizeQueue(state) {
     const rows = state.finalizeQueue.items
+        .filter((item) => item.status === 'PENDING')
         .slice()
         .sort((a, b) => a.feature_id.localeCompare(b.feature_id))
         .map((item) => {
         return `| ${item.feature_id} | ${item.status} | ${item.summary || '-'} | ${formatDate(item.created_at)} | ${formatDate(item.completed_at)} |`;
     });
+    const historyRows = state.finalizeQueue.history
+        .slice()
+        .sort((a, b) => (b.completed_at || '').localeCompare(a.completed_at || ''))
+        .slice(0, 20)
+        .map((item) => {
+        return `| ${item.feature_id} | ${item.summary || '-'} | ${formatDate(item.created_at)} | ${formatDate(item.completed_at)} |`;
+    });
     return `# Finalize Queue
 
 Generated from \`.sdd/state/finalize-queue.yaml\`.
 
+Active queue items: ${rows.length}
+Finalize history items: ${state.finalizeQueue.history.length}
+
 | Feature | Status | Summary | Created | Completed |
 | --- | --- | --- | --- | --- |
 ${rows.length > 0 ? rows.join('\n') : '| - | - | No items | - | - |'}
+
+## Recent History
+
+| Feature | Summary | Created | Completed |
+| --- | --- | --- | --- |
+${historyRows.length > 0 ? historyRows.join('\n') : '| - | No completed finalizations | - | - |'}
 `;
 }
 function renderTechDebt(state) {