amicus 1.6.1 → 1.7.0

package/src/utils/project-root-sanity.js

@@ -0,0 +1,66 @@
+// src/utils/project-root-sanity.js
+'use strict';
+
+/**
+ * Project-root sanity heuristic (#43).
+ *
+ * `amicus doctor` resolves the project dir from process.cwd(); when a user
+ * launches amicus from a packaged-app/install directory (e.g. the Claude
+ * Desktop app dir) instead of their repo, sessions land in the wrong place.
+ * This pure helper inspects a path string + its directory markers and decides
+ * whether to WARN. It never touches the filesystem and never throws.
+ */
+
+/**
+ * Path fragments that signal a packaged-app / install directory rather than a
+ * user project. Matched case-insensitively against the normalized path.
+ */
+const INSTALL_PATTERNS = [
+  /anthropicclaude/i,        // Claude Desktop app dir
+  /[\\/]app-\d/i,            // versioned electron app dir, e.g. app-1.2.3
+  /appdata[\\/]local/i,      // Windows per-user app data
+  /program files/i,          // Windows install root
+  /[\\/]\.asar/i,            // packaged electron resources
+];
+
+/** @returns {boolean} true if the path looks like an app/install dir */
+function looksLikeInstallDir(dir) {
+  if (!dir || typeof dir !== 'string') { return false; }
+  return INSTALL_PATTERNS.some((re) => re.test(dir));
+}
+
+/**
+ * Assess a resolved project dir.
+ *
+ * @param {string} dir Resolved project directory (e.g. process.cwd()).
+ * @param {{hasGit?:boolean, hasPackageJson?:boolean, hasClaude?:boolean}} markers
+ *   Presence of .git / package.json / .claude in `dir`.
+ * @returns {{status:'ok'|'warn', message:string, hint:string|null}}
+ */
+function assessProjectRoot(dir, markers) {
+  const m = markers || {};
+  const safeDir = (dir && typeof dir === 'string') ? dir : '';
+  const hint =
+    'pass an explicit project (amicus … --project <path>) or cd into your repo before running amicus';
+
+  if (looksLikeInstallDir(safeDir)) {
+    return {
+      status: 'warn',
+      message: `${safeDir || '(empty)'} looks like an app/install dir, not a project`,
+      hint,
+    };
+  }
+
+  const hasMarker = !!(m.hasGit || m.hasPackageJson || m.hasClaude);
+  if (!hasMarker) {
+    return {
+      status: 'warn',
+      message: `${safeDir || '(empty)'} has no project markers (.git / package.json / .claude)`,
+      hint,
+    };
+  }
+
+  return { status: 'ok', message: safeDir, hint: null };
+}
+
+module.exports = { assessProjectRoot, looksLikeInstallDir, INSTALL_PATTERNS };

package/src/utils/remediation-hints.js

@@ -0,0 +1,51 @@
+// src/utils/remediation-hints.js
+'use strict';
+
+/**
+ * Shared, copy-paste remediation hint strings.
+ *
+ * One source of truth for the fix commands surfaced by `amicus doctor` and by
+ * failure messages across the CLI, so the guidance never drifts. Consumed by
+ * src/cli-handlers-doctor.js (per-check hints) and reused by sweep'd failure
+ * sites (#32) and the MCP recovery surface (#43).
+ *
+ * The object is frozen — these are a stable copy-paste contract; callers read
+ * fields, they do not mutate them.
+ */
+const REMEDIATION_HINTS = Object.freeze({
+  /** Canonical global (re)install. */
+  reinstall: 'npm install -g amicus',
+
+  /** `npm cache clean --force` — clears a corrupt npm cache before reinstalling. */
+  cacheClean: 'npm cache clean --force',
+
+  /**
+   * Engine binaries missing/rolled back. A transient install error can roll
+   * back the platform engine packages; re-run, or clean the cache and reinstall.
+   */
+  reinstallEngine:
+    'npm install -g amicus  (a transient install error can roll back the engine binaries — re-run, or: npm cache clean --force && npm install -g amicus)',
+
+  /** Electron absent — reinstall to add the interactive GUI (headless still works). */
+  reinstallElectron: 'npm install -g amicus  (reinstall to add Electron)',
+
+  /**
+   * Electron present but broken (ABI mismatch / partial unpack). Delete the
+   * vendored copy and reinstall to force a clean rebuild.
+   */
+  rebuildElectron:
+    'rm -rf node_modules/electron && npm install -g amicus  (rebuild Electron after an ABI mismatch or partial unpack)',
+
+  /** Point the user at the single recovery hub. */
+  runDoctor: 'run: amicus doctor  (diagnoses config, keys, engine & MCP, with copy-paste fixes)',
+
+  /**
+   * Self-heal the optional Electron GUI in place (#56). This is the convergence
+   * target for the three "reinstall to fix Electron" hints — it provisions the
+   * binary from cache (or downloads on demand) WITHOUT a global reinstall, so it
+   * can't loop the way `npm install -g amicus` could when the rollback recurs.
+   */
+  doctorFix: 'amicus doctor --fix  (self-heal the Electron GUI in place — provisions the binary; no reinstall, so it can\'t loop)',
+});
+
+module.exports = REMEDIATION_HINTS;

package/src/utils/result-schema.js

@@ -106,9 +106,19 @@ function waveExitCode(waveStatus) {
  * @param {object} opts
  * @param {string} opts.waveId
  * @param {Array<object>} opts.legs - run documents (in --models order)
- * Counts track the four primary terminal statuses (complete/error/timeout/aborted);
- * legs with other statuses (e.g. 'crashed', 'running' in a rebuilt wave) count toward
- * `total` only, so total may exceed the sum of the named buckets.
+ *
+ * COUNTS REMAINDER RULE (stable, no schemaVersion bump): `counts` exposes four
+ * NAMED terminal buckets — complete, error, timeout, aborted — plus `total`
+ * (= legs.length). The remaining TERMINAL_STATUSES ('crashed', 'idle-timeout')
+ * and any non-terminal status (e.g. 'running' in a live-rebuilt wave) are
+ * deliberately NOT given their own bucket; they are reflected ONLY in `total`.
+ * Therefore a consumer must treat the unnamed remainder as
+ *   total − (complete + error + timeout + aborted)
+ * and must NOT assume the named buckets sum to `total`. Adding new buckets
+ * would change the document shape and REQUIRES bumping SCHEMA_VERSION.
+ * This agrees with the MCP wave path (mcp-server.js), which counts a leg as
+ * "done" iff its status is in TERMINAL_STATUSES — including 'crashed' — so a
+ * crashed leg is done/total there exactly as it is total-only here.
  * @param {{source: string, file: string|null, chars: number}|null} [opts.promptMeta]
  * @param {string|null} [opts.createdAt]
  * @param {string|null} [opts.completedAt]
@@ -117,6 +127,9 @@ function waveExitCode(waveStatus) {
  */
 function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = null, completedAt = null, status = null }) {
   const { sumWaveUsage } = require('./pricing');
+  // Named buckets only (see "COUNTS REMAINDER RULE" above). 'crashed' and
+  // 'idle-timeout' legs are intentionally NOT bucketed — they land in `total`
+  // only, so total may exceed complete+error+timeout+aborted.
   const counts = {
     total: legs.length,
     complete: legs.filter(l => l.status === 'complete').length,

package/src/utils/version-info.js

@@ -0,0 +1,49 @@
+/**
+ * @module utils/version-info — running vs. on-disk amicus version (#33)
+ *
+ * After an `npm i -g amicus` upgrade, a long-lived MCP server process keeps
+ * running the OLD code until the client restarts it. That staleness is
+ * invisible from inside an agent session. These helpers surface the running
+ * version in MCP responses and, via a CALL-TIME re-read of the on-disk
+ * package.json, flag when the two have diverged.
+ */
+const fs = require('fs');
+const path = require('path');
+
+/** Absolute path to this install's package.json (repo root). */
+const PKG_PATH = path.join(__dirname, '..', '..', 'package.json');
+
+/**
+ * The version baked into the running process at load time. Free: package.json
+ * is already require()'d elsewhere, so this hits the module cache.
+ */
+const RUNNING_VERSION = require('../../package.json').version;
+
+/**
+ * Re-read the on-disk package.json version at call time. Wrapped in try/catch
+ * — the file may be mid-rewrite, missing, or unreadable during/after an
+ * upgrade — and returns null on any failure rather than throwing.
+ * @returns {string|null}
+ */
+function readOnDiskVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(PKG_PATH, 'utf-8'));
+    return (pkg && typeof pkg.version === 'string') ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One-line staleness warning, or null when there's nothing to warn about
+ * (on-disk version unreadable or identical to the running version).
+ * @returns {string|null}
+ */
+function versionWarning() {
+  const onDisk = readOnDiskVersion();
+  if (!onDisk || onDisk === RUNNING_VERSION) { return null; }
+  return `Amicus was upgraded on disk (running v${RUNNING_VERSION}, on-disk v${onDisk}). `
+    + `Restart your MCP client to load v${onDisk}.`;
+}
+
+module.exports = { RUNNING_VERSION, readOnDiskVersion, versionWarning, PKG_PATH };