aethel 1.0.0 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.2.1 (2026-04-26)
+
+- Document the `verify` integrity-check command in the README help guide.
+- Add `verify` to the TUI command catalog with local and remote verification actions.
+- Fix legacy local-delete staging so remote deletions can resolve Drive file IDs from the latest snapshot.
+- Add a debug installer command that symlinks the working-copy CLI as `debug_aethel`.
+
+## 1.2.0 (2026-04-15)
+
+- Add Packing modules
+
+## 1.1.0 (2026-04-15)
+
+### Added
+- **Directory Packing**: Pack large directories (e.g., `node_modules`) into compressed archives for faster sync
+- Multi-algorithm compression support: gzip, brotli (built-in), zstd, xz (optional)
+- Tree hash algorithm for fast directory fingerprinting (~30x faster than MD5)
+- Pack-aware scanning that skips packed directories
+- Pack change detection: PACK_NEW, PACK_LOCAL_MODIFIED, PACK_REMOTE_MODIFIED, PACK_SYNCED, PACK_CONFLICT
+- `aethel status --verbose` shows synced packs
+- `.aethelconfig` YAML file for packing configuration
+
+### Changed
+- Upgraded ink from 6.8.0 to 7.0.0
+- Upgraded react from 19.2.4 to 19.2.5
+
 ## 1.0.0 (2026-04-06)
 
 - release: 1.0.0

package/README.md

@@ -23,6 +23,7 @@ git clone https://github.com/CCJ-0617/Aethel.git
 cd Aethel
 npm install
 npm run install:cli   # symlinks `aethel` into ~/.local/bin
+npm run install:debug # symlinks `debug_aethel` without replacing `aethel`
 ```
 
 </details>
@@ -85,6 +86,7 @@ aethel commit -m "sync"        # execute staged operations
 aethel pull -m "pull"          # fetch remote changes and apply
 aethel pull --all              # download the full remote tree to local
 aethel push -m "push"          # push local changes to Drive
+aethel verify                  # verify local files against the last snapshot
 ```
 
 `pull` applies remote changes relative to the latest snapshot. Use `pull --all` for the first full download or to rehydrate a local workspace from the current remote tree.
@@ -131,10 +133,20 @@ Processes deepest-first for single-pass convergence, caches child state to minim
 | `restore`        | Restore files from the last snapshot                                |
 | `rm`             | Remove local files and stage remote deletion                        |
 | `mv`             | Move or rename local files                                          |
+| `verify`         | Verify local and optional remote integrity against the last snapshot |
 | `clean`          | List and optionally trash/delete Drive files                        |
 | `dedupe-folders` | Detect and merge duplicate remote folders                           |
 | `tui`            | Launch interactive terminal UI                                      |
 
+### Integrity Verification
+
+```bash
+aethel verify          # check snapshot checksum and local file hashes
+aethel verify --remote # also compare Drive file hashes
+```
+
+`verify` compares the latest snapshot with the workspace on disk and exits non-zero when files are missing or modified. Add `--remote` when you also want to verify Drive state before a release, migration, or restore.
+
 ## TUI
 
 ```bash
@@ -158,6 +170,46 @@ Dual-pane file browser — local filesystem on the left, Google Drive on the rig
 | `f`                | Open the commands page and choose a TUI action     |
 | `:`                | Run any Aethel CLI command inside the TUI          |
 
+## Directory Packing
+
+Large directories with many small files (e.g., `node_modules`, `vendor`) can be slow to sync. Aethel can pack these into compressed archives for faster transfers.
+
+### Enable Packing
+
+Create `.aethelconfig` in your workspace root:
+
+```yaml
+packing:
+  enabled: true
+  compression:
+    default:
+      algorithm: gzip  # gzip, brotli, zstd, xz, or none
+      level: 6
+  rules:
+    - path: node_modules
+      strategy: full
+    - path: vendor
+      strategy: full
+```
+
+### How It Works
+
+1. **Tree Hash**: Directories are fingerprinted using mtime+size (30x faster than MD5)
+2. **Pack Detection**: `aethel status` shows pack states (P+, PL, PR, P=, P!)
+3. **Compression**: Archives use gzip/brotli (built-in) or zstd/xz (if installed)
+
+### Pack Status Codes
+
+| Code | Meaning |
+|------|---------|
+| `P+` | New pack (not yet synced) |
+| `PL` | Pack changed locally |
+| `PR` | Pack changed on Drive |
+| `P=` | Pack up to date |
+| `P!` | Pack conflict |
+
+Use `aethel status --verbose` to show synced packs.
+
 ## Ignore Patterns
 
 Create `.aethelignore` (gitignore syntax) in your workspace root — or run `aethel init` to generate a default one.
@@ -194,10 +246,13 @@ src/
 │   ├── drive-api.js          Google Drive API wrapper
 │   ├── local-fs.js           Local filesystem operations
 │   ├── remote-cache.js       Short-lived remote file cache
-│   ├── snapshot.js            Local scanning & snapshot creation
+│   ├── snapshot.js           Local scanning & snapshot creation
 │   ├── staging.js            Stage/unstage operations
 │   ├── sync.js               Execute staged changes
-│   └── ignore.js             .aethelignore pattern matching
+│   ├── ignore.js             .aethelignore pattern matching
+│   ├── compress.js           Multi-algorithm compression (gzip, brotli, zstd, xz)
+│   ├── pack.js               Tar archive operations & tree hash
+│   └── pack-manifest.js      Pack manifest CRUD operations
 └── tui/
     ├── app.js                React (Ink) dual-pane component
     ├── index.js              TUI entry

package/docs/ARCHITECTURE.md

@@ -45,6 +45,15 @@ The core design is not a live mirror between local storage and Drive. Instead, s
   - Manages `.aethelignore`
 - `src/core/remote-cache.js`
   - Short-lived cache for remote listings
+- `src/core/compress.js`
+  - Multi-algorithm compression (gzip, brotli, zstd, xz)
+  - Compression profiles and algorithm detection
+- `src/core/pack.js`
+  - Tar archive creation and extraction
+  - Tree hash algorithm for fast directory fingerprinting
+- `src/core/pack-manifest.js`
+  - CRUD operations for pack manifest
+  - Tracks packed directories and their sync state
 
 ### 2.3 State Storage Layer
 
@@ -55,16 +64,20 @@ After workspace initialization, the project root contains:
   config.json
   index.json
   .hash-cache.json
+  pack-manifest.json
   snapshots/
     latest.json
     history/
+.aethelconfig
 ```
 
 - `config.json`: sync root configuration
 - `index.json`: currently staged operations
 - `.hash-cache.json`: local file hash cache
+- `pack-manifest.json`: tracks packed directories and their sync state
 - `snapshots/latest.json`: baseline state after the most recent successful sync
 - `snapshots/history/`: archived older snapshots
+- `.aethelconfig` (workspace root): YAML configuration for directory packing
 
 ## 3. Core Data Flow
 
@@ -124,6 +137,7 @@ That means the system does not compare only "local vs remote". It also asks:
 
 `src/core/diff.js` classifies changes as:
 
+**File changes:**
 - `remote_added`
 - `remote_modified`
 - `remote_deleted`
@@ -132,6 +146,13 @@ That means the system does not compare only "local vs remote". It also asks:
 - `local_deleted`
 - `conflict`
 
+**Pack changes (for packed directories):**
+- `pack_new` - directory newly configured for packing
+- `pack_local_modified` - packed directory changed locally
+- `pack_remote_modified` - packed directory changed on Drive
+- `pack_synced` - packed directory up to date
+- `pack_conflict` - both sides changed the packed directory
+
 It also provides default suggested actions for each category:
 
 - Drive added/modified -> `download`
@@ -139,6 +160,9 @@ It also provides default suggested actions for each category:
 - Local added/modified -> `upload`
 - Local deleted -> `delete_remote`
 - Both sides changed the same path -> `conflict`
+- Pack new/local modified -> `push_pack`
+- Pack remote modified -> `pull_pack`
+- Pack conflict -> `resolve_pack`
 
 ### 4.3 Execution Model
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aethel",
-  "version": "1.0.0",
+  "version": "1.2.1",
   "description": "Git-style Google Drive sync CLI with interactive TUI",
   "type": "module",
   "license": "MIT",
@@ -48,6 +48,7 @@
     "auth": "node src/cli.js auth",
     "clean": "node src/cli.js clean",
     "install:cli": "bash scripts/install.sh",
+    "install:debug": "bash scripts/install-debug.sh",
     "release": "bash scripts/release.sh",
     "pack:check": "npm pack --dry-run",
     "prepublishOnly": "npm test && npm run pack:check",
@@ -59,12 +60,14 @@
     "commander": "^14.0.3",
     "googleapis": "^171.4.0",
     "ignore": "^7.0.5",
-    "ink": "^6.8.0",
+    "ink": "^7.0.0",
     "ink-select-input": "^6.0.0",
     "ink-spinner": "^5.0.0",
     "ink-text-input": "^6.0.0",
     "open": "^11.0.0",
-    "react": "^19.2.4"
+    "react": "^19.2.4",
+    "tar": "^7.5.13",
+    "yaml": "^2.8.3"
   },
   "engines": {
     "node": ">=18"

package/src/cli.js

@@ -289,7 +289,9 @@ async function handleStatus(options) {
   const { diff } = await loadStateWithProgress(repo);
   const staged = repo.getStagedEntries();
 
-  if (diff.isClean && staged.length === 0) {
+  const hasPackChanges = diff.hasPackChanges || (options.verbose && diff.syncedPacks?.length > 0);
+
+  if (diff.isClean && staged.length === 0 && !hasPackChanges) {
     console.log("Everything up to date.");
     return;
   }
@@ -326,6 +328,32 @@ async function handleStatus(options) {
       console.log(`  ${change.shortStatus} ${change.path}  (${change.description})`);
     }
   }
+
+  // Display pack changes
+  const pendingPacks = diff.pendingPackChanges || [];
+  const packConflicts = diff.packConflicts || [];
+  const syncedPacks = diff.syncedPacks || [];
+
+  if (pendingPacks.length) {
+    console.log(`\nPack changes (${pendingPacks.length}):`);
+    for (const change of pendingPacks) {
+      console.log(`  ${change.shortStatus} ${change.path}  (${change.description})`);
+    }
+  }
+
+  if (packConflicts.length) {
+    console.log(`\nPack conflicts (${packConflicts.length}):`);
+    for (const change of packConflicts) {
+      console.log(`  ${change.shortStatus} ${change.path}  (${change.description})`);
+    }
+  }
+
+  if (options.verbose && syncedPacks.length) {
+    console.log(`\nSynced packs (${syncedPacks.length}):`);
+    for (const change of syncedPacks) {
+      console.log(`  ${change.shortStatus} ${change.path}  (${change.description})`);
+    }
+  }
 }
 
 async function handleDiff(options) {
@@ -1081,9 +1109,10 @@ async function main() {
       .option("--drive-folder-name <name>", "Display name for the Drive folder")
   ).action(handleInit);
 
-  addAuthOptions(program.command("status").description("Show sync status")).action(
-    handleStatus
-  );
+  addAuthOptions(
+    program.command("status").description("Show sync status")
+      .option("-v, --verbose", "Show all pack states including synced")
+  ).action(handleStatus);
 
   addAuthOptions(
     program

package/src/core/compress.js

@@ -0,0 +1,285 @@
+/**
+ * Multi-algorithm compression/decompression abstraction.
+ * Supports gzip, brotli (built-in), and optionally zstd, xz.
+ */
+
+import zlib from "node:zlib";
+import { pipeline } from "node:stream/promises";
+import fs from "node:fs";
+import path from "node:path";
+
+// Algorithm enumeration
+export const Algorithm = Object.freeze({
+  NONE: "none",
+  GZIP: "gzip",
+  ZSTD: "zstd",
+  BROTLI: "brotli",
+  XZ: "xz",
+});
+
+// File extension mapping
+export const EXTENSIONS = {
+  [Algorithm.NONE]: ".tar",
+  [Algorithm.GZIP]: ".tar.gz",
+  [Algorithm.ZSTD]: ".tar.zst",
+  [Algorithm.BROTLI]: ".tar.br",
+  [Algorithm.XZ]: ".tar.xz",
+};
+
+// Compression profiles for easy configuration
+export const PROFILES = {
+  fast: { algorithm: Algorithm.ZSTD, level: 1 },
+  balanced: { algorithm: Algorithm.ZSTD, level: 6 },
+  maximum: { algorithm: Algorithm.ZSTD, level: 19 },
+  extreme: { algorithm: Algorithm.XZ, level: 6 },
+};
+
+// Cache for optional dependency availability
+const availabilityCache = new Map();
+
+/**
+ * Try to load an optional dependency.
+ * @param {string} moduleName
+ * @returns {Promise<any|null>}
+ */
+async function tryLoadModule(moduleName) {
+  if (availabilityCache.has(moduleName)) {
+    return availabilityCache.get(moduleName);
+  }
+  try {
+    const mod = await import(moduleName);
+    availabilityCache.set(moduleName, mod.default || mod);
+    return availabilityCache.get(moduleName);
+  } catch {
+    availabilityCache.set(moduleName, null);
+    return null;
+  }
+}
+
+/**
+ * Check if an algorithm is available in the current environment.
+ * @param {string} algorithm - Algorithm name from Algorithm enum
+ * @returns {Promise<boolean>}
+ */
+export async function isAlgorithmAvailable(algorithm) {
+  switch (algorithm) {
+    case Algorithm.NONE:
+    case Algorithm.GZIP:
+    case Algorithm.BROTLI:
+      return true; // Built-in Node.js
+    case Algorithm.ZSTD:
+      return (await tryLoadModule("@bokuweb/zstd-wasm")) !== null;
+    case Algorithm.XZ:
+      return (await tryLoadModule("lzma-native")) !== null;
+    default:
+      return false;
+  }
+}
+
+/**
+ * Get the best available algorithm for compression.
+ * Falls back to gzip if preferred is unavailable.
+ * @param {string} preferred - Preferred algorithm
+ * @returns {Promise<string>} Available algorithm
+ */
+export async function resolveAlgorithm(preferred) {
+  if (await isAlgorithmAvailable(preferred)) {
+    return preferred;
+  }
+  // Fallback chain: zstd -> gzip
+  if (preferred !== Algorithm.ZSTD && (await isAlgorithmAvailable(Algorithm.ZSTD))) {
+    return Algorithm.ZSTD;
+  }
+  return Algorithm.GZIP;
+}
+
+/**
+ * Create a compression stream for the given algorithm.
+ * @param {string} algorithm - Algorithm name
+ * @param {{ level?: number }} options - Compression options
+ * @returns {Promise<import("node:stream").Transform>} Compression stream
+ */
+export async function createCompressStream(algorithm, options = {}) {
+  const level = options.level ?? 6;
+
+  switch (algorithm) {
+    case Algorithm.NONE:
+      // Pass-through stream
+      const { PassThrough } = await import("node:stream");
+      return new PassThrough();
+
+    case Algorithm.GZIP:
+      return zlib.createGzip({ level });
+
+    case Algorithm.BROTLI:
+      return zlib.createBrotliCompress({
+        params: {
+          [zlib.constants.BROTLI_PARAM_QUALITY]: Math.min(level, 11),
+        },
+      });
+
+    case Algorithm.ZSTD: {
+      const zstd = await tryLoadModule("@bokuweb/zstd-wasm");
+      if (!zstd) {
+        throw new Error("zstd not available. Install @bokuweb/zstd-wasm");
+      }
+      // zstd-wasm provides compress/decompress functions, not streams
+      // We need to wrap it in a transform stream
+      const { Transform } = await import("node:stream");
+      const chunks = [];
+      return new Transform({
+        transform(chunk, encoding, callback) {
+          chunks.push(chunk);
+          callback();
+        },
+        async flush(callback) {
+          try {
+            const input = Buffer.concat(chunks);
+            const compressed = await zstd.compress(input, level);
+            this.push(Buffer.from(compressed));
+            callback();
+          } catch (err) {
+            callback(err);
+          }
+        },
+      });
+    }
+
+    case Algorithm.XZ: {
+      const lzma = await tryLoadModule("lzma-native");
+      if (!lzma) {
+        throw new Error("xz not available. Install lzma-native");
+      }
+      return lzma.createCompressor({ preset: level });
+    }
+
+    default:
+      throw new Error(`Unknown compression algorithm: ${algorithm}`);
+  }
+}
+
+/**
+ * Create a decompression stream for the given algorithm.
+ * @param {string} algorithm - Algorithm name
+ * @returns {Promise<import("node:stream").Transform>} Decompression stream
+ */
+export async function createDecompressStream(algorithm) {
+  switch (algorithm) {
+    case Algorithm.NONE: {
+      const { PassThrough } = await import("node:stream");
+      return new PassThrough();
+    }
+
+    case Algorithm.GZIP:
+      return zlib.createGunzip();
+
+    case Algorithm.BROTLI:
+      return zlib.createBrotliDecompress();
+
+    case Algorithm.ZSTD: {
+      const zstd = await tryLoadModule("@bokuweb/zstd-wasm");
+      if (!zstd) {
+        throw new Error("zstd not available. Install @bokuweb/zstd-wasm");
+      }
+      const { Transform } = await import("node:stream");
+      const chunks = [];
+      return new Transform({
+        transform(chunk, encoding, callback) {
+          chunks.push(chunk);
+          callback();
+        },
+        async flush(callback) {
+          try {
+            const input = Buffer.concat(chunks);
+            const decompressed = await zstd.decompress(input);
+            this.push(Buffer.from(decompressed));
+            callback();
+          } catch (err) {
+            callback(err);
+          }
+        },
+      });
+    }
+
+    case Algorithm.XZ: {
+      const lzma = await tryLoadModule("lzma-native");
+      if (!lzma) {
+        throw new Error("xz not available. Install lzma-native");
+      }
+      return lzma.createDecompressor();
+    }
+
+    default:
+      throw new Error(`Unknown decompression algorithm: ${algorithm}`);
+  }
+}
+
+/**
+ * Compress a file to destination.
+ * @param {string} inputPath - Source file path
+ * @param {string} outputPath - Destination file path
+ * @param {{ algorithm?: string, level?: number }} options
+ * @returns {Promise<{ originalSize: number, compressedSize: number, ratio: number }>}
+ */
+export async function compressFile(inputPath, outputPath, options = {}) {
+  const algorithm = options.algorithm ?? Algorithm.GZIP;
+  const level = options.level ?? 6;
+
+  const inputStat = fs.statSync(inputPath);
+  const originalSize = inputStat.size;
+
+  const readStream = fs.createReadStream(inputPath);
+  const writeStream = fs.createWriteStream(outputPath);
+  const compressStream = await createCompressStream(algorithm, { level });
+
+  await pipeline(readStream, compressStream, writeStream);
+
+  const outputStat = fs.statSync(outputPath);
+  const compressedSize = outputStat.size;
+  const ratio = originalSize > 0 ? 1 - compressedSize / originalSize : 0;
+
+  return { originalSize, compressedSize, ratio };
+}
+
+/**
+ * Decompress a file to destination.
+ * @param {string} inputPath - Compressed file path
+ * @param {string} outputPath - Destination file path
+ * @param {string} algorithm - Algorithm used for compression
+ * @returns {Promise<void>}
+ */
+export async function decompressFile(inputPath, outputPath, algorithm) {
+  const readStream = fs.createReadStream(inputPath);
+  const writeStream = fs.createWriteStream(outputPath);
+  const decompressStream = await createDecompressStream(algorithm);
+
+  await pipeline(readStream, decompressStream, writeStream);
+}
+
+/**
+ * Detect algorithm from file extension.
+ * @param {string} filePath - File path with extension
+ * @returns {string|null} Algorithm name or null if unknown
+ */
+export function detectAlgorithm(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const fullExt = filePath.toLowerCase();
+
+  if (fullExt.endsWith(".tar.gz") || fullExt.endsWith(".tgz")) {
+    return Algorithm.GZIP;
+  }
+  if (fullExt.endsWith(".tar.zst")) {
+    return Algorithm.ZSTD;
+  }
+  if (fullExt.endsWith(".tar.br")) {
+    return Algorithm.BROTLI;
+  }
+  if (fullExt.endsWith(".tar.xz")) {
+    return Algorithm.XZ;
+  }
+  if (ext === ".tar") {
+    return Algorithm.NONE;
+  }
+
+  return null;
+}