@consiliency/agent-board-cli 1.22.5 → 1.24.0

package/dist/doctor_scopes.d.ts

@@ -0,0 +1,288 @@
+import type { IdentityHarness } from "@consiliency/agent-board-client";
+export declare const BOARD_MCP_MARKER = "agent-board-mcp";
+export declare const METADATA_ONLY_FLAG = "--metadata-only";
+export declare const OPENCODE_PLUGIN_PACKAGE = "@consiliency/agent-board-opencode";
+export declare const PI_PACKAGE = "npm:@consiliency/agent-board-pi";
+/** Claude Code events that each need exactly one `wake-hook.sh` hook (`docs/local-wake-signal.md`). */
+export declare const CLAUDE_REQUIRED_HOOK_EVENTS: readonly ["SessionStart", "FileChanged"];
+/** A wake hook is a command with a token whose BASENAME is this (see `namesWakeHook`). */
+export declare const WAKE_HOOK_MARKER = "wake-hook.sh";
+export declare const CLAUDE_PLUGIN_ID = "agent-board@message-board";
+export declare const CLAUDE_PLUGIN_MARKETPLACE = "message-board";
+/** Compared lower-cased, as Claude Code compares repos. */
+export declare const CLAUDE_PLUGIN_REPO = "consiliency/message-board";
+export declare const CLAUDE_PLUGIN_SERVER = "agent-board";
+export declare const CLAUDE_PLUGIN_MCP_PACKAGE = "@consiliency/agent-board-mcp";
+/** The SL-0 outcome: `B` = the FileChanged hook carries `asyncRewake: true`. */
+export declare const CLAUDE_WAKE_SHAPE: "A" | "B";
+export declare const CLAUDE_PLUGIN_HOOK_COMMANDS: Readonly<Record<string, string>>;
+/** The stanza a plugin of version `version` must carry: the pin IS the plugin version. */
+export declare function claudePluginStanza(version: string): {
+    command: string;
+    args: string[];
+};
+/**
+ * Whether a hook command names the wake hook. The tokenizer is frozen: split on whitespace, strip
+ * quotes, no comment handling; a token matches when its basename is exactly `wake-hook.sh`, so
+ * `codex-wake-hook.sh` does not. Floor: a hook that never names the basename is invisible.
+ */
+export declare function namesWakeHook(command: string): boolean;
+export interface ScopeContext {
+    cwd: string;
+    home: string;
+    env: Record<string, string | undefined>;
+    /** Claude Code's managed directory (Linux `/etc/claude-code`); injectable for tests. */
+    claudeManagedDir: string;
+    fs: RegistrationFs;
+    /** The OS, for the managed (MDM) sources doctor probes. Absent → treated as Linux. */
+    platform?: NodeJS.Platform;
+    /** The login name the macOS per-user managed plist is keyed by. */
+    userName?: string;
+    /** Registry probe for the Windows policy keys; default `nodeRegQuery`. */
+    regQuery?: RegQuery;
+}
+/** The filesystem reads registration makes; everything is read-only. */
+export interface RegistrationFs {
+    /** File text, or null when the file does not exist. */
+    readFile(path: string): string | null;
+    /** Sorted entry names, or null when the directory does not exist. */
+    readdir(path: string): string[] | null;
+    lstat(path: string): {
+        uid: number;
+        size: number;
+        isFile: boolean;
+    } | null;
+    exists(path: string): boolean;
+    /** The canonical path (every symlink resolved), or null when it does not exist. */
+    realpath(path: string): string | null;
+    getuid(): number;
+}
+export declare const nodeRegistrationFs: RegistrationFs;
+export declare class UnparseableConfigError extends Error {
+    constructor(message: string);
+}
+/** Keys that name a prototype slot rather than data: a file carrying one is refused. */
+export declare const FORBIDDEN_CONFIG_KEYS: ReadonlySet<string>;
+/** An OWN property of `value`, else undefined: nothing is read through a prototype. */
+export declare function own(value: unknown, key: string): unknown;
+/** JSONC: `//` and `/* *\/` comments and trailing commas removed outside strings, then JSON. */
+export declare function parseJsonc(text: string): unknown;
+/**
+ * A restricted TOML reader: enough of the grammar to read `[mcp_servers.*]` and `[projects.*]`
+ * tables without a new dependency, and fail-closed on anything outside it. It handles bare and
+ * quoted dotted keys, `[table]` and `[[array.table]]` headers, basic/literal (and multi-line)
+ * strings, arrays over several lines, inline tables, and bare scalars. Sub-tables nest, so
+ * `[mcp_servers.x.env]` is `x`'s `env`, never a server named `x.env`.
+ */
+export declare function parseRestrictedToml(text: string): Record<string, unknown>;
+type McpShape = "claude" | "toml" | "agy" | "opencode";
+export interface McpEntry {
+    /** Server name (the harness merges same-named entries across its layers). */
+    name: string;
+    command: string | null;
+    args: string[];
+    /** The harness will not launch it (`disabled: true`, `enabled = false`). */
+    disabled: boolean;
+    /** The entry's own fields, as written: a field-merging harness overlays these across layers. */
+    fields: Readonly<Record<string, unknown>>;
+    shape: McpShape;
+}
+export interface HookEntry {
+    /** The handler's `type` (`command`, `http`, `prompt`, `agent`, `mcp_tool`); a non-string type is "". */
+    type: string;
+    /** A command handler's command; null for every other handler (its url or prompt is never kept). */
+    command: string | null;
+    /** Claude Code's `asyncRewake`: only a literal `true` counts. */
+    asyncRewake: boolean;
+    /**
+     * The group has a matcher that filters (round-2 F029): anything but absent or "". A SessionStart
+     * matcher filters on the start source, a FileChanged one on basename(file_path) (binary). The
+     * matcher text itself is never kept.
+     */
+    hasMatcher: boolean;
+    /** The handler's and its group's own key NAMES (never values), for the exact freeze. */
+    handlerKeys: string[];
+    groupKeys: string[];
+}
+export interface ScopeContribution {
+    mcp: McpEntry[];
+    /** Claude hooks: event → the hooks registered for it. */
+    hooks: Record<string, HookEntry[]>;
+    /** opencode `plugin` / pi `packages` specs. */
+    packages: string[];
+}
+export interface ScopeFile {
+    row: string;
+    path: string;
+    contribution: ScopeContribution;
+    /** A synthetic plugin file's plugin id (for the managed-plugin hook exemption); never echoed. */
+    pluginId?: string;
+}
+type Parser = "json" | "json_or_empty" | "jsonc" | "toml";
+export interface ScopeRow {
+    /** Stable row name; reported, and keyed by the per-row fixture table in doctor.test.ts. */
+    name: string;
+    parser: Parser;
+    /** Precedence within the harness: a same-named entry in a higher-ranked row overrides. */
+    rank: number;
+    /**
+     * For a row whose paths walk from cwd up to the git root (cwd first), one file per directory:
+     * which end wins when two of its files name the same server. Absent for a single-path row, and
+     * for a row that already returns its paths in application order (`opencode_project`, which has
+     * two files per directory and must not have them swapped).
+     */
+    walkWins?: "nearest" | "farthest";
+    /** Every candidate file for this row (absent ones are skipped). */
+    paths(ctx: ScopeContext): string[];
+    /** Whether a present file at `path` is loaded by the harness (codex trust). Default: yes. */
+    loaded?(path: string, ctx: ScopeContext): boolean;
+    extract(document: unknown, ctx: ScopeContext): ScopeContribution;
+}
+/** Judge-relevant fields of one entry, from its own fields only. */
+export declare function mcpEntry(name: string, fields: Readonly<Record<string, unknown>>, shape: McpShape): McpEntry;
+/** Directories from `cwd` up to its git root (inclusive); just `cwd` outside a repository. */
+export declare function walkToGitRoot(cwd: string, fs: RegistrationFs): string[];
+/** The frozen, re-checked scope table (see the header for each amendment and its evidence). */
+export declare const HARNESS_CONFIG_SCOPES: Readonly<Record<IdentityHarness, readonly ScopeRow[]>>;
+/**
+ * How a harness combines a same-named entry across its layers (see the header): codex and
+ * opencode overlay the higher layer's fields (measured); claude replaces the whole entry
+ * (inferred); grok is assumed to behave like codex (unmeasured); agy and pi have one layer, so
+ * their value is never used.
+ */
+export declare const MCP_LAYER_MERGE: Readonly<Record<IdentityHarness, "replace" | "fields">>;
+/** Synthetic row names: authored, so no plugin id, marketplace name or path reaches a reason. */
+export declare const CLAUDE_PLUGIN_ROW = "claude_plugin";
+export declare const CLAUDE_FOREIGN_PLUGIN_ROW = "claude_plugin_foreign";
+export type AutoUpdateSource = "env_disabled" | "config_disabled" | "settings" | "known_marketplaces" | "default" | "undetermined";
+/** What doctor learned about OUR plugin. Values are raw; the report sanitises them. */
+export interface ClaudePluginSummary {
+    installed: boolean;
+    /** Our plugin's board server is registered in this cwd (not turned off by `disabledMcpServers`). */
+    serverActive: boolean;
+    version: string | null;
+    pinnedMcpVersion: string | null;
+    sourceRef: string | null;
+    autoUpdate: {
+        effective: boolean;
+        source: AutoUpdateSource;
+    };
+}
+export interface ClaudePluginRead {
+    /** One synthetic file per enabled plugin read, ranked above user settings. */
+    files: ScopeFile[];
+    unparseable: string[];
+    /** An installPath (or a file under it) resolved outside the cache: nothing beyond it was read. */
+    untrusted: boolean;
+    failures: string[];
+    summary: ClaudePluginSummary;
+    hookPolicy: ClaudeHookPolicy;
+}
+/**
+ * Which hooks Claude Code runs (round-2 F027/F028; see the header's `hook policy`): settings
+ * hooks from every scope, from managed settings only, or none; plugin hooks from every plugin,
+ * only from plugins managed settings enable, or none.
+ */
+export interface ClaudeHookPolicy {
+    settings: "all" | "managed_only" | "none";
+    plugins: "all" | "managed_only" | "none";
+    /** Plugin ids managed settings enable (`enabledPlugins[id] === true`), for `managed_only`. */
+    managedPluginIds: ReadonlySet<string>;
+    /** The managed-plugin set comes from somewhere doctor cannot read (managed `prependPlugins`/`appendPlugins`). */
+    unjudgeable: boolean;
+    /**
+     * The managed tier may not be the file doctor reads (round-3 N1): a server-managed or MDM source
+     * replaces the file tier entirely ("first-wins"), and doctor reads neither. True when the probe
+     * found evidence of one, or could not complete.
+     */
+    managedTierUnreadable: boolean;
+    probe: ManagedPolicyProbe;
+}
+export declare const CLAUDE_REMOTE_SETTINGS_FILE = "remote-settings.json";
+/**
+ * Storage-v5 (round 4): the binary writes the server-managed payload to its state store
+ * (`Re.state("remote-settings")`, a `state` namespace in the config home) and a signed-cache
+ * sidecar beside the json path. The store's exact on-disk name is not recoverable from strings,
+ * so every candidate is probed; any one present is evidence.
+ */
+export declare const CLAUDE_REMOTE_SETTINGS_STATE_CANDIDATES: readonly string[];
+export declare const CLAUDE_REMOTE_SETTINGS_SIDECARS: readonly string[];
+export declare const MACOS_MANAGED_PREFERENCES = "/Library/Managed Preferences";
+export declare const MACOS_POLICY_PLIST = "com.anthropic.claudecode.plist";
+export declare const WINDOWS_POLICY_KEYS: Readonly<{
+    hklm: "HKLM\\SOFTWARE\\Policies\\ClaudeCode";
+    hkcu: "HKCU\\SOFTWARE\\Policies\\ClaudeCode";
+}>;
+export declare const WINDOWS_POLICY_VALUE = "Settings";
+/** Where WSL's Windows interop puts reg.exe; the binary reads HKLM policy through this path. */
+export declare const WSL_REG_EXE = "/mnt/c/Windows/System32/reg.exe";
+export declare const WSL_WINDOWS_MANAGED_DIR = "/mnt/c/Program Files/ClaudeCode";
+export type RegQueryOutcome = {
+    kind: "present";
+} | {
+    kind: "absent";
+} | {
+    kind: "error";
+    cause: "reg_unavailable" | "reg_timeout" | "reg_failed";
+};
+/** `reg query <key> /v Settings`, read-only. */
+export type RegQuery = (regExe: string, key: string) => RegQueryOutcome;
+/**
+ * The binary's own query: `reg query <key> /v Settings`, an argv array, no shell, 5 s. Exit 0 →
+ * the value is there; reg's "unable to find" → not there (the binary's own test); anything else —
+ * no reg.exe, a timeout, another failure — is an error, never "absent".
+ */
+export declare function regQueryWith(timeoutMs: number): RegQuery;
+export declare const nodeRegQuery: RegQuery;
+/** What doctor looked at for admin policy: authored source names only. */
+export interface ManagedPolicyProbe {
+    checked: string[];
+    /** Sources that exist: each means a tier doctor cannot read replaces the managed file. */
+    evidence: string[];
+    /** Authored causes of probes that could not finish (`reg_unavailable`, `reg_timeout`, `reg_failed`, `login_unavailable`). */
+    errors: string[];
+    /** The platform has admin sources doctor checks only by presence (macOS, Windows, WSL). */
+    unreadableSourcesPossible: boolean;
+    platformLabel: "Linux" | "macOS" | "Windows" | "WSL";
+}
+export declare function probeManagedPolicy(ctx: ScopeContext): ManagedPolicyProbe;
+/** Evidence of (or an unfinished probe for) a tier that replaces the managed settings FILE. */
+export declare const managedFileTierReplaced: (probe: ManagedPolicyProbe) => boolean;
+/**
+ * IF-0-CCPLUGIN-3: every plugin enabled for `ctx.cwd`, followed from `enabledPlugins` to its
+ * installed row and read from the cache. Ours is the plugin id `agent-board@message-board` whose
+ * marketplace is declared, EVERYWHERE it is declared, as the github repository
+ * Consiliency/message-board; anything else contributing a board server or a wake hook is foreign.
+ */
+export declare function readClaudePluginScopes(ctx: ScopeContext): ClaudePluginRead;
+/** A package spec's identity without its version: `@scope/name@1.2.3` → `@scope/name`. */
+export declare function packageIdentity(spec: string): string;
+interface BoardEntryVerdict {
+    board: boolean;
+    flagged: boolean;
+}
+/** A board MCP entry names `agent-board-mcp` in its command/args, or through ONE user-owned wrapper file. */
+export declare function judgeMcpEntry(entry: McpEntry, fs: RegistrationFs): BoardEntryVerdict;
+export interface RegistrationVerdict {
+    status: "pass" | "fail" | "undetermined";
+    reason: string;
+    /** claude only: what doctor learned about our plugin, for the report and the pin check. */
+    plugin?: ClaudePluginSummary;
+    /** claude only: wake hooks per required event, across settings and plugins. */
+    hookCounts?: Record<(typeof CLAUDE_REQUIRED_HOOK_EVENTS)[number], number>;
+    /** claude only: which admin-policy sources were probed, for the report. */
+    managedPolicy?: ManagedPolicyProbe;
+}
+/**
+ * Read every scope row of `harness` for `cwd`. A file that fails to parse is reported, not guessed.
+ * `files` is in ascending precedence: a later file's same-named entry overrides an earlier one's.
+ */
+export declare function readScopes(harness: IdentityHarness, ctx: ScopeContext): {
+    files: ScopeFile[];
+    unparseable: string[];
+};
+/** The `.claude.json` `projects` key Claude Code uses for `cwd`: the git root of its realpath, else the realpath. */
+export declare function claudeProjectKey(ctx: ScopeContext): string;
+/** IF-0-CREDPATH-4 registration, for one working directory. */
+export declare function judgeRegistration(harness: IdentityHarness, ctx: ScopeContext): RegistrationVerdict;
+export {};