@descent-vtt/spec-harness 0.17.0 → 0.19.0

package/dist/configure.d.ts

@@ -8,7 +8,8 @@
  * nothing to add.
  */
 import type { AllowedSigner } from './signers.js';
-import type { HookLine } from './usage.js';
+import type { LocalBranch } from './types.js';
+import { type HookLine } from './usage.js';
 import { type ClaudeCodeCheck } from './versions.js';
 type Json = Record<string, unknown>;
 /** The project root, as Claude Code substitutes it in a hook's arguments and in a plugin server's. */
@@ -24,6 +25,44 @@ export declare const PROJECT_DIR_OR_HERE = "${CLAUDE_PROJECT_DIR:-.}";
  * path is one argument whatever it holds, and no shell is involved.
  */
 export declare const GUARD_HOOK: Readonly<Json>;
+/**
+ * The release of Claude Code from which a comma in a matcher separates
+ * names as a `|` does. Its page on debugging a configuration (Check hooks,
+ * read 2026-10-14) has a comma before it fall through to the reading of a
+ * pattern, under which the matcher never matched, and its changelog has the
+ * fix under this release: hooks with comma-separated matchers no longer
+ * silently never firing.
+ */
+export declare const COMMA_SINCE = "2.1.191";
+/**
+ * The release of Claude Code from which a hyphenated name in a matcher of
+ * names is matched exactly. Its changelog
+ * (https://code.claude.com/docs/en/changelog, 2.1.195, read 2026-10-18) has,
+ * among its fixes, hook matchers with hyphenated identifiers that matched as
+ * substrings, and match exactly from this release on; it does not say how
+ * the rest of such a matcher was read.
+ */
+export declare const HYPHEN_SINCE = "2.1.195";
+/**
+ * How the Claude Code that runs the hooks reads a matcher of names: as every
+ * release from {@link HYPHEN_SINCE} on, and the hooks reference today; as
+ * the release named, which is older; or it cannot be told, where the release
+ * cannot.
+ */
+export type Matching = {
+    readonly as: 'today';
+} | {
+    readonly as: 'older';
+    readonly release: string;
+} | {
+    readonly as: 'untold';
+};
+/**
+ * How the Claude Code doctor asked its release reads a matcher of names. A
+ * release that was not asked, or could not be told, leaves the reading
+ * untold: asked or not, nothing says which it is.
+ */
+export declare function matchingUnder(release: ClaudeCodeCheck | null): Matching;
 /** What reads a matcher that is a pattern: the writing tools it matches, or `null` where that cannot be told. */
 export type PatternReader = (source: string) => readonly string[] | null;
 /**
@@ -57,8 +96,34 @@ export declare function patternReader(read?: PatternReader): PatternReader;
  *
  * `pattern` reads a matcher that is a pattern: the run's own reader, where
  * the run has read the file's matchers already ({@link patternReader}).
+ * `matching` is how the Claude Code here reads a matcher of names, where
+ * the run asked its release ({@link matchingUnder}): a line that
+ * release starts for no write is no guard, and init's own is written beside
+ * it.
  */
-export declare function mergeClaudeSettings(current: Json, isHook?: (words: readonly string[]) => boolean, pattern?: PatternReader): Json | null;
+export declare function mergeClaudeSettings(current: Json, isHook?: (words: readonly string[]) => boolean, pattern?: PatternReader, matching?: Matching): Json | null;
+/**
+ * Settings with init's entry under `SessionStart` added beside its two, or
+ * `null` where it is not to be: where init's own line does not stand
+ * under both `PreToolUse` and `PostToolUse`, a file init writes no hook
+ * into or one it has yet to complete; and where a line of the hook stands
+ * under `SessionStart` already, init's or one `isHook` knows, which would
+ * say the same twice (ADR-0012).
+ */
+export declare function withSessionStart(settings: Json, isHook: (words: readonly string[]) => boolean): Json | null;
+/**
+ * Whether settings have Claude Code start the hook as a session starts: an
+ * entry under `SessionStart` whose line is init's, or one `isHook` knows
+ * as the hook's. Its matcher is not read: one that names some of the ways a
+ * session starts has the check made for those.
+ */
+export declare function startsSessions(settings: unknown, isHook: (words: readonly string[]) => boolean): boolean;
+/**
+ * What doctor notes where settings hold the guard hooks and none under
+ * `SessionStart`: what would hold every write is said at the first write,
+ * which it holds, and not as the session starts.
+ */
+export declare const NO_SESSION_START = "note: no settings file has Claude Code start the hook as a session starts, so a configuration that does not load, or a brief named that spec-brief does not list, is said only at the first write, which it holds: spec-harness init --write adds the entry beside the two it wrote";
 /** The server's entry, reading the project at `projectDir`: {@link PROJECT_DIR} for the plugin, {@link PROJECT_DIR_OR_HERE} for a project. */
 export declare function mcpServer(projectDir: string): Json;
 /**
@@ -113,7 +178,8 @@ export interface HookReport {
      * `guards`: Claude Code waits on the hook before a write, and the hook
      * checks it. `off`: the hook checks no write, for a line it cannot read, a
      * root that is no directory, or a root that is a directory outside any
-     * work tree. `held`: the hook holds every write, for a
+     * work tree; or it is never started, in a file an array for a matcher
+     * keeps Claude Code from loading the hooks of. `held`: the hook holds every write, for a
      * brief the line names that is not one. `unstarted`: Claude Code waits on
      * the line before no write, so it is not the guard. `unknown`: what the
      * hook is handed, which writes it is started for, or whether Claude Code
@@ -132,6 +198,30 @@ export interface HookReport {
     /** What `onFailure` changes, where the entry sets it to `"block"`. */
     readonly note: string | null;
 }
+/** An array that stands for a matcher where it unloads a settings file's hooks: the event it stands under, and the array as written. */
+export interface ArrayMatcher {
+    readonly event: string;
+    readonly matcher: string;
+}
+/**
+ * The first array that stands for a matcher under `PreToolUse` or
+ * `PermissionRequest` in a settings file, or `null`.
+ *
+ * Claude Code's page on debugging a configuration
+ * (https://code.claude.com/docs/en/debug-your-config, Check hooks, read
+ * 2026-10-14) has a matcher that is an array, where it must be one string,
+ * as an entry Claude Code lists as an invalid setting, at the start of an
+ * interactive session and in `claude doctor`; and where the array is under
+ * one of these two events, none of that file's other hooks load either. It
+ * names no release. So a file that holds one runs no hook at all, whoever
+ * wrote the entry and whatever it runs: the array's own is not loaded, and
+ * neither is any other.
+ */
+export declare function arrayMatcher(settings: unknown): ArrayMatcher | null;
+/** What is said of a settings file that an array for a matcher keeps Claude Code from loading the hooks of. */
+export declare function describeArrayMatcher(file: string, { event, matcher }: ArrayMatcher): string;
+/** How a matcher that is an array is mended. */
+export declare const ONE_STRING = "write the matcher as one string, its names between \"|\"";
 /** The words handed over for every line of the harness's in the settings files, for a caller that has to ask something of each before it reports them. */
 export declare function handedLines(sources: readonly ClaudeSettings[], project: string): string[][];
 /**
@@ -144,16 +234,25 @@ export declare function handedLines(sources: readonly ClaudeSettings[], project:
  * A line that guards and holds no more than a release wrote is reported
  * with nothing to say, as it always was. One with more on it is said as it
  * is, and fails nothing. One the hook cannot read, or whose root is no
- * directory, is a guard that is off, and one that names a brief which is not
+ * directory, or is in no work tree that holds the project, is a guard that
+ * is off, and one that names a brief which is not
  * one holds every write: each a problem, and doctor exits 1 for it. A line
  * Claude Code waits on before no write is not the guard, whatever the hook
  * would do with it.
  *
  * `pattern` reads a matcher that is a pattern, once for every entry under
  * it in every file: the run's own reader, where something else in the run
- * reads the same files ({@link patternReader}).
+ * reads the same files ({@link patternReader}). `matching` is how the
+ * Claude Code here reads a matcher of names, where its release was asked
+ * ({@link matchingUnder}); a caller that asks none reads one as every
+ * release from {@link HYPHEN_SINCE} on does.
+ *
+ * A file that holds an array for a matcher under `PreToolUse` or
+ * `PermissionRequest` has none of its hooks loaded ({@link arrayMatcher}):
+ * each line of the hook there is started for no write, and one that stood
+ * to be started for a write is a guard that is off.
  */
-export declare function reportHooks(sources: readonly ClaudeSettings[], project: string, read: (words: readonly string[]) => HookLine | null, pattern?: PatternReader): HookReport[];
+export declare function reportHooks(sources: readonly ClaudeSettings[], project: string, read: (words: readonly string[]) => HookLine | null, pattern?: PatternReader, matching?: Matching): HookReport[];
 /** Whether a project's `.mcp.json` registers a server under the harness's name, however it runs it. */
 export declare function registersServer(mcp: unknown): boolean;
 /** A Claude Code settings file, named as a person finds it, and what reading it gave: an object, or nothing usable. */
@@ -278,11 +377,26 @@ export interface ClaudeCodeWiring {
     readonly lines: readonly HookReport[];
     /** Whether `.mcp.json` registers the server. */
     readonly server: boolean;
+    /** Whether a settings file has Claude Code start the hook as a session starts (startsSessions). */
+    readonly sessionStart: boolean;
+    /**
+     * The release of the Claude Code on `PATH`, where it was asked: a matcher
+     * that lists names with a comma is read as that release reads it
+     * ({@link matchingUnder}). `null` where it was not asked.
+     */
+    readonly release: ClaudeCodeCheck | null;
+    /**
+     * An array for a matcher that keeps Claude Code from loading the hooks of
+     * the project's settings file, the file init writes its hooks into, or
+     * `null`: init writes none there while it stands ({@link arrayMatcher}).
+     */
+    readonly unloaded: ArrayMatcher | null;
 }
 export type WiringState = 'plugin' | 'init' | 'both' | 'none';
-/** The wiring as its descriptions read it: what a caller knows of the plugin's presence, which one that does not ask leaves out. */
+/** The wiring as its descriptions read it: what a caller knows of the plugin's presence, and of an array in the project's settings, which one that does not ask leaves out. */
 type Wired = Pick<ClaudeCodeWiring, 'plugin' | 'hooks' | 'server'> & {
     readonly presence?: PluginPresence | null;
+    readonly unloaded?: ArrayMatcher | null;
 };
 /**
  * Which of the four the wiring is. `both` is a double install, and doctor
@@ -315,8 +429,7 @@ export declare function describePresence(wiring: Wired): string | null;
 export declare function describeClaudeCode(wiring: Wired): string;
 /** The spec-brief plugin this package ships, as spec-brief's `plugins` names it. */
 export declare const PLUGIN = "@descent-vtt/spec-harness/spec-brief-plugin";
-/** spec-brief's configuration files, in the order spec-brief looks for them in a directory. */
-export declare const SPEC_BRIEF_CONFIGS: readonly string[];
+export { SPEC_BRIEF_CONFIGS } from './config.js';
 /**
  * The file a package's `exports` target names for an import, as Node's
  * PACKAGE_TARGET_RESOLVE finds it, or `null` when it names none: a string
@@ -362,10 +475,10 @@ export declare function describePlugin(state: PluginState): string;
 export interface BaseFacts {
     /** The remote's default branch as a local ref, such as `origin/main`, or `null`. */
     readonly remoteDefault: string | null;
-    /** The branch checked out, or `null` on a detached head. */
+    /** The name of the branch checked out, or `null` on a detached head. */
     readonly branch: string | null;
-    /** Every local branch. */
-    readonly branches: readonly string[];
+    /** Every local branch, by its name and the ref a base names it by. */
+    readonly branches: readonly LocalBranch[];
 }
 /** The base `init` names, and why; `base` is `null` when none can be told. */
 export interface BaseChoice {
@@ -412,6 +525,30 @@ export declare function describeClaudeRelease(check: ClaudeCodeCheck): string;
 export type GitHookState = {
     readonly state: 'runs' | 'absent' | 'other' | 'inert';
     readonly file: string;
+}
+/**
+ * What stands at the path is no file, `what` it is instead. `stops`: git
+ * can execute it, tries to run it as the hook, fails, and stops every
+ * commit. `ignored`: git cannot execute it, and skips it as it skips a
+ * hook that is not executable.
+ */
+ | {
+    readonly state: 'stops' | 'ignored';
+    readonly file: string;
+    readonly what: string;
+}
+/**
+ * A file the account may not read, `reason` being why, and `runs` whether
+ * git may execute it. One git may not execute it skips, with a hint, and
+ * commits. One it may it runs, and a script the shell cannot read either
+ * stops every commit there (measured with git 2.47 as an ordinary account),
+ * where a program runs without being read: which it is cannot be read.
+ */
+ | {
+    readonly state: 'unreadable';
+    readonly file: string;
+    readonly runs: boolean;
+    readonly reason: string;
 } | {
     readonly state: 'unknown';
     readonly reason: string;
@@ -438,13 +575,17 @@ export declare const PROTECT_RULE_FILES: string;
 export declare const GIT_HOOK_LINE = "node node_modules/@descent-vtt/spec-harness/bin/spec-harness.js hook git";
 /**
  * The hook init writes. It is a POSIX sh script on every platform, since Git
- * for Windows runs a hook with the sh it ships. Where the project's install
- * is not in the work tree - a linked worktree nobody installed into, a
+ * for Windows runs a hook with the sh it ships. git starts it at the top of
+ * the work tree it commits in, so the project's install is read from there,
+ * and where a linked worktree has none, from the repository's main work
+ * tree: the work tree whose `.git` the common directory is, where `git
+ * worktree add` was run and the project installed (ADR-0005). Where neither
+ * has the install - a worktree of a repository nobody installed into, a
  * repository that shares its hooks with one that uses the harness - node
- * would end on a stack trace, so the hook says what is missing and where, and
- * the commit waits, as it did when npx found nothing to run.
+ * would end on a stack trace, so the hook says what is missing and where,
+ * and the commit waits, as it did when npx found nothing to run.
  */
-export declare const PRE_COMMIT = "#!/bin/sh\n# spec-harness: refuse a commit that changes what the active brief protects.\n# git runs this at the top of the work tree it commits in, a linked worktree's\n# own, wherever the hook is kept: the project's install is read from there.\nbin=node_modules/@descent-vtt/spec-harness/bin/spec-harness.js\nif [ ! -f \"$bin\" ]; then\n  printf '%s\\n' \"spec-harness: $bin is not in $PWD, the work tree git commits in: install the project's dependencies there, as with npm ci, and commit again\" >&2\n  exit 2\nfi\nexec node \"$bin\" hook git\n";
+export declare const PRE_COMMIT = "#!/bin/sh\n# spec-harness: refuse a commit that changes what the active brief protects.\n# git runs this at the top of the work tree it commits in, a linked worktree's\n# own, wherever the hook is kept: the project's install is read from there,\n# or, where a linked worktree has none, from the repository's main work tree.\nbin=node_modules/@descent-vtt/spec-harness/bin/spec-harness.js\nif [ ! -f \"$bin\" ]; then\n  common=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)\n  if [ \"${common##*/}\" = .git ] && [ -f \"${common%/.git}/$bin\" ]; then\n    bin=${common%/.git}/$bin\n  else\n    printf '%s\\n' \"spec-harness: $bin is not in $PWD, the work tree git commits in, nor in its repository's main work tree: install the project's dependencies there, as with npm ci, and commit again\" >&2\n    exit 2\n  fi\nfi\nexec node \"$bin\" hook git\n";
 /**
  * What doctor and init add of a hook whose text runs the harness through
  * npx: the hook init wrote through 0.9.1, or the line it advised for a hook
@@ -469,4 +610,3 @@ export declare function graphReadsBriefs(config: Json, briefs: string): boolean;
 export declare function describeGraph(archiveGlob: string, briefs: string, reads: boolean, added: boolean): string;
 /** spec-graph's configuration with the archive read as history, or `null` when it already is. */
 export declare function mergeSpecGraph(current: Json, archiveGlob: string): Json | null;
-export {};