aethel 0.3.7 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.4.0 (2026-04-06)
+
+- Add pull --all for full remote download
+
+## 0.3.8 (2026-04-06)
+
+- Fix Drive upload checksum test stub
+
 ## 0.3.7 (2026-04-05)
 
 - Fix orphan checker not recognizing My Drive root — all files under synced folders were silently dropped

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Aethel Contributors
+Copyright (c) 2026 Aethel Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -78,6 +78,7 @@ aethel add --all               # stage default suggested actions
 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
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aethel",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "description": "Git-style Google Drive sync CLI with interactive TUI",
   "type": "module",
   "license": "MIT",

package/src/cli.js

@@ -97,6 +97,15 @@ async function loadStateWithProgress(repo, opts) {
   }
 }
 
+function assertInsideRoot(root, targetPath) {
+  const abs = path.resolve(root, targetPath);
+  const resolvedRoot = path.resolve(root);
+  if (!abs.startsWith(resolvedRoot + path.sep) && abs !== resolvedRoot) {
+    throw new Error(`Path traversal blocked: '${targetPath}' resolves outside workspace`);
+  }
+  return abs;
+}
+
 function matchesPattern(targetPath, pattern) {
   if (targetPath === pattern) {
     return true;
@@ -504,6 +513,37 @@ async function handlePull(paths, options) {
   const repo = await openRepo(options);
   const { diff, remoteState } = await loadStateWithProgress(repo, { useCache: false });
 
+  if (options.all) {
+    let remoteFiles = remoteState.files;
+
+    if (paths && paths.length > 0) {
+      remoteFiles = remoteFiles.filter((file) =>
+        paths.some((p) => matchesPattern(file.path, p))
+      );
+    }
+
+    if (!remoteFiles.length) {
+      console.log("No remote files matched.");
+      return;
+    }
+
+    if (options.dryRun) {
+      console.log(`Would pull ${remoteFiles.length} remote item(s):`);
+      for (const file of remoteFiles) {
+        console.log(`  +R ${file.path}  (full remote download)`);
+      }
+      return;
+    }
+
+    const count = repo.stageRemoteFilesForDownload(remoteFiles);
+    console.log(`Staged ${count} remote item(s). Committing...`);
+    await handleCommit({ ...options, message: options.message || "pull" }, {
+      repo,
+      snapshotHint: { remote: remoteState },
+    });
+    return;
+  }
+
   let remoteChanges = diff.changes.filter((change) =>
     [
       ChangeType.REMOTE_ADDED,
@@ -783,7 +823,7 @@ async function handleRestore(paths, options) {
       continue;
     }
 
-    const localDest = path.join(root, entry.localPath || entry.path);
+    const localDest = assertInsideRoot(root, entry.localPath || entry.path);
     const spinner = createSpinner(`Restoring ${targetPath}...`);
 
     try {
@@ -807,7 +847,7 @@ async function handleRm(paths, options) {
   const root = repo.root;
 
   for (const targetPath of paths) {
-    const localAbs = path.join(root, targetPath);
+    const localAbs = assertInsideRoot(root, targetPath);
     if (fs.existsSync(localAbs)) {
       await fs.promises.rm(localAbs, { recursive: true });
       console.log(`  Deleted locally: ${targetPath}`);
@@ -833,8 +873,8 @@ async function handleRm(paths, options) {
 async function handleMv(source, dest, options) {
   const root = requireRoot();
 
-  const srcAbs = path.join(root, source);
-  const destAbs = path.join(root, dest);
+  const srcAbs = assertInsideRoot(root, source);
+  const destAbs = assertInsideRoot(root, dest);
 
   if (!fs.existsSync(srcAbs)) {
     console.log(`Source not found: ${source}`);
@@ -848,6 +888,77 @@ async function handleMv(source, dest, options) {
   console.log("  Run 'aethel status' to see the resulting changes (old path deleted, new path added).");
 }
 
+async function handleVerify(options) {
+  const checkRemote = Boolean(options.remote);
+  const repo = checkRemote
+    ? await openRepo(options)
+    : (() => { const root = requireRoot(); return new Repository(root); })();
+
+  const snapshot = repo.getSnapshot();
+  if (!snapshot) {
+    console.log("No snapshot to verify. Run 'aethel commit' first.");
+    return;
+  }
+
+  const localCount = Object.keys(snapshot.localFiles || {}).filter(
+    (k) => !snapshot.localFiles[k].isFolder
+  ).length;
+  const remoteCount = checkRemote ? Object.keys(snapshot.files || {}).length : 0;
+  const total = localCount + remoteCount;
+
+  const bar = createProgressBar("Verifying", total);
+  const result = await repo.verify({
+    checkRemote,
+    onProgress(done) { bar.update(done); },
+  });
+
+  // Snapshot integrity
+  if (result.snapshot.valid) {
+    bar.done(`Verification complete`);
+    console.log(`\n  Snapshot: ✔ ${result.snapshot.reason}`);
+  } else {
+    bar.done(`Verification found issues`);
+    console.log(`\n  Snapshot: ✖ ${result.snapshot.reason}`);
+  }
+
+  // Local issues
+  if (result.local.length) {
+    console.log(`\n  Local issues (${result.local.length}):`);
+    for (const e of result.local) {
+      if (e.status === "missing") {
+        console.log(`    ✖ ${e.path}  — file missing`);
+      } else if (e.status === "modified") {
+        console.log(`    ✖ ${e.path}  — md5 mismatch (expected ${e.expected.slice(0, 8)}, got ${e.actual.slice(0, 8)})`);
+      }
+    }
+  } else {
+    console.log(`  Local files: ✔ ${localCount} file(s) verified`);
+  }
+
+  // Remote issues
+  if (checkRemote) {
+    if (result.remote.length) {
+      console.log(`\n  Remote issues (${result.remote.length}):`);
+      for (const e of result.remote) {
+        if (e.status === "deleted_remote") {
+          console.log(`    ✖ ${e.path}  — deleted on Drive`);
+        } else if (e.status === "modified_remote") {
+          console.log(`    ✖ ${e.path}  — md5 mismatch (expected ${e.expected.slice(0, 8)}, got ${e.actual.slice(0, 8)})`);
+        }
+      }
+    } else {
+      console.log(`  Remote files: ✔ ${remoteCount} file(s) verified`);
+    }
+  }
+
+  if (result.ok) {
+    console.log("\n✔ All integrity checks passed.");
+  } else {
+    console.log("\n✖ Integrity issues detected. Run 'aethel status' to review.");
+    process.exitCode = 1;
+  }
+}
+
 async function handleTui(options) {
   const repo = await openRepo(options, { requireWorkspace: false, silent: true });
   const cliArgs = [];
@@ -1020,6 +1131,7 @@ async function main() {
       .command("pull")
       .description("Download remote changes")
       .argument("[paths...]", "Specific paths to pull (default: all)")
+      .option("--all", "Download all remote files regardless of snapshot state")
       .option("-m, --message <message>", "Commit message")
       .option("--force", "Force-pull conflicts (remote wins)")
       .option("--dry-run", "Preview changes without applying")
@@ -1080,6 +1192,13 @@ async function main() {
     .argument("<dest>", "Destination path (relative to workspace)")
     .action((source, dest, options) => handleMv(source, dest, options));
 
+  addAuthOptions(
+    program
+      .command("verify")
+      .description("Verify file integrity against last snapshot")
+      .option("--remote", "Also verify remote files on Drive (requires network)")
+  ).action(handleVerify);
+
   addAuthOptions(
     program
       .command("tui")

package/src/core/auth.js

@@ -40,8 +40,9 @@ export async function persistCredentials(sourcePath) {
   const resolved = path.resolve(sourcePath);
   if (resolved === dest) return;
   if (fsSyncFallback.existsSync(dest)) return;
-  await fs.mkdir(CONFIG_DIR, { recursive: true });
+  await fs.mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
   await fs.copyFile(resolved, dest);
+  await fs.chmod(dest, 0o600);
 }
 
 export function resolveCredentialsPath(customPath) {
@@ -109,8 +110,8 @@ function createOAuthClient(config, redirectUri) {
 }
 
 async function persistToken(tokenPath, credentials) {
-  await fs.mkdir(path.dirname(path.resolve(tokenPath)), { recursive: true });
-  await fs.writeFile(tokenPath, JSON.stringify(credentials, null, 2) + "\n");
+  await fs.mkdir(path.dirname(path.resolve(tokenPath)), { recursive: true, mode: 0o700 });
+  await fs.writeFile(tokenPath, JSON.stringify(credentials, null, 2) + "\n", { mode: 0o600 });
 }
 
 function attachTokenPersistence(client, tokenPath) {

package/src/core/config.js

@@ -2,6 +2,7 @@
  * .aethel/ directory management, configuration, and state persistence.
  */
 
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 
@@ -97,10 +98,28 @@ export function latestSnapshotPath(root) {
   return path.join(dot(root), SNAPSHOTS_DIR, LATEST_SNAPSHOT);
 }
 
-export function readLatestSnapshot(root) {
+export function readLatestSnapshot(root, { verify = false } = {}) {
   const p = latestSnapshotPath(root);
   if (!fs.existsSync(p)) return null;
-  return JSON.parse(fs.readFileSync(p, "utf-8"));
+  const snapshot = JSON.parse(fs.readFileSync(p, "utf-8"));
+
+  if (verify && snapshot._checksum) {
+    const canonical = JSON.stringify({
+      timestamp: snapshot.timestamp,
+      message: snapshot.message,
+      files: snapshot.files,
+      localFiles: snapshot.localFiles,
+    });
+    const actual = crypto.createHash("sha256").update(canonical).digest("hex");
+    if (actual !== snapshot._checksum) {
+      throw new Error(
+        `Snapshot integrity check failed: checksum mismatch. ` +
+        `The snapshot file may have been tampered with.`
+      );
+    }
+  }
+
+  return snapshot;
 }
 
 export function writeSnapshot(root, snapshot) {

package/src/core/drive-api.js

@@ -111,7 +111,12 @@ export function isWorkspaceType(mime) {
 }
 
 function escapeDriveQueryValue(value) {
-  return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+  // Google Drive API query strings use single-quoted values.
+  // Escape backslashes first, then single quotes.
+  return value
+    .replace(/\\/g, "\\\\")
+    .replace(/'/g, "\\'")
+    .replace(/"/g, '\\"');
 }
 
 export function iconForMime(mime) {
@@ -504,14 +509,36 @@ export async function downloadFile(drive, fileMeta, localPath) {
       { responseType: "stream" }
     );
     await pipeline(response.data, fs.createWriteStream(targetPath));
+    // Exported files have no md5Checksum from Drive — skip verification
     return;
   }
 
+  // Stream to disk while computing MD5 in parallel
+  const { createHash } = await import("node:crypto");
+  const md5 = createHash("md5");
+  const writeStream = fs.createWriteStream(localPath);
   const response = await drive.files.get(
     { fileId: fileMeta.id, alt: "media", supportsAllDrives: true },
     { responseType: "stream" }
   );
-  await pipeline(response.data, fs.createWriteStream(localPath));
+
+  // Tee: pipe to both disk and hasher
+  response.data.on("data", (chunk) => md5.update(chunk));
+  await pipeline(response.data, writeStream);
+
+  // Verify integrity if Drive provided an md5
+  const expectedMd5 = fileMeta.md5Checksum;
+  if (expectedMd5) {
+    const actualMd5 = md5.digest("hex");
+    if (actualMd5 !== expectedMd5) {
+      // Remove corrupt file
+      fs.unlinkSync(localPath);
+      throw new Error(
+        `Integrity check failed for ${fileMeta.name}: ` +
+        `expected md5 ${expectedMd5}, got ${actualMd5}`
+      );
+    }
+  }
 }
 
 export async function uploadFile(

package/src/core/repository.js

@@ -36,11 +36,18 @@ import {
   readRemoteCache,
   writeRemoteCache,
 } from "./remote-cache.js";
-import { buildSnapshot, scanLocal } from "./snapshot.js";
+import {
+  buildSnapshot,
+  hashFile,
+  md5Local,
+  scanLocal,
+  verifySnapshotChecksum,
+} from "./snapshot.js";
 import {
   stageChange,
   stageChanges,
   stageConflictResolution,
+  stageRemoteFilesForDownload,
   stagedEntries,
   unstageAll,
   unstagePath,
@@ -184,6 +191,10 @@ export class Repository {
     return stageChanges(this._root, changes);
   }
 
+  stageRemoteFilesForDownload(remoteFiles) {
+    return stageRemoteFilesForDownload(this._root, remoteFiles);
+  }
+
   unstagePath(targetPath) {
     return unstagePath(this._root, targetPath);
   }
@@ -329,6 +340,87 @@ export class Repository {
     return JSON.parse(fs.readFileSync(path.join(historyPath, match), "utf-8"));
   }
 
+  // ── Integrity verification ──────────────────────────────────────────
+
+  /**
+   * Full integrity verification of the workspace.
+   * Checks: snapshot checksum, local files vs snapshot md5, remote vs snapshot md5.
+   *
+   * @param {object} [options]
+   * @param {boolean} [options.checkRemote=false]  Also verify remote checksums (requires connect)
+   * @param {function} [options.onProgress]         (done, total, path, status) callback
+   * @returns {{ ok: boolean, snapshot: object, local: object[], remote: object[] }}
+   */
+  async verify({ checkRemote = false, onProgress } = {}) {
+    const snapshot = readLatestSnapshot(this._root, { verify: true });
+    const result = { ok: true, snapshot: { valid: true }, local: [], remote: [] };
+
+    if (!snapshot) {
+      return { ok: true, snapshot: { valid: true, reason: "no snapshot yet" }, local: [], remote: [] };
+    }
+
+    // 1. Snapshot integrity
+    const snapshotCheck = verifySnapshotChecksum(snapshot);
+    result.snapshot = snapshotCheck;
+    if (!snapshotCheck.valid) result.ok = false;
+
+    // 2. Local file integrity vs snapshot
+    const localFiles = snapshot.localFiles || {};
+    const entries = Object.entries(localFiles).filter(([, meta]) => !meta.isFolder);
+    const total = entries.length + (checkRemote ? Object.keys(snapshot.files || {}).length : 0);
+    let done = 0;
+
+    for (const [relativePath, meta] of entries) {
+      const absPath = path.join(this._root, ...relativePath.split("/"));
+      const entry = { path: relativePath, status: "ok" };
+
+      if (!fs.existsSync(absPath)) {
+        entry.status = "missing";
+        result.ok = false;
+      } else if (meta.md5) {
+        const actual = await md5Local(absPath);
+        if (actual !== meta.md5) {
+          entry.status = "modified";
+          entry.expected = meta.md5;
+          entry.actual = actual;
+          result.ok = false;
+        }
+      }
+
+      if (entry.status !== "ok") result.local.push(entry);
+      done++;
+      onProgress?.(done, total, relativePath, entry.status);
+    }
+
+    // 3. Remote integrity vs snapshot (optional, requires API call)
+    if (checkRemote) {
+      const remoteState = await this._loadRemoteState({ useCache: false });
+      const remoteById = new Map(remoteState.files.map((f) => [f.id, f]));
+
+      for (const [fileId, snapEntry] of Object.entries(snapshot.files || {})) {
+        if (snapEntry.isFolder) { done++; continue; }
+        const entry = { path: snapEntry.path || snapEntry.localPath, status: "ok" };
+        const remote = remoteById.get(fileId);
+
+        if (!remote) {
+          entry.status = "deleted_remote";
+          result.ok = false;
+        } else if (snapEntry.md5Checksum && remote.md5Checksum && snapEntry.md5Checksum !== remote.md5Checksum) {
+          entry.status = "modified_remote";
+          entry.expected = snapEntry.md5Checksum;
+          entry.actual = remote.md5Checksum;
+          result.ok = false;
+        }
+
+        if (entry.status !== "ok") result.remote.push(entry);
+        done++;
+        onProgress?.(done, total, entry.path, entry.status);
+      }
+    }
+
+    return result;
+  }
+
   // ── Private helpers ─────────────────────────────────────────────────
 
   async _loadRemoteState({ useCache = true } = {}) {

package/src/core/snapshot.js

@@ -17,6 +17,48 @@ export async function md5Local(filePath) {
   });
 }
 
+/**
+ * Stream-hash a file with the given algorithm (default sha256).
+ * Returns hex digest.
+ */
+export async function hashFile(filePath, algorithm = "sha256") {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash(algorithm);
+    const stream = fs.createReadStream(filePath);
+
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("error", reject);
+    stream.on("end", () => resolve(hash.digest("hex")));
+  });
+}
+
+/**
+ * Compute a SHA-256 integrity checksum over the snapshot's data fields.
+ * The checksum covers files + localFiles + message + timestamp, but NOT
+ * the checksum field itself, so it can be verified after reading.
+ */
+export function computeSnapshotChecksum(snapshot) {
+  const canonical = JSON.stringify({
+    timestamp: snapshot.timestamp,
+    message: snapshot.message,
+    files: snapshot.files,
+    localFiles: snapshot.localFiles,
+  });
+  return crypto.createHash("sha256").update(canonical).digest("hex");
+}
+
+/**
+ * Verify a snapshot's embedded checksum.  Returns true if valid or
+ * if the snapshot has no checksum (pre-integrity snapshots).
+ */
+export function verifySnapshotChecksum(snapshot) {
+  if (!snapshot?._checksum) return { valid: true, reason: "no checksum (legacy snapshot)" };
+  const expected = snapshot._checksum;
+  const actual = computeSnapshotChecksum(snapshot);
+  if (actual === expected) return { valid: true, reason: "checksum valid" };
+  return { valid: false, reason: `checksum mismatch: expected ${expected.slice(0, 12)}…, got ${actual.slice(0, 12)}…` };
+}
+
 // ── Hash cache ───────────────────────────────────────────────────────
 
 function hashCachePath(root) {
@@ -227,10 +269,14 @@ export function buildSnapshot(remoteFiles, localFiles, message = "") {
     };
   }
 
-  return {
+  const snapshot = {
     timestamp: new Date().toISOString(),
     message,
     files,
     localFiles: { ...localFiles },
   };
+
+  // Embed integrity checksum
+  snapshot._checksum = computeSnapshotChecksum(snapshot);
+  return snapshot;
 }

package/src/core/staging.js

@@ -50,6 +50,26 @@ export function stageChanges(root, changes) {
   return changes.length;
 }
 
+export function stageRemoteFilesForDownload(root, remoteFiles) {
+  const index = readIndex(root);
+  const byPath = new Map((index.staged || []).map((entry) => [entry.path, entry]));
+
+  for (const remoteFile of remoteFiles) {
+    byPath.set(remoteFile.path, {
+      action: "download",
+      path: remoteFile.path,
+      localPath: remoteFile.path,
+      fileId: remoteFile.id,
+      remotePath: remoteFile.path,
+      ...(remoteFile.isFolder ? { isFolder: true } : {}),
+    });
+  }
+
+  index.staged = [...byPath.values()];
+  writeIndex(root, index);
+  return remoteFiles.length;
+}
+
 export function unstagePath(root, targetPath) {
   const index = readIndex(root);
   const staged = index.staged || [];

package/src/core/sync.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { readConfig, readIndex, writeIndex } from "./config.js";
 import { downloadFile, ensureFolder, trashFile, uploadFile } from "./drive-api.js";
+import { md5Local } from "./snapshot.js";
 
 function readPositiveIntEnv(name, fallback) {
   const rawValue = Number.parseInt(process.env[name] || "", 10);
@@ -11,7 +12,12 @@ function readPositiveIntEnv(name, fallback) {
 const CONCURRENCY = readPositiveIntEnv("AETHEL_DRIVE_CONCURRENCY", 10);
 
 function toLocalAbsolutePath(root, relativePath) {
-  return path.join(root, ...relativePath.split("/"));
+  const abs = path.resolve(root, ...relativePath.split("/"));
+  const resolvedRoot = path.resolve(root);
+  if (!abs.startsWith(resolvedRoot + path.sep) && abs !== resolvedRoot) {
+    throw new Error(`Path traversal blocked: ${relativePath} resolves outside workspace`);
+  }
+  return abs;
 }
 
 export class CommitResult {
@@ -102,10 +108,22 @@ async function uploadStagedFile(drive, entry, root, driveFolderId) {
     parentId = await ensureFolder(drive, parentPath, driveFolderId);
   }
 
-  await uploadFile(drive, localAbsolutePath, remotePath, {
+  const uploadResult = await uploadFile(drive, localAbsolutePath, remotePath, {
     parentId,
     existingId: entry.fileId || null,
   });
+
+  // Verify: Drive-returned md5 must match the local file we just uploaded.
+  // Google Workspace files (Docs, Sheets, etc.) don't have md5 — skip them.
+  if (uploadResult?.md5Checksum) {
+    const localMd5 = await md5Local(localAbsolutePath);
+    if (localMd5 !== uploadResult.md5Checksum) {
+      throw new Error(
+        `Upload integrity check failed for ${remotePath}: ` +
+        `local md5 ${localMd5}, Drive returned ${uploadResult.md5Checksum}`
+      );
+    }
+  }
 }
 
 async function deleteLocalFile(entry, root) {
@@ -194,6 +212,7 @@ export async function executeStaged(drive, root, progress) {
   // Remote operations (download, upload, delete_remote) share a concurrency pool.
   const localDeletes = [];
   const remoteOps = [];
+  const failedPaths = new Set();
 
   for (const [i, entry] of staged.entries()) {
     if (entry.action === "delete_local") {
@@ -210,6 +229,7 @@ export async function executeStaged(drive, root, progress) {
         await deleteLocalFile(entry, root);
         result.deletedLocal++;
       } catch (err) {
+        failedPaths.add(entry.path);
         result.errors.push(`delete_local ${entry.path}: ${err.message}`);
       }
     })
@@ -242,13 +262,20 @@ export async function executeStaged(drive, root, progress) {
     completed++;
     const op = remoteOps[idx];
     if (err) {
+      failedPaths.add(op.entry.path);
       result.errors.push(`${op.entry.action} ${op.entry.path}: ${err.message}`);
     }
     progress?.(completed - 1, staged.length, op.entry.action, path.posix.basename(op.entry.path || ""));
   });
 
   progress?.(staged.length, staged.length, "done", "");
-  index.staged = [];
+
+  // Only clear succeeded entries — keep failed ones staged for retry
+  if (failedPaths.size > 0) {
+    index.staged = staged.filter((e) => failedPaths.has(e.path));
+  } else {
+    index.staged = [];
+  }
   writeIndex(root, index);
 
   return result;