hermes-git 0.3.0 → 0.3.2

package/README.md

@@ -42,6 +42,8 @@ hermes wip
 
 No magic. Every command shows exactly what git operations it runs.
 
+Run `hermes` with no arguments to see the full command reference and available workflows.
+
 ---
 
 ## Installation
@@ -78,7 +80,7 @@ hermes config set provider gemini
 hermes config set gemini-key AIza...
 ```
 
-Verify it worked:
+Verify:
 
 ```bash
 hermes config list
@@ -93,7 +95,7 @@ hermes config list
 npm install -g hermes-git
 hermes config setup
 
-# 2. Initialize your project (optional, enables team config sharing)
+# 2. Initialize your project (optional — enables team config sharing)
 cd your-project
 hermes init
 
@@ -105,13 +107,26 @@ hermes start "user authentication"
 
 ## Commands
 
+### `hermes update`
+
+Update hermes to the latest version.
+
+```bash
+hermes update           # check and install if a newer version exists
+hermes update --check   # check only, don't install
+```
+
+Auto-detects your package manager (npm, bun, or pnpm).
+
+---
+
 ### `hermes config`
 
 Manage API keys and provider settings.
 
 ```bash
-hermes config setup              # Interactive wizard
-hermes config list               # Show current config (keys masked)
+hermes config setup              # interactive wizard
+hermes config list               # show current config (keys masked, sources shown)
 hermes config set provider openai
 hermes config set openai-key sk-...
 hermes config get provider
@@ -122,6 +137,52 @@ Config is stored in `~/.config/hermes/config.json`. You can also use environment
 
 ---
 
+### `hermes guard`
+
+Scan staged files for secrets and sensitive content before committing.
+
+```bash
+hermes guard
+```
+
+Scans every staged file for:
+
+- **Sensitive filenames** — `.env`, `id_rsa`, `*.pem`, `credentials.json`, `google-services.json`, etc.
+- **API keys** — Anthropic, OpenAI, Google, AWS, GitHub, Stripe, SendGrid, Twilio
+- **Private key headers** — `-----BEGIN PRIVATE KEY-----` and variants
+- **Database URLs** with embedded credentials — `postgres://user:pass@host`
+- **Hardcoded passwords/tokens** — common assignment patterns
+
+Findings are categorised as `BLOCKED` (definite secret) or `WARN` (suspicious). The AI explains each finding and what to do about it, then you choose: abort, unstage the flagged files, or proceed anyway.
+
+```
+  BLOCKED  src/config.ts
+           ● Anthropic API key  line 12
+             apiKey: "sk-a...****",
+             Rotate at: https://console.anthropic.com/settings/keys
+
+  What this means:
+  This key gives anyone with repo access full billing access to your
+  Anthropic account. Rotate it immediately and load it from an
+  environment variable instead.
+
+  ? Blocked secrets found. What do you want to do?
+  ❯ Abort — I will fix these before committing
+    Unstage the flagged files and continue
+    Proceed anyway (I know what I'm doing)
+```
+
+**Install as a git pre-commit hook** so it runs automatically on every commit:
+
+```bash
+hermes guard install-hook    # installs to .git/hooks/pre-commit
+hermes guard uninstall-hook  # removes it
+```
+
+In hook mode the scan is non-interactive: prints findings to stderr and exits 1 on any blocker.
+
+---
+
 ### `hermes plan "<intent>"`
 
 Analyze repo state and propose a safe Git plan. **Makes no changes.**
@@ -154,7 +215,7 @@ hermes sync
 hermes sync --from develop
 ```
 
-Hermes evaluates whether rebase or merge is safer given your branch state and explains before executing.
+Evaluates whether rebase or merge is safer given your branch state and explains before executing.
 
 ---
 
@@ -197,15 +258,17 @@ For each file: shows a proposed resolution, lets you accept, edit manually, or s
 
 ### `hermes workflow <name>`
 
-One-command workflows for common patterns.
+One-command workflows for common patterns. Available workflows are shown when you run `hermes` with no arguments.
 
 ```bash
 hermes workflow pr-ready      # fetch → rebase → push --force-with-lease
 hermes workflow daily-sync    # fetch all → show status → suggest next action
 hermes workflow quick-commit  # generate commit message from staged diff
-hermes workflow list          # show available workflows
+hermes workflow list          # show all workflows including project-specific
 ```
 
+Define project-specific workflows in `.hermes/config.json` and they appear automatically in the help output.
+
 ---
 
 ### `hermes worktree new "<task>"`
@@ -224,8 +287,8 @@ hermes worktree new "fix memory leak"
 Initialize project-level config (`.hermes/config.json`). Commit this to share branch patterns and workflows with your team.
 
 ```bash
-hermes init         # Interactive
-hermes init --quick # Use defaults
+hermes init         # interactive
+hermes init --quick # use defaults
 ```
 
 ---
@@ -252,6 +315,8 @@ Hermes resolves config in this priority order:
 | `.env` file in current dir | `ANTHROPIC_API_KEY=sk-ant-...` |
 | `~/.config/hermes/config.json` | set via `hermes config set` |
 
+Environment variables always win — useful for CI and Docker environments where you don't want a config file.
+
 **Supported env vars:**
 
 | Variable | Description |
@@ -277,9 +342,9 @@ If `HERMES_PROVIDER` is not set, Hermes auto-detects by using whichever key it f
 
 1. **Reads your repo state** — branch, commits, dirty files, conflicts, remote tracking
 2. **Sends context + intent to an AI** — using your configured provider
-3. **Validates the response** — all returned commands must start with `git`, destructive flags are blocked
+3. **Validates the response** — all returned commands must start with `git`; destructive flags are blocked
 4. **Executes with display** — shows every command before running it
-5. **You always stay in control** — interactive prompts for anything irreversible
+5. **You stay in control** — interactive prompts for anything irreversible
 
 ---
 
@@ -301,30 +366,23 @@ If `HERMES_PROVIDER` is not set, Hermes auto-detects by using whichever key it f
 hermes config setup
 ```
 
-**Wrong provider selected**
+**Wrong provider being used**
 
 ```bash
 hermes config set provider anthropic
-hermes config list   # verify
+hermes config list   # check sources — env vars override saved config
 ```
 
-**Key saved but not working**
+**Key set but not working**
 
 ```bash
-# Check what Hermes sees
-hermes config list
-
-# Environment variables override saved config
-# Check for conflicting vars:
-echo $ANTHROPIC_API_KEY
+hermes config list   # shows value and where it came from (env / .env / config)
 ```
 
-**General debugging**
+**Update to latest**
 
 ```bash
-hermes --version
-hermes config list
-git status
+hermes update
 ```
 
 ---

package/dist/index.js

@@ -38120,18 +38120,635 @@ Valid keys:`));
   }
 }
 
-// src/lib/update-notifier.ts
-import { readFile as readFile5, writeFile as writeFile5, mkdir as mkdir4 } from "fs/promises";
+// src/commands/guard.ts
+import { writeFile as writeFile5, readFile as readFile5, chmod as chmod2, mkdir as mkdir4 } from "fs/promises";
 import { existsSync as existsSync5 } from "fs";
+import { exec as exec4 } from "child_process";
+import { promisify as promisify4 } from "util";
+
+// src/lib/secrets.ts
+import { exec as exec3 } from "child_process";
+import { promisify as promisify3 } from "util";
+var execAsync3 = promisify3(exec3);
+var BLOCKED_FILENAMES = [
+  { pattern: /^\.env$/, description: "Environment variable file" },
+  { pattern: /^\.env\..+/, description: "Environment variable file" },
+  { pattern: /id_rsa$/, description: "SSH private key" },
+  { pattern: /id_ed25519$/, description: "SSH private key" },
+  { pattern: /id_ecdsa$/, description: "SSH private key" },
+  { pattern: /id_dsa$/, description: "SSH private key" },
+  { pattern: /\.pem$/, description: "PEM certificate/key file" },
+  { pattern: /\.p12$/, description: "PKCS#12 certificate file" },
+  { pattern: /\.pfx$/, description: "PKCS#12 certificate file" },
+  { pattern: /\.jks$/, description: "Java keystore file" },
+  { pattern: /\.keystore$/, description: "Keystore file" },
+  { pattern: /credentials\.json$/, description: "Credentials file" },
+  { pattern: /google-services\.json$/, description: "Google services config (may contain API keys)" },
+  { pattern: /firebase-adminsdk.*\.json$/, description: "Firebase admin SDK credentials" },
+  { pattern: /serviceAccountKey.*\.json$/, description: "Service account credentials" },
+  { pattern: /\.netrc$/, description: ".netrc credentials file" }
+];
+var WARNED_FILENAMES = [
+  { pattern: /\.npmrc$/, description: ".npmrc (may contain auth tokens)" },
+  { pattern: /\.pypirc$/, description: ".pypirc (may contain PyPI token)" },
+  { pattern: /secrets?\.(json|yaml|yml|toml)$/, description: "Secrets config file" },
+  { pattern: /config\.(local|private|secret)\.(json|yaml|yml|toml|js|ts)$/, description: "Local/private config file" },
+  { pattern: /private.*\.(json|yaml|yml|toml)$/, description: "Private config file" }
+];
+var SECRET_PATTERNS = [
+  {
+    id: "private-key",
+    description: "Private key header",
+    severity: "blocked",
+    pattern: /-----BEGIN\s+(RSA\s+|EC\s+|OPENSSH\s+|DSA\s+)?PRIVATE KEY-----/
+  },
+  {
+    id: "anthropic-key",
+    description: "Anthropic API key",
+    severity: "blocked",
+    pattern: /sk-ant-[a-zA-Z0-9_-]{80,}/,
+    rotation: "https://console.anthropic.com/settings/keys"
+  },
+  {
+    id: "openai-key",
+    description: "OpenAI API key",
+    severity: "blocked",
+    pattern: /sk-(?:proj-)?[a-zA-Z0-9]{40,}/,
+    rotation: "https://platform.openai.com/api-keys"
+  },
+  {
+    id: "google-api-key",
+    description: "Google API key",
+    severity: "blocked",
+    pattern: /AIza[a-zA-Z0-9_-]{35}/,
+    rotation: "https://console.cloud.google.com/apis/credentials"
+  },
+  {
+    id: "aws-access-key",
+    description: "AWS access key ID",
+    severity: "blocked",
+    pattern: /AKIA[A-Z0-9]{16}/,
+    rotation: "https://console.aws.amazon.com/iam/home#/security_credentials"
+  },
+  {
+    id: "aws-secret-key",
+    description: "AWS secret access key",
+    severity: "blocked",
+    pattern: /aws[_-]?secret[_-]?access[_-]?key\s*[=:]\s*["']?[a-zA-Z0-9/+]{40}/i,
+    rotation: "https://console.aws.amazon.com/iam/home#/security_credentials"
+  },
+  {
+    id: "github-token",
+    description: "GitHub personal access token",
+    severity: "blocked",
+    pattern: /gh[pousr]_[a-zA-Z0-9]{36}/,
+    rotation: "https://github.com/settings/tokens"
+  },
+  {
+    id: "github-pat-v2",
+    description: "GitHub fine-grained personal access token",
+    severity: "blocked",
+    pattern: /github_pat_[a-zA-Z0-9_]{82}/,
+    rotation: "https://github.com/settings/tokens"
+  },
+  {
+    id: "stripe-key",
+    description: "Stripe secret key",
+    severity: "blocked",
+    pattern: /(?:sk|rk)_live_[a-zA-Z0-9]{24,}/,
+    rotation: "https://dashboard.stripe.com/apikeys"
+  },
+  {
+    id: "sendgrid-key",
+    description: "SendGrid API key",
+    severity: "blocked",
+    pattern: /SG\.[a-zA-Z0-9_-]{22}\.[a-zA-Z0-9_-]{43}/,
+    rotation: "https://app.sendgrid.com/settings/api_keys"
+  },
+  {
+    id: "twilio-key",
+    description: "Twilio API key",
+    severity: "blocked",
+    pattern: /SK[a-f0-9]{32}/,
+    rotation: "https://www.twilio.com/console/project/api-keys"
+  },
+  {
+    id: "db-url",
+    description: "Database URL with credentials",
+    severity: "blocked",
+    pattern: /(?:mongodb(?:\+srv)?|postgres(?:ql)?|mysql|redis):\/\/[^:/?#\s]+:[^@\s]+@/
+  },
+  {
+    id: "password-assignment",
+    description: "Hardcoded password",
+    severity: "warn",
+    pattern: /(?:password|passwd|pwd)\s*[=:]\s*["'][^"']{6,}["']/i
+  },
+  {
+    id: "secret-assignment",
+    description: "Hardcoded secret",
+    severity: "warn",
+    pattern: /(?:secret|api_secret|client_secret)\s*[=:]\s*["'][^"']{8,}["']/i
+  },
+  {
+    id: "token-assignment",
+    description: "Hardcoded token",
+    severity: "warn",
+    pattern: /(?<![a-z])token\s*[=:]\s*["'][a-zA-Z0-9_\-\.]{16,}["']/i
+  }
+];
+async function getStagedFiles() {
+  const { stdout } = await execAsync3("git diff --cached --name-only --diff-filter=ACMR");
+  return stdout.trim().split(`
+`).filter(Boolean);
+}
+async function readStagedFile(file) {
+  try {
+    const { stdout } = await execAsync3(`git show ":${file}"`, {
+      maxBuffer: 2 * 1024 * 1024
+    });
+    return stdout;
+  } catch {
+    return null;
+  }
+}
+function checkFilename(file) {
+  const basename = file.split("/").pop() || file;
+  for (const { pattern, description } of BLOCKED_FILENAMES) {
+    if (pattern.test(basename)) {
+      return {
+        patternId: "filename-blocked",
+        description: `Sensitive filename: ${description}`,
+        severity: "blocked",
+        line: 0,
+        preview: file
+      };
+    }
+  }
+  for (const { pattern, description } of WARNED_FILENAMES) {
+    if (pattern.test(basename)) {
+      return {
+        patternId: "filename-warned",
+        description: `Potentially sensitive filename: ${description}`,
+        severity: "warn",
+        line: 0,
+        preview: file
+      };
+    }
+  }
+  return null;
+}
+function scanContent(content) {
+  const lines2 = content.split(`
+`);
+  const findings = [];
+  const seen = new Set;
+  for (let i = 0;i < lines2.length; i++) {
+    const line = lines2[i];
+    for (const sp of SECRET_PATTERNS) {
+      if (sp.pattern.test(line)) {
+        const dedupeKey = `${sp.id}:${i}`;
+        if (seen.has(dedupeKey))
+          continue;
+        seen.add(dedupeKey);
+        findings.push({
+          patternId: sp.id,
+          description: sp.description,
+          severity: sp.severity,
+          line: i + 1,
+          preview: redactLine(line, sp.pattern),
+          rotation: sp.rotation
+        });
+      }
+    }
+  }
+  return findings;
+}
+function redactLine(line, pattern) {
+  const redacted = line.replace(pattern, (match) => {
+    if (match.length <= 8)
+      return "****";
+    return match.slice(0, 4) + "..." + match.slice(-4).replace(/./g, "*");
+  });
+  return redacted.length > 120 ? redacted.slice(0, 117) + "..." : redacted;
+}
+async function scanStagedFiles() {
+  const files = await getStagedFiles();
+  const result = { blocked: [], warned: [], clean: [], skipped: [] };
+  await Promise.all(files.map(async (file) => {
+    const allFindings = [];
+    const filenameFindig = checkFilename(file);
+    if (filenameFindig)
+      allFindings.push(filenameFindig);
+    const content = await readStagedFile(file);
+    if (content === null) {
+      result.skipped.push(file);
+      return;
+    }
+    allFindings.push(...scanContent(content));
+    if (allFindings.length === 0) {
+      result.clean.push(file);
+      return;
+    }
+    const maxSeverity = allFindings.some((f) => f.severity === "blocked") ? "blocked" : "warn";
+    const fileFindings = { file, findings: allFindings, maxSeverity };
+    if (maxSeverity === "blocked") {
+      result.blocked.push(fileFindings);
+    } else {
+      result.warned.push(fileFindings);
+    }
+  }));
+  return result;
+}
+
+// src/commands/guard.ts
+var execAsync4 = promisify4(exec4);
+function guardCommand(program2) {
+  const guard = program2.command("guard").description("Scan staged files for secrets and sensitive content before committing");
+  guard.option("--hook", "Run in non-interactive hook mode (exit 1 on blockers)").action(async (options) => {
+    await runScan(options.hook ?? false);
+  });
+  guard.command("install-hook").description("Install hermes guard as a git pre-commit hook").action(async () => {
+    try {
+      const gitDir = await execAsync4("git rev-parse --git-dir").then((r) => r.stdout.trim()).catch(() => null);
+      if (!gitDir) {
+        console.error(source_default.red("❌ Not a git repository"));
+        process.exit(1);
+      }
+      const hooksDir = `${gitDir}/hooks`;
+      await mkdir4(hooksDir, { recursive: true });
+      const hookPath = `${hooksDir}/pre-commit`;
+      const hookScript = [
+        "#!/bin/sh",
+        "# Installed by hermes guard install-hook",
+        "hermes guard --hook"
+      ].join(`
+`) + `
+`;
+      if (existsSync5(hookPath)) {
+        const existing = await readFile5(hookPath, "utf-8");
+        if (existing.includes("hermes guard")) {
+          console.log(source_default.dim("Hook already installed."));
+          return;
+        }
+        await writeFile5(hookPath, existing.trimEnd() + `
+
+` + hookScript.split(`
+`).slice(1).join(`
+`));
+      } else {
+        await writeFile5(hookPath, hookScript);
+      }
+      await chmod2(hookPath, 493);
+      console.log(`${source_default.green("✓")} Pre-commit hook installed at ${source_default.dim(hookPath)}`);
+      console.log(source_default.dim("  hermes guard will run automatically before every commit."));
+    } catch (error3) {
+      console.error("❌ Error:", error3 instanceof Error ? error3.message : error3);
+      process.exit(1);
+    }
+  });
+  guard.command("uninstall-hook").description("Remove hermes guard from the git pre-commit hook").action(async () => {
+    try {
+      const gitDir = await execAsync4("git rev-parse --git-dir").then((r) => r.stdout.trim()).catch(() => null);
+      if (!gitDir) {
+        console.error(source_default.red("❌ Not a git repository"));
+        process.exit(1);
+      }
+      const hookPath = `${gitDir}/hooks/pre-commit`;
+      if (!existsSync5(hookPath)) {
+        console.log(source_default.dim("No pre-commit hook found."));
+        return;
+      }
+      const content = await readFile5(hookPath, "utf-8");
+      if (!content.includes("hermes guard")) {
+        console.log(source_default.dim("hermes guard is not in the pre-commit hook."));
+        return;
+      }
+      const cleaned = content.split(`
+`).filter((line) => !line.includes("hermes guard") && line !== "# Installed by hermes guard install-hook").join(`
+`).replace(/\n{3,}/g, `
+
+`).trim() + `
+`;
+      if (cleaned === `#!/bin/sh
+`) {
+        const { unlink } = await import("fs/promises");
+        await unlink(hookPath);
+        console.log(`${source_default.green("✓")} Pre-commit hook removed.`);
+      } else {
+        await writeFile5(hookPath, cleaned);
+        console.log(`${source_default.green("✓")} hermes guard removed from pre-commit hook.`);
+      }
+    } catch (error3) {
+      console.error("❌ Error:", error3 instanceof Error ? error3.message : error3);
+      process.exit(1);
+    }
+  });
+}
+async function runScan(hookMode) {
+  try {
+    const staged = await getStagedFiles();
+    if (staged.length === 0) {
+      if (!hookMode)
+        console.log(source_default.dim("No staged files to scan."));
+      return;
+    }
+    if (!hookMode) {
+      console.log(source_default.bold(`
+  Scanning ${staged.length} staged file${staged.length === 1 ? "" : "s"}...
+`));
+    }
+    const result = await scanStagedFiles();
+    const hasBlockers = result.blocked.length > 0;
+    const hasWarnings = result.warned.length > 0;
+    if (!hasBlockers && !hasWarnings) {
+      if (!hookMode) {
+        console.log(source_default.green("  ✓ All clear") + source_default.dim(` — ${staged.length} file${staged.length === 1 ? "" : "s"} scanned, nothing suspicious found.
+`));
+      }
+      return;
+    }
+    if (!hookMode) {
+      printReport(result);
+    } else {
+      if (hasBlockers) {
+        process.stderr.write(source_default.red(`
+  hermes guard: ${result.blocked.length} blocked file${result.blocked.length === 1 ? "" : "s"} with secrets detected.
+`));
+        for (const f of result.blocked) {
+          process.stderr.write(source_default.dim(`    ${f.file}: ${f.findings.map((x) => x.description).join(", ")}
+`));
+        }
+        process.stderr.write(source_default.dim(`
+  Run \`hermes guard\` for details and remediation advice.
+
+`));
+      }
+    }
+    if (!hookMode && (hasBlockers || hasWarnings)) {
+      await printAIExplanation(result);
+      if (hasBlockers) {
+        const { action } = await esm_default12.prompt([
+          {
+            type: "list",
+            name: "action",
+            message: source_default.red("Blocked secrets found. What do you want to do?"),
+            choices: [
+              { name: "Abort — I will fix these before committing", value: "abort" },
+              { name: "Unstage the flagged files and continue", value: "unstage" },
+              { name: "Proceed anyway (I know what I'm doing)", value: "proceed" }
+            ],
+            default: "abort"
+          }
+        ]);
+        if (action === "abort") {
+          console.log(source_default.dim(`
+  Commit aborted. Fix the issues above, then try again.
+`));
+          process.exit(1);
+        }
+        if (action === "unstage") {
+          for (const f of result.blocked) {
+            await execAsync4(`git restore --staged "${f.file}"`);
+            console.log(source_default.dim(`  Unstaged: ${f.file}`));
+          }
+          console.log(source_default.yellow(`
+  Flagged files have been unstaged. Commit the rest? (run git commit again)`));
+          process.exit(0);
+        }
+        console.log(source_default.dim(`
+  Proceeding. Be careful.
+`));
+      } else if (hasWarnings) {
+        const { proceed } = await esm_default12.prompt([
+          {
+            type: "confirm",
+            name: "proceed",
+            message: source_default.yellow("Warnings found. Proceed with commit?"),
+            default: true
+          }
+        ]);
+        if (!proceed) {
+          console.log(source_default.dim(`
+  Commit aborted.
+`));
+          process.exit(1);
+        }
+      }
+    }
+    if (hookMode && hasBlockers) {
+      process.exit(1);
+    }
+  } catch (error3) {
+    if (!hookMode) {
+      console.error(source_default.dim("  guard scan failed:"), error3 instanceof Error ? error3.message : error3);
+    }
+    process.exit(0);
+  }
+}
+function printReport(result) {
+  const totalFiles = result.blocked.length + result.warned.length + result.clean.length + result.skipped.length;
+  if (result.blocked.length > 0) {
+    console.log(source_default.red.bold("  ✖ Secrets detected") + source_default.dim(` — review before committing
+`));
+  } else {
+    console.log(source_default.yellow.bold("  ⚠ Warnings") + source_default.dim(` — review before committing
+`));
+  }
+  for (const ff of result.blocked) {
+    console.log(source_default.red(`  BLOCKED  `) + source_default.bold(ff.file));
+    for (const f of ff.findings) {
+      const lineRef = f.line > 0 ? source_default.dim(` line ${f.line}`) : "";
+      console.log(source_default.dim("           ") + source_default.red("●") + " " + f.description + lineRef);
+      if (f.preview && f.line > 0) {
+        console.log(source_default.dim("             " + f.preview.trim()));
+      }
+      if (f.rotation) {
+        console.log(source_default.dim(`             Rotate at: ${f.rotation}`));
+      }
+    }
+    console.log();
+  }
+  for (const ff of result.warned) {
+    console.log(source_default.yellow(`  WARN     `) + source_default.bold(ff.file));
+    for (const f of ff.findings) {
+      const lineRef = f.line > 0 ? source_default.dim(` line ${f.line}`) : "";
+      console.log(source_default.dim("           ") + source_default.yellow("●") + " " + f.description + lineRef);
+      if (f.preview && f.line > 0) {
+        console.log(source_default.dim("             " + f.preview.trim()));
+      }
+    }
+    console.log();
+  }
+  if (result.clean.length > 0) {
+    console.log(source_default.dim(`  ✓ ${result.clean.length} file${result.clean.length === 1 ? "" : "s"} clean`));
+  }
+  if (result.skipped.length > 0) {
+    console.log(source_default.dim(`  − ${result.skipped.length} binary/unreadable file${result.skipped.length === 1 ? "" : "s"} skipped`));
+  }
+  console.log();
+}
+async function printAIExplanation(result) {
+  const allFindings = [...result.blocked, ...result.warned];
+  if (allFindings.length === 0)
+    return;
+  const findingSummary = allFindings.map((ff) => {
+    const items = ff.findings.map((f) => `  - ${f.description}${f.line > 0 ? ` (line ${f.line})` : ""}`).join(`
+`);
+    return `File: ${ff.file}
+Severity: ${ff.maxSeverity}
+${items}`;
+  }).join(`
+
+`);
+  process.stdout.write(source_default.dim("  Asking AI for context...\r"));
+  try {
+    const explanation = await getAISuggestion(`A developer is about to commit these files that were flagged by a secret scanner:
+
+${findingSummary}
+
+For each finding, briefly explain:
+1. The specific risk if this gets committed (e.g., "Anyone with repo access can use this key to...")
+2. One concrete remediation step (e.g., "Add .env to .gitignore and use process.env instead")
+
+Be direct and specific. 3-4 sentences per finding max. No preamble.`);
+    process.stdout.write("                                    \r");
+    console.log(source_default.bold(`  What this means:
+`));
+    const indented = explanation.split(`
+`).map((l) => "  " + l).join(`
+`);
+    console.log(indented);
+    console.log();
+  } catch {
+    process.stdout.write("                                    \r");
+  }
+}
+
+// src/commands/update.ts
+import { exec as exec5 } from "child_process";
+import { promisify as promisify5 } from "util";
+var execAsync5 = promisify5(exec5);
+var PACKAGE_NAME = "hermes-git";
+function updateCommand(program2, currentVersion) {
+  program2.command("update").description("Update hermes to the latest version").option("--check", "Check for updates without installing").option("--bun", "Use bun instead of npm to install").action(async (options) => {
+    try {
+      process.stdout.write(source_default.dim("  Checking npm for latest version..."));
+      const latest = await fetchLatestVersion();
+      process.stdout.write("\r" + " ".repeat(50) + "\r");
+      if (!latest) {
+        console.error(source_default.red("  ✖ Could not reach npm registry. Check your connection."));
+        process.exit(1);
+      }
+      const isNewer = compareVersions(latest, currentVersion) > 0;
+      const isAhead = compareVersions(currentVersion, latest) > 0;
+      if (!isNewer) {
+        if (isAhead) {
+          console.log(source_default.green("  ✓ ") + `You're running ${source_default.cyan(`v${currentVersion}`)} ` + source_default.dim(`(latest on npm is ${latest})`));
+        } else {
+          console.log(source_default.green(`  ✓ Already on the latest version`) + source_default.dim(` (v${currentVersion})`));
+        }
+        return;
+      }
+      console.log(`  Update available  ${source_default.dim(currentVersion)} ${source_default.dim("→")} ${source_default.green.bold(latest)}
+`);
+      if (options.check)
+        return;
+      const pm = options.bun ? "bun" : await detectPackageManager();
+      const installCmd = buildInstallCommand(pm);
+      console.log(`  Running: ${source_default.cyan(installCmd)}
+`);
+      const { stdout, stderr } = await execAsync5(installCmd, { timeout: 120000 });
+      const output = (stdout + stderr).trim();
+      if (output) {
+        output.split(`
+`).forEach((line) => {
+          console.log(source_default.dim("  " + line));
+        });
+        console.log();
+      }
+      console.log(source_default.green("  ✓ Updated to ") + source_default.bold(`v${latest}`) + source_default.dim("  Restart your terminal if the version does not change."));
+    } catch (error3) {
+      console.error(source_default.red(`
+  ✖ Update failed`));
+      console.error(source_default.dim("  " + (error3.message || error3)));
+      console.log(source_default.dim(`
+  Try manually: npm install -g ${PACKAGE_NAME}@latest`));
+      process.exit(1);
+    }
+  });
+}
+async function fetchLatestVersion() {
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`);
+    if (!res.ok)
+      return null;
+    const data = await res.json();
+    return data.version ?? null;
+  } catch {
+    return null;
+  }
+}
+function compareVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0;i < 3; i++) {
+    if (pa[i] > pb[i])
+      return 1;
+    if (pa[i] < pb[i])
+      return -1;
+  }
+  return 0;
+}
+async function detectPackageManager() {
+  if (process.execPath?.includes("bun") || process.argv[0]?.includes("bun")) {
+    return "bun";
+  }
+  try {
+    const { stdout } = await execAsync5("bun --version", { timeout: 3000 });
+    if (stdout.trim()) {
+      try {
+        const { stdout: list } = await execAsync5("bun pm ls -g 2>/dev/null", { timeout: 3000 });
+        if (list.includes(PACKAGE_NAME))
+          return "bun";
+      } catch {}
+    }
+  } catch {}
+  try {
+    const { stdout } = await execAsync5("pnpm --version", { timeout: 3000 });
+    if (stdout.trim()) {
+      try {
+        const { stdout: list } = await execAsync5("pnpm list -g --depth=0 2>/dev/null", { timeout: 3000 });
+        if (list.includes(PACKAGE_NAME))
+          return "pnpm";
+      } catch {}
+    }
+  } catch {}
+  return "npm";
+}
+function buildInstallCommand(pm) {
+  switch (pm) {
+    case "bun":
+      return `bun add -g ${PACKAGE_NAME}@latest`;
+    case "pnpm":
+      return `pnpm add -g ${PACKAGE_NAME}@latest`;
+    default:
+      return `npm install -g ${PACKAGE_NAME}@latest`;
+  }
+}
+
+// src/lib/update-notifier.ts
+import { readFile as readFile6, writeFile as writeFile6, mkdir as mkdir5 } from "fs/promises";
+import { existsSync as existsSync6 } from "fs";
 import { homedir as homedir2 } from "os";
 import path5 from "path";
-var PACKAGE_NAME = "hermes-git";
+var PACKAGE_NAME2 = "hermes-git";
 var CHECK_INTERVAL = 24 * 60 * 60 * 1000;
 var CACHE_DIR = path5.join(homedir2(), ".hermes", "cache");
 var CACHE_FILE = path5.join(CACHE_DIR, "update-check.json");
 async function getLatestVersion() {
   try {
-    const response = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`);
+    const response = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME2}/latest`);
     if (!response.ok)
       return null;
     const data = await response.json();
@@ -38142,9 +38759,9 @@ async function getLatestVersion() {
 }
 async function readCache() {
   try {
-    if (!existsSync5(CACHE_FILE))
+    if (!existsSync6(CACHE_FILE))
       return null;
-    const content = await readFile5(CACHE_FILE, "utf-8");
+    const content = await readFile6(CACHE_FILE, "utf-8");
     return JSON.parse(content);
   } catch {
     return null;
@@ -38152,8 +38769,8 @@ async function readCache() {
 }
 async function writeCache(cache) {
   try {
-    await mkdir4(CACHE_DIR, { recursive: true });
-    await writeFile5(CACHE_FILE, JSON.stringify(cache, null, 2));
+    await mkdir5(CACHE_DIR, { recursive: true });
+    await writeFile6(CACHE_FILE, JSON.stringify(cache, null, 2));
   } catch {}
 }
 function isNewerVersion(current, latest) {
@@ -38191,10 +38808,93 @@ async function checkForUpdates(currentVersion) {
   } catch {}
 }
 
+// src/lib/banner.ts
+import { readFileSync, existsSync as existsSync7 } from "fs";
+var ART_LINES = [
+  "██╗  ██╗███████╗██████╗ ███╗   ███╗███████╗███████╗",
+  "██║  ██║██╔════╝██╔══██╗████╗ ████║██╔════╝██╔════╝",
+  "███████║█████╗  ██████╔╝██╔████╔██║█████╗  ███████╗",
+  "██╔══██║██╔══╝  ██╔══██╗██║╚██╔╝██║██╔══╝  ╚════██║",
+  "██║  ██║███████╗██║  ██║██║ ╚═╝ ██║███████╗███████║",
+  "╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝╚══════╝╚══════╝"
+];
+var ROW_COLORS = [
+  (s) => source_default.bold.cyanBright(s),
+  (s) => source_default.bold.cyanBright(s),
+  (s) => source_default.bold.cyan(s),
+  (s) => source_default.bold.cyan(s),
+  (s) => source_default.cyan(s),
+  (s) => source_default.dim.cyan(s)
+];
+var ART_WIDTH = 52;
+function printBanner(version) {
+  const wings = source_default.dim.cyan("~>))><");
+  const tail = source_default.dim.cyan("><((<~");
+  console.log();
+  console.log(`  ${wings}${"─".repeat(ART_WIDTH - 14)}${tail}`);
+  for (let i = 0;i < ART_LINES.length; i++) {
+    console.log("  " + ROW_COLORS[i](ART_LINES[i]));
+  }
+  const subtitle = "intent-driven git";
+  const versionLabel = source_default.dim(`v${version}`);
+  const dot = source_default.dim("·");
+  const padding = " ".repeat(Math.max(0, Math.floor((ART_WIDTH - subtitle.length - version.length - 4) / 2)));
+  console.log();
+  console.log(`  ${padding}${source_default.dim(subtitle)}  ${dot}  ${versionLabel}`);
+  console.log(`  ${wings}${"─".repeat(ART_WIDTH - 14)}${tail}`);
+  console.log();
+}
+var BUILTIN_WORKFLOWS = [
+  { name: "pr-ready", description: "Sync, rebase, push — ready for pull request" },
+  { name: "daily-sync", description: "Fetch + status check to start the day" },
+  { name: "quick-commit", description: "Stage changes and commit with AI message" }
+];
+function loadProjectWorkflows() {
+  try {
+    if (!existsSync7(".hermes/config.json"))
+      return [];
+    const config = JSON.parse(readFileSync(".hermes/config.json", "utf-8"));
+    const workflows = config?.workflows;
+    if (!workflows || typeof workflows !== "object")
+      return [];
+    return Object.entries(workflows).filter(([name]) => !BUILTIN_WORKFLOWS.some((b) => b.name === name)).map(([name, steps]) => ({
+      name,
+      description: Array.isArray(steps) ? steps.join(" → ") : String(steps),
+      custom: true
+    }));
+  } catch {
+    return [];
+  }
+}
+function printWorkflows() {
+  const project = loadProjectWorkflows();
+  const all = [...BUILTIN_WORKFLOWS, ...project];
+  const nameWidth = Math.max(...all.map((w) => w.name.length)) + 2;
+  console.log(source_default.bold("  Workflows"));
+  console.log();
+  for (const w of BUILTIN_WORKFLOWS) {
+    const cmd = source_default.cyan(`hermes workflow ${w.name.padEnd(nameWidth)}`);
+    console.log(`    ${cmd}  ${source_default.dim(w.description)}`);
+  }
+  if (project.length > 0) {
+    console.log();
+    console.log(source_default.dim("  Project-specific:"));
+    for (const w of project) {
+      const cmd = source_default.cyan(`hermes workflow ${w.name.padEnd(nameWidth)}`);
+      console.log(`    ${cmd}  ${source_default.dim(w.description)}`);
+    }
+  }
+  console.log();
+}
+
 // src/index.ts
 var program2 = new Command;
-var CURRENT_VERSION = "0.3.0";
-program2.name("hermes").description("\uD83E\uDEBD Intent-driven Git, guided by AI").version(CURRENT_VERSION);
+var CURRENT_VERSION = "0.3.2";
+program2.name("hermes").description("Intent-driven Git, guided by AI").version(CURRENT_VERSION).action(() => {
+  printBanner(CURRENT_VERSION);
+  printWorkflows();
+  program2.help();
+});
 initCommand(program2);
 planCommand(program2);
 startCommand(program2);
@@ -38205,5 +38905,7 @@ worktreeCommand(program2);
 statsCommand(program2);
 workflowCommand(program2);
 configCommand(program2);
+guardCommand(program2);
+updateCommand(program2, CURRENT_VERSION);
 checkForUpdates(CURRENT_VERSION).catch(() => {});
 program2.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hermes-git",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Intent-driven Git, guided by AI. Turn natural language into safe, explainable Git operations.",
   "type": "module",
   "main": "./dist/index.js",