@thxgg/steward 0.1.23 → 0.1.25

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

@@ -0,0 +1,579 @@
+import { resolve } from 'node:path';
+import { dbAll } from './db.js';
+import { getRepos } from './repos.js';
+import { parseStoredProgressFile, parseTasksFile } from './state-schema.js';
+import { createSyncFieldHashes, parseSyncBundle } from './sync-schema.js';
+import { ensureRepoSyncMetaForRepos } from './sync-identity.js';
+function normalizePath(path) {
+    return resolve(path);
+}
+function createRepoIndex(localRepos) {
+    const byRepoId = new Map();
+    const byPath = new Map();
+    const bySyncKey = new Map();
+    const byFingerprint = new Map();
+    for (const repo of localRepos) {
+        byRepoId.set(repo.repoId, repo);
+        byPath.set(normalizePath(repo.repoPath), repo);
+        bySyncKey.set(repo.syncKey, repo);
+        const fingerprintKey = `${repo.fingerprintKind}:${repo.fingerprint}`;
+        const current = byFingerprint.get(fingerprintKey);
+        if (current) {
+            current.push(repo);
+        }
+        else {
+            byFingerprint.set(fingerprintKey, [repo]);
+        }
+    }
+    return { byRepoId, byPath, bySyncKey, byFingerprint };
+}
+function parseLocalJson(rawValue, parseValue, fallback) {
+    if (rawValue === null) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(rawValue);
+        try {
+            return parseValue(parsed);
+        }
+        catch {
+            return fallback(parsed);
+        }
+    }
+    catch {
+        return rawValue;
+    }
+}
+function toClock(primary, fallback, hasValue) {
+    if (primary) {
+        return primary;
+    }
+    if (hasValue) {
+        return fallback;
+    }
+    return null;
+}
+function compareIsoTimestamps(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    if (!a && !b) {
+        return 0;
+    }
+    if (!a) {
+        return -1;
+    }
+    if (!b) {
+        return 1;
+    }
+    const aEpoch = Date.parse(a);
+    const bEpoch = Date.parse(b);
+    if (Number.isFinite(aEpoch) && Number.isFinite(bEpoch) && aEpoch !== bEpoch) {
+        return aEpoch > bEpoch ? 1 : -1;
+    }
+    return a.localeCompare(b);
+}
+function compareHashes(a, b) {
+    const left = a || '';
+    const right = b || '';
+    return left.localeCompare(right);
+}
+function decideFieldMerge(params) {
+    const { localClock, incomingClock, localHash, incomingHash } = params;
+    const valueChanged = (localHash || '') !== (incomingHash || '');
+    const clockChanged = localClock !== incomingClock;
+    const conflict = valueChanged && localHash !== null && incomingHash !== null;
+    if (!valueChanged && !clockChanged) {
+        return {
+            winner: 'local',
+            reason: 'equal_value',
+            localClock,
+            incomingClock,
+            localHash,
+            incomingHash,
+            changed: false,
+            valueChanged,
+            clockChanged,
+            conflict
+        };
+    }
+    if (incomingClock && localClock) {
+        const timestampComparison = compareIsoTimestamps(incomingClock, localClock);
+        if (timestampComparison > 0) {
+            return {
+                winner: 'incoming',
+                reason: 'incoming_newer_clock',
+                localClock,
+                incomingClock,
+                localHash,
+                incomingHash,
+                changed: valueChanged || clockChanged,
+                valueChanged,
+                clockChanged,
+                conflict
+            };
+        }
+        if (timestampComparison < 0) {
+            return {
+                winner: 'local',
+                reason: 'local_newer_clock',
+                localClock,
+                incomingClock,
+                localHash,
+                incomingHash,
+                changed: false,
+                valueChanged,
+                clockChanged,
+                conflict
+            };
+        }
+    }
+    else if (incomingClock && !localClock) {
+        return {
+            winner: 'incoming',
+            reason: 'incoming_has_clock',
+            localClock,
+            incomingClock,
+            localHash,
+            incomingHash,
+            changed: valueChanged || clockChanged,
+            valueChanged,
+            clockChanged,
+            conflict
+        };
+    }
+    else if (!incomingClock && localClock) {
+        return {
+            winner: 'local',
+            reason: 'local_has_clock',
+            localClock,
+            incomingClock,
+            localHash,
+            incomingHash,
+            changed: false,
+            valueChanged,
+            clockChanged,
+            conflict
+        };
+    }
+    const hashComparison = compareHashes(incomingHash, localHash);
+    if (hashComparison > 0) {
+        return {
+            winner: 'incoming',
+            reason: 'incoming_hash_tiebreak',
+            localClock,
+            incomingClock,
+            localHash,
+            incomingHash,
+            changed: valueChanged || clockChanged,
+            valueChanged,
+            clockChanged,
+            conflict
+        };
+    }
+    if (hashComparison < 0) {
+        return {
+            winner: 'local',
+            reason: 'local_hash_tiebreak',
+            localClock,
+            incomingClock,
+            localHash,
+            incomingHash,
+            changed: false,
+            valueChanged,
+            clockChanged,
+            conflict
+        };
+    }
+    return {
+        winner: 'local',
+        reason: 'equal_value',
+        localClock,
+        incomingClock,
+        localHash,
+        incomingHash,
+        changed: false,
+        valueChanged,
+        clockChanged,
+        conflict
+    };
+}
+function buildStateKey(repoId, slug) {
+    return `${repoId}:${slug}`;
+}
+function resolveMappedRepo(incomingRepoSyncKey, incomingRepoMeta, repoIndex, repoMap) {
+    const mappedValue = repoMap[incomingRepoSyncKey];
+    if (typeof mappedValue === 'string' && mappedValue.trim().length > 0) {
+        const target = mappedValue.trim();
+        const byId = repoIndex.byRepoId.get(target)
+            || repoIndex.byPath.get(normalizePath(target))
+            || repoIndex.bySyncKey.get(target);
+        if (!byId) {
+            return {
+                incomingRepoSyncKey,
+                ...(incomingRepoMeta?.name ? { incomingRepoName: incomingRepoMeta.name } : {}),
+                source: 'unresolved',
+                reason: 'map_target_not_found'
+            };
+        }
+        return {
+            incomingRepoSyncKey,
+            ...(incomingRepoMeta?.name ? { incomingRepoName: incomingRepoMeta.name } : {}),
+            localRepoId: byId.repoId,
+            localRepoPath: byId.repoPath,
+            localRepoSyncKey: byId.syncKey,
+            source: 'map'
+        };
+    }
+    const bySyncKey = repoIndex.bySyncKey.get(incomingRepoSyncKey);
+    if (bySyncKey) {
+        return {
+            incomingRepoSyncKey,
+            ...(incomingRepoMeta?.name ? { incomingRepoName: incomingRepoMeta.name } : {}),
+            localRepoId: bySyncKey.repoId,
+            localRepoPath: bySyncKey.repoPath,
+            localRepoSyncKey: bySyncKey.syncKey,
+            source: 'sync_key'
+        };
+    }
+    if (!incomingRepoMeta?.fingerprint || !incomingRepoMeta.fingerprintKind) {
+        return {
+            incomingRepoSyncKey,
+            ...(incomingRepoMeta?.name ? { incomingRepoName: incomingRepoMeta.name } : {}),
+            source: 'unresolved',
+            reason: incomingRepoMeta ? 'no_match' : 'unknown_repo_metadata'
+        };
+    }
+    const fingerprintKey = `${incomingRepoMeta.fingerprintKind}:${incomingRepoMeta.fingerprint}`;
+    const matches = repoIndex.byFingerprint.get(fingerprintKey) || [];
+    if (matches.length === 1) {
+        const matchedRepo = matches[0];
+        return {
+            incomingRepoSyncKey,
+            ...(incomingRepoMeta?.name ? { incomingRepoName: incomingRepoMeta.name } : {}),
+            localRepoId: matchedRepo.repoId,
+            localRepoPath: matchedRepo.repoPath,
+            localRepoSyncKey: matchedRepo.syncKey,
+            source: 'fingerprint'
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            incomingRepoSyncKey,
+            ...(incomingRepoMeta?.name ? { incomingRepoName: incomingRepoMeta.name } : {}),
+            source: 'unresolved',
+            reason: 'fingerprint_ambiguous'
+        };
+    }
+    return {
+        incomingRepoSyncKey,
+        ...(incomingRepoMeta?.name ? { incomingRepoName: incomingRepoMeta.name } : {}),
+        source: 'unresolved',
+        reason: 'no_match'
+    };
+}
+async function loadLocalStateRows(repoIds) {
+    if (repoIds.length === 0) {
+        return new Map();
+    }
+    const placeholders = repoIds.map(() => '?').join(', ');
+    const rows = 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})
+    `, repoIds);
+    const byKey = new Map();
+    for (const row of rows) {
+        byKey.set(buildStateKey(row.repo_id, row.slug), row);
+    }
+    return byKey;
+}
+async function loadLocalArchiveRows(repoIds) {
+    if (repoIds.length === 0) {
+        return new Map();
+    }
+    const placeholders = repoIds.map(() => '?').join(', ');
+    const rows = await dbAll(`
+      SELECT repo_id, slug, archived_at
+      FROM prd_archives
+      WHERE repo_id IN (${placeholders})
+    `, repoIds);
+    const byKey = new Map();
+    for (const row of rows) {
+        byKey.set(buildStateKey(row.repo_id, row.slug), row);
+    }
+    return byKey;
+}
+function getIncomingRepoMeta(bundle, repoSyncKey) {
+    const repo = bundle.repos.find((entry) => entry.repoSyncKey === repoSyncKey);
+    if (!repo) {
+        return null;
+    }
+    return {
+        name: repo.name,
+        fingerprint: repo.fingerprint,
+        fingerprintKind: repo.fingerprintKind
+    };
+}
+function parseLocalTasks(row) {
+    return parseLocalJson(row.tasks_json, parseTasksFile, (value) => value);
+}
+function parseLocalProgress(row, tasks) {
+    return parseLocalJson(row.progress_json, (value) => parseStoredProgressFile(value, {
+        totalTasksHint: tasks && typeof tasks === 'object' && !Array.isArray(tasks)
+            ? Array.isArray(tasks.tasks)
+                ? (tasks.tasks.length)
+                : undefined
+            : undefined,
+        prdNameFallback: row.slug
+    }), (value) => value);
+}
+function buildStateRowPlan(params) {
+    const { row, mapping, localStateRows } = params;
+    if (!mapping.localRepoId || mapping.source === 'unresolved') {
+        return {
+            repoSyncKey: row.repoSyncKey,
+            slug: row.slug,
+            action: 'unresolved',
+            mappingSource: mapping.source,
+            ...(mapping.reason ? { reason: mapping.reason } : {}),
+            updateFields: [],
+            conflictFields: []
+        };
+    }
+    const stateKey = buildStateKey(mapping.localRepoId, row.slug);
+    const localRow = localStateRows.get(stateKey);
+    if (!localRow) {
+        return {
+            repoSyncKey: row.repoSyncKey,
+            slug: row.slug,
+            action: 'insert',
+            localRepoId: mapping.localRepoId,
+            ...(mapping.localRepoPath ? { localRepoPath: mapping.localRepoPath } : {}),
+            mappingSource: mapping.source,
+            updateFields: ['tasks', 'progress', 'notes'],
+            conflictFields: []
+        };
+    }
+    const localTasks = parseLocalTasks(localRow);
+    const localProgress = parseLocalProgress(localRow, localTasks);
+    const localNotes = localRow.notes_md;
+    const localClocks = {
+        tasksUpdatedAt: toClock(localRow.tasks_updated_at, localRow.updated_at, localTasks !== null),
+        progressUpdatedAt: toClock(localRow.progress_updated_at, localRow.updated_at, localProgress !== null),
+        notesUpdatedAt: toClock(localRow.notes_updated_at, localRow.updated_at, localNotes !== null)
+    };
+    const localHashes = createSyncFieldHashes({
+        tasks: localTasks,
+        progress: localProgress,
+        notes: localNotes
+    });
+    const incomingHashes = createSyncFieldHashes({
+        tasks: row.tasks,
+        progress: row.progress,
+        notes: row.notes
+    });
+    const tasksDecision = decideFieldMerge({
+        localClock: localClocks.tasksUpdatedAt,
+        incomingClock: row.clocks.tasksUpdatedAt,
+        localHash: localHashes.tasksHash,
+        incomingHash: incomingHashes.tasksHash
+    });
+    const progressDecision = decideFieldMerge({
+        localClock: localClocks.progressUpdatedAt,
+        incomingClock: row.clocks.progressUpdatedAt,
+        localHash: localHashes.progressHash,
+        incomingHash: incomingHashes.progressHash
+    });
+    const notesDecision = decideFieldMerge({
+        localClock: localClocks.notesUpdatedAt,
+        incomingClock: row.clocks.notesUpdatedAt,
+        localHash: localHashes.notesHash,
+        incomingHash: incomingHashes.notesHash
+    });
+    const updateFields = [];
+    const conflictFields = [];
+    if (tasksDecision.changed) {
+        updateFields.push('tasks');
+    }
+    if (progressDecision.changed) {
+        updateFields.push('progress');
+    }
+    if (notesDecision.changed) {
+        updateFields.push('notes');
+    }
+    if (tasksDecision.conflict) {
+        conflictFields.push('tasks');
+    }
+    if (progressDecision.conflict) {
+        conflictFields.push('progress');
+    }
+    if (notesDecision.conflict) {
+        conflictFields.push('notes');
+    }
+    return {
+        repoSyncKey: row.repoSyncKey,
+        slug: row.slug,
+        action: updateFields.length > 0 ? 'update' : 'skip',
+        localRepoId: mapping.localRepoId,
+        ...(mapping.localRepoPath ? { localRepoPath: mapping.localRepoPath } : {}),
+        mappingSource: mapping.source,
+        updateFields,
+        conflictFields,
+        fieldDecisions: {
+            tasks: tasksDecision,
+            progress: progressDecision,
+            notes: notesDecision
+        }
+    };
+}
+function buildArchiveRowPlan(params) {
+    const { row, mapping, localArchiveRows } = params;
+    if (!mapping.localRepoId || mapping.source === 'unresolved') {
+        return {
+            repoSyncKey: row.repoSyncKey,
+            slug: row.slug,
+            action: 'unresolved',
+            mappingSource: mapping.source,
+            ...(mapping.reason ? { reason: mapping.reason } : {})
+        };
+    }
+    const archiveKey = buildStateKey(mapping.localRepoId, row.slug);
+    const localRow = localArchiveRows.get(archiveKey);
+    if (!localRow) {
+        return {
+            repoSyncKey: row.repoSyncKey,
+            slug: row.slug,
+            action: 'insert',
+            localRepoId: mapping.localRepoId,
+            ...(mapping.localRepoPath ? { localRepoPath: mapping.localRepoPath } : {}),
+            mappingSource: mapping.source
+        };
+    }
+    const incomingIsNewer = compareIsoTimestamps(row.archivedAt, localRow.archived_at) > 0;
+    return {
+        repoSyncKey: row.repoSyncKey,
+        slug: row.slug,
+        action: incomingIsNewer ? 'update' : 'skip',
+        localRepoId: mapping.localRepoId,
+        ...(mapping.localRepoPath ? { localRepoPath: mapping.localRepoPath } : {}),
+        mappingSource: mapping.source
+    };
+}
+export async function planSyncMerge(bundleInput, options = {}) {
+    const bundle = parseSyncBundle(bundleInput);
+    const localRepos = await getRepos();
+    const repoMetaById = await ensureRepoSyncMetaForRepos(localRepos);
+    const identities = localRepos.map((repo) => {
+        const meta = repoMetaById.get(repo.id);
+        if (!meta) {
+            throw new Error(`Missing sync metadata for local repository ${repo.id}`);
+        }
+        return {
+            repoId: repo.id,
+            repoPath: repo.path,
+            syncKey: meta.syncKey,
+            fingerprint: meta.fingerprint,
+            fingerprintKind: meta.fingerprintKind
+        };
+    });
+    const repoIndex = createRepoIndex(identities);
+    const incomingRepoKeys = new Set();
+    for (const repo of bundle.repos) {
+        incomingRepoKeys.add(repo.repoSyncKey);
+    }
+    for (const row of bundle.states) {
+        incomingRepoKeys.add(row.repoSyncKey);
+    }
+    for (const row of bundle.archives) {
+        incomingRepoKeys.add(row.repoSyncKey);
+    }
+    const mappingResults = Array.from(incomingRepoKeys)
+        .sort((a, b) => a.localeCompare(b))
+        .map((repoSyncKey) => {
+        return resolveMappedRepo(repoSyncKey, getIncomingRepoMeta(bundle, repoSyncKey), repoIndex, options.repoMap || {});
+    });
+    const mappingByIncomingKey = new Map(mappingResults.map((result) => [result.incomingRepoSyncKey, result]));
+    const mappedRepoIds = Array.from(new Set(mappingResults
+        .map((result) => result.localRepoId)
+        .filter((value) => typeof value === 'string' && value.length > 0)));
+    const [localStateRows, localArchiveRows] = await Promise.all([
+        loadLocalStateRows(mappedRepoIds),
+        loadLocalArchiveRows(mappedRepoIds)
+    ]);
+    const statePlans = bundle.states.map((row) => {
+        const mapping = mappingByIncomingKey.get(row.repoSyncKey) || {
+            incomingRepoSyncKey: row.repoSyncKey,
+            source: 'unresolved',
+            reason: 'unknown_repo_metadata'
+        };
+        return buildStateRowPlan({
+            row,
+            mapping,
+            localStateRows
+        });
+    });
+    const archivePlans = bundle.archives.map((row) => {
+        const mapping = mappingByIncomingKey.get(row.repoSyncKey) || {
+            incomingRepoSyncKey: row.repoSyncKey,
+            source: 'unresolved',
+            reason: 'unknown_repo_metadata'
+        };
+        return buildArchiveRowPlan({
+            row,
+            mapping,
+            localArchiveRows
+        });
+    });
+    const summary = {
+        repos: {
+            mapped: mappingResults.filter((result) => result.source !== 'unresolved').length,
+            unresolved: mappingResults.filter((result) => result.source === 'unresolved').length
+        },
+        states: {
+            insert: statePlans.filter((row) => row.action === 'insert').length,
+            update: statePlans.filter((row) => row.action === 'update').length,
+            skip: statePlans.filter((row) => row.action === 'skip').length,
+            unresolved: statePlans.filter((row) => row.action === 'unresolved').length,
+            conflicts: statePlans.reduce((sum, row) => sum + row.conflictFields.length, 0)
+        },
+        archives: {
+            insert: archivePlans.filter((row) => row.action === 'insert').length,
+            update: archivePlans.filter((row) => row.action === 'update').length,
+            skip: archivePlans.filter((row) => row.action === 'skip').length,
+            unresolved: archivePlans.filter((row) => row.action === 'unresolved').length
+        }
+    };
+    return {
+        bundle: {
+            bundleId: bundle.bundleId,
+            formatVersion: bundle.formatVersion,
+            sourceDeviceId: bundle.sourceDeviceId,
+            createdAt: bundle.createdAt
+        },
+        mappings: mappingResults,
+        states: statePlans,
+        archives: archivePlans,
+        summary
+    };
+}
+export async function planSyncMergeJson(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 planSyncMerge(parsed, options);
+}

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

@@ -0,0 +1,100 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+export const SYNC_BUNDLE_TYPE = 'steward-sync-bundle';
+export const SYNC_BUNDLE_FORMAT_VERSION = 1;
+const prdSlugSchema = z.string().trim().regex(/^[A-Za-z0-9][A-Za-z0-9-]*$/);
+const syncRepoSchema = z.object({
+    repoSyncKey: z.string().trim().min(1),
+    name: z.string().trim().min(1),
+    pathHint: z.string().trim().min(1).optional(),
+    fingerprint: z.string().trim().min(1),
+    fingerprintKind: z.string().trim().min(1)
+});
+const syncFieldClocksSchema = z.object({
+    tasksUpdatedAt: z.string().nullable(),
+    progressUpdatedAt: z.string().nullable(),
+    notesUpdatedAt: z.string().nullable()
+});
+const syncFieldHashesSchema = z.object({
+    tasksHash: z.string().nullable(),
+    progressHash: z.string().nullable(),
+    notesHash: z.string().nullable()
+});
+const syncStateRowSchema = z.object({
+    repoSyncKey: z.string().trim().min(1),
+    slug: prdSlugSchema,
+    tasks: z.unknown().nullable(),
+    progress: z.unknown().nullable(),
+    notes: z.string().nullable(),
+    clocks: syncFieldClocksSchema,
+    hashes: syncFieldHashesSchema
+});
+const syncArchiveRowSchema = z.object({
+    repoSyncKey: z.string().trim().min(1),
+    slug: prdSlugSchema,
+    archivedAt: z.string().trim().min(1)
+});
+const syncBundleSchema = z.object({
+    type: z.literal(SYNC_BUNDLE_TYPE),
+    formatVersion: z.literal(SYNC_BUNDLE_FORMAT_VERSION),
+    bundleId: z.string().trim().min(1),
+    createdAt: z.string().trim().min(1),
+    sourceDeviceId: z.string().trim().min(1),
+    stewardVersion: z.string().trim().min(1),
+    repos: z.array(syncRepoSchema),
+    states: z.array(syncStateRowSchema),
+    archives: z.array(syncArchiveRowSchema)
+});
+function canonicalize(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => canonicalize(entry));
+    }
+    if (!value || typeof value !== 'object') {
+        return value;
+    }
+    const objectValue = value;
+    const keys = Object.keys(objectValue).sort((a, b) => a.localeCompare(b));
+    const result = {};
+    for (const key of keys) {
+        result[key] = canonicalize(objectValue[key]);
+    }
+    return result;
+}
+export function toCanonicalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+export function hashCanonicalValue(value) {
+    return createHash('sha256').update(toCanonicalJson(value)).digest('hex');
+}
+export function hashNullableCanonicalValue(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    return hashCanonicalValue(value);
+}
+export function createSyncFieldHashes(fields) {
+    return {
+        tasksHash: hashNullableCanonicalValue(fields.tasks),
+        progressHash: hashNullableCanonicalValue(fields.progress),
+        notesHash: hashNullableCanonicalValue(fields.notes)
+    };
+}
+export function parseSyncBundle(value) {
+    return syncBundleSchema.parse(value);
+}
+export function validateSyncBundle(value) {
+    const parsed = syncBundleSchema.safeParse(value);
+    if (parsed.success) {
+        return { success: true };
+    }
+    const issue = parsed.error.issues[0];
+    if (!issue) {
+        return { success: false, error: 'Invalid sync bundle payload' };
+    }
+    return {
+        success: false,
+        error: issue.path.length > 0
+            ? `${issue.path.join('.')}: ${issue.message}`
+            : issue.message
+    };
+}