@thxgg/steward 0.1.24 → 0.1.25

package/dist/server/utils/sync-apply.js

@@ -0,0 +1,380 @@
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { dbExec, dbGet, dbRun, getDbPath } from './db.js';
+import { planSyncMerge } from './sync-merge.js';
+import { parseSyncBundle } from './sync-schema.js';
+const DEFAULT_BACKUP_RETENTION_DAYS = 30;
+const DEFAULT_MAX_BACKUPS = 20;
+const DEFAULT_LOG_RETENTION_DAYS = 180;
+const DEFAULT_MAX_LOG_ENTRIES = 10_000;
+function sanitizeRetentionNumber(value, fallback, min) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return fallback;
+    }
+    return Math.max(min, Math.floor(value));
+}
+function resolveRetentionPolicy(options) {
+    return {
+        backupRetentionDays: sanitizeRetentionNumber(options.backupRetentionDays, DEFAULT_BACKUP_RETENTION_DAYS, 0),
+        maxBackups: sanitizeRetentionNumber(options.maxBackups, DEFAULT_MAX_BACKUPS, 1),
+        logRetentionDays: sanitizeRetentionNumber(options.logRetentionDays, DEFAULT_LOG_RETENTION_DAYS, 0),
+        maxLogEntries: sanitizeRetentionNumber(options.maxLogEntries, DEFAULT_MAX_LOG_ENTRIES, 1)
+    };
+}
+function toStateKey(repoSyncKey, slug) {
+    return `${repoSyncKey}:${slug}`;
+}
+function serializeJson(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    return JSON.stringify(value);
+}
+function parseIsoOrNow(value) {
+    if (typeof value === 'string' && value.trim().length > 0 && Number.isFinite(Date.parse(value))) {
+        return new Date(value).toISOString();
+    }
+    return new Date().toISOString();
+}
+function escapeSqliteString(value) {
+    return value.replaceAll("'", "''");
+}
+function toBackupFileTimestamp(nowIso) {
+    return nowIso
+        .replaceAll('-', '')
+        .replaceAll(':', '')
+        .replaceAll('.', '');
+}
+function toSafeFileSegment(value) {
+    const sanitized = value.replace(/[^A-Za-z0-9._-]/g, '_');
+    return sanitized.length > 0 ? sanitized : 'bundle';
+}
+function getBackupFilePrefix(dbPath) {
+    return `${basename(dbPath)}.sync-backup.`;
+}
+async function createDatabaseBackup(bundleId, nowIso) {
+    const dbPath = getDbPath();
+    const backupDir = dirname(dbPath);
+    const filePrefix = getBackupFilePrefix(dbPath);
+    const fileName = `${filePrefix}${toBackupFileTimestamp(nowIso)}-${toSafeFileSegment(bundleId)}-${randomUUID().slice(0, 8)}.db`;
+    const backupPath = join(backupDir, fileName);
+    await fs.mkdir(backupDir, { recursive: true });
+    await dbExec(`VACUUM INTO '${escapeSqliteString(backupPath)}';`);
+    return backupPath;
+}
+async function pruneDatabaseBackups(nowIso, policy) {
+    const dbPath = getDbPath();
+    const backupDir = dirname(dbPath);
+    const filePrefix = getBackupFilePrefix(dbPath);
+    const cutoffMs = Date.parse(nowIso) - (policy.backupRetentionDays * 24 * 60 * 60 * 1000);
+    let entries = [];
+    try {
+        const dirEntries = await fs.readdir(backupDir, { withFileTypes: true });
+        const candidateFiles = dirEntries
+            .filter((entry) => entry.isFile())
+            .map((entry) => entry.name)
+            .filter((name) => name.startsWith(filePrefix) && name.endsWith('.db'));
+        entries = await Promise.all(candidateFiles.map(async (name) => {
+            const filePath = join(backupDir, name);
+            const stat = await fs.stat(filePath);
+            return {
+                path: filePath,
+                mtimeMs: stat.mtimeMs
+            };
+        }));
+    }
+    catch {
+        return 0;
+    }
+    entries.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    let deleted = 0;
+    for (let index = 0; index < entries.length; index += 1) {
+        const entry = entries[index];
+        const tooOld = Number.isFinite(cutoffMs) ? entry.mtimeMs < cutoffMs : false;
+        const overLimit = index >= policy.maxBackups;
+        if (!tooOld && !overLimit) {
+            continue;
+        }
+        try {
+            await fs.unlink(entry.path);
+            deleted += 1;
+        }
+        catch {
+            // Ignore retention cleanup errors; merge apply already succeeded.
+        }
+    }
+    return deleted;
+}
+async function pruneSyncLog(nowIso, policy) {
+    const cutoffIso = new Date(Date.parse(nowIso) - (policy.logRetentionDays * 24 * 60 * 60 * 1000)).toISOString();
+    let deleted = 0;
+    const deleteOlder = await dbRun('DELETE FROM sync_bundle_log WHERE applied_at < ?', [cutoffIso]);
+    deleted += deleteOlder.changes;
+    const countRow = await dbGet('SELECT COUNT(*) as count FROM sync_bundle_log');
+    const currentCount = countRow?.count ?? 0;
+    if (currentCount <= policy.maxLogEntries) {
+        return deleted;
+    }
+    const toDeleteCount = currentCount - policy.maxLogEntries;
+    if (toDeleteCount <= 0) {
+        return deleted;
+    }
+    const deleteOverflow = await dbRun(`
+      DELETE FROM sync_bundle_log
+      WHERE bundle_id IN (
+        SELECT bundle_id
+        FROM sync_bundle_log
+        ORDER BY applied_at ASC, bundle_id ASC
+        LIMIT ?
+      )
+    `, [toDeleteCount]);
+    deleted += deleteOverflow.changes;
+    return deleted;
+}
+function assertNoUnresolvedMappings(plan) {
+    const unresolvedMappings = plan.mappings.filter((mapping) => mapping.source === 'unresolved');
+    if (unresolvedMappings.length === 0) {
+        return;
+    }
+    const unresolvedKeys = unresolvedMappings.map((mapping) => mapping.incomingRepoSyncKey).join(', ');
+    throw new Error(`Cannot apply bundle with unresolved repositories: ${unresolvedKeys}`);
+}
+async function applyStateInsert(planRow, incomingRow, appliedAt) {
+    if (!planRow.localRepoId) {
+        throw new Error(`Missing local repository mapping for ${planRow.repoSyncKey}`);
+    }
+    await dbRun(`
+      INSERT INTO prd_states (
+        repo_id,
+        slug,
+        tasks_json,
+        progress_json,
+        notes_md,
+        tasks_updated_at,
+        progress_updated_at,
+        notes_updated_at,
+        updated_at
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(repo_id, slug) DO UPDATE SET
+        tasks_json = excluded.tasks_json,
+        progress_json = excluded.progress_json,
+        notes_md = excluded.notes_md,
+        tasks_updated_at = excluded.tasks_updated_at,
+        progress_updated_at = excluded.progress_updated_at,
+        notes_updated_at = excluded.notes_updated_at,
+        updated_at = excluded.updated_at
+    `, [
+        planRow.localRepoId,
+        incomingRow.slug,
+        serializeJson(incomingRow.tasks),
+        serializeJson(incomingRow.progress),
+        incomingRow.notes,
+        incomingRow.clocks.tasksUpdatedAt,
+        incomingRow.clocks.progressUpdatedAt,
+        incomingRow.clocks.notesUpdatedAt,
+        appliedAt
+    ]);
+}
+async function applyStateUpdate(planRow, incomingRow, appliedAt) {
+    if (!planRow.localRepoId) {
+        throw new Error(`Missing local repository mapping for ${planRow.repoSyncKey}`);
+    }
+    const updateTasks = planRow.updateFields.includes('tasks');
+    const updateProgress = planRow.updateFields.includes('progress');
+    const updateNotes = planRow.updateFields.includes('notes');
+    const anyUpdate = updateTasks || updateProgress || updateNotes;
+    if (!anyUpdate) {
+        return;
+    }
+    const result = await dbRun(`
+      UPDATE prd_states
+      SET
+        tasks_json = CASE WHEN ? THEN ? ELSE tasks_json END,
+        progress_json = CASE WHEN ? THEN ? ELSE progress_json END,
+        notes_md = CASE WHEN ? THEN ? ELSE notes_md END,
+        tasks_updated_at = CASE WHEN ? THEN ? ELSE tasks_updated_at END,
+        progress_updated_at = CASE WHEN ? THEN ? ELSE progress_updated_at END,
+        notes_updated_at = CASE WHEN ? THEN ? ELSE notes_updated_at END,
+        updated_at = CASE WHEN ? THEN ? ELSE updated_at END
+      WHERE repo_id = ? AND slug = ?
+    `, [
+        updateTasks ? 1 : 0,
+        serializeJson(incomingRow.tasks),
+        updateProgress ? 1 : 0,
+        serializeJson(incomingRow.progress),
+        updateNotes ? 1 : 0,
+        incomingRow.notes,
+        updateTasks ? 1 : 0,
+        incomingRow.clocks.tasksUpdatedAt,
+        updateProgress ? 1 : 0,
+        incomingRow.clocks.progressUpdatedAt,
+        updateNotes ? 1 : 0,
+        incomingRow.clocks.notesUpdatedAt,
+        anyUpdate ? 1 : 0,
+        appliedAt,
+        planRow.localRepoId,
+        incomingRow.slug
+    ]);
+    if (result.changes > 0) {
+        return;
+    }
+    await applyStateInsert(planRow, incomingRow, appliedAt);
+}
+async function applyArchiveAction(planRow, incomingRow) {
+    if (!planRow.localRepoId) {
+        throw new Error(`Missing local repository mapping for ${planRow.repoSyncKey}`);
+    }
+    if (planRow.action === 'insert') {
+        await dbRun(`
+        INSERT INTO prd_archives (repo_id, slug, archived_at)
+        VALUES (?, ?, ?)
+        ON CONFLICT(repo_id, slug) DO UPDATE SET
+          archived_at = CASE
+            WHEN excluded.archived_at > prd_archives.archived_at THEN excluded.archived_at
+            ELSE prd_archives.archived_at
+          END
+      `, [planRow.localRepoId, incomingRow.slug, incomingRow.archivedAt]);
+        return;
+    }
+    if (planRow.action === 'update') {
+        await dbRun(`
+        UPDATE prd_archives
+        SET archived_at = ?
+        WHERE repo_id = ? AND slug = ? AND archived_at < ?
+      `, [incomingRow.archivedAt, planRow.localRepoId, incomingRow.slug, incomingRow.archivedAt]);
+    }
+}
+async function assertIntegrityCheckPasses() {
+    const row = await dbGet('PRAGMA integrity_check');
+    if (!row) {
+        throw new Error('SQLite integrity check returned no results');
+    }
+    const firstValue = Object.values(row)[0];
+    if (firstValue !== 'ok') {
+        throw new Error(`SQLite integrity check failed: ${String(firstValue)}`);
+    }
+}
+async function hasBundleBeenApplied(bundleId) {
+    return await dbGet('SELECT bundle_id, applied_at FROM sync_bundle_log WHERE bundle_id = ?', [bundleId]);
+}
+export async function executeSyncMerge(bundleInput, options = {}) {
+    const bundle = parseSyncBundle(bundleInput);
+    const nowIso = parseIsoOrNow(options.now);
+    const retentionPolicy = resolveRetentionPolicy(options);
+    const plan = await planSyncMerge(bundle, {
+        repoMap: options.repoMap
+    });
+    if (options.apply !== true) {
+        return {
+            mode: 'dry_run',
+            applied: false,
+            alreadyApplied: false,
+            bundleId: bundle.bundleId,
+            plan,
+            retention: {
+                backupsDeleted: 0,
+                logsDeleted: 0
+            }
+        };
+    }
+    const existingLog = await hasBundleBeenApplied(bundle.bundleId);
+    if (existingLog) {
+        return {
+            mode: 'apply',
+            applied: false,
+            alreadyApplied: true,
+            bundleId: bundle.bundleId,
+            plan,
+            retention: {
+                backupsDeleted: 0,
+                logsDeleted: 0
+            }
+        };
+    }
+    assertNoUnresolvedMappings(plan);
+    const backupPath = await createDatabaseBackup(bundle.bundleId, nowIso);
+    const incomingStateByKey = new Map();
+    const incomingArchiveByKey = new Map();
+    for (const row of bundle.states) {
+        incomingStateByKey.set(toStateKey(row.repoSyncKey, row.slug), row);
+    }
+    for (const row of bundle.archives) {
+        incomingArchiveByKey.set(toStateKey(row.repoSyncKey, row.slug), row);
+    }
+    let logsDeleted = 0;
+    let inTransaction = false;
+    try {
+        await dbExec('BEGIN IMMEDIATE');
+        inTransaction = true;
+        for (const planRow of plan.states) {
+            if (planRow.action === 'skip' || planRow.action === 'unresolved') {
+                continue;
+            }
+            const incoming = incomingStateByKey.get(toStateKey(planRow.repoSyncKey, planRow.slug));
+            if (!incoming) {
+                throw new Error(`Missing incoming state row for ${planRow.repoSyncKey}:${planRow.slug}`);
+            }
+            if (planRow.action === 'insert') {
+                await applyStateInsert(planRow, incoming, nowIso);
+            }
+            else {
+                await applyStateUpdate(planRow, incoming, nowIso);
+            }
+        }
+        for (const planRow of plan.archives) {
+            if (planRow.action === 'skip' || planRow.action === 'unresolved') {
+                continue;
+            }
+            const incoming = incomingArchiveByKey.get(toStateKey(planRow.repoSyncKey, planRow.slug));
+            if (!incoming) {
+                throw new Error(`Missing incoming archive row for ${planRow.repoSyncKey}:${planRow.slug}`);
+            }
+            await applyArchiveAction(planRow, incoming);
+        }
+        await assertIntegrityCheckPasses();
+        await dbRun(`
+        INSERT INTO sync_bundle_log (bundle_id, source_device_id, applied_at, summary_json)
+        VALUES (?, ?, ?, ?)
+      `, [bundle.bundleId, bundle.sourceDeviceId, nowIso, JSON.stringify(plan.summary)]);
+        logsDeleted = await pruneSyncLog(nowIso, retentionPolicy);
+        await dbExec('COMMIT');
+        inTransaction = false;
+    }
+    catch (error) {
+        if (inTransaction) {
+            try {
+                await dbExec('ROLLBACK');
+            }
+            catch {
+                // Ignore rollback failure; original error is surfaced.
+            }
+        }
+        throw error;
+    }
+    const backupsDeleted = await pruneDatabaseBackups(nowIso, retentionPolicy);
+    return {
+        mode: 'apply',
+        applied: true,
+        alreadyApplied: false,
+        bundleId: bundle.bundleId,
+        plan,
+        backupPath,
+        retention: {
+            backupsDeleted,
+            logsDeleted
+        }
+    };
+}
+export async function executeSyncMergeJson(jsonPayload, options = {}) {
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonPayload);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid bundle JSON: ${message}`);
+    }
+    return await executeSyncMerge(parsed, options);
+}

package/dist/server/utils/sync-export.js

@@ -0,0 +1,183 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { promises as fs } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dbAll } from './db.js';
+import { getRepos } from './repos.js';
+import { createSyncFieldHashes, parseSyncBundle } from './sync-schema.js';
+import { ensureRepoSyncMetaForRepos, getOrCreateSyncDeviceId } from './sync-identity.js';
+import { parseStoredProgressFile, parseTasksFile } from './state-schema.js';
+function parseStoredJson(rawValue, fieldName, parseValue) {
+    if (!rawValue) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawValue);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid JSON stored in ${fieldName}: ${message}`);
+    }
+    return parseValue(parsed);
+}
+function resolvePathHint(path, mode) {
+    if (mode === 'none') {
+        return undefined;
+    }
+    if (mode === 'absolute') {
+        return resolve(path);
+    }
+    return basename(resolve(path));
+}
+function toClockValue(primary, fallback, hasValue) {
+    if (primary) {
+        return primary;
+    }
+    if (hasValue) {
+        return fallback;
+    }
+    return null;
+}
+function findPackageRoot(startDir) {
+    let currentDir = startDir;
+    while (true) {
+        const packageJsonPath = join(currentDir, 'package.json');
+        if (existsSync(packageJsonPath)) {
+            return currentDir;
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir) {
+            return startDir;
+        }
+        currentDir = parentDir;
+    }
+}
+async function readStewardVersion() {
+    const packageRoot = findPackageRoot(dirname(fileURLToPath(import.meta.url)));
+    const packageJsonPath = join(packageRoot, 'package.json');
+    try {
+        const contents = await fs.readFile(packageJsonPath, 'utf-8');
+        const parsed = JSON.parse(contents);
+        if (typeof parsed.version === 'string' && parsed.version.trim().length > 0) {
+            return parsed.version;
+        }
+    }
+    catch {
+        // Fall back to unknown when package metadata cannot be loaded.
+    }
+    return 'unknown';
+}
+export async function buildSyncBundle(options = {}) {
+    const pathHintsMode = options.pathHints || 'basename';
+    const createdAt = options.createdAt || new Date().toISOString();
+    const [allRepos, sourceDeviceId, stewardVersion] = await Promise.all([
+        getRepos(),
+        getOrCreateSyncDeviceId(),
+        options.stewardVersion ? Promise.resolve(options.stewardVersion) : readStewardVersion()
+    ]);
+    const filteredRepoIds = new Set(Array.isArray(options.repoIds)
+        ? options.repoIds.filter((repoId) => typeof repoId === 'string' && repoId.trim().length > 0)
+        : []);
+    const repos = filteredRepoIds.size > 0
+        ? allRepos.filter((repo) => filteredRepoIds.has(repo.id))
+        : allRepos;
+    const repoMetaById = await ensureRepoSyncMetaForRepos(repos);
+    const repoIds = repos.map((repo) => repo.id);
+    let stateRows = [];
+    let archiveRows = [];
+    if (repoIds.length > 0) {
+        const placeholders = repoIds.map(() => '?').join(', ');
+        stateRows = await dbAll(`
+        SELECT
+          repo_id,
+          slug,
+          tasks_json,
+          progress_json,
+          notes_md,
+          updated_at,
+          tasks_updated_at,
+          progress_updated_at,
+          notes_updated_at
+        FROM prd_states
+        WHERE repo_id IN (${placeholders})
+        ORDER BY repo_id ASC, slug ASC
+      `, repoIds);
+        archiveRows = await dbAll(`
+        SELECT repo_id, slug, archived_at
+        FROM prd_archives
+        WHERE repo_id IN (${placeholders})
+        ORDER BY repo_id ASC, slug ASC
+      `, repoIds);
+    }
+    const syncRepos = repos.map((repo) => {
+        const repoMeta = repoMetaById.get(repo.id);
+        if (!repoMeta) {
+            throw new Error(`Missing sync metadata for repository ${repo.id}`);
+        }
+        const pathHint = resolvePathHint(repo.path, pathHintsMode);
+        return {
+            repoSyncKey: repoMeta.syncKey,
+            name: repo.name,
+            ...(pathHint && { pathHint }),
+            fingerprint: repoMeta.fingerprint,
+            fingerprintKind: repoMeta.fingerprintKind
+        };
+    });
+    const states = stateRows.map((row) => {
+        const repoMeta = repoMetaById.get(row.repo_id);
+        if (!repoMeta) {
+            throw new Error(`Missing sync metadata for repository ${row.repo_id}`);
+        }
+        const tasks = parseStoredJson(row.tasks_json, 'prd_states.tasks_json', parseTasksFile);
+        const progress = parseStoredJson(row.progress_json, 'prd_states.progress_json', (value) => parseStoredProgressFile(value, {
+            totalTasksHint: Array.isArray(tasks?.tasks) ? tasks.tasks.length : undefined,
+            prdNameFallback: tasks?.prd?.name || row.slug
+        }));
+        const clocks = {
+            tasksUpdatedAt: toClockValue(row.tasks_updated_at, row.updated_at, tasks !== null),
+            progressUpdatedAt: toClockValue(row.progress_updated_at, row.updated_at, progress !== null),
+            notesUpdatedAt: toClockValue(row.notes_updated_at, row.updated_at, row.notes_md !== null)
+        };
+        const hashes = createSyncFieldHashes({
+            tasks,
+            progress,
+            notes: row.notes_md
+        });
+        return {
+            repoSyncKey: repoMeta.syncKey,
+            slug: row.slug,
+            tasks,
+            progress,
+            notes: row.notes_md,
+            clocks,
+            hashes
+        };
+    });
+    const archives = archiveRows.map((row) => {
+        const repoMeta = repoMetaById.get(row.repo_id);
+        if (!repoMeta) {
+            throw new Error(`Missing sync metadata for repository ${row.repo_id}`);
+        }
+        return {
+            repoSyncKey: repoMeta.syncKey,
+            slug: row.slug,
+            archivedAt: row.archived_at
+        };
+    });
+    return parseSyncBundle({
+        type: 'steward-sync-bundle',
+        formatVersion: 1,
+        bundleId: options.bundleId || randomUUID(),
+        createdAt,
+        sourceDeviceId,
+        stewardVersion,
+        repos: syncRepos,
+        states,
+        archives
+    });
+}
+export function serializeSyncBundle(bundle) {
+    return JSON.stringify(bundle, null, 2);
+}