aethel 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 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

@@ -158,6 +158,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 +234,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.0",
   "description": "Git-style Google Drive sync CLI with interactive TUI",
   "type": "module",
   "license": "MIT",
@@ -59,12 +59,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;
+}

package/src/core/config.js

@@ -5,6 +5,8 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import YAML from "yaml";
+import { createManifest } from "./pack-manifest.js";
 
 export const AETHEL_DIR = ".aethel";
 export const CONFIG_FILE = "config.json";
@@ -12,6 +14,8 @@ export const INDEX_FILE = "index.json";
 export const SNAPSHOTS_DIR = "snapshots";
 export const HISTORY_DIR = "history";
 export const LATEST_SNAPSHOT = "latest.json";
+export const PACK_MANIFEST_FILE = "pack-manifest.json";
+export const PACK_CONFIG_FILE = ".aethelconfig";
 
 /** Walk up from `start` looking for a .aethel/ directory. */
 export function findRoot(start = process.cwd()) {
@@ -135,3 +139,118 @@ export function writeSnapshot(root, snapshot) {
   // Compact JSON — snapshots can be large, pretty-printing is slow + wastes disk
   fs.writeFileSync(latest, JSON.stringify(snapshot) + "\n");
 }
+
+// ── pack config helpers ───────────────────────────────────────────────
+
+const DEFAULT_PACK_CONFIG = {
+  packing: {
+    enabled: false,
+    compression: {
+      default: {
+        algorithm: "zstd",
+        level: 6,
+      },
+      overrides: [],
+    },
+    rules: [],
+  },
+};
+
+/**
+ * Load pack configuration from .aethelconfig (YAML).
+ * Returns default config if file doesn't exist.
+ * @param {string} root - Workspace root
+ * @returns {object} Pack configuration
+ */
+export function loadPackConfig(root) {
+  const p = path.join(root, PACK_CONFIG_FILE);
+  if (!fs.existsSync(p)) {
+    return structuredClone(DEFAULT_PACK_CONFIG);
+  }
+  try {
+    const content = fs.readFileSync(p, "utf-8");
+    const parsed = YAML.parse(content);
+    // Merge with defaults for missing keys
+    return {
+      packing: {
+        ...DEFAULT_PACK_CONFIG.packing,
+        ...parsed?.packing,
+        compression: {
+          ...DEFAULT_PACK_CONFIG.packing.compression,
+          ...parsed?.packing?.compression,
+        },
+      },
+    };
+  } catch {
+    return structuredClone(DEFAULT_PACK_CONFIG);
+  }
+}
+
+/**
+ * Save pack configuration to .aethelconfig.
+ * @param {string} root - Workspace root
+ * @param {object} config - Configuration to save
+ */
+export function savePackConfig(root, config) {
+  const p = path.join(root, PACK_CONFIG_FILE);
+  const content = YAML.stringify(config);
+  fs.writeFileSync(p, content);
+}
+
+/**
+ * Read pack manifest from .aethel/pack-manifest.json.
+ * Returns empty manifest if file doesn't exist.
+ * @param {string} root - Workspace root
+ * @returns {object} Pack manifest
+ */
+export function loadPackManifest(root) {
+  const p = path.join(dot(root), PACK_MANIFEST_FILE);
+  if (!fs.existsSync(p)) {
+    return createManifest();
+  }
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf-8"));
+  } catch {
+    return createManifest();
+  }
+}
+
+/**
+ * Save pack manifest to .aethel/pack-manifest.json.
+ * @param {string} root - Workspace root
+ * @param {object} manifest - Manifest to save
+ */
+export function savePackManifest(root, manifest) {
+  const p = path.join(dot(root), PACK_MANIFEST_FILE);
+  fs.writeFileSync(p, JSON.stringify(manifest, null, 2) + "\n");
+}
+
+/**
+ * Check if packing feature is enabled.
+ * @param {string} root - Workspace root
+ * @returns {boolean}
+ */
+export function isPackingEnabled(root) {
+  const config = loadPackConfig(root);
+  return config.packing?.enabled === true;
+}
+
+/**
+ * Get packing rule for a specific path.
+ * @param {object} packConfig - Pack configuration
+ * @param {string} relativePath - Path to check
+ * @returns {object|null} Matching rule or null
+ */
+export function getPackRule(packConfig, relativePath) {
+  const rules = packConfig.packing?.rules ?? [];
+  const normalized = relativePath.replace(/\\/g, "/").replace(/^\/+/, "").replace(/\/+$/, "");
+
+  for (const rule of rules) {
+    const rulePath = rule.path.replace(/\\/g, "/").replace(/^\/+/, "").replace(/\/+$/, "");
+    if (normalized === rulePath || normalized.startsWith(rulePath + "/")) {
+      return rule;
+    }
+  }
+
+  return null;
+}