create-egregore 0.17.3 → 0.18.0

package/lib/api.js

@@ -88,17 +88,17 @@ class EgregoreAPI {
     });
   }
 
-  async joinOrg(githubToken, { github_org, repo_name = "egregore-core" }) {
+  async joinOrg(githubToken, { github_org, repo_name = "egregore" }) {
     return request("POST", `${this.base}/api/org/join`, {
       headers: { Authorization: `Bearer ${githubToken}` },
       body: { github_org, repo_name },
     });
   }
 
-  async registerOrg(githubToken, { org_name, github_org, slug }) {
+  async registerOrg(githubToken, { org_name, github_org, slug, flow_variant }) {
     return request("POST", `${this.base}/api/org/register`, {
       headers: { Authorization: `Bearer ${githubToken}` },
-      body: { org_name, github_org, slug },
+      body: { org_name, github_org, slug, ...(flow_variant ? { flow_variant } : {}) },
     });
   }
 

package/lib/auth.js

@@ -4,9 +4,201 @@
  */
 
 const https = require("node:https");
+const { spawnSync } = require("node:child_process");
 
-const GITHUB_APP_CLIENT_ID = "Iv23li2obNsAjakoK2RE";   // GitHub App — founder flow (clean install screen)
-const OAUTH_APP_CLIENT_ID = "Ov23liYZjJbbbNgnJ9vH";    // OAuth App — join flow (repo:invite only)
+/**
+ * Try to get a token from the user's `gh` CLI, if installed and authenticated.
+ * Returns { token, scopes, user, hasRepoScope } on success, null when gh is
+ * missing/not authenticated/no token.
+ *
+ * Skips the Egregore GitHub App install step entirely — the gh-issued token
+ * has the scopes we need for founder/join flows. Matches the pattern in
+ * bin/init-gh.sh.
+ *
+ * Respects EGREGORE_SKIP_GH=1 to force device flow even when gh is present
+ * (useful for testing the fallback path).
+ */
+function envGhAuth() {
+  const envToken = (process.env.EGREGORE_GITHUB_TOKEN || "").trim();
+  if (!envToken) return null;
+  return {
+    token: envToken,
+    scopes: [],
+    user: process.env.EGREGORE_GITHUB_USER || null,
+    hasRepoScope: null,
+  };
+}
+
+function ghCliExists() {
+  if (process.env.EGREGORE_SKIP_GH === "1") return false;
+  const which = spawnSync("which", ["gh"], { stdio: "pipe" });
+  return which.status === 0;
+}
+
+function canUseInteractiveBrowserFlow() {
+  return !!(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+// Canonical, cross-platform install page — always correct regardless of OS.
+const GH_INSTALL_URL = "https://cli.github.com";
+
+// The most reliable one-line install for the current OS. Linux package names
+// and repos vary too much for a single command, so we point at the canonical
+// page there (and always print GH_INSTALL_URL alongside on every platform).
+function _has(b) {
+  try { return spawnSync("which", [b], { stdio: "pipe" }).status === 0; }
+  catch { return false; }
+}
+
+// True on a machine with no way to open a browser (server / SSH). macOS and
+// Windows always have one; on Linux we need a display AND a browser opener.
+function isHeadless() {
+  if (process.platform === "darwin" || process.platform === "win32") return false;
+  const hasDisplay = !!(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
+  const hasOpener = ["xdg-open", "x-www-browser", "www-browser", "wslview"].some(_has);
+  return !hasDisplay && !hasOpener;
+}
+
+// Human-readable install command for the current OS (for manual instructions).
+function ghInstallCommand() {
+  if (process.platform === "darwin") return "brew install gh";
+  if (process.platform === "win32") return "winget install --id GitHub.cli";
+  if (_has("apt-get") || _has("apt")) return "sudo apt install gh";
+  if (_has("dnf")) return "sudo dnf install gh";
+  if (_has("pacman")) return "sudo pacman -S github-cli";
+  if (_has("zypper")) return "sudo zypper install gh";
+  if (_has("brew")) return "brew install gh";
+  return "install the 'gh' package";
+}
+
+// Runnable, non-interactive install command for the current OS — or null when
+// we can't safely auto-install (unknown package manager, or brew/winget absent).
+function ghInstallShellCommand() {
+  if (process.platform === "darwin") return _has("brew") ? "brew install gh" : null;
+  if (process.platform === "win32") return _has("winget") ? "winget install --id GitHub.cli --silent" : null;
+  if (_has("apt-get")) return "sudo apt-get install -y gh";
+  if (_has("dnf")) return "sudo dnf install -y gh";
+  if (_has("pacman")) return "sudo pacman -S --noconfirm github-cli";
+  if (_has("zypper")) return "sudo zypper install -y gh";
+  if (_has("brew")) return "brew install gh";
+  return null;
+}
+
+// Run the OS install command (the user sees it + any sudo prompt), then start
+// gh's own first-party login. Returns the gh token on success, null otherwise.
+// gh is GitHub's CLI, so login uses GitHub's own screen — never an Egregore one.
+function runGhInstallAndLogin(ui, cmd) {
+  ui?.info?.("");
+  ui?.info?.(`Running ${ui.bold ? ui.bold(cmd) : cmd}`);
+  ui?.info?.("");
+  const res = spawnSync("bash", ["-c", cmd], { stdio: "inherit", env: process.env });
+  if (res.status !== 0 || !_has("gh")) {
+    ui?.warn?.("Couldn't install GitHub CLI automatically.");
+    return null;
+  }
+  ui?.success?.("GitHub CLI installed.");
+  const auth = runGhAuthLogin(ui);
+  return auth ? auth.token : null;
+}
+
+function explainNoGhHeadless(ui) {
+  const bold = (s) => (ui.bold ? ui.bold(s) : s);
+  ui?.error?.("GitHub CLI is not installed, and this environment is not interactive.");
+  ui?.info?.("Install GitHub CLI, authenticate once, then re-run this command:");
+  ui?.info?.(`  ${bold(ghInstallCommand())}`);
+  ui?.info?.(`  ${bold("gh auth login")}`);
+  ui?.info?.(`  Install for any OS: ${GH_INSTALL_URL}`);
+}
+
+function tryGhAuth() {
+  if (process.env.EGREGORE_SKIP_GH === "1") return null;
+
+  const envAuth = envGhAuth();
+  if (envAuth) return envAuth;
+
+  if (!ghCliExists()) return null;
+
+  // gh auth status writes to stderr; capture both.
+  const status = spawnSync("gh", ["auth", "status"], { stdio: "pipe", encoding: "utf-8" });
+  if (status.status !== 0) return null;
+  const statusText = `${status.stdout || ""}${status.stderr || ""}`;
+
+  const tokenRun = spawnSync("gh", ["auth", "token"], { stdio: "pipe", encoding: "utf-8" });
+  if (tokenRun.status !== 0) return null;
+  const token = (tokenRun.stdout || "").trim();
+  if (!token) return null;
+
+  // Parse declared token scopes when gh exposes them. Some gh versions and
+  // fine-grained auth paths do not print a classic Token scopes line. Treat
+  // that as "unknown" and continue with the first-party gh token instead of
+  // bouncing a correctly authenticated user into the Egregore App install.
+  const scopeMatch = statusText.match(/Token scopes:\s*(.+)/);
+  const scopes = scopeMatch
+    ? scopeMatch[1].split(",").map((s) => s.trim().replace(/['"]/g, ""))
+    : [];
+  const hasRepoScope = scopes.some((s) => s === "repo");
+
+  // Extract user from status line: "Logged in to github.com account <login>"
+  const userMatch = statusText.match(/account\s+(\S+)/);
+  const user = userMatch ? userMatch[1] : null;
+
+  return { token, scopes, user, hasRepoScope: scopeMatch ? hasRepoScope : null };
+}
+
+function runGhAuthLogin(ui, opts = {}) {
+  const envAuth = envGhAuth();
+  if (envAuth) return envAuth;
+  if (!ghCliExists()) return null;
+
+  const scopes = opts.scopes || "repo,read:org";
+  const args = ["auth", "login", "--hostname", "github.com", "--git-protocol", "https", "--scopes", scopes];
+
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    ui?.info?.("GitHub CLI is installed but not authenticated.");
+    ui?.info?.(`Run ${ui.bold ? ui.bold("gh auth login") : "gh auth login"} and then re-run this command.`);
+    return null;
+  }
+
+  const cyan = (s) => (ui.cyan ? ui.cyan(s) : s);
+  const bold = (s) => (ui.bold ? ui.bold(s) : s);
+  ui?.info?.("GitHub CLI is installed but not authenticated.");
+  ui?.info?.(`Starting ${bold("gh auth login")} so Egregore can use your local GitHub session.`);
+  ui?.info?.("");
+
+  // On a headless box (server/SSH, no browser) gh's "open browser" step errors
+  // and the manual link only appears AFTER the failure. Force gh's browser
+  // opener to just PRINT the URL instead — so the device link shows right at the
+  // moment of action, no error. On a laptop we leave it so the real browser opens.
+  const env = { ...process.env };
+  if (isHeadless()) {
+    env.BROWSER = "echo";
+    ui?.info?.(`No browser on this machine — when gh prompts, open the printed link`);
+    ui?.info?.(`(${cyan("https://github.com/login/device")}) and enter the one-time code yourself.`);
+  } else {
+    ui?.info?.(`A browser will open to sign in. If it doesn't, open`);
+    ui?.info?.(`${cyan("https://github.com/login/device")} and enter the one-time code gh shows.`);
+  }
+  ui?.info?.("");
+
+  const result = spawnSync("gh", args, { stdio: "inherit", env });
+  if (result.status !== 0) return null;
+
+  return tryGhAuth();
+}
+
+function tryGhAuthOrLogin(ui, opts = {}) {
+  const existing = tryGhAuth();
+  if (existing) return existing;
+  if (!ghCliExists()) return null;
+  return runGhAuthLogin(ui, opts);
+}
+
+// OAuth App — used for ALL device-flow auth (founder + join). We deliberately
+// do NOT use a GitHub App here: a GitHub App device flow surfaces the App
+// install/authorize screen, which blocked installs in the field. The OAuth App
+// device flow lets the user paste a code at github.com/login/device — no popup,
+// no App authorization page.
+const OAUTH_APP_CLIENT_ID = "Ov23liYZjJbbbNgnJ9vH";
 const SUPPORT_URL = "https://github.com/egregore-labs/egregore";
 
 function post(url, body) {
@@ -95,12 +287,27 @@ function copyToClipboard(text) {
  * Run GitHub Device Flow.
  * Returns the access token string, or throws on failure.
  * @param {object} [opts] - Options
- * @param {string} [opts.mode] - "join" uses OAuth App with repo:invite scope
+ * @param {string} [opts.mode] - "join" uses OAuth App with repo access
  */
 async function deviceFlow(ui, opts = {}) {
+  if (!canUseInteractiveBrowserFlow()) {
+    throw new Error(
+      "GitHub browser/device authentication requires an interactive terminal. " +
+      "Install GitHub CLI and run: gh auth login"
+    );
+  }
+
   const isJoin = opts.mode === "join";
-  const clientId = isJoin ? OAUTH_APP_CLIENT_ID : GITHUB_APP_CLIENT_ID;
-  const scope = isJoin ? "repo:invite" : "";
+  // Always the OAuth App — never the GitHub App (see OAUTH_APP_CLIENT_ID note).
+  // Default to ONLY `repo` — the minimum to create/clone private repos. We
+  // deliberately omit `read:org`: it adds an "Organizations and teams" line and
+  // org-spanning Grant/Request prompts to the consent screen (the exact
+  // third-party-app friction we're escaping). Org enumeration is a gh-only
+  // affordance; the local device-flow path stays in the personal account.
+  // Connected mode (hosted) enumerates orgs server-side and opts into read:org
+  // explicitly via opts.scope.
+  const clientId = OAUTH_APP_CLIENT_ID;
+  const scope = opts.scope || "repo";
 
   // 1. Request device code (with retry — handles transient network hiccups
   //    and GitHub edge server blips that caused ECONNREFUSED in the field)
@@ -126,34 +333,44 @@ async function deviceFlow(ui, opts = {}) {
   }
 
   const { device_code, user_code, verification_uri, interval: pollInterval } = codeResp;
-  const verifyUrl = codeResp.verification_uri_complete || verification_uri;
+  // Device-entry page (NOT verification_uri_complete — we want the user to type
+  // the code, not follow a pre-filled link, so no browser is auto-opened).
+  const verifyUrl = verification_uri || "https://github.com/login/device";
 
-  // 2. Show code + open browser
+  // 2. Show the code for MANUAL entry. We do NOT open a browser — auto-opening
+  //    is what made this feel like the old GitHub App popup. The user opens the
+  //    page themselves and pastes the code (already on their clipboard).
   const copied = copyToClipboard(user_code);
   ui.info("");
-  ui.info("A GitHub page will open. Just click Authorize — you'll choose");
-  ui.info("where to set up Egregore in the next step.");
+  if (isJoin) {
+    ui.info("Sign in to your GitHub to accept the invite and clone the repos:");
+  } else {
+    ui.info("Sign in to your GitHub — your repos are created in your account and stay yours:");
+  }
   ui.info("");
+  ui.info(`  1. Open: ${ui.bold(verifyUrl)}`);
   if (copied) {
-    ui.info(`Code copied to clipboard: ${ui.bold(user_code)}`);
+    ui.info(`  2. Enter this code (copied to clipboard): ${ui.bold(user_code)}`);
   } else {
-    ui.info(`Your code: ${ui.bold(user_code)}`);
+    ui.info(`  2. Enter this code: ${ui.bold(user_code)}`);
   }
-  ui.info("Opening browser...");
-  ui.info(`If it doesn't open, visit: ${verifyUrl}`);
+  ui.info("  3. Click Authorize.");
   ui.info("");
-  openBrowser(verifyUrl);
 
-  // 3. Poll for token. Transient network errors (one bad packet, WiFi blip,
-  //    GitHub edge restart) must NOT kill the whole flow — the user might
-  //    be mid-authorize on the browser side. Catch per-poll errors and
-  //    continue; the outer 5-minute timeout handles genuinely broken networks.
+  // 3. Poll for token, with a live heartbeat so the wait never looks hung.
+  //    Transient network errors (one bad packet, WiFi blip, GitHub edge
+  //    restart) must NOT kill the whole flow — the user might be mid-authorize
+  //    on the browser side. Catch per-poll errors and continue; the outer
+  //    5-minute timeout handles genuinely broken networks.
   let interval = (pollInterval || 5) * 1000;
   const timeout = 300000; // 5 minutes
   const start = Date.now();
   let consecutiveNetworkErrors = 0;
   let networkWarningShown = false;
 
+  const waitMsg = "Waiting for you to authorize — the page stays open until you do";
+  let waitSpin = ui.spinner(waitMsg);
+
   while (Date.now() - start < timeout) {
     await sleep(interval);
 
@@ -170,16 +387,19 @@ async function deviceFlow(ui, opts = {}) {
       // After 3 consecutive failures, surface a note so the user knows
       // something is off — but keep polling until the outer timeout.
       if (consecutiveNetworkErrors >= 3 && !networkWarningShown) {
+        waitSpin.clear();
         ui.warn(
           `Network trouble reaching GitHub (${err.message}). Still trying.\n` +
           `If this persists, report at ${SUPPORT_URL}/issues`
         );
         networkWarningShown = true;
+        waitSpin = ui.spinner(waitMsg); // resume the heartbeat
       }
       continue;
     }
 
     if (tokenResp.access_token) {
+      waitSpin.clear(); // caller prints its own "Authenticated" line
       return tokenResp.access_token;
     }
 
@@ -191,17 +411,32 @@ async function deviceFlow(ui, opts = {}) {
       continue;
     }
 
+    waitSpin.fail("Authorization failed");
     throw new Error(
       `${tokenResp.error_description || tokenResp.error || "Auth failed"}\n` +
       `If you need help, see ${SUPPORT_URL}`
     );
   }
 
+  waitSpin.fail("Timed out");
   throw new Error(
     `Timed out waiting for authorization (5 minutes).\n` +
-    `If the browser tab didn't open, visit the verification URL manually and enter your code.\n` +
+    `Open https://github.com/login/device and enter the code shown above.\n` +
     `If this keeps happening, report at ${SUPPORT_URL}/issues`
   );
 }
 
-module.exports = { deviceFlow, openBrowser };
+module.exports = {
+  canUseInteractiveBrowserFlow,
+  deviceFlow,
+  explainNoGhHeadless,
+  GH_INSTALL_URL,
+  ghCliExists,
+  ghInstallCommand,
+  ghInstallShellCommand,
+  openBrowser,
+  runGhAuthLogin,
+  runGhInstallAndLogin,
+  tryGhAuth,
+  tryGhAuthOrLogin,
+};

package/lib/codex-runtime.js

@@ -0,0 +1,268 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const PACKAGE = require("../package.json");
+
+const BUNDLE_DIR = path.join(__dirname, "..", "runtime", "codex");
+const BUNDLE_MANIFEST = path.join(BUNDLE_DIR, "manifest.json");
+const LOCAL_MANIFEST = path.join(".egregore", "codex-runtime-manifest.json");
+
+const REQUIRED_RUNTIME_PATHS = [
+  "AGENTS.md",
+  ".codex/config.toml",
+  ".codex/hooks.json",
+  ".codex/hooks/branch-guard.js",
+  ".codex/skills",
+  "bin/agent.sh",
+  "bin/codex-install-skills.sh",
+  "bin/codex-session-start.sh",
+  "bin/codex-render-spec.mjs",
+  "bin/codex-skill-render.mjs",
+];
+
+function hashBuffer(buffer) {
+  return crypto.createHash("sha256").update(buffer).digest("hex");
+}
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf-8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function listFiles(dir, prefix = "") {
+  if (!fs.existsSync(dir)) return [];
+  const result = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const rel = prefix ? path.join(prefix, entry.name) : entry.name;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      result.push(...listFiles(full, rel));
+    } else if (entry.isFile()) {
+      result.push(rel);
+    }
+  }
+  return result.sort();
+}
+
+function bundleManifest() {
+  return readJson(BUNDLE_MANIFEST, { files: [], skills: [], skillCount: 0 });
+}
+
+function bundleFiles() {
+  return listFiles(BUNDLE_DIR).filter((rel) => rel !== "manifest.json");
+}
+
+function installManifestPath(egregoreDir) {
+  const gitPath = path.join(egregoreDir, ".git");
+  try {
+    const stat = fs.lstatSync(gitPath);
+    if (stat.isDirectory()) {
+      return path.join(gitPath, "info", "egregore-codex-runtime.json");
+    }
+    if (stat.isFile()) {
+      const raw = fs.readFileSync(gitPath, "utf-8").trim();
+      const match = raw.match(/^gitdir:\s*(.+)$/);
+      if (match) {
+        const gitDir = path.isAbsolute(match[1])
+          ? match[1]
+          : path.resolve(egregoreDir, match[1]);
+        return path.join(gitDir, "info", "egregore-codex-runtime.json");
+      }
+    }
+  } catch {}
+  return path.join(egregoreDir, LOCAL_MANIFEST);
+}
+
+function readInstallManifest(egregoreDir) {
+  return readJson(installManifestPath(egregoreDir), { files: {} });
+}
+
+function writeInstallManifest(egregoreDir, manifest) {
+  const manifestPath = installManifestPath(egregoreDir);
+  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+}
+
+function applySourceMode(src, dest) {
+  try {
+    fs.chmodSync(dest, fs.statSync(src).mode & 0o777);
+  } catch {}
+}
+
+function copyFile(src, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+  applySourceMode(src, dest);
+}
+
+function installAgentsSkillsLink(egregoreDir, summary) {
+  const agentsDir = path.join(egregoreDir, ".agents");
+  const linkPath = path.join(agentsDir, "skills");
+  const target = "../.codex/skills";
+
+  if (pathExistsOrSymlink(linkPath)) {
+    try {
+      const stat = fs.lstatSync(linkPath);
+      if (stat.isSymbolicLink() && fs.readlinkSync(linkPath) === target) {
+        summary.skipped += 1;
+        summary.symlink = "skipped";
+        return;
+      }
+      summary.conflicted += 1;
+      summary.conflicts.push(".agents/skills");
+      summary.symlink = "conflicted";
+      return;
+    } catch {
+      summary.conflicted += 1;
+      summary.conflicts.push(".agents/skills");
+      summary.symlink = "conflicted";
+      return;
+    }
+  }
+
+  try {
+    fs.mkdirSync(agentsDir, { recursive: true });
+    fs.symlinkSync(target, linkPath);
+    summary.installed += 1;
+    summary.symlink = "installed";
+  } catch {
+    summary.conflicted += 1;
+    summary.conflicts.push(".agents/skills");
+    summary.symlink = "conflicted";
+  }
+}
+
+function pathExistsOrSymlink(file) {
+  try {
+    fs.lstatSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function installCodexRuntime(egregoreDir) {
+  const summary = {
+    installed: 0,
+    updated: 0,
+    skipped: 0,
+    conflicted: 0,
+    conflicts: [],
+    files: [],
+    bundleSkills: bundleManifest().skills || [],
+    bundleSkillCount: bundleManifest().skillCount || 0,
+    symlink: "skipped",
+  };
+
+  if (!fs.existsSync(BUNDLE_DIR)) {
+    throw new Error(`Codex runtime bundle missing: ${BUNDLE_DIR}`);
+  }
+
+  const previous = readInstallManifest(egregoreDir);
+  const next = {
+    package: PACKAGE.name,
+    version: PACKAGE.version,
+    installedAt: new Date().toISOString(),
+    files: {},
+  };
+  const previousFiles = previous.files || {};
+
+  for (const rel of bundleFiles()) {
+    const src = path.join(BUNDLE_DIR, rel);
+    const dest = path.join(egregoreDir, rel);
+    const sourceBuffer = fs.readFileSync(src);
+    const sourceHash = hashBuffer(sourceBuffer);
+    const previousHash = previousFiles[rel] && previousFiles[rel].hash;
+    const recordSource = () => {
+      next.files[rel] = { hash: sourceHash };
+      summary.files.push(rel);
+    };
+
+    if (!pathExistsOrSymlink(dest)) {
+      copyFile(src, dest);
+      summary.installed += 1;
+      recordSource();
+      continue;
+    }
+
+    let stat;
+    try {
+      stat = fs.lstatSync(dest);
+    } catch {
+      summary.conflicted += 1;
+      summary.conflicts.push(rel);
+      continue;
+    }
+
+    if (!stat.isFile()) {
+      summary.conflicted += 1;
+      summary.conflicts.push(rel);
+      if (previousHash) next.files[rel] = { hash: previousHash };
+      continue;
+    }
+
+    const currentHash = hashBuffer(fs.readFileSync(dest));
+    if (currentHash === sourceHash) {
+      applySourceMode(src, dest);
+      summary.skipped += 1;
+      recordSource();
+      continue;
+    }
+
+    if (previousHash && currentHash === previousHash) {
+      copyFile(src, dest);
+      summary.updated += 1;
+      recordSource();
+      continue;
+    }
+
+    summary.conflicted += 1;
+    summary.conflicts.push(rel);
+    if (previousHash) next.files[rel] = { hash: previousHash };
+  }
+
+  installAgentsSkillsLink(egregoreDir, summary);
+  writeInstallManifest(egregoreDir, next);
+  return summary;
+}
+
+function hasCodexRuntimeSupport(egregoreDir) {
+  return REQUIRED_RUNTIME_PATHS.every((rel) => fs.existsSync(path.join(egregoreDir, rel)));
+}
+
+function reportCodexRuntimeSummary(summary, ui, opts = {}) {
+  if (!summary || !ui) return;
+  const label = opts.label || "Codex runtime";
+  const includeConflicts = opts.includeConflicts !== false;
+  const changed = summary.installed + summary.updated;
+  if (changed > 0) {
+    ui.success(
+      `${label} ready (${summary.installed} installed, ${summary.updated} updated, ${summary.skipped} unchanged)`,
+    );
+  }
+  if (includeConflicts && summary.conflicted > 0) {
+    // These "conflicts" are shared framework files your Egregore already ships
+    // and keeps current (agent.sh, graph-op.sh, AGENTS.md, …) — we keep yours
+    // and only add the Codex-specific files. It's expected, not an error, so
+    // say so calmly instead of warning.
+    const n = summary.conflicted;
+    const line = `${label}: kept ${n} framework file${n === 1 ? "" : "s"} your Egregore already manages.`;
+    ui.info(ui.dim ? ui.dim(line) : line);
+  }
+}
+
+module.exports = {
+  BUNDLE_DIR,
+  bundleFiles,
+  bundleManifest,
+  hasCodexRuntimeSupport,
+  installCodexRuntime,
+  installManifestPath,
+  reportCodexRuntimeSummary,
+};

package/lib/commands.js

@@ -0,0 +1,31 @@
+"use strict";
+
+// Central command surface. create-egregore is the public package — this is the
+// single source of truth for the advertised npx command across the installer
+// and launcher surfaces.
+const PUBLIC_NPX_PACKAGE = "create-egregore";
+
+function publicPackageSpec() {
+  return `${PUBLIC_NPX_PACKAGE}@latest`;
+}
+
+function npxCommand(args = []) {
+  return ["npx", "-y", publicPackageSpec(), ...args].filter(Boolean).join(" ");
+}
+
+function joinCommand(owner, repo) {
+  const target = repo ? `${owner}/${repo}` : owner;
+  return npxCommand(["join", target]);
+}
+
+function tokenCommand(token) {
+  return npxCommand(["--token", token]);
+}
+
+module.exports = {
+  PUBLIC_NPX_PACKAGE,
+  publicPackageSpec,
+  npxCommand,
+  joinCommand,
+  tokenCommand,
+};

package/lib/context.js

@@ -2,7 +2,7 @@
  * Detect whether cwd is inside a git work-tree.
  *
  * Egregore installs as a sibling shell alongside managed repos. If a user runs
- * `npx create-egregore` from inside an existing git repo, we want to redirect
+ * `npx -y create-egregore@latest` from inside an existing git repo, we want to redirect
  * them to the repo's parent directory and auto-adopt their repo as a managed
  * repo. This module is the single source of truth for that detection.
  */