backdot 1.5.0 → 1.6.0

package/README.md

@@ -51,14 +51,17 @@ Prefix a pattern with `!` to exclude matching files:
 
 ## Commands
 
-| Command        | Description                                            |
-| -------------- | ------------------------------------------------------ |
-| `--init`       | Set up backdot for the first time                      |
-| `--backup`     | Run a backup now                                       |
-| `--restore`    | Restore files to their original locations              |
-| `--schedule`   | Schedule automatic daily backup via launchd (Mac-only) |
-| `--unschedule` | Remove the daily schedule                              |
-| `--status`     | Show schedule and resolved file list                   |
+| 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          |
+| `--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
 

package/dist/cli.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 import fs from "node:fs";
 import path from "node:path";
+import { parseArgs } from "node:util";
 import chalk from "chalk";
 import { CONFIG_PATH } from "./config.js";
 import { backup } from "./commands/backup.js";
 import { status } from "./commands/status.js";
 import { schedule, unschedule } from "./commands/schedule.js";
 import { restore } from "./commands/restore.js";
+import { history } from "./commands/history.js";
 import { init } from "./commands/init.js";
 import { logger } from "./log.js";
 import { sendNotification } from "./notify.js";
@@ -20,55 +22,83 @@ function getVersion() {
         return "unknown";
     }
 }
+function printHelp() {
+    console.log();
+    console.log("  Usage: backdot <command>");
+    console.log();
+    console.log("  Commands:");
+    console.log();
+    console.log("    --init                       Set up backdot for the first time");
+    console.log("    --backup                     Run a backup now");
+    console.log("    --restore [url]              Restore files from the backup repo");
+    console.log("    --restore [url] --commit <sha>  Restore from a specific backup commit");
+    console.log("    --restore [url] --yes (-y)      Accept defaults without prompting");
+    console.log("    --history [url]              Browse and restore a previous backup");
+    console.log("    --schedule                   Install daily backup schedule (macOS launchd)");
+    console.log("    --unschedule                 Remove the daily backup schedule");
+    console.log("    --status                     Show schedule and resolved files");
+    console.log("    --version                    Show version");
+    console.log();
+}
 async function main() {
-    const args = process.argv.slice(2);
-    const command = args[0];
+    let values;
+    let positionals;
+    try {
+        ({ values, positionals } = parseArgs({
+            args: process.argv.slice(2),
+            options: {
+                init: { type: "boolean" },
+                backup: { type: "boolean" },
+                restore: { type: "boolean" },
+                history: { type: "boolean" },
+                schedule: { type: "boolean" },
+                unschedule: { type: "boolean" },
+                status: { type: "boolean" },
+                version: { type: "boolean" },
+                help: { type: "boolean" },
+                commit: { type: "string" },
+                yes: { type: "boolean", short: "y" },
+            },
+            allowPositionals: true,
+            strict: true,
+        }));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`\n  Error: ${msg}\n`);
+        printHelp();
+        process.exit(1);
+    }
     try {
-        if (command === "--init") {
+        if (values.init) {
             init();
         }
-        else if (command === "--backup") {
+        else if (values.backup) {
             await backup();
         }
-        else if (command === "--schedule") {
+        else if (values.schedule) {
             schedule();
         }
-        else if (command === "--unschedule") {
+        else if (values.unschedule) {
             unschedule();
         }
-        else if (command === "--status") {
+        else if (values.status) {
             await status();
         }
-        else if (command === "--restore") {
-            const url = args[1];
-            if (url?.startsWith("--")) {
-                throw new Error(`Invalid repository URL: "${url}". Did you mean to pass a Git URL?`);
-            }
-            await restore(url);
+        else if (values.restore) {
+            await restore(positionals[0], values.commit, {
+                yes: !!values.yes,
+            });
         }
-        else if (command === "--version") {
+        else if (values.history) {
+            await history(positionals[0]);
+        }
+        else if (values.version) {
             console.log(getVersion());
         }
         else {
-            console.log();
-            console.log("  Usage: backdot <command>");
-            console.log();
-            console.log("  Commands:");
-            console.log();
-            console.log("    --init         Set up backdot for the first time");
-            console.log("    --backup       Run a backup now");
-            console.log("    --restore [url] Restore files from the backup repo");
-            console.log("    --schedule     Install daily backup schedule (macOS launchd)");
-            console.log("    --unschedule   Remove the daily backup schedule");
-            console.log("    --status       Show schedule and resolved files");
-            console.log("    --version      Show version");
-            console.log();
-            if (command && command !== "--help") {
-                console.error(`  Unknown command: ${command}`);
-                console.log();
-                process.exit(1);
-            }
-            else if (!fs.existsSync(CONFIG_PATH)) {
+            printHelp();
+            if (!fs.existsSync(CONFIG_PATH)) {
                 console.log(`  No config found. Run ${chalk.bold("backdot --init")} to get started.`);
                 console.log();
             }

package/dist/commands/history.d.ts

@@ -0,0 +1 @@
+export declare function history(repoUrl?: string): Promise<void>;

package/dist/commands/history.js

@@ -0,0 +1,28 @@
+import ora from "ora";
+import { select } from "@inquirer/prompts";
+import { loadConfig } from "../config.js";
+import { gitPull, gitLog } from "../git.js";
+import { restore } from "./restore.js";
+import { logger } from "../log.js";
+export async function history(repoUrl) {
+    logger.info("Starting history");
+    const repository = repoUrl ?? loadConfig().repository;
+    const spinner = ora("Fetching backup history").start();
+    await gitPull(repository);
+    const commits = await gitLog();
+    spinner.stop();
+    if (commits.length === 0) {
+        console.log("\n  No backup history found.\n");
+        return;
+    }
+    const selected = await select({
+        message: "Select a backup to restore from:",
+        loop: false,
+        choices: commits.map((c) => ({
+            name: `${c.hash.slice(0, 7)}  ${c.date.split("T")[0]}  ${c.message}`,
+            value: c.hash,
+        })),
+    });
+    console.log();
+    await restore(repoUrl, selected);
+}

package/dist/commands/restore.d.ts

@@ -1 +1,5 @@
-export declare function restore(repoUrl?: string): Promise<void>;
+interface RestoreOptions {
+    yes?: boolean;
+}
+export declare function restore(repoUrl?: string, commit?: string, options?: RestoreOptions): Promise<void>;
+export {};

package/dist/commands/restore.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import ora from "ora";
-import { checkbox, select } from "@inquirer/prompts";
+import { checkbox, select, Separator } from "@inquirer/prompts";
 import { loadConfig } from "../config.js";
 import { gitPull } from "../git.js";
 import { STAGING_DIR, machineDir } from "../staging.js";
@@ -25,13 +25,13 @@ function listMachines() {
         .filter((e) => e.isDirectory() && e.name !== ".git")
         .map((e) => e.name);
 }
-async function resolveRepoAndMachine(repoUrl) {
+async function resolveRepoAndMachine(repoUrl, commit) {
     if (!repoUrl) {
         const config = loadConfig();
         return { repository: config.repository, machine: config.machine };
     }
     const spinner = ora("Cloning backup repository").start();
-    await gitPull(repoUrl);
+    await gitPull(repoUrl, commit);
     spinner.stop();
     const machines = listMachines();
     if (machines.length === 0) {
@@ -44,18 +44,19 @@ async function resolveRepoAndMachine(repoUrl) {
     else {
         machine = await select({
             message: "Multiple machines found. Which one do you want to restore?",
+            loop: false,
             choices: machines.map((m) => ({ name: m, value: m })),
         });
     }
     return { repository: repoUrl, machine };
 }
-export async function restore(repoUrl) {
+export async function restore(repoUrl, commit, options = {}) {
     logger.info("Starting restore");
-    const { repository, machine } = await resolveRepoAndMachine(repoUrl);
+    const { repository, machine } = await resolveRepoAndMachine(repoUrl, commit);
     const spinner = ora("Fetching latest backup").start();
     const baseDir = machineDir(machine);
     if (!repoUrl) {
-        await gitPull(repository);
+        await gitPull(repository, commit);
     }
     spinner.text = "Resolving files";
     if (!fs.existsSync(baseDir)) {
@@ -86,25 +87,29 @@ export async function restore(repoUrl) {
     logger.info(`${fresh.length} new, ${existing.length} already exist`);
     spinner.stop();
     console.log();
-    if (fresh.length > 0) {
-        console.log(`${fresh.length} new file(s) to restore:`);
-        console.log();
-        for (const f of fresh) {
-            console.log(`  ${f.rel}`);
-        }
-        console.log();
+    let toRestore;
+    if (options.yes) {
+        toRestore = fresh;
     }
-    let toRestore = fresh;
-    if (existing.length > 0) {
-        const selected = await checkbox({
-            message: `${existing.length} file(s) already exist. Select which to overwrite:`,
-            choices: existing.map((f) => ({
-                name: f.rel,
-                value: f,
-                checked: true,
-            })),
+    else {
+        const choices = [];
+        if (fresh.length > 0) {
+            choices.push(new Separator(`── New files (${fresh.length}) ──`));
+            for (const f of fresh) {
+                choices.push({ name: f.rel, value: f, checked: true });
+            }
+        }
+        if (existing.length > 0) {
+            choices.push(new Separator(`── Existing files — will overwrite (${existing.length}) ──`));
+            for (const f of existing) {
+                choices.push({ name: f.rel, value: f, checked: false });
+            }
+        }
+        toRestore = await checkbox({
+            message: "Select files to restore:",
+            loop: false,
+            choices,
         });
-        toRestore = [...fresh, ...selected];
         console.log();
     }
     if (toRestore.length === 0) {

package/dist/git.d.ts

@@ -1,4 +1,20 @@
-export declare function gitPull(repository: string): Promise<void>;
+interface FileChangeSummary {
+    created: string[];
+    deleted: string[];
+    modified: string[];
+    renamed: Array<{
+        from: string;
+        to: string;
+    }>;
+}
+export declare function buildCommitMessage(changes: FileChangeSummary, maxLen?: number): string;
+export declare function gitPull(repository: string, commit?: string): Promise<void>;
+export declare function gitLog(limit?: number): Promise<Array<{
+    hash: string;
+    date: string;
+    message: string;
+}>>;
 export declare function gitCommitAndPush(): Promise<{
     commitUrl: string | null;
 } | null>;
+export {};

package/dist/git.js

@@ -5,12 +5,50 @@ import { simpleGit, CleanOptions } from "simple-git";
 import { logger } from "./log.js";
 import { STAGING_DIR } from "./staging.js";
 import { getCommitUrl } from "./commitUrl.js";
-export async function gitPull(repository) {
+export function buildCommitMessage(changes, maxLen = 250) {
+    const unique = (paths) => [...new Set(paths.map((f) => path.basename(f)))];
+    const removed = unique(changes.deleted);
+    const added = unique(changes.created);
+    const modified = unique([...changes.modified, ...changes.renamed.map((r) => r.to)]);
+    const categories = [
+        { label: "removed", files: removed },
+        { label: "added", files: added },
+        { label: "modified", files: modified },
+    ].filter((c) => c.files.length > 0);
+    if (categories.length === 0) {
+        return "backup";
+    }
+    function format(cat, listFiles) {
+        if (listFiles) {
+            return `${cat.label}: ${cat.files.join(", ")}`;
+        }
+        const n = cat.files.length;
+        return `${cat.label}: ${n} file${n !== 1 ? "s" : ""}`;
+    }
+    function build(listFlags) {
+        return categories.map((cat, i) => format(cat, listFlags[i])).join("; ");
+    }
+    const flags = categories.map(() => true);
+    let msg = build(flags);
+    if (msg.length <= maxLen)
+        return msg;
+    for (const label of ["modified", "added", "removed"]) {
+        const idx = categories.findIndex((c) => c.label === label);
+        if (idx !== -1 && flags[idx]) {
+            flags[idx] = false;
+            msg = build(flags);
+            if (msg.length <= maxLen)
+                return msg;
+        }
+    }
+    return msg.slice(0, maxLen - 3) + "...";
+}
+export async function gitPull(repository, commit) {
     if (fs.existsSync(path.join(STAGING_DIR, ".git"))) {
         const git = simpleGit(STAGING_DIR);
         await git.fetch("origin");
-        const branch = await git.revparse(["--abbrev-ref", "HEAD"]);
-        await git.reset(["--hard", `origin/${branch}`]);
+        const target = commit ?? `origin/${await git.revparse(["--abbrev-ref", "HEAD"])}`;
+        await git.reset(["--hard", target]);
         await git.clean(CleanOptions.FORCE, ["-d"]);
     }
     else {
@@ -23,9 +61,23 @@ export async function gitPull(repository) {
             await git.init();
             await git.addRemote("origin", repository);
         }
+        if (commit) {
+            const git = simpleGit(STAGING_DIR);
+            await git.reset(["--hard", commit]);
+            await git.clean(CleanOptions.FORCE, ["-d"]);
+        }
     }
     logger.info("Synced staging directory from remote");
 }
+export async function gitLog(limit = 20) {
+    const git = simpleGit(STAGING_DIR);
+    const log = await git.log({ maxCount: limit });
+    return log.all.map((entry) => ({
+        hash: entry.hash,
+        date: entry.date,
+        message: entry.message,
+    }));
+}
 export async function gitCommitAndPush() {
     const git = simpleGit(STAGING_DIR);
     await git.add(".");
@@ -34,8 +86,7 @@ export async function gitCommitAndPush() {
         logger.info("No changes to commit");
         return null;
     }
-    const date = new Date().toISOString().split("T")[0];
-    const message = `Automated backup: ${date}`;
+    const message = buildCommitMessage(status);
     await git.commit(message);
     await pRetry(async () => git.push(["-u", "origin", "HEAD"]), {
         retries: 5,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backdot",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Lightweight CLI to backup dotfiles and gitignored files to a Git repo on a daily schedule",
   "type": "module",
   "license": "MIT",