backdot 1.0.0

package/README.md

@@ -0,0 +1,98 @@
+# backdot
+
+Lightweight CLI to back up dotfiles and gitignored files to a private Git repo, with optional daily scheduling via macOS launchd.
+
+## How it works
+
+1. Reads `~/.backdot.json` for the target repository and file entries
+2. Resolves file entries — either gitignored files in a directory or glob patterns
+3. Copies resolved files to `~/.backdot/repo/`, preserving directory structure relative to `~`
+4. Commits and pushes changes to the configured remote
+
+## Installation
+
+```bash
+npm install -g backdot
+```
+
+Requires Node.js and `git` available on your PATH.
+
+## Configuration
+
+Create `~/.backdot.json`:
+
+```json
+{
+  "repository": "git@github.com:USERNAME/dotfiles-backup.git",
+  "files.gitignored": ["~/my-project"],
+  "files.match": ["~/.zshrc", "~/.config/ghostty/**"]
+}
+```
+
+### File entry types
+
+| Key                | Description                                                                                                                       |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `files.gitignored` | Array of directories. Backs up all gitignored files in each directory (runs `git ls-files --others --ignored --exclude-standard`) |
+| `files.match`      | Array of glob patterns. Backs up all matching files (powered by [fast-glob](https://github.com/mrmlnc/fast-glob))                 |
+
+Both keys are optional, but at least one must be present and non-empty. Paths support `~` expansion.
+
+## Usage
+
+### Run a backup
+
+```bash
+backdot --backup
+```
+
+### Restore from backup
+
+```bash
+backdot --restore
+```
+
+Pulls the latest state from the remote backup repo and copies files back to their original locations. If any files already exist, you'll be prompted to select which ones to overwrite.
+
+### Schedule daily backups (macOS)
+
+```bash
+backdot --schedule
+```
+
+Installs a launchd job (`com.backdot.daemon`) that runs the backup daily at 02:00.
+
+### Remove the schedule
+
+```bash
+backdot --unschedule
+```
+
+### Check status
+
+```bash
+backdot --status
+```
+
+Shows whether the daily schedule is active and lists all files that would be backed up. Useful for verifying your `~/.backdot.json` is correct.
+
+## File locations
+
+| Path                                              | Purpose                                |
+| ------------------------------------------------- | -------------------------------------- |
+| `~/.backdot.json`                                 | Configuration file                     |
+| `~/.backdot/repo/`                                | Local staging directory (the git repo) |
+| `~/.backdot/backup.log`                           | Backup log                             |
+| `~/Library/LaunchAgents/com.backdot.daemon.plist` | launchd job (when using `--schedule`)  |
+
+## Development
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import ora from "ora";
+import { loadConfig } from "./config.js";
+import { resolveFiles } from "./resolve.js";
+import { copyToStaging } from "./staging.js";
+import { gitSync } from "./git.js";
+import { restore } from "./restore.js";
+import { setupLaunchd, uninstallLaunchd, isScheduled } from "./plist.js";
+import { logger } from "./log.js";
+async function backup() {
+    logger.info("Starting backup");
+    const config = loadConfig();
+    logger.info(`Repository: ${config.repository}`);
+    const spinner = ora("Resolving files").start();
+    const files = resolveFiles(config.files);
+    logger.info(`Resolved ${files.length} file(s)`);
+    if (files.length === 0) {
+        spinner.info("No files resolved, nothing to back up");
+        return;
+    }
+    spinner.text = `Copying ${files.length} file(s) to staging`;
+    copyToStaging(files);
+    spinner.text = "Pushing to remote";
+    await gitSync(config.repository);
+    spinner.succeed("Backup complete");
+    console.log();
+    logger.info("Backup complete");
+}
+function status() {
+    const scheduled = isScheduled();
+    console.log();
+    console.log(`  Schedule:  ${scheduled ? "active (daily at 02:00)" : "not active"}`);
+    try {
+        const config = loadConfig();
+        console.log(`  Repo:      ${config.repository}`);
+        console.log();
+        const spinner = ora("Resolving files").start();
+        const files = resolveFiles(config.files);
+        if (files.length === 0) {
+            spinner.warn("No files resolved. Check your ~/.backdot.json entries.");
+        }
+        else {
+            spinner.succeed(`${files.length} file(s) resolved`);
+            console.log();
+            for (const file of files) {
+                console.log(`  ${file}`);
+            }
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`\n  Config error: ${msg}`);
+        process.exit(1);
+    }
+    console.log();
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    try {
+        if (command === "--backup") {
+            await backup();
+        }
+        else if (command === "--schedule") {
+            setupLaunchd();
+        }
+        else if (command === "--unschedule") {
+            uninstallLaunchd();
+        }
+        else if (command === "--status") {
+            status();
+        }
+        else if (command === "--restore") {
+            await restore();
+        }
+        else {
+            console.log();
+            console.log("  Usage: backdot <command>");
+            console.log();
+            console.log("  Commands:");
+            console.log();
+            console.log("    --backup       Run a backup now");
+            console.log("    --restore      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();
+            if (command && command !== "--help") {
+                console.error(`  Unknown command: ${command}`);
+                console.log();
+                process.exit(1);
+            }
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.error(msg);
+        console.error(`\n  Error: ${msg}\n`);
+        process.exit(1);
+    }
+}
+main();

package/dist/config.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+export declare function expandTilde(p: string): string;
+declare const ConfigSchema: z.ZodPipe<z.ZodObject<{
+    repository: z.ZodString;
+    "files.gitignored": z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>>;
+    "files.match": z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>>;
+}, z.core.$strip>, z.ZodTransform<{
+    repository: string;
+    files: {
+        gitignored: string[];
+        match: string[];
+    };
+}, {
+    repository: string;
+    "files.gitignored": string[];
+    "files.match": string[];
+}>>;
+export type Config = z.infer<typeof ConfigSchema>;
+export declare function loadConfig(): Config;
+export {};

package/dist/config.js

@@ -0,0 +1,48 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { z } from "zod";
+const CONFIG_PATH = path.join(os.homedir(), ".backdot.json");
+export function expandTilde(p) {
+    if (p.startsWith("~/") || p === "~") {
+        return path.join(os.homedir(), p.slice(1));
+    }
+    return p;
+}
+const pathList = z.array(z.string().min(1).transform(expandTilde)).optional().default([]);
+const ConfigSchema = z
+    .object({
+    repository: z.string().min(1),
+    "files.gitignored": pathList,
+    "files.match": pathList,
+})
+    .refine((c) => c["files.gitignored"].length > 0 || c["files.match"].length > 0, {
+    message: 'At least one of "files.gitignored" or "files.match" must be a non-empty array',
+})
+    .transform((c) => ({
+    repository: c.repository,
+    files: {
+        gitignored: c["files.gitignored"],
+        match: c["files.match"],
+    },
+}));
+export function loadConfig() {
+    if (!fs.existsSync(CONFIG_PATH)) {
+        throw new Error(`Config file not found: ${CONFIG_PATH}`);
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(CONFIG_PATH, "utf-8");
+    }
+    catch {
+        throw new Error(`Failed to read config file: ${CONFIG_PATH}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Invalid JSON in config file: ${CONFIG_PATH}`);
+    }
+    return ConfigSchema.parse(parsed);
+}

package/dist/git.d.ts

@@ -0,0 +1,2 @@
+export declare function gitPull(repository: string): Promise<void>;
+export declare function gitSync(repository: string): Promise<void>;

package/dist/git.js

@@ -0,0 +1,48 @@
+import fs from "node:fs";
+import path from "node:path";
+import { simpleGit, CleanOptions } from "simple-git";
+import { logger } from "./log.js";
+import { STAGING_DIR } from "./staging.js";
+export async function gitPull(repository) {
+    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}`]);
+        await git.clean(CleanOptions.FORCE, ["-d"]);
+    }
+    else {
+        await simpleGit().clone(repository, STAGING_DIR);
+    }
+    logger.info("Synced staging directory from remote");
+}
+export async function gitSync(repository) {
+    if (!fs.existsSync(STAGING_DIR)) {
+        fs.mkdirSync(STAGING_DIR, { recursive: true });
+    }
+    const git = simpleGit(STAGING_DIR);
+    if (!fs.existsSync(path.join(STAGING_DIR, ".git"))) {
+        logger.info("Initializing new git repository in staging directory");
+        await git.init();
+        await git.addRemote("origin", repository);
+    }
+    await git.add(".");
+    const status = await git.status();
+    if (status.isClean()) {
+        logger.info("No changes to commit");
+        return;
+    }
+    const date = new Date().toISOString().split("T")[0];
+    const message = `Automated backup: ${date}`;
+    await git.commit(message);
+    logger.info(`Committed: ${message}`);
+    try {
+        await git.push(["-u", "origin", "HEAD"]);
+        logger.info("Pushed to remote");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.error(`Push failed: ${msg}`);
+        throw new Error(`Push failed: ${msg}`);
+    }
+}

package/dist/log.d.ts

@@ -0,0 +1,2 @@
+import winston from "winston";
+export declare const logger: winston.Logger;

package/dist/log.js

@@ -0,0 +1,9 @@
+import path from "node:path";
+import os from "node:os";
+import winston from "winston";
+const LOG_FILE = path.join(os.homedir(), ".backdot", "backup.log");
+export const logger = winston.createLogger({
+    level: "info",
+    format: winston.format.combine(winston.format.timestamp({ format: "YYYY-MM-DD HH:mm:ss" }), winston.format.printf(({ timestamp, level, message }) => `${timestamp} [${level}] ${message}`)),
+    transports: [new winston.transports.File({ filename: LOG_FILE })],
+});

package/dist/plist.d.ts

@@ -0,0 +1,3 @@
+export declare function isScheduled(): boolean;
+export declare function setupLaunchd(): void;
+export declare function uninstallLaunchd(): void;

package/dist/plist.js

@@ -0,0 +1,104 @@
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import ora from "ora";
+import { logger } from "./log.js";
+const LABEL = "com.backdot.daemon";
+const PLIST_PATH = path.join(os.homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+function getScriptPath() {
+    const currentDir = path.dirname(new URL(import.meta.url).pathname);
+    return path.resolve(currentDir, "cli.js");
+}
+function buildPlist() {
+    const nodePath = process.execPath;
+    const scriptPath = getScriptPath();
+    const workingDir = path.dirname(scriptPath);
+    const logPath = path.join(os.homedir(), ".backdot", "launchd.log");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${nodePath}</string>
+    <string>${scriptPath}</string>
+    <string>--backup</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${workingDir}</string>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Hour</key>
+    <integer>2</integer>
+    <key>Minute</key>
+    <integer>0</integer>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>${logPath}</string>
+  <key>StandardErrorPath</key>
+  <string>${logPath}</string>
+  <key>RunAtLoad</key>
+  <false/>
+</dict>
+</plist>`;
+}
+export function isScheduled() {
+    if (!fs.existsSync(PLIST_PATH)) {
+        return false;
+    }
+    try {
+        const output = execSync(`launchctl list ${LABEL}`, { encoding: "utf-8", stdio: "pipe" });
+        return output.includes(LABEL);
+    }
+    catch {
+        return false;
+    }
+}
+export function setupLaunchd() {
+    const spinner = ora("Installing schedule").start();
+    const plistContent = buildPlist();
+    const dir = path.dirname(PLIST_PATH);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    try {
+        execSync(`launchctl unload ${PLIST_PATH}`, { stdio: "pipe" });
+    }
+    catch {
+        // Not loaded, that's fine
+    }
+    fs.writeFileSync(PLIST_PATH, plistContent);
+    logger.info(`Plist written to ${PLIST_PATH}`);
+    try {
+        execSync(`launchctl load ${PLIST_PATH}`);
+        spinner.succeed("Daily backup scheduled (02:00)");
+        console.log();
+        logger.info("Launchd job loaded");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        spinner.fail(`Failed to load launchd job: ${msg}`);
+        console.log();
+        logger.error(`Failed to load launchd job: ${msg}`);
+        process.exit(1);
+    }
+}
+export function uninstallLaunchd() {
+    const spinner = ora("Removing schedule").start();
+    try {
+        execSync(`launchctl unload ${PLIST_PATH}`, { stdio: "pipe" });
+        logger.info("Launchd job unloaded");
+    }
+    catch {
+        logger.info("Launchd job was not loaded");
+    }
+    if (fs.existsSync(PLIST_PATH)) {
+        fs.unlinkSync(PLIST_PATH);
+        logger.info(`Plist removed: ${PLIST_PATH}`);
+    }
+    spinner.succeed("Schedule removed");
+    console.log();
+}

package/dist/resolve.d.ts

@@ -0,0 +1,6 @@
+import { Config } from "./config.js";
+/**
+ * Resolve all file entries to absolute paths.
+ * Skips entries that fail resolution and logs warnings.
+ */
+export declare function resolveFiles(files: Config["files"]): string[];

package/dist/resolve.js

@@ -0,0 +1,62 @@
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import fg from "fast-glob";
+import { logger } from "./log.js";
+function resolveGitignored(dirPath) {
+    if (!fs.existsSync(dirPath)) {
+        logger.warn(`Directory does not exist, skipping: ${dirPath}`);
+        return [];
+    }
+    try {
+        const output = execSync("git ls-files --others --ignored --exclude-standard", {
+            cwd: dirPath,
+            encoding: "utf-8",
+        });
+        return output
+            .split("\n")
+            .filter((line) => line.length > 0)
+            .map((rel) => path.resolve(dirPath, rel));
+    }
+    catch {
+        logger.warn(`Failed to list gitignored files in: ${dirPath}`);
+        return [];
+    }
+}
+function resolveGlob(pattern) {
+    try {
+        return fg.sync(pattern, { absolute: true, dot: true });
+    }
+    catch {
+        logger.warn(`Glob pattern failed: ${pattern}`);
+        return [];
+    }
+}
+/**
+ * Resolve all file entries to absolute paths.
+ * Skips entries that fail resolution and logs warnings.
+ */
+export function resolveFiles(files) {
+    const allFiles = [];
+    for (const dirPath of files.gitignored) {
+        allFiles.push(...resolveGitignored(dirPath));
+    }
+    for (const pattern of files.match) {
+        allFiles.push(...resolveGlob(pattern));
+    }
+    return allFiles.filter((filePath) => {
+        try {
+            fs.accessSync(filePath, fs.constants.R_OK);
+            const stat = fs.statSync(filePath);
+            if (!stat.isFile()) {
+                logger.warn(`Not a regular file, skipping: ${filePath}`);
+                return false;
+            }
+            return true;
+        }
+        catch {
+            logger.warn(`File not readable, skipping: ${filePath}`);
+            return false;
+        }
+    });
+}

package/dist/restore.d.ts

@@ -0,0 +1 @@
+export declare function restore(): Promise<void>;

package/dist/restore.js

@@ -0,0 +1,81 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import ora from "ora";
+import { checkbox } from "@inquirer/prompts";
+import { loadConfig } from "./config.js";
+import { gitPull } from "./git.js";
+import { STAGING_DIR } from "./staging.js";
+import { logger } from "./log.js";
+const HOME = os.homedir();
+function walkDir(dir) {
+    const results = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === ".git")
+            continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...walkDir(full));
+        }
+        else {
+            results.push(full);
+        }
+    }
+    return results;
+}
+export async function restore() {
+    logger.info("Starting restore");
+    const config = loadConfig();
+    const spinner = ora("Fetching latest backup").start();
+    await gitPull(config.repository);
+    spinner.text = "Resolving files";
+    const stagedFiles = walkDir(STAGING_DIR);
+    logger.info(`Found ${stagedFiles.length} file(s) in backup repository`);
+    if (stagedFiles.length === 0) {
+        spinner.stop();
+        console.log("No files found in backup repository.");
+        return;
+    }
+    const fileMappings = stagedFiles.map((src) => {
+        const rel = path.relative(STAGING_DIR, src);
+        return { src, dest: path.join(HOME, rel), rel };
+    });
+    const existing = fileMappings.filter((f) => fs.existsSync(f.dest));
+    const fresh = fileMappings.filter((f) => !fs.existsSync(f.dest));
+    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 = 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,
+            })),
+        });
+        toRestore = [...fresh, ...selected];
+        console.log();
+    }
+    if (toRestore.length === 0) {
+        console.log("No files selected for restore.");
+        return;
+    }
+    const copySpinner = ora("Restoring files").start();
+    for (const { src, dest } of toRestore) {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(src, dest);
+    }
+    copySpinner.succeed(`Restored ${toRestore.length} file(s)`);
+    console.log();
+    logger.info(`Restored ${toRestore.length} file(s)`);
+}

package/dist/staging.d.ts

@@ -0,0 +1,2 @@
+export declare const STAGING_DIR: string;
+export declare function copyToStaging(files: string[]): void;

package/dist/staging.js

@@ -0,0 +1,26 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { logger } from "./log.js";
+const HOME = os.homedir();
+export const STAGING_DIR = path.join(HOME, ".backdot", "repo");
+export function copyToStaging(files) {
+    if (!fs.existsSync(STAGING_DIR)) {
+        fs.mkdirSync(STAGING_DIR, { recursive: true });
+    }
+    let copied = 0;
+    for (const filePath of files) {
+        const rel = path.relative(HOME, filePath);
+        const destRel = rel.startsWith("..") ? filePath.slice(1) : rel;
+        const dest = path.join(STAGING_DIR, destRel);
+        try {
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            fs.copyFileSync(filePath, dest);
+            copied++;
+        }
+        catch {
+            logger.warn(`Failed to copy: ${filePath} -> ${dest}`);
+        }
+    }
+    logger.info(`Copied ${copied} file(s) to staging`);
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "backdot",
+  "version": "1.0.0",
+  "description": "Lightweight CLI to backup dotfiles and gitignored files to a Git repo on a daily schedule",
+  "type": "module",
+  "license": "MIT",
+  "main": "dist/cli.js",
+  "bin": {
+    "backdot": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "dotfiles",
+    "backup",
+    "git",
+    "cli",
+    "launchd",
+    "gitignore"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write src/",
+    "format:check": "prettier --check src/",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.0",
+    "fast-glob": "^3.3.3",
+    "ora": "^9.3.0",
+    "simple-git": "^3.32.2",
+    "winston": "^3.19.0",
+    "zod": "^4.3.6"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.13.5",
+    "eslint": "^10.0.2",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.1",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.56.1",
+    "vitest": "^4.0.18"
+  }
+}