zam-core 0.4.0 → 0.4.1

package/.agents/skills/zam/SKILL.md

@@ -326,7 +326,7 @@ The `capture-ui` command supports:
 
 On Windows, uses PowerShell/.NET for screen capture. On macOS, uses `screencapture`.
 
-**Observer permissions (Layer 2, ADR-0001).** `capture-ui` enforces a
+**Observer permissions (Layer 2).** `capture-ui` enforces a
 user-configurable policy resolved from `zam settings`: `observer.scope`
 (`off` | `window` | `fullscreen`), `observer.allowlist`, `observer.denylist`,
 `observer.consent`, `observer.retention`. Set them with e.g.

package/README.de.md

@@ -63,6 +63,25 @@ Einstieg: `zam whoami --set <deine-id>`
 
 ---
 
+## 🔄 ZAM aktuell halten
+
+Prüfe, ob eine neuere Version vorliegt, und aktualisiere — ZAM wählt den passenden Mechanismus je nachdem, wie diese Kopie installiert wurde:
+
+```bash
+zam update          # neueste Version anwenden (fragt nach; -y überspringt)
+zam update check    # nur prüfen, ob ein Update verfügbar ist
+```
+
+Was `zam update` je nach Installationskanal tut:
+
+- **Developer** (Quell-Checkout, Standard für Mitwirkende) — holt den neuesten Quellcode, installiert Abhängigkeiten neu, baut die CLI und frischt die Skill-Dateien auf (`zam setup --force`). Danach den Agent-Client (z. B. Claude Code) neu starten, damit der aktualisierte `/zam`-Skill geladen wird.
+- **winget / Homebrew** — delegiert an `winget upgrade` / `brew upgrade`, damit eine paketverwaltete Installation nie selbst ersetzt wird.
+- **Direkt-Download / Desktop** — installiert ein signiertes In-place-Update über ZAM Desktop.
+
+`zam update` verweigert einen Developer-Checkout mit uncommitteten Änderungen; committe oder stashe sie zuerst, oder nutze `--force`. Design-Details: [ADR „Approachable Setup and Self-Update“](docs/adr/2026-06-13b-approachable-setup-and-self-update.md).
+
+---
+
 ## 🏛 Vision: Eine paradiesische Zukunft
 
 ZAM ist das Werkzeug für den Übergang in eine Welt, in der Fürsorge und gemeinsames Wachstum die Währung sind.

package/README.md

@@ -83,6 +83,25 @@ Token deletion is global. Card deletion is per-user.
 
 ---
 
+## 🔄 Keeping ZAM up to date
+
+Check whether a newer release is out, then update — ZAM picks the right mechanism for how this copy was installed:
+
+```bash
+zam update          # apply the latest release (asks first; -y to skip)
+zam update check    # only report whether an update is available
+```
+
+What `zam update` does per install channel:
+
+- **Developer** (source checkout, the default for contributors) — pulls the latest source, reinstalls dependencies, rebuilds the CLI, and refreshes the skill files (`zam setup --force`) in the current instance. Restart your agent client (e.g. Claude Code) afterwards to load the refreshed `/zam` skill.
+- **winget / Homebrew** — defers to `winget upgrade` / `brew upgrade`, so a package-managed install is never self-replaced.
+- **Direct download / desktop** — applies a signed in-place update through ZAM Desktop.
+
+`zam update` refuses to touch a developer checkout with uncommitted changes; commit or stash them first, or pass `--force`. See the [“Approachable Setup and Self-Update” ADR](docs/adr/2026-06-13b-approachable-setup-and-self-update.md) for the design.
+
+---
+
 ## 🏛 Vision: A Flourishing Future
 
 ZAM is a tool for the transition to a world where care and shared growth are the common currency.

package/dist/cli/index.js

@@ -4847,6 +4847,37 @@ function decideUpdate(input8) {
       };
   }
 }
+function planUpdate(decision) {
+  if (!decision.updateAvailable) return [];
+  switch (decision.channel) {
+    case "developer":
+      return [
+        { kind: "git-pull", label: "Pull the latest source" },
+        { kind: "npm-install", label: "Install dependencies" },
+        { kind: "npm-build", label: "Rebuild the CLI" },
+        {
+          kind: "distribute-skills",
+          label: "Refresh skill files (zam setup --force)"
+        }
+      ];
+    case "winget":
+    case "homebrew":
+      return [
+        {
+          kind: "run-command",
+          label: `Update via ${decision.channel}`,
+          command: decision.command
+        }
+      ];
+    case "direct":
+      return [
+        {
+          kind: "self-update",
+          label: "Apply the signed update via the desktop app"
+        }
+      ];
+  }
+}
 
 // src/cli/commands/agent.ts
 var C = {
@@ -5267,8 +5298,8 @@ async function startLocalRunner(url, model, locale) {
       process.stdout.write("\n");
       console.log(`\x1B[33m${t(locale, "wait_warning")}\x1B[0m`);
       console.log(`\x1B[2m${t(locale, "wait_info")}\x1B[0m`);
-      const { confirm: confirm4 } = await import("@inquirer/prompts");
-      const keepWaiting = await confirm4({
+      const { confirm: confirm5 } = await import("@inquirer/prompts");
+      const keepWaiting = await confirm5({
         message: t(locale, "keep_waiting_llm"),
         default: true
       }).catch(() => false);
@@ -5412,8 +5443,8 @@ async function fetchWithInteractiveTimeout(url, options = {}) {
       }
       console.log(`
 \x1B[33m${t(locale, "local_ai_working")}\x1B[0m`);
-      const { confirm: confirm4 } = await import("@inquirer/prompts");
-      const keepWaiting = await confirm4({
+      const { confirm: confirm5 } = await import("@inquirer/prompts");
+      const keepWaiting = await confirm5({
         message: t(locale, "keep_waiting"),
         default: true
       }).catch(() => false);
@@ -10603,9 +10634,11 @@ ${C3.dim}After that, 'zam ui' launches it directly.${C3.reset}`
 });
 
 // src/cli/commands/update.ts
-import { readFileSync as readFileSync13 } from "fs";
+import { spawnSync as spawnSync2 } from "child_process";
+import { existsSync as existsSync20, readFileSync as readFileSync13, realpathSync } from "fs";
 import { dirname as dirname9, join as join20 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
+import { confirm as confirm3 } from "@inquirer/prompts";
 import { Command as Command21 } from "commander";
 var GITHUB_REPO = "zam-os/zam";
 var CHANNELS = [
@@ -10620,6 +10653,7 @@ var C4 = {
   cyan: "\x1B[36m",
   dim: "\x1B[2m",
   green: "\x1B[32m",
+  red: "\x1B[31m",
   yellow: "\x1B[33m"
 };
 function currentVersion() {
@@ -10635,6 +10669,16 @@ function currentVersion() {
   }
   return "0.0.0";
 }
+function versionAt(dir) {
+  try {
+    const pkg2 = JSON.parse(
+      readFileSync13(join20(dir, "package.json"), "utf-8")
+    );
+    return pkg2.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
 async function fetchLatestVersion(repo) {
   const res = await fetch(
     `https://api.github.com/repos/${repo}/releases/latest`,
@@ -10704,7 +10748,150 @@ var checkCmd = new Command21("check").description("Check whether a newer ZAM has
     }
   }
 );
-var updateCommand = new Command21("update").description("Check for ZAM updates").addCommand(checkCmd);
+function findSourceRepo() {
+  let dir = realpathSync(dirname9(fileURLToPath4(import.meta.url)));
+  let parent = dirname9(dir);
+  while (parent !== dir) {
+    if (existsSync20(join20(dir, ".git"))) return dir;
+    dir = parent;
+    parent = dirname9(dir);
+  }
+  return existsSync20(join20(dir, ".git")) ? dir : null;
+}
+function runGit(cwd, args, capture) {
+  const res = spawnSync2("git", args, {
+    cwd,
+    stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit",
+    encoding: "utf8"
+  });
+  return { ok: res.status === 0, out: (res.stdout ?? "").trim() };
+}
+function runNpm2(args, cwd) {
+  const res = spawnSync2("npm", args, {
+    cwd,
+    stdio: "inherit",
+    shell: process.platform === "win32"
+  });
+  return res.status ?? 1;
+}
+function runShell(command) {
+  const res = spawnSync2(command, { stdio: "inherit", shell: true });
+  return res.status === 0;
+}
+function applyDeveloperUpdate(force) {
+  if (!hasCommand("git")) {
+    console.error(`${C4.red}\u2717${C4.reset} git was not found on PATH.`);
+    process.exit(1);
+  }
+  const src = findSourceRepo();
+  if (!src) {
+    console.error(
+      `${C4.red}\u2717${C4.reset} Could not locate the ZAM source checkout to update.`
+    );
+    process.exit(1);
+  }
+  const status = runGit(src, ["status", "--porcelain"], true);
+  if (status.ok && status.out && !force) {
+    console.error(
+      `${C4.red}\u2717${C4.reset} The source checkout has uncommitted changes:
+${status.out}
+Commit or stash them, or re-run with ${C4.cyan}--force${C4.reset}.`
+    );
+    process.exit(1);
+  }
+  console.log(
+    `${C4.dim}\u2192 git pull --ff-only${C4.reset}  ${C4.dim}(${src})${C4.reset}`
+  );
+  if (!runGit(src, ["pull", "--ff-only"], false).ok) {
+    console.error(
+      `${C4.red}\u2717${C4.reset} git pull failed \u2014 the branch may have diverged or you are offline. Resolve it manually, then retry.`
+    );
+    process.exit(1);
+  }
+  console.log(`${C4.dim}\u2192 npm install${C4.reset}`);
+  if (runNpm2(["install"], src) !== 0) {
+    console.error(`${C4.red}\u2717${C4.reset} npm install failed.`);
+    process.exit(1);
+  }
+  console.log(`${C4.dim}\u2192 npm run build${C4.reset}`);
+  if (runNpm2(["run", "build"], src) !== 0) {
+    console.error(`${C4.red}\u2717${C4.reset} Build failed.`);
+    process.exit(1);
+  }
+  console.log(`${C4.dim}\u2192 zam setup --force${C4.reset}`);
+  const setup = spawnSync2(
+    process.execPath,
+    [join20(src, "dist", "cli", "index.js"), "setup", "--force"],
+    { cwd: process.cwd(), stdio: "inherit" }
+  );
+  if (setup.status !== 0) {
+    console.warn(
+      `${C4.yellow}\u26A0${C4.reset} Skill refresh reported a problem \u2014 run '${C4.cyan}zam setup --force${C4.reset}' here manually.`
+    );
+  }
+  console.log(
+    `
+${C4.green}\u2713${C4.reset} Updated to ${C4.cyan}${versionAt(src)}${C4.reset}. Restart your agent client (e.g. Claude Code) to load the refreshed ${C4.cyan}/zam${C4.reset} skill.`
+  );
+}
+async function applyUpdate(opts) {
+  try {
+    const current = currentVersion();
+    const latest = await fetchLatestVersion(GITHUB_REPO);
+    const channel = getInstallChannel();
+    const decision = decideUpdate({
+      currentVersion: current,
+      latestVersion: latest,
+      channel
+    });
+    if (!decision.updateAvailable) {
+      console.log(
+        `${C4.green}\u2713${C4.reset} ZAM is up to date (${C4.cyan}${current}${C4.reset}).`
+      );
+      return;
+    }
+    console.log(
+      `${C4.yellow}\u2191${C4.reset} ${C4.bold}Update available${C4.reset}: ${C4.dim}${current}${C4.reset} \u2192 ${C4.cyan}${latest}${C4.reset} ${C4.dim}(${channel} install)${C4.reset}`
+    );
+    for (const step of planUpdate(decision)) {
+      console.log(`  ${C4.dim}\u2022${C4.reset} ${step.label}`);
+    }
+    if (channel === "direct") {
+      console.log(
+        `
+${C4.dim}This install updates through the desktop app's signed updater \u2014 open ZAM Desktop to install ${latest}.${C4.reset}`
+      );
+      return;
+    }
+    if (!opts.yes) {
+      const ok = await confirm3({
+        message: "Apply this update?",
+        default: true
+      });
+      if (!ok) {
+        console.log("Aborted.");
+        return;
+      }
+    }
+    console.log();
+    if (channel === "winget" || channel === "homebrew") {
+      if (!decision.command || !runShell(decision.command)) process.exit(1);
+      return;
+    }
+    applyDeveloperUpdate(opts.force ?? false);
+  } catch (err) {
+    console.error("Error:", err.message);
+    process.exit(1);
+  }
+}
+var updateCommand = new Command21("update").description(
+  "Update ZAM to the latest release (use `update check` to only check)"
+).option("-y, --yes", "Apply without confirmation").option(
+  "--force",
+  "Update even if the source checkout has uncommitted changes"
+).action(async (opts) => {
+  await applyUpdate(opts);
+}).addCommand(checkCmd);
 
 // src/cli/commands/whoami.ts
 import { Command as Command22 } from "commander";
@@ -10745,11 +10932,11 @@ var whoamiCommand = new Command22("whoami").description("Show or set the default
 
 // src/cli/commands/workspace.ts
 import { execSync as execSync6 } from "child_process";
-import { existsSync as existsSync20, writeFileSync as writeFileSync11 } from "fs";
+import { existsSync as existsSync21, writeFileSync as writeFileSync11 } from "fs";
 import { join as join21 } from "path";
-import { confirm as confirm3, input as input7 } from "@inquirer/prompts";
+import { confirm as confirm4, input as input7 } from "@inquirer/prompts";
 import { Command as Command23 } from "commander";
-function runGit(cwd, args) {
+function runGit2(cwd, args) {
   try {
     return execSync6(`git ${args}`, {
       cwd,
@@ -10779,7 +10966,7 @@ workspaceCommand.command("publish").description("Publish your local workspace sa
     );
     process.exit(1);
   }
-  if (!existsSync20(workspaceDir)) {
+  if (!existsSync21(workspaceDir)) {
     console.error(
       `\x1B[31m\u2717 Workspace directory does not exist: ${workspaceDir}\x1B[0m`
     );
@@ -10794,19 +10981,19 @@ Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
     process.exit(1);
   }
   const gitignorePath = join21(workspaceDir, ".gitignore");
-  if (!existsSync20(gitignorePath)) {
+  if (!existsSync21(gitignorePath)) {
     writeFileSync11(
       gitignorePath,
       "node_modules/\n.agent/\n.agents/\n.claude/\n.gemini/\n.goose/\n*.log\n",
       "utf8"
     );
   }
-  const hasGitRepo = existsSync20(join21(workspaceDir, ".git"));
+  const hasGitRepo = existsSync21(join21(workspaceDir, ".git"));
   if (!hasGitRepo) {
     console.log("Initializing local Git repository...");
-    runGit(workspaceDir, "init -b main");
-    runGit(workspaceDir, "add .");
-    runGit(
+    runGit2(workspaceDir, "init -b main");
+    runGit2(workspaceDir, "add .");
+    runGit2(
       workspaceDir,
       'commit -m "chore: initial workspace sandbox bootstrap"'
     );
@@ -10818,14 +11005,14 @@ Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
     message: "Choose a name for your GitHub repository:",
     default: "zam-personal"
   });
-  const isPrivate = await confirm3({
+  const isPrivate = await confirm4({
     message: "Should the repository be private?",
     default: true
   });
   const repoVisibility = isPrivate ? "--private" : "--public";
   if (hasCommand("gh")) {
     console.log("GitHub CLI detected! Automating repository creation...");
-    const proceedGh = await confirm3({
+    const proceedGh = await confirm4({
       message: "Would you like ZAM to create the repository using the GitHub CLI?",
       default: true
     });
@@ -10870,16 +11057,16 @@ Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
       console.log("Linking remote repository and pushing...");
       let hasOrigin = false;
       try {
-        runGit(workspaceDir, "remote get-url origin");
+        runGit2(workspaceDir, "remote get-url origin");
         hasOrigin = true;
       } catch {
       }
       if (hasOrigin) {
-        runGit(workspaceDir, `remote set-url origin ${githubUrl}`);
+        runGit2(workspaceDir, `remote set-url origin ${githubUrl}`);
       } else {
-        runGit(workspaceDir, `remote add origin ${githubUrl}`);
+        runGit2(workspaceDir, `remote add origin ${githubUrl}`);
       }
-      runGit(workspaceDir, "push -u origin main");
+      runGit2(workspaceDir, "push -u origin main");
       console.log(
         "\x1B[32m\u2713 Successfully linked and pushed to GitHub!\x1B[0m"
       );