@capagents/forgeqe 2.2.4 → 2.2.5

package/HOW_TO_USE.md

@@ -204,7 +204,7 @@ pip install forgeqe-cli
 forgeqe --help
 ```
 
-That is the only install step on Windows, macOS and Linux. The first run downloads Bun into `~/.forgeqe/tools` (unless a Bun 1.3+ is already installed), and `forgeqe setup` downloads the agent runtime and uv, which fetches Python. Nothing is added to PATH or shell profiles; deleting `~/.forgeqe` removes it all.
+That is the only install step on Windows, macOS and Linux. npm installs Bun with ForgeQE (through your npm registry, so a company mirror works); with pip, or when npm skipped it, the first run downloads Bun into `~/.forgeqe/tools` (unless a Bun 1.3+ is already installed), and `forgeqe setup` downloads the agent runtime and uv, which fetches Python. Nothing is added to PATH or shell profiles; deleting `~/.forgeqe` removes it all.
 
 Set up the ForgeQE engine once (the first live run does it automatically if you skip this):
 
@@ -233,6 +233,38 @@ bun install
 bun src/index.ts --help
 ```
 
+### Company networks
+
+On a company laptop, ForgeQE sets itself up for the network without anyone changing settings:
+
+| What the network does | What ForgeQE does |
+|---|---|
+| Inspects HTTPS (Zscaler, Netskope, a firewall), with the company's own certificate | Uses the certificates this computer trusts: Windows' Trusted Root store, or the macOS System keychain. ForgeQE, the agent runtime, Playwright and Copilot's runtime get them through `NODE_EXTRA_CA_CERTS` (a copy in `~/.forgeqe/cache/system-ca.pem`, refreshed weekly); the Python engines check with the system through truststore; uv with `UV_SYSTEM_CERTS`. Certificates are still verified. |
+| Sends traffic through a proxy set in Windows | Reads Windows' proxy setting (or the one proxy its automatic configuration script names) and passes it on as `HTTPS_PROXY`. ForgeQE's own servers on `127.0.0.1` always bypass it. |
+| Blocks downloads from GitHub or the Playwright CDN | npm brings Bun through your registry; Microsoft Edge is used when Google Chrome is not installed, so no Chromium is downloaded; mirrors can stand in for the rest (below). |
+
+To see where the network stops ForgeQE, run:
+
+```bash
+forgeqe doctor
+```
+
+It shows the proxy and certificates in use, checks each address ForgeQE needs (GitHub downloads, Python packages, the npm registry, your models, Azure DevOps or Jira), and for anything blocked prints what to ask IT for, ready to forward.
+
+**For IT: mirrors and settings.** Set these as environment variables (for example by Group Policy):
+
+| Variable | What it does |
+|---|---|
+| `FORGEQE_GITHUB_MIRROR` | A mirror of GitHub release downloads (`https://artifacts.example.com/github`, laid out as `<owner>/<repo>/releases/download/<tag>/<file>`): Bun, uv, the agent runtime, Python builds and Copilot's runtime come from it. Checksums are still checked. |
+| `UV_DEFAULT_INDEX` (or `PIP_INDEX_URL`) | A mirror of PyPI for the engine's Python packages. |
+| `PLAYWRIGHT_DOWNLOAD_HOST` | A mirror for Chromium, needed only without Chrome or Edge. |
+| `HTTPS_PROXY`, `NO_PROXY` | A proxy other than Windows' setting. A proxy that needs a sign-in takes `http://user:password@host:port`. |
+| `NODE_EXTRA_CA_CERTS` | Your own certificate file instead of the system's roots. |
+| `FORGEQE_SYSTEM_CERTS=off` | Leaves certificates to each tool's built-in list. |
+| `FORGEQE_HOME` | Where ForgeQE keeps its tools (default `~/.forgeqe`), for machines where programs may run only from certain folders. |
+
+What still needs IT: a proxy that signs in with your Windows account only (NTLM or Kerberos), and policies that block programs in the user folder (set `FORGEQE_HOME` to an allowed folder). On macOS, the company's certificate must be in the System keychain, where device management puts it.
+
 ## 2. Scaffold config
 
 ```bash
@@ -330,6 +362,7 @@ GitHub Models, which ForgeQE used for the engine before, was [retired by GitHub]
 | `ForgeQE's agent and Scribe cannot run on a github_copilot profile yet` | Pick another profile for them (`--profile`, or Tab in the shell), or set `code.model`. |
 | The model is refused, or not found | The seat's plan or your organization's Copilot policies do not allow that model: pick one the sign-in listed, or ask a Copilot admin to enable it. |
 | `GitHub Copilot runs through the ForgeQE engine, which is not set up` | Run `forgeqe setup`. |
+| `CERTIFICATE_VERIFY_FAILED` while downloading Copilot's runtime | Your network inspects HTTPS. Update ForgeQE and run `forgeqe setup`, then sign in again: it uses the certificates your computer trusts (see [Company networks](#company-networks)). If it still fails, run `forgeqe doctor` and send its output to IT. |
 
 ### Your prompts, skills, and product knowledge
 

package/THIRD_PARTY_NOTICES.md

@@ -57,10 +57,10 @@ ForgeQE downloads these onto the machine it runs on, from their own sources, whe
 
 | Software | What for | Licence | Source |
 |----------|----------|---------|--------|
-| Bun | the JavaScript runtime, when the machine has none (bin/forgeqe.js) | MIT | https://bun.sh |
+| Bun | the JavaScript runtime: npm installs it with ForgeQE (@oven/bun-* optional dependencies), else it is downloaded when the machine has none (bin/forgeqe.js) | MIT | https://bun.sh |
 | OpenCode | the agent runtime for ForgeQE's agent and Scribe (src/code/runtime.ts) | MIT | https://opencode.ai |
 | uv and Python | the browser engine's interpreter (src/engine/setup.ts) | MIT or Apache-2.0; PSF | https://github.com/astral-sh/uv |
-| browser-use, Playwright, PyYAML, azure-identity, github-copilot-sdk | the browser engine's libraries and Chromium (src/engine/setup.ts) | MIT; Apache-2.0; MIT; MIT; MIT | https://pypi.org |
+| browser-use, Playwright, PyYAML, azure-identity, github-copilot-sdk, truststore | the browser engine's libraries and Chromium (src/engine/setup.ts) | MIT; Apache-2.0; MIT; MIT; MIT; MIT | https://pypi.org |
 | GitHub Copilot CLI runtime | downloaded by GitHub's Copilot SDK for github_copilot profiles (src/copilot.ts) | GitHub Copilot CLI license (GitHub) | https://github.com/github/copilot-cli |
 
 ## Licence texts

package/bin/forgeqe.d.ts

@@ -3,3 +3,9 @@ export const BUN_VERSION: string
 export function cliEntry(root: string): string
 export function bunAsset(platform?: string, arch?: string, musl?: boolean): string | null
 export function unzipEntry(zip: Buffer, name: string): Buffer
+/** The npm package with this machine's Bun build (@oven/bun-windows-x64-baseline). */
+export function bunPackage(platform?: string, arch?: string, musl?: boolean): string | null
+/** The Bun npm installed beside ForgeQE, or null. */
+export function npmBun(resolve?: (id: string) => string, pkg?: string | null): string | null
+/** `env` with NODE_EXTRA_CA_CERTS set to the system's roots ForgeQE saved, when there are some and the user set none. */
+export function bunEnv(env?: Record<string, string | undefined>, home?: string): Record<string, string | undefined>

package/bin/forgeqe.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 /**
  * npm bin for the ForgeQE CLI.
- * The CLI runs on Bun. Use a system Bun 1.3+ if there is one, otherwise download the pinned Bun
- * into ~/.forgeqe/tools (checksum verified, no PATH or shell profile changes) and run the TypeScript entry with it.
+ * The CLI runs on Bun: the pinned Bun npm installed with ForgeQE (an @oven/bun-* optional dependency, so it comes through
+ * the company's npm mirror and proxy), else a system Bun 1.3+, else the pinned Bun downloaded into ~/.forgeqe/tools
+ * (checksum verified, no PATH or shell profile changes).
  */
 
 import { spawnSync } from "node:child_process";
@@ -10,6 +11,7 @@ import { createHash } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { inflateRawSync } from "node:zlib";
 
@@ -60,9 +62,28 @@ function newEnough(v) {
   return true;
 }
 
-/** FORGEQE_BUN, then bun on PATH, then the official installer's location, then a Bun ForgeQE downloaded earlier. */
+/** The npm package with this machine's Bun build, named like its release asset (@oven/bun-windows-x64-baseline). */
+export function bunPackage(platform = process.platform, arch = process.arch, musl = isMusl()) {
+  const asset = bunAsset(platform, arch, musl);
+  return asset ? `@oven/${asset.replace(/\.zip$/, "")}` : null;
+}
+
+/** The Bun npm installed beside ForgeQE, or null (another machine's install, or --no-optional). */
+export function npmBun(resolve = createRequire(import.meta.url).resolve, pkg = bunPackage()) {
+  if (!pkg) return null;
+  try {
+    const bin = path.join(path.dirname(resolve(`${pkg}/package.json`)), "bin", exe);
+    return existsSync(bin) ? bin : null;
+  } catch {
+    return null;
+  }
+}
+
+/** FORGEQE_BUN, then the Bun npm installed, then bun on PATH, then the official installer's location, then a Bun ForgeQE downloaded earlier. */
 function findBun() {
   if (process.env.FORGEQE_BUN) return process.env.FORGEQE_BUN;
+  const fromNpm = npmBun();
+  if (fromNpm) return fromNpm;
   const home = process.env.HOME || process.env.USERPROFILE || "";
   const candidates = ["bun", ...(home ? [path.join(home, ".bun", "bin", exe)] : []), managedBun()];
   for (const c of candidates) {
@@ -132,7 +153,8 @@ async function download(url) {
 async function installBun() {
   const asset = bunAsset();
   if (!asset) throw new Error(`no Bun build for ${process.platform}/${process.arch}`);
-  const base = `https://github.com/oven-sh/bun/releases/download/bun-v${BUN_VERSION}`;
+  const mirror = (process.env.FORGEQE_GITHUB_MIRROR || "").trim().replace(/\/+$/, "");
+  const base = `${/^https:\/\//i.test(mirror) ? mirror : "https://github.com"}/oven-sh/bun/releases/download/bun-v${BUN_VERSION}`;
   process.stderr.write(`forgeqe: downloading Bun ${BUN_VERSION} (${asset}) into ${toolsDir()} (one time)...\n`);
   const [zip, sums] = await Promise.all([download(`${base}/${asset}`), download(`${base}/SHASUMS256.txt`)]);
   const expected = String(sums)
@@ -156,9 +178,19 @@ async function installBun() {
   return target;
 }
 
+/**
+ * Bun reads NODE_EXTRA_CA_CERTS only at start: give it the system's trusted roots that ForgeQE saved
+ * (src/network.ts), for networks that inspect HTTPS. Without the file yet, ForgeQE writes it and starts itself again.
+ */
+export function bunEnv(env = process.env, home = forgeqeHome()) {
+  const ca = path.join(home, "cache", "system-ca.pem");
+  if (env.NODE_EXTRA_CA_CERTS || /^(0|off|false|no)$/i.test(env.FORGEQE_SYSTEM_CERTS || "") || !existsSync(ca)) return env;
+  return { ...env, NODE_EXTRA_CA_CERTS: ca };
+}
+
 function manualHint() {
   const install = windows ? `powershell -c "irm bun.sh/install.ps1 | iex"` : "curl -fsSL https://bun.sh/install | bash";
-  return `Install Bun ${MIN_BUN.join(".")}+ yourself (${install}) and re-run forgeqe,\nor set FORGEQE_BUN to the full path of ${exe}.`;
+  return `Reinstall ForgeQE with npm (npm install -g @capagents/forgeqe), which brings Bun through your npm registry,\nor install Bun ${MIN_BUN.join(".")}+ yourself (${install}) and re-run forgeqe,\nor set FORGEQE_BUN to the full path of ${exe}.\nBehind a company mirror of GitHub downloads, set FORGEQE_GITHUB_MIRROR to it.`;
 }
 
 async function main() {
@@ -175,7 +207,7 @@ async function main() {
       process.exit(1);
     }
   }
-  const result = spawnSync(bun, [entry, ...process.argv.slice(2)], { stdio: "inherit", env: process.env, shell: false });
+  const result = spawnSync(bun, [entry, ...process.argv.slice(2)], { stdio: "inherit", env: bunEnv(), shell: false });
   if (result.error) {
     console.error(`forgeqe: could not start ${bun}: ${result.error.message}\n${manualHint()}`);
     process.exit(1);