@tyvm/knowhow 0.0.109-dev.05fe5a0 → 0.0.109-dev.38b1faa

package/src/commands/modules.ts

@@ -4,6 +4,7 @@ import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
 import { getConfig, getGlobalConfig, updateConfig, updateGlobalConfig } from "../config";
+import * as readline from "readline";
 
 // Default built-in modules that `knowhow modules setup` adds to the config.
 export const BUILTIN_MODULES = [
@@ -49,6 +50,234 @@ function npmInstallToKnowhow(mod: string, knowhowDir: string): void {
   });
 }
 
+/**
+ * Returns true if a module package is already installed in the given knowhow dir.
+ */
+function isModuleInstalled(mod: string, knowhowDir: string): boolean {
+  try {
+    require.resolve(mod, {
+      paths: [path.join(knowhowDir, "node_modules"), knowhowDir],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+interface NpmRegistryInfo {
+  latestVersion: string;
+  publishedAt: string;
+}
+
+/**
+ * Fetch the latest version and publish time from the npm registry for a package.
+ * Returns null if the package info can't be fetched.
+ */
+async function fetchNpmRegistryInfo(mod: string): Promise<NpmRegistryInfo | null> {
+  try {
+    // npm view <pkg> version time --json returns either a single value or array
+    const output = execSync(`npm view ${mod} version time --json`, {
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+    const parsed = JSON.parse(output.trim());
+    let latestVersion: string;
+    let timestamps: Record<string, string> = {};
+    if (Array.isArray(parsed)) {
+      latestVersion = parsed[0];
+      timestamps = parsed[1] || {};
+    } else if (parsed && typeof parsed === "object") {
+      latestVersion = parsed["version"] || "";
+      timestamps = parsed["time"] || {};
+    } else {
+      latestVersion = String(parsed);
+    }
+    const publishedAt = timestamps[latestVersion] || timestamps["modified"] || "";
+    return { latestVersion, publishedAt };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Simple engine range checker — handles the common cases:
+ *   ">=22"  ">=22.0.0"  "^20"  "20.x"  "*"  ""
+ * Returns true if the given nodeVersion satisfies the range.
+ * Falls back to true (permissive) for unsupported range syntax.
+ */
+function nodeSatisfiesRange(nodeVersion: string, range: string): boolean {
+  if (!range || range === "*" || range === "") return true;
+
+  // Parse "major.minor.patch" from e.g. "v20.17.0"
+  const vMatch = nodeVersion.replace(/^v/, "").match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  if (!vMatch) return true;
+  const vMajor = parseInt(vMatch[1], 10);
+  const vMinor = parseInt(vMatch[2] ?? "0", 10);
+  const vPatch = parseInt(vMatch[3] ?? "0", 10);
+  const vNum = vMajor * 1_000_000 + vMinor * 1_000 + vPatch;
+
+  function parseVersion(s: string): number {
+    const m = s.trim().match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+    if (!m) return 0;
+    return parseInt(m[1], 10) * 1_000_000 + parseInt(m[2] ?? "0", 10) * 1_000 + parseInt(m[3] ?? "0", 10);
+  }
+
+  // Handle " || " — any segment satisfying is fine
+  if (range.includes("||")) {
+    return range.split("||").some((r) => nodeSatisfiesRange(nodeVersion, r.trim()));
+  }
+
+  // Handle space-separated AND conditions e.g. ">=14 <18"
+  const parts = range.trim().split(/\s+/);
+  for (const part of parts) {
+    const gteMatch = part.match(/^>=(.+)/);
+    const gtMatch = part.match(/^>(?!=)(.+)/);
+    const lteMatch = part.match(/^<=(.+)/);
+    const ltMatch = part.match(/^<(?!=)(.+)/);
+    const caretMatch = part.match(/^\^(\d+)/);
+    const tildeMatch = part.match(/^~(\d+)(?:\.(\d+))?/);
+    const exactMatch = part.match(/^(\d+(?:\.\d+)*)/);
+
+    if (gteMatch) {
+      if (vNum < parseVersion(gteMatch[1])) return false;
+    } else if (gtMatch) {
+      if (vNum <= parseVersion(gtMatch[1])) return false;
+    } else if (lteMatch) {
+      if (vNum > parseVersion(lteMatch[1])) return false;
+    } else if (ltMatch) {
+      if (vNum >= parseVersion(ltMatch[1])) return false;
+    } else if (caretMatch) {
+      const base = parseVersion(caretMatch[1]);
+      const baseMajor = parseInt(caretMatch[1], 10);
+      if (vNum < base || vMajor !== baseMajor) return false;
+    } else if (tildeMatch) {
+      const baseMajor = parseInt(tildeMatch[1], 10);
+      const baseMinor = parseInt(tildeMatch[2] ?? "0", 10);
+      const base = parseVersion(`${baseMajor}.${baseMinor}`);
+      const nextMinor = parseVersion(`${baseMajor}.${baseMinor + 1}`);
+      if (vNum < base || vNum >= nextMinor) return false;
+    } else if (exactMatch && !part.startsWith("v")) {
+      // e.g. "20.x" or "20"
+      const xMatch = part.match(/^(\d+)(?:\.x)?$/);
+      if (xMatch) {
+        if (vMajor !== parseInt(xMatch[1], 10)) return false;
+      }
+    }
+    // Unknown operators — fall through (permissive)
+  }
+  return true;
+}
+
+/**
+ * Fetch the latest version of a package that is compatible with the current
+ * Node.js engine. Falls back to "@latest" if no engine info is available.
+ *
+ * Uses the npm registry API to get per-version engine requirements.
+ */
+async function fetchLatestCompatibleVersion(mod: string): Promise<string> {
+  const currentNode = process.version; // e.g. "v20.17.0"
+  try {
+    // Encode scoped package names for URL (e.g. @tyvm/pkg -> @tyvm%2Fpkg)
+    const encodedMod = mod.replace(/^@/, "").replace("/", "%2F");
+    const registryUrl = mod.startsWith("@")
+      ? `https://registry.npmjs.org/@${encodedMod}`
+      : `https://registry.npmjs.org/${mod}`;
+
+    const response = await fetch(registryUrl);
+    if (!response.ok) throw new Error(`Registry returned ${response.status}`);
+    const pkgData = await response.json() as any;
+
+    // pkgData.versions is a map of version -> package metadata
+    const versionsMap: Record<string, any> = pkgData.versions ?? {};
+    const allVersions = Object.keys(versionsMap);
+
+    // Build per-version engine map from actual per-version metadata
+    const enginesByVersion: Record<string, string> = {};
+    for (const [v, meta] of Object.entries(versionsMap)) {
+      enginesByVersion[v] = (meta as any)?.engines?.node ?? "";
+    }
+
+    if (allVersions.length === 0) return `${mod}@latest`;
+
+    // Sort versions descending (simple semver numeric sort)
+    const sorted = [...allVersions].sort((a, b) => {
+      const pa = a.split(".").map(Number);
+      const pb = b.split(".").map(Number);
+      for (let i = 0; i < 3; i++) {
+        if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pb[i] ?? 0) - (pa[i] ?? 0);
+      }
+      return 0;
+    });
+
+    for (const v of sorted) {
+      const engineRange = enginesByVersion[v] ?? "";
+      if (nodeSatisfiesRange(currentNode, engineRange)) {
+        return `${mod}@${v}`;
+      }
+    }
+
+    // No compatible version found — warn and fall back to latest
+    console.warn(`⚠️  No version of ${mod} found compatible with Node ${currentNode}. Installing latest anyway.`);
+    return `${mod}@latest`;
+  } catch {
+    // Can't fetch registry info — fall back to latest
+    return `${mod}@latest`;
+  }
+}
+
+/**
+ * Get the currently installed version of a package in .knowhow/node_modules.
+ */
+function getInstalledVersion(mod: string, knowhowDir: string): string | null {
+  try {
+    const pkgJsonPath = path.join(knowhowDir, "node_modules", mod, "package.json");
+    const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+    return pkgJson.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format a date string as a human-readable relative time (e.g. "2 days ago").
+ */
+function formatRelativeTime(isoDate: string): string {
+  if (!isoDate) return "unknown";
+  const then = new Date(isoDate).getTime();
+  if (isNaN(then)) return "unknown";
+  const diffMs = Date.now() - then;
+  const diffMins = Math.floor(diffMs / 60_000);
+  if (diffMins < 2) return "just now";
+  if (diffMins < 60) return `${diffMins} minutes ago`;
+  const diffHours = Math.floor(diffMins / 60);
+  if (diffHours < 24) return `${diffHours} hour${diffHours !== 1 ? "s" : ""} ago`;
+  const diffDays = Math.floor(diffHours / 24);
+  if (diffDays < 30) return `${diffDays} day${diffDays !== 1 ? "s" : ""} ago`;
+  const diffMonths = Math.floor(diffDays / 30);
+  if (diffMonths < 12) return `${diffMonths} month${diffMonths !== 1 ? "s" : ""} ago`;
+  const diffYears = Math.floor(diffMonths / 12);
+  return `${diffYears} year${diffYears !== 1 ? "s" : ""} ago`;
+}
+
+/**
+ * Prompt the user for a yes/no confirmation.
+ */
+function promptConfirm(question: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    rl.question(`${question} (y/N) `, (answer) => {
+      rl.close();
+      resolve(
+        answer.trim().toLowerCase() === "y" ||
+          answer.trim().toLowerCase() === "yes"
+      );
+    });
+  });
+}
+
 export function addModulesCommand(program: Command): void {
   const modulesCmd = program
     .command("modules")
@@ -70,39 +299,39 @@ export function addModulesCommand(program: Command): void {
 
         if (!cfg.modules) cfg.modules = [];
 
-        const toAdd = BUILTIN_MODULES.filter(
-          (m) => !cfg.modules!.includes(m)
-        );
-
-        if (toAdd.length === 0) {
-          console.log(
-            `✅ All default modules are already in ${configLabel}. Nothing to do.`
-          );
-          return;
-        }
-
         const knowhowDir = getKnowhowDir(isGlobal);
         ensureKnowhowPackageJson(knowhowDir);
 
-        // Install packages that are not local file paths
-        for (const mod of toAdd) {
+        // Even if modules are already in the config, they may not be installed.
+        // Check and install any that are missing from .knowhow/node_modules.
+        let anyChanges = false;
+        for (const mod of BUILTIN_MODULES) {
           if (!mod.startsWith(".") && !mod.startsWith("/")) {
-            console.log(`📦 Installing ${mod}...`);
-            npmInstallToKnowhow(mod, knowhowDir);
+            if (!isModuleInstalled(mod, knowhowDir)) {
+              const installTarget = await fetchLatestCompatibleVersion(mod);
+              console.log(`📦 Installing ${installTarget}...`);
+              npmInstallToKnowhow(installTarget, knowhowDir);
+              console.log(`✅ Installed ${mod}`);
+              anyChanges = true;
+            }
+          }
+          if (!cfg.modules.includes(mod)) {
+            cfg.modules.push(mod);
+            console.log(`✅ Added ${mod} to ${configLabel}`);
+            anyChanges = true;
           }
-          cfg.modules!.push(mod);
-          console.log(`✅ Added ${mod} to ${configLabel}`);
         }
 
-        if (isGlobal) {
-          await updateGlobalConfig(cfg);
+        if (!anyChanges) {
+          console.log(
+            `✅ All default modules are already in ${configLabel} and installed. Nothing to do.`
+          );
         } else {
-          await updateConfig(cfg);
+          await (isGlobal ? updateGlobalConfig(cfg) : updateConfig(cfg));
+          console.log(
+            `\n🎉 Setup complete! Modules ready in ${knowhowDir}/node_modules.`
+          );
         }
-
-        console.log(
-          `\n🎉 Setup complete! ${toAdd.length} module(s) added to ${configLabel}`
-        );
       } catch (error: any) {
         console.error("Error during modules setup:", error.message ?? error);
         process.exit(1);
@@ -116,6 +345,7 @@ export function addModulesCommand(program: Command): void {
       "If no module name is given, installs all modules already in the config."
     )
     .option("--global", "Use the global config (~/.knowhow/knowhow.json)")
+    .option("--latest", "Force install the latest version (bypasses package-lock)")
     .action(async (moduleName: string | undefined, opts) => {
       try {
         const isGlobal: boolean = opts.global ?? false;
@@ -135,9 +365,7 @@ export function addModulesCommand(program: Command): void {
             (m) => !m.startsWith(".") && !m.startsWith("/")
           );
           if (installable.length === 0) {
-            console.log(
-              `ℹ No installable modules found in ${configLabel}.`
-            );
+            console.log(`ℹ No installable modules found in ${configLabel}.`);
             return;
           }
           console.log(
@@ -145,7 +373,8 @@ export function addModulesCommand(program: Command): void {
           );
           for (const mod of installable) {
             console.log(`  📦 Installing ${mod}...`);
-            npmInstallToKnowhow(mod, knowhowDir);
+            const installTarget = opts.latest ? await fetchLatestCompatibleVersion(mod) : mod;
+            npmInstallToKnowhow(installTarget, knowhowDir);
             console.log(`  ✅ Installed ${mod}`);
           }
           console.log(`\n🎉 All modules installed!`);
@@ -153,8 +382,9 @@ export function addModulesCommand(program: Command): void {
         }
 
         // Install the specified module
-        console.log(`📦 Installing ${moduleName} into ${knowhowDir}/node_modules...`);
-        npmInstallToKnowhow(moduleName, knowhowDir);
+        const installTarget = opts.latest ? await fetchLatestCompatibleVersion(moduleName) : moduleName;
+        console.log(`📦 Installing ${installTarget} into ${knowhowDir}/node_modules...`);
+        npmInstallToKnowhow(installTarget, knowhowDir);
         console.log(`✅ Installed ${moduleName}`);
 
         // Add to config if not already there
@@ -214,4 +444,109 @@ export function addModulesCommand(program: Command): void {
         process.exit(1);
       }
     });
+
+  modulesCmd
+    .command("update")
+    .description(
+      "Check for updates to all modules in your config and update them. " +
+      "Shows installed vs latest version with publish date before updating."
+    )
+    .option("--global", "Use the global config (~/.knowhow/knowhow.json)")
+    .option("-y, --yes", "Skip confirmation prompt and update all outdated modules automatically")
+    .action(async (opts) => {
+      try {
+        const isGlobal: boolean = opts.global ?? false;
+        const skipConfirm: boolean = opts.yes ?? false;
+        const cfg = isGlobal ? await getGlobalConfig() : await getConfig();
+        const configLabel = isGlobal
+          ? "~/.knowhow/knowhow.json"
+          : ".knowhow/knowhow.json";
+
+        if (!cfg.modules || cfg.modules.length === 0) {
+          console.log(`ℹ No modules found in ${configLabel}.`);
+          return;
+        }
+
+        const knowhowDir = getKnowhowDir(isGlobal);
+        ensureKnowhowPackageJson(knowhowDir);
+
+        // Only check npm packages (not local paths)
+        const installable = cfg.modules.filter(
+          (m) => !m.startsWith(".") && !m.startsWith("/")
+        );
+
+        if (installable.length === 0) {
+          console.log(`ℹ No npm modules found in ${configLabel}.`);
+          return;
+        }
+
+        console.log(`🔍 Checking for updates to ${installable.length} module(s)...\n`);
+
+        interface UpdateInfo {
+          mod: string;
+          installed: string | null;
+          latest: string;
+          compatibleVersion: string; // e.g. "@tyvm/knowhow-module-script@0.0.4"
+          publishedAt: string;
+          needsUpdate: boolean;
+        }
+
+        const updates: UpdateInfo[] = [];
+
+        for (const mod of installable) {
+          const registryInfo = await fetchNpmRegistryInfo(mod);
+          if (!registryInfo) {
+            console.log(`  ⚠️  ${mod}: could not fetch registry info (skipping)`);
+            continue;
+          }
+          const installed = getInstalledVersion(mod, knowhowDir);
+          const { latestVersion, publishedAt } = registryInfo;
+          // Find the latest compatible version for the current Node.js engine
+          const compatibleInstallTarget = await fetchLatestCompatibleVersion(mod);
+          const compatibleVersion = compatibleInstallTarget.replace(/^[^@]+@/, ""); // strip "pkg@" prefix
+          const needsUpdate = installed !== compatibleVersion;
+          const timeAgo = formatRelativeTime(publishedAt);
+
+          if (needsUpdate) {
+            const installedStr = installed ?? "(not installed)";
+            const versionLabel = compatibleVersion !== latestVersion
+              ? `${compatibleVersion} (latest compatible with Node ${process.version}; absolute latest: ${latestVersion})`
+              : compatibleVersion;
+            console.log(`  📦 ${mod}`);
+            console.log(`     installed: ${installedStr}  →  latest: ${versionLabel} (published ${timeAgo})`);
+          } else {
+            console.log(`  ✅ ${mod}  v${compatibleVersion}  (up to date, published ${timeAgo})`);
+          }
+          updates.push({ mod, installed, latest: compatibleVersion, compatibleVersion: compatibleInstallTarget, publishedAt, needsUpdate });
+        }
+
+        const toUpdate = updates.filter((u) => u.needsUpdate);
+
+        if (toUpdate.length === 0) {
+          console.log(`\n✅ All modules are up to date!`);
+          return;
+        }
+
+        console.log(`\n${toUpdate.length} module(s) can be updated.`);
+
+        if (!skipConfirm) {
+          const confirmed = await promptConfirm(`Update ${toUpdate.length} module(s) now?`);
+          if (!confirmed) {
+            console.log("Cancelled.");
+            return;
+          }
+        }
+
+        console.log("");
+        for (const { mod, compatibleVersion } of toUpdate) {
+          console.log(`  📦 Updating ${compatibleVersion}...`);
+          npmInstallToKnowhow(compatibleVersion, knowhowDir);
+          console.log(`  ✅ Updated ${mod}`);
+        }
+        console.log(`\n🎉 Update complete! ${toUpdate.length} module(s) updated.`);
+      } catch (error: any) {
+        console.error("Error during modules update:", error.message ?? error);
+        process.exit(1);
+      }
+    });
 }

package/src/config.ts

@@ -74,7 +74,7 @@ const defaultConfig = {
       description:
         "You can define agents in the config. They will have access to all tools.",
       instructions: "Reply to the user saying 'Hello, world!'",
-      model: "gpt-4o-2024-08-06",
+      model: "gpt-5.4-nano",
       provider: "openai",
     },
   ],

package/src/fileSync.ts

@@ -6,7 +6,7 @@ import { loadJwt } from "./login";
 import { getConfig } from "./config";
 import { services } from "./services";
 import { S3Service } from "./services/S3";
-import { getHashes, hasFileChangedSinceUpload, saveUploadHash, isLocalFileMatchingRemote, isLocalFileMatchingDownloadHash, saveDownloadHash } from "./hashes";
+import { getHashes, saveHashes, hasFileChangedSinceUpload, saveUploadHash, isLocalFileMatchingRemote, isLocalFileMatchingDownloadHash, saveDownloadHash } from "./hashes";
 
 export const DEFAULT_BATCH_SIZE = 5;
 
@@ -165,7 +165,8 @@ export async function downloadFile(
   s3Service: S3Service,
   remotePath: string,
   localPath: string,
-  dryRun: boolean
+  dryRun: boolean,
+  hashes?: any
 ): Promise<void> {
   console.log(`⬇️  Downloading ${remotePath} → ${localPath}`);
 
@@ -176,8 +177,7 @@ export async function downloadFile(
 
   try {
     // Fast-path: check stored download hash before hitting the API
-    const hashes = await getHashes();
-    if (await isLocalFileMatchingDownloadHash(localPath, hashes)) {
+    if (hashes && await isLocalFileMatchingDownloadHash(localPath, hashes)) {
       console.log(`   ✓ Skipping ${localPath} (matches stored download hash)`);
       return;
     }
@@ -189,7 +189,7 @@ export async function downloadFile(
     if (isLocalFileMatchingRemote(localPath, checksumSHA256)) {
       console.log(`   ✓ Skipping ${localPath} (matches remote checksum)`);
       // Store the hash so future syncs can skip without hitting the API
-      await saveDownloadHash(localPath);
+      await saveDownloadHash(localPath, hashes);
       return;
     }
 
@@ -203,7 +203,7 @@ export async function downloadFile(
     await s3Service.downloadFromPresignedUrl(downloadUrl, localPath);
 
     // Save download hash so we can skip unchanged files next time
-    await saveDownloadHash(localPath);
+    await saveDownloadHash(localPath, hashes);
 
     // Get file size for logging
     const stats = fs.statSync(localPath);
@@ -221,7 +221,8 @@ export async function uploadFile(
   s3Service: S3Service,
   remotePath: string,
   localPath: string,
-  dryRun: boolean
+  dryRun: boolean,
+  hashes?: any
 ): Promise<void> {
   console.log(`⬆️  Uploading ${localPath} → ${remotePath}`);
 
@@ -237,8 +238,7 @@ export async function uploadFile(
   }
 
   // Skip upload if file hasn't changed since last upload
-  const hashes = await getHashes();
-  const changed = await hasFileChangedSinceUpload(localPath, hashes);
+  const changed = hashes ? await hasFileChangedSinceUpload(localPath, hashes) : true;
   if (!changed) {
     console.log(`   ✓ Skipping ${localPath} (unchanged since last upload)`);
     return;
@@ -254,7 +254,7 @@ export async function uploadFile(
   await client.markOrgFileUploadComplete(remotePath);
 
   // Save upload hash so we can skip unchanged files next time
-  await saveUploadHash(localPath);
+  await saveUploadHash(localPath, hashes);
 
   const stats = fs.statSync(localPath);
   console.log(`   ✓ Uploaded ${stats.size} bytes`);
@@ -276,6 +276,8 @@ export async function uploadDirectory(
 
   console.log(`⬆️  Uploading directory ${localDir} → ${remoteDir}`);
 
+  const hashes = await getHashes();
+
   if (!fs.existsSync(localDir)) {
     console.warn(`   ⚠️  Local directory not found: ${localDir}`);
     return 0;
@@ -295,7 +297,7 @@ export async function uploadDirectory(
     const localFilePath = localDir + relFile;
     const remoteFilePath = remoteDir + relFile;
     try {
-      await uploadFile(client, s3Service, remoteFilePath, localFilePath, dryRun);
+      await uploadFile(client, s3Service, remoteFilePath, localFilePath, dryRun, hashes);
       return 1;
     } catch (error) {
       console.error(
@@ -306,6 +308,8 @@ export async function uploadDirectory(
   });
 
   const counts = await batchRun(tasks);
+  await saveHashes(hashes);
+
   return counts.reduce((sum, n) => sum + n, 0);
 }
 
@@ -325,6 +329,8 @@ export async function downloadDirectory(
 
   console.log(`⬇️  Downloading directory ${remoteDir} → ${localDir}`);
 
+  const hashes = await getHashes();
+
   // List all org files and find those in the remote directory
   const response = await client.listOrgFiles();
   const allFiles = response.data;
@@ -352,10 +358,12 @@ export async function downloadDirectory(
     // Strip the base remote dir prefix to get relative path
     const relativePath = fullRemotePath.slice(remoteDir.length);
     const localFilePath = localDir + relativePath;
-    await downloadFile(client, s3Service, fullRemotePath, localFilePath, dryRun);
+    await downloadFile(client, s3Service, fullRemotePath, localFilePath, dryRun, hashes);
     return 1;
   });
 
   const counts = await batchRun(tasks);
+  await saveHashes(hashes);
+
   return counts.reduce((sum, n) => sum + n, 0);
 }

package/src/hashes.ts

@@ -1,16 +1,35 @@
 import fs from "fs";
 import * as crypto from "crypto";
 import { Hashes } from "./types";
-import { readFile, writeFile } from "./utils";
+import { readFile } from "./utils";
 import { convertToText } from "./conversion";
 
 export async function getHashes() {
-  const hashes = JSON.parse(await readFile(".knowhow/.hashes.json", "utf8"));
-  return hashes as Hashes;
+  try {
+    const hashes = JSON.parse(await readFile(".knowhow/.hashes.json", "utf8"));
+    return hashes as Hashes;
+  } catch (err: any) {
+    if (err.code === "ENOENT") {
+      return {} as Hashes;
+    }
+    throw err;
+  }
 }
 
+/**
+ * Atomically save hashes to disk — writes to a temp file then renames,
+ * preventing concurrent writes from producing corrupted/truncated JSON.
+ */
 export async function saveHashes(hashes: any) {
-  await writeFile(".knowhow/.hashes.json", JSON.stringify(hashes, null, 2));
+  const target = ".knowhow/.hashes.json";
+  const tmp = `${target}.tmp.${process.pid}`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(hashes, null, 2));
+    fs.renameSync(tmp, target);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch (_) {}
+    throw err;
+  }
 }
 
 export async function md5Hash(str: string) {
@@ -90,17 +109,19 @@ export async function hasFileChangedSinceUpload(
 }
 
 /**
- * Saves the hash of the file at the time of a successful upload
+ * Mutates the provided hashes object with the upload hash for localPath.
+ * If no hashes object is provided, loads, mutates, and saves independently.
  */
-export async function saveUploadHash(localPath: string) {
-  const hashes = await getHashes();
+export async function saveUploadHash(localPath: string, hashes?: any) {
+  const standalone = !hashes;
+  if (standalone) hashes = await getHashes();
   const content = fs.readFileSync(localPath);
   const currentHash = crypto.createHash("md5").update(content).digest("hex");
   if (!hashes[localPath]) {
     hashes[localPath] = { fileHash: currentHash, promptHash: "" };
   }
   hashes[localPath][UPLOAD_KEY] = currentHash;
-  await saveHashes(hashes);
+  if (standalone) await saveHashes(hashes);
 }
 
 /**
@@ -120,18 +141,19 @@ export async function isLocalFileMatchingDownloadHash(
 }
 
 /**
- * Saves the SHA-256 hash of the file after a successful download so we can
- * skip unchanged files on the next sync.
+ * Mutates the provided hashes object with the download hash for localPath.
+ * If no hashes object is provided, loads, mutates, and saves independently.
  */
-export async function saveDownloadHash(localPath: string) {
-  const hashes = await getHashes();
+export async function saveDownloadHash(localPath: string, hashes?: any) {
+  const standalone = !hashes;
+  if (standalone) hashes = await getHashes();
   const content = fs.readFileSync(localPath);
   const currentHash = crypto.createHash("sha256").update(content).digest("base64");
   if (!hashes[localPath]) {
     hashes[localPath] = { fileHash: currentHash, promptHash: "" };
   }
   hashes[localPath][DOWNLOAD_KEY] = currentHash;
-  await saveHashes(hashes);
+  if (standalone) await saveHashes(hashes);
 }
 
 /**