cchost 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,54 @@ All notable changes to `cchost` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.6.0] - 2026-11-07
+
+### Added
+
+- **`cchost ui`: a local web view.** One page shows every profile, the state
+  of its 7 resources, its login and endpoint, the shared pool and doctor
+  results, and lets you add and remove profiles, share or unshare groups, copy
+  from `~/.claude/` and apply doctor fixes. Every change is previewed per
+  resource before it runs and reported step by step afterwards (Activity).
+  Zero dependencies; served on `127.0.0.1` with a Host-header check, strict
+  CSP, and no endpoint tokens ever sent to the page.
+- **Web view sign-in, like rclone's web GUI.** `cchost ui` prints a username
+  and a per-run random password and opens a one-time sign-in link; the browser
+  gets an expiring HttpOnly session (`--session`, default 8h) and can sign
+  out. `--user` / `--pass` set your own credentials. Failed sign-ins are
+  rate-limited.
+- **Fix doctor issues from the web view.** Per-issue Fix buttons with a
+  preview; fixes that need `--force` in the CLI ask for confirmation; manual
+  steps show a copyable command.
+- **Web view polish.** Collapsible sidebar (remembered), share/private changes
+  can be reverted before applying by clicking the current side again, and
+  subtle motion (view and panel entrances, card hover, expanding Doctor
+  groups) that switches off under reduced motion.
+
+- **`cchost add <profile> --private[=projects,tools,config]`** creates a
+  profile whose chosen resource groups (or all 7) start private and empty
+  instead of shared. Nothing from `~/.claude/` is copied in, unlike
+  `cchost unlink`. Works with `--custom`.
+- **Private-by-choice record.** `add --private` and `cchost unlink` record
+  private resources in `<profile>/.cc-private.json`; `cchost link` removes
+  them. `cchost doctor` reports these as `private by choice` and `--fix` no
+  longer re-shares an empty or absent private resource. Profiles without the
+  file behave as before.
+
+### Changed
+
+- **`cc` passes compiler calls to the real C compiler.** When the legacy `cc`
+  alias is run with anything other than a cchost command (`cc -c foo.c`,
+  `cc --version`, …), it runs the next `cc` on `PATH` that isn't cchost, so
+  `make`, `node-gyp`, and configure scripts work even when npm's bin directory
+  comes before `/usr/bin`. cchost commands (`cc use work`) and bare `cc` are
+  unchanged. Use `cchost --version` for cchost's own version.
+
+### CI
+
+- Releases now create the `vX.Y.Z` tag and GitHub Release (notes from this
+  changelog) right after the npm publish. Actions updated to v7.
+
 ## [0.5.0] - 2026-11-07
 
 ### Added

package/README.md

@@ -28,8 +28,11 @@ npm install -g cchost
 Requires Node.js 18+ and Claude Code 2.1.140+ (`npm install -g @anthropic-ai/claude-code`).
 
 `cchost` is the primary command. The same binary is also installed as `cc` for
-backwards compatibility, but `cc` is the standard C compiler on macOS and
-Linux — prefer `cchost` in scripts, build files, and daily use.
+backwards compatibility. Because `cc` is also the C compiler on macOS and
+Linux, `cc` only acts as cchost for cchost commands (`cc use work`, `cc list`,
+…); anything else (`cc -c foo.c`, `cc --version`) is passed to the real
+compiler further down `PATH`, so builds keep working. Prefer `cchost` in
+scripts and daily use; `cchost --version` prints cchost's version.
 
 ## Quickstart
 
@@ -39,13 +42,32 @@ cchost use work             # launch Claude under it (prompts for login on first
 cchost use work --resume    # resume the last conversation
 cchost list                 # see all profiles
 cchost remove old-profile   # delete a profile
+cchost ui                   # see and change everything in your browser
 ```
 
+## Web view
+
+`cchost ui` opens a local page that shows every profile, what each one shares with `~/.claude/`, its login and endpoint, and the doctor results. You can add and remove profiles, switch a group between shared and private, copy from `~/.claude/` and apply doctor fixes from the page. Every change shows a per-resource preview first (the same result as `--dry-run`) and, once applied, lists each step it took; the Activity view keeps the history for the session.
+
+Sign-in works like rclone's web GUI. `cchost ui` prints a username (`cchost`) and a random password that is new every run, then opens your browser with a one-time sign-in link (valid 2 minutes). The browser keeps an HttpOnly session cookie that lasts 8 hours (`--session=30m|8h|2d`) or until `cchost ui` stops; the sidebar's Sign out ends it early. Wrong passwords are rate-limited.
+
+```
+cchost ui running at http://127.0.0.1:52134/
+
+  Username:  cchost
+  Password:  k7Qp-3mZx-Wb9t-Lr2v
+  Sessions last 8h. The password is new every run.
+```
+
+The page runs on `127.0.0.1` only. Endpoint tokens are never sent to the page and emails are masked. `--port=N` picks a port, `--no-open` prints the one-time link instead of opening a browser, and `--user=NAME` / `--pass=PASSWORD` set your own credentials (a random password is safer: `--pass` ends up in shell history). Ctrl+C stops it.
+
+In Doctor, every issue with an automatic fix has its own **Fix** button with a preview; fixes the CLI only applies with `--fix --force` (such as resetting a corrupt `.claude.json`) are marked **Fix…** and ask you to confirm. Issues that need a manual step show the command with a copy button.
+
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `cchost add <profile>` | Create a subscription profile. Logs in via Anthropic OAuth on first `cchost use`. Auto-shares all 7 resources with `~/.claude/`. |
+| `cchost add <profile> [--private[=groups]]` | Create a subscription profile. Logs in via Anthropic OAuth on first `cchost use`. Auto-shares all 7 resources with `~/.claude/`, or starts the `--private` ones empty and unshared. |
 | `cchost add <profile> --custom [...]` | Create or edit a custom-endpoint profile. Interactive wizard, or `--base-url=URL --token=TOKEN [--model=…]`. See [Custom endpoints](#custom-endpoints). |
 | `cchost use <profile> [...args]` | Launch Claude under that profile. Extra args are forwarded to `claude`. |
 | `cchost list [<profile>] [--json] [--reveal]` | List all profiles, or show one in detail including the state of each of its 7 resources. Emails and tokens are masked by default; `--reveal` prints them in full. |
@@ -53,6 +75,7 @@ cchost remove old-profile   # delete a profile
 | `cchost link <profile> [--projects\|--tools\|--config] [--dry-run]` | Link a profile's resources to `~/.claude/`. Defaults to all 7 when no flag is passed. |
 | `cchost unlink <profile> [--projects\|--tools\|--config] [--dry-run]` | Break the link and make those resources private to the profile. Non-destructive. |
 | `cchost remove <profile> [--force]` | Delete a profile. Requires typing the profile name. `--force` required when private resources exist. |
+| `cchost ui [--port=N] [--no-open] [--session=8h]` | Open the local web view: see every profile and change sharing, profiles and doctor fixes with a preview first. See [Web view](#web-view). |
 | `cchost doctor [--fix [--force]] [--json]` | Diagnose environment, storage, and platform issues. `--fix` applies safe auto-fixes; `--force` is required for destructive ones. |
 | `cchost help [command]` | Print usage. `cchost help sharing` is a task guide to linking, unlinking, and copying. |
 
@@ -76,7 +99,7 @@ On Windows and Linux, anything that authenticates a profile stays per-profile an
 | `projects/` | ✓ | `--projects` |
 | `skills/`, `agents/`, `commands/` | ✓ | `--tools` |
 | `mcp.json`, `settings.json`, `CLAUDE.md` | ✓ | `--config` |
-| `.credentials.json`, `.claude.json`, `.cc-env.json` | never | — |
+| `.credentials.json`, `.claude.json`, `.cc-env.json`, `.cc-private.json` | never | — |
 | `sessions/`, `plugins/` | never | — |
 
 Sharing uses POSIX symlinks on Linux/macOS and directory junctions on Windows (no admin or Developer Mode required). File resources fall back to a hard link on Windows when symlink creation would require elevation. Note that `mcp.json` and `settings.json` can execute arbitrary code through MCP servers and hooks — if a profile needs an isolated copy of either, run `cchost unlink <profile> --config`.
@@ -86,6 +109,8 @@ Sharing uses POSIX symlinks on Linux/macOS and directory junctions on Windows (n
 > execute hooks and MCP servers. For a work/personal split, unlink the resources
 > that must not cross over before first use, or use a separate OS account.
 
+To create a profile that starts private instead, use `cchost add <profile> --private` (all 7) or `--private=projects,tools,config` (just those groups). Private resources start empty — nothing from `~/.claude/` is copied in — and are recorded in `<profile>/.cc-private.json` so `cchost doctor --fix` never re-shares them.
+
 To see exactly what a profile shares, run `cchost list <profile>` — it prints each resource as `shared`, `private`, `empty`, `missing`, or `foreign-link`. `cchost help sharing` walks through the common tasks.
 
 To break sharing for a single profile (add `--dry-run` to any of these to preview first):

package/bin/cc.js

@@ -2,10 +2,15 @@
 'use strict';
 
 const { run } = require('../lib/cli');
+const { maybeForward } = require('../lib/ccforward');
 
 (async () => {
   try {
-    const code = await run(process.argv.slice(2));
+    const args = process.argv.slice(2);
+    // Invoked as `cc` for a compile (`cc -c foo.c`)? Run the real compiler.
+    const forwarded = maybeForward(args);
+    if (forwarded !== null) process.exit(forwarded);
+    const code = await run(args);
     process.exit(typeof code === 'number' ? code : 0);
   } catch (err) {
     const message = err && err.message ? err.message : String(err);

package/lib/actions.js

@@ -0,0 +1,290 @@
+'use strict';
+
+// Structured versions of cchost's mutating commands, for `cchost ui`. Each
+// action runs in two modes on the same code path the CLI uses: dryRun (the
+// preview) and real (the apply). Both return per-resource lines:
+//   { n, resource, label, kind, text }
+// where kind is 'change' | 'same' | 'warn' | 'error' | 'info', so the page can
+// show exactly what will happen, then exactly what did.
+//
+// Nothing returned here ever contains an endpoint token, and emails are masked.
+
+const fs = require('fs');
+const path = require('path');
+
+const profiles = require('./profiles');
+const share = require('./share');
+const copyLib = require('./copy');
+const envLib = require('./env');
+
+const GROUPS = {
+  projects: share.PROJECT_SUBDIRS,
+  tools: share.TOOL_SUBDIRS,
+  config: share.CONFIG_FILES,
+};
+const GROUP_NAMES = Object.keys(GROUPS);
+
+function groupOf(resource) {
+  return GROUP_NAMES.find((g) => GROUPS[g].includes(resource));
+}
+
+const RESOURCES = share.SHARED_RESOURCES.map((id, i) => ({
+  id,
+  n: String(i + 1).padStart(2, '0'),
+  label: share.isFileResource(id) ? id : `${id}/`,
+  group: groupOf(id),
+}));
+const META = Object.fromEntries(RESOURCES.map((r) => [r.id, r]));
+
+function actionError(message, status = 400) {
+  const e = new Error(message);
+  e.status = status;
+  return e;
+}
+
+// `label` names a profile-level line (no resource), e.g. 'profile', 'login'.
+function line(resource, kind, text, label = null) {
+  if (!resource) return { n: null, resource: null, label, kind, text };
+  const m = META[resource];
+  return { n: m.n, resource, label: m.label, kind, text };
+}
+
+// ['tools', 'config'] -> { tools: true, config: true }. Empty means all 7.
+function groupOpts(groups) {
+  const list = Array.isArray(groups) ? groups : [];
+  const opts = {};
+  for (const g of list) {
+    if (!GROUP_NAMES.includes(g)) throw actionError(`Unknown group "${g}". Use: ${GROUP_NAMES.join(', ')}`);
+    opts[g] = true;
+  }
+  return opts;
+}
+
+function existingProfile(name) {
+  if (typeof name !== 'string') throw actionError('profile is required');
+  profiles.validateProfileName(name);
+  const dir = profiles.profileDir(name);
+  if (!fs.existsSync(dir)) throw actionError(`Profile "${name}" does not exist.`, 404);
+  return dir;
+}
+
+function profileSummary(p) {
+  const resources = {};
+  for (const r of share.SHARED_RESOURCES) resources[r] = share.resourceState(p.dir, r);
+  let endpoint;
+  try {
+    endpoint = envLib.endpointSummary(p.dir);
+  } catch {
+    endpoint = '(invalid config)';
+  }
+  return {
+    name: p.name,
+    loggedIn: p.loggedIn,
+    credentialSource: p.credentialSource,
+    email: p.email ? envLib.maskEmail(p.email) : '',
+    kind: envLib.hasEnvConfig(p.dir) ? 'endpoint' : 'subscription',
+    endpoint,
+    resources,
+    shared: Object.values(resources).filter((s) => s === 'shared').length,
+  };
+}
+
+function state() {
+  return {
+    pool: '~/.claude',
+    profilesDir: '~/.claude-profiles',
+    groups: GROUPS,
+    resources: RESOURCES,
+    profiles: profiles.listProfiles().map(profileSummary),
+  };
+}
+
+// --- link / unlink ---------------------------------------------------------
+
+function link({ profile, groups }, { dryRun }) {
+  existingProfile(profile);
+  const results = share.shareLink(profile, { ...groupOpts(groups), dryRun });
+  return results.map((r) => {
+    if (r.status === 'already-linked') return line(r.resource, 'same', 'already shared');
+    if (r.status === 'linked') {
+      const legacy = r.relinkedFromLegacy ? ' (was pointing at legacy ~/.claude-shared/)' : '';
+      return line(r.resource, 'change', `${dryRun ? 'link to' : 'linked to'} ~/.claude/${r.resource}${legacy}`);
+    }
+    if (r.status === 'refused') {
+      return line(r.resource, 'warn', 'has private content — move or delete it first; it is not merged into ~/.claude/');
+    }
+    if (r.status === 'foreign-link') return line(r.resource, 'warn', 'points outside ~/.claude/ — left alone');
+    return line(r.resource, 'error', r.message || r.status);
+  });
+}
+
+function unlink({ profile, groups }, { dryRun }) {
+  existingProfile(profile);
+  const results = share.shareUnlink(profile, { ...groupOpts(groups), dryRun });
+  return results.map((r) => {
+    if (r.status === 'not-linked') return line(r.resource, 'same', 'already private');
+    if (r.status === 'unlinked') {
+      if (!dryRun) return line(r.resource, 'change', 'unlinked; current content copied in');
+      if (r.items === 0) return line(r.resource, 'change', 'unlink (nothing to copy in — ~/.claude/ has no items here)');
+      const what = r.items === undefined ? 'the current content' : `${r.items} item${r.items === 1 ? '' : 's'}`;
+      return line(r.resource, 'change', `copy ${what} in from ~/.claude/, then unlink`);
+    }
+    return line(r.resource, 'error', r.message || r.status);
+  });
+}
+
+// --- copy ------------------------------------------------------------------
+
+function copy({ profile, force }, { dryRun }) {
+  existingProfile(profile);
+  const { results } = copyLib.copy('default', profile, { force: Boolean(force), dryRun, log: () => {} });
+  const verb = dryRun ? 'copy' : 'copied';
+  return results.map((r) => {
+    if (r.status === 'shared') return line(r.resource, 'same', 'shared — nothing to copy');
+    if (r.status === 'absent') return line(r.resource, 'same', 'not present in ~/.claude/');
+    if (r.status === 'skipped') return line(r.resource, 'same', 'already present (overwrite to replace)');
+    if (r.status === 'copied') return line(r.resource, 'change', `${verb} from ~/.claude/`);
+    if (r.status === 'dir') {
+      if (r.copied === 0 && r.skipped === 0) return line(r.resource, 'same', 'empty in ~/.claude/');
+      const skipped = r.skipped ? `, ${r.skipped} already present` : '';
+      if (r.copied === 0) return line(r.resource, 'same', `all ${r.skipped} item(s) already present`);
+      return line(r.resource, 'change', `${verb} ${r.copied} item${r.copied === 1 ? '' : 's'}${skipped}`);
+    }
+    return line(r.resource, 'info', r.status);
+  });
+}
+
+// --- add -------------------------------------------------------------------
+
+function add({ name, private: privateGroups, endpoint }, { dryRun }) {
+  if (typeof name !== 'string' || !name) throw actionError('name is required');
+  profiles.validateProfileName(name);
+  const dir = profiles.profileDir(name);
+  if (fs.existsSync(dir)) throw actionError(`Profile "${name}" already exists.`, 409);
+
+  const privateOpts = groupOpts(privateGroups);
+  const privateSet = new Set(Object.keys(privateOpts).length ? share.resolveSubset(privateOpts) : []);
+
+  let config = null;
+  if (endpoint) {
+    config = {};
+    for (const key of envLib.FIELDS) {
+      const v = endpoint[key];
+      if (typeof v === 'string' && v.trim()) config[key] = v.trim();
+    }
+    if (!config.base_url || !config.auth_token) {
+      throw actionError('An endpoint profile needs both a base URL and a token.');
+    }
+    const warnings = [];
+    for (const [key, value] of Object.entries(config)) envLib.validateField(key, value, (m) => warnings.push(m));
+  }
+
+  const lines = [line(null, 'change', `${dryRun ? 'create' : 'created'} ~/.claude-profiles/${name}`, 'profile')];
+  if (config) {
+    lines.push(line(null, 'change', `${dryRun ? 'use' : 'uses'} ${envLib.hostOf(config.base_url)} (token stored user-only)`, 'endpoint'));
+  } else {
+    lines.push(line(null, 'info', `Anthropic subscription: sign in on the first "cchost use ${name}"`, 'login'));
+  }
+
+  if (dryRun) {
+    for (const r of share.SHARED_RESOURCES) {
+      lines.push(privateSet.has(r)
+        ? line(r, 'change', 'start private and empty')
+        : line(r, 'change', `link to ~/.claude/${r}`));
+    }
+    return lines;
+  }
+
+  profiles.addProfile(name);
+  try {
+    const sharedOpts = {};
+    for (const g of GROUP_NAMES) if (!privateOpts[g]) sharedOpts[g] = true;
+    const linkResults = Object.keys(sharedOpts).length ? share.shareLink(name, sharedOpts) : [];
+    for (const r of share.SHARED_RESOURCES) {
+      if (privateSet.has(r)) {
+        if (!share.isFileResource(r)) fs.mkdirSync(path.join(dir, r), { recursive: true });
+        lines.push(line(r, 'change', 'private and empty'));
+        continue;
+      }
+      const res = linkResults.find((x) => x.resource === r);
+      lines.push(res && (res.status === 'linked' || res.status === 'already-linked')
+        ? line(r, 'change', `linked to ~/.claude/${r}`)
+        : line(r, 'warn', `not linked — ${(res && res.message) || 'unknown'}`));
+    }
+    share.markPrivate(dir, privateSet);
+    if (config) envLib.writeEnvConfig(dir, config);
+  } catch (err) {
+    // Same as the CLI: a half-created profile is removed, shared content kept.
+    try {
+      require('./cli').removeRecursivelyPreservingLinks(dir);
+    } catch { /* best effort */ }
+    throw err;
+  }
+  return lines;
+}
+
+// --- remove ----------------------------------------------------------------
+
+function remove({ profile, confirm }, { dryRun }) {
+  const dir = existingProfile(profile);
+  const lines = [];
+  for (const r of share.SHARED_RESOURCES) {
+    const st = share.resourceState(dir, r);
+    if (st === 'shared') lines.push(line(r, 'same', 'shared — only the link is removed, ~/.claude/ keeps the content'));
+    else if (st === 'private') lines.push(line(r, 'warn', 'private content deleted permanently'));
+    else if (st === 'foreign-link') lines.push(line(r, 'same', 'link removed; its target is left alone'));
+    else lines.push(line(r, 'same', 'nothing to delete'));
+  }
+  lines.push(line(null, 'warn', `login, sessions and settings in ~/.claude-profiles/${profile} deleted`, 'login'));
+  if (dryRun) return lines;
+
+  if (confirm !== profile) throw actionError(`Type the profile name "${profile}" to confirm removal.`);
+  require('./cli').removeRecursivelyPreservingLinks(dir);
+  return [line(null, 'change', `removed ~/.claude-profiles/${profile}`, 'profile'), ...lines];
+}
+
+// --- doctor ----------------------------------------------------------------
+
+function doctorChecks() {
+  const doctor = require('./doctor');
+  return doctor.runChecks().map((c) => ({
+    group: c.group,
+    name: c.name,
+    status: c.status,
+    message: c.message,
+    fixable: Boolean(c.fix && c.fix.apply && c.fix.safe),
+    // Has an automatic fix that `doctor --fix` only runs with --force.
+    forceable: Boolean(c.fix && c.fix.apply && !c.fix.safe),
+    fix: c.fix ? (c.fix.description || null) : null,
+    cmd: c.fix ? (c.fix.cmd || null) : null,
+  }));
+}
+
+// With no name: every safe fix, the same set `cchost doctor --fix` applies.
+// With a name: just that check's fix; one that needs confirmation (the CLI's
+// --force) runs only when `force` is true, i.e. the user confirmed it.
+async function doctorFix({ name, force } = {}, { dryRun }) {
+  const doctor = require('./doctor');
+  const results = doctor.runChecks();
+  let fixable;
+  if (name) {
+    const target = results.find((r) => r.name === name && r.status !== 'ok');
+    if (!target) return [line(null, 'same', `"${name}" no longer needs fixing`, 'doctor')];
+    if (!target.fix || !target.fix.apply) throw actionError(`"${name}" has no automatic fix.`);
+    if (!target.fix.safe && !force) throw actionError(`"${name}" needs confirmation to fix.`);
+    fixable = [target];
+  } else {
+    fixable = results.filter((r) => r.fix && r.fix.apply && r.fix.safe);
+  }
+  if (fixable.length === 0) return [line(null, 'same', 'nothing auto-fixable', 'doctor')];
+  if (dryRun) return fixable.map((r) => line(null, 'change', `${r.name}: ${r.fix.description || 'fix'}`, 'fix'));
+  const out = [];
+  await doctor.applyFixes(fixable, Boolean(name && force), async () => 'y', (text) => {
+    for (const t of String(text).split('\n')) if (t.trim()) out.push(line(null, 'change', t.trim(), 'fix'));
+  });
+  return out;
+}
+
+const ACTIONS = { link, unlink, copy, add, remove, 'doctor-fix': doctorFix };
+
+module.exports = { state, doctorChecks, ACTIONS, RESOURCES, GROUPS, actionError };

package/lib/ccforward.js

@@ -0,0 +1,77 @@
+'use strict';
+
+// The legacy `cc` alias shares its name with the POSIX C compiler, and npm's
+// global bin dir often sits ahead of /usr/bin on PATH. Build tools (make,
+// node-gyp, configure scripts) then run cchost instead of the compiler. When
+// we are invoked as `cc` with arguments that are not a cchost command, hand
+// the call to the next real `cc` on PATH so both uses keep working.
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// First arguments that mean "this is cchost". Everything else — `-c`, `-o`,
+// `foo.c`, and `--version` / `-v`, which build tools use to probe the
+// compiler — goes to the compiler. Use `cchost --version` for cchost itself.
+const CCHOST_FIRST_ARGS = new Set([
+  'add', 'use', 'list', 'copy', 'migrate', 'link', 'unlink', 'remove',
+  'doctor', 'ui', 'help', 'env', '--help', '-h',
+]);
+
+function invokedAsCc(argv1 = process.argv[1]) {
+  // npm installs `cc` as a symlink on POSIX and Node keeps the symlink's name
+  // in argv[1]. Windows .cmd shims call bin/cc.js directly, so this is false
+  // there — `cc` is rarely a compiler on Windows anyway.
+  return Boolean(argv1) && path.basename(argv1) === 'cc';
+}
+
+function shouldForward(args) {
+  // Bare `cc` keeps printing cchost help, as it always has.
+  return args.length > 0 && !CCHOST_FIRST_ARGS.has(args[0]);
+}
+
+function realpathOrNull(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return null;
+  }
+}
+
+// The first executable `cc` on PATH that is not cchost (this install or any
+// other cchost install, e.g. under another nvm Node version).
+function findCompiler({ env = process.env, self = process.argv[1] } = {}) {
+  const selfReal = realpathOrNull(self);
+  const dirs = (env.PATH || '').split(path.delimiter).filter(Boolean);
+  for (const dir of dirs) {
+    const candidate = path.join(dir, 'cc');
+    const real = realpathOrNull(candidate);
+    if (!real || real === selfReal) continue;
+    if (/[\\/]cchost[\\/]bin[\\/]cc\.js$/.test(real)) continue;
+    try {
+      if (!fs.statSync(real).isFile()) continue;
+      fs.accessSync(real, fs.constants.X_OK);
+    } catch {
+      continue;
+    }
+    return candidate;
+  }
+  return null;
+}
+
+// Returns the compiler's exit code, or null when the call is not forwarded
+// (not invoked as `cc`, a cchost command, or no compiler found).
+function maybeForward(args, { argv1 = process.argv[1], env = process.env } = {}) {
+  if (!invokedAsCc(argv1) || !shouldForward(args)) return null;
+  const compiler = findCompiler({ env, self: argv1 });
+  if (!compiler) return null;
+  const res = spawnSync(compiler, args, { stdio: 'inherit', env });
+  if (res.error) throw res.error;
+  if (res.signal) {
+    process.kill(process.pid, res.signal);
+    return 1;
+  }
+  return res.status === null ? 1 : res.status;
+}
+
+module.exports = { invokedAsCc, shouldForward, findCompiler, maybeForward, CCHOST_FIRST_ARGS };