harnery 0.38.0 → 0.40.0

package/dist/commands/backup.js

@@ -19,9 +19,36 @@
  */
 import { spawnSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { hostname } from "node:os";
 import path from "node:path";
+import { newestSnapshotTime, parseBackupDuration, recordHostSnapshot, } from "../core/backup/host-snapshot.js";
 import { backupConfig } from "../core/config.js";
+import { createStorageCatalog } from "../core/storage/catalog.js";
+export { hostSnapshotCachePath, newestSnapshotTime, parseBackupDuration, readHostSnapshotCache, } from "../core/backup/host-snapshot.js";
+export const DEFAULT_BACKUP_MAX_BYTES = 50 * 1_024 * 1_024;
+export const DEFAULT_BACKUP_CLASSES = new Set([
+    "canonical-authority",
+    "durable-object-history",
+    "recovery-state",
+]);
+export const DEFAULT_BACKUP_EXCLUDED_CLASSES = new Set([
+    "debug-log",
+    "managed-artifact",
+    "operational-log",
+    "repairable-cache",
+]);
+export const DEFAULT_BACKUP_EXCLUDED_FAMILY_IDS = new Set([
+    "event-v3-canonical-active",
+    "event-v3-canonical-archives",
+    "event-v3-support-active",
+    "event-v3-support-archives",
+    "event-v3-recovery-records",
+    "legacy-canonical-ledgers",
+    "managed-artifacts",
+    "captured-images",
+    "storage-exports",
+]);
 function defaultRepo() {
     return backupConfig().repo;
 }
@@ -48,6 +75,145 @@ function ensurePasswordFile(file) {
     const pw = randomBytes(24).toString("base64");
     writeFileSync(file, `${pw}\n`, { encoding: "utf-8", mode: 0o600 });
 }
+function isFilesystemRepository(repo) {
+    if (/^[a-zA-Z]:[\\/]/.test(repo))
+        return true;
+    return !/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(repo);
+}
+function inside(base, candidate) {
+    const relative = path.relative(base, candidate);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function configPath(harneryDir, value) {
+    if (path.isAbsolute(value))
+        return null;
+    const normalized = value.replaceAll("\\", "/").replace(/^\.harnery\//, "");
+    if (!normalized || normalized.split("/").some((part) => part === ".." || part === "")) {
+        return null;
+    }
+    const resolved = path.resolve(harneryDir, normalized);
+    return inside(harneryDir, resolved) ? resolved : null;
+}
+export function resolveBackupSelection(projectRoot, config = backupConfig(projectRoot), includeArtifacts = false) {
+    const root = path.resolve(projectRoot);
+    const harneryDir = path.join(root, ".harnery");
+    const catalog = createStorageCatalog({ coord_root: root, project_root: root });
+    const knownFamilyIds = new Set(catalog.families.map((family) => family.id));
+    const configuredFamilyExclusions = new Set(config.exclude.filter((entry) => knownFamilyIds.has(entry)));
+    const configuredPathExclusions = config.exclude
+        .filter((entry) => !knownFamilyIds.has(entry))
+        .map((entry) => configPath(harneryDir, entry))
+        .filter((entry) => entry !== null);
+    const selectedFamilies = catalog.families.filter((family) => DEFAULT_BACKUP_CLASSES.has(family.storage_class) &&
+        !DEFAULT_BACKUP_EXCLUDED_FAMILY_IDS.has(family.id) &&
+        !configuredFamilyExclusions.has(family.id));
+    const excludedByPath = (candidate) => configuredPathExclusions.some((excluded) => candidate === excluded || inside(excluded, candidate));
+    const targets = selectedFamilies
+        .flatMap((family) => family.resolved_roots.map((storageRoot) => storageRoot.path))
+        .filter((candidate) => inside(harneryDir, candidate))
+        .filter((candidate) => !excludedByPath(candidate));
+    for (const entry of config.include) {
+        const candidate = configPath(harneryDir, entry);
+        if (candidate && !excludedByPath(candidate))
+            targets.push(candidate);
+    }
+    if (includeArtifacts)
+        targets.push(path.join(harneryDir, "artifacts"));
+    return {
+        targets: [...new Set(targets)].filter(existsSync).sort(),
+        familyIds: selectedFamilies.map((family) => family.id).sort(),
+    };
+}
+export function backupCatalogCoverage(projectRoot) {
+    const root = path.resolve(projectRoot);
+    const harneryDir = path.join(root, ".harnery");
+    const catalog = createStorageCatalog({ coord_root: root, project_root: root });
+    const uncovered = catalog.families
+        .filter((family) => {
+        const selected = DEFAULT_BACKUP_CLASSES.has(family.storage_class) &&
+            !DEFAULT_BACKUP_EXCLUDED_FAMILY_IDS.has(family.id);
+        const excluded = DEFAULT_BACKUP_EXCLUDED_CLASSES.has(family.storage_class) ||
+            DEFAULT_BACKUP_EXCLUDED_FAMILY_IDS.has(family.id);
+        const externalOnly = family.resolved_roots.length === 0 ||
+            family.resolved_roots.every((storageRoot) => !inside(harneryDir, storageRoot.path));
+        return !selected && !excluded && !externalOnly;
+    })
+        .map((family) => family.id);
+    return { uncovered };
+}
+export function selectedLogicalBytes(targets) {
+    const visited = new Set();
+    const measure = (candidate) => {
+        let stat;
+        try {
+            stat = lstatSync(candidate);
+        }
+        catch {
+            return 0;
+        }
+        const identity = `${stat.dev}:${stat.ino}`;
+        if (visited.has(identity))
+            return 0;
+        visited.add(identity);
+        if (stat.isSymbolicLink())
+            return 0;
+        if (stat.isFile())
+            return stat.size;
+        if (!stat.isDirectory())
+            return 0;
+        return readdirSync(candidate).reduce((total, entry) => total + measure(path.join(candidate, entry)), 0);
+    };
+    return targets.reduce((total, target) => total + measure(target), 0);
+}
+function lockOwnerIsAlive(lockDir) {
+    try {
+        const owner = JSON.parse(readFileSync(path.join(lockDir, "owner.json"), "utf8"));
+        if (typeof owner.pid === "number" && owner.pid > 0) {
+            try {
+                process.kill(owner.pid, 0);
+                return true;
+            }
+            catch {
+                // The owner is gone; the directory is reclaimable.
+            }
+        }
+        const createdAt = typeof owner.created_at === "string" ? Date.parse(owner.created_at) : 0;
+        return Number.isFinite(createdAt) && Date.now() - createdAt < 60 * 60 * 1_000;
+    }
+    catch {
+        return false;
+    }
+}
+function acquireSnapshotLock(harneryDir) {
+    const locksDir = path.join(harneryDir, "locks");
+    const lockDir = path.join(locksDir, "backup-snapshot.lock");
+    mkdirSync(locksDir, { recursive: true });
+    const create = () => {
+        try {
+            mkdirSync(lockDir);
+            writeFileSync(path.join(lockDir, "owner.json"), `${JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() })}\n`, "utf8");
+            return true;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            return false;
+        }
+    };
+    if (!create()) {
+        if (lockOwnerIsAlive(lockDir))
+            return { acquired: false, release() { } };
+        rmSync(lockDir, { recursive: true, force: true });
+        if (!create())
+            return { acquired: false, release() { } };
+    }
+    return {
+        acquired: true,
+        release() {
+            rmSync(lockDir, { recursive: true, force: true });
+        },
+    };
+}
 function runRestic(args, opts = {}) {
     const repo = opts.repo ?? defaultRepo();
     const pwFile = opts.passwordFile ?? defaultPasswordFile();
@@ -96,7 +262,8 @@ export function registerBackupCommand(program, emit) {
         const repo = opts.repo ?? defaultRepo();
         const pwFile = opts.passwordFile ?? defaultPasswordFile();
         ensurePasswordFile(pwFile);
-        mkdirSync(path.dirname(repo), { recursive: true });
+        if (isFilesystemRepository(repo))
+            mkdirSync(path.dirname(repo), { recursive: true });
         const r = runRestic(["init"], { repo, passwordFile: pwFile, stdio: "inherit" });
         if (r.exitCode === 0) {
             emit.text(`restic repo initialized at ${repo}\npassword file: ${pwFile}`);
@@ -113,13 +280,15 @@ export function registerBackupCommand(program, emit) {
         .option("--repo <path>", "Repository path")
         .option("--password-file <path>", "Password file")
         .option("--include-artifacts", "Include managed working artifacts (default: excluded; potentially large + ephemeral)")
+        .option("--allow-large", "Permit a selected set larger than backup.max_bytes")
+        .option("--if-stale <duration>", "Skip when this host has a newer snapshot (for example 24h)")
         .action((opts) => {
         if (!checkRestic(emit)) {
             emit.setExitCode(1);
             return;
         }
-        const harnery = findHarneryDir();
-        if (!harnery) {
+        const harneryDir = findHarneryDir();
+        if (!harneryDir) {
             emit.error({
                 code: "target_missing",
                 message: "No .harnery/ found above cwd; run from an initialized project",
@@ -127,40 +296,77 @@ export function registerBackupCommand(program, emit) {
             emit.setExitCode(1);
             return;
         }
-        const passThrough = [];
-        for (const t of opts.tag) {
-            passThrough.push("--tag", t);
-        }
-        const safeTargets = [
-            "ledgers",
-            "councils",
-            "journal",
-            "work",
-            "workflows",
-            "decisions",
-            "config.jsonc",
-            ".name-history",
-        ]
-            .map((entry) => path.join(harnery, entry))
-            .filter(existsSync);
-        if (opts.includeArtifacts && existsSync(path.join(harnery, "artifacts"))) {
-            safeTargets.push(path.join(harnery, "artifacts"));
-        }
-        if (safeTargets.length === 0) {
+        const staleMs = opts.ifStale ? parseBackupDuration(opts.ifStale) : null;
+        if (opts.ifStale && staleMs === null) {
             emit.error({
-                code: "backup_empty",
-                message: "No durable V3 state is available to back up",
+                code: "backup_invalid_duration",
+                message: `Invalid --if-stale duration: ${opts.ifStale}`,
+                hint: "Use an integer duration such as 30m, 24h, or 7d",
             });
             emit.setExitCode(1);
             return;
         }
-        const r = runRestic(["backup", ...safeTargets], {
-            repo: opts.repo,
-            passwordFile: opts.passwordFile,
-            stdio: "inherit",
-            passThrough,
-        });
-        emit.setExitCode(r.exitCode);
+        const lock = acquireSnapshotLock(harneryDir);
+        if (!lock.acquired) {
+            emit.text("backup snapshot already running; skipped");
+            return;
+        }
+        try {
+            if (staleMs !== null) {
+                const latest = runRestic(["snapshots", "--json", "--host", hostname()], {
+                    repo: opts.repo,
+                    passwordFile: opts.passwordFile,
+                    stdio: "pipe",
+                });
+                if (latest.exitCode !== 0) {
+                    emit.error({ code: "backup_snapshot_list_failed", message: latest.stdout.trim() });
+                    emit.setExitCode(latest.exitCode);
+                    return;
+                }
+                const newest = newestSnapshotTime(latest.stdout);
+                if (newest !== null && Date.now() - newest < staleMs) {
+                    recordHostSnapshot(harneryDir, newest);
+                    emit.text(`latest snapshot for ${hostname()} is newer than ${opts.ifStale}; skipped`);
+                    return;
+                }
+            }
+            const config = backupConfig(path.dirname(harneryDir));
+            const selection = resolveBackupSelection(path.dirname(harneryDir), config, opts.includeArtifacts);
+            if (selection.targets.length === 0) {
+                emit.error({
+                    code: "backup_empty",
+                    message: "No durable Harnery state is available to back up",
+                });
+                emit.setExitCode(1);
+                return;
+            }
+            const logicalBytes = selectedLogicalBytes(selection.targets);
+            if (!opts.allowLarge && logicalBytes > config.maxBytes) {
+                emit.error({
+                    code: "backup_too_large",
+                    message: `Selected backup is ${logicalBytes} bytes; limit is ${config.maxBytes} bytes`,
+                    hint: "Review backup.include/exclude or pass --allow-large for this snapshot",
+                });
+                emit.setExitCode(1);
+                return;
+            }
+            const passThrough = [];
+            for (const tag of opts.tag)
+                passThrough.push("--tag", tag);
+            const startedAt = Date.now();
+            const result = runRestic(["backup", ...selection.targets], {
+                repo: opts.repo,
+                passwordFile: opts.passwordFile,
+                stdio: "inherit",
+                passThrough,
+            });
+            if (result.exitCode === 0)
+                recordHostSnapshot(harneryDir, startedAt);
+            emit.setExitCode(result.exitCode);
+        }
+        finally {
+            lock.release();
+        }
     });
     // -- list --
     backup

package/dist/commands/browse.d.ts

@@ -1,4 +1,12 @@
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.js";
 export declare function registerBrowseCommand(program: Command, emitParam: EmitContext, context?: HarneryProgramContext, binName?: string): void;
+/**
+ * Capture this render into a page review pack: one full-page screenshot,
+ * budgeted native tiles, one candidate set per
+ * --review-pack-scope selector, the serialized DOM, and the QA signature —
+ * all written to disk, with no vision call. The judge stage reads them back
+ * once the browser is gone.
+ */
+export declare const REVIEW_CAPTURE_RECIPE = "native-full-page-scroll-probe/v2";
 //# sourceMappingURL=browse.d.ts.map

package/dist/commands/browse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browse.d.ts","sourceRoot":"","sources":["../../src/commands/browse.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AA8P1E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,EAC/B,OAAO,SAAmB,GACzB,IAAI,CA+fN"}
+{"version":3,"file":"browse.d.ts","sourceRoot":"","sources":["../../src/commands/browse.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAkS1E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,EAC/B,OAAO,SAAmB,GACzB,IAAI,CAugBN;AAuzDD;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,qCAAqC,CAAC"}