aethel 0.4.0 → 1.2.0

package/scripts/demo.js

@@ -0,0 +1,416 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { fileURLToPath } from "node:url";
+import { initWorkspace } from "../src/core/config.js";
+import { ensureFolder, resetFolderLookupCache } from "../src/core/drive-api.js";
+import { Repository } from "../src/core/repository.js";
+
+const FOLDER_MIME = "application/vnd.google-apps.folder";
+
+function md5(buffer) {
+  return createHash("md5").update(buffer).digest("hex");
+}
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function folder(id, name, parentId, createdTime) {
+  return {
+    id,
+    name,
+    mimeType: FOLDER_MIME,
+    parents: parentId ? [parentId] : [],
+    createdTime,
+    modifiedTime: createdTime,
+    md5Checksum: null,
+    size: null,
+    trashed: false,
+  };
+}
+
+function file(id, name, parentId, createdTime, content) {
+  const body = Buffer.from(content);
+  return {
+    id,
+    name,
+    mimeType: "application/octet-stream",
+    parents: [parentId],
+    createdTime,
+    modifiedTime: createdTime,
+    md5Checksum: md5(body),
+    size: body.length,
+    trashed: false,
+    body,
+  };
+}
+
+function createFakeDrive(initialItems = []) {
+  const items = new Map();
+  const contentById = new Map();
+  let sequence = 0;
+  let idCounter = 1000;
+
+  for (const item of initialItems) {
+    const next = clone(item);
+    delete next.body;
+    items.set(next.id, next);
+    if (item.body) {
+      contentById.set(next.id, Buffer.from(item.body));
+    }
+  }
+
+  function decodeQueryValue(value) {
+    return value.replace(/\\\\/g, "\\").replace(/\\'/g, "'");
+  }
+
+  function matches(item, query) {
+    if (!query) {
+      return true;
+    }
+
+    return query.split(" and ").every((part) => {
+      if (part === "trashed = false") {
+        return !item.trashed;
+      }
+
+      const nameMatch = part.match(/^name = '(.+)'$/);
+      if (nameMatch) {
+        return item.name === decodeQueryValue(nameMatch[1]);
+      }
+
+      const mimeMatch = part.match(/^mimeType = '(.+)'$/);
+      if (mimeMatch) {
+        return item.mimeType === decodeQueryValue(mimeMatch[1]);
+      }
+
+      const parentMatch = part.match(/^'(.+)' in parents$/);
+      if (parentMatch) {
+        return (item.parents || []).includes(parentMatch[1]);
+      }
+
+      return true;
+    });
+  }
+
+  async function drain(stream) {
+    if (!stream) {
+      return Buffer.alloc(0);
+    }
+
+    const chunks = [];
+    for await (const chunk of stream) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+  }
+
+  function touch(item) {
+    item.modifiedTime = new Date(1710000000000 + sequence++).toISOString();
+  }
+
+  return {
+    files: {
+      async list({ q, pageSize = 1000, pageToken, orderBy }) {
+        const matchesQuery = [...items.values()].filter((item) => matches(item, q));
+        matchesQuery.sort((left, right) => {
+          if (orderBy === "createdTime desc") {
+            return Date.parse(right.createdTime) - Date.parse(left.createdTime);
+          }
+          return String(left.id).localeCompare(String(right.id));
+        });
+
+        const start = Number(pageToken || 0);
+        const slice = matchesQuery.slice(start, start + pageSize).map(clone);
+        const nextPageToken =
+          start + pageSize < matchesQuery.length ? String(start + pageSize) : undefined;
+
+        return {
+          data: {
+            files: slice,
+            nextPageToken,
+          },
+        };
+      },
+      async create({ requestBody, media }) {
+        const body = await drain(media?.body);
+        const id = `id-${++idCounter}`;
+        const createdTime = new Date(1710000000000 + sequence++).toISOString();
+        const item = {
+          id,
+          name: requestBody.name,
+          mimeType: requestBody.mimeType || "application/octet-stream",
+          parents: requestBody.parents || [],
+          createdTime,
+          modifiedTime: createdTime,
+          md5Checksum: requestBody.mimeType === FOLDER_MIME ? null : md5(body),
+          size: requestBody.mimeType === FOLDER_MIME ? null : body.length,
+          trashed: false,
+        };
+        items.set(id, item);
+        if (item.mimeType !== FOLDER_MIME) {
+          contentById.set(id, body);
+        }
+        return { data: clone(item) };
+      },
+      async update({ fileId, requestBody = {}, addParents, removeParents, media }) {
+        const body = await drain(media?.body);
+        const item = items.get(fileId);
+
+        if (!item) {
+          throw new Error(`Missing file: ${fileId}`);
+        }
+
+        if (requestBody.name) {
+          item.name = requestBody.name;
+        }
+
+        if (Object.hasOwn(requestBody, "trashed")) {
+          item.trashed = Boolean(requestBody.trashed);
+        }
+
+        if (addParents || removeParents) {
+          const nextParents = new Set(item.parents || []);
+          for (const parentId of String(removeParents || "").split(",").filter(Boolean)) {
+            nextParents.delete(parentId);
+          }
+          if (addParents) {
+            nextParents.add(addParents);
+          }
+          item.parents = [...nextParents];
+        }
+
+        if (body.length && item.mimeType !== FOLDER_MIME) {
+          item.md5Checksum = md5(body);
+          item.size = body.length;
+          contentById.set(fileId, body);
+        }
+
+        touch(item);
+        return { data: clone(item) };
+      },
+      async delete({ fileId }) {
+        items.delete(fileId);
+        contentById.delete(fileId);
+        return { data: {} };
+      },
+      async get({ fileId, alt }) {
+        if (fileId === "root") {
+          return {
+            data: {
+              id: "root",
+              name: "My Drive",
+              mimeType: FOLDER_MIME,
+              parents: [],
+              createdTime: "2026-01-01T00:00:00.000Z",
+            },
+          };
+        }
+
+        const item = items.get(fileId);
+        if (!item) {
+          throw new Error(`Missing file: ${fileId}`);
+        }
+
+        if (alt === "media") {
+          return {
+            data: Readable.from([contentById.get(fileId) || Buffer.alloc(0)]),
+          };
+        }
+
+        return { data: clone(item) };
+      },
+    },
+  };
+}
+
+function writeLocal(root, relativePath, content) {
+  const absolutePath = path.join(root, relativePath);
+  fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+  fs.writeFileSync(absolutePath, content);
+}
+
+function formatStatus(diff, staged) {
+  const lines = [];
+
+  if (diff.isClean && staged.length === 0) {
+    lines.push("Everything up to date.");
+    return lines;
+  }
+
+  if (staged.length) {
+    lines.push(`Staged changes (${staged.length}):`);
+    for (const entry of staged) {
+      lines.push(`  ${entry.action.padStart(15, " ")}  ${entry.path}`);
+    }
+  }
+
+  const stagedPaths = new Set(staged.map((e) => e.path));
+  const unstagedRemote = diff.remoteChanges.filter((c) => !stagedPaths.has(c.path));
+  const unstagedLocal = diff.localChanges.filter((c) => !stagedPaths.has(c.path));
+  const unstagedConflicts = diff.conflicts.filter((c) => !stagedPaths.has(c.path));
+
+  if (unstagedRemote.length) {
+    lines.push(`Remote changes (${unstagedRemote.length}):`);
+    for (const change of unstagedRemote) {
+      lines.push(`  ${change.shortStatus} ${change.path}  (${change.description})`);
+    }
+  }
+
+  if (unstagedLocal.length) {
+    lines.push(`Local changes (${unstagedLocal.length}):`);
+    for (const change of unstagedLocal) {
+      lines.push(`  ${change.shortStatus} ${change.path}  (${change.description})`);
+    }
+  }
+
+  if (unstagedConflicts.length) {
+    lines.push(`Conflicts (${unstagedConflicts.length}):`);
+    for (const change of unstagedConflicts) {
+      lines.push(`  ${change.shortStatus} ${change.path}  (${change.description})`);
+    }
+  }
+
+  return lines;
+}
+
+function formatDiff(diff) {
+  if (diff.isClean) {
+    return ["No changes detected."];
+  }
+
+  const lines = [];
+  const sections = [
+    ["Remote changes", diff.remoteChanges],
+    ["Local changes", diff.localChanges],
+    ["Conflicts", diff.conflicts],
+  ];
+
+  for (const [title, changes] of sections) {
+    if (!changes.length) {
+      continue;
+    }
+
+    lines.push(`${title}:`);
+    for (const change of changes) {
+      lines.push(`  ${change.shortStatus} ${change.path}`);
+      lines.push(`       ${change.description}`);
+    }
+  }
+
+  return lines;
+}
+
+async function commit(repo, message, snapshotHint) {
+  const result = await repo.executeStaged();
+  await repo.saveSnapshot(message, snapshotHint);
+  return result.summary;
+}
+
+function renderCommand(lines, command, output) {
+  if (lines.length) {
+    lines.push("");
+  }
+
+  lines.push(`$ ${command}`);
+  lines.push(...output);
+}
+
+export async function generateDemoTranscript({ redactWorkspace = false } = {}) {
+  const workspace = fs.mkdtempSync(path.join(os.tmpdir(), "aethel-demo-"));
+  const visibleWorkspace = redactWorkspace ? "/tmp/aethel-demo-XXXXXX" : workspace;
+  resetFolderLookupCache();
+
+  try {
+    initWorkspace(workspace, "root", "My Drive");
+
+    const drive = createFakeDrive([
+      folder("fld-docs", "docs", "root", "2026-04-01T10:00:00.000Z"),
+      folder("fld-notes", "notes", "root", "2026-04-01T10:01:00.000Z"),
+      file("file-spec", "spec.txt", "fld-docs", "2026-04-01T10:02:00.000Z", "Spec v1\n"),
+      file("file-ideas", "ideas.txt", "fld-notes", "2026-04-01T10:03:00.000Z", "Idea v1\n"),
+    ]);
+
+    const repo = new Repository(workspace, { drive });
+
+    writeLocal(workspace, "docs/spec.txt", "Spec v1\n");
+    writeLocal(workspace, "notes/ideas.txt", "Idea v1\n");
+    await repo.saveSnapshot("initial sync");
+
+    await drive.files.update({
+      fileId: "file-spec",
+      media: { body: Readable.from(["Spec v2 from Drive\n"]) },
+    });
+    const designFolderId = await ensureFolder(drive, "design");
+    await drive.files.create({
+      requestBody: {
+        name: "roadmap.txt",
+        parents: [designFolderId],
+      },
+      media: { body: Readable.from(["Roadmap from Drive\n"]) },
+    });
+    writeLocal(workspace, "notes/ideas.txt", "Idea v2 from local\n");
+    writeLocal(workspace, "drafts/todo.txt", "Local draft\n");
+    repo.invalidateRemoteCache();
+
+    const lines = [
+      "Aethel demo",
+      `Workspace: ${visibleWorkspace}`,
+      "Backend: fake Google Drive",
+      "",
+      "Scenario:",
+      "  Drive changed docs/spec.txt and added design/roadmap.txt",
+      "  Local changed notes/ideas.txt and added drafts/todo.txt",
+    ];
+
+    let state = await repo.loadState({ useCache: false });
+
+    renderCommand(lines, "aethel status", formatStatus(state.diff, repo.getStagedEntries()));
+    renderCommand(lines, "aethel diff --side all", formatDiff(state.diff));
+
+    const stagedCount = repo.stageChanges(
+      state.diff.changes.filter((change) => change.suggestedAction !== "conflict")
+    );
+    renderCommand(lines, "aethel add --all", [`Staged ${stagedCount} change(s).`]);
+    renderCommand(lines, "aethel status", formatStatus(state.diff, repo.getStagedEntries()));
+
+    const summary = await commit(repo, "demo sync");
+    renderCommand(lines, 'aethel commit -m "demo sync"', [`Commit complete: ${summary}`]);
+
+    state = await repo.loadState({ useCache: false });
+    renderCommand(lines, "aethel status", formatStatus(state.diff, repo.getStagedEntries()));
+
+    lines.push("");
+    lines.push(`Inspect the demo workspace at: ${visibleWorkspace}`);
+
+    return { workspace, lines };
+  } finally {
+    resetFolderLookupCache();
+  }
+}
+
+export async function runDemo({ cleanup = false, redactWorkspace = false } = {}) {
+  const { workspace, lines } = await generateDemoTranscript({ redactWorkspace });
+  process.stdout.write(`${lines.join("\n")}\n`);
+
+  if (cleanup) {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+}
+
+const entryPath = fileURLToPath(import.meta.url);
+
+if (process.argv[1] && path.resolve(process.argv[1]) === entryPath) {
+  const cleanup = process.argv.includes("--cleanup");
+  const redactWorkspace = process.argv.includes("--redact-workspace");
+
+  runDemo({ cleanup, redactWorkspace }).catch((error) => {
+    console.error(error?.stack || String(error));
+    process.exitCode = 1;
+  });
+}

package/scripts/render-demo-gif.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+
+from pathlib import Path
+from subprocess import run
+from PIL import Image, ImageDraw, ImageFont
+
+ROOT = Path(__file__).resolve().parent.parent
+OUTPUT = ROOT / "docs" / "demo.gif"
+DISPLAY_WIDTH = 1320
+DISPLAY_MIN_HEIGHT = 760
+LINE_HEIGHT = 30
+SCALE = 2
+
+
+def load_lines():
+    result = run(
+        ["node", "scripts/demo.js", "--cleanup", "--redact-workspace"],
+        cwd=ROOT,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return result.stdout.rstrip("\n").splitlines()
+
+
+def load_font(size):
+    for candidate in [
+        "/System/Library/Fonts/Supplemental/Times New Roman.ttf",
+        "/System/Library/Fonts/Supplemental/Times New Roman Bold.ttf",
+    ]:
+        path = Path(candidate)
+        if path.exists():
+            return ImageFont.truetype(str(path), size)
+    return ImageFont.load_default()
+
+
+def load_title_font(size):
+    for candidate in [
+        "/System/Library/Fonts/Supplemental/Times New Roman Bold.ttf",
+        "/System/Library/Fonts/Supplemental/Times New Roman.ttf",
+    ]:
+        path = Path(candidate)
+        if path.exists():
+            return ImageFont.truetype(str(path), size)
+    return ImageFont.load_default()
+
+
+def build_frame(lines, font, title_font, visible):
+    shown = lines[:visible]
+    width = DISPLAY_WIDTH * SCALE
+    height = max(DISPLAY_MIN_HEIGHT, 180 + len(lines) * LINE_HEIGHT) * SCALE
+    image = Image.new("RGB", (width, height), "#0b1324")
+    draw = ImageDraw.Draw(image)
+    draw.rounded_rectangle((40, 40, width - 40, height - 40), 44, fill="#0a0f1a", outline="#243044", width=4)
+    draw.rounded_rectangle((40, 40, width - 40, 108), 44, fill="#10192a")
+    draw.ellipse((84, 62, 108, 86), fill="#fb7185")
+    draw.ellipse((124, 62, 148, 86), fill="#f59e0b")
+    draw.ellipse((164, 62, 188, 86), fill="#22c55e")
+    draw.text((236, 52), "Aethel demo", font=title_font, fill="#dbe4f0")
+    y = 176
+    for line in shown:
+        draw.text((104, y), line, font=font, fill="#dbe4f0")
+        y += LINE_HEIGHT * SCALE
+    if visible < len(lines):
+        draw.rounded_rectangle((104, y + 8, 134, y + 48), 6, fill="#38bdf8")
+    return image.resize((DISPLAY_WIDTH, height // SCALE), Image.Resampling.LANCZOS)
+
+
+def main():
+    lines = load_lines()
+    font = load_font(24 * SCALE)
+    title_font = load_title_font(22 * SCALE)
+    checkpoints = [3, 7, 13, 21, 27, len(lines)]
+    frames = [build_frame(lines, font, title_font, count) for count in checkpoints]
+    durations = [500, 600, 700, 800, 900, 1800]
+    OUTPUT.parent.mkdir(parents=True, exist_ok=True)
+    frames[0].save(
+        OUTPUT,
+        save_all=True,
+        append_images=frames[1:],
+        duration=durations,
+        loop=0,
+        optimize=False,
+        disposal=2,
+    )
+    print(OUTPUT)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/render-demo-screenshot.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { generateDemoTranscript } from "./demo.js";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const outputPath = path.join(root, "docs", "demo-screenshot.svg");
+
+function escapeXml(value) {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+const { workspace, lines } = await generateDemoTranscript({ redactWorkspace: true });
+
+try {
+  const longest = lines.reduce((max, line) => Math.max(max, line.length), 0);
+  const charWidth = 12.4;
+  const lineHeight = 32;
+  const width = Math.max(1120, Math.ceil(longest * charWidth) + 160);
+  const height = lines.length * lineHeight + 168;
+  const text = lines
+    .map(
+      (line, index) =>
+        `<text x="64" y="${100 + index * lineHeight}" xml:space="preserve">${escapeXml(line)}</text>`
+    )
+    .join("\n");
+
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img" aria-label="Aethel demo screenshot">
+<defs>
+<linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+<stop offset="0%" stop-color="#0b1324"/>
+<stop offset="55%" stop-color="#111827"/>
+<stop offset="100%" stop-color="#1f2937"/>
+</linearGradient>
+<linearGradient id="glow" x1="0" y1="0" x2="1" y2="0">
+<stop offset="0%" stop-color="#22c55e"/>
+<stop offset="50%" stop-color="#38bdf8"/>
+<stop offset="100%" stop-color="#f59e0b"/>
+</linearGradient>
+</defs>
+<rect width="${width}" height="${height}" rx="28" fill="url(#bg)"/>
+<rect x="24" y="24" width="${width - 48}" height="${height - 48}" rx="20" fill="#0a0f1a" stroke="#243044"/>
+<rect x="24" y="24" width="${width - 48}" height="36" rx="20" fill="#10192a"/>
+<circle cx="52" cy="42" r="7" fill="#fb7185"/>
+<circle cx="74" cy="42" r="7" fill="#f59e0b"/>
+<circle cx="96" cy="42" r="7" fill="#22c55e"/>
+<rect x="132" y="35" width="${Math.min(320, width - 220)}" height="12" rx="6" fill="url(#glow)" opacity="0.8"/>
+<g fill="#dbe4f0" font-family="'Times New Roman', Times, serif" font-size="22">
+${text}
+</g>
+</svg>
+`;
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, svg);
+  process.stdout.write(`${outputPath}\n`);
+} finally {
+  fs.rmSync(workspace, { recursive: true, force: true });
+}

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;
   }
@@ -301,23 +303,54 @@ async function handleStatus(options) {
     }
   }
 
-  if (diff.remoteChanges.length) {
-    console.log(`\nRemote changes (${diff.remoteChanges.length}):`);
-    for (const change of diff.remoteChanges) {
+  const stagedPaths = new Set(staged.map((e) => e.path));
+  const unstagedRemote = diff.remoteChanges.filter((c) => !stagedPaths.has(c.path));
+  const unstagedLocal = diff.localChanges.filter((c) => !stagedPaths.has(c.path));
+  const unstagedConflicts = diff.conflicts.filter((c) => !stagedPaths.has(c.path));
+
+  if (unstagedRemote.length) {
+    console.log(`\nRemote changes (${unstagedRemote.length}):`);
+    for (const change of unstagedRemote) {
       console.log(`  ${change.shortStatus} ${change.path}  (${change.description})`);
     }
   }
 
-  if (diff.localChanges.length) {
-    console.log(`\nLocal changes (${diff.localChanges.length}):`);
-    for (const change of diff.localChanges) {
+  if (unstagedLocal.length) {
+    console.log(`\nLocal changes (${unstagedLocal.length}):`);
+    for (const change of unstagedLocal) {
       console.log(`  ${change.shortStatus} ${change.path}  (${change.description})`);
     }
   }
 
-  if (diff.conflicts.length) {
-    console.log(`\nConflicts (${diff.conflicts.length}):`);
-    for (const change of diff.conflicts) {
+  if (unstagedConflicts.length) {
+    console.log(`\nConflicts (${unstagedConflicts.length}):`);
+    for (const change of unstagedConflicts) {
+      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})`);
     }
   }
@@ -1076,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