@codedology/code-forge 0.1.0

package/src/install/detect.mjs

@@ -0,0 +1,121 @@
+/**
+ * Harness detection (plan §2.1 "Detect" column): `<command>` on PATH OR `~/<homeMarker>/`
+ * exists. Deliberately never shells out (`which`/`where`) — this module scans `PATH` directory
+ * entries itself, which is both faster and, critically, testable under a FAKE `PATH`/`home`
+ * without ever touching the real `$PATH` or the real `~/.claude`, `~/.codex`, `~/.grok`,
+ * `~/.gemini`, `~/.agents` (coder-rules.md rule 10 — never inspect the real harness dirs in tests
+ * or manual runs).
+ */
+
+import { access, constants, stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { HARNESSES } from './harnesses.mjs';
+
+/** Windows executable suffixes probed when no extension is already present (PATHEXT convention). */
+const DEFAULT_WIN32_EXTS = ['.EXE', '.CMD', '.BAT', '.COM'];
+
+/**
+ * @param {string} pathEnv - a `PATH`-shaped string (colon- or semicolon-separated).
+ * @param {NodeJS.Platform} platform
+ * @returns {string[]} non-empty directory entries, in order, duplicates kept (matches shell PATH
+ *   resolution: the first match wins, so order must survive).
+ */
+function splitPathEnv(pathEnv, platform) {
+  const sep = platform === 'win32' ? ';' : ':';
+  return pathEnv.split(sep).filter((entry) => entry.length > 0);
+}
+
+/**
+ * Whether `command` resolves to an executable file in `opts.pathEnv`. Never spawns a process.
+ * @param {string} command
+ * @param {object} [opts]
+ * @param {string} [opts.pathEnv] - defaults to `process.env.PATH`; tests pass a fake one.
+ * @param {NodeJS.Platform} [opts.platform] - defaults to `process.platform`.
+ * @param {string} [opts.pathExt] - Windows only; defaults to `process.env.PATHEXT`.
+ * @returns {Promise<boolean>}
+ */
+export async function commandOnPath(command, opts = {}) {
+  if (typeof command !== 'string' || command.length === 0) {
+    return false;
+  }
+  const platform = opts.platform ?? process.platform;
+  const pathEnv = opts.pathEnv ?? process.env.PATH ?? '';
+  const dirs = splitPathEnv(pathEnv, platform);
+  const exts =
+    platform === 'win32'
+      ? (opts.pathExt ?? process.env.PATHEXT ?? DEFAULT_WIN32_EXTS.join(';')).split(';').filter((e) => e.length > 0)
+      : [''];
+
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, `${command}${ext}`);
+      try {
+        // Sequential, not Promise.all: PATH entries are searched in order and the first match
+        // must win, matching real shell PATH resolution.
+        await access(candidate, constants.X_OK);
+        return true;
+      } catch {
+        // not this directory — keep looking.
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether `<home>/<harness.homeMarker>` exists and is a directory.
+ * @param {import('./harnesses.mjs').HarnessRow} harness
+ * @param {object} [opts]
+ * @param {string} [opts.home] - defaults to `os.homedir()`.
+ * @returns {Promise<boolean>}
+ */
+export async function homeMarkerPresent(harness, opts = {}) {
+  const home = opts.home ?? os.homedir();
+  try {
+    const info = await stat(path.join(home, harness.homeMarker));
+    return info.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @typedef {object} DetectionResult
+ * @property {string} id
+ * @property {boolean} detected - `onPath || homeDirPresent`.
+ * @property {boolean} onPath
+ * @property {boolean} homeDirPresent
+ */
+
+/**
+ * @param {import('./harnesses.mjs').HarnessRow} harness
+ * @param {object} [opts]
+ * @param {string} [opts.home]
+ * @param {string} [opts.pathEnv]
+ * @param {NodeJS.Platform} [opts.platform]
+ * @returns {Promise<DetectionResult>}
+ */
+export async function detectHarness(harness, opts = {}) {
+  const [onPath, homeDirPresent] = await Promise.all([
+    harness.command ? commandOnPath(harness.command, opts) : Promise.resolve(false),
+    homeMarkerPresent(harness, opts),
+  ]);
+  return { id: harness.id, detected: onPath || homeDirPresent, onPath, homeDirPresent };
+}
+
+/**
+ * Detects every row of {@link HARNESSES}, in table order.
+ * @param {object} [opts]
+ * @param {string} [opts.home]
+ * @param {string} [opts.pathEnv]
+ * @param {NodeJS.Platform} [opts.platform]
+ * @returns {Promise<DetectionResult[]>}
+ */
+export async function detectAll(opts = {}) {
+  const results = [];
+  for (const harness of HARNESSES) {
+    results.push(await detectHarness(harness, opts));
+  }
+  return results;
+}

package/src/install/harnesses.mjs

@@ -0,0 +1,131 @@
+/**
+ * The per-harness install path table (plan §2.1, unchanged from v1; research/installer-patterns.md
+ * §"Agent Skills standard + `npx skills`"). Pure data — no filesystem access here (that is
+ * `./detect.mjs`) and no writes (that is `./link.mjs`).
+ *
+ * Claude Code and Codex CLI's paths are backed by assumption `[A7]` (both skill directories were
+ * observed on this machine, 2026-09-24: `~/.claude/skills` and `~/.codex/skills`, the latter
+ * empty). Grok's GLOBAL path is also backed by `[A7]` (`~/.grok/skills` observed with 5 entries,
+ * so Grok reads that directory) but its PROJECT path is not — a harness CLI exists to probe it
+ * (`doctor`, a later block, asks Grok to list its skills). Gemini is not installed on this machine
+ * at all: `[A6]`, its whole row is `verified: false`, matching the plan's "Gemini row UNVERIFIED"
+ * (§10.3 acceptance) — the only row that flag applies to. Cursor and Copilot have no CLI and no
+ * adapter; detection is directory-presence only, and their paths (shared with Codex/Gemini under
+ * `.agents/skills/`) come from research/installer-patterns.md, not from an observation on this
+ * machine, but the plan does not ask `doctor` to mark them unverified (there is no CLI to probe).
+ */
+
+import path from 'node:path';
+
+/**
+ * @typedef {object} HarnessRow
+ * @property {string} id - stable identifier, also the config `harnesses[]` entry value.
+ * @property {string} label - human-readable name.
+ * @property {string|null} command - executable name to look for on PATH, or `null` when the
+ *   harness has no CLI (Cursor, Copilot) — detection then relies on `homeMarker` alone.
+ * @property {string} homeMarker - directory name directly under `$HOME` (e.g. `.claude`) used
+ *   both as a detection fallback and as the base of the global install path.
+ * @property {string} projectSkillsDir - project-relative directory that holds installed skills.
+ * @property {boolean} verified - whether this row's paths are confirmed on a real machine (§10.3:
+ *   exactly the Gemini row is `false`).
+ * @property {string} notes - the plan's free-text note for this row, unchanged wording.
+ */
+
+/**
+ * Six rows, Claude Code first (plan §2.1 table order). Frozen so a caller cannot mutate the
+ * shared table in place.
+ * @type {ReadonlyArray<HarnessRow>}
+ */
+export const HARNESSES = Object.freeze(
+  [
+    {
+      id: 'claude',
+      label: 'Claude Code',
+      command: 'claude',
+      homeMarker: '.claude',
+      projectSkillsDir: '.claude/skills',
+      verified: true,
+      notes: '[A7] global skills dir exists here.',
+    },
+    {
+      id: 'codex',
+      label: 'Codex CLI',
+      command: 'codex',
+      homeMarker: '.codex',
+      projectSkillsDir: '.agents/skills',
+      verified: true,
+      notes: '[A7] ~/.codex/skills exists (empty). Paths from research/installer-patterns.md.',
+    },
+    {
+      id: 'grok',
+      label: 'Grok CLI',
+      command: 'grok',
+      homeMarker: '.grok',
+      projectSkillsDir: '.agents/skills',
+      verified: true,
+      notes:
+        '[A7] ~/.grok/skills exists with 5 entries, so Grok reads it; the PROJECT path is unverified — doctor asks Grok to list its skills.',
+    },
+    {
+      id: 'gemini',
+      label: 'Gemini CLI',
+      command: 'gemini',
+      homeMarker: '.gemini',
+      projectSkillsDir: '.agents/skills',
+      verified: false,
+      notes: '[A6] not installed on this machine; path from research, UNVERIFIED.',
+    },
+    {
+      id: 'cursor',
+      label: 'Cursor',
+      command: null,
+      homeMarker: '.cursor',
+      projectSkillsDir: '.agents/skills',
+      verified: true,
+      notes: 'detection only; no adapter (no CLI).',
+    },
+    {
+      id: 'copilot',
+      label: 'Copilot',
+      command: null,
+      homeMarker: '.copilot',
+      projectSkillsDir: '.agents/skills',
+      verified: true,
+      notes: 'detection only; no adapter (no CLI).',
+    },
+  ].map((row) => Object.freeze(row)),
+);
+
+/**
+ * @param {string} id
+ * @returns {HarnessRow}
+ * @throws {RangeError} when `id` names no row in {@link HARNESSES}.
+ */
+export function getHarness(id) {
+  const row = HARNESSES.find((h) => h.id === id);
+  if (!row) {
+    throw new RangeError(`install: unknown harness "${id}"`);
+  }
+  return row;
+}
+
+/**
+ * @param {HarnessRow} harness
+ * @param {string} projectRoot - absolute path to the project.
+ * @param {string} [skillName]
+ * @returns {string} absolute path where the skill would be installed inside the project.
+ */
+export function projectSkillPath(harness, projectRoot, skillName = 'code-forge') {
+  return path.join(projectRoot, harness.projectSkillsDir, skillName);
+}
+
+/**
+ * @param {HarnessRow} harness
+ * @param {string} home - absolute path to `$HOME`.
+ * @param {string} [skillName]
+ * @returns {string} absolute path where the skill would be installed globally, under
+ *   `<home>/<homeMarker>/skills/<skillName>`.
+ */
+export function globalSkillPath(harness, home, skillName = 'code-forge') {
+  return path.join(home, harness.homeMarker, 'skills', skillName);
+}