backdot 1.8.3 → 1.8.5

package/README.md

@@ -0,0 +1,90 @@
+<p align="center">
+  <img src="logo-small.png" alt="backdot" width="400" />
+</p>
+
+<h1 align="center">backdot</h1>
+
+<p align="center">Automated backup of important files (configs, dotfiles) to your own private Git repo.</p>
+
+## Getting started
+
+```bash
+npm install -g backdot
+backdot init
+```
+
+This creates `~/.backdot/config.json` with sensible defaults and walks you through setup. Open the config file and set your repository URL and the files you want backed up:
+
+```json
+{
+  "repository": "git@github.com:USERNAME/backdot-backup.git",
+  "machine": "my-work-laptop",
+  "paths": ["~/.zshrc", "~/.oh-my-zsh/custom/*.zsh", "~/.ssh/config", "~/.npmrc"]
+}
+```
+
+Run your first backup:
+
+```bash
+backdot backup
+```
+
+or configure the backport process to run automatically (daily at 2am)
+
+```bash
+backdot schedule
+```
+
+## Configuration
+
+| Key     | Description                                                                                      |
+| ------- | ----------------------------------------------------------------------------------------------- |
+| `paths` | Glob patterns matching files. To back up a whole directory, use a trailing `/**` (e.g. `~/.config/nvim/**`) — a bare directory path matches nothing. |
+
+Prefix a pattern with `!` to exclude matching files:
+
+```json
+{
+  "paths": ["~/.config/ghostty/**", "!~/.config/ghostty/crash-reports/**"]
+}
+```
+
+## Encryption
+
+To encrypt files before they are pushed to the remote repo, add `"encrypt": true` to your config.
+
+On first backup you'll be prompted for a password and offered to save it to `~/.backdot/encryption.key` so that future backups do not prompt for a password.
+
+For non-interactive backups (the scheduled job, CI, etc.) you can supply the password via the `BACKDOT_PASSWORD` environment variable instead of the key file.
+
+## Post-restore hook
+
+Add a `~/.backdot/post-restore` shell script which will be executed after `backdot restore`to install packages, clone repos, etc. It's backed up automatically.
+
+## Commands
+
+| Command                        | Description                                    |
+| ------------------------------ | ---------------------------------------------- |
+| `init`                         | Set up backdot for the first time              |
+| `backup`                       | Run a backup now                               |
+| `restore`                      | Restore latest backup from the configured repo |
+| `restore <url>`                | Restore from a specific repo URL               |
+| `restore [url] --commit <sha>` | Restore from a specific backup commit          |
+| `restore [url] --machine <name>` | Restore a specific machine non-interactively |
+| `restore [url] --yes` (`-y`)   | Restore new files non-interactively (skips existing files) |
+| `history [url]`                | Browse and restore a previous backup           |
+| `schedule`                     | Schedule automatic daily backup (Mac-only)     |
+| `unschedule`                   | Unschedule the daily backup                    |
+| `status`                       | Show schedule and resolved file list           |
+
+## Development
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+## License
+
+MIT

package/dist/commands/backup.js

@@ -54,6 +54,14 @@ export async function backup() {
                 "Backing up to a public repo would expose sensitive files.\n" +
                 "Make the repository private, then try again.");
         }
+        if (visibility === "unverifiable" && !process.env.BACKDOT_ALLOW_UNVERIFIED_VISIBILITY) {
+            spinner.fail("Backup refused — could not verify repository visibility");
+            throw new Error(`Could not verify whether "${config.repository}" is private — the anonymous ` +
+                "visibility check failed (network error, timeout, or blocked HTTPS access).\n" +
+                "Backup is refused so files are never pushed to a repository that might be public.\n" +
+                "Confirm the repository is private and retry. If HTTPS is blocked in your " +
+                "environment, set BACKDOT_ALLOW_UNVERIFIED_VISIBILITY=1 to override.");
+        }
         spinner.text = "Resolving files";
         const userFiles = resolveFiles(config);
         logger.info(`Resolved ${pluralize(userFiles.length, "file")}`);

package/dist/commands/history.js

@@ -22,6 +22,10 @@ export async function history(repoUrl) {
         console.log("\n  No backup history found.\n");
         return;
     }
+    if (!process.stdin.isTTY) {
+        throw new Error("Browsing history is interactive.\n" +
+            "  Use `restore --commit <sha>` to restore a specific backup non-interactively.");
+    }
     const selectedCommitHash = await select({
         message: "Select a backup to restore from:",
         loop: false,

package/dist/commands/restore.js

@@ -132,6 +132,11 @@ export async function restore({ repoUrl, commit, skipExisting, machine: machineO
         }
     }
     else {
+        if (!process.stdin.isTTY) {
+            throw new Error("Selecting files to restore is interactive.\n" +
+                "  Re-run with --yes to restore new files non-interactively (existing files are skipped),\n" +
+                "  or run in a terminal to choose which files to restore.");
+        }
         const choices = [];
         if (newFiles.length > 0) {
             choices.push(new Separator(`── New files (${newFiles.length}) ──`));

package/dist/commands/status.js

@@ -6,7 +6,7 @@ import { loadConfig, CONFIG_PATH } from "../config.js";
 import { resolveFiles } from "../resolveFiles.js";
 import { compareFiles } from "../staging.js";
 import { isScheduled } from "../launchd.js";
-import { pluralize } from "../utils.js";
+import { pluralize, errorMessage } from "../utils.js";
 import { checkRepoVisibility } from "../repoVisibility.js";
 import { deriveKey } from "../crypto/encryption.js";
 import { resolvePassword } from "../crypto/password.js";
@@ -20,6 +20,8 @@ function formatVisibility(visibility) {
             return chalk.red.bold("public (backup disabled)");
         case "private":
             return chalk.green("private");
+        case "unverifiable":
+            return chalk.yellow("could not verify (network error)");
         case "unknown":
             return chalk.yellow("unknown (could not verify)");
     }
@@ -66,17 +68,23 @@ export async function status() {
         }
         const files = [...userFiles, CONFIG_PATH];
         spinner.text = "Comparing with remote backup";
-        const { backedUp, modified, notBackedUp, remoteIsEmpty, error } = await compareFiles({
-            files,
-            machine: config.machine,
-            repository: config.repository,
-            resolveKey,
-        });
-        spinner.stop();
-        if (error) {
-            console.log(chalk.yellow(`  Could not fetch status: ${error}`));
+        let comparison;
+        try {
+            comparison = await compareFiles({
+                files,
+                machine: config.machine,
+                repository: config.repository,
+                resolveKey,
+            });
+        }
+        catch (err) {
+            spinner.stop();
+            console.log(chalk.yellow(`  Could not fetch status: ${errorMessage(err)}`));
+            console.log();
             return;
         }
+        spinner.stop();
+        const { backedUp, modified, notBackedUp, remoteIsEmpty } = comparison;
         if (remoteIsEmpty) {
             console.log(`  No backup yet — showing what ${chalk.bold("backdot backup")} would back up.`);
             console.log();

package/dist/repoVisibility.d.ts

@@ -1,4 +1,4 @@
-export type RepoVisibility = "public" | "private" | "unknown";
+export type RepoVisibility = "public" | "private" | "unknown" | "unverifiable";
 /**
  * Converts an SSH or HTTPS repo URL to a credential-free HTTPS URL
  * for known hosts. Returns `null` for unrecognized hosts.
@@ -9,7 +9,21 @@ export type RepoVisibility = "public" | "private" | "unknown";
  */
 export declare function toHttpsUrl(repository: string): string | null;
 /**
- * Checks whether `repository` is publicly readable by attempting an
- * anonymous `git ls-remote` over HTTPS with all credential helpers disabled.
+ * Determines whether `repository` is publicly readable by sending an anonymous
+ * (no-credentials) request to git's smart-HTTP advertised-refs endpoint and
+ * classifying the HTTP status code — a documented, stable signal:
+ *
+ *   - 200          → refs are served anonymously                    → "public"
+ *   - 401/403/404  → host refuses anonymous reads (private, or
+ *                    hidden-as-missing)                              → "private"
+ *   - anything else (3xx, 5xx, …) or no response at all (DNS error,
+ *                    timeout, TLS/proxy failure)                     → "unverifiable"
+ *
+ * Verified 2026-06: github.com & gitlab.com public → 200, private → 401;
+ * bitbucket.org returns 401 even for public repos, so a public Bitbucket repo
+ * reads as private here — it is not anonymously readable over git either way.
+ * The status code does not depend on the request's User-Agent.
+ *
+ * Unknown hosts have no HTTPS form to probe and return "unknown".
  */
 export declare function checkRepoVisibility(repository: string): Promise<RepoVisibility>;

package/dist/repoVisibility.js

@@ -1,4 +1,4 @@
-import { execFile } from "node:child_process";
+import https from "node:https";
 import { extractRepoPath } from "./utils.js";
 /**
  * Converts an SSH or HTTPS repo URL to a credential-free HTTPS URL
@@ -15,42 +15,58 @@ export function toHttpsUrl(repository) {
     }
     return `https://${parsed.host}/${parsed.repoPath}.git`;
 }
+const PROBE_TIMEOUT_MS = 10_000;
 /**
- * Checks whether `repository` is publicly readable by attempting an
- * anonymous `git ls-remote` over HTTPS with all credential helpers disabled.
+ * Determines whether `repository` is publicly readable by sending an anonymous
+ * (no-credentials) request to git's smart-HTTP advertised-refs endpoint and
+ * classifying the HTTP status code — a documented, stable signal:
+ *
+ *   - 200          → refs are served anonymously                    → "public"
+ *   - 401/403/404  → host refuses anonymous reads (private, or
+ *                    hidden-as-missing)                              → "private"
+ *   - anything else (3xx, 5xx, …) or no response at all (DNS error,
+ *                    timeout, TLS/proxy failure)                     → "unverifiable"
+ *
+ * Verified 2026-06: github.com & gitlab.com public → 200, private → 401;
+ * bitbucket.org returns 401 even for public repos, so a public Bitbucket repo
+ * reads as private here — it is not anonymously readable over git either way.
+ * The status code does not depend on the request's User-Agent.
+ *
+ * Unknown hosts have no HTTPS form to probe and return "unknown".
  */
 export async function checkRepoVisibility(repository) {
     const httpsUrl = toHttpsUrl(repository);
     if (!httpsUrl) {
         return "unknown";
     }
+    let status;
     try {
-        await execGitLsRemote(httpsUrl);
-        return "public";
+        status = await probeAnonymousRefsStatus(`${httpsUrl}/info/refs?service=git-upload-pack`);
     }
     catch {
+        // No usable response (DNS failure, timeout, TLS/proxy error): visibility is
+        // undetermined — never assume private.
+        return "unverifiable";
+    }
+    if (status === 200) {
+        return "public";
+    }
+    if (status === 401 || status === 403 || status === 404) {
         return "private";
     }
+    return "unverifiable";
 }
-function execGitLsRemote(url) {
+/**
+ * Issues an anonymous GET to a smart-HTTP refs URL and resolves with the HTTP
+ * status code. Sends no credentials; rejects on connection failure or timeout.
+ */
+function probeAnonymousRefsStatus(refsUrl) {
     return new Promise((resolve, reject) => {
-        const child = execFile("git", ["-c", "credential.helper=", "ls-remote", "--quiet", url], {
-            timeout: 10_000,
-            env: {
-                ...process.env,
-                GIT_TERMINAL_PROMPT: "0",
-                GIT_ASKPASS: undefined,
-                SSH_ASKPASS: undefined,
-            },
-        }, (error) => {
-            if (error) {
-                reject(error);
-            }
-            else {
-                resolve();
-            }
+        const request = https.get(refsUrl, { headers: { "User-Agent": "backdot" }, timeout: PROBE_TIMEOUT_MS }, (response) => {
+            response.resume(); // drain the body so the socket is released
+            resolve(response.statusCode ?? 0);
         });
-        // Don't let stdin keep the process alive
-        child.stdin?.end();
+        request.on("timeout", () => request.destroy(new Error("Visibility probe timed out")));
+        request.on("error", reject);
     });
 }

package/dist/staging.d.ts

@@ -22,7 +22,6 @@ export interface ComparisonResult {
     modified: string[];
     notBackedUp: string[];
     remoteIsEmpty?: boolean;
-    error?: string;
 }
 export declare function compareFiles(opts: {
     files: string[];

package/dist/staging.js

@@ -4,7 +4,7 @@ import os from "node:os";
 import { execFileSync } from "node:child_process";
 import { simpleGit } from "simple-git";
 import { logger } from "./log.js";
-import { errorMessage, pluralize } from "./utils.js";
+import { pluralize } from "./utils.js";
 import { ensureRemoteUrl, getCurrentBranch, gitError } from "./git.js";
 import { STAGING_DIR, STAGING_GIT_DIR, machineDir } from "./paths.js";
 import { encrypt, decrypt } from "./crypto/encryption.js";
@@ -27,12 +27,19 @@ export function getStagedPath(filePath, machine) {
         : path.join(HOME_NAMESPACE, path.relative(HOME, filePath));
     return path.join(machineDir(machine), pathWithinMachineDir);
 }
+/**
+ * git stores and reports repo paths with forward slashes on every platform, so
+ * normalize OS-native separators before comparing against `git ls-tree` output.
+ */
+function toRepoRelativePath(stagedPath) {
+    return path.relative(STAGING_DIR, stagedPath).split(path.sep).join("/");
+}
 /**
  * Inverse of getStagedPath: maps a path relative to the machine dir
  * (e.g. "home/.zshrc" or "root/etc/hosts") back to its restore destination.
  */
 export function getRestoreTarget(machineRelativePath) {
-    const [namespace, ...rest] = machineRelativePath.split(path.sep);
+    const [namespace, ...rest] = machineRelativePath.split(/[/\\]/);
     const subPath = rest.join(path.sep);
     if (namespace === ROOT_NAMESPACE) {
         const destination = path.join("/", subPath);
@@ -75,9 +82,6 @@ export function copyToStaging(files, machine, derivedKey) {
     }
     logger.info(`Copied ${pluralize(copiedCount, "file")} to staging`);
 }
-function failedComparisonResult(err) {
-    return { backedUp: [], modified: [], notBackedUp: [], error: errorMessage(err) };
-}
 // This machine has no snapshot in the remote yet, so every file counts as "not
 // backed up". Lets `status` preview what a first backup would push instead of erroring.
 function emptyRemoteResult(files) {
@@ -97,30 +101,18 @@ export async function compareFiles(opts) {
         await git.fetch("origin");
     }
     catch (err) {
-        return failedComparisonResult(gitError(err, repository));
-    }
-    let branch;
-    try {
-        branch = await getCurrentBranch(git);
-    }
-    catch (err) {
-        return failedComparisonResult(err);
-    }
-    let remoteBlobHashes;
-    try {
-        const treeOutput = execFileSync("git", ["ls-tree", "-r", `origin/${branch}`, `${machine}/`], {
-            encoding: "utf-8",
-            cwd: STAGING_DIR,
-        });
-        remoteBlobHashes = new Map(treeOutput
-            .split("\n")
-            .map((line) => line.match(/^\d+ blob ([0-9a-f]+)\t(.+)$/))
-            .filter((match) => match !== null)
-            .map((match) => [match[2], match[1]]));
-    }
-    catch (err) {
-        return failedComparisonResult(err);
+        throw gitError(err, repository);
     }
+    const branch = await getCurrentBranch(git);
+    const treeOutput = execFileSync("git", ["ls-tree", "-r", `origin/${branch}`, `${machine}/`], {
+        encoding: "utf-8",
+        cwd: STAGING_DIR,
+    });
+    const remoteBlobHashes = new Map(treeOutput
+        .split("\n")
+        .map((line) => line.match(/^\d+ blob ([0-9a-f]+)\t(.+)$/))
+        .filter((match) => match !== null)
+        .map((match) => [match[2], match[1]]));
     // Repo reachable but this machine has nothing backed up yet (empty repo, or it
     // only holds other machines). Treat as a pre-backup preview.
     if (remoteBlobHashes.size === 0) {
@@ -143,17 +135,11 @@ export async function compareFiles(opts) {
             }
         });
     }
-    let localFileHashes;
-    try {
-        const hashOutput = execFileSync("git", ["hash-object", "--stdin-paths"], {
-            encoding: "utf-8",
-            input: files.join("\n") + "\n",
-        });
-        localFileHashes = hashOutput.trim().split("\n");
-    }
-    catch (err) {
-        return failedComparisonResult(err);
-    }
+    const hashOutput = execFileSync("git", ["hash-object", "--stdin-paths"], {
+        encoding: "utf-8",
+        input: files.join("\n") + "\n",
+    });
+    const localFileHashes = hashOutput.trim().split("\n");
     const localHashByFile = new Map(files.map((file, i) => [file, localFileHashes[i]]));
     return compareFilesToRemote(files, machine, remoteBlobHashes, "", (file, remoteBlobHash) => {
         return remoteBlobHash === localHashByFile.get(file);
@@ -162,7 +148,7 @@ export async function compareFiles(opts) {
 function compareFilesToRemote(files, machine, remoteBlobHashes, pathSuffix, matchesRemote) {
     const result = { backedUp: [], modified: [], notBackedUp: [] };
     for (const file of files) {
-        const repoRelativePath = path.relative(STAGING_DIR, getStagedPath(file, machine)) + pathSuffix;
+        const repoRelativePath = toRepoRelativePath(getStagedPath(file, machine)) + pathSuffix;
         const remoteBlobHash = remoteBlobHashes.get(repoRelativePath);
         if (!remoteBlobHash) {
             result.notBackedUp.push(file);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backdot",
-  "version": "1.8.3",
+  "version": "1.8.5",
   "description": "Lightweight CLI to backup dotfiles and gitignored files to a Git repo on a daily schedule",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "fmt:check": "prettier --check src/",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
-    "prepare": "cd .. && husky",
+    "prepare": "husky",
     "start": "node dist/cli.js",
     "test": "vitest run --exclude src/e2e.test.ts --exclude src/git.integration.test.ts",
     "test:all": "npm run build && vitest run",