omegon 0.6.3 → 0.6.4

package/README.md

@@ -2,7 +2,7 @@
 
 An opinionated distribution of [**pi**](https://github.com/badlogic/pi) — the coding agent by [Mario Zechner](https://github.com/badlogic). Omegon bundles pi core with extensions for persistent project memory, spec-driven development, local LLM inference, image generation, web search, parallel task decomposition, a live dashboard, and quality-of-life tools.
 
-> **Relationship to pi:** Omegon is not a fork or replacement. It packages pi as a dependency and layers extensions on top. All credit for the pi coding agent goes to Mario Zechner and the pi contributors. The core pi packages (`@cwilson613/pi-coding-agent`) track [upstream `badlogic/pi-mono`](https://github.com/badlogic/pi-mono) daily, adding targeted fixes for OAuth login reliability and bracketed-paste input handling. If you want standalone pi without Omegon's extensions, install `@mariozechner/pi-coding-agent` directly.
+> **Relationship to pi:** Omegon is not a fork or replacement. It packages pi as a dependency and layers extensions on top. All credit for the pi coding agent goes to Mario Zechner and the pi contributors. The core pi packages are migrating to the styrene-lab-owned npm scope (`@styrene-lab/pi-coding-agent` and related packages) so package ownership matches the `styrene-lab/omegon` product boundary. Older `@cwilson613/*` package names are compatibility debt during the transition, not the long-term release boundary. If you want standalone pi without Omegon's extensions, install `@mariozechner/pi-coding-agent` directly.
 
 ## Installation
 
@@ -10,7 +10,7 @@ An opinionated distribution of [**pi**](https://github.com/badlogic/pi) — the
 npm install -g omegon
 ```
 
-This installs the `pi` command globally. If a standalone pi package is already installed, omegon will transparently replace it (the same `pi` command, with extensions included). To switch back to standalone pi at any time:
+This installs the canonical `omegon` command globally. A legacy `pi` alias may remain available for compatibility, but the supported lifecycle entrypoint is `omegon`. If a standalone pi package is already installed, omegon transparently takes ownership of the lifecycle boundary so startup, update, verification, and restart all stay inside Omegon control. To switch back to standalone pi at any time:
 
 ```bash
 npm uninstall -g omegon
@@ -20,26 +20,27 @@ npm install -g @mariozechner/pi-coding-agent
 **First-time setup:**
 
 ```bash
-pi          # start pi in any project directory
+omegon      # start Omegon in any project directory
 /bootstrap  # check deps, install missing tools, configure preferences
 ```
 
 ### Keeping up to date
 
-| What to update | How |
-|----------------|-----|
-| **Omegon extensions** | `/update` or `pi update` (tracks `main` branch) |
-| **pi binary** | `/update-pi` — checks npm for latest `@cwilson613/pi-coding-agent`, prompts before installing |
+| Context | How |
+|--------|-----|
+| **Installed Omegon (`npm install -g omegon`)** | Run `/update` from inside Omegon. Omegon installs the latest package, verifies the active `omegon` command still resolves to Omegon, clears caches, then asks you to restart Omegon. |
+| **Dev checkout / contributor workflow** | Run `/update` or `./scripts/install-pi.sh`. Both follow the same lifecycle contract: pull/sync, build, refresh dependencies, `npm link --force`, verify the active `omegon` target, then stop at an explicit restart handoff. |
+| **Lightweight cache refresh only** | Run `/refresh`. This clears transient caches and reloads extensions, but it is not equivalent to package/runtime replacement. |
 
 > The patched fork syncs from upstream daily via GitHub Actions. Bug fixes and new AI provider support land automatically. If a sync PR has conflicts, they are surfaced for manual review before merging — upstream changes are never silently dropped.
 
-> **Note:** `pi install` and `pi update` track the `main` branch. The version-check extension notifies you when a new Omegon release is available.
+> **Note:** `/update` is the authoritative Omegon update path. It intentionally ends at a verified restart boundary rather than hot-swapping the running process after package/runtime mutation.
 
 ## Architecture
 
 ![Omegon Architecture](docs/img/architecture.png)
 
-Omegon extends `@cwilson613/pi-coding-agent` with **27 extensions**, **12 skills**, and **4 prompt templates** — loaded automatically on session start.
+Omegon extends `@styrene-lab/pi-coding-agent` with **27 extensions**, **12 skills**, and **4 prompt templates** — loaded automatically on session start.
 
 ### Development Methodology
 
@@ -263,7 +264,8 @@ Pre-built prompts for common workflows:
 ## Requirements
 
 **Required:**
-- `@cwilson613/pi-coding-agent` ≥ 0.57 — patched fork of [badlogic/pi-mono](https://github.com/badlogic/pi-mono). Install via `npm install -g @cwilson613/pi-coding-agent`. Fork source: [cwilson613/pi-mono](https://github.com/cwilson613/pi-mono)
+- `omegon` — install via `npm install -g omegon`; launch via `omegon`
+- `@styrene-lab/pi-coding-agent` ≥ 0.57 underpins Omegon's bundled agent core and tracks a patched fork of [badlogic/pi-mono](https://github.com/badlogic/pi-mono). Fork source: [cwilson613/pi-mono](https://github.com/cwilson613/pi-mono)
 
 **Optional (installed by `/bootstrap`):**
 - [Ollama](https://ollama.ai) — local inference, offline mode, semantic memory search

package/bin/omegon.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * Omegon entry point.
+ *
+ * Sets PI_CODING_AGENT_DIR to the omegon package root so the bundled agent
+ * core loads all agent configuration (extensions, themes, skills, AGENTS.md)
+ * from omegon rather than from ~/.pi/agent/.
+ *
+ * Resolution order for the underlying agent core:
+ *   1. vendor/pi-mono (dev mode — git submodule present)
+ *   2. node_modules/@styrene-lab/pi-coding-agent (installed via npm)
+ */
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const omegonRoot = dirname(dirname(__filename));
+
+const vendorCli = join(omegonRoot, "vendor/pi-mono/packages/coding-agent/dist/cli.js");
+const npmCli = join(omegonRoot, "node_modules/@styrene-lab/pi-coding-agent/dist/cli.js");
+const cli = existsSync(vendorCli) ? vendorCli : npmCli;
+const resolutionMode = cli === vendorCli ? "vendor" : "npm";
+
+if (process.argv.includes("--where")) {
+  process.stdout.write(JSON.stringify({
+    omegonRoot,
+    cli,
+    resolutionMode,
+    agentDir: process.env.PI_CODING_AGENT_DIR ?? omegonRoot,
+    executable: "omegon",
+  }, null, 2) + "\n");
+  process.exit(0);
+}
+
+if (!process.env.PI_CODING_AGENT_DIR) {
+  process.env.PI_CODING_AGENT_DIR = omegonRoot;
+}
+
+await import(cli);

package/bin/pi.mjs

@@ -1,30 +1,9 @@
 #!/usr/bin/env node
 /**
- * Omegon pi entry point.
+ * Legacy compatibility shim.
  *
- * Sets PI_CODING_AGENT_DIR to the omegon package root so pi loads all agent
- * configuration (extensions, themes, skills, AGENTS.md) from omegon rather
- * than from ~/.pi/agent/.
- *
- * Resolution order for pi core:
- *   1. vendor/pi-mono (dev mode — git submodule present)
- *   2. node_modules/@cwilson613/pi-coding-agent (installed via npm)
+ * `pi` remains available temporarily so existing installs are not stranded,
+ * but it immediately re-enters the same Omegon-owned executable boundary as
+ * the canonical `omegon` command.
  */
-import { dirname, join } from "node:path";
-import { existsSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-
-const __filename = fileURLToPath(import.meta.url);
-const omegonRoot = dirname(dirname(__filename));
-
-// Only set if not already overridden
-if (!process.env.PI_CODING_AGENT_DIR) {
-  process.env.PI_CODING_AGENT_DIR = omegonRoot;
-}
-
-// Resolve pi core: prefer vendor/ (dev), fall back to node_modules/ (installed)
-const vendorCli = join(omegonRoot, "vendor/pi-mono/packages/coding-agent/dist/cli.js");
-const npmCli = join(omegonRoot, "node_modules/@cwilson613/pi-coding-agent/dist/cli.js");
-
-const cli = existsSync(vendorCli) ? vendorCli : npmCli;
-await import(cli);
+await import("./omegon.mjs");

package/extensions/00-secrets/index.ts

@@ -14,9 +14,10 @@
  * Commands: /secrets list, /secrets configure <name>, /secrets rm <name>, /secrets test <name>
  */
 
-import type { ExtensionAPI } from "@cwilson613/pi-coding-agent";
-import { existsSync, readFileSync, writeFileSync, appendFileSync, mkdirSync, readdirSync } from "fs";
-import { join, resolve } from "path";
+import type { ExtensionAPI } from "@styrene-lab/pi-coding-agent";
+import { existsSync, readFileSync, realpathSync, writeFileSync, appendFileSync, mkdirSync, readdirSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
 import { homedir } from "os";
 import { execSync, execFileSync } from "child_process";
 
@@ -51,17 +52,33 @@ function scanAnnotations(): {
   const secretPattern = /^\/\/\s*@secret\s+([A-Z_][A-Z0-9_]*)\s+"([^"]+)"/;
   const configPattern = /^\/\/\s*@config\s+([A-Z_][A-Z0-9_]*)\s+"([^"]+)"(?:\s+\[default:\s*([^\]]*)\])?/;
 
-  // Extension directories to scan
-  const extensionDirs = [
-    join(homedir(), ".pi", "agent", "extensions"),
-    join(homedir(), ".pi", "agent", "git"),  // Omegon and other git packages
-  ];
+  // Extension directories to scan (deduplicated by realpath to avoid
+  // double-walking when dev checkout overlaps with git-installed package)
+  const seen = new Set<string>();
+  const extensionDirs: string[] = [];
+  function addDir(dir: string) {
+    try {
+      const real = realpathSync(dir);
+      if (!seen.has(real)) { seen.add(real); extensionDirs.push(dir); }
+    } catch {
+      // realpathSync fails if dir doesn't exist — skip silently
+    }
+  }
+
+  addDir(join(homedir(), ".pi", "agent", "extensions"));
+  addDir(join(homedir(), ".pi", "agent", "git"));  // Omegon and other git packages
+
+  // Scan the package's own extensions/ directory (where this file lives).
+  // Covers both dev (repo checkout) and npm-installed modes.
+  try {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    addDir(resolve(thisDir, ".."));  // 00-secrets/ → extensions/
+  } catch {}
 
   // Also scan project-local extensions
   try {
     const cwd = process.cwd();
-    const projectDir = join(cwd, ".pi", "extensions");
-    if (existsSync(projectDir)) extensionDirs.push(projectDir);
+    addDir(join(cwd, ".pi", "extensions"));
   } catch {}
 
   function scanFile(filePath: string) {
@@ -367,11 +384,17 @@ const SECRET_ACCESS_PATTERNS = [
   /\bvault\s+(read|kv\s+get)\b/i,
 
   // ── Environment variable dumping ──
-  // Targeted env access with secret-adjacent keywords
-  /\benv\b.*\b(key|token|secret|password|credential)/i,
-  /\bprintenv\b.*\b(key|token|secret|password|credential)/i,
-  // Echo/printf of known secret env vars
-  /\b(echo|printf)\s+.*\$[A-Z_]*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL)/i,
+  // Targeted env/printenv commands with secret-adjacent keywords.
+  // Match only the standalone `env` or `printenv` command, not the substring
+  // "env" in filenames like "env-api-keys.ts" or words like "environment".
+  /(?:^|\||\;|&&|\|\|)\s*env\s+.*\b(key|token|secret|password|credential)/i,
+  /(?:^|\||\;|&&|\|\|)\s*printenv\s+.*\b(key|token|secret|password|credential)/i,
+  // Bare `env` piped to grep/filter for secrets (full dump → filter pattern).
+  // Use looser keyword matching (no leading \b) since env var names use
+  // underscores: API_KEY, _TOKEN, etc. where \b won't match mid-identifier.
+  /(?:^|\||\;|&&|\|\|)\s*env\s*\|.*(key|token|secret|password|credential)/i,
+  // Echo/printf of known secret env vars (literal $VAR references, not prose)
+  /\b(echo|printf)\s+.*\$[A-Z_]*(API_KEY|_TOKEN|_SECRET|_PASSWORD|_CREDENTIAL)\b/i,
   // Full env dumps (these can leak all injected secrets)
   /\bnode\s+-e\s+.*process\.env/i,
   /\bpython[23]?\s+-c\s+.*os\.environ/i,
@@ -379,12 +402,18 @@ const SECRET_ACCESS_PATTERNS = [
   /\bperl\s+-e\s+.*%ENV/i,
 
   // ── File readers on sensitive paths ──
-  // cat/less/more/head/tail/bat on secret-adjacent files
-  /\b(cat|less|more|head|tail|bat|batcat)\b.*(secrets?\.json|\bcredentials?\b|\.env\b)/i,
+  // cat/less/more/head/tail/bat on actual secret/credential files.
+  // Match files like "secrets.json", "credentials", ".env" — but not source code
+  // files that happen to contain the word "credential" (e.g. provider-env.ts).
+  // The path must look like a config/data file, not a .ts/.js/.py source file.
+  /\b(cat|less|more|head|tail|bat|batcat)\s+\S*secrets?\.json\b/i,
+  /\b(cat|less|more|head|tail|bat|batcat)\s+\S*credentials\s*$/im,
+  /\b(cat|less|more|head|tail|bat|batcat)\s+\S*\.env(\.[a-z]+)?\s*$/im,
   // jq on secret files
-  /\bjq\b.*\b(secrets?\.json|credentials?)\b/i,
-  // sed/awk/grep reading secret files
-  /\b(sed|awk|grep)\b.*\b(secrets?\.json|credentials?)\b/i,
+  /\bjq\b.*\b(secrets?\.json)\b/i,
+  /\bjq\b\s+\S+\s+\S*credentials\s*$/im,
+  // sed/awk/grep on actual secret data files (not source code containing the word)
+  /\b(sed|awk|grep)\b.*\bsecrets?\.json\b/i,
   // Our own secrets file — match the specific path
   /\.pi\/agent\/secrets\.json/i,
   // Writing to secrets file (via tee, redirect, etc.)
@@ -393,8 +422,9 @@ const SECRET_ACCESS_PATTERNS = [
   /\b(cat|less|more|head|tail)\b.*\.(aws|gcloud)\/(credentials|config)/i,
 
   // ── Command wrapping (shell indirection) ──
-  // sh/bash/zsh -c wrapping with secret-adjacent content
-  /\b(sh|bash|zsh)\s+-c\s+.*\b(security|op\s+read|pass\s+show|vault\s+read|keychain|credential|secret)/i,
+  // sh/bash/zsh -c wrapping with actual secret store tool invocations.
+  // Narrow: only match specific tool commands, not prose containing "secret".
+  /\b(sh|bash|zsh)\s+-c\s+.*\b(security\s+find|op\s+(read|get|item)|pass\s+show|vault\s+(read|kv\s+get)|keychain)/i,
   // Python/Ruby/Node/Perl subprocess wrappers accessing secret stores
   /\b(python[23]?|ruby|node|perl)\b.*\b(security\s+find|op\s+read|find-generic-password|secrets?\.json)/i,
   // Base64 decode piped to shell (obfuscation technique)
@@ -580,6 +610,39 @@ export default function (pi: ExtensionAPI) {
         "error"
       );
     }
+
+    // Warn about secrets resolved from bare env vars (no recipe — set in
+    // .bashrc/.zshrc or shell profile). These are insecure: visible in
+    // /proc/*/environ, inherited by every child process, persisted in
+    // dotfile repos and shell history. A keychain-backed recipe resolves
+    // at runtime with biometric/password auth and doesn't leak on disk.
+    //
+    // Skip in CI environments where env vars are the expected mechanism.
+    // Exempt tokens managed by their own CLI credential stores (e.g.
+    // GH_TOKEN set by `gh auth login`, GITHUB_TOKEN from gh, COPILOT_GITHUB_TOKEN
+    // from the Copilot extension) — these are already secured by the tool.
+    const isCI = !!(process.env.CI || process.env.GITHUB_ACTIONS || process.env.GITLAB_CI);
+    if (!isCI) {
+      // Tokens managed by CLI tools that handle their own credential storage
+      const CLI_MANAGED_TOKENS = new Set([
+        "GH_TOKEN", "GITHUB_TOKEN", "COPILOT_GITHUB_TOKEN",  // gh auth login
+        "GITLAB_TOKEN",     // glab auth login
+        "AWS_PROFILE",      // aws configure / SSO profile name (not a secret)
+      ]);
+      const bareEnvSecrets = Object.keys(KNOWN_SECRETS).filter(name =>
+        resolvedCache.has(name) && !recipes[name] && !CLI_MANAGED_TOKENS.has(name)
+      );
+      if (bareEnvSecrets.length > 0) {
+        // Show at most 3 names to avoid wall-of-text, never show values
+        const examples = bareEnvSecrets.slice(0, 3).join(", ");
+        const more = bareEnvSecrets.length > 3 ? ` (+${bareEnvSecrets.length - 3} more)` : "";
+        ctx.ui.notify(
+          `🔓 ${bareEnvSecrets.length} secret${bareEnvSecrets.length !== 1 ? "s" : ""} loaded from plain env vars: ${examples}${more}\n` +
+          `Run \`/secrets configure <name>\` to migrate to a secure backend.`,
+          "warning"
+        );
+      }
+    }
   });
 
   // ──────────────────────────────────────────────────────────────
@@ -824,36 +887,60 @@ export default function (pi: ExtensionAPI) {
         case "list": {
           const lines: string[] = ["Secret recipes (~/.pi/agent/secrets.json):", ""];
 
+          function describeSource(name: string, recipe: string | undefined, resolved: boolean): string {
+            if (recipe) {
+              if (recipe.startsWith("!")) return `command: ${recipe.slice(1, 40)}${recipe.length > 41 ? "..." : ""}`;
+              if (recipe.startsWith("literal:")) return "⚠️  literal value (insecure — run /secrets configure to migrate)";
+              return `env: ${recipe}`;
+            }
+            if (resolved) return "🔓 plain env var (run /secrets configure to use a secure backend)";
+            return "not configured";
+          }
+
+          // Split into resolved and unresolved for cleaner display
+          const resolvedEntries: Array<[string, string]> = [];
+          const unresolvedEntries: Array<[string, string]> = [];
           for (const [name, desc] of Object.entries(KNOWN_SECRETS)) {
-            const recipe = recipes[name];
             const resolved = resolvedCache.has(name);
-            const source = recipe
-              ? recipe.startsWith("!")
-                ? `command: ${recipe.slice(1, 40)}${recipe.length > 41 ? "..." : ""}`
-                : recipe.startsWith("literal:")
-                  ? "⚠️  literal value (insecure — run /secrets configure to migrate)"
-                  : `env: ${recipe}`
-              : resolved
-                ? "env (auto-detected)"
-                : "not configured";
+            if (resolved || recipes[name]) {
+              resolvedEntries.push([name, desc]);
+            } else {
+              unresolvedEntries.push([name, desc]);
+            }
+          }
 
+          // Show resolved/configured secrets first
+          for (const [name, desc] of resolvedEntries) {
+            const recipe = recipes[name];
+            const resolved = resolvedCache.has(name);
             const status = resolved ? "✅" : "❌";
             lines.push(`  ${status} ${name}`);
             lines.push(`     ${desc}`);
-            lines.push(`     Source: ${source}`);
+            lines.push(`     Source: ${describeSource(name, recipe, resolved)}`);
             lines.push("");
           }
 
-          // Show any non-known secrets
+          // Show any non-known custom secrets
           for (const name of Object.keys(recipes)) {
             if (name in KNOWN_SECRETS) continue;
             const recipe = recipes[name];
             const resolved = resolvedCache.has(name);
             const status = resolved ? "✅" : "❌";
             lines.push(`  ${status} ${name} (custom)`);
-            lines.push(
-              `     Source: ${recipe.startsWith("!") ? `command: ${recipe.slice(1, 40)}` : recipe.startsWith("literal:") ? "⚠️  literal (insecure)" : `env: ${recipe}`}`
-            );
+            lines.push(`     Source: ${describeSource(name, recipe, resolved)}`);
+            lines.push("");
+          }
+
+          // Unconfigured secrets: collapsed summary instead of a wall
+          if (unresolvedEntries.length > 0) {
+            const names = unresolvedEntries.map(([n]) => n);
+            if (names.length <= 5) {
+              lines.push(`  Not configured: ${names.join(", ")}`);
+            } else {
+              const shown = names.slice(0, 5).join(", ");
+              lines.push(`  Not configured: ${shown} (+${names.length - 5} more)`);
+            }
+            lines.push(`  Run /secrets configure <name> to set up any of these.`);
             lines.push("");
           }
 
@@ -1032,14 +1119,34 @@ export default function (pi: ExtensionAPI) {
           saveRecipes(recipes);
 
           // Verify it actually resolves — this is the moment of truth
+          // Note: resolveSecret checks process.env FIRST (for CI compat), so if the
+          // env var is still set from the user's shell profile, it shadows the recipe.
+          // We detect this and warn the user to remove the export.
           resolvedCache.delete(secretName);
-          const value = resolveSecret(secretName);
+          const envShadowed = !!process.env[secretName];
+          // Temporarily clear env to test the recipe in isolation
+          const savedEnv = process.env[secretName];
+          if (envShadowed) delete process.env[secretName];
+          const recipeValue = resolveSecret(secretName);
+          // Restore env (it'll be the active source until user removes it)
+          if (savedEnv !== undefined) {
+            process.env[secretName] = savedEnv;
+            resolvedCache.delete(secretName);
+            resolvedCache.set(secretName, savedEnv);
+          }
+          const value = recipeValue || savedEnv;
           if (value) {
             process.env[secretName] = value;
             const masked = value.length > 8
               ? value.slice(0, 4) + "•".repeat(Math.min(value.length - 4, 16)) + ` (${value.length} chars)`
               : "•".repeat(value.length) + ` (${value.length} chars)`;
-            ctx.ui.notify(`✅ ${secretName} configured and verified: ${masked}`, "info");
+            let msg = `✅ ${secretName} configured and verified: ${masked}`;
+            if (envShadowed && recipeValue) {
+              msg += `\n\n⚠️  Note: \$${secretName} is also set in your shell environment.` +
+                `\nRemove the \`export ${secretName}=...\` from your shell profile` +
+                `\nso the secure backend is used instead of the plain env var.`;
+            }
+            ctx.ui.notify(msg, "info");
           } else {
             // Don't just warn — this is a failure. Remove the broken recipe.
             delete recipes[secretName];

package/extensions/01-auth/auth.ts

@@ -5,7 +5,7 @@
  * pi-tui/pi-coding-agent dependencies (which aren't resolvable under tsx).
  */
 
-import type { ExtensionAPI } from "@cwilson613/pi-coding-agent";
+import type { ExtensionAPI } from "@styrene-lab/pi-coding-agent";
 
 // ─── Types ───────────────────────────────────────────────────────
 

package/extensions/01-auth/index.ts

@@ -25,10 +25,10 @@
  * Load order: 01-auth loads after 00-secrets, so process.env is populated.
  */
 
-import type { ExtensionAPI } from "@cwilson613/pi-coding-agent";
-import { Text } from "@cwilson613/pi-tui";
+import type { ExtensionAPI } from "@styrene-lab/pi-coding-agent";
+import { Text } from "@styrene-lab/pi-tui";
 import { Type } from "@sinclair/typebox";
-import { sciCall, sciOk, sciErr, sciExpanded } from "../sci-ui.ts";
+import { sciCall, sciOk, sciErr, sciExpanded } from "../lib/sci-ui.ts";
 
 // Import domain logic from auth.ts (testable without pi-tui dependency)
 import {

package/extensions/auto-compact.ts

@@ -12,7 +12,7 @@
  *   AUTO_COMPACT_COOLDOWN — minimum seconds between compactions (default: 60)
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@cwilson613/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@styrene-lab/pi-coding-agent";
 
 const COMPACT_PERCENT = Number(process.env.AUTO_COMPACT_PERCENT) || 70;
 const COOLDOWN_MS = (Number(process.env.AUTO_COMPACT_COOLDOWN) || 60) * 1000;

package/extensions/bootstrap/deps.ts

@@ -46,9 +46,46 @@ function hasCmd(cmd: string): boolean {
 	}
 }
 
+/**
+ * Detect immutable/atomic Linux distros (Bazzite, Silverblue, Kinoite, etc.)
+ * where dnf/apt are unavailable or aliased to guides. These distros typically
+ * use Homebrew (Linuxbrew) or Flatpak for user-space packages.
+ */
+function isImmutableLinux(): boolean {
+	if (process.platform !== "linux") return false;
+	try {
+		const osRelease = execSync("cat /etc/os-release 2>/dev/null", { encoding: "utf-8" });
+		// Bazzite, Silverblue, Kinoite, Aurora, Bluefin — all Fedora Atomic variants
+		return /VARIANT_ID=.*(silverblue|kinoite|bazzite|aurora|bluefin|atomic)/i.test(osRelease)
+			|| /ostree/i.test(osRelease);
+	} catch {
+		return false;
+	}
+}
+
+/** Cached immutable Linux detection */
+const _isImmutable = isImmutableLinux();
+
 /** Get the best install command for the current platform */
 export function bestInstallCmd(dep: Dep): string | undefined {
 	const plat = process.platform === "darwin" ? "darwin" : "linux";
+
+	// On immutable Linux (Bazzite, Silverblue, etc.), dnf/apt are unavailable
+	// or aliased to documentation guides. Prefer brew commands.
+	// On regular Linux, prefer non-brew (apt/dnf) unless brew is the only option.
+	const hasBrew = hasCmd("brew");
+	if (plat === "linux" && (_isImmutable || !hasBrew)) {
+		// Immutable: must use brew (skip apt/dnf). Regular without brew: skip brew commands.
+		const candidates = dep.install.filter((o) => o.platform === plat || o.platform === "any");
+		if (_isImmutable && hasBrew) {
+			const brewCmd = candidates.find((o) => o.cmd.startsWith("brew "));
+			if (brewCmd) return brewCmd.cmd;
+		} else if (!_isImmutable) {
+			const nonBrew = candidates.find((o) => !o.cmd.startsWith("brew "));
+			if (nonBrew) return nonBrew.cmd;
+		}
+	}
+
 	return (
 		dep.install.find((o) => o.platform === plat)?.cmd ??
 		dep.install.find((o) => o.platform === "any")?.cmd ??
@@ -108,6 +145,7 @@ export const DEPS: Dep[] = [
 		check: () => hasCmd("gh"),
 		install: [
 			{ platform: "darwin", cmd: "brew install gh" },
+			{ platform: "linux", cmd: "brew install gh" },
 			{ platform: "linux", cmd: "sudo apt install gh || sudo dnf install gh" },
 		],
 		url: "https://cli.github.com",
@@ -163,6 +201,7 @@ export const DEPS: Dep[] = [
 		check: () => hasCmd("rsvg-convert"),
 		install: [
 			{ platform: "darwin", cmd: "brew install librsvg" },
+			{ platform: "linux", cmd: "brew install librsvg" },
 			{ platform: "linux", cmd: "sudo apt install librsvg2-bin" },
 		],
 	},
@@ -175,6 +214,7 @@ export const DEPS: Dep[] = [
 		check: () => hasCmd("pdftoppm"),
 		install: [
 			{ platform: "darwin", cmd: "brew install poppler" },
+			{ platform: "linux", cmd: "brew install poppler" },
 			{ platform: "linux", cmd: "sudo apt install poppler-utils" },
 		],
 	},
@@ -200,6 +240,7 @@ export const DEPS: Dep[] = [
 		check: () => hasCmd("aws"),
 		install: [
 			{ platform: "darwin", cmd: "brew install awscli" },
+			{ platform: "linux", cmd: "brew install awscli" },
 			{ platform: "linux", cmd: "sudo apt install awscli" },
 		],
 	},
@@ -212,6 +253,7 @@ export const DEPS: Dep[] = [
 		check: () => hasCmd("kubectl"),
 		install: [
 			{ platform: "darwin", cmd: "brew install kubectl" },
+			{ platform: "linux", cmd: "brew install kubectl" },
 			{ platform: "linux", cmd: "sudo apt install kubectl" },
 		],
 	},