@descent-vtt/spec-harness 0.18.0 → 0.19.0

package/dist/configure.d.ts

@@ -8,6 +8,7 @@
  * nothing to add.
  */
 import type { AllowedSigner } from './signers.js';
+import type { LocalBranch } from './types.js';
 import { type HookLine } from './usage.js';
 import { type ClaudeCodeCheck } from './versions.js';
 type Json = Record<string, unknown>;
@@ -34,25 +35,34 @@ export declare const GUARD_HOOK: Readonly<Json>;
  */
 export declare const COMMA_SINCE = "2.1.191";
 /**
- * How the Claude Code that runs the hooks reads a comma in a matcher of
- * names: as a separator, from {@link COMMA_SINCE} on; as part of a pattern,
- * in the release named, which is older; or it cannot be told, where the
- * release cannot.
+ * 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 type Commas = {
-    readonly as: 'separator';
+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: 'pattern';
+    readonly as: 'older';
     readonly release: string;
 } | {
     readonly as: 'untold';
 };
 /**
- * How the Claude Code doctor asked its release reads a comma. A release that
- * was not asked, or could not be told, leaves the reading untold: asked or
- * not, nothing says which it is.
+ * 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 commasUnder(release: ClaudeCodeCheck | null): Commas;
+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;
 /**
@@ -86,12 +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}).
- * `commas` is how the Claude Code here reads a comma in a matcher of names,
- * where the run asked its release ({@link commasUnder}): a line that
+ * `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, commas?: Commas): 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;
 /**
@@ -210,17 +242,17 @@ export declare function handedLines(sources: readonly ClaudeSettings[], project:
  *
  * `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}). `commas` is how the Claude
- * Code here reads a comma in a matcher of names, where its release was
- * asked ({@link commasUnder}); a caller that asks none reads a comma as
- * every release from {@link COMMA_SINCE} on does.
+ * 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, commas?: Commas): 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. */
@@ -345,17 +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 commasUnder}). `null` where it was not asked.
+     * ({@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
@@ -388,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
@@ -435,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 {
@@ -496,6 +536,19 @@ export type GitHookState = {
     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;
@@ -522,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
@@ -553,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 {};