@lifeaitools/clauth 1.7.1 → 1.8.0

package/README.md

@@ -72,20 +72,20 @@ clauth get github
 ```
 clauth install              Provision Supabase + install Claude skill
 clauth setup                Register this machine with the vault
-clauth status               All services + state
-clauth search <query>       Find services by name, project, description, or redacted address
-clauth test                 Verify connection
+clauth status               All services + state
+clauth search <query>       Find services by name, project, description, or redacted address
+clauth test                 Verify connection
 
 clauth write key <service>  Store a credential
 clauth write pw             Change password
 clauth enable <svc|all>     Activate service
 clauth disable <svc|all>    Suspend service
-clauth get <service>        Retrieve a key
-clauth npm whoami           Verify npm token without PowerShell secret plumbing
-clauth npm sync-github-secret LIFEAI/rdc-skills
-                            Update GitHub NPM_TOKEN from clauth
-
-clauth add service <n>      Register new service
+clauth get <service>        Retrieve a key
+clauth npm whoami           Verify npm token without PowerShell secret plumbing
+clauth npm sync-github-secret LIFEAI/rdc-skills
+                            Update GitHub NPM_TOKEN from clauth
+
+clauth add service <n>      Register new service
 clauth remove service <n>   Remove service
 clauth revoke <svc|all>     Delete key (destructive)
 ```
@@ -127,7 +127,7 @@ Full daemon operations reference: see `regen-root/.claude/rules/clauth.md`.
 
 ---
 
-## MCP Server — 3 Namespaces, 32 Tools
+## MCP Server — 3 Namespaces, 32 Tools
 
 clauth is the single MCP interface for all local tools. One process, namespaced paths:
 
@@ -135,18 +135,18 @@ clauth is the single MCP interface for all local tools. One process, namespaced
 |------|-----------|-------|-------------|
 | `/clauth` | `clauth_*` | 13 | Credential vault operations |
 | `/gws` | `gws_*` | 6 | Google Workspace (Gmail, Calendar, Drive) |
-| `/fs` | `fs_*` | 13 | Filesystem (read, write, append, chunked write, URL ingest, Git import, stat, grep, glob, delete, mkdir, mounts) |
-| `/mcp` | all | 32 | All namespaces combined (Claude Code) |
-
-### FS Tools
-
-13 filesystem tools with path-jail security:
-- `fs_read`, `fs_write`, `fs_stat`, `fs_append`, `fs_write_chunk`, `fs_ingest_url`, `fs_import_git_files`, `fs_list`, `fs_grep`, `fs_glob`, `fs_delete`, `fs_mkdir`, `fs_mounts`
-- Uses `node:fs/promises` (async), `@vscode/ripgrep` (shipped binary), `fast-glob`
-- Permission flags per mount: `r` (read), `w` (write), `d` (delete)
-- Mount config stored as "fileserver" service type in vault — only configurable through web UI
-- Large writes should use `fs_write_chunk`; cloud-to-local transfer should use `fs_ingest_url`; guarded appends should pass `expected_sha256` from `fs_stat`
-- Durable new files authored by Claude.ai in GitHub should use `fs_import_git_files` so the local dirty monorepo fetches and restores only named paths without `git pull`
+| `/fs` | `fs_*` | 13 | Filesystem (read, write, append, chunked write, URL ingest, Git import, stat, grep, glob, delete, mkdir, mounts) |
+| `/mcp` | all | 32 | All namespaces combined (Claude Code) |
+
+### FS Tools
+
+13 filesystem tools with path-jail security:
+- `fs_read`, `fs_write`, `fs_stat`, `fs_append`, `fs_write_chunk`, `fs_ingest_url`, `fs_import_git_files`, `fs_list`, `fs_grep`, `fs_glob`, `fs_delete`, `fs_mkdir`, `fs_mounts`
+- Uses `node:fs/promises` (async), `@vscode/ripgrep` (shipped binary), `fast-glob`
+- Permission flags per mount: `r` (read), `w` (write), `d` (delete)
+- Mount config stored as "fileserver" service type in vault — only configurable through web UI
+- Large writes should use `fs_write_chunk`; cloud-to-local transfer should use `fs_ingest_url`; guarded appends should pass `expected_sha256` from `fs_stat`
+- Durable new files authored by Claude.ai in GitHub should use `fs_import_git_files` so the local dirty monorepo fetches and restores only named paths without `git pull`
 
 ### GWS Tools
 
@@ -200,15 +200,34 @@ Tests actual MCP tool calls (not just OAuth + listing).
 
 ## Releasing a New Version (maintainers)
 
+Publishing is **manual** — there is no auto-publish. The GitHub Actions
+`publish.yml` workflow was removed on 2026-04-27 (commit `08b7751`); trusted
+publishing via OIDC was tried first (`b2bf08b`→`41d2d92`) and dropped. clauth is
+a **private** repo and GitHub Actions bill for minutes on private repos, so we
+don't run them here (reserve Actions for *public* repos, where they're free).
+
 ```bash
 # 1. Bump version in package.json
-# 2. Commit and tag
-git tag v1.5.38
+# 2. Commit + tag + push
+git add -A && git commit -m "feat(...): description (vX.Y.Z)"
+git tag vX.Y.Z
 git push && git push --tags
-# GitHub Actions publishes automatically via Trusted Publishing
+
+# 3. Publish manually with the vault npm token
+clauth npm set-local          # writes ~/.npmrc auth from the vault 'npm' service
+npm publish --access public
+
+# 4. Verify on the registry (direct check — bypasses npm's local cache)
+curl -s https://registry.npmjs.org/@lifeaitools/clauth \
+  | python -c "import sys,json;print(json.load(sys.stdin)['dist-tags'])"
+
+# 5. Update the running daemon
+curl -s -X POST http://127.0.0.1:52437/restart   # picks up new code, stays unlocked
 ```
 
-**NEVER** commit a version bump without tagging — the tag triggers npm CI.
+**The tag push does NOT publish anything** — you must run step 3. A version bump
+that is committed+tagged but never `npm publish`ed leaves the registry stale
+(symptom: `npm view` still shows the old version after a push).
 
 ---
 

package/cli/commands/npm.js

@@ -121,3 +121,62 @@ export async function runNpm(action = "help", opts = {}) {
   usage();
   throw new Error(`unknown clauth npm action: ${action}`);
 }
+
+// ── Guarded publish ──────────────────────────────────────────────────────────
+// Generic, package-agnostic publish that REFUSES to publish unless the package
+// is already committed and pushed to GitHub — so the npm tarball can never be
+// built from uncommitted "dev" code that isn't on the repo. Works for standalone
+// repos and monorepo subpackages (clean-check is scoped to the package's dir).
+export async function runPublish(target, opts = {}) {
+  const pkgDir = path.resolve(target || process.cwd());
+  const pkgJsonPath = path.join(pkgDir, "package.json");
+  if (!fs.existsSync(pkgJsonPath)) throw new Error(`No package.json found at ${pkgDir}`);
+  const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8"));
+  if (!pkg.name || !pkg.version) throw new Error(`package.json at ${pkgDir} is missing name or version`);
+  if (pkg.private === true) throw new Error(`${pkg.name} is marked "private": true — refusing to publish`);
+  const access = opts.access || pkg.publishConfig?.access || (pkg.name.startsWith("@") ? "public" : undefined);
+
+  const gitRoot = run("git", ["rev-parse", "--show-toplevel"], { cwd: pkgDir }).stdout?.trim();
+  if (!gitRoot) throw new Error(`${pkgDir} is not inside a git repository`);
+  const rel = path.relative(gitRoot, pkgDir) || ".";
+
+  // Guard 1 — nothing uncommitted in the package (else we'd pack dev code).
+  const dirty = run("git", ["status", "--porcelain", "--", rel], { cwd: gitRoot }).stdout?.trim();
+  if (dirty && !opts.allowDirty) {
+    throw new Error(`Refusing to publish ${pkg.name}@${pkg.version}: uncommitted changes in ${rel} would be packed but are NOT on GitHub:\n${dirty}\n\nCommit + push first (or pass --allow-dirty to override).`);
+  }
+
+  // Guard 2 — HEAD is on a remote (actually pushed to GitHub).
+  const head = run("git", ["rev-parse", "HEAD"], { cwd: gitRoot }).stdout?.trim();
+  const onRemote = run("git", ["branch", "-r", "--contains", head], { cwd: gitRoot }).stdout?.trim();
+  if (!onRemote && !opts.allowUnpushed) {
+    throw new Error(`Refusing to publish ${pkg.name}@${pkg.version}: HEAD ${head.slice(0, 9)} is not on any remote branch — push to GitHub first (or pass --allow-unpushed to override).`);
+  }
+
+  // Traceability — warn (don't block) if there's no v<version> tag at HEAD.
+  const tags = (run("git", ["tag", "--points-at", "HEAD"], { cwd: gitRoot }).stdout || "").split("\n").map((s) => s.trim()).filter(Boolean);
+  if (!tags.includes(`v${pkg.version}`)) {
+    console.log(`⚠  No git tag v${pkg.version} at HEAD (traceability only). Tags here: ${tags.join(", ") || "none"}`);
+  }
+
+  console.log(`${opts.dryRun ? "[dry-run] " : ""}Publishing ${pkg.name}@${pkg.version} from ${rel} @ ${head.slice(0, 9)} (pushed${access ? `, access=${access}` : ""})`);
+
+  const token = await fetchNpmToken();
+  const args = ["publish"];
+  if (access) args.push("--access", access);
+  if (opts.dryRun) args.push("--dry-run");
+  const result = withNpmAuth(token, (npmrc) => run("npm", ["--userconfig", npmrc, ...args], { cwd: pkgDir }));
+  printResult(result, { redact: true });
+  if (result.status !== 0) { process.exitCode = result.status; throw new Error(`npm publish failed for ${pkg.name}`); }
+  if (opts.dryRun) { console.log("Dry run complete — nothing published."); return; }
+
+  // Verify on the registry directly (bypasses npm's local cache lag).
+  try {
+    const reg = await fetch(`https://registry.npmjs.org/${pkg.name}`);
+    const meta = await reg.json();
+    if (meta.versions?.[pkg.version]) console.log(`✓ Verified ${pkg.name}@${pkg.version} on the registry (latest: ${meta["dist-tags"]?.latest}).`);
+    else console.log(`⚠  ${pkg.name}@${pkg.version} not visible on the registry yet (propagation lag) — re-check shortly.`);
+  } catch (e) {
+    console.log(`(could not verify on registry: ${e.message})`);
+  }
+}

package/cli/commands/serve.js

@@ -784,6 +784,7 @@ function dashboardHtml(port, whitelist, isStaged = false) {
     <button class="btn-add" onclick="toggleAddService()">+ Add Service</button>
     <button class="btn-check" id="check-btn" onclick="checkAll()">⬤ Check All</button>
     <button class="btn-ccandme" id="ccandme-btn" onclick="launchCCandMe()" title="Launch CCandMe — 4-pane WezTerm: Claude + Codex + Me">⚡ CCandMe</button>
+    <button class="btn-lock" id="unlock-writes-btn" onclick="unlockWrites()" title="Enter password to enable saving changes this browser session (needed after a daemon restart when auto-unlocked via --pw)">🔓 Unlock Writes</button>
     <button class="btn-lock" onclick="lockVault()">🔒 Lock</button>
     <button class="btn-stop" onclick="restartDaemon()" style="background:#1a2e1a;border:1px solid #166534;color:#86efac" title="Restart daemon — keeps vault unlocked">↺ Restart</button>
     <button class="btn-stop" onclick="stopDaemon()" style="background:#7f1d1d;border:1px solid #991b1b;color:#fca5a5" title="Stop daemon — password required on next start">⏹ Stop</button>
@@ -1090,6 +1091,7 @@ function showMain(ping) {
   }
   pollTunnel();
   updateBuildStatus();
+  refreshWriteLockUi();
 }
 
 // ── Unlock ──────────────────────────────────
@@ -1151,6 +1153,34 @@ async function lockVault() {
   showLockScreen(r.hard_locked || false);
 }
 
+// ── Unlock writes (re-establish write scope without locking) ──
+// Needed when the daemon auto-unlocks via --pw/boot.key: the page never sees the
+// unlock screen, so it holds no write token. POST /auth mints one (10-min TTL).
+async function unlockWrites() {
+  if (writeToken && !confirm("Writes are already unlocked this session. Re-unlock?")) return;
+  const pw = prompt("Enter your vault password to enable saving changes (10-minute write session):");
+  if (!pw) return;
+  try {
+    const r = await fetch(BASE + "/auth", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ password: pw }),
+    }).then(r => r.json());
+    if (r.error) { alert("Unlock failed: " + r.error); return; }
+    writeToken = r.write_token || null;
+    refreshWriteLockUi();
+    alert(writeToken ? "Writes unlocked for 10 minutes." : "Unlock did not return a write token.");
+  } catch (e) { alert("Unlock error: " + (e.message || e)); }
+}
+
+// Reflect write-lock state on the button so it is obvious when a save will fail.
+function refreshWriteLockUi() {
+  const b = document.getElementById("unlock-writes-btn");
+  if (!b) return;
+  if (writeToken) { b.textContent = "🔓 Writes On"; b.style.opacity = "0.6"; b.style.borderColor = ""; }
+  else { b.textContent = "🔓 Unlock Writes"; b.style.opacity = "1"; b.style.borderColor = "#f59e0b"; }
+}
+
 // ── Make Live (blue-green: promote staged instance to live port) ──
 async function makeLive() {
   if (!confirm("Promote this staged instance to live?\\n\\nThe current live daemon (port ${LIVE_PORT}) will be stopped and this instance will restart on port ${LIVE_PORT}.")) return;
@@ -7251,19 +7281,35 @@ const MCP_TOOLS = [
   },
   {
     name: "fs_commit",
-    description: "Save the files you edited durably: stages changes, commits, and PUSHES by default — usually a single call is all you need after editing. Handles the messy cases for you: nothing-to-commit returns cleanly (no error); a merge/rebase in progress or a detached HEAD is refused with a clear message; if the branch is behind the remote it auto-rebases and retries the push, and on conflict it aborts the rebase (restoring your tree) and keeps the commit local so nothing is lost. Refuses to push protected branches (main/master/production) — those are promoted by a human. Returns the commit sha, the exact files committed, whether the push succeeded, and ahead/behind counts, so you never need a follow-up status call. Push auth uses the vault's github token directly (never exposed). Requires 'g' (git) access on the mount.",
+    description: "Commit and push to GitHub: stages changes, commits, and PUSHES by default — usually a single call is all you need after editing. Handles the messy cases: nothing-to-commit returns cleanly (no error); a merge/rebase in progress or a detached HEAD is refused with a clear message; if the branch is behind the remote it auto-rebases and retries the push, and on conflict it aborts the rebase (restoring your tree) and keeps the commit local so nothing is lost. Refuses to push protected branches (main/master/production) — those are promoted by a human. Returns the commit sha, the exact files committed, whether the push succeeded, and ahead/behind counts, so you never need a follow-up status call. Set dry_run=true first to preview what WOULD be committed/pushed without doing it. Set expected_head to refuse committing if the base moved under you. Push auth uses the vault github token directly (never exposed). Requires 'g' (git) access on the mount.",
     inputSchema: {
       type: "object",
       properties: {
-        message: { type: "string", description: "Commit message (required)" },
+        message: { type: "string", description: "Commit message. Required for a real commit; optional when dry_run=true." },
         paths: { type: "array", items: { type: "string" }, description: "Repo-relative paths to commit. Omit to commit ALL current changes in the repo." },
         push: { type: "boolean", description: "Push to the remote after committing (default true)" },
+        dry_run: { type: "boolean", description: "Preview only: returns the branch, the files that would be committed, and whether/where it would push — without staging, committing, or pushing. Use to confirm before a real push." },
+        expected_head: { type: "string", description: "Optimistic-concurrency guard: the commit SHA you believe HEAD is on. If HEAD has moved, the commit is refused so you don't build on a stale base." },
         remote: { type: "string", description: "Git remote name (default: origin)" },
         author_name: { type: "string", description: "Commit author name (default: clauth-fs)" },
         author_email: { type: "string", description: "Commit author email (default: fs@clauth.local)" },
         mount: { type: "string", description: "Mount name (default: first mount)" },
       },
-      required: ["message"],
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_diff",
+    description: "Show the unified diff of your changes so you can self-verify BEFORE committing/pushing — essential after large or multi-step edits. Default compares the working tree to the last commit (HEAD). Pass ref (e.g. 'origin/develop') to compare against a remote branch and catch staleness — i.e. see exactly how your working tree differs from what's on the remote, in one call. Pass staged=true to see only what's staged. Returns a --stat summary plus the patch (capped at 60KB; `truncated` flags when hit). Requires 'g' (git) access on the mount.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        paths: { type: "array", items: { type: "string" }, description: "Repo-relative paths to limit the diff to. Omit for all changes." },
+        ref: { type: "string", description: "Compare the working tree against this ref instead of HEAD (e.g. 'origin/develop', a tag, or a commit sha). Use for remote/staleness comparison." },
+        staged: { type: "boolean", description: "Show only staged changes (index vs HEAD) instead of the full working-tree diff." },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+      },
       additionalProperties: false,
     },
   },
@@ -8213,7 +8259,13 @@ async function handleMcpTool(vault, name, args) {
       const { mounts, error } = await getFileserverMounts(vault);
       if (error) return mcpError(error);
       if (!mounts || mounts.length === 0) return mcpResult("No fileserver mounts configured. Create one:\n1. Use clauth dashboard or clauth_enable to add a service with key_type='fileserver'\n2. Set the secret value to JSON: {\"path\": \"C:/Dev/regen-root\", \"access\": \"rwdg\"}  (add 'g' to allow the git verbs: fs_commit, fs_use_branch, fs_repo_status)");
-      return mcpResult(JSON.stringify(mounts, null, 2));
+      // Decode the access string so callers know what's possible BEFORE trying —
+      // notably `git` (the git verbs require it; absent = explain how to enable).
+      const decorated = mounts.map((m) => {
+        const a = String(m.access || "");
+        return { ...m, can: { read: a.includes("r"), write: a.includes("w"), delete: a.includes("d"), git: a.includes("g") } };
+      });
+      return mcpResult(JSON.stringify(decorated, null, 2));
     }
 
     case "fs_repo_status": {
@@ -8247,10 +8299,11 @@ async function handleMcpTool(vault, name, args) {
       if (r.error) return mcpError(r.error);
       if (!checkAccess(r.mount, "g")) return mcpError("Git access denied on this mount. Add 'g' to the mount's access string (e.g. 'rwdg') to enable the git verbs.");
       const push = args.push !== false;
+      const dryRun = args.dry_run === true;
       // Fetch the push token from the vault up front (commit happens first, so
-      // a missing token still preserves the local commit).
+      // a missing token still preserves the local commit). Skipped on dry-run.
       let token = null, tokenError = null;
-      if (push) {
+      if (push && !dryRun) {
         const sec = await vaultRetrieveValue(vault, "github");
         if (sec.error || !sec.value) tokenError = `could not read the 'github' token (${sec.error || "empty"})`;
         else token = sec.value;
@@ -8260,6 +8313,8 @@ async function handleMcpTool(vault, name, args) {
           message: args.message,
           paths: args.paths,
           push,
+          dryRun,
+          expectedHead: args.expected_head,
           remote: args.remote,
           token,
           tokenError,
@@ -8273,6 +8328,19 @@ async function handleMcpTool(vault, name, args) {
       }
     }
 
+    case "fs_diff": {
+      const r = await resolveInMount(".", args.mount, vault);
+      if (r.error) return mcpError(r.error);
+      if (!checkAccess(r.mount, "g")) return mcpError("Git access denied on this mount. Add 'g' to the mount's access string (e.g. 'rwdg') to enable the git verbs.");
+      try {
+        const { result, error } = await fsGit.diff(r.resolved, { paths: args.paths, ref: args.ref, staged: args.staged === true });
+        if (error) return mcpError(error);
+        return mcpResult(JSON.stringify(result, null, 2));
+      } catch (err) {
+        return mcpError(`Diff failed: ${err.message}`);
+      }
+    }
+
     case "monkey_dispatch": {
       const { prompt, job_id } = args;
       if (!prompt) return mcpError("prompt required");

package/cli/index.js

@@ -150,7 +150,7 @@ import { runUninstall } from './commands/uninstall.js';
 import { runScrub } from './commands/scrub.js';
 import { runServe } from './commands/serve.js';
 import { runCodevelop } from './commands/codevelop.js';
-import { runNpm } from './commands/npm.js';
+import { runNpm, runPublish } from './commands/npm.js';
 
 program
   .command('install')
@@ -229,6 +229,27 @@ program
     await runNpm(action, { ...opts, args });
   });
 
+// ──────────────────────────────────────────────
+// clauth publish [target]
+// Guarded npm publish for ANY package — refuses to ship code that isn't
+// committed AND pushed to GitHub (prevents npm/repo divergence from dev builds).
+// ──────────────────────────────────────────────
+program
+  .command("publish [target]")
+  .description("Safely publish an npm package (default: cwd). Refuses unless committed + pushed to GitHub.")
+  .option("--dry-run", "Run all guards and pack, but do not publish")
+  .option("--access <access>", "npm access: public | restricted")
+  .option("--allow-dirty", "Override the uncommitted-changes guard (NOT recommended)")
+  .option("--allow-unpushed", "Override the not-pushed-to-remote guard (NOT recommended)")
+  .action(async (target, opts) => {
+    try {
+      await runPublish(target, opts);
+    } catch (err) {
+      console.error(chalk.red(err.message));
+      process.exitCode = 1;
+    }
+  });
+
 // ──────────────────────────────────────────────
 // clauth setup
 // ──────────────────────────────────────────────

package/cli/lib/fs-git.js

@@ -138,7 +138,7 @@ export async function useBranch(repoRoot, branch, create) {
  */
 export async function commit(repoRoot, opts = {}) {
   const message = (opts.message || "").trim();
-  if (!message) return { error: "message is required" };
+  if (!message && !opts.dryRun) return { error: "message is required" };
   const push = opts.push !== false;
   const remote = opts.remote || "origin";
 
@@ -151,16 +151,43 @@ export async function commit(repoRoot, opts = {}) {
   const branch = await runGitAsync(repoRoot, ["rev-parse", "--abbrev-ref", "HEAD"]);
   if (branch === "HEAD") return { error: "Refused: detached HEAD. Use fs_use_branch to get on a branch first." };
 
-  // Stage
+  // Optional optimistic-concurrency guard: refuse if the base moved under us.
+  if (opts.expectedHead) {
+    const cur = await runGitAsync(repoRoot, ["rev-parse", "HEAD"]);
+    if (cur !== opts.expectedHead) {
+      return { error: `Base moved: expected HEAD ${opts.expectedHead} but current is ${cur}. Re-read the files and retry so you don't commit on top of a base that changed.` };
+    }
+  }
+
+  // Normalize explicit paths once (used by dry-run preview and staging).
+  let pathArgs = [];
   if (Array.isArray(opts.paths) && opts.paths.length > 0) {
     if (opts.paths.length > 100) return { error: "Too many paths: max 100 per commit" };
-    const norm = [];
     for (const p of opts.paths) {
       const n = normalizeRepoPath(p);
       if (!n) return { error: `Invalid repo path: ${p}` };
-      norm.push(n);
+      pathArgs.push(n);
     }
-    await runGitAsync(repoRoot, ["add", "--", ...norm]);
+  }
+
+  // Dry run: report what WOULD be committed/pushed without mutating anything.
+  if (opts.dryRun) {
+    const tail = pathArgs.length ? ["--", ...pathArgs] : [];
+    // Mirror `git add -A`: tracked changes (diff vs HEAD) ∪ untracked files.
+    const tracked = await runGitAsync(repoRoot, ["diff", "--name-only", "HEAD", ...tail]);
+    const untracked = await runGitAsync(repoRoot, ["ls-files", "--others", "--exclude-standard", ...tail]);
+    const files = [...new Set(
+      [...(tracked ? tracked.split("\n") : []), ...(untracked ? untracked.split("\n") : [])]
+        .map((s) => s.trim()).filter(Boolean)
+    )];
+    const { ahead, behind } = await aheadBehind(repoRoot);
+    const isProtected = FS_GIT_PROTECTED_BRANCHES.has(branch.toLowerCase());
+    return { result: { status: "dry_run", branch, would_commit: files, file_count: files.length, would_push: push && !isProtected, protected_branch: isProtected, target: push && !isProtected ? `${remote}/${branch}` : null, ahead, behind } };
+  }
+
+  // Stage
+  if (pathArgs.length) {
+    await runGitAsync(repoRoot, ["add", "--", ...pathArgs]);
   } else {
     await runGitAsync(repoRoot, ["add", "-A"]);
   }
@@ -215,3 +242,41 @@ export async function commit(repoRoot, opts = {}) {
   const { ahead, behind } = await aheadBehind(repoRoot);
   return { result: { status: "committed_and_pushed", branch, commit: finalSha, commit_short: finalShort, files: committedFiles, pushed: true, remote, ahead, behind, message: `Committed and pushed ${committedFiles.length} file(s) to ${remote}/${branch} as ${finalShort}.` } };
 }
+
+/**
+ * Unified diff of the working tree (or index) — self-verify before pushing, or
+ * compare against a remote ref to catch staleness.
+ * opts: { paths?, ref?, staged? }
+ *   - default:      working tree vs HEAD (everything uncommitted)
+ *   - ref:"origin/x": working tree vs that ref (remote compare / staleness)
+ *   - staged:true:  index vs HEAD (only what's staged)
+ * Patch is capped; `truncated` flags when the cap was hit.
+ */
+export async function diff(repoRoot, opts = {}) {
+  const MAX = 60000;
+  let pathArgs = [];
+  if (Array.isArray(opts.paths) && opts.paths.length > 0) {
+    for (const p of opts.paths) {
+      const n = normalizeRepoPath(p);
+      if (!n) return { error: `Invalid repo path: ${p}` };
+      pathArgs.push(n);
+    }
+  }
+  const flags = [];
+  if (opts.staged) flags.push("--cached");
+  const ref = opts.ref || (opts.staged ? null : "HEAD");
+  if (ref) flags.push(ref);
+  const tail = pathArgs.length ? ["--", ...pathArgs] : [];
+
+  // Validate ref up front so a typo yields a clean error, not a raw git failure.
+  if (ref && ref !== "HEAD") {
+    try { await runGitAsync(repoRoot, ["rev-parse", "--verify", "--quiet", ref + "^{commit}"]); }
+    catch { return { error: `Unknown ref: ${opts.ref} (try fetching it first, e.g. origin/<branch>)` }; }
+  }
+
+  const stat = await runGitAsync(repoRoot, ["diff", ...flags, "--stat", ...tail]);
+  let patch = await runGitAsync(repoRoot, ["diff", ...flags, ...tail]);
+  let truncated = false;
+  if (patch.length > MAX) { patch = patch.slice(0, MAX) + "\n... (diff truncated at 60KB)"; truncated = true; }
+  return { result: { compared_to: ref || "index", staged: !!opts.staged, stat: stat || "(no differences)", patch: patch || "(no differences)", truncated } };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/clauth",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Hardware-bound credential vault for the LIFEAI infrastructure stack",
   "type": "module",
   "bin": {