@tech-leads-club/harness-toolkit 0.2.1 → 0.3.0

package/src/core/release/release.version.ts

@@ -0,0 +1,147 @@
+/**
+ * How a release tag is spelled.
+ *
+ * hazard: the changelog generator listed tags with the glob `v*` while every tag this repository has ever created
+ * is `harness-toolkit-v…`. It matched none, put all 88 decision records under `## Unreleased`, and passed its own
+ * `--check` because the generated document and the committed one were wrong in the same way. Three releases shipped
+ * with a changelog attributing nothing to any of them ([/decisions/ad-087.md](/decisions/ad-087.md)).
+ *
+ * invariant: derived from the package name, which is the same source `release-please-config.json` writes the tag
+ * from. A prefix written down twice is a prefix that drifts once.
+ */
+export function tagPrefixFor(packageName: string): string {
+  const unscoped = packageName.includes("/") ? (packageName.split("/").pop() ?? packageName) : packageName;
+  return `${unscoped}-v`;
+}
+
+export type SemVer = { major: number; minor: number; patch: number };
+
+export function parseVersion(text: string): SemVer | null {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(text.trim());
+  if (match === null) {
+    return null;
+  }
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+
+/** The version inside a tag, or null when the tag belongs to another package or another scheme. */
+export function versionInTag(packageName: string, tag: string): string | null {
+  const prefix = tagPrefixFor(packageName);
+  if (!tag.startsWith(prefix)) {
+    return null;
+  }
+  const rest = tag.slice(prefix.length);
+  return parseVersion(rest) === null ? null : rest;
+}
+
+/**
+ * The version a set of commits earns, from Conventional Commit subjects.
+ *
+ * why: the release writes to `main` directly and publishes before it tags, so nothing assembles the bump in a pull
+ * request for a human to look at. The arithmetic therefore has to be a pure function with tests rather than a step
+ * inside somebody else's action ([/decisions/ad-087.md](/decisions/ad-087.md)).
+ */
+export type Bump = "major" | "minor" | "patch" | "none";
+
+export type Commit = {
+  /** The subject line, e.g. `fix(gate): …`. */
+  subject: string;
+  /** The body, where a `BREAKING CHANGE:` footer lives. */
+  body?: string;
+};
+
+const SUBJECT = /^(?<type>[a-z]+)(?:\((?<scope>[^)]*)\))?(?<breaking>!)?:\s*(?<rest>.+)$/;
+const BREAKING_FOOTER = /^BREAKING[ -]CHANGE:/m;
+
+/**
+ * invariant: `feat` and `fix` are the only types that release. Everything else — `docs`, `chore`, `refactor`,
+ * `test`, `ci`, `build`, `perf`, `style` — lands without moving the version. That is what stops the release's own
+ * commit from earning the next version and looping, which this pipeline did six times in nine minutes.
+ */
+export const MINOR_TYPES: ReadonlySet<string> = new Set(["feat"]);
+export const PATCH_TYPES: ReadonlySet<string> = new Set(["fix"]);
+
+/**
+ * invariant: a scope on this list never releases, whatever the type. `fix(ci)` and `fix(gate)` are repository
+ * plumbing that cannot reach anyone who installed the package — three versions were published for exactly that
+ * kind of work before this existed.
+ */
+export const INERT_SCOPES: ReadonlySet<string> = new Set(["ci", "gate", "release", "docs", "deps-dev"]);
+
+export function bumpFor(commit: Commit): Bump {
+  const match = SUBJECT.exec(commit.subject.trim());
+  if (match?.groups === undefined) {
+    return "none";
+  }
+  const { type, scope, breaking } = match.groups as { type: string; scope?: string; breaking?: string };
+  if (scope !== undefined && INERT_SCOPES.has(scope)) {
+    return "none";
+  }
+  if (breaking === "!" || BREAKING_FOOTER.test(commit.body ?? "")) {
+    return "major";
+  }
+  if (MINOR_TYPES.has(type)) {
+    return "minor";
+  }
+  return PATCH_TYPES.has(type) ? "patch" : "none";
+}
+
+const RANK: Record<Bump, number> = { none: 0, patch: 1, minor: 2, major: 3 };
+
+export function highestBump(commits: readonly Commit[]): Bump {
+  return commits.reduce<Bump>((best, commit) => {
+    const bump = bumpFor(commit);
+    return RANK[bump] > RANK[best] ? bump : best;
+  }, "none");
+}
+
+/**
+ * why: below 1.0.0 a breaking change takes the minor, not the major. Reaching 1.0.0 is a claim about stability that
+ * a commit message must not be able to make on its own.
+ *
+ * hazard: a feature still takes the minor below 1.0.0. Rebasing `feat` down to a patch is a *different* convention
+ * and this repository does not use it — the history says so: 0.1.0 went to 0.2.0 on a `feat:`. Implementing both at
+ * once would silently renumber every future feature.
+ */
+export function applyBump(current: SemVer, bump: Bump): SemVer {
+  if (bump === "none") {
+    return current;
+  }
+  const effective: Exclude<Bump, "none"> = current.major === 0 && bump === "major" ? "minor" : bump;
+  switch (effective) {
+    case "major":
+      return { major: current.major + 1, minor: 0, patch: 0 };
+    case "minor":
+      return { major: current.major, minor: current.minor + 1, patch: 0 };
+    default:
+      return { major: current.major, minor: current.minor, patch: current.patch + 1 };
+  }
+}
+
+export type VersionPlan = {
+  current: string;
+  next: string;
+  bump: Bump;
+  released: boolean;
+  /** The subjects that earned the bump, for the run's log. */
+  reasons: string[];
+};
+
+export function planVersion(currentVersion: string, commits: readonly Commit[]): VersionPlan {
+  const current = parseVersion(currentVersion);
+  if (current === null) {
+    throw new Error(`release: \`${currentVersion}\` is not a version this can bump`);
+  }
+  const bump = highestBump(commits);
+  return {
+    current: formatVersion(current),
+    next: formatVersion(applyBump(current, bump)),
+    bump,
+    released: bump !== "none",
+    reasons: commits.filter((commit) => bumpFor(commit) !== "none").map((commit) => commit.subject),
+  };
+}
+
+export function formatVersion(version: SemVer): string {
+  return `${version.major}.${version.minor}.${version.patch}`;
+}

package/src/core/shim/shim.precedence.ts

@@ -0,0 +1,72 @@
+/**
+ * Whether the project-level shim should stand down because a user-level hook already covers this event.
+ *
+ * hazard: this was `if (process.env.TLC_ACTIVE === "1")`, and nothing in the repository ever set `TLC_ACTIVE`.
+ * Four documents stated that the user-level `sessionStart` hook sets it; none could, because a hook cannot export
+ * an environment variable to a later hook process — the host's own documentation says there is no field that
+ * passes state between hook invocations. So the condition was never true, the shim never stood down, and both
+ * levels ran the handler on every overlapping event. Measured on one machine: eleven hook groups registered at
+ * user level, six at project level, six events overlapping, and the host merges rather than replaces — it
+ * deduplicates only byte-identical handlers, and these differ (`… tlc-exec.mjs shim stop` against
+ * `… tlc-exec.mjs stop`) ([/decisions/ad-095.md](/decisions/ad-095.md)).
+ *
+ * invariant: the answer is derived from what is on disk, not from what a previous process might have exported.
+ * Two hooks in the same event are separate processes with no channel between them, so the only thing they can
+ * agree on is a file both can read.
+ */
+
+export type HookEntry = { command?: string; args?: readonly string[] };
+export type HookMatcher = { hooks?: readonly HookEntry[] };
+export type ProviderSettings = { hooks?: Record<string, readonly HookMatcher[]> };
+
+/**
+ * why: the launcher's file name, not its full path. The user-level hook names the runtime home
+ * (`~/.tlc/harness/bin/tlc-exec.mjs`) and the project shim names wherever init resolved the runtime from — the
+ * paths differ by construction, so comparing them would never match. What identifies the harness is the launcher
+ * it runs and the handler it runs it with.
+ */
+export const LAUNCHER = "tlc-exec";
+
+export function invocationText(entry: HookEntry): string {
+  return [entry.command ?? "", ...(entry.args ?? [])].join(" ");
+}
+
+/**
+ * Does this settings document already run the harness for this handler?
+ *
+ * invariant: `shim` is not part of the comparison. The user-level hook runs `tlc-exec <handler>` and the project
+ * shim runs `tlc-exec shim <handler>` — the same handler reached two ways. Requiring the spellings to match is
+ * what made the host's own deduplication miss them.
+ */
+export function coversHandler(settings: ProviderSettings, handler: string): boolean {
+  for (const matchers of Object.values(settings.hooks ?? {})) {
+    for (const matcher of matchers) {
+      for (const entry of matcher.hooks ?? []) {
+        const text = invocationText(entry);
+        if (text.includes(LAUNCHER) && new RegExp(`(^|\\s)${handler}(\\s|$)`).test(text)) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+export type ShimDecision = { run: boolean; reason: string };
+
+/**
+ * why: `null` for the user-level settings means "there is no user-level install", which is the case the project
+ * shim exists for — a cloud agent with no user-level hooks runs the real handler through it
+ * (`docs/architecture.md`). Absence must therefore mean run, and only a positive match means stand down.
+ */
+export function decideShim(userSettings: ProviderSettings | null, handler: string): ShimDecision {
+  if (userSettings === null) {
+    return { run: true, reason: "no user-level settings — this shim is the only hook for this event" };
+  }
+  return coversHandler(userSettings, handler)
+    ? {
+        run: false,
+        reason: `a user-level hook already runs ${handler} — standing down to avoid a second run`,
+      }
+    : { run: true, reason: `no user-level hook runs ${handler}` };
+}

package/src/core/skill/skill.link.ts

@@ -0,0 +1,92 @@
+/**
+ * Where the init skill has to be linked, and what counts as a link that works.
+ *
+ * hazard: the installer looped over every provider config directory that exists and linked
+ * `<provider>/skills/harness-init`, with the comment "Each provider only reads its own skills directory".
+ * `tlc harness update` linked to `<runtime-home>/../skills/harness-init` instead — a directory no provider reads,
+ * and which did not exist at all on the machine where this was found. So an update never refreshed the skill
+ * anywhere a provider looks, and the evidence was a link left pointing into a `/tmp` recovery directory that does
+ * not survive a reboot ([/decisions/ad-095.md](/decisions/ad-095.md)).
+ *
+ * invariant: one function, used by both, so the two cannot disagree again.
+ */
+
+export const SKILL_NAME = "harness-init";
+
+export type SkillLink = { providerDir: string; source: string; target: string };
+
+/**
+ * why: the provider directories are given rather than resolved here. Both tools relocate their config directory by
+ * environment variable, and this repository is itself installed under a relocated one — so the caller resolves and
+ * this decides.
+ */
+export function skillLinks(
+  runtimeHome: string,
+  providerDirs: readonly string[],
+  present: (path: string) => boolean,
+) {
+  const source = `${runtimeHome}/skills/${SKILL_NAME}`;
+  return providerDirs
+    .filter((dir) => present(dir))
+    .map((providerDir) => ({
+      providerDir,
+      source,
+      target: `${providerDir}/skills/${SKILL_NAME}`,
+    }));
+}
+
+export type LinkHealth =
+  | { state: "ok"; target: string; resolved: string }
+  | { state: "dangling"; target: string; resolved: string }
+  | { state: "outside-runtime"; target: string; resolved: string }
+  | { state: "absent"; target: string };
+
+/**
+ * hazard: a link whose destination does not exist reads as installed to anything that only checks the link. The
+ * one found on the machine that prompted this pointed at `/tmp/tlc-recovery-…/install/skills/harness-init` — a
+ * directory from a recovery run, gone on the next boot, and invisible to every check the harness had.
+ *
+ * invariant: a link that resolves outside the runtime home is reported even when it currently exists, because
+ * a source that is not the runtime is a source that will move.
+ *
+ * hazard: BOTH sides have to be resolved. The first version compared the link's realpath against the runtime home
+ * as configured, and on a contributor install — where `~/.tlc/harness` is a symlink to a working clone, which
+ * `doctor` reports as healthy — the two never share a prefix. It printed two failures on a machine where nothing
+ * was wrong, which is the reading AD-034 exists to forbid: a warning that fires on a healthy install is not a
+ * warning ([/decisions/ad-095.md](/decisions/ad-095.md)).
+ */
+export function linkHealth(
+  target: string,
+  runtimeHome: string,
+  probe: {
+    linkTarget: (path: string) => string | null;
+    exists: (path: string) => boolean;
+    realpath?: (path: string) => string;
+  },
+): LinkHealth {
+  const resolved = probe.linkTarget(target);
+  if (resolved === null) {
+    return { state: "absent", target };
+  }
+  if (!probe.exists(resolved)) {
+    return { state: "dangling", target, resolved };
+  }
+  const resolveHome = probe.realpath ?? ((path: string) => path);
+  const home = resolveHome(runtimeHome).replace(/\/+$/, "");
+  return resolved === home || resolved.startsWith(`${home}/`)
+    ? { state: "ok", target, resolved }
+    : { state: "outside-runtime", target, resolved };
+}
+
+export function linkHealthMessage(health: LinkHealth): string {
+  switch (health.state) {
+    case "ok":
+      return `linked → ${health.resolved}`;
+    case "dangling":
+      return `points at ${health.resolved}, which does not exist — re-run \`tlc harness install\``;
+    case "outside-runtime":
+      return `points at ${health.resolved}, outside the runtime — it will break when that path goes`;
+    default:
+      return "not linked — the provider cannot see the init skill";
+  }
+}

package/src/entrypoints/shim.ts

@@ -1,23 +1,61 @@
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { runtimeHome } from "../platform/paths.ts";
+import { coreFacade, type ProviderSettings } from "../core/index.ts";
+import { runtimeHome, userSettingsPaths } from "../platform/paths.ts";
 
-const handler = process.argv[2];
-if (!handler) {
-  console.error("usage: shim <handler-name>");
-  process.exit(1);
+function requireHandler(): string {
+  const name = process.argv[2];
+  if (!name) {
+    console.error("usage: shim <handler-name>");
+    process.exit(1);
+  }
+  return name;
 }
 
-// hazard: a project-level hook and a user-level hook both fire for the same event. The user-level
-// session start sets TLC_ACTIVE, so the project shim stands down rather than double-firing.
-if (process.env.TLC_ACTIVE === "1") {
+const handler = requireHandler();
+
+/**
+ * hazard: a project-level hook and a user-level hook both fire for the same event, and the host merges the two
+ * rather than replacing one with the other. This used to read `TLC_ACTIVE`, which nothing ever set — a hook cannot
+ * export an environment variable to a later hook process, so the condition was never true and both levels ran the
+ * handler every time ([/decisions/ad-095.md](/decisions/ad-095.md)).
+ *
+ * invariant: read from disk, because two hooks in one event share no channel except the filesystem.
+ */
+// why: the first document that covers the handler wins, and a document that does not cover it must not stop the
+// next one being read — otherwise a user with only one editor installed globally would decide for both.
+function coveringSettings(): ProviderSettings | null {
+  let seen: ProviderSettings | null = null;
+  for (const path of userSettingsPaths()) {
+    let parsed: ProviderSettings;
+    try {
+      parsed = JSON.parse(readFileSync(path, "utf8")) as ProviderSettings;
+    } catch {
+      continue;
+    }
+    seen = parsed;
+    if (coreFacade.shim.coversHandler(parsed, handler)) {
+      return parsed;
+    }
+  }
+  return seen;
+}
+
+const decision = coreFacade.shim.decideShim(coveringSettings(), handler);
+if (!decision.run) {
   process.stdout.write("{}\n");
   process.exit(0);
 }
 
 const home = runtimeHome();
-const execBin = join(home, "bin", "tlc-exec");
+/**
+ * hazard: this was the extensionless bash wrapper, which Windows cannot execute — so the first branch simply
+ * never fired there and the shim fell through to the bundle. The launcher is a `.mjs` run by the interpreter
+ * already running this, which behaves the same on every platform
+ * ([/decisions/ad-097.md](/decisions/ad-097.md)).
+ */
+const execBin = join(home, "bin", "tlc-exec.mjs");
 const distHandler = join(home, "dist", `${handler}.mjs`);
 const srcHandler = join(home, "src", "entrypoints", `${handler}.ts`);
 
@@ -35,7 +73,7 @@ function run(command: string, args: string[]): void {
 }
 
 if (existsSync(execBin)) {
-  run(execBin, [handler]);
+  run(process.execPath, [execBin, handler]);
 } else if (existsSync(distHandler)) {
   run(process.execPath, [distHandler]);
 } else if (existsSync(srcHandler)) {

package/src/platform/fs-atomic.ts

@@ -88,20 +88,52 @@ function readJson<T>(path: string): T | null {
   }
 }
 
-async function withFileLock<T>(lockPath: string, fn: () => Promise<T>): Promise<T> {
+/**
+ * hazard: `EEXIST` is what a held lock looks like on POSIX and only sometimes on Windows. There, a concurrent
+ * `wx` open against a file another process is creating or unlinking answers `EPERM` — so the loop below threw
+ * instead of waiting, and the two-concurrent-writers test failed in Windows CI with
+ * `EPERM: operation not permitted, open '…\handoff.json.lock'`. This module already listed the codes that mean
+ * "busy, come back" for its rename; the lock, which is the one place contention is the expected case, did not
+ * consult them ([/decisions/ad-086.md](/decisions/ad-086.md)).
+ */
+function isContention(error: unknown): boolean {
+  return errorCode(error) === "EEXIST" || isRetryableFsError(error);
+}
+
+/**
+ * invariant: prefixed names. `FsAtomicOptions` already carries `attempts` and `sleep` for the rename retry, and
+ * `UpdateJsonAtomicOptions` is the intersection of both — sharing a name there would silently hand the lock's
+ * budget to the rename, or the other way round.
+ */
+export type FileLockOptions = {
+  /** Injected so the contention branch has a test that does not need a second process or Windows. */
+  openLock?: (path: string) => void;
+  lockSleep?: (ms: number) => Promise<void>;
+  lockAttempts?: number;
+};
+
+export async function withFileLock<T>(
+  lockPath: string,
+  fn: () => Promise<T>,
+  options: FileLockOptions = {},
+): Promise<T> {
+  const {
+    openLock = (path: string) => closeSync(openSync(path, "wx")),
+    lockSleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)),
+    lockAttempts = 200,
+  } = options;
   mkdirSync(dirname(lockPath), { recursive: true });
-  const attempts = 200;
   let acquired = false;
-  for (let attempt = 0; attempt < attempts; attempt++) {
+  for (let attempt = 0; attempt < lockAttempts; attempt++) {
     try {
-      closeSync(openSync(lockPath, "wx"));
+      openLock(lockPath);
       acquired = true;
       break;
     } catch (error) {
-      if (errorCode(error) !== "EEXIST") {
+      if (!isContention(error)) {
         throw error;
       }
-      await new Promise((resolve) => setTimeout(resolve, nextDelay({ attempt, baseMs: 10, capMs: 200 })));
+      await lockSleep(nextDelay({ attempt, baseMs: 10, capMs: 200 }));
     }
   }
   if (!acquired) {
@@ -116,27 +148,33 @@ async function withFileLock<T>(lockPath: string, fn: () => Promise<T>): Promise<
   }
 }
 
-export type UpdateJsonAtomicOptions = FsAtomicOptions & {
-  lockPath: string /**
-   * Run inside the write lock, after the file lands. The platform does not care what it does — recording a
-   * content hash is core's business, and doing it here is what makes the record and the content one write.
-   */;
-  afterWrite?: (path: string) => void;
-};
+export type UpdateJsonAtomicOptions = FsAtomicOptions &
+  FileLockOptions & {
+    lockPath: string;
+    /**
+     * Run inside the write lock, after the file lands. The platform does not care what it does — recording a
+     * content hash is core's business, and doing it here is what makes the record and the content one write.
+     */
+    afterWrite?: (path: string) => void;
+  };
 
 export async function updateJsonAtomic<T>(
   path: string,
   mutator: (current: T | null) => T,
   options: UpdateJsonAtomicOptions,
 ): Promise<T> {
-  const { lockPath, afterWrite, ...atomicOptions } = options;
-  return withFileLock(lockPath, async () => {
-    const current = readJson<T>(path);
-    const next = mutator(current);
-    await writeJsonAtomic(path, next, atomicOptions);
-    // why: inside the lock. A caller that sealed after the lock released would race the next writer, and the pair
-    // that lost would leave a record matching neither content ([/decisions/ad-078.md](/decisions/ad-078.md)).
-    afterWrite?.(path);
-    return next;
-  });
+  const { lockPath, afterWrite, openLock, lockSleep, lockAttempts, ...atomicOptions } = options;
+  return withFileLock(
+    lockPath,
+    async () => {
+      const current = readJson<T>(path);
+      const next = mutator(current);
+      await writeJsonAtomic(path, next, atomicOptions);
+      // why: inside the lock. A caller that sealed after the lock released would race the next writer, and the
+      // pair that lost would leave a record matching neither content ([/decisions/ad-078.md](/decisions/ad-078.md)).
+      afterWrite?.(path);
+      return next;
+    },
+    { openLock, lockSleep, lockAttempts },
+  );
 }

package/src/platform/links.ts

@@ -0,0 +1,73 @@
+/**
+ * The two filesystem primitives an install needs: a directory link, and a config seeded once.
+ *
+ * why there is no platform branch here: the code this replaces shelled out to `ln -sfn` on POSIX and to
+ * PowerShell on Windows, and *that* is where the branch came from — not from anything Node cannot do. Node's
+ * `symlinkSync` takes a link type that is only meaningful on Windows and is ignored elsewhere, so `"junction"`
+ * is correct on all three platforms: a junction on Windows, a plain symlink on Linux and macOS. Measured on
+ * Linux, and stated in Node's own API history ([/decisions/ad-097.md](/decisions/ad-097.md)).
+ *
+ * why junction rather than a Windows symlink: a directory symlink needs Developer Mode or an elevated shell,
+ * which the PowerShell installer demanded of a contributor. A junction needs neither.
+ *
+ * The launcher on PATH is not here either. `npm i -g` generates the shims for the platform it runs on, and
+ * `npm link` does the same from a checkout — a second implementation of that is a second thing to get wrong.
+ */
+import { copyFileSync, existsSync, lstatSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** invariant: one link type, chosen because Windows is the only platform that reads it. */
+export const LINK_TYPE = "junction";
+
+export type LinkOutcome =
+  | { kind: "linked"; target: string; source: string }
+  | { kind: "relinked"; target: string; source: string }
+  | { kind: "refused"; target: string; reason: string };
+
+/**
+ * Point `target` at `source`.
+ *
+ * invariant: an existing *link* is replaced; anything else is refused. A real directory at the target is either
+ * somebody's install or somebody's work, and removing it to make room is not a decision a tool makes
+ * ([/decisions/ad-046.md](/decisions/ad-046.md)). The bash installer removed it.
+ */
+export function linkDir(source: string, target: string): LinkOutcome {
+  let replaced = false;
+  if (isLink(target)) {
+    rmSync(target, { recursive: true, force: true });
+    replaced = true;
+  } else if (existsSync(target)) {
+    return {
+      kind: "refused",
+      target,
+      reason: `${target} exists and is not a link — move it aside and re-run`,
+    };
+  }
+  mkdirSync(dirname(target), { recursive: true });
+  symlinkSync(source, target, LINK_TYPE);
+  return { kind: replaced ? "relinked" : "linked", target, source };
+}
+
+/**
+ * why lstat: a link whose destination is gone is still a link, and `existsSync` says it is not there — so the
+ * check has to come first, or a dangling link reads as free space. Node reports a Windows junction as a symbolic
+ * link, so one call covers both kinds.
+ */
+export function isLink(path: string): boolean {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/** invariant: seeded once, never overwritten. The operator's config is theirs from the moment it exists. */
+export function seedConfig(dest: string): { seeded: boolean; path: string } {
+  const path = join(dest, "config.json");
+  const example = join(dest, "config.example.json");
+  if (existsSync(path) || !existsSync(example)) {
+    return { seeded: false, path };
+  }
+  copyFileSync(example, path);
+  return { seeded: true, path };
+}

package/src/platform/paths.ts

@@ -78,3 +78,30 @@ export function cursorConfigDir(): string {
   const custom = process.env.CURSOR_CONFIG_DIR?.trim();
   return custom && custom.length > 0 ? custom : join(homedir(), ".cursor");
 }
+
+/**
+ * The user-level hook documents, in the order the shim reads them.
+ *
+ * why: the project shim is told a handler and nothing else — it does not know which provider invoked it. So it
+ * asks both: if any user-level document already runs this handler, a second run would be a duplicate. The cost of
+ * that imprecision is under-running in a setup where one editor is installed globally and the other only in the
+ * project, which is the safe direction — the alternative was running the handler twice, which is what actually
+ * happened ([/decisions/ad-095.md](/decisions/ad-095.md)).
+ *
+ * invariant: both paths are resolved, never assumed. Either tool can relocate its config directory by env, and
+ * this repository is itself installed under a relocated one.
+ */
+export function userSettingsPaths(): string[] {
+  return [join(claudeConfigDir(), "settings.json"), join(cursorConfigDir(), "hooks.json")];
+}
+
+/**
+ * The provider config directories, resolved. Each provider reads only its own skills directory, so this is the
+ * list anything linking the init skill must walk.
+ *
+ * invariant: resolved, never assumed — either tool relocates its config directory by env, and this repository is
+ * itself installed under a relocated one ([/decisions/ad-095.md](/decisions/ad-095.md)).
+ */
+export function providerConfigDirs(): string[] {
+  return [cursorConfigDir(), claudeConfigDir()];
+}