@geonosis/doctor 2.0.0 → 2.2.0

package/dist/doctor-cli.js

@@ -1,12 +1,108 @@
 import {
   CHECKS,
+  ENVELOPES_DIR,
   formatDoctor,
   formatJson,
   runDoctor
-} from "./chunk-SMCRXSH5.js";
+} from "./chunk-DR5P4QYC.js";
+
+// src/doctor-cli.ts
+import { fstatSync, statSync } from "fs";
+import { resolve as resolve2 } from "path";
+
+// src/envelope-write.ts
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+var envelopePath = (root, tool) => join(root, ENVELOPES_DIR, `${tool}.json`);
+var UnbalancedEnvelope = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnbalancedEnvelope";
+  }
+};
+var isCount = (value) => Number.isSafeInteger(value) && value >= 0;
+var unbalancedMessage = (envelope, next) => `${envelope.tool}: considered ${envelope.considered} but accounts for ${envelope.read + envelope.refused.length + envelope.excused.length} \u2014 ${envelope.read} read + ${envelope.refused.length} refused + ${envelope.excused.length} excused. A run that has lost count of its own inputs cannot say what it measured, so no verdict was rendered and no envelope was written. Next: ${next}`;
+var FORBIDDEN_ROOT = "GEONOSIS_ENVELOPES_FORBIDDEN_ROOT";
+var refuseForbiddenRoot = (root) => {
+  const forbidden = process.env[FORBIDDEN_ROOT];
+  if (forbidden === void 0 || resolve(forbidden) !== resolve(root)) return;
+  throw new UnbalancedEnvelope(
+    `${root} is off limits to envelope writers in this process (${FORBIDDEN_ROOT}) \u2014 a run that writes one into a shared root races every other run reading it, and leaves a file the next one takes for real. Point this at a scratch root of its own: tooling/scratch-dir.ts.`
+  );
+};
+var writeEnvelope = ({
+  envelope,
+  next,
+  root
+}) => {
+  if (envelope.tool.trim() === "") {
+    throw new UnbalancedEnvelope(
+      `an envelope with no tool name cannot be filed or reported against. Next: ${next}`
+    );
+  }
+  if (envelope.version.trim() === "") {
+    throw new UnbalancedEnvelope(
+      `${envelope.tool}: an envelope that cannot name the build that wrote it dates nothing, and a stale one reads exactly like a fresh one. Next: ${next}`
+    );
+  }
+  if (!isCount(envelope.considered) || !isCount(envelope.read)) {
+    throw new UnbalancedEnvelope(
+      `${envelope.tool}: considered ${envelope.considered} and read ${envelope.read} \u2014 a census is a whole number of things, and arithmetic over anything else balances by accident. Next: ${next}`
+    );
+  }
+  if (envelope.considered !== envelope.read + envelope.refused.length + envelope.excused.length) {
+    throw new UnbalancedEnvelope(unbalancedMessage(envelope, next));
+  }
+  refuseForbiddenRoot(root);
+  const at = envelopePath(root, envelope.tool);
+  mkdirSync(dirname(at), { recursive: true });
+  writeFileSync(at, `${JSON.stringify(envelope, void 0, 2)}
+`);
+  return at;
+};
+var UNKNOWN = "unknown";
+var versionIn = (dir) => {
+  try {
+    const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    return typeof manifest.version === "string" ? manifest.version : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var versionOf = (moduleUrl) => {
+  let dir = dirname(fileURLToPath(moduleUrl));
+  for (; ; ) {
+    const found = versionIn(dir);
+    if (found !== void 0) return found;
+    const up = dirname(dir);
+    if (up === dir) return UNKNOWN;
+    dir = up;
+  }
+};
+var DOCTOR_TOOL = "doctor";
+var DOCTOR_NEXT = "geonosis-doctor --json and count the checks it printed \u2014 this run considered every question the tool has, and a check nobody asked for is excused by name rather than left out of the denominator";
+var doctorEnvelope = ({
+  durationMs,
+  report
+}) => {
+  const ran = new Set(report.ran);
+  return {
+    considered: CHECKS.length,
+    durationMs,
+    excused: CHECKS.filter((check) => !ran.has(check)).map((check) => ({
+      path: check,
+      reason: "not asked for by --only, so this run says nothing about it"
+    })),
+    findings: report.findings,
+    read: report.ran.length,
+    refused: [],
+    tool: DOCTOR_TOOL,
+    version: versionOf(import.meta.url)
+  };
+};
 
 // src/doctor-cli.ts
-import { resolve } from "path";
 var ABOUT = {
   baseline: `The ratchet's numbers at HEAD against another ref. A ratchet lowers its own baseline
               when a number shrinks, so nothing inside one checkout can see a branch raise one back
@@ -94,6 +190,10 @@ plugin-route-namespaced on its package root, while the shipped corpus says acme
 
   --print-config-shape   every file this reads, and the keys it reads out of each
 
+Every run writes .geonosis/envelopes/doctor.json: the ten checks CONSIDERED against the ones this
+run read, with the rest excused by name, so a --only run can never read as a verdict about the whole
+tree. The envelope check SKIPs that one file \u2014 this run is the one writing it.
+
 Exits 1 when any line is a FAIL or an UNJUDGED \u2014 a question this could not ask is not a pass \u2014 and
 2 when the run could not be made at all. --strict promotes every WARN to a FAIL. --json prints the
 whole report for a CI step to read.`;
@@ -134,8 +234,8 @@ var parseDoctorArgs = (argv, cwd) => {
     ...baseline === void 0 ? {} : { baseline },
     json,
     ...only === void 0 || only.length === 0 ? {} : { only },
-    ...read["--oxlint"] === void 0 ? {} : { oxlint: resolve(cwd, read["--oxlint"]) },
-    root: resolve(cwd, read["--root"] ?? cwd),
+    ...read["--oxlint"] === void 0 ? {} : { oxlint: resolve2(cwd, read["--oxlint"]) },
+    root: resolve2(cwd, read["--root"] ?? cwd),
     strict
   };
 };
@@ -186,6 +286,15 @@ geonosis.json \u2192 "rails.egress"
 .geonosis/rails-run.json
   deniedEgress    object[]   what a run reached for and was refused. A GATE AT ZERO (D-025): one
                              entry fails, and it is never a counter to hold flat`;
+var sameFile = (fd, path) => {
+  try {
+    const open = fstatSync(fd);
+    const there = statSync(path);
+    return open.dev === there.dev && open.ino === there.ino;
+  } catch {
+    return false;
+  }
+};
 var main = async () => {
   const argv = process.argv.slice(2);
   if (argv.includes("--help") || argv.includes("-h")) {
@@ -199,7 +308,21 @@ var main = async () => {
     return 0;
   }
   const { json, ...options } = parseDoctorArgs(argv, process.cwd());
+  const started = Date.now();
   const report = await runDoctor(options);
+  const at = envelopePath(options.root, "doctor");
+  if (sameFile(process.stdout.fd, at)) {
+    process.stderr.write(
+      `geonosis-doctor: stdout is ${ENVELOPES_DIR}/doctor.json, so no envelope was written \u2014 it would have overwritten the report redirected there. Send --json somewhere else and the envelope is written after every run.
+`
+    );
+  } else {
+    writeEnvelope({
+      envelope: doctorEnvelope({ durationMs: Date.now() - started, report }),
+      next: DOCTOR_NEXT,
+      root: options.root
+    });
+  }
   process.stdout.write(json ? formatJson(report) : formatDoctor(report));
   return report.ok ? 0 : 1;
 };

package/dist/index.d.ts

@@ -66,6 +66,8 @@ type RatchetConfig = {
     counters: Record<string, unknown>[];
 };
 type DoctorOptions = {
+    /** Where `~/.claude` lives — the plugin registry and the user settings the doctor reads; the home directory unless a caller says otherwise. */
+    home?: string;
     /**
      * Present only when a baseline comparison was asked for, because making one is the one part of
      * this tool that runs git — and the release check runs the doctor inside repos other sessions
@@ -83,6 +85,8 @@ type DoctorOptions = {
 type DoctorReport = {
     counts: Record<Verdict, number>;
     findings: Finding[];
+    /** The checks this run asked. `--only` makes it a subset, and the envelope's denominator needs it. */
+    ran: CheckName[];
     /**
      * False as soon as one line is a FAIL or an UNJUDGED — after `--strict` has promoted the
      * warnings. "We could not tell" is not a pass; it is the quietest way there is of reading green.
@@ -136,7 +140,7 @@ declare const discoverConfigs: (root: string) => DiscoveredConfig[];
 declare const discoverWorkspaces: (root: string) => Workspace[];
 declare const readRatchet: (root: string) => RatchetConfig | undefined;
 
-declare const runDoctor: ({ baseline, only, oxlint, root, strict, }: DoctorOptions) => Promise<DoctorReport>;
+declare const runDoctor: ({ baseline, home, only, oxlint, root, strict, }: DoctorOptions) => Promise<DoctorReport>;
 
 /** The file `create-geonosis --domains` writes, held against the scaffold's own name by a test. */
 declare const COMPOSITION_ROOT = "src/platform.ts";
@@ -189,7 +193,7 @@ declare const checkDrift: ({ readers, root, userSettings, workspaces, }: {
  * duplicated here on purpose: it is one comparison over three numbers, and it is the check.
  */
 declare const ENVELOPES_DIR = ".geonosis/envelopes";
-declare const NO_ENVELOPES = "no .geonosis/envelopes/*.json \u2014 the tools write one per run, so an absent envelope is a run nobody has made here yet, and it is not a balanced one";
+declare const NO_ENVELOPES = "no .geonosis/envelopes/*.json \u2014 the tools write one per run, so an absent envelope is a run nobody has made here yet, and it is not a balanced one (this run\u2019s own doctor.json is not one of them: it is written after these checks, and balanced at write time)";
 declare const checkEnvelopes: ({ root }: {
     root: string;
 }) => Finding[];
@@ -263,6 +267,39 @@ declare const checkGroup: ({ groups, root, workspaces, }: {
     workspaces: Workspace[];
 }) => Finding[];
 
+/**
+ * Where Claude Code records what it has installed.
+ *
+ * MEASURED 2026-09-02 (`~/.claude/plugins/installed_plugins.json`, `version: 2`): a map keyed
+ * `<plugin>@<marketplace>`, each value a list of installations carrying `version`, `installPath`
+ * and the commit it came from. This is the file `claude plugin list` answers from.
+ */
+declare const INSTALLED_PLUGINS = ".claude/plugins/installed_plugins.json";
+/** The plugin this kit publishes. Its own name, the way `FIXED_GROUP` is its own group. */
+declare const PLUGIN_NAME = "geonosis";
+/**
+ * Every version of one plugin this machine has installed, in the order the record lists them.
+ *
+ * A name can be installed from more than one marketplace and at more than one scope, so this
+ * answers with a list rather than picking one: a session loads what it loads, and a doctor that
+ * chose for the reader would be reporting about an installation nobody has.
+ */
+declare const installedPluginVersions: (home: string, name: string) => string[];
+/**
+ * #133: a consumer's npm bump does not move the CLAUDE PLUGIN.
+ *
+ * The hooks, the agents and the skills live in the plugin, and it updates on `claude plugin update`
+ * and never on an install — so a repo can be on this release's packages while every session in it
+ * runs the hooks of the one before, and a refusal added this release cannot fire. That is the
+ * declared-versus-loaded question one surface out, and it is this check's to ask.
+ */
+declare const checkClaudePlugin: ({ home, name, train, }: {
+    home?: string;
+    name?: string;
+    /** The version the package train is on here, or nothing when this tree declares none. */
+    train: string | undefined;
+}) => Finding[];
+
 /** The scope this tool asks about. A config's other plugins are somebody else's release to check. */
 declare const SCOPE = "@geonosis/";
 /**
@@ -284,8 +321,9 @@ declare const declaredFor: ({ dir, specifier, workspaces, }: {
     at: string;
     spec: string;
 } | undefined;
-declare const checkLoaded: ({ configs, root, workspaces, }: {
+declare const checkLoaded: ({ configs, home, root, workspaces, }: {
     configs: DiscoveredConfig[];
+    home?: string;
     root: string;
     workspaces: Workspace[];
 }) => Promise<Finding[]>;
@@ -368,4 +406,4 @@ declare const checkRunner: ({ ratchet, root, workspaces, }: {
     workspaces: Workspace[];
 }) => Finding[];
 
-export { CHECKS, COMPOSITION_ROOT, CONFIG_FILE, type CheckName, DEPLOYED_FILE, type DiscoveredConfig, DoctorError, type DoctorOptions, type DoctorReport, ENVELOPES_DIR, FIXED_GROUP, FLOOR_PACKAGES, type Finding, GEONOSIS_FILE, type HeldTogether, KIT_GROUP, type LastEventRecord, MANIFEST_FILE, type Manifest, NOT_WRITTEN, NO_ENVELOPES, type ObservabilityConfig, RATCHET_FILE, READERS, type RatchetConfig, SCOPE, type Verdict, type Workspace, checkBaseline, checkDeployed, checkDrift, checkEnvelopes, checkExercised, checkGroup, checkLoaded, checkObservability, checkRunner, corpusOfPlugin, declaredFor, declaredGroupsOf, defaultRef, discoverConfigs, discoverWorkspaces, enabledRulesOf, formatDoctor, formatJson, packageDirOf, pluginVersionOf, readConfig, readRatchet, relativePath, relativeToRoot, repoCorpusOf, resolveFrom, runDoctor, satisfies };
+export { CHECKS, COMPOSITION_ROOT, CONFIG_FILE, type CheckName, DEPLOYED_FILE, type DiscoveredConfig, DoctorError, type DoctorOptions, type DoctorReport, ENVELOPES_DIR, FIXED_GROUP, FLOOR_PACKAGES, type Finding, GEONOSIS_FILE, type HeldTogether, INSTALLED_PLUGINS, KIT_GROUP, type LastEventRecord, MANIFEST_FILE, type Manifest, NOT_WRITTEN, NO_ENVELOPES, type ObservabilityConfig, PLUGIN_NAME, RATCHET_FILE, READERS, type RatchetConfig, SCOPE, type Verdict, type Workspace, checkBaseline, checkClaudePlugin, checkDeployed, checkDrift, checkEnvelopes, checkExercised, checkGroup, checkLoaded, checkObservability, checkRunner, corpusOfPlugin, declaredFor, declaredGroupsOf, defaultRef, discoverConfigs, discoverWorkspaces, enabledRulesOf, formatDoctor, formatJson, installedPluginVersions, packageDirOf, pluginVersionOf, readConfig, readRatchet, relativePath, relativeToRoot, repoCorpusOf, resolveFrom, runDoctor, satisfies };

package/dist/index.js

@@ -8,14 +8,17 @@ import {
   FIXED_GROUP,
   FLOOR_PACKAGES,
   GEONOSIS_FILE,
+  INSTALLED_PLUGINS,
   KIT_GROUP,
   MANIFEST_FILE,
   NOT_WRITTEN,
   NO_ENVELOPES,
+  PLUGIN_NAME,
   RATCHET_FILE,
   READERS,
   SCOPE,
   checkBaseline,
+  checkClaudePlugin,
   checkDeployed,
   checkDrift,
   checkEnvelopes,
@@ -33,6 +36,7 @@ import {
   enabledRulesOf,
   formatDoctor,
   formatJson,
+  installedPluginVersions,
   packageDirOf,
   pluginVersionOf,
   readConfig,
@@ -43,7 +47,7 @@ import {
   resolveFrom,
   runDoctor,
   satisfies
-} from "./chunk-SMCRXSH5.js";
+} from "./chunk-DR5P4QYC.js";
 export {
   CHECKS,
   COMPOSITION_ROOT,
@@ -54,14 +58,17 @@ export {
   FIXED_GROUP,
   FLOOR_PACKAGES,
   GEONOSIS_FILE,
+  INSTALLED_PLUGINS,
   KIT_GROUP,
   MANIFEST_FILE,
   NOT_WRITTEN,
   NO_ENVELOPES,
+  PLUGIN_NAME,
   RATCHET_FILE,
   READERS,
   SCOPE,
   checkBaseline,
+  checkClaudePlugin,
   checkDeployed,
   checkDrift,
   checkEnvelopes,
@@ -79,6 +86,7 @@ export {
   enabledRulesOf,
   formatDoctor,
   formatJson,
+  installedPluginVersions,
   packageDirOf,
   pluginVersionOf,
   readConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geonosis/doctor",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "types": "./dist/index.d.ts",
   "description": "The adoption doctor — declared ≠ loaded, enabled ≠ exercised, a baseline that grew, a runner whose exit code is the only verdict.",
   "keywords": [
@@ -35,7 +35,10 @@
     "dist"
   ],
   "dependencies": {
-    "@geonosis/lint-parity": "2.0.0"
+    "@geonosis/lint-parity": "2.2.0"
+  },
+  "devDependencies": {
+    "@geonosis/ratchet": "2.2.0"
   },
   "peerDependencies": {
     "oxlint": ">=1.77"