@frakjs/frak 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 frakjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# Frak
+
+**Frak** is an agentless deployment tool for web apps. Powered by `rsync` over SSH, it tracks file changes, creates patch backups, and supports dry-run diffs, interactive confirmations, and post-deploy hooks.
+
+> “Frak it, ship it.”
+
+ 
+
+## 🚀 Features
+
+- 🔌 **Init once, deploy anytime**
+- 🔎 **Interactive diffs** before every push/pull
+- 📦 **Patch-based backups** stored on your server
+- 🧾 **Post-deploy commands** (e.g. restart services)
+- 📡 **SSH console access** into deploy root
+- 🔁 **Pull support** for syncing back changes
+- 📋 **Backup inspection** with additions/deletions summary
+
+## 📦 Installation
+
+```bash
+npm install -g @frakjs/frak
+```
+
+Or run it on-demand with `npx`
+
+```bash
+npx @frakjs/frak <command>
+```
+
+## 🛠️ Setup
+
+```bash
+frak init
+```
+
+This creates a `frak.config.js` file:
+
+```js
+export default {
+    server: "user@example.com",
+    root: "/var/www/html",
+    after: "npm run restart" // optional post-deploy hook
+};
+```
+
+## 🧩 Commands
+
+```
+frak init              # Create config file
+frak console           # SSH into the deploy root
+frak diff              # Show dry-run changes
+frak push              # Deploy changes (with confirmation)
+frak pull              # Download changes from remote
+frak backups:list      # List previous patch deployments
+```
+
+## 🔐 Authentication
+
+Frak uses SSH. Make sure your public key is in `~/.ssh/authorized_keys` on the remote server.
+
+## 🧪 Example: Deployment Flow
+
+```bash
+frak diff          # See what will change
+frak push          # Sync files, confirm, deploy
+```
+
+Behind the scenes:
+
+- Files are compared with a dry-run rsync
+- If approved, a patch file is generated and saved
+- Files are synced live
+- Optional after script is run remotely
+
+## 💾 Backups
+
+Each deployment saves a `.patch` file on the server under `.backups/`. You can list them with:
+
+```bash
+frak backups:list
+```
+
+Output shows:
+
+- Timestamp
+- Filename
+- Additions and deletions in the patch
+
+## 🧠 Design Philosophy
+
+- Minimal dependencies
+- Pure CLI
+- Patch-based history
+- No Docker or Node on server
+- Human-friendly
+
+## 🧰 Advanced Config (optional)
+
+```js
+export default {
+    server: 'user@host',
+    root: '/srv/www',
+    after: 'sudo systemctl reload nginx',
+
+    dev: {
+        root: '/srv/www-dev',
+    },
+
+    production: {
+        root: '/srv/www-prod',
+    },
+};
+```
+
+```bash
+frak push                   # uses default root-level properties
+frak push env=dev           # uses properties in "dev" to override
+frak push env=production    # uses properties in "production" to override
+```
+
+## 🐛 Debugging
+
+Enable debug output by setting `DEBUG=1`:
+
+```bash
+DEBUG=1 frak push
+```
+
+## 📄 License
+
+MIT
+
+## 🧑‍💻 Author
+
+Built by [Frank Strube](https://github.com/fstrube)
+
+Contributions and suggestions welcome!

package/bin/frak.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+
+import { execSync, spawn } from 'node:child_process';
+import { readFileSync, writeFileSync, existsSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import * as ansi from '../src/ansi.js';
+import * as cli from '../src/cli.js';
+import config, { load as loadConfig } from '../src/config.js';
+import { sha256 } from '../src/crypto.js';
+import debug from '../src/debug.js';
+import diff from '../src/diff.js';
+import humanize from '../src/humanize.js';
+import * as rsync from '../src/rsync.js';
+import * as ssh from '../src/ssh.js';
+import * as date from '../src/date.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Try to load config. If it fails, print error message in red.
+ *
+ * @param {String} env
+ */
+async function tryLoadConfig(env) {
+    try {
+        await loadConfig(env);
+    } catch (e) {
+        console.log(ansi.red(e.message));
+
+        process.exit(1);
+    }
+
+    return;
+}
+
+/**
+ * Print command usage instructions.
+ */
+function usage() {
+    console.log('Usage: frak <command>');
+    console.log('Commands:');
+    console.log('  init          Initialize the current directory for frak deployment');
+    console.log('  console       Connect to the remote server via SSH');
+    console.log('  diff          Show differences between local and remote files');
+    console.log('  pull          Download the remote file(s)');
+    console.log('  push          Deploy website via rsync');
+    console.log('  backups:list  List backups on the server');
+}
+
+/**
+ * Execute the command.
+ *
+ * @param {Array} args
+ */
+async function main(args) {
+    const { command, options } = cli.parse(args.slice(2));
+
+    debug('parsed:', { command, options });
+
+
+    // Initialize Frak in the current directory
+    if (command === 'init') {
+        const configPath = path.join(process.cwd(), 'frak.config.js');
+
+        if (!existsSync(configPath)) {
+            writeFileSync(configPath, `export default ${JSON.stringify({ server: 'example.com', root: '/var/www/html' }, null, 4)}`);
+            console.info(ansi.green('Configuration file created: frak.config.js'));
+        } else {
+            console.error(ansi.red('Frak is already initialized in this directory.'));
+        }
+
+    // Start a console session, or run the provided command on
+    // the remote server.
+    } else if (command === 'console') {
+        await tryLoadConfig(options.env);
+
+        if (!config.server) {
+            console.error('No remote server configured. Add "server" to frak.config.js');
+            process.exit(1);
+        }
+
+        try {
+            const cmd = options.command ?? '\\$SHELL -l -i';
+
+            execSync(`ssh -t ${config.server} -- cd ${config.root} \\&\\& ${cmd}`, { stdio: 'inherit' });
+        } catch (e) {
+            debug(e)
+        }
+    // Show the differences between local files and remote server
+    } else if (command === 'diff') {
+        await tryLoadConfig(options.env);
+
+        const { output } = await rsync.exec('--dry-run');
+
+        await diff(output, options);
+
+    // Push or pull changes to remote server
+    } else if (command === 'push' || command === 'pull') {
+        await tryLoadConfig(options.env);
+
+        // Execute dry-run
+        const { output } = await rsync.exec('--dry-run');
+
+        console.log(humanize(output));
+
+        if (command === 'push' && config.after) {
+            console.log(ansi.blue('Run command:'), config.after, '\n');
+        }
+
+        const proceed = await cli.agree(ansi.yellow('The above actions will be taken. Continue? (This cannot be undone): '));
+
+        if (!proceed) {
+            process.exit(1);
+        }
+
+        // Prepare patch file
+        let patch;
+
+        try {
+            patch = await diff(output, { interactive: false });
+        } catch (e) {
+            console.error(e);
+
+            process.exit(1);
+        }
+
+        // Execute actual rsync command
+        const { backupPath, output: actualOutput } = await rsync.exec();
+
+        console.log('');
+        console.log(humanize(actualOutput));
+
+        // Place patch file in backup dir
+        const hash = sha256(patch).slice(0, 7);
+        const copy = spawn('ssh', [config.server, '--', `cat > '${config.root || '.'}/${backupPath}/${hash}.patch'`]);
+
+        copy.stdout.on('data', (data) => debug('' + data));
+        copy.stderr.on('data', (data) => debug('' + data));
+        copy.stdin.write(patch);
+
+        // Execute "after" command
+        if (command === 'push' && config.after) {
+            console.log(ansi.yellow('Executing commands on remote server.'));
+
+            debug({ command: config.after });
+
+            try {
+                await ssh.exec(config.after, { server: config.server, root: config.root });
+            } catch (e) {
+                debug(e);
+            }
+        }
+
+        // TODO Webhook
+
+        if (command === 'push') {
+            console.log(ansi.green('Deployment complete.'));
+        }
+    } else if (command === 'backups:list') {
+        await tryLoadConfig(options.env);
+
+        const delimeter = '------Separator--';
+        const grep = {
+            additions: `grep -e '^+' "$NAME"/*.patch | grep -v '^+++' | wc -l`,
+            deletions: `grep -e '^-' "$NAME"/*.patch | grep -v '^---' | wc -l`,
+        }
+        const ls = `stat --format='%Y %n' .backups/* | sort -r`;
+
+        const list = ssh.exec(`${ls} | xargs -I {} sh -c 'TIMESTAMP=$(echo {} | cut -d" " -f1); NAME=$(echo {} | cut -d" " -f2-); echo $TIMESTAMP${delimeter}$NAME${delimeter}$(${grep.additions})${delimeter}$(${grep.deletions})'`, { quiet: true, server: config.server, root: config.root });
+        let backups = '';
+
+        list.stdout.on('data', data => backups += data);
+
+        await list;
+
+        const table = new cli.Table([
+            {
+                header: 'Name',
+                width: 55,
+            },
+            {
+                header: 'Date',
+                width: 25,
+            },
+            {
+                header: 'Changes',
+                width: 30,
+            }
+        ]);
+
+        backups.trim().split(/\n/).forEach(backup => {
+            const [ timestamp, name, additions, deletions ] = backup.split(delimeter);
+            table.row([
+                name.replace(/^.backups\//, ''),
+                date.relative(timestamp * 1000),
+                ansi.green(`${additions} addition${additions == 1 ? '' : 's'}`) + ', ' + ansi.red(`${deletions} deletion${deletions == 1 ? '' : 's'}`),
+            ]);
+        });
+
+        table.print();
+    } else {
+        usage();
+
+        if (command !== '--help') {
+            process.exit(1);
+        }
+    }
+
+    process.exit(0);
+}
+
+main(process.argv);

package/eslint.config.js

@@ -0,0 +1 @@
+export default [{}]

package/frak.config.js

@@ -0,0 +1,10 @@
+export default {
+    server: 'franklinstrube.com',
+    root: '/home/ash/frak',
+    after: 'touch deployed; pwd',
+    method: 'rsync',
+
+    production: {
+        root: '/home/ash/frak-production',
+    },
+};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@frakjs/frak",
+  "version": "0.1.0",
+  "description": "A commandline deployment tool for syncing files to remote servers.",
+  "main": "index.js",
+  "bin": {
+    "frak": "bin/frak.js"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/frakjs/frak.git"
+  },
+  "keywords": [
+    "rsync",
+    "deployment",
+    "ssh"
+  ],
+  "author": "Frank Strube <contact@frakjs.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/frakjs/frak/issues"
+  },
+  "homepage": "https://github.com/frakjs/frak#readme"
+}

package/src/ansi.js

@@ -0,0 +1,77 @@
+const ansi = {
+    CLEAR: '\u001b[0m',
+    BOLD: '\u001b[1m',
+    UNDERLINE: '\u001b[4m',
+
+    BLACK: '\u001b[30m',
+    GRAY: '\u001b[90m',
+    RED: '\u001b[31m',
+    GREEN: '\u001b[32m',
+    YELLOW: '\u001b[33m',
+    BLUE: '\u001b[34m',
+    MAGENTA: '\u001b[35m',
+    CYAN: '\u001b[36m',
+    WHITE: '\u001b[37m',
+};
+
+export function strip(string) {
+    return string
+        .replace(new RegExp(ansi.CLEAR.replace('[', '\\['), 'g'), '')
+        .replace(new RegExp(ansi.BOLD.replace('[', '\\['), 'g'), '')
+        .replace(new RegExp(ansi.UNDERLINE.replace('[', '\\['), 'g'), '')
+        .replace(new RegExp(ansi.BLACK.replace('[', '\\['), 'g'), '')
+        .replace(new RegExp(ansi.GRAY.replace('[', '\\['), 'g'), '')
+        .replace(new RegExp(ansi.RED.replace('[', '\\['), 'g'), '')
+        .replace(new RegExp(ansi.GREEN.replace('[', '\\['), 'g'), '')
+        .replace(new RegExp(ansi.YELLOW.replace('[', '\\['), 'g'), '')
+        .replace(new RegExp(ansi.BLUE.replace('[', '\\['), 'g'), '')
+        .replace(new RegExp(ansi.MAGENTA.replace('[', '\\['), 'g'), '')
+        .replace(new RegExp(ansi.CYAN.replace('[', '\\['), 'g'), '')
+        .replace(new RegExp(ansi.WHITE.replace('[', '\\['), 'g'), '');
+}
+
+export function bold(string) {
+    return `${ansi.BOLD}${string}${ansi.CLEAR}`;
+}
+
+export function underline(string) {
+    return `${ansi.UNDERLINE}${string}${ansi.CLEAR}`;
+}
+
+export function black(string) {
+    return `${ansi.BLACK}${string}${ansi.CLEAR}`;
+}
+
+export function gray(string) {
+    return `${ansi.GRAY}${string}${ansi.CLEAR}`;
+}
+
+export function red(string) {
+    return `${ansi.RED}${string}${ansi.CLEAR}`;
+}
+
+export function green(string) {
+    return `${ansi.GREEN}${string}${ansi.CLEAR}`;
+}
+
+export function yellow(string) {
+    return `${ansi.YELLOW}${string}${ansi.CLEAR}`;
+}
+
+export function blue(string) {
+    return `${ansi.BLUE}${string}${ansi.CLEAR}`;
+}
+
+export function magenta(string) {
+    return `${ansi.MAGENTA}${string}${ansi.CLEAR}`;
+}
+
+export function cyan(string) {
+    return `${ansi.CYAN}${string}${ansi.CLEAR}`;
+}
+
+export function white(string) {
+    return `${ansi.WHITE}${string}${ansi.CLEAR}`;
+}
+
+export default ansi;

package/src/cli.js

@@ -0,0 +1,79 @@
+import * as ansi from './ansi.js';
+
+/**
+ * Parse the arguments into command and options.
+ *
+ * @param {Array} args
+ * @returns {{command: String, options: Object}}
+ */
+export function parse(args) {
+    let command = 'push';
+    const options = {
+        colorize: true,
+    };
+
+    for (let arg of args) {
+        if (arg.includes('=')) {
+            const [option, value] = arg.split('=', 2);
+
+            options[option] = value;
+        } else {
+            command = arg;
+        }
+    }
+
+    return { command, options };
+}
+
+export async function agree(string) {
+    process.stdout.write(string);
+
+    const answer = await new Promise((resolve, reject) => {
+        process.stdin.on('data', data => resolve(data));
+    });
+
+    return ['y', 'yes'].includes(`${answer}`.trim().toLowerCase());
+}
+
+export class Table {
+    constructor(columns) {
+        this.columns = columns;
+        this.rows = [];
+    }
+
+    row(cells) {
+        this.rows.push(cells);
+    }
+
+    print() {
+        const { border, header } = this.columns.reduce(({ header, border }, column, i) => {
+            const width = ansi.strip(column.header).length;
+            const padding = Math.max(0, column.width - width - 2);
+            const paddingString = (new Array(padding + 1)).join(' ');
+            const borderString = (new Array(column.width + 1).join('-'));
+
+            return {
+                border: `${border || ''}+${borderString}${i === this.columns.length - 1 ? '+' : ''}`,
+                header: `${header || ''}${ansi.gray('|')} ${ansi.bold(column.header)}${paddingString} ${i === this.columns.length - 1 ? ansi.gray('|') : ''}`,
+            };
+        }, {});
+
+        console.log(ansi.gray(border));
+        console.log(header);
+        console.log(ansi.gray(border));
+
+        this.rows.forEach(r => {
+            const rowString = r.reduce((row, cell, i) => {
+                const width = ansi.strip(cell).length
+                const padding = Math.max(0, this.columns[i].width - width - 2);
+                const paddingString = (new Array(padding + 1)).join(' ');
+                const borderString = (new Array(this.columns[i].width + 1).join('-'));
+
+                return `${row || ''}${ansi.gray('|')} ${cell}${paddingString} ${i === r.length - 1 ? ansi.gray('|') : ''}`
+            }, '');
+
+            console.log(rowString);
+            console.log(ansi.gray(border));
+        })
+    }
+}

package/src/config.js

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Cached config object. The config is stored in here so it can
+// be loaded once and imported across all modules.
+let config = {};
+
+/**
+ * Locate a config file in the current working directory or its parents.
+ *
+ * @returns {String}
+ */
+export function locate() {
+    for (let dir = process.cwd(); dir != '/'; dir = path.dirname(dir)) {
+        const configPath = path.join(dir, 'frak.config.js');
+
+        if (fs.existsSync(configPath)) {
+            return configPath;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Load the config values.
+ *
+ * @returns {Object}
+ */
+export async function load(env = null) {
+    const configPath = locate();
+
+    if (fs.existsSync(configPath)) {
+        Object.assign(config, (await import(configPath)).default);
+
+        if (env in config) {
+            return Object.assign(config, {...config[env]});
+        }
+
+        if (env) {
+            throw new Error(`Missing configuration for environment "${env}"!`);
+        }
+
+        return config;
+    }
+
+    throw new Error('Config file not found! Try running frak init.');
+}
+
+export default config;
+

package/src/crypto.js

@@ -0,0 +1,5 @@
+import crypto from 'node:crypto';
+
+export function sha256(text) {
+    return crypto.createHash('sha256').update(text).digest('hex');
+}

package/src/date.js

@@ -0,0 +1,61 @@
+function plural(string, value) {
+    return `${string}${value === 1 ? '' : 's'}`;
+}
+
+export function relative(date) {
+    const datetime = new Date(date);
+    const now = new Date();
+    const months = [
+        'Jan',
+        'Feb',
+        'Mar',
+        'Apr',
+        'May',
+        'Jun',
+        'Jul',
+        'Aug',
+        'Sep',
+        'Oct',
+        'Nov',
+        'Dec',
+    ];
+
+    let seconds = Math.abs((datetime - now) / 1000);
+    let agoOrFromNow = datetime > now ? 'from now' : 'ago';
+    let unit = 'second';
+    let value = 0;
+
+    if (seconds < 30) {
+        value = 'just';
+        unit = 'now';
+        agoOrFromNow = '';
+    // Less than a minute
+    } else if (seconds < 60) {
+        value = Math.floor(seconds);
+        unit = plural('second', value);
+    // Less than an hour
+    } else if (seconds < 60 * 60) {
+        value = Math.floor(seconds / 60);
+        unit = plural('minute', value);
+    // Less than a day
+    } else if (seconds < 60 * 60 * 24) {
+        value = Math.floor(seconds / 60 / 60);
+        unit = plural('hour', value);
+    // Less than a week
+    } else if (seconds < 60 * 60 * 24 * 7) {
+        value = Math.floor(seconds / 60 / 60 / 24);
+        unit = plural('day', value);
+    // Less than a month
+    } else if (seconds < 60 * 60 * 24 * 30) {
+        value = Math.floor(seconds / 60 / 60 / 24 / 7);
+        unit = plural('week', value);
+    // Less than a year
+    } else if (seconds < 60 * 60 * 24 * 365) {
+        value = Math.floor(seconds / 60 / 60 / 24 / 30);
+        unit = plural('month', value);
+    } else {
+        return `${months[datetime.getMonth()]} ${datetime.getDay()}, ${datetime.getFullYear()} @ ${datetime.getHours() % 12}:${`0${datetime.getMinutes()}`.slice(-2)} ${datetime.getHours() >= 12 ? 'pm' : 'am'}`;
+    }
+
+    return `${value} ${unit} ${agoOrFromNow}`.trim();
+}

package/src/debug.js

@@ -0,0 +1,10 @@
+import * as ansi from '../src/ansi.js';
+
+/**
+ * Wrapper for console.log, only prints in DEBUG mode.
+ */
+export default function debug() {
+    if (process.env.DEBUG) {
+        console.log.apply(console, [ansi.bold(ansi.cyan('DEBUG:')), ...arguments]);
+    }
+}

package/src/diff.js

@@ -0,0 +1,173 @@
+import { spawn } from 'node:child_process';
+import { statSync } from 'node:fs';
+import * as ansi from './ansi.js';
+import config from './config.js';
+import debug from './debug.js';
+
+export default async function diff(dryRunOutput, options) {
+    // Default options
+    options = {
+        interactive: true,
+        ...options,
+    };
+
+    // Get changes from an rsync dry-run
+    const changes = dryRunOutput
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map(line => {
+            // Split line into action and file, preserving whitespace for filenames
+            const [action, ...parts] = line.split(/\s+/);
+
+            let file, target;
+
+            // Links also have a target
+            if (action === 'cL+++++++++' || action === 'cLc.T......') {
+                const index = parts.indexOf('->');
+
+                debug({ parts })
+
+                file = parts.slice(0, index).join(' ');
+                target = parts.slice(index + 1).join(' ');
+            } else {
+                file = parts.join(' ');
+            }
+
+            return [action, file, target];
+        })
+        .filter(([action, file]) => file.slice(-1) !== '/');
+
+    debug({ changes })
+
+    let proceed = true;
+
+    if (changes.length >= 50 && options.interactive) {
+        proceed = await cli.agree(ansi.yellow(`${changes.length} file(s) will be compared. Continue?`))
+    }
+
+    if (!proceed) {
+        return Promise.reject('Process canceled by user');
+    }
+
+    const files = changes.map(([action, file]) => file);
+
+    const diffs = changes.sort((a, b) => a[1].localeCompare(b[1])).map(change => {
+        const [action, file] = change;
+        const header = [
+            `diff --git a/${file} b/${file}`,
+        ];
+
+        let diff = [];
+
+        if (action === '*deleting') {
+            header.push('deleted file mode 100644');
+            header.push('index 0000000..0000000');
+
+            diff = ['diff', '-Naurp', `--label=a/${file}`, `--label=/dev/null`, file, '/dev/null'];
+        } else if (action === '<f+++++++++') {
+            const { mode } = statSync(file);
+
+            header.push(`new file mode ${mode.toString(8)}`);
+            header.push('index 0000000..0000000');
+
+            diff = ['diff', '-Naurp', `--label=/dev/null`, `--label=b/${file}`, '/dev/null', `<(tar xzOf $tarball --warning=no-unknown-keyword ${file} || cat /dev/null)`];
+        } else if (action === 'cLc.T......') {
+            const target = change[2];
+
+            header.push('index 0000000..0000000');
+
+            diff = ['diff', '-Naurp', `--label=a/${file}`, `--label=b/${file}`, `<(printf %s $(readlink ${file}))`, `<(printf %s ${target})`];
+        } else if (action === 'cL+++++++++') {
+            const target = change[2];
+
+            header.push('new file mode 120000');
+            header.push('index 0000000..0000000');
+
+            diff = ['diff', '-Naurp', `--label=/dev/null`, `--label=b/${file}`, '/dev/null', `<(printf %s ${target})`];
+        } else {
+            const { mode } = statSync(file);
+
+            header.push(`index 0000000..0000000  ${mode.toString(8)}`);
+
+            diff = ['diff', '-Naurp', `--label=a/${file}`, `--label=b/${file}`, file, `<(tar xzOf $tarball --warning=no-unknown-keyword ${file} || cat /dev/null)`];
+        }
+
+        return [`printf "%s\\n" "${header.join('\n')}"`, ';', ...diff, ';'];
+    });
+
+    if (diffs.length > 0) {
+        debug({ diffs, files });
+
+        // Tarball the local files up to the server
+        const tar = spawn('tar', ['cz', ...files]);
+        const ssh = spawn('ssh', [
+            config.server,
+            '--',
+            'tarball=$(mktemp /tmp/frak-diff-tarball.XXXXXXXX);',
+            'cat > $tarball;',
+            `cd ${config.root};`,
+            ...diffs.reduce((commands, diff) => commands.concat(...diff), []),
+            // `${diffs.join(';')};`,
+            // 'rm $tarball',
+        ])
+        tar.stdout.pipe(ssh.stdin);
+
+        let less;
+
+        if (options.interactive) {
+            less = spawn('less', ['-r'], { stdio: ['pipe', 'inherit', 'inherit'] });
+        }
+
+        if (options.interactive && options.colorize) {
+            const colorize = spawn('sed', [
+                // headers
+                '-e', `s/^\\(diff --git .*\\)/${ansi.bold('\\1')}/`,
+                '-e', `s/^\\(index .*\\)/${ansi.bold('\\1')}/`,
+                '-e', `s/^\\(new file mode .*\\)/${ansi.bold('\\1')}/`,
+                '-e', `s/^\\(deleted file mode .*\\)/${ansi.bold('\\1')}/`,
+                '-e', `s/^\\(--- .*\\)/${ansi.bold('\\1')}/`,
+                '-e', `s/^\\(+++ .*\\)/${ansi.bold('\\1')}/`,
+                // additions
+                '-e', `s/^\\(+[^+].*\\)/${ansi.green('\\1')}/`,
+                '-e', `s/^\\(+\\)$/${ansi.green('\\1')}/`,
+                // deletions
+                '-e', `s/^\\(-[^-].*\\)/${ansi.red('\\1')}/`,
+                '-e', `s/^\\(-\\)$/${ansi.red('\\1')}/`,
+                // markers
+                '-e', `s/^\\(@@ -[0-9][0-9]*,[0-9][0-9]* +[0-9][0-9]*,[0-9][0-9]* .*@@\\)/${ansi.blue('\\1')}/`,
+                '-e', `s/^\\(@@ -[0-9][0-9]*,[0-9][0-9]* +[0-9][0-9]* .*@@\\)/${ansi.blue('\\1')}/`,
+                '-e', `s/^\\(@@ -[0-9][0-9]* +[0-9][0-9]*,[0-9][0-9]* .*@@\\)/${ansi.blue('\\1')}/`,
+            ]);
+            ssh.stdout.pipe(colorize.stdin);
+            colorize.stdout.pipe(less.stdin);
+        } else if (options.interactive) {
+            ssh.stdout.pipe(less.stdin);
+        }
+
+        if (options.interactive) {
+            await new Promise((resolve, reject) => {
+                less.on('exit', (code) => {
+                    if (code === 0) {
+                        resolve();
+                    } else {
+                        reject(`exited with code ${code}`);
+                    }
+                });
+            });
+        } else {
+            return await new Promise((resolve, reject) => {
+                let diff = '';
+
+                ssh.stdout.on('data', (data) => diff += data);
+
+                ssh.stderr.pipe(process.stderr);
+
+                ssh.on('exit', (code) => {
+                    resolve(diff);
+                });
+            });
+        }
+    } else if (options.interactive) {
+        console.log(ansi.yellow('No changes detected.'));
+    }
+}

package/src/humanize.js

@@ -0,0 +1,13 @@
+import * as ansi from './ansi.js';
+
+export default function humanize(changes) {
+    return changes
+        .replace(/cL\+\+\+\+\+\+\+\+\+/g,   ansi.blue('New Link   '))
+        .replace(/<f\+\+\+\+\+\+\+\+\+/g,  ansi.green('New File   '))
+        .replace(/>f\+\+\+\+\+\+\+\+\+/g,  ansi.green('New File   '))
+        .replace(/cd\+\+\+\+\+\+\+\+\+/g,  ansi.green('New Folder '))
+        .replace(/<fc..\.\.\.\.\.\./g,    ansi.yellow('Update     '))
+        .replace(/>fc..\.\.\.\.\.\./g,    ansi.yellow('Update     '))
+        .replace(/cLc\.T\.\.\.\.\.\./g,   ansi.yellow('Update     '))
+        .replace(/\*deleting  /g,            ansi.red('Delete     '))
+}

package/src/rsync.js

@@ -0,0 +1,155 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse } from './cli.js';
+import config, { locate as locateConfig } from './config.js';
+import debug from './debug.js';
+
+let backupPath = null;
+
+/**
+ * Generate rsync filters.
+ */
+export function filters() {
+    const { options } = parse(process.argv.slice(2));
+    const filters = [];
+    const includes = [];
+    const excludes = [
+        '.frak*',
+        '.git*',
+        '.svn*',
+        '.tags*',
+        'Capfile',
+        'Gemfile*',
+        'Vagrantfile*',
+    ];
+
+    // merge excludes via commandline
+    if (options.ignore) {
+        excludes.push.apply(excludes, options.ignore.split(/ +/));
+    }
+
+    // merge path
+    if (options.path) {
+        const paths = options.path.split(/ +/)
+            .map(p => path.resolve(p))
+            .map(p => p) // TODO glob // paths.map! { |p| p[/[*?]/] ? Dir.glob(p) : p }
+            .flat(Infinity)
+            // make paths relative to .frak file
+            .map(p => p.replace(path.dirname(locateConfig()), ''));
+
+        // include all parent directories to fix recursive rsync from excluding all
+        paths.forEach(p => {
+            includes.push(p);
+
+            while (path.dirname(p) !== '/') {
+                excludes.push(`${path.dirname(p)}/*`);
+
+                p = path.dirname(p);
+                includes.push(p)
+            }
+        });
+
+        excludes.push('/*');
+    }
+
+    // merge .frakignore file
+    if (fs.existsSync(path.resolve(locateConfig(), '../.frakignore'))) {
+        filters.push('.e .frakignore');
+    }
+
+    includes.forEach(include => filters.push(`+ ${include}`));
+    excludes.forEach(include => filters.push(`- ${include}`));
+
+    return filters;
+}
+
+/**
+ * Execute the entire rsync command. Uses rsync's --files-from
+ * parameter to deploy multiple paths at once.
+ *
+ * @param {String} source
+ * @param {String} destination
+ * @param {Object} options
+ */
+export function exec(...options) {
+    // Get the current command
+    const { command, options: commandOptions } = parse(process.argv.slice(2));
+    let source, destination;
+
+    // Flip the source and destination if this is a pull command
+    if (command === 'pull') {
+        // trailing slashes are important for pull
+        source = `${config['server']}:${config['root']}/`;
+        destination = './';
+    } else {
+        source = './';
+        destination = `${config['server']}:${config['root']}/`;
+    }
+
+    let backup = [];
+    let backupName = 'name' in commandOptions
+        ? `${commandOptions.name}_${(new Date()).toISOString()}`
+        : (new Date()).toISOString();
+
+    // Figure out backup options
+    backup = [
+        '--exclude=.backups/',
+    ];
+
+    // Keep the same backup path for all rsync commands
+    if (backupPath === null) {
+        backupPath = `.backups/${backupName}`
+    }
+
+    // This should only happen on push
+    if (command === 'push') {
+        backup = [...backup, '--backup', `--backup-dir='${backupPath}'`]
+    }
+
+    const args = [
+        'rsync',
+        [
+            '--archive', '--no-group', '--no-owner', '--no-perms', '--no-times', '--human-readable',
+            '--compress', '--checksum', '--itemize-changes', '--recursive', '--delete',
+            `--rsync-path=${config['rsync_path'] ? config['rsync_path'] : 'rsync'}`,
+            '--filter=. -',
+            ...backup,
+            ...options,
+            source, destination,
+        ],
+    ];
+
+    debug('rsync:', args);
+    debug(args.flat().join(' '));
+    debug('filters:', filters());
+
+    let output = '';
+
+    const rsync = spawn.apply(null, args);
+
+    const echo = spawn('echo', [ filters().join('\n') ]);
+
+    echo.stdout.pipe(rsync.stdin);
+
+    rsync.stdout.on('data', (data) => {
+        output += `${data}`;
+    });
+
+    rsync.stderr.on('data', (data) => {
+        process.stderr.write(`${data}`); // Print any errors from the child process
+    });
+
+    return new Promise((resolve, reject) => {
+        rsync.on('exit', (code) => {
+            if (code === 0) {
+                resolve({
+                    output,
+                    backupPath,
+                });
+            } else {
+                reject(`rsync exited with code ${code}`);
+            }
+        });
+    });
+}

package/src/ssh.js

@@ -0,0 +1,44 @@
+import { spawn } from 'node:child_process';
+import debug from './debug.js';
+
+export function exec(command, options = {}) {
+    debug({ command });
+
+    const cmd = `cd ${options.root || '.'}; sh`;
+
+    const ssh = spawn('ssh', [ options.server, '--', cmd ]);
+
+    // const echo = spawn('echo', [ command ]);
+
+    // echo.stdout.pipe(ssh.stdin);
+
+    ssh.stdin.write(command);
+    ssh.stdin.end();
+
+    ssh.stdout.on('data', (data) => {
+        debug('' + data);
+
+        options.quiet || process.stdout.write(`${data}`);
+    });
+
+    ssh.stderr.on('data', (data) => {
+        debug('' + data);
+
+        options.quiet || process.stderr.write(`${data}`);
+    });
+
+    const promise = new Promise((resolve, reject) => {
+        ssh.on('exit', (code) => {
+            if (code === 0) {
+                resolve();
+            } else {
+                reject(`exited with code ${code}`);
+            }
+        });
+    });
+
+    promise.stdout = ssh.stdout;
+    promise.stderr = ssh.stderr;
+
+    return promise;
+}