@codeyam-editor/codeyam-editor 0.1.4 → 0.1.6

package/npm/codesign-plan.js

@@ -0,0 +1,68 @@
+"use strict";
+// Pure helpers for scripts/package-mcpb.js's darwin code-signing step.
+//
+// Dependency-free and unit-tested (npm/codesign-plan.test.js) so the packaging
+// script keeps the sign decision + argv rendering out of its execSync path:
+// signDarwinBinary stays thin boundary glue while every branch of "do we sign,
+// and with which command" is exercised here without invoking codesign.
+
+/**
+ * The `codesign` argv for a Developer ID signature with a secure timestamp.
+ * Pure — takes the identity and binary path, returns the flag list. `--force`
+ * replaces cargo's ad-hoc signature (codesign refuses an already-signed binary
+ * otherwise); `--timestamp` embeds the secure timestamp a later notarization
+ * needs.
+ */
+function codesignArgs(identity, binaryPath) {
+  return ["--force", "--timestamp", "--sign", identity, binaryPath];
+}
+
+/**
+ * The shell-quoted `codesign …` command string for signing `binaryPath` with
+ * `identity`. Pure: quotes each argv element so a path or identity with spaces
+ * survives the shell.
+ */
+function codesignCommand(identity, binaryPath) {
+  const quoted = codesignArgs(identity, binaryPath)
+    .map((a) => `"${a}"`)
+    .join(" ");
+  return `codesign ${quoted}`;
+}
+
+/**
+ * Decide whether/how to sign the staged darwin binary, given the target
+ * `platform`, the configured Developer ID `identity`, the `hostPlatform`
+ * (process.platform), and a `serverLabel` for the warning text. Pure — no I/O,
+ * no env, no clock — so the decision and its warnings are unit-testable.
+ *
+ * Returns `{ action: "sign", identity }` when a real Developer ID signature is
+ * possible, otherwise `{ action: "skip", warning? }`: the non-darwin target is a
+ * silent skip (its binary is not Mach-O), while a missing identity or a
+ * non-macOS host skips WITH a warning so an unsigned local bundle stays testable
+ * on the machine that built it rather than failing the build.
+ */
+function signPlan({ platform, identity, hostPlatform, serverLabel }) {
+  if (platform !== "darwin") {
+    return { action: "skip" };
+  }
+  if (!identity) {
+    return {
+      action: "skip",
+      warning:
+        `⚠️  ${serverLabel} is ad-hoc signed — set MCPB_SIGN_IDENTITY (or ` +
+        `APPLE_SIGNING_IDENTITY) to a Developer ID identity to sign it. An unsigned ` +
+        `binary has no stable Keychain identity and re-prompts for access.`,
+    };
+  }
+  if (hostPlatform !== "darwin") {
+    return {
+      action: "skip",
+      warning:
+        `⚠️  cannot codesign ${serverLabel} on ${hostPlatform} — ` +
+        `sign the darwin binary on a macOS host.`,
+    };
+  }
+  return { action: "sign", identity };
+}
+
+module.exports = { codesignArgs, codesignCommand, signPlan };

package/npm/container.js

@@ -35,6 +35,9 @@ async function main() {
     14199,
   );
 
+  // A cloud container's stdin is not a TTY, so the cross-project takeover prompt
+  // in `ensureServer` resolves to "abort" (print-and-exit) here — never a silent
+  // kill of another project's editor in a headless context.
   const serverChild = await ensureServer(PORT);
   const url = `http://localhost:${PORT}`;
   console.error(`Container UI: ${url}`);

package/npm/disk-pressure.js

@@ -45,6 +45,63 @@ const PRUNABLE_CACHE_DIRS = [
   '.angular/cache',
 ];
 
+// The in-container mount of the persistent cargo build-target volume
+// (`cargo-target:/codeyam-build-target`, set as CARGO_TARGET_DIR in
+// docker-compose.cloud.template.yml). This is SEPARATE from PRUNABLE_CACHE_DIRS
+// on purpose: the frontend-cache allowlist deliberately excludes Rust target/
+// (expensive to rebuild), so it can never reclaim this volume — yet on a
+// self-host VM that builds codeyam-editor, this volume is exactly what fills the
+// disk (VM-3 grew it to ~69GB and wedged). The reclamation below is narrowly
+// keyed on this known mount path, NOT folded into the generic allowlist, so a
+// client project's own Rust target/ is never touched.
+//
+// Stack assumption: only self-host VMs that run cargo write to this volume;
+// guest/client VMs (Next.js, Vite, Tauri, Python, …) carry an empty or absent
+// volume, so cargoTargetReclaimPlan returns an empty plan there (a guaranteed
+// no-op — honoring the stack-agnosticism rule in CLAUDE.md).
+const CARGO_TARGET_DIR = '/codeyam-build-target';
+
+// Sub-dirs of CARGO_TARGET_DIR that are ALWAYS safe to delete: pure coverage
+// instrumentation, regenerated on every `llvm-cov` run. Reclaiming this costs
+// the warm incremental build nothing (~13GB on VM-3). Pruned at WARN already.
+const CARGO_TARGET_ALWAYS_PRUNE = ['llvm-cov-target'];
+
+// Sub-trees reclaimed ONLY at CRITICAL and ONLY when no build is in flight:
+// `debug/` is the incremental compile cache that keeps `rebuild-self` fast, so
+// deleting it forces a ~14-min cold recompile. We pay that cost only when the
+// disk is genuinely critical AND nothing is mid-build (else we'd sabotage an
+// in-flight compile to free space — the failure mode this tiering avoids).
+const CARGO_TARGET_CRITICAL_CLEAN = ['debug'];
+
+// Pure decision function for tiered cargo-target reclamation. Given the current
+// pressure `level`, whether a build is in flight, and whether this VM actually
+// has the cargo-target volume, return which sub-dirs to prune and whether the
+// heavy `debug` clean was deferred (so the caller can log it — no silent cap).
+//
+// Tiers (mirrored by the bash guard + watchdog):
+//   - no cargo-target (guest/client VM)      → prune nothing (total no-op)
+//   - warn                                   → ALWAYS_PRUNE only (llvm-cov)
+//   - critical & idle                        → ALWAYS_PRUNE + CRITICAL_CLEAN
+//   - critical & build in flight             → ALWAYS_PRUNE only, defer heavy
+//   - ok / unknown level                     → fail-safe: prune nothing
+function cargoTargetReclaimPlan({ level, buildInFlight, hasCargoTarget } = {}) {
+  if (!hasCargoTarget) return { prune: [], deferredHeavyClean: false };
+  if (level === 'warn') {
+    return { prune: [...CARGO_TARGET_ALWAYS_PRUNE], deferredHeavyClean: false };
+  }
+  if (level === 'critical') {
+    if (buildInFlight) {
+      return { prune: [...CARGO_TARGET_ALWAYS_PRUNE], deferredHeavyClean: true };
+    }
+    return {
+      prune: [...CARGO_TARGET_ALWAYS_PRUNE, ...CARGO_TARGET_CRITICAL_CLEAN],
+      deferredHeavyClean: false,
+    };
+  }
+  // 'ok', undefined, or any unknown level → do nothing (fail safe).
+  return { prune: [], deferredHeavyClean: false };
+}
+
 // Classify an integer disk-usage percent into a pressure level. A non-numeric,
 // non-finite, or out-of-range (<0 or >100) value is treated as a BAD READING
 // and classified 'ok' with no action — a misread must never escalate to a
@@ -80,10 +137,31 @@ function parseDfUsedPct(dfOutput) {
   return null;
 }
 
+// Classify a disk-guard sidecar age (updatedAt vs current time).
+// If the sidecar is older than 600s (10 min), classify it as stale.
+function classifySidecarAge(updatedAt, currentEpoch) {
+  if (typeof updatedAt !== 'number' || typeof currentEpoch !== 'number') return 'stale';
+  const age = currentEpoch - updatedAt;
+  if (age > 600) return 'stale';
+  return 'healthy';
+}
+
+// Map or classify a general disk state level including 'unknown-exec-failed'
+function mapDiskStateLevel(usedPct, hasExecError) {
+  if (hasExecError) return 'unknown-exec-failed';
+  return classifyDiskPressure(usedPct);
+}
+
 module.exports = {
   DISK_WARN_PCT,
   DISK_CRITICAL_PCT,
   PRUNABLE_CACHE_DIRS,
+  CARGO_TARGET_DIR,
+  CARGO_TARGET_ALWAYS_PRUNE,
+  CARGO_TARGET_CRITICAL_CLEAN,
+  cargoTargetReclaimPlan,
   classifyDiskPressure,
   parseDfUsedPct,
+  classifySidecarAge,
+  mapDiskStateLevel,
 };

package/npm/editor-dev.js

@@ -28,6 +28,7 @@
 
 const { execSync, spawn, spawnSync } = require("child_process");
 const path = require("path");
+const os = require("os");
 const {
   ensureServer,
   restartServer,
@@ -89,6 +90,62 @@ function buildBinary() {
   }
 }
 
+/**
+ * Build the React UI from the editor repo into ui/dist/. A failed build is
+ * non-fatal: log a warning and continue on the last-good bundle so a transient
+ * vite failure doesn't block launch. The cargo build embeds ui/dist/ at compile
+ * time via include_dir! (crates/control-api/src/embedded_ui.rs), so this MUST
+ * run before buildBinary() or the binary embeds the *previous* launch's bundle.
+ */
+function buildUI() {
+  console.error("Building UI...");
+  try {
+    execSync("npx vite build", { stdio: "inherit", cwd: path.join(rootDir, "ui") });
+  } catch {
+    console.error("Failed to build UI. Continuing with existing build (if any)...");
+  }
+}
+
+/**
+ * Build the launcher artifacts in embed-correct order: UI first (so the fresh
+ * ui/dist/ is on disk), then the Rust binary (which embeds that dist via
+ * include_dir!). build.rs declares `cargo:rerun-if-changed=ui/dist`, so a fresh
+ * bundle on disk before compilation forces cargo to recompile and embed it in
+ * the same launch — fixing the one-generation-stale UI bug. Only the launcher
+ * (no-subcommand) path calls this; the passthrough path rebuilds only the Rust
+ * binary and embeds no fresh UI, which is correct for non-launcher commands.
+ * Side-effecting steps are injectable so the ordering can be unit-tested.
+ */
+function buildLauncherArtifacts(deps = {}) {
+  const {
+    buildUI: doBuildUI = buildUI,
+    buildBinary: doBuildBinary = buildBinary,
+    enforceFreshBinary: doEnforceFreshBinary = enforceFreshBinary,
+  } = deps;
+  // UI build FIRST — the fresh bundle must be on disk before cargo embeds it.
+  doBuildUI();
+  doEnforceFreshBinary(doBuildBinary(), {
+    action: "run editor commands",
+    continueVerb: "launching with",
+  });
+}
+
+/**
+ * Rebuild artifacts for the passthrough path (a known subcommand like
+ * `editor step`/`advance`): the Rust binary ONLY, no UI build. Non-launcher
+ * commands never serve a fresh UI, so embedding a rebuilt bundle would be
+ * wasted work — and pulling vite into every CLI invocation would slow the
+ * common `editor advance` round-trip. Side-effecting steps are injectable so
+ * the "no UI build on passthrough" contract is unit-testable.
+ */
+function buildPassthroughArtifacts(deps = {}) {
+  const {
+    buildBinary: doBuildBinary = buildBinary,
+    enforceFreshBinary: doEnforceFreshBinary = enforceFreshBinary,
+  } = deps;
+  doEnforceFreshBinary(doBuildBinary(), { action: "run editor commands" });
+}
+
 /**
  * Decide whether the dev wrapper should rebuild the Rust binary (and the UI,
  * for the launcher path) before forwarding to it. The answer is always yes:
@@ -114,6 +171,32 @@ function shouldRebuildOnPassthrough() {
   return true;
 }
 
+/**
+ * Translate a passthrough child's exit into the code the dev wrapper should
+ * forward. A subcommand passthrough must report the inner editor binary's OWN
+ * outcome faithfully so every caller (gates, scripts, the agent) can trust the
+ * exit code:
+ *
+ *   - A real exit code (including 0) is forwarded verbatim — a successful
+ *     `analyze-imports` that printed valid JSON and exited 0 stays exit 0,
+ *     never a spurious 1.
+ *   - A null/undefined code means the child was terminated by a signal (e.g.
+ *     SIGPIPE after it already produced its output, or SIGTERM at teardown).
+ *     Report it distinctly via the conventional 128+signum so a clean run that
+ *     was merely signalled at the end is not collapsed into a generic `1` that
+ *     reads as a command failure. The previous `code ?? 1` erased that
+ *     distinction, surfacing a successful inner command as exit 1.
+ *
+ * Pure (no process.exit) so the mapping is unit-testable.
+ */
+function passthroughExitCode(code, signal) {
+  if (code !== null && code !== undefined) {
+    return code;
+  }
+  const signum = signal ? os.constants.signals[signal] : undefined;
+  return signum ? 128 + signum : 1;
+}
+
 /**
  * Returns true when the merged project config has a non-empty start
  * command — either at `apps[0].startCommand` (per-app, preferred) or at
@@ -250,7 +333,11 @@ function shouldOpenBrowser({ shouldRestart, wasRunning, freshInit }) {
 module.exports = {
   hasSubcommand,
   buildBinary,
+  buildUI,
+  buildLauncherArtifacts,
+  buildPassthroughArtifacts,
   shouldRebuildOnPassthrough,
+  passthroughExitCode,
   staleBinaryBanner,
   hasStartCommand,
   planPreflightAction,
@@ -268,7 +355,7 @@ if (require.main === module) {
     // exactly when the developer wants the new code live. `ensureBinary()`
     // still builds once if no binary exists at all.
     if (shouldRebuildOnPassthrough()) {
-      enforceFreshBinary(buildBinary(), { action: "run editor commands" });
+      buildPassthroughArtifacts();
     }
     const binary = ensureBinary();
     const child = spawn(binary, args, {
@@ -276,8 +363,11 @@ if (require.main === module) {
       cwd: process.cwd(),
       env: process.env,
     });
-    child.on("exit", (code) => {
-      process.exit(code ?? 1);
+    child.on("exit", (code, signal) => {
+      // Forward the inner editor binary's OWN outcome faithfully — exit 0
+      // stays 0, a signal-terminated child reports 128+signum, not a generic
+      // 1 that would mask a successful command (see passthroughExitCode).
+      process.exit(passthroughExitCode(code, signal));
     });
   } else {
     // --- Launcher mode: build everything, start server, open browser ---
@@ -352,18 +442,9 @@ if (require.main === module) {
       // client-project launch is never disrupted. `ensureBinary()` still
       // builds once if no binary exists.
       if (shouldRebuildOnPassthrough()) {
-        enforceFreshBinary(buildBinary(), {
-          action: "run editor commands",
-          continueVerb: "launching with",
-        });
-
-        // Build the UI from the editor repo
-        console.error("Building UI...");
-        try {
-          execSync("npx vite build", { stdio: "inherit", cwd: path.join(rootDir, "ui") });
-        } catch {
-          console.error("Failed to build UI. Continuing with existing build (if any)...");
-        }
+        // Embed-correct order: UI build → cargo build (embeds the fresh
+        // ui/dist via include_dir!). See buildLauncherArtifacts.
+        buildLauncherArtifacts();
       }
 
       const serverChild = shouldRestart

package/npm/editor.js

@@ -28,8 +28,9 @@ const {
   resolveLauncherPort,
   resolveWrappedAppPort,
   classifyPortHolder,
+  fetchServerIdentity,
   formatForeignListenerError,
-  formatCrossProjectError,
+  resolveCrossProjectCollision,
   staleBinaryBanner,
   enforceFreshBinary,
 } = require("./utils");
@@ -47,6 +48,58 @@ function buildBinary() {
   }
 }
 
+// Build the React UI into ui/dist/. A failed build is non-fatal: we log a
+// warning and continue on the last-good bundle (a transient vite failure must
+// not block launch). The cargo build embeds ui/dist/ at compile time via
+// include_dir! (crates/control-api/src/embedded_ui.rs), so this MUST run
+// before buildBinary() or the binary embeds the *previous* launch's bundle.
+function buildUI() {
+  console.error("Building UI...");
+  try {
+    execSync("npx vite build", {
+      stdio: "inherit",
+      cwd: path.join(rootDir, "ui"),
+    });
+  } catch {
+    console.error("Failed to build UI. Continuing with existing build (if any)...");
+  }
+}
+
+// Build the launch artifacts in embed-correct order: UI first (so the fresh
+// ui/dist/ is on disk), then the Rust binary (which embeds that dist via
+// include_dir!), then install the freshly-compiled binary. build.rs declares
+// `cargo:rerun-if-changed=ui/dist`, so a fresh bundle on disk before
+// compilation forces cargo to recompile and embed it in the same launch —
+// fixing the one-generation-stale UI bug. Side-effecting steps are injectable
+// so the ordering can be unit-tested without shelling out to vite/cargo.
+function buildArtifacts(deps = {}) {
+  const {
+    buildUI: doBuildUI = buildUI,
+    buildBinary: doBuildBinary = buildBinary,
+    enforceFreshBinary: doEnforceFreshBinary = enforceFreshBinary,
+    installBinary: doInstallBinary = installBinary,
+  } = deps;
+
+  // UI build FIRST — the fresh bundle must be on disk before cargo embeds it.
+  doBuildUI();
+  // Rebuild the Rust binary so code changes (and the just-built UI) are picked
+  // up on restart. This script is only invoked from a source checkout (via
+  // `npm run editor`), so Cargo.toml and the crates tree are always present.
+  const buildOk = doBuildBinary();
+  // A failed rebuild means the server would boot on a stale binary that no
+  // longer matches the source. Refuse by default; CODEYAM_ALLOW_STALE=1 forces
+  // the old behavior (continue with the last-good install).
+  doEnforceFreshBinary(buildOk, { action: "start the editor server" });
+  // Refresh <cargo_bin>/codeyam-editor (and the pty-broker hardlink) so the
+  // broker auto-spawn execs a binary that knows the `pty-broker daemon`
+  // subcommand. Skip if the build failed — installing a stale debug binary
+  // over a working install is worse than leaving it.
+  if (buildOk) {
+    doInstallBinary();
+  }
+  return buildOk;
+}
+
 // Resolve <CARGO_HOME>/bin (falling back to $HOME/.cargo/bin). Mirrors
 // `installed_binary_path()` in crates/control-api/src/pty_broker_startup.rs
 // — the Rust broker auto-spawn execs the binary at this path, so we MUST
@@ -181,32 +234,9 @@ async function main() {
   // VITE_PORT + 1. We need to wait for the real Vite server, not the proxy.
   const VITE_INTERNAL_PORT = VITE_PORT + 1;
 
-  // Rebuild the Rust binary so code changes are picked up on restart.
-  // This script is only invoked from a source checkout (via `npm run editor`),
-  // so Cargo.toml and the crates tree are always present.
-  const buildOk = buildBinary();
-  // A failed rebuild means the server would boot on a stale binary that no
-  // longer matches the source. Refuse by default; CODEYAM_ALLOW_STALE=1
-  // forces the old behavior (continue with the last-good install).
-  enforceFreshBinary(buildOk, { action: "start the editor server" });
-  // Refresh <cargo_bin>/codeyam-editor (and the pty-broker hardlink) so
-  // the broker auto-spawn execs a binary that knows the `pty-broker
-  // daemon` subcommand. Skip if the build failed — installing a stale
-  // debug binary over a working install is worse than leaving it.
-  if (buildOk) {
-    installBinary();
-  }
-
-  // Build the UI so the backend can serve it as static files
-  console.error("Building UI...");
-  try {
-    execSync("npx vite build", {
-      stdio: "inherit",
-      cwd: path.join(rootDir, "ui"),
-    });
-  } catch {
-    console.error("Failed to build UI. Continuing with existing build (if any)...");
-  }
+  // Build the launch artifacts in embed-correct order: UI build → cargo build
+  // (embeds the fresh ui/dist via include_dir!) → install. See buildArtifacts.
+  buildArtifacts();
 
   // Start the Rust backend — it serves ui/dist/ and launches the Vite dev
   // server (configured via startCommand in editor.json) for Live Preview HMR.
@@ -223,8 +253,12 @@ async function main() {
       process.exit(1);
     }
     if (holder.kind === "cross-project") {
-      console.error(formatCrossProjectError(SERVER_PORT, holder, "restart"));
-      process.exit(1);
+      const outcome = await resolveCrossProjectCollision(SERVER_PORT, holder, "restart");
+      if (outcome.action !== "took-over") {
+        // "abort" (non-TTY) or "declined": resolver already printed the message.
+        process.exit(1);
+      }
+      // took-over: stopServer freed the port; fall through to the fresh-boot path.
     }
     if (holder.kind === "same-project") {
       console.error(`Stopping existing server on port ${SERVER_PORT}...`);
@@ -237,17 +271,29 @@ async function main() {
   }
   const serverChild = await ensureServer(SERVER_PORT);
 
-  // Wait for the actual Vite dev server on the internal port (not the reverse
-  // proxy on VITE_PORT, which starts immediately with the Rust binary).
-  console.error("Waiting for Vite dev server...");
-  const viteReady = await waitForPort(VITE_INTERNAL_PORT, 15000, 300);
-  if (!viteReady) {
-    console.error(`Warning: Vite dev server not ready on port ${VITE_INTERNAL_PORT}. Live Preview may not work initially.`);
+  // With 2+ projects registered the launch diverts to the Project Launcher
+  // (selector) on SERVER_PORT — there is no wrapped app, so the Vite wait and
+  // the "Live Preview" line don't apply. Probe the identity to detect it;
+  // best-effort, a missed detection only yields a harmless "Vite not ready"
+  // warning, never a failure.
+  const identity = await fetchServerIdentity(SERVER_PORT);
+  const launcherMode = Boolean(identity && identity.role === "launcher");
+
+  if (!launcherMode) {
+    // Wait for the actual Vite dev server on the internal port (not the reverse
+    // proxy on VITE_PORT, which starts immediately with the Rust binary).
+    console.error("Waiting for Vite dev server...");
+    const viteReady = await waitForPort(VITE_INTERNAL_PORT, 15000, 300);
+    if (!viteReady) {
+      console.error(`Warning: Vite dev server not ready on port ${VITE_INTERNAL_PORT}. Live Preview may not work initially.`);
+    }
   }
 
   const url = `http://localhost:${SERVER_PORT}`;
-  console.error(`Editor UI: ${url}`);
-  console.error(`Live Preview: http://localhost:${VITE_PORT}`);
+  console.error(launcherMode ? `Project selector: ${url}` : `Editor UI: ${url}`);
+  if (!launcherMode) {
+    console.error(`Live Preview: http://localhost:${VITE_PORT}`);
+  }
   console.error(`Logs: ${path.join(rootDir, ".codeyam", "logs")}`);
   open(url);
   const keepAlive = setInterval(() => {}, 60_000);
@@ -271,6 +317,8 @@ async function main() {
 
 module.exports = {
   buildBinary,
+  buildUI,
+  buildArtifacts,
   staleBinaryBanner,
   cargoBinDir,
   installBinary,

package/npm/empty-project-dir.js

@@ -1,13 +1,14 @@
 "use strict";
 
 /**
- * Launcher-side mirror of `is_empty_project_dir` in
+ * Launcher-side mirrors of `is_empty_project_dir` and
+ * `looks_like_onboardable_project` in
  * `crates/codeyam-editor/src/commands/init.rs`. The Rust side decides
- * which `/codeyam-…` skill the init binary points at; this JS mirror
- * decides the same for the launcher's post-launch tail banner. Keep
- * both in sync — the test `empty-project-dir.test.js` and Rust's
- * `is_empty_project_dir_ignores_hidden_entries` /
- * `is_empty_project_dir_detects_visible_entry` pin the contract.
+ * which `/codeyam-…` skill the init binary points at; these JS mirrors
+ * decide the same for the launcher's post-launch tail banner. Keep both
+ * predicates in sync with Rust — the test `empty-project-dir.test.js`
+ * and Rust's `is_empty_project_dir_*` / `looks_like_onboardable_project_*`
+ * tests pin the contracts.
  *
  * A "fresh" project directory has no non-hidden entries — only things
  * like `.git/`, `.gitignore`, or other dotfiles. Hidden entries don't
@@ -19,6 +20,7 @@
  */
 
 const fs = require("node:fs");
+const path = require("node:path");
 
 function isEmptyProjectDir(projectDir) {
   let entries;
@@ -30,4 +32,87 @@ function isEmptyProjectDir(projectDir) {
   return entries.every((name) => name.startsWith("."));
 }
 
-module.exports = { isEmptyProjectDir };
+// Root files that signal a real project: dependency/build manifests,
+// lockfiles, and the static-site `index.html`. Mirror of the Rust
+// `MANIFEST_MARKERS` list.
+const MANIFEST_MARKERS = new Set([
+  "package.json",
+  "Cargo.toml",
+  "pyproject.toml",
+  "requirements.txt",
+  "setup.py",
+  "go.mod",
+  "Gemfile",
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+  "composer.json",
+  "pubspec.yaml",
+  "Package.swift",
+  "mix.exs",
+  "deno.json",
+  "CMakeLists.txt",
+  "Makefile",
+  "tsconfig.json",
+  "index.html",
+]);
+
+// Subdirectories that signal an organized source tree. Mirror of the Rust
+// `SOURCE_DIR_MARKERS` list.
+const SOURCE_DIR_MARKERS = new Set([
+  "src",
+  "app",
+  "lib",
+  "pages",
+  "components",
+  "crates",
+  "packages",
+  "source",
+  "include",
+]);
+
+/**
+ * Does this directory contain a *project* worth onboarding, as opposed to
+ * being empty or holding only a stray file or two? Mirror of Rust
+ * `looks_like_onboardable_project`. A folder "contains a project" when it
+ * holds a recognized manifest / lockfile, a `.csproj` / `.xcodeproj`, a root
+ * `index.html`, OR an organized source subdirectory. Intentionally
+ * marker-based, not file-count based: a home dir full of loose files is still
+ * not a project. A read error returns false (not a project → the
+ * auto-init/open path), matching Rust's `Err(_) => false`.
+ */
+function looksLikeOnboardableProject(projectDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(projectDir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const entry of entries) {
+    const name = entry.name;
+    if (MANIFEST_MARKERS.has(name)) {
+      return true;
+    }
+    if (name.endsWith(".csproj") || name.endsWith(".xcodeproj")) {
+      return true;
+    }
+    // Source-tree markers only count as directories, not like-named files.
+    if (SOURCE_DIR_MARKERS.has(name)) {
+      let isDir = entry.isDirectory();
+      // A symlinked source dir surfaces as a symlink Dirent; resolve it.
+      if (!isDir && entry.isSymbolicLink()) {
+        try {
+          isDir = fs.statSync(path.join(projectDir, name)).isDirectory();
+        } catch {
+          isDir = false;
+        }
+      }
+      if (isDir) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+module.exports = { isEmptyProjectDir, looksLikeOnboardableProject };