@hydraharness/harness-hooks-registry 0.1.1-rc.10

package/lib/types/index.js

@@ -0,0 +1,482 @@
+/**
+ * User-declared hook records: one settings-backed registry that mounts every
+ * enabled record on its dialect's bridge (`@hydraharness/harness-hooks-claude-code` or
+ * `@hydraharness/harness-hooks-codex`) and unmounts it when the record is disabled,
+ * redefined, or removed. The stored document (`hooks.records` in the harness
+ * settings file) is the only source of truth, so a hook added from a
+ * configuration surface survives a restart and one added by hand-editing that
+ * document mounts without one.
+ *
+ * A record either points at an existing hook document (`configPath`) or carries
+ * its definitions inline. Inline definitions are materialized under the harness
+ * home, because both bridges read one file path at load.
+ * @module @hydraharness/harness-hooks-registry
+ */
+import { mkdir, readFile, rm } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
+import { Service } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+import { writeFileAtomic } from '@hydraharness/harness-atomic-write';
+import { resolveHydraHome } from '@hydraharness/harness-home-paths';
+import { settingsNamespace } from '@hydraharness/harness-settings';
+import { apply as applyClaudeCodeHooks, inject as claudeCodeInject, } from '@hydraharness/harness-hooks-claude-code';
+import { apply as applyCodexHooks, inject as codexInject } from '@hydraharness/harness-hooks-codex';
+import { parseClaudeCodeConfig } from '@hydraharness/harness-hooks-claude-code/config';
+import { parseCodexConfig } from '@hydraharness/harness-hooks-codex/config';
+/** Settings namespace holding every user-declared hook record. */
+export const HOOKS_SETTINGS_NAMESPACE = settingsNamespace('hooks');
+/** Accepted record name. */
+const RECORD_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/u;
+const MAX_RECORDS = 50;
+const MAX_INLINE_BYTES = 256 * 1024;
+const DEFAULT_HOOK_TIMEOUT_MS = 600_000;
+const StoredRecordSchema = z.object({
+    name: z.string().required(),
+    dialect: z.union([z.const('claude-code'), z.const('codex')]).default('claude-code'),
+    configPath: z.string().default(''),
+    // Inline definitions stay opaque to the schema: each dialect owns its own
+    // document grammar, and both parsers already refuse what they cannot run.
+    config: z.dict(z.any()).default({}),
+    pluginRoot: z.string().default(''),
+    projectDir: z.string().default(''),
+    defaultTimeoutMs: z.number().step(1).min(1).default(DEFAULT_HOOK_TIMEOUT_MS),
+    enabled: z.boolean().default(false),
+});
+const HooksSettingsSchema = z.object({
+    records: z.array(StoredRecordSchema).max(MAX_RECORDS).default([]),
+});
+/** Which document source a stored record declares. */
+function sourceKind(record) {
+    return record.configPath === '' ? 'inline' : 'file';
+}
+/**
+ * Reject a definition this registry could not mount. Every check answers a
+ * constraint the schema cannot express: the name grammar, that exactly one
+ * document source is declared, that a path is absolute, and that inline
+ * definitions stay inside the document budget.
+ * @param record - one stored record to judge.
+ * @param label - operation name used in the diagnostic.
+ */
+function assertMountable(record, label, cwd) {
+    if (!RECORD_NAME_PATTERN.test(record.name)) {
+        throw new Error(`${label}: record name must match ${String(RECORD_NAME_PATTERN)}`);
+    }
+    const inline = Object.keys(record.config).length > 0;
+    if (record.configPath === '' && !inline) {
+        throw new Error(`${label}: record ${record.name} needs either a configPath or inline hook definitions`);
+    }
+    if (record.configPath !== '' && inline) {
+        throw new Error(`${label}: record ${record.name} declares both a configPath and inline hook definitions`);
+    }
+    if (record.configPath !== '' && !isAbsolute(record.configPath) && cwd === undefined) {
+        throw new Error(`${label}: record ${record.name} configPath must be absolute`);
+    }
+    if (inline && Buffer.byteLength(JSON.stringify(record.config), 'utf8') > MAX_INLINE_BYTES) {
+        throw new Error(`${label}: record ${record.name} inline hooks exceed ${String(MAX_INLINE_BYTES)} bytes`);
+    }
+    if (record.dialect === 'codex' && (record.pluginRoot !== '' || record.projectDir !== '')) {
+        throw new Error(`${label}: record ${record.name} substitution roots apply to claude-code records only`);
+    }
+}
+/** Reject a stored section whose records collide, so no mount silently wins. */
+function assertUniqueNames(settings) {
+    const seen = new Set();
+    for (const record of settings.records) {
+        if (seen.has(record.name)) {
+            throw new Error(`hookRecords: record name ${JSON.stringify(record.name)} is declared more than once`);
+        }
+        seen.add(record.name);
+    }
+}
+/**
+ * Parse one document with its dialect's parser, so what the registry reports is
+ * exactly what the bridge will run.
+ * @param dialect - the record's config dialect.
+ * @param raw - parsed JSON document.
+ * @returns the event names covered and the total command-hook count.
+ */
+function summarize(dialect, raw) {
+    const parsed = dialect === 'claude-code' ? parseClaudeCodeConfig(raw) : parseCodexConfig(raw);
+    const events = Object.keys(parsed.config).sort();
+    let hookCount = 0;
+    for (const groups of Object.values(parsed.config)) {
+        for (const group of groups)
+            hookCount += group.hooks.length;
+    }
+    if (hookCount === 0)
+        throw new Error(`hookRecords: ${dialect} document contains no supported synchronous command hooks`);
+    return { events, hookCount };
+}
+/**
+ * Fold one write request onto the record it replaces. Every field is restated
+ * by the caller: unlike a credential, nothing here is withheld from a read, so
+ * an omission is a deliberate clear.
+ * @param request - complete definition supplied by the caller.
+ * @param previous - the record being replaced, when one exists.
+ * @returns the next stored record.
+ */
+function foldDefinition(request, previous) {
+    return {
+        name: request.name.trim(),
+        dialect: request.dialect,
+        configPath: (request.configPath ?? '').trim(),
+        config: { ...request.config },
+        pluginRoot: (request.pluginRoot ?? '').trim(),
+        projectDir: (request.projectDir ?? '').trim(),
+        defaultTimeoutMs: request.defaultTimeoutMs ?? previous?.defaultTimeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS,
+        enabled: request.enabled ?? previous?.enabled ?? false,
+    };
+}
+/** Services required by the registry; the bridges themselves need `shell`. */
+export const inject = ['settings', 'shell'];
+/**
+ * Settings-backed hook records with their live bridge mounts. Reconciliation is
+ * idempotent and runs on one serialized chain, so a document commit from any
+ * source — this service's own write, another process, or a hand edit —
+ * converges the mounted set on the stored one.
+ * Mutations reject with `SettingsConflictError` if another writer changes the
+ * stored section after the read; retry uses the refreshed projection.
+ */
+export class HookRecordRegistry extends Service {
+    static inject = inject;
+    /** Bridge mounts belong to this Host service, not to a traced API caller. */
+    owner;
+    static Config = z.object({
+        hydraHome: z.string(),
+        cwd: z.string(),
+    });
+    settings;
+    live = new Map();
+    /** Stored records this registry refuses to mount, with the refusal reason. */
+    invalid = new Map();
+    /** Directory holding the documents materialized from inline definitions. */
+    inlineRoot;
+    cwd;
+    tail = Promise.resolve();
+    stopped = false;
+    constructor(ctx, config = {}) {
+        super(ctx, 'hookRecords');
+        if (config.cwd !== undefined && !isAbsolute(config.cwd))
+            throw new Error('hookRecords: cwd must be absolute');
+        this.owner = ctx;
+        this.cwd = config.cwd;
+        this.inlineRoot = join(resolveHydraHome(config.hydraHome), 'hooks');
+        this.settings = ctx.settings.register(HOOKS_SETTINGS_NAMESPACE, HooksSettingsSchema, {
+            // Refuse a colliding section where it is written: two records claiming
+            // one name would make which definitions run depend on mount order.
+            validate: assertUniqueNames,
+        });
+    }
+    async [Service.init]() {
+        this.ctx.inject(['optionalPlugins'], (pctx) => {
+            pctx.effect(() => pctx.optionalPlugins.subscribe((enabled) => {
+                void this.enqueue(async () => {
+                    if (!enabled)
+                        await pctx.optionalPlugins.drain();
+                    if (pctx.optionalPlugins.enabled === enabled)
+                        await this.reconcile();
+                }).catch((error) => { this.ctx.logger.error(error); });
+            }), 'hooks-registry: optional policy');
+        });
+        this.ctx.effect(() => () => this.shutdown(), 'hookRecords.dispose');
+        this.ctx.effect(() => this.settings.watch(() => this.enqueue(() => this.reconcile())), 'hookRecords.settingsWatch');
+        await this.enqueue(() => this.reconcile());
+    }
+    /**
+     * Project every stored record with its live state.
+     * @param settings - optional layer whose desired records to project.
+     * @returns the current record projection, in stored order.
+     */
+    list(settings) {
+        const records = settings === undefined ? this.settings.get().records : this.writeSource(settings).records;
+        return { records: records.map(record => this.view(record)) };
+    }
+    /**
+     * Reconcile the current effective settings after a layer or trust change.
+     * @returns completion after earlier queued work and the current mounts settle.
+     */
+    settle() {
+        return this.enqueue(() => this.reconcile());
+    }
+    /**
+     * Create or replace one complete definition as requested, then
+     * converge the mounted set. A definition this registry could not mount is
+     * refused before anything persists.
+     * @param request - complete record definition.
+     * @param settings - selected write layer; omitted uses this registry's provider.
+     * @returns the refreshed projection.
+     * @throws If create names an existing record or replace names a missing record.
+     */
+    define(request, settings = this.owner.settings) {
+        return this.enqueue(async () => {
+            const { revision, records } = this.writeSource(settings);
+            const index = records.findIndex(candidate => candidate.name === request.name.trim());
+            if (request.mode === 'create' && index !== -1)
+                throw new Error(`hookRecords.define: record ${request.name} already exists`);
+            if (request.mode === 'replace' && index === -1)
+                throw new Error(`hookRecords.define: record ${request.name} is not configured`);
+            const record = foldDefinition(request, index === -1 ? undefined : records[index]);
+            assertMountable(record, 'hookRecords.define', this.cwd);
+            // The dialect parser is the authority on whether these definitions run;
+            // refusing here means a stored record can never be silently inert.
+            summarize(record.dialect, await this.readDefinitions(record));
+            const next = index === -1
+                ? [...records, record]
+                : records.map((candidate, position) => position === index ? record : candidate);
+            if (next.length > MAX_RECORDS)
+                throw new Error(`hookRecords.define: at most ${String(MAX_RECORDS)} records are supported`);
+            await settings.update(HOOKS_SETTINGS_NAMESPACE, { records: next }, revision);
+            await this.reconcile();
+            return this.list();
+        });
+    }
+    /**
+     * Change one stored record's desired state.
+     * @param request - target record and desired state.
+     * @param settings - selected write layer; omitted uses this registry's provider.
+     * @returns the refreshed projection.
+     */
+    setEnabled(request, settings = this.owner.settings) {
+        return this.enqueue(async () => {
+            const { revision, records } = this.writeSource(settings);
+            const index = records.findIndex(candidate => candidate.name === request.name);
+            if (index === -1)
+                throw new Error(`hookRecords.setEnabled: record ${request.name} is not configured`);
+            const next = records.map((candidate, position) => position === index
+                ? { ...candidate, enabled: request.enabled }
+                : candidate);
+            await settings.update(HOOKS_SETTINGS_NAMESPACE, { records: next }, revision);
+            await this.reconcile();
+            return this.list();
+        });
+    }
+    /**
+     * Remove one stored record, unmount it, and delete any document this registry
+     * materialized for it.
+     * @param name - stored record name.
+     * @param settings - selected write layer; omitted uses this registry's provider.
+     * @returns the refreshed projection.
+     */
+    remove(name, settings = this.owner.settings) {
+        return this.enqueue(async () => {
+            const { revision, records } = this.writeSource(settings);
+            if (!records.some(candidate => candidate.name === name)) {
+                throw new Error(`hookRecords.remove: record ${name} is not configured`);
+            }
+            await settings.replace(HOOKS_SETTINGS_NAMESPACE, { records: records.filter(candidate => candidate.name !== name) }, revision);
+            await this.reconcile();
+            if (!this.settings.get().records.some(record => record.name === name)) {
+                await rm(this.inlinePath(name), { force: true });
+            }
+            return this.list();
+        });
+    }
+    /** Read the selected layer's desired records, including overrides suppressed by trust. */
+    writeSource(settings) {
+        const descriptor = settings.describe().find(section => section.ns === HOOKS_SETTINGS_NAMESPACE);
+        if (descriptor === undefined)
+            throw new Error('hookRecords: selected settings provider has no hooks namespace');
+        return {
+            ...HooksSettingsSchema({
+                records: descriptor.user?.records
+                    ?? descriptor.base?.records ?? [],
+            }),
+            revision: descriptor.revision,
+        };
+    }
+    /* jscpd:ignore-start -- hook and MCP registries intentionally share serialized reconciliation. */
+    /** Serialize every mutation and reconciliation on one chain. */
+    enqueue(task) {
+        const run = this.tail.then(task, task);
+        this.tail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /**
+     * Converge the mounted set on the stored one: unmount every record that is
+     * gone, disabled, or redefined, then mount every enabled record that is not
+     * already live from the same definition. A record whose document is missing,
+     * unparseable, or refused by its dialect is recorded as `invalid` with the
+     * diagnostic and does not stop the others.
+     */
+    async reconcile() {
+        if (this.stopped)
+            return;
+        const records = new Map(this.settings.get().records.map(record => [record.name, record]));
+        this.invalid.clear();
+        for (const [name, mount] of [...this.live]) {
+            const record = records.get(name);
+            if (this.ctx.get('optionalPlugins')?.enabled !== false && record?.enabled === true && recordDigest(record) === mount.digest)
+                continue;
+            this.live.delete(name);
+            await disposeQuietly(mount.fiber);
+        }
+        for (const record of records.values()) {
+            if (this.ctx.get('optionalPlugins')?.enabled === false || !record.enabled || this.live.has(record.name))
+                continue;
+            await this.mount(record);
+        }
+        // The projection is published only after every mount settled, so an
+        // observer cannot read a record whose bridge is still loading.
+        this.ctx.emit('hooks-registry/reconciled', this.list());
+    }
+    /* jscpd:ignore-end */
+    /**
+     * Materialize the record's document when it is inline, then start its
+     * dialect's bridge. A refusal is stored as `invalid` rather than thrown: a
+     * hand-edited document must not stop every other record from mounting.
+     */
+    async mount(record) {
+        let configPath;
+        let summary;
+        try {
+            assertMountable(record, 'hookRecords', this.cwd);
+            configPath = await this.materialize(record);
+            summary = summarize(record.dialect, await this.readDefinitions(record));
+        }
+        catch (error) {
+            /* v8 ignore next -- validation, JSON parsing, and local filesystem operations throw Error instances. */
+            this.invalid.set(record.name, error instanceof Error ? error.message : String(error));
+            return;
+        }
+        const fiber = record.dialect === 'claude-code'
+            ? this.owner.plugin({
+                name: `hook-record:${record.name}`,
+                inject: claudeCodeInject,
+                apply: applyClaudeCodeHooks,
+            }, {
+                configPath,
+                defaultTimeoutMs: record.defaultTimeoutMs,
+                ...this.cwd === undefined ? {} : { cwd: this.cwd },
+                ...record.pluginRoot === '' ? {} : { pluginRoot: this.documentPath(record.pluginRoot) },
+                ...record.projectDir === '' ? {} : { projectDir: this.documentPath(record.projectDir) },
+            })
+            : this.owner.plugin({
+                name: `hook-record:${record.name}`,
+                inject: codexInject,
+                apply: applyCodexHooks,
+            }, {
+                configPath,
+                defaultTimeoutMs: record.defaultTimeoutMs,
+                ...this.cwd === undefined ? {} : { cwd: this.cwd },
+            });
+        const mount = {
+            fiber,
+            digest: recordDigest(record),
+            events: summary.events,
+            hookCount: summary.hookCount,
+            status: 'started',
+        };
+        this.live.set(record.name, mount);
+        try {
+            await fiber;
+        }
+        catch (error) {
+            mount.status = 'failed';
+            /* v8 ignore next -- Cordis normalizes plugin failures to Error before fiber.await rejects. */
+            mount.detail = error instanceof Error ? error.message : String(error);
+        }
+    }
+    /**
+     * Resolve the document path the bridge reads: a `file` record's own path, or
+     * the harness-home document this registry writes from inline definitions.
+     * Materialization is idempotent and re-runs per mount, so an edited inline
+     * section always reaches the bridge.
+     */
+    async materialize(record) {
+        if (sourceKind(record) === 'file')
+            return this.documentPath(record.configPath);
+        const path = this.inlinePath(record.name);
+        await mkdir(this.inlineRoot, { recursive: true, mode: 0o700 });
+        await writeFileAtomic(path, `${JSON.stringify(record.config, undefined, 2)}\n`, { mode: 0o600, dirMode: 0o700 });
+        return path;
+    }
+    /** Read one record's raw definitions, from its file or its inline section. */
+    async readDefinitions(record) {
+        if (sourceKind(record) === 'inline')
+            return record.config;
+        let text;
+        try {
+            text = await readFile(this.documentPath(record.configPath), 'utf8');
+        }
+        catch (cause) {
+            throw new Error(`hookRecords: record ${record.name} cannot read ${record.configPath}`, { cause });
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch (cause) {
+            throw new Error(`hookRecords: record ${record.name} document is not valid JSON`, { cause });
+        }
+    }
+    /** Path of the document this registry materializes for one inline record. */
+    inlinePath(name) {
+        return join(this.inlineRoot, `${name}.json`);
+    }
+    /** Resolve a read-only document or substitution path inside the owning cwd. */
+    documentPath(path) {
+        return this.cwd === undefined ? path : resolve(this.cwd, path);
+    }
+    /** Project one stored record with its live state. */
+    view(record) {
+        const candidate = this.live.get(record.name);
+        const digest = recordDigest(record);
+        const mount = candidate?.digest === digest ? candidate : undefined;
+        const effective = this.settings.get().records.find(hook => hook.name === record.name);
+        const invalid = effective !== undefined && recordDigest(effective) === digest ? this.invalid.get(record.name) : undefined;
+        const status = invalid !== undefined
+            ? 'invalid'
+            : !record.enabled ? 'stopped' : mount?.status ?? 'stopped';
+        const detail = invalid ?? mount?.detail;
+        return {
+            name: record.name,
+            dialect: record.dialect,
+            source: sourceKind(record),
+            enabled: record.enabled,
+            status,
+            ...detail === undefined || status === 'stopped' ? {} : { detail },
+            ...sourceKind(record) === 'file' ? { configPath: record.configPath } : {},
+            events: mount?.events ?? [],
+            hookCount: mount?.hookCount ?? 0,
+            ...record.pluginRoot === '' ? {} : { pluginRoot: record.pluginRoot },
+            ...record.projectDir === '' ? {} : { projectDir: record.projectDir },
+        };
+    }
+    /* jscpd:ignore-start -- hook and MCP shutdowns intentionally share teardown semantics. */
+    /** Refuse new work, then unmount every live record. */
+    async shutdown() {
+        this.stopped = true;
+        /* v8 ignore next -- enqueue stores a fulfilled tail after either task outcome. */
+        await this.tail.catch(() => undefined);
+        this.invalid.clear();
+        for (const [name, mount] of [...this.live]) {
+            this.live.delete(name);
+            await disposeQuietly(mount.fiber);
+        }
+    }
+}
+/**
+ * Digest of everything a mount is started from, so reconciliation can tell a
+ * redefined record from an untouched one without restarting a live bridge on
+ * every unrelated document commit. The desired state is excluded: enablement is
+ * handled by mount and unmount, not by a restart.
+ */
+function recordDigest(record) {
+    const { enabled: _desired, ...definition } = record;
+    return JSON.stringify(definition);
+}
+/**
+ * Unmount one bridge and swallow its teardown failure. The record it served is
+ * already out of the live map, so a disposal error cannot restore it, and
+ * letting it escape would strand every later record in the same reconcile.
+ * @param fiber - the mount to tear down.
+ */
+async function disposeQuietly(fiber) {
+    try {
+        await fiber.dispose();
+    }
+    catch (_hookMountTeardownFailure) {
+        // The fiber is inactive either way; nothing here can act on the failure.
+    }
+}
+export default HookRecordRegistry;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-hooks-registry`.
+ * @module @hydraharness/harness-hooks-registry/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "hooks-registry-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,34 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-hooks-registry`.
+ * @module @hydraharness/harness-hooks-registry/invariant
+ */
+const PACKAGE_NAME = '@hydraharness/harness-hooks-registry';
+/** Cordis companion plugin name. */
+export const name = 'hooks-registry-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * The registry's contract is that the mounted bridge set follows the stored
+ * records once reconciliation settles: an enabled record it accepted is live,
+ * and a disabled one is not. Both sides ride the reconciliation event, so the
+ * check observes the authoritative projection rather than re-deriving it.
+ */
+const install = (ctx, fail) => {
+    ctx.on('hooks-registry/reconciled', (snapshot) => {
+        for (const record of snapshot.records) {
+            if (record.enabled && record.status === 'stopped') {
+                fail(`enabled hook record ${JSON.stringify(record.name)} has no live bridge after reconciliation`);
+            }
+            if (!record.enabled && record.status !== 'stopped') {
+                fail(`disabled hook record ${JSON.stringify(record.name)} still reports ${record.status}`);
+            }
+        }
+    });
+};
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,89 @@
+/** Public types for the user-declared hook registry. */
+import type { JsonValue } from '@hydraharness/harness-session/types';
+/** Hook config dialect a record is written in, selecting its bridge. */
+export type HookDialect = 'claude-code' | 'codex';
+/** Where a record's hook definitions come from. */
+export type HookSourceKind = 'file' | 'inline';
+/**
+ * Live state of one stored record. `invalid` is a stored record this registry
+ * refuses to mount — an unreadable path, an unparseable document, or a
+ * definition the dialect rejects — never a hook execution failure.
+ */
+export type HookRecordStatus = 'stopped' | 'started' | 'failed' | 'invalid';
+/** One stored hook record as a configuration surface sees it. */
+export interface HookRecordView {
+    readonly name: string;
+    readonly dialect: HookDialect;
+    readonly source: HookSourceKind;
+    /** Desired state stored in the document, independent of {@link status}. */
+    readonly enabled: boolean;
+    readonly status: HookRecordStatus;
+    /** Why a record is `invalid`, or the mount failure summary. */
+    readonly detail?: string;
+    /** Absolute document path of a `file` record. */
+    readonly configPath?: string;
+    /**
+     * Event names the mounted definitions cover, in dialect spelling. Empty until
+     * the record's definitions are read, and for a record this registry refuses.
+     */
+    readonly events: readonly string[];
+    /** How many command hooks the definitions declare across every event. */
+    readonly hookCount: number;
+    /** Substitution root a `claude-code` record supplies for `${CLAUDE_PLUGIN_ROOT}`. */
+    readonly pluginRoot?: string;
+    /** Substitution root a `claude-code` record supplies for `${CLAUDE_PROJECT_DIR}`. */
+    readonly projectDir?: string;
+}
+/** Complete immutable projection returned by every registry operation. */
+export interface HookRecordSnapshot {
+    readonly records: readonly HookRecordView[];
+}
+/**
+ * Complete definition of one hook record. A write replaces the named record
+ * wholesale, so an omitted optional field clears the stored one. Exactly one of
+ * `configPath` and `config` must be supplied.
+ */
+export interface HookRecordDefinitionRequest {
+    /** Create requires an unused name; replace requires an existing record. */
+    readonly mode: 'create' | 'replace';
+    /** Stable record name; `[A-Za-z0-9_-]{1,64}`. */
+    readonly name: string;
+    readonly dialect: HookDialect;
+    /** Absolute path to an existing hook document the harness reads as-is. */
+    readonly configPath?: string;
+    /**
+     * Hook definitions stored inline in the settings document: either a bare
+     * event map or a `{ hooks: … }` wrapper, in the record's dialect. The registry
+     * materializes them into a file for the bridge to read. Each dialect owns its
+     * own document grammar, so the values stay lossless JSON rather than a shape
+     * this package restates.
+     */
+    readonly config?: Readonly<Record<string, JsonValue>>;
+    /** Replaces `${CLAUDE_PLUGIN_ROOT}` in `claude-code` commands. */
+    readonly pluginRoot?: string;
+    /** Replaces `${CLAUDE_PROJECT_DIR}` in `claude-code` commands and env. */
+    readonly projectDir?: string;
+    /** Default per-hook timeout in milliseconds when a hook declares none. */
+    readonly defaultTimeoutMs?: number;
+    /** Desired state; a new record defaults to disabled. */
+    readonly enabled?: boolean;
+}
+/** Change one stored record's desired state without touching its definition. */
+export interface HookRecordEnablementRequest {
+    readonly name: string;
+    readonly enabled: boolean;
+}
+declare module '@hydraharness/cordis' {
+    interface Events {
+        /**
+         * The mounted bridge set now matches the stored records. Emitted after each
+         * reconciliation settles — including the one at startup and the ones a
+         * document change triggers — so an observer never reads the projection
+         * between a committed record change and the mount that follows it.
+         * @param snapshot - the projection as of this reconciliation.
+         * @mode emit
+         */
+        'hooks-registry/reconciled'(snapshot: HookRecordSnapshot): void;
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,3 @@
+/** Public types for the user-declared hook registry. */
+export {};
+//# sourceMappingURL=types.js.map