@thxgg/steward 0.1.23 → 0.1.25

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);
+}

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

@@ -0,0 +1,231 @@
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { dbGet, dbRun } from './db.js';
+import { isGitRepo } from './git.js';
+const SYNC_DEVICE_ID_KEY = 'sync:device-id';
+const SYNC_KEY_PREFIX = 'rsk_';
+const GIT_REMOTE_FINGERPRINT_KIND = 'git-remotes-v1';
+const REPO_SHAPE_FINGERPRINT_KIND = 'repo-shape-v1';
+function nowIso() {
+    return new Date().toISOString();
+}
+function sha256Hex(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function normalizePathSlashes(path) {
+    return path.replaceAll('\\', '/');
+}
+function createSyncKey() {
+    return `${SYNC_KEY_PREFIX}${randomUUID().replaceAll('-', '')}`;
+}
+async function execGit(repoPath, args) {
+    return new Promise((resolvePromise) => {
+        const proc = spawn('git', args, {
+            cwd: repoPath,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }
+        });
+        let stdout = '';
+        proc.stdout.on('data', (data) => {
+            stdout += data.toString();
+        });
+        proc.on('close', (code) => {
+            resolvePromise({
+                ok: code === 0,
+                stdout
+            });
+        });
+        proc.on('error', () => {
+            resolvePromise({ ok: false, stdout: '' });
+        });
+    });
+}
+function normalizeRemoteUrl(url) {
+    const trimmed = url.trim();
+    if (!trimmed) {
+        return '';
+    }
+    const scpLikeMatch = trimmed.match(/^([^@/\s]+)@([^:/\s]+):(.+)$/);
+    const candidate = scpLikeMatch
+        ? `ssh://${scpLikeMatch[1]}@${scpLikeMatch[2]}/${scpLikeMatch[3]}`
+        : trimmed;
+    try {
+        const parsed = new URL(candidate);
+        const protocol = parsed.protocol.toLowerCase();
+        const username = parsed.username ? `${parsed.username}@` : '';
+        const hostname = parsed.hostname.toLowerCase();
+        const port = parsed.port ? `:${parsed.port}` : '';
+        let pathname = parsed.pathname.replace(/\/+/g, '/').replace(/\.git$/i, '').replace(/\/$/, '');
+        pathname = pathname.toLowerCase();
+        return `${protocol}//${username}${hostname}${port}${pathname}`;
+    }
+    catch {
+        return candidate.replace(/\.git$/i, '').toLowerCase();
+    }
+}
+function mapRepoSyncMetaRow(row) {
+    return {
+        repoId: row.repo_id,
+        syncKey: row.sync_key,
+        fingerprint: row.fingerprint || '',
+        fingerprintKind: row.fingerprint_kind || '',
+        updatedAt: row.updated_at
+    };
+}
+function getGitRoots(repo) {
+    const roots = new Map();
+    roots.set(resolve(repo.path), {
+        repoRef: '',
+        path: repo.path
+    });
+    for (const gitRepo of repo.gitRepos || []) {
+        const repoRef = normalizePathSlashes(gitRepo.relativePath).replace(/^\.\//, '').replace(/\/$/, '');
+        if (!repoRef) {
+            continue;
+        }
+        roots.set(resolve(gitRepo.absolutePath), {
+            repoRef,
+            path: gitRepo.absolutePath
+        });
+    }
+    return Array.from(roots.values());
+}
+async function readGitRemoteSignatures(repo) {
+    const roots = getGitRoots(repo);
+    const signatures = new Set();
+    for (const root of roots) {
+        if (!await isGitRepo(root.path)) {
+            continue;
+        }
+        const result = await execGit(root.path, ['config', '--get-regexp', '^remote\\..*\\.url$']);
+        if (!result.ok) {
+            continue;
+        }
+        const lines = result.stdout
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        for (const line of lines) {
+            const firstSpace = line.indexOf(' ');
+            const rawUrl = firstSpace >= 0 ? line.slice(firstSpace + 1).trim() : line;
+            const normalized = normalizeRemoteUrl(rawUrl);
+            if (!normalized) {
+                continue;
+            }
+            signatures.add(`${root.repoRef}:${normalized}`);
+        }
+    }
+    return Array.from(signatures).sort((a, b) => a.localeCompare(b));
+}
+async function readPrdSlugs(repoPath) {
+    try {
+        const files = await fs.readdir(join(repoPath, 'docs', 'prd'));
+        return files
+            .filter((file) => file.endsWith('.md'))
+            .map((file) => basename(file, '.md'))
+            .sort((a, b) => a.localeCompare(b));
+    }
+    catch {
+        return [];
+    }
+}
+export async function calculateRepoFingerprint(repo) {
+    const remoteSignatures = await readGitRemoteSignatures(repo);
+    if (remoteSignatures.length > 0) {
+        return {
+            fingerprint: sha256Hex(JSON.stringify(remoteSignatures)),
+            fingerprintKind: GIT_REMOTE_FINGERPRINT_KIND
+        };
+    }
+    const prdSlugs = await readPrdSlugs(repo.path);
+    const nestedRepos = (repo.gitRepos || [])
+        .map((gitRepo) => normalizePathSlashes(gitRepo.relativePath).replace(/^\.\//, '').replace(/\/$/, ''))
+        .filter((value) => value.length > 0)
+        .sort((a, b) => a.localeCompare(b));
+    return {
+        fingerprint: sha256Hex(JSON.stringify({
+            name: repo.name.trim().toLowerCase(),
+            prdSlugs,
+            nestedRepos
+        })),
+        fingerprintKind: REPO_SHAPE_FINGERPRINT_KIND
+    };
+}
+export async function getOrCreateSyncDeviceId() {
+    const existing = await dbGet('SELECT value FROM app_meta WHERE key = ?', [SYNC_DEVICE_ID_KEY]);
+    if (existing?.value) {
+        return existing.value;
+    }
+    const createdAt = nowIso();
+    const generatedValue = randomUUID();
+    await dbRun(`
+      INSERT INTO app_meta (key, value, updated_at)
+      VALUES (?, ?, ?)
+      ON CONFLICT(key) DO NOTHING
+    `, [SYNC_DEVICE_ID_KEY, generatedValue, createdAt]);
+    const resolved = await dbGet('SELECT value FROM app_meta WHERE key = ?', [SYNC_DEVICE_ID_KEY]);
+    if (!resolved?.value) {
+        throw new Error('Failed to initialize sync device identifier');
+    }
+    return resolved.value;
+}
+export async function getRepoSyncMeta(repoId) {
+    const row = await dbGet(`
+      SELECT repo_id, sync_key, fingerprint, fingerprint_kind, updated_at
+      FROM repo_sync_meta
+      WHERE repo_id = ?
+    `, [repoId]);
+    return row ? mapRepoSyncMetaRow(row) : null;
+}
+export async function ensureRepoSyncMetaForRepo(repo) {
+    await getOrCreateSyncDeviceId();
+    const { fingerprint, fingerprintKind } = await calculateRepoFingerprint(repo);
+    const existing = await dbGet(`
+      SELECT repo_id, sync_key, fingerprint, fingerprint_kind, updated_at
+      FROM repo_sync_meta
+      WHERE repo_id = ?
+    `, [repo.id]);
+    const updatedAt = nowIso();
+    if (!existing) {
+        const created = {
+            repoId: repo.id,
+            syncKey: createSyncKey(),
+            fingerprint,
+            fingerprintKind,
+            updatedAt
+        };
+        await dbRun(`
+        INSERT INTO repo_sync_meta (repo_id, sync_key, fingerprint, fingerprint_kind, updated_at)
+        VALUES (?, ?, ?, ?, ?)
+      `, [created.repoId, created.syncKey, created.fingerprint, created.fingerprintKind, created.updatedAt]);
+        return created;
+    }
+    if (existing.fingerprint !== fingerprint || existing.fingerprint_kind !== fingerprintKind) {
+        await dbRun(`
+        UPDATE repo_sync_meta
+        SET fingerprint = ?, fingerprint_kind = ?, updated_at = ?
+        WHERE repo_id = ?
+      `, [fingerprint, fingerprintKind, updatedAt, repo.id]);
+        return {
+            repoId: existing.repo_id,
+            syncKey: existing.sync_key,
+            fingerprint,
+            fingerprintKind,
+            updatedAt
+        };
+    }
+    return mapRepoSyncMetaRow(existing);
+}
+export async function ensureRepoSyncMetaForRepos(repos) {
+    const metaByRepoId = new Map();
+    if (repos.length === 0) {
+        return metaByRepoId;
+    }
+    await getOrCreateSyncDeviceId();
+    for (const repo of repos) {
+        const meta = await ensureRepoSyncMetaForRepo(repo);
+        metaByRepoId.set(repo.id, meta);
+    }
+    return metaByRepoId;
+}

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

@@ -0,0 +1,103 @@
+import { parseSyncBundle } from './sync-schema.js';
+function uniqueSorted(values) {
+    return Array.from(new Set(values)).sort((a, b) => a.localeCompare(b));
+}
+function sortByKey(values) {
+    return [...values].sort((a, b) => a.repoSyncKey.localeCompare(b.repoSyncKey));
+}
+function toRepoInspection(accumulator) {
+    const stateSlugs = uniqueSorted(accumulator.stateSlugs);
+    const archiveSlugs = uniqueSorted(accumulator.archiveSlugs);
+    return {
+        repoSyncKey: accumulator.repo.repoSyncKey,
+        name: accumulator.repo.name,
+        ...(accumulator.repo.pathHint ? { pathHint: accumulator.repo.pathHint } : {}),
+        fingerprint: accumulator.repo.fingerprint,
+        fingerprintKind: accumulator.repo.fingerprintKind,
+        stateCount: stateSlugs.length,
+        archiveCount: archiveSlugs.length,
+        stateSlugs,
+        archiveSlugs
+    };
+}
+function collectUnknownRepoRows(rows, knownRepoKeys) {
+    const slugsByRepoKey = new Map();
+    for (const row of rows) {
+        if (knownRepoKeys.has(row.repoSyncKey)) {
+            continue;
+        }
+        const current = slugsByRepoKey.get(row.repoSyncKey);
+        if (current) {
+            current.push(row.slug);
+        }
+        else {
+            slugsByRepoKey.set(row.repoSyncKey, [row.slug]);
+        }
+    }
+    return Array.from(slugsByRepoKey.entries())
+        .map(([repoSyncKey, slugs]) => ({
+        repoSyncKey,
+        slugs: uniqueSorted(slugs)
+    }))
+        .sort((a, b) => a.repoSyncKey.localeCompare(b.repoSyncKey));
+}
+export function inspectSyncBundle(bundleInput) {
+    const bundle = parseSyncBundle(bundleInput);
+    const repoAccumulators = new Map();
+    for (const repo of sortByKey(bundle.repos)) {
+        repoAccumulators.set(repo.repoSyncKey, {
+            repo,
+            stateSlugs: [],
+            archiveSlugs: []
+        });
+    }
+    for (const state of bundle.states) {
+        const accumulator = repoAccumulators.get(state.repoSyncKey);
+        if (!accumulator) {
+            continue;
+        }
+        accumulator.stateSlugs.push(state.slug);
+    }
+    for (const archive of bundle.archives) {
+        const accumulator = repoAccumulators.get(archive.repoSyncKey);
+        if (!accumulator) {
+            continue;
+        }
+        accumulator.archiveSlugs.push(archive.slug);
+    }
+    const repos = Array.from(repoAccumulators.values())
+        .map((entry) => toRepoInspection(entry))
+        .sort((a, b) => a.repoSyncKey.localeCompare(b.repoSyncKey));
+    const knownRepoKeys = new Set(bundle.repos.map((repo) => repo.repoSyncKey));
+    const unknownRepoStates = collectUnknownRepoRows(bundle.states, knownRepoKeys);
+    const unknownRepoArchives = collectUnknownRepoRows(bundle.archives, knownRepoKeys);
+    return {
+        type: bundle.type,
+        formatVersion: bundle.formatVersion,
+        bundleId: bundle.bundleId,
+        createdAt: bundle.createdAt,
+        sourceDeviceId: bundle.sourceDeviceId,
+        stewardVersion: bundle.stewardVersion,
+        totals: {
+            repos: bundle.repos.length,
+            states: bundle.states.length,
+            archives: bundle.archives.length,
+            unknownRepoStates: unknownRepoStates.reduce((sum, item) => sum + item.slugs.length, 0),
+            unknownRepoArchives: unknownRepoArchives.reduce((sum, item) => sum + item.slugs.length, 0)
+        },
+        repos,
+        unknownRepoStates,
+        unknownRepoArchives
+    };
+}
+export function inspectSyncBundleJson(jsonPayload) {
+    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 inspectSyncBundle(parsed);
+}