gnosys 5.11.4 → 5.12.2

package/dist/lib/syncClient.js

@@ -0,0 +1,234 @@
+/**
+ * v13 client-side sync: reachability heartbeat, offline snapshot rule, pending overlay.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import path from "path";
+import { GnosysDB } from "./db.js";
+import { readMachineConfig, getMachineId } from "./machineConfig.js";
+import { getConfiguredRemotePath } from "./remote.js";
+import { acceptClientSnapshot, clientSnapshotStore, compareSnapshotVersion, formatSnapshotAge, getClientAcceptedManifest, getMasterManifest, } from "./syncSnapshot.js";
+import { countFailedStagingFiles, machineStagingDir, stagingRoot } from "./syncStaging.js";
+import { renderClientSyncStatusLines, } from "./setup/remoteRender.js";
+const REACHABILITY_TTL_MS = 30_000;
+function readManifestHeartbeat(masterPath) {
+    const manifestPath = path.join(masterPath, "snapshots", "snapshot-manifest.json");
+    if (!existsSync(manifestPath))
+        return null;
+    try {
+        const m = JSON.parse(readFileSync(manifestPath, "utf-8"));
+        return m.publishedAt ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function isMasterReachable(masterPath) {
+    try {
+        const manifestPath = path.join(masterPath, "snapshots", "snapshot-manifest.json");
+        if (existsSync(manifestPath)) {
+            const mtime = statSync(manifestPath).mtimeMs;
+            if (Date.now() - mtime < REACHABILITY_TTL_MS)
+                return true;
+        }
+        const dbPath = path.join(masterPath, "gnosys.db");
+        if (existsSync(dbPath)) {
+            statSync(dbPath);
+            return true;
+        }
+        statSync(masterPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function countClientWaitingStaging(masterPath, machineId) {
+    const dir = machineStagingDir(masterPath, machineId);
+    if (!existsSync(dir))
+        return 0;
+    try {
+        return readdirSync(dir).filter((n) => n.endsWith(".json")).length;
+    }
+    catch {
+        return 0;
+    }
+}
+export function listClientReceipts(masterPath, machineId) {
+    const dir = path.join(stagingRoot(masterPath), machineId, "receipts");
+    if (!existsSync(dir))
+        return [];
+    const receipts = [];
+    for (const file of readdirSync(dir).filter((f) => f.endsWith(".json"))) {
+        try {
+            const raw = readFileSync(path.join(dir, file), "utf-8");
+            receipts.push(JSON.parse(raw));
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    return receipts;
+}
+export function getIngestedUlids(masterPath, machineId) {
+    return new Set(listClientReceipts(masterPath, machineId).map((r) => r.ulid));
+}
+export function openClientReadContext(localDb, masterPath, machineId) {
+    const mc = readMachineConfig();
+    const role = mc?.remote.role;
+    if (!role || role === "master") {
+        return {
+            db: localDb,
+            localDb,
+            pendingOverlay: [],
+            source: "master",
+            masterReachable: true,
+            ownsReadDb: false,
+        };
+    }
+    const reachable = isMasterReachable(masterPath);
+    const ingestedUlids = getIngestedUlids(masterPath, machineId);
+    const pendingAdds = localDb.listActivePendingAdds().filter((p) => !ingestedUlids.has(p.id));
+    const store = clientSnapshotStore(masterPath);
+    const snapPath = path.join(store, "gnosys.db");
+    if (reachable) {
+        // v13 completion (5.12.x): clients must not open the live gnosys.db over
+        // the network (concurrent master writes + network FS = torn-page hazard,
+        // DESIGN.md "The Simple Rule"). Refresh the verified local snapshot copy
+        // when the master has published a newer one, then read the local copy.
+        const manifest = getMasterManifest(masterPath);
+        if (manifest) {
+            const accepted = getClientAcceptedManifest(masterPath);
+            if (compareSnapshotVersion(accepted, manifest)) {
+                // Best effort — on checksum/copy failure we fall through to whatever
+                // local snapshot (or live-DB fallback) is still available.
+                acceptClientSnapshot(masterPath, manifest);
+            }
+            if (existsSync(snapPath)) {
+                const snapDb = new GnosysDB(store);
+                if (snapDb.isAvailable()) {
+                    return {
+                        db: snapDb,
+                        localDb,
+                        pendingOverlay: pendingAdds,
+                        source: "snapshot",
+                        masterReachable: true,
+                        ownsReadDb: true,
+                    };
+                }
+                snapDb.close();
+            }
+        }
+        // Compatibility fallback: master has never published a snapshot (older
+        // master version, or first sweep still pending) — open the live DB as
+        // before. Disappears once the master runs one publish-enabled sweep.
+        const masterDb = new GnosysDB(masterPath);
+        if (masterDb.isAvailable()) {
+            return {
+                db: masterDb,
+                localDb,
+                pendingOverlay: pendingAdds,
+                source: "master",
+                masterReachable: true,
+                ownsReadDb: true,
+            };
+        }
+        masterDb.close();
+    }
+    // Offline (soft rule, signed off 2026-06-11): the last-accepted snapshot
+    // stays readable — immutable + checksummed, and offline clients are
+    // add-only, so staleness is the only risk. Status surfaces snapshotAge.
+    if (existsSync(snapPath)) {
+        const snapDb = new GnosysDB(store);
+        if (snapDb.isAvailable()) {
+            return {
+                db: snapDb,
+                localDb,
+                pendingOverlay: pendingAdds,
+                source: "snapshot",
+                masterReachable: false,
+                ownsReadDb: true,
+            };
+        }
+        snapDb.close();
+    }
+    return {
+        db: localDb,
+        localDb,
+        pendingOverlay: pendingAdds,
+        source: "pending-only",
+        masterReachable: false,
+        ownsReadDb: false,
+    };
+}
+/** Release snapshot/master DB handles opened by openClientReadContext. */
+export function closeClientReadContext(ctx) {
+    if (ctx.ownsReadDb) {
+        ctx.db.close();
+    }
+}
+export function getV13SyncStatus(localDb) {
+    const mc = readMachineConfig();
+    const masterPath = getConfiguredRemotePath(localDb);
+    const role = mc?.remote.role ?? null;
+    const empty = {
+        role,
+        masterPath,
+        masterReachable: false,
+        waitingToSync: 0,
+        failedToSync: 0,
+        pendingOfflineAdds: 0,
+        snapshotAge: null,
+        lines: [],
+    };
+    if (!masterPath || !role)
+        return empty;
+    const reachable = isMasterReachable(masterPath);
+    const machineId = getMachineId();
+    let waitingToSync = 0;
+    let failedToSync = 0;
+    if (role === "client") {
+        waitingToSync = countClientWaitingStaging(masterPath, machineId);
+        failedToSync = countFailedStagingFiles(masterPath, machineId);
+    }
+    else if (role === "master") {
+        const masterDb = new GnosysDB(masterPath);
+        if (masterDb.isAvailable()) {
+            waitingToSync = masterDb.countPendingStagingLedger();
+        }
+        masterDb.close();
+    }
+    let pendingOfflineAdds = 0;
+    if (localDb.isAvailable()) {
+        pendingOfflineAdds = localDb.listActivePendingAdds().length;
+    }
+    let snapshotAge = null;
+    const accepted = getClientAcceptedManifest(masterPath);
+    if (accepted?.publishedAt) {
+        snapshotAge = formatSnapshotAge(accepted.publishedAt);
+    }
+    else {
+        const pub = readManifestHeartbeat(masterPath);
+        if (pub)
+            snapshotAge = formatSnapshotAge(pub);
+    }
+    const input = {
+        masterReachable: reachable,
+        waitingToSync,
+        failedToSync,
+        pendingOfflineAdds: reachable ? undefined : pendingOfflineAdds,
+    };
+    const lines = renderClientSyncStatusLines(input);
+    if (snapshotAge && reachable) {
+        lines.push(`Snapshot as of ${snapshotAge}`);
+    }
+    return {
+        role,
+        masterPath,
+        masterReachable: reachable,
+        waitingToSync,
+        failedToSync,
+        pendingOfflineAdds,
+        snapshotAge,
+        lines,
+    };
+}

package/dist/lib/syncCommand.d.ts

@@ -0,0 +1,6 @@
+export type SyncCommandOptions = {
+    directory?: string;
+    target?: string;
+    global?: boolean;
+};
+export declare function runSyncCommand(opts: SyncCommandOptions): Promise<void>;

package/dist/lib/syncCommand.js

@@ -0,0 +1,57 @@
+import path from "path";
+import { GnosysDB } from "./db.js";
+import { readProjectIdentity } from "./projectIdentity.js";
+import { syncToTarget } from "./rulesGen.js";
+export async function runSyncCommand(opts) {
+    const projectDir = opts.directory ? path.resolve(opts.directory) : process.cwd();
+    const target = opts.global ? "global" : (opts.target || null);
+    let centralDb = null;
+    try {
+        centralDb = GnosysDB.openCentral();
+        if (!centralDb.isAvailable()) {
+            console.error("Central DB not available (better-sqlite3 missing).");
+            process.exitCode = 1;
+            return;
+        }
+        if (target === "global") {
+            const results = await syncToTarget(centralDb, projectDir, "global", null);
+            for (const result of results) {
+                const action = result.created ? "Created" : "Updated";
+                console.log(`${action} global rules: ${result.filePath}`);
+                console.log(`  Preferences injected: ${result.prefCount}`);
+            }
+            console.log(`\nContent is inside <!-- GNOSYS:START --> / <!-- GNOSYS:END --> markers.`);
+            console.log(`User content outside these markers is preserved.`);
+            return;
+        }
+        const identity = await readProjectIdentity(projectDir);
+        if (!identity) {
+            console.error("No project identity found. Run 'gnosys init' first.");
+            process.exitCode = 1;
+            return;
+        }
+        const resolvedTarget = target || identity.agentRulesTarget || "all";
+        const results = await syncToTarget(centralDb, projectDir, resolvedTarget, identity.projectId);
+        if (results.length === 0) {
+            console.error("No targets found. Create a CLAUDE.md, .cursor/, or .codex/ directory first.");
+            process.exitCode = 1;
+            return;
+        }
+        for (const result of results) {
+            const action = result.created ? "Created" : "Updated";
+            console.log(`${action} rules file: ${result.filePath}`);
+            console.log(`  Preferences injected: ${result.prefCount}`);
+            console.log(`  Project conventions:  ${result.conventionCount}`);
+        }
+        console.log(`\nContent is inside <!-- GNOSYS:START --> / <!-- GNOSYS:END --> markers.`);
+        console.log(`User content outside these markers is preserved.`);
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exitCode = 1;
+        return;
+    }
+    finally {
+        centralDb?.close();
+    }
+}

package/dist/lib/syncDoctorCommand.d.ts

@@ -0,0 +1,5 @@
+export declare function runSyncDoctorCommand(opts: {
+    json?: boolean;
+    ingest?: boolean;
+    quiet?: boolean;
+}): Promise<void>;

package/dist/lib/syncDoctorCommand.js

@@ -0,0 +1,100 @@
+import { GnosysDB } from "./db.js";
+import { getConfiguredRemotePath } from "./remote.js";
+import { readMachineConfig } from "./machineConfig.js";
+import { getV13SyncStatus } from "./syncClient.js";
+import { runMasterIngestSweepAndPublish } from "./syncIngest.js";
+import { getSyncIngestTimerStatus } from "./syncIngestTimer.js";
+import { quarantineStaleTmpFiles, stagingRoot } from "./syncStaging.js";
+import { existsSync, readdirSync } from "fs";
+import { readMasterMarker } from "./masterLease.js";
+import { printStatus } from "./setup/ui/status.js";
+export async function runSyncDoctorCommand(opts) {
+    let db = null;
+    try {
+        db = GnosysDB.openLocal();
+        if (!db.isAvailable()) {
+            console.error("Central DB not available.");
+            process.exitCode = 1;
+            return;
+        }
+        const masterPath = getConfiguredRemotePath(db);
+        const mc = readMachineConfig();
+        if (!masterPath || !mc?.remote.enabled) {
+            console.log("Multi-machine sync is not configured.");
+            return;
+        }
+        const status = getV13SyncStatus(db);
+        const marker = readMasterMarker(masterPath);
+        const timerStatus = getSyncIngestTimerStatus();
+        const report = {
+            role: status.role,
+            masterPath,
+            masterReachable: status.masterReachable,
+            waitingToSync: status.waitingToSync,
+            failedToSync: status.failedToSync,
+            pendingOfflineAdds: status.pendingOfflineAdds,
+            masterEpoch: marker?.epoch ?? null,
+            snapshotAge: status.snapshotAge,
+            timerInstalled: timerStatus.installed,
+            timerPath: timerStatus.path || null,
+            timerPlatform: timerStatus.platform,
+        };
+        let ingestResult = null;
+        if (opts.ingest && mc.remote.role === "master") {
+            const root = stagingRoot(masterPath);
+            if (existsSync(root)) {
+                for (const id of readdirSync(root)) {
+                    if (!id.startsWith("."))
+                        quarantineStaleTmpFiles(masterPath, id);
+                }
+            }
+            ingestResult = await runMasterIngestSweepAndPublish(masterPath, {
+                quiet: opts.quiet || !!opts.json,
+            });
+            if (ingestResult.errors.length > 0) {
+                process.exitCode = 1;
+            }
+            if (opts.json) {
+                report.ingest = ingestResult;
+            }
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        console.log("\nGnosys sync doctor (v13)\n");
+        for (const line of status.lines)
+            console.log(line);
+        if (marker) {
+            console.log(`\nMaster lease: epoch ${marker.epoch}, holder ${marker.holderMachineId}`);
+        }
+        if (timerStatus.installed) {
+            console.log(`\nIngest timer: installed (${timerStatus.path})`);
+        }
+        else if (timerStatus.platform === "unsupported") {
+            console.log("\nIngest timer: not available on this platform (Windows — use doctor --ingest manually)");
+        }
+        else {
+            console.log("\nIngest timer: not installed");
+            console.log("Install with: gnosys setup remote timer --install");
+        }
+        if (status.failedToSync > 0) {
+            printStatus("progress", "remediation", "inspect master-folder/.gnosys-staging/*/failed/");
+        }
+        if (!status.masterReachable) {
+            printStatus("warn", "mount or VPN path to master folder, then re-run doctor");
+        }
+        if (opts.ingest && mc.remote.role === "master" && ingestResult && !opts.quiet) {
+            console.log(`\nIngest sweep: +${ingestResult.ingested} ingested, ${ingestResult.skipped} skipped, ${ingestResult.quarantined} quarantined`);
+            for (const e of ingestResult.errors)
+                printStatus("fail", e);
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exitCode = 1;
+    }
+    finally {
+        db?.close();
+    }
+}

package/dist/lib/syncIngest.d.ts

@@ -0,0 +1,30 @@
+/**
+ * v13 master ingest sweep — process staged JSON into gnosys.db.
+ */
+export interface IngestSweepResult {
+    ingested: number;
+    skipped: number;
+    quarantined: number;
+    errors: string[];
+}
+export interface IngestSweepOptions {
+    /** Suppress stdout (for timer / background contexts). */
+    quiet?: boolean;
+    /** Write a single JSON object to stdout with the sweep result. */
+    json?: boolean;
+}
+/**
+ * Always-on cheap ingest sweep (agent start + timer). Single-writer lock on local disk.
+ */
+export declare function runMasterIngestSweep(masterPath: string, opts?: IngestSweepOptions): IngestSweepResult;
+/**
+ * v13 completion (5.12.x): sweep, then publish a fresh immutable snapshot
+ * when the sweep changed the DB (or none has ever been published). Clients
+ * read the published snapshot via a verified local copy instead of opening
+ * the live gnosys.db over the network — the hazard the design forbids.
+ *
+ * Kept separate from runMasterIngestSweep: publishMasterSnapshot acquires
+ * the same master-ingest lock, so it must run after the sweep releases it,
+ * and the sweep itself stays synchronous for existing callers.
+ */
+export declare function runMasterIngestSweepAndPublish(masterPath: string, opts?: IngestSweepOptions): Promise<IngestSweepResult>;

package/dist/lib/syncIngest.js

@@ -0,0 +1,175 @@
+/**
+ * v13 master ingest sweep — process staged JSON into gnosys.db.
+ */
+import { existsSync, readdirSync, unlinkSync, writeFileSync, mkdirSync } from "fs";
+import path from "path";
+import { GnosysDB, fnv1a } from "./db.js";
+import { getGnosysHome } from "./paths.js";
+import { ensureMachineConfig } from "./machineConfig.js";
+import { listPendingStagingQueue, observeStagingFile, parseStagedFile, quarantineStagingFile, quarantineStaleTmpFiles, stagingRoot, verifyMemoryExistsInDb, } from "./syncStaging.js";
+import { assertMasterLeaseHeld, readMasterMarker, touchMasterMarkerHeartbeat, validateLeaseEpochBeforeWrite, } from "./masterLease.js";
+import { acquireWriteLockSync, } from "./syncLock.js";
+const INGEST_LOCK_NAME = "master-ingest.lock";
+function payloadToMemory(p, now) {
+    const contentHash = fnv1a(`${p.title}\n${p.content}`);
+    return {
+        id: p.id,
+        title: p.title,
+        category: p.category,
+        content: p.content,
+        summary: null,
+        tags: JSON.stringify(p.tags),
+        relevance: "",
+        author: "user",
+        authority: "user",
+        confidence: 0.8,
+        reinforcement_count: 0,
+        content_hash: contentHash,
+        status: "active",
+        tier: "active",
+        supersedes: null,
+        superseded_by: null,
+        last_reinforced: null,
+        created: p.writtenAt || now,
+        modified: now,
+        source_path: null,
+        project_id: p.project_id,
+        scope: p.scope || "project",
+    };
+}
+function writeIngestReceipt(masterPath, machineId, ulid, outcome) {
+    const dir = path.join(stagingRoot(masterPath), machineId, "receipts");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path.join(dir, `${ulid}.json`), JSON.stringify({ ulid, outcome, at: new Date().toISOString() }, null, 2) + "\n");
+}
+function listMachineIds(masterPath) {
+    const root = stagingRoot(masterPath);
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root).filter((name) => {
+        if (name.startsWith("."))
+            return false;
+        try {
+            return existsSync(path.join(root, name));
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * Always-on cheap ingest sweep (agent start + timer). Single-writer lock on local disk.
+ */
+export function runMasterIngestSweep(masterPath, opts) {
+    const result = { ingested: 0, skipped: 0, quarantined: 0, errors: [] };
+    const { config: mc } = ensureMachineConfig();
+    const lockPath = path.join(getGnosysHome(), INGEST_LOCK_NAME);
+    let release = null;
+    try {
+        release = acquireWriteLockSync(lockPath, "master-ingest");
+        touchMasterMarkerHeartbeat(masterPath);
+        assertMasterLeaseHeld(masterPath, mc.machineId);
+        const marker = readMasterMarker(masterPath);
+        if (!marker) {
+            result.errors.push("master.json missing");
+            return result;
+        }
+        const masterDb = new GnosysDB(masterPath);
+        if (!masterDb.isAvailable()) {
+            result.errors.push("master database unavailable");
+            masterDb.close();
+            return result;
+        }
+        try {
+            for (const machineId of listMachineIds(masterPath)) {
+                quarantineStaleTmpFiles(masterPath, machineId);
+                const queue = listPendingStagingQueue(masterPath, machineId, masterDb);
+                for (const entry of queue) {
+                    observeStagingFile(masterDb, machineId, entry.fileName, entry.memoryUlid);
+                    const parsed = parseStagedFile(entry.filePath);
+                    if (!parsed.ok) {
+                        if (parsed.quarantine) {
+                            quarantineStagingFile(entry.filePath, masterPath, machineId);
+                            result.quarantined++;
+                        }
+                        else {
+                            result.errors.push(parsed.reason);
+                        }
+                        continue;
+                    }
+                    if (masterDb.isUlidProcessed(parsed.payload.id)) {
+                        try {
+                            unlinkSync(entry.filePath);
+                        }
+                        catch {
+                            // ignore
+                        }
+                        writeIngestReceipt(masterPath, machineId, parsed.payload.id, "deduped");
+                        result.skipped++;
+                        continue;
+                    }
+                    try {
+                        validateLeaseEpochBeforeWrite(masterPath, marker.epoch, mc.machineId);
+                        const now = new Date().toISOString();
+                        masterDb.insertMemory(payloadToMemory(parsed.payload, now));
+                        if (!verifyMemoryExistsInDb(masterDb, parsed.payload.id)) {
+                            result.errors.push(`read-back failed for ${parsed.payload.id}`);
+                            continue;
+                        }
+                        masterDb.markUlidProcessed(parsed.payload.id, marker.epoch);
+                        masterDb.recordStagingLedgerEntry({
+                            stagingKey: `${machineId}/${entry.fileName}`,
+                            machineId,
+                            memoryUlid: parsed.payload.id,
+                            firstSeenAt: masterDb.getStagingLedgerFirstSeenAt(`${machineId}/${entry.fileName}`) ?? now,
+                            ingestEpoch: marker.epoch,
+                            status: "ingested",
+                        });
+                        unlinkSync(entry.filePath);
+                        writeIngestReceipt(masterPath, machineId, parsed.payload.id, "ingested");
+                        result.ingested++;
+                    }
+                    catch (err) {
+                        result.errors.push(err instanceof Error ? err.message : String(err));
+                    }
+                }
+            }
+        }
+        finally {
+            masterDb.close();
+        }
+    }
+    catch (err) {
+        result.errors.push(err instanceof Error ? err.message : String(err));
+    }
+    finally {
+        release?.();
+    }
+    if (opts?.json) {
+        console.log(JSON.stringify(result));
+    }
+    return result;
+}
+/**
+ * v13 completion (5.12.x): sweep, then publish a fresh immutable snapshot
+ * when the sweep changed the DB (or none has ever been published). Clients
+ * read the published snapshot via a verified local copy instead of opening
+ * the live gnosys.db over the network — the hazard the design forbids.
+ *
+ * Kept separate from runMasterIngestSweep: publishMasterSnapshot acquires
+ * the same master-ingest lock, so it must run after the sweep releases it,
+ * and the sweep itself stays synchronous for existing callers.
+ */
+export async function runMasterIngestSweepAndPublish(masterPath, opts) {
+    const result = runMasterIngestSweep(masterPath, opts);
+    try {
+        const { getMasterManifest, publishMasterSnapshot } = await import("./syncSnapshot.js");
+        if (result.ingested > 0 || !getMasterManifest(masterPath)) {
+            await publishMasterSnapshot(masterPath);
+        }
+    }
+    catch (err) {
+        result.errors.push(`snapshot publish: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return result;
+}

package/dist/lib/syncIngestLaunchd.d.ts

@@ -0,0 +1,8 @@
+/** Build launchd plist XML (testable without writing to disk). */
+export declare function buildSyncIngestLaunchAgentPlist(intervalMinutes: number): string;
+export declare function installSyncIngestLaunchAgent(intervalMinutes?: number): string | null;
+export declare function uninstallSyncIngestLaunchAgent(): string | null;
+export declare function getSyncIngestLaunchAgentStatus(): {
+    installed: boolean;
+    path: string;
+};