@adaptic/maestro 1.4.1 → 1.5.1

package/bin/maestro.mjs

@@ -8,16 +8,21 @@
  *   npx @adaptic/maestro doctor             # Verify installation and configuration
  */
 
-import { resolve, join, dirname } from "node:path";
+import { resolve, join, dirname, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   mkdirSync,
   cpSync,
+  copyFileSync,
   existsSync,
   readFileSync,
   writeFileSync,
+  readdirSync,
+  statSync,
+  lstatSync,
 } from "node:fs";
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const MAESTRO_ROOT = resolve(__dirname, "..");
@@ -664,68 +669,332 @@ rubrics: []
 }
 
 // ---------------------------------------------------------------------------
-// UPGRADE — update framework files in current agent repo
+// UPGRADE — update framework files in current agent repo (smart merge)
 // ---------------------------------------------------------------------------
+//
+// Upgrade philosophy: by default, never silently overwrite a file the user has
+// modified locally. Detection uses git as the source of truth:
+//
+//   • untracked or has-uncommitted-changes in agent repo ⇒ "locally modified"
+//   • tracked and clean against HEAD ⇒ "vendored, safe to overwrite"
+//
+// For every framework file we'd otherwise overwrite, we classify into:
+//
+//   added     — file doesn't exist in agent repo → copy
+//   updated   — file exists, agent's copy matches HEAD (no local edits) → overwrite
+//   same      — file exists, content already byte-identical to upstream → skip
+//   preserved — file exists with local edits → keep agent's copy, write the
+//               upstream version to .maestro/incoming/<path> for manual review
+//               (unless --force-overwrite is passed)
+//
+// Flags:
+//   --dry-run            preview only; no files written
+//   --force-overwrite    overwrite even locally-modified files (with backup)
+//   --no-incoming        skip writing .maestro/incoming/ shadows
+//   --verbose            list every file's classification
+
+// Paths that get upgraded. Each entry is { path, mode } where mode is:
+//   "smart"  — per-file classification described above
+//   "merge"  — add new files only; never overwrite existing (used for agents/)
+const UPGRADE_PATHS = [
+  { path: "scripts", mode: "smart" },
+  { path: "policies", mode: "smart" },
+  { path: "docs", mode: "smart" },
+  { path: "public/assets", mode: "smart" },
+  { path: "workflows", mode: "smart" },
+  { path: "schedules", mode: "smart" },
+  { path: "desktop-control", mode: "smart" },
+  { path: "ingest", mode: "smart" },
+  { path: "mcp", mode: "smart" },
+  { path: ".claude/commands", mode: "smart" },
+  { path: "plugins/maestro-skills", mode: "smart" },
+  { path: "teams", mode: "smart" },
+  { path: "agents", mode: "merge" },
+];
+
+function sha256File(p) {
+  return createHash("sha256").update(readFileSync(p)).digest("hex");
+}
 
-function upgrade() {
-  const cwd = process.cwd();
+function walkFiles(root) {
+  const out = [];
+  if (!existsSync(root)) return out;
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    for (const name of readdirSync(dir)) {
+      const full = join(dir, name);
+      // Use lstat first so we can detect (and skip) symlinks — particularly
+      // broken ones, which are common in shared scaffolds.
+      let lst;
+      try { lst = lstatSync(full); }
+      catch { continue; }
+      if (lst.isSymbolicLink()) {
+        // Skip symlinks entirely — agents shouldn't inherit links into paths
+        // that may not exist on the target machine.
+        continue;
+      }
+      if (lst.isDirectory()) stack.push(full);
+      else if (lst.isFile()) out.push(full);
+    }
+  }
+  return out;
+}
 
-  if (!existsSync(join(cwd, "config/agent.ts")) && !existsSync(join(cwd, "CLAUDE.md"))) {
-    fail("Not a Maestro agent directory (config/agent.ts not found)");
-    process.exit(1);
+// .maestroignore — gitignore-style allowlist of paths the upgrade must NOT
+// touch. Supports comments (#), directory prefixes (trailing /), exact paths,
+// simple globs (* matches a single path segment, ** matches recursively), and
+// negation (! prefix to un-ignore). Match order is top-to-bottom; last match
+// wins, like .gitignore.
+function loadMaestroignore(cwd) {
+  const file = join(cwd, ".maestroignore");
+  if (!existsSync(file)) return null;
+  const patterns = [];
+  for (const raw of readFileSync(file, "utf-8").split(/\r?\n/)) {
+    const stripped = raw.replace(/^\s+|\s+$/g, "");
+    if (!stripped || stripped.startsWith("#")) continue;
+    const negate = stripped.startsWith("!");
+    const pat = negate ? stripped.slice(1).trim() : stripped;
+    if (!pat) continue;
+    patterns.push({ pat, negate });
   }
+  return patterns.length ? patterns : null;
+}
 
-  log("Upgrading framework files from @adaptic/maestro...");
+function patternToRegex(pat) {
+  // Directory prefix: `scripts/daemon/` matches scripts/daemon/* (recursive)
+  if (pat.endsWith("/")) {
+    const prefix = pat.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    return new RegExp("^" + prefix);
+  }
+  // Glob with * and **.
+  // Step order matters: ** must be captured before single * to preserve
+  // recursive semantics. * is intentionally NOT in the regex-escape char
+  // class so we can rewrite it after escaping the other specials.
+  if (pat.includes("*")) {
+    const escaped = pat
+      .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+      .replace(/\*\*/g, "<DBL>")
+      .replace(/\*/g, "[^/]*")
+      .replace(/<DBL>/g, ".*");
+    return new RegExp("^" + escaped + "$");
+  }
+  // Exact: also match anything underneath (a path like `scripts/daemon`
+  // without trailing slash should still protect the whole directory if
+  // it resolves to one — gitignore semantics).
+  const escaped = pat.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  return new RegExp("^" + escaped + "(/|$)");
+}
 
-  // Framework directories that get overwritten on upgrade
-  const frameworkDirs = [
-    "scripts", "policies", "docs", "public/assets",
-    "workflows", "schedules", "desktop-control", "ingest", "mcp",
-  ];
+function matchesIgnore(repoRel, patterns) {
+  if (!patterns) return false;
+  let ignored = false;
+  for (const { pat, negate } of patterns) {
+    if (patternToRegex(pat).test(repoRel)) {
+      ignored = !negate;
+    }
+  }
+  return ignored;
+}
 
-  let updated = 0;
-  for (const dir of frameworkDirs) {
-    const src = join(MAESTRO_ROOT, dir);
-    if (existsSync(src)) {
-      cpSync(src, join(cwd, dir), { recursive: true, force: true });
-      ok(dir);
-      updated++;
+function isGitRepo(cwd) {
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd, stdio: "pipe" });
+    return true;
+  } catch { return false; }
+}
+
+// Build a Set of repo-relative paths that are dirty (modified, added, untracked).
+// Single git invocation is much faster than per-file checks.
+function dirtyPathSet(cwd) {
+  const set = new Set();
+  try {
+    const out = execFileSync(
+      "git",
+      ["status", "--porcelain=v1", "-z", "--untracked-files=all"],
+      { cwd, encoding: "utf-8" }
+    );
+    // -z separates records with NUL; each record is "XY path" (no quoting).
+    // For renames (R/C) the format is "R  newpath\0oldpath\0" — we only care
+    // about destination, but for safety we treat both as dirty.
+    for (const rec of out.split("\0")) {
+      if (!rec) continue;
+      const status = rec.slice(0, 2);
+      const path = rec.slice(3);
+      // Anything in porcelain output is non-clean by definition.
+      if (status !== "  ") set.add(path);
     }
+  } catch {
+    // Not a git repo or git failed — caller will fall back to caution mode.
+  }
+  return set;
+}
+
+function parseUpgradeFlags(args) {
+  const flags = {
+    dryRun: false,
+    forceOverwrite: false,
+    noIncoming: false,
+    verbose: false,
+  };
+  for (const a of args) {
+    if (a === "--dry-run" || a === "-n") flags.dryRun = true;
+    else if (a === "--force-overwrite" || a === "--force") flags.forceOverwrite = true;
+    else if (a === "--no-incoming") flags.noIncoming = true;
+    else if (a === "--verbose" || a === "-v") flags.verbose = true;
+    else if (a === "--help" || a === "-h") return null;
+    else { fail(`Unknown flag: ${a}`); process.exit(1); }
+  }
+  return flags;
+}
+
+function upgrade(args = []) {
+  const flags = parseUpgradeFlags(args);
+  if (flags === null) {
+    console.log(`
+Usage: maestro upgrade [flags]
+
+Flags:
+  --dry-run, -n          Preview changes without writing
+  --force-overwrite      Overwrite even locally-modified files (backs them up)
+  --no-incoming          Don't write .maestro/incoming/ shadows for preserved files
+  --verbose, -v          Print classification for every file
+  --help, -h             Show this help
+
+Per-file behaviour:
+  added     — new upstream file → copy
+  updated   — existed, byte-equal to your committed copy → safe overwrite
+  same      — existed and already byte-identical to upstream → skip
+  ignored   — matches a pattern in .maestroignore → never touched (any state)
+  preserved — has uncommitted local edits → keep yours, upstream lands at
+              .maestro/incoming/<path> for manual diff
+  mergeKept — under agents/ → never overwrite (custom agents preserved)
+  forced    — overwritten by --force-overwrite; backup at .maestro/backup/<path>
+
+.maestroignore format (gitignore-style, top-down, last match wins):
+  scripts/slack-send.sh          exact file
+  scripts/daemon/                directory and everything beneath
+  scripts/send-email-*.py        single-segment glob
+  workflows/**                   recursive glob
+  !workflows/quarterly/          un-ignore (force overwrite)
+`);
+    return;
   }
 
-  // .claude/commands (NOT settings.json — that's agent-specific)
-  const commandsSrc = join(MAESTRO_ROOT, ".claude", "commands");
-  if (existsSync(commandsSrc)) {
-    cpSync(commandsSrc, join(cwd, ".claude", "commands"), { recursive: true, force: true });
-    ok(".claude/commands");
-    updated++;
+  const cwd = process.cwd();
+
+  if (!existsSync(join(cwd, "config/agent.ts")) && !existsSync(join(cwd, "CLAUDE.md"))) {
+    fail("Not a Maestro agent directory (config/agent.ts not found)");
+    process.exit(1);
   }
 
-  // Plugins
-  const pluginSrc = join(MAESTRO_ROOT, "plugins", "maestro-skills");
-  if (existsSync(pluginSrc)) {
-    cpSync(pluginSrc, join(cwd, "plugins", "maestro-skills"), { recursive: true, force: true });
-    ok("plugins/maestro-skills");
-    updated++;
+  const inGit = isGitRepo(cwd);
+  if (!inGit) {
+    warn("Not in a git repo — cannot detect local modifications.");
+    warn("All existing files will be treated as locally modified and preserved.");
+    warn("Use --force-overwrite to override.");
   }
 
-  // Agent definitions (merge: add new agents, update existing, don't delete custom ones)
-  const agentsSrc = join(MAESTRO_ROOT, "agents");
-  if (existsSync(agentsSrc)) {
-    cpSync(agentsSrc, join(cwd, "agents"), { recursive: true, force: false });
-    ok("agents (merged, custom agents preserved)");
-    updated++;
+  const dirty = inGit ? dirtyPathSet(cwd) : null;
+  const ignorePatterns = loadMaestroignore(cwd);
+  if (ignorePatterns) {
+    log(`.maestroignore loaded (${ignorePatterns.length} pattern${ignorePatterns.length === 1 ? "" : "s"})`);
   }
 
-  // Teams
-  const teamsSrc = join(MAESTRO_ROOT, "teams");
-  if (existsSync(teamsSrc)) {
-    cpSync(teamsSrc, join(cwd, "teams"), { recursive: true, force: true });
-    ok("teams");
-    updated++;
+  const banner = flags.dryRun ? "DRY RUN — " : "";
+  log(`${banner}Upgrading framework files from @adaptic/maestro...`);
+
+  const counts = { added: 0, updated: 0, same: 0, ignored: 0, preserved: 0, mergeKept: 0, forced: 0 };
+  const preservedFiles = [];
+  const ignoredFiles = [];
+
+  for (const { path: relRoot, mode } of UPGRADE_PATHS) {
+    const srcRoot = join(MAESTRO_ROOT, relRoot);
+    const dstRoot = join(cwd, relRoot);
+    if (!existsSync(srcRoot)) continue;
+
+    const srcFiles = walkFiles(srcRoot);
+    for (const srcFile of srcFiles) {
+      const relFromRoot = relative(srcRoot, srcFile);
+      const dstFile = join(dstRoot, relFromRoot);
+      const repoRel = relative(cwd, dstFile).split(sep).join("/");
+
+      const isIgnored = matchesIgnore(repoRel, ignorePatterns);
+
+      // Case 0: .maestroignore match — never touch, regardless of state.
+      // Checked BEFORE existsSync so that protected new-files-from-upstream
+      // are never silently introduced into the agent repo either.
+      if (isIgnored) {
+        counts.ignored++;
+        ignoredFiles.push(repoRel);
+        if (flags.verbose) console.log(`  · ${repoRel} (ignored via .maestroignore)`);
+        continue;
+      }
+
+      // Case 1: new file (doesn't exist in agent) — always copy.
+      if (!existsSync(dstFile)) {
+        if (!flags.dryRun) {
+          mkdirSync(dirname(dstFile), { recursive: true });
+          copyFileSync(srcFile, dstFile);
+        }
+        counts.added++;
+        if (flags.verbose) ok(`+ ${repoRel}`);
+        continue;
+      }
+
+      // Case 2: byte-identical — nothing to do.
+      const srcHash = sha256File(srcFile);
+      const dstHash = sha256File(dstFile);
+      if (srcHash === dstHash) {
+        counts.same++;
+        if (flags.verbose) console.log(`  = ${repoRel}`);
+        continue;
+      }
+
+      // Case 3: merge-mode never overwrites existing files.
+      if (mode === "merge") {
+        counts.mergeKept++;
+        if (flags.verbose) console.log(`  ~ ${repoRel} (merge-mode, kept)`);
+        continue;
+      }
+
+      // Case 4: locally modified? Determine via git dirty set.
+      const locallyModified = inGit ? dirty.has(repoRel) : true;
+
+      if (locallyModified && !flags.forceOverwrite) {
+        counts.preserved++;
+        preservedFiles.push(repoRel);
+        if (!flags.dryRun && !flags.noIncoming) {
+          const shadow = join(cwd, ".maestro", "incoming", repoRel);
+          mkdirSync(dirname(shadow), { recursive: true });
+          copyFileSync(srcFile, shadow);
+        }
+        if (flags.verbose) console.log(`  ~ ${repoRel} (local edits, preserved)`);
+        continue;
+      }
+
+      // Case 5: overwrite (clean tracked file, or --force).
+      if (locallyModified && flags.forceOverwrite) {
+        // Back up the about-to-be-clobbered file.
+        if (!flags.dryRun) {
+          const backup = join(cwd, ".maestro", "backup", repoRel);
+          mkdirSync(dirname(backup), { recursive: true });
+          copyFileSync(dstFile, backup);
+        }
+        counts.forced++;
+        if (flags.verbose) warn(`! ${repoRel} (forced; backup written)`);
+      } else {
+        counts.updated++;
+        if (flags.verbose) console.log(`  > ${repoRel}`);
+      }
+      if (!flags.dryRun) {
+        mkdirSync(dirname(dstFile), { recursive: true });
+        copyFileSync(srcFile, dstFile);
+      }
+    }
   }
 
-  // Create any missing directories from the expanded list
+  // Ensure standard runtime directories exist.
   const ensureDirs = [
     "state/handoffs", "state/huddle", "state/indexes", "state/rag",
     "state/sessions", "state/slack-responded", "state/slack-thread-tracker",
@@ -739,15 +1008,33 @@ function upgrade() {
   for (const dir of ensureDirs) {
     const dirPath = join(cwd, dir);
     if (!existsSync(dirPath)) {
-      mkdirSync(dirPath, { recursive: true });
+      if (!flags.dryRun) mkdirSync(dirPath, { recursive: true });
       newDirs++;
     }
   }
-  if (newDirs > 0) ok(`Created ${newDirs} new directories`);
+
+  // Summary
+  console.log();
+  console.log(`${C.bold}Upgrade summary${C.reset}${flags.dryRun ? " (dry run, nothing written)" : ""}`);
+  if (counts.added)     ok(`${counts.added} added (new files)`);
+  if (counts.updated)   ok(`${counts.updated} updated (vendored, no local edits)`);
+  if (counts.same)      console.log(`  = ${counts.same} already up-to-date`);
+  if (counts.ignored)   console.log(`  · ${counts.ignored} ignored (.maestroignore protected)`);
+  if (counts.mergeKept) console.log(`  ~ ${counts.mergeKept} merge-mode kept (agents/ custom files preserved)`);
+  if (counts.preserved) warn(`${counts.preserved} preserved (local edits — kept your version)`);
+  if (counts.forced)    warn(`${counts.forced} force-overwritten (backups in .maestro/backup/)`);
+  if (newDirs)          ok(`${newDirs} new directories created`);
+
+  if (preservedFiles.length && !flags.noIncoming && !flags.dryRun) {
+    console.log();
+    log("Upstream versions of your locally-modified files saved to .maestro/incoming/");
+    log("Review with:  diff <path> .maestro/incoming/<path>");
+    for (const p of preservedFiles.slice(0, 5)) console.log(`    ${p}`);
+    if (preservedFiles.length > 5) console.log(`    … and ${preservedFiles.length - 5} more`);
+  }
 
   console.log();
-  ok(`Upgraded ${updated} framework components.`);
-  log("Agent-specific files (config/, CLAUDE.md, knowledge/, memory/) were NOT modified.");
+  log("Agent-specific paths (config/, CLAUDE.md, knowledge/, memory/, state/, outputs/, logs/, .env) were NOT touched.");
 }
 
 // ---------------------------------------------------------------------------
@@ -820,16 +1107,22 @@ const [, , command, ...args] = process.argv;
 
 switch (command) {
   case "create": create(args[0]); break;
-  case "upgrade": upgrade(); break;
+  case "upgrade": upgrade(args); break;
   case "doctor": doctor(); break;
   case "--help": case "-h": case undefined:
     console.log(`
 Maestro — Autonomous AI Agent Operating System
 
 Usage:
-  npx @adaptic/maestro create <dirname>   Create a new agent repo
-  npx @adaptic/maestro upgrade            Update framework files
-  npx @adaptic/maestro doctor             Verify installation
+  npx @adaptic/maestro create <dirname>           Create a new agent repo
+  npx @adaptic/maestro upgrade [--dry-run]        Update framework files
+  npx @adaptic/maestro doctor                     Verify installation
+
+Upgrade flags:
+  --dry-run, -n          Preview changes without writing
+  --force-overwrite      Overwrite even locally-modified files (backs them up)
+  --no-incoming          Don't write .maestro/incoming/ shadows
+  --verbose, -v          List classification for every file
 
 Workflow:
   1. npx @adaptic/maestro create my-agent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaptic/maestro",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "description": "Maestro — Autonomous AI agent operating system. Deploy AI employees on dedicated Mac minis.",
   "type": "module",
   "bin": {