@pellux/goodvibes-sdk 0.18.13 → 0.18.15

package/dist/_internal/platform/hooks/runners/agent.js

@@ -0,0 +1,76 @@
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+/**
+ * Agent hook runner — spawns a subagent via AgentManager and waits for
+ * completion up to the hook's configured timeout.
+ *
+ * The hook's `prompt` field (with `$ARGUMENTS` replaced by the event JSON)
+ * becomes the agent task description.
+ *
+ * Since AgentManager currently registers agents synchronously and doesn't
+ * execute them in a true background thread, the hook marks the agent as
+ * completed immediately and returns a success result.  When real background
+ * execution is wired the status polling loop below will take effect.
+ */
+export async function run(hook, event, manager) {
+    const promptTemplate = hook.prompt;
+    if (promptTemplate == null) {
+        return { ok: false, error: 'agent hook missing "prompt" field' };
+    }
+    const task = promptTemplate.replaceAll('$ARGUMENTS', JSON.stringify(event));
+    const timeoutMs = (hook.timeout ?? 60) * 1000;
+    logger.debug('agent hook: spawning agent', {
+        event: event.path,
+        timeoutMs,
+    });
+    let record;
+    try {
+        record = manager.spawn({
+            mode: 'spawn',
+            task,
+            template: 'general',
+            model: hook.model,
+        });
+    }
+    catch (err) {
+        const message = summarizeError(err);
+        logger.error('agent hook: spawn failed', { event: event.path, error: message });
+        return { ok: false, error: `agent spawn failed: ${message}` };
+    }
+    const agentId = record.id;
+    logger.debug('agent hook: agent spawned', { agentId, event: event.path });
+    // Poll for agent completion up to timeoutMs.
+    // Currently AgentManager doesn't execute agents in the background, so after
+    // spawning the agent is in 'pending' state and this loop will time out unless
+    // the record is manually advanced.  When real execution is wired, this loop
+    // will catch the completion/failure transition.
+    const pollInterval = 100; // ms
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const current = manager.getStatus(agentId);
+        if (!current) {
+            return { ok: false, error: `agent ${agentId} disappeared from registry` };
+        }
+        if (current.status === 'completed') {
+            logger.debug('agent hook: agent completed', { agentId });
+            return {
+                ok: true,
+                additionalContext: current.progress,
+            };
+        }
+        if (current.status === 'failed') {
+            logger.error('agent hook: agent failed', { agentId, error: current.error });
+            return { ok: false, error: current.error ?? 'agent failed without error message' };
+        }
+        if (current.status === 'cancelled') {
+            return { ok: false, error: `agent ${agentId} was cancelled before completing` };
+        }
+        // Agent still pending/running — wait a tick
+        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+    // Timed out — cancel the agent and return error
+    manager.cancel(agentId);
+    const timeoutSecs = hook.timeout ?? 60;
+    logger.error('agent hook: timed out', { agentId, timeoutSecs });
+    return { ok: false, error: `agent hook timed out after ${timeoutSecs}s (agentId: ${agentId})` };
+}

package/dist/_internal/platform/hooks/runners/prompt.d.ts

@@ -0,0 +1,13 @@
+import type { HookDefinition, HookResult, HookEvent } from '@pellux/goodvibes-sdk/platform/hooks/types';
+import type { ToolLLM } from '../../config/tool-llm.js';
+/**
+ * Prompt hook runner — sends event data to an LLM via ToolLLM.
+ *
+ * The hook definition's `prompt` field is a template string.
+ * `$ARGUMENTS` is replaced with the JSON-serialised event before
+ * the prompt is sent.  The LLM response is parsed as a HookResult
+ * JSON object.  If the response is not valid JSON (or is empty)
+ * the hook returns `{ ok: true }` (fire-and-forget semantics).
+ */
+export declare function run(hook: HookDefinition, event: HookEvent, toolLLM: Pick<ToolLLM, 'chat'> | null): Promise<HookResult>;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/_internal/platform/hooks/runners/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/hooks/runners/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,4CAA4C,CAAC;AAExG,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAGxD;;;;;;;;GAQG;AACH,wBAAsB,GAAG,CACvB,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,IAAI,GACpC,OAAO,CAAC,UAAU,CAAC,CAkDrB"}

package/dist/_internal/platform/hooks/runners/prompt.js

@@ -0,0 +1,58 @@
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+/**
+ * Prompt hook runner — sends event data to an LLM via ToolLLM.
+ *
+ * The hook definition's `prompt` field is a template string.
+ * `$ARGUMENTS` is replaced with the JSON-serialised event before
+ * the prompt is sent.  The LLM response is parsed as a HookResult
+ * JSON object.  If the response is not valid JSON (or is empty)
+ * the hook returns `{ ok: true }` (fire-and-forget semantics).
+ */
+export async function run(hook, event, toolLLM) {
+    if (!toolLLM) {
+        return { ok: false, error: 'prompt hook runner is not configured in this runtime' };
+    }
+    const promptTemplate = hook.prompt;
+    if (!promptTemplate) {
+        return { ok: false, error: 'prompt hook missing "prompt" field' };
+    }
+    const resolvedPrompt = promptTemplate.replaceAll('$ARGUMENTS', JSON.stringify(event));
+    const timeoutMs = (hook.timeout ?? 30) * 1000;
+    logger.debug('prompt hook: sending to LLM', {
+        event: event.path,
+        timeoutMs,
+    });
+    let timerId;
+    try {
+        const timeoutPromise = new Promise((_resolve, reject) => {
+            timerId = setTimeout(() => {
+                reject(new Error(`prompt hook timed out after ${hook.timeout ?? 30}s`));
+            }, timeoutMs);
+        });
+        let response;
+        try {
+            response = await Promise.race([toolLLM.chat(resolvedPrompt), timeoutPromise]);
+        }
+        finally {
+            clearTimeout(timerId);
+        }
+        const trimmed = response.trim();
+        if (!trimmed) {
+            return { ok: true };
+        }
+        try {
+            const result = JSON.parse(trimmed);
+            return { ...result, ok: result.ok ?? true };
+        }
+        catch {
+            // Non-JSON LLM output — fire-and-forget semantics
+            return { ok: true };
+        }
+    }
+    catch (err) {
+        const message = summarizeError(err);
+        logger.error('prompt hook error', { event: event.path, error: message });
+        return { ok: false, error: message };
+    }
+}

package/dist/_internal/platform/hooks/workbench.d.ts

@@ -0,0 +1,67 @@
+import type { HookDispatcher } from './dispatcher.js';
+import type { HookChain, HookDefinition, HookType, HooksConfig } from '@pellux/goodvibes-sdk/platform/hooks/types';
+import type { ConfigManager } from '../config/manager.js';
+export interface HookAuthoringAction {
+    readonly kind: 'load' | 'save' | 'reload' | 'scaffold-hook' | 'scaffold-chain' | 'remove' | 'toggle' | 'simulate' | 'export' | 'import' | 'inspect';
+    readonly target: string;
+    readonly timestamp: number;
+    readonly detail?: string;
+}
+export interface HookSimulationResult {
+    readonly eventPath: string;
+    readonly matchedHooks: readonly {
+        readonly pattern: string;
+        readonly name: string;
+        readonly type: HookType;
+        readonly contract: string;
+    }[];
+    readonly matchedChains: readonly {
+        readonly name: string;
+        readonly stepMatches: number;
+    }[];
+    readonly capturedAt: number;
+}
+export interface HookConfigInspection {
+    readonly path: string;
+    readonly hookCount: number;
+    readonly chainCount: number;
+    readonly patterns: readonly string[];
+}
+export interface HookWorkbenchOptions {
+    readonly hookDispatcher: Pick<HookDispatcher, 'clear' | 'loadFromFile'>;
+    readonly configManager: Pick<ConfigManager, 'get' | 'getWorkingDirectory'>;
+    readonly hooksFilePathResolver?: () => string;
+}
+export declare class HookWorkbench {
+    private readonly hookDispatcher;
+    private readonly hooksFilePathResolver;
+    private managedConfig;
+    private recentActions;
+    private lastSimulation;
+    private lastLoadedPath;
+    constructor(hookDispatcher: Pick<HookDispatcher, 'clear' | 'loadFromFile'>, hooksFilePathResolver: () => string);
+    getHooksFilePath(): string;
+    getManagedConfig(): HooksConfig;
+    listManagedHooks(): Array<{
+        pattern: string;
+        hook: HookDefinition;
+    }>;
+    listManagedChains(): HookChain[];
+    listRecentActions(limit?: number): HookAuthoringAction[];
+    getLastSimulation(): HookSimulationResult | null;
+    private recordAction;
+    loadManagedConfig(path?: string): HooksConfig;
+    saveManagedConfig(path?: string): Promise<void>;
+    loadAndApplyManagedHooks(path?: string): Promise<void>;
+    scaffoldHook(name: string, match: string, type: HookType): HookDefinition;
+    scaffoldChain(name: string, matches: readonly string[]): HookChain;
+    removeManagedEntry(name: string): boolean;
+    toggleManagedHook(name: string, enabled: boolean): boolean;
+    exportManagedConfig(path: string): Promise<string>;
+    inspectManagedConfig(path: string): HookConfigInspection;
+    importManagedConfig(path: string, strategy?: 'merge' | 'replace'): HooksConfig;
+    simulate(eventPath: string, payload?: Record<string, unknown>): HookSimulationResult;
+    clear(): void;
+}
+export declare function createHookWorkbench(options: HookWorkbenchOptions): HookWorkbench;
+//# sourceMappingURL=workbench.d.ts.map

package/dist/_internal/platform/hooks/workbench.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbench.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/hooks/workbench.ts"],"names":[],"mappings":"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"}

package/dist/_internal/platform/hooks/workbench.js

@@ -0,0 +1,301 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import { getHookPointContract } from '@pellux/goodvibes-sdk/platform/hooks/contracts';
+import { matchesEventPath, matchesMatcher } from '@pellux/goodvibes-sdk/platform/hooks/matcher';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+const EMPTY_CONFIG = Object.freeze({ hooks: {}, chains: [] });
+function cloneConfig(config) {
+    return {
+        hooks: Object.fromEntries(Object.entries(config.hooks ?? {}).map(([pattern, defs]) => [pattern, defs.map((def) => ({ ...def }))])),
+        chains: (config.chains ?? []).map((chain) => ({
+            ...chain,
+            steps: chain.steps.map((step) => ({ ...step })),
+            action: { ...chain.action },
+        })),
+    };
+}
+function ensureConfigShape(parsed) {
+    if (!parsed || typeof parsed !== 'object')
+        return cloneConfig(EMPTY_CONFIG);
+    const candidate = parsed;
+    return {
+        hooks: candidate.hooks && typeof candidate.hooks === 'object' ? candidate.hooks : {},
+        chains: Array.isArray(candidate.chains) ? candidate.chains : [],
+    };
+}
+export class HookWorkbench {
+    hookDispatcher;
+    hooksFilePathResolver;
+    managedConfig = cloneConfig(EMPTY_CONFIG);
+    recentActions = [];
+    lastSimulation = null;
+    lastLoadedPath = null;
+    constructor(hookDispatcher, hooksFilePathResolver) {
+        this.hookDispatcher = hookDispatcher;
+        this.hooksFilePathResolver = hooksFilePathResolver;
+    }
+    getHooksFilePath() {
+        return this.hooksFilePathResolver();
+    }
+    getManagedConfig() {
+        return cloneConfig(this.managedConfig);
+    }
+    listManagedHooks() {
+        const entries = [];
+        for (const [pattern, defs] of Object.entries(this.managedConfig.hooks ?? {})) {
+            for (const hook of defs)
+                entries.push({ pattern, hook: { ...hook } });
+        }
+        return entries;
+    }
+    listManagedChains() {
+        return (this.managedConfig.chains ?? []).map((chain) => ({
+            ...chain,
+            steps: chain.steps.map((step) => ({ ...step })),
+            action: { ...chain.action },
+        }));
+    }
+    listRecentActions(limit = 8) {
+        return this.recentActions.slice(0, limit);
+    }
+    getLastSimulation() {
+        return this.lastSimulation;
+    }
+    recordAction(action) {
+        this.recentActions.unshift(action);
+        if (this.recentActions.length > 25)
+            this.recentActions.length = 25;
+    }
+    loadManagedConfig(path = this.getHooksFilePath()) {
+        this.lastLoadedPath = path;
+        if (!existsSync(path)) {
+            this.managedConfig = cloneConfig(EMPTY_CONFIG);
+            this.recordAction({ kind: 'load', target: path, timestamp: Date.now(), detail: 'empty config' });
+            return this.getManagedConfig();
+        }
+        try {
+            const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+            this.managedConfig = ensureConfigShape(parsed);
+            this.recordAction({ kind: 'load', target: path, timestamp: Date.now(), detail: `${this.listManagedHooks().length} hooks / ${this.listManagedChains().length} chains` });
+        }
+        catch (error) {
+            logger.debug('HookWorkbench.loadManagedConfig failed, using empty config', { path, error: summarizeError(error) });
+            this.managedConfig = cloneConfig(EMPTY_CONFIG);
+            this.recordAction({ kind: 'load', target: path, timestamp: Date.now(), detail: 'invalid JSON; using empty config' });
+        }
+        return this.getManagedConfig();
+    }
+    async saveManagedConfig(path = this.lastLoadedPath ?? this.getHooksFilePath()) {
+        mkdirSync(dirname(path), { recursive: true });
+        await writeFile(path, `${JSON.stringify(this.managedConfig, null, 2)}\n`, 'utf-8');
+        this.lastLoadedPath = path;
+        this.recordAction({ kind: 'save', target: path, timestamp: Date.now(), detail: `${this.listManagedHooks().length} hooks / ${this.listManagedChains().length} chains` });
+    }
+    async loadAndApplyManagedHooks(path = this.getHooksFilePath()) {
+        this.loadManagedConfig(path);
+        this.hookDispatcher.clear();
+        this.hookDispatcher.loadFromFile(path);
+        this.recordAction({ kind: 'reload', target: path, timestamp: Date.now(), detail: 'dispatcher refreshed' });
+    }
+    scaffoldHook(name, match, type) {
+        const hook = {
+            name,
+            match,
+            type,
+            enabled: false,
+            description: `Managed hook scaffold for ${match}`,
+            ...(type === 'command' ? { command: 'echo implement-hook' } : {}),
+            ...(type === 'prompt' ? { prompt: 'Return a HookResult JSON object for $ARGUMENTS.' } : {}),
+            ...(type === 'http' ? { url: 'http://localhost:3000/hooks' } : {}),
+            ...(type === 'ts' ? { path: './hooks/handler.ts' } : {}),
+            ...(type === 'agent' ? { prompt: 'Handle this hook event: $ARGUMENTS' } : {}),
+        };
+        const config = cloneConfig(this.managedConfig);
+        config.hooks ??= {};
+        config.hooks[match] ??= [];
+        config.hooks[match].push(hook);
+        this.managedConfig = config;
+        this.recordAction({ kind: 'scaffold-hook', target: name, timestamp: Date.now(), detail: `${type} ${match}` });
+        return hook;
+    }
+    scaffoldChain(name, matches) {
+        const chain = {
+            name,
+            description: `Managed hook workflow for ${matches.join(' -> ')}`,
+            steps: matches.map((match) => ({ match })),
+            action: {
+                name: `${name}-action`,
+                match: matches[matches.length - 1] ?? 'Post:tool:*',
+                type: 'command',
+                command: 'echo chain-action',
+                enabled: true,
+            },
+        };
+        const config = cloneConfig(this.managedConfig);
+        config.chains ??= [];
+        config.chains.push(chain);
+        this.managedConfig = config;
+        this.recordAction({ kind: 'scaffold-chain', target: name, timestamp: Date.now(), detail: matches.join(' -> ') });
+        return chain;
+    }
+    removeManagedEntry(name) {
+        const config = cloneConfig(this.managedConfig);
+        let removed = false;
+        for (const [pattern, defs] of Object.entries(config.hooks ?? {})) {
+            const nextDefs = defs.filter((def) => def.name !== name);
+            if (nextDefs.length !== defs.length) {
+                removed = true;
+                if (nextDefs.length === 0)
+                    delete config.hooks?.[pattern];
+                else
+                    config.hooks[pattern] = nextDefs;
+            }
+        }
+        const nextChains = (config.chains ?? []).filter((chain) => chain.name !== name);
+        if (nextChains.length !== (config.chains ?? []).length) {
+            removed = true;
+            config.chains = nextChains;
+        }
+        if (removed) {
+            this.managedConfig = config;
+            this.recordAction({ kind: 'remove', target: name, timestamp: Date.now() });
+        }
+        return removed;
+    }
+    toggleManagedHook(name, enabled) {
+        let changed = false;
+        const config = cloneConfig(this.managedConfig);
+        for (const defs of Object.values(config.hooks ?? {})) {
+            for (const hook of defs) {
+                if (hook.name === name) {
+                    hook.enabled = enabled;
+                    changed = true;
+                }
+            }
+        }
+        if (changed) {
+            this.managedConfig = config;
+            this.recordAction({ kind: 'toggle', target: name, timestamp: Date.now(), detail: enabled ? 'enabled' : 'disabled' });
+        }
+        return changed;
+    }
+    async exportManagedConfig(path) {
+        await this.saveManagedConfig(path);
+        this.recordAction({ kind: 'export', target: path, timestamp: Date.now() });
+        return path;
+    }
+    inspectManagedConfig(path) {
+        const config = ensureConfigShape(JSON.parse(readFileSync(path, 'utf-8')));
+        const inspection = {
+            path,
+            hookCount: Object.values(config.hooks ?? {}).reduce((sum, defs) => sum + defs.length, 0),
+            chainCount: (config.chains ?? []).length,
+            patterns: Object.keys(config.hooks ?? {}).sort((a, b) => a.localeCompare(b)),
+        };
+        this.recordAction({
+            kind: 'inspect',
+            target: path,
+            timestamp: Date.now(),
+            detail: `${inspection.hookCount} hooks / ${inspection.chainCount} chains`,
+        });
+        return inspection;
+    }
+    importManagedConfig(path, strategy = 'merge') {
+        const incoming = ensureConfigShape(JSON.parse(readFileSync(path, 'utf-8')));
+        if (strategy === 'replace') {
+            this.managedConfig = cloneConfig(incoming);
+        }
+        else {
+            const merged = cloneConfig(this.managedConfig);
+            merged.hooks ??= {};
+            for (const [pattern, defs] of Object.entries(incoming.hooks ?? {})) {
+                const existing = merged.hooks[pattern] ?? [];
+                const byName = new Map(existing.map((def) => [def.name ?? `${pattern}:${def.type}:${existing.indexOf(def)}`, { ...def }]));
+                for (const def of defs) {
+                    byName.set(def.name ?? `${pattern}:${def.type}:${byName.size}`, { ...def });
+                }
+                merged.hooks[pattern] = [...byName.values()];
+            }
+            const existingChains = new Map((merged.chains ?? []).map((chain) => [chain.name, {
+                    ...chain,
+                    steps: chain.steps.map((step) => ({ ...step })),
+                    action: { ...chain.action },
+                }]));
+            for (const chain of incoming.chains ?? []) {
+                existingChains.set(chain.name, {
+                    ...chain,
+                    steps: chain.steps.map((step) => ({ ...step })),
+                    action: { ...chain.action },
+                });
+            }
+            merged.chains = [...existingChains.values()];
+            this.managedConfig = merged;
+        }
+        this.recordAction({
+            kind: 'import',
+            target: path,
+            timestamp: Date.now(),
+            detail: `${strategy} -> ${this.listManagedHooks().length} hooks / ${this.listManagedChains().length} chains`,
+        });
+        return this.getManagedConfig();
+    }
+    simulate(eventPath, payload = {}) {
+        const [phase, category, ...specificParts] = eventPath.split(':');
+        const specific = specificParts.join(':');
+        const event = {
+            path: eventPath,
+            phase: phase,
+            category: category,
+            specific,
+            sessionId: 'hook-sim',
+            timestamp: Date.now(),
+            payload,
+        };
+        const matchedHooks = this.listManagedHooks()
+            .filter(({ pattern, hook }) => matchesEventPath(pattern, event.path) && matchesMatcher(hook.matcher, event.specific))
+            .map(({ pattern, hook }) => ({
+            pattern,
+            name: hook.name ?? '(unnamed)',
+            type: hook.type,
+            contract: getHookPointContract(event.path)?.description ?? 'No exact contract',
+        }));
+        const matchedChains = this.listManagedChains()
+            .map((chain) => ({
+            name: chain.name,
+            stepMatches: chain.steps.filter((step) => matchesEventPath(step.match, event.path)).length,
+        }))
+            .filter((chain) => chain.stepMatches > 0);
+        const result = {
+            eventPath,
+            matchedHooks,
+            matchedChains,
+            capturedAt: Date.now(),
+        };
+        this.lastSimulation = result;
+        this.recordAction({
+            kind: 'simulate',
+            target: eventPath,
+            timestamp: result.capturedAt,
+            detail: `${matchedHooks.length} hooks / ${matchedChains.length} chains`,
+        });
+        return result;
+    }
+    clear() {
+        this.managedConfig = cloneConfig(EMPTY_CONFIG);
+        this.recentActions = [];
+        this.lastSimulation = null;
+        this.lastLoadedPath = null;
+    }
+}
+export function createHookWorkbench(options) {
+    const hooksFilePathResolver = options.hooksFilePathResolver ?? (() => {
+        const workingDirectory = options.configManager.getWorkingDirectory();
+        if (!workingDirectory) {
+            throw new Error('createHookWorkbench requires configManager.getWorkingDirectory() when no hooksFilePathResolver is provided');
+        }
+        return resolve(workingDirectory, options.configManager.get('tools.hooksFile'));
+    });
+    return new HookWorkbench(options.hookDispatcher, hooksFilePathResolver);
+}

package/dist/_internal/platform/input/command-registry.d.ts

@@ -0,0 +1,17 @@
+export interface SlashCommand {
+    name: string;
+    aliases?: string[];
+    description: string;
+    usage?: string;
+    argsHint?: string;
+    handler: (args: string[]) => void | Promise<void>;
+}
+export declare class CommandRegistry {
+    private commands;
+    private aliasIndex;
+    register(command: SlashCommand): void;
+    unregister(name: string): void;
+    get(name: string): SlashCommand | undefined;
+    list(): SlashCommand[];
+}
+//# sourceMappingURL=command-registry.d.ts.map

package/dist/_internal/platform/input/command-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-registry.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/input/command-registry.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,UAAU,CAAmC;IAErD,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAOrC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAU9B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI3C,IAAI,IAAI,YAAY,EAAE;CAGvB"}

package/dist/_internal/platform/input/command-registry.js

@@ -0,0 +1,25 @@
+export class CommandRegistry {
+    commands = new Map();
+    aliasIndex = new Map();
+    register(command) {
+        this.commands.set(command.name, command);
+        for (const alias of command.aliases ?? []) {
+            this.aliasIndex.set(alias, command);
+        }
+    }
+    unregister(name) {
+        const command = this.commands.get(name);
+        if (command) {
+            for (const alias of command.aliases ?? []) {
+                this.aliasIndex.delete(alias);
+            }
+        }
+        this.commands.delete(name);
+    }
+    get(name) {
+        return this.commands.get(name) ?? this.aliasIndex.get(name);
+    }
+    list() {
+        return [...this.commands.values()];
+    }
+}

package/dist/_internal/platform/input/keybindings.d.ts

@@ -0,0 +1,86 @@
+/**
+ * KeybindingsManager — loads and merges keyboard shortcut configuration.
+ *
+ * Default bindings are hardcoded here. Users can override any binding by
+ * creating ~/.goodvibes/goodvibes/keybindings.json.
+ *
+ * Config file format example:
+ * {
+ *   "search": { "key": "g", "ctrl": true },
+ *   "block-copy": { "key": "c", "ctrl": true, "alt": true }
+ * }
+ *
+ * Each value is a KeyCombo or an array of KeyCombos for multi-binding support.
+ */
+/** Identifies a specific key press with modifiers. */
+export interface KeyCombo {
+    /** Logical key name (single char like 'f', or named key like 'r', 'z', 'f2', etc.) */
+    key: string;
+    ctrl?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+}
+/** All bindable action identifiers. */
+export type KeyAction = 'copy-selection' | 'clear-cancel' | 'screen-clear' | 'panel-picker' | 'panel-close' | 'panel-close-all' | 'panel-tab-next' | 'panel-tab-prev' | 'history-search' | 'search' | 'block-copy' | 'bookmark' | 'block-save' | 'delete-word' | 'apply-diff-line-start' | 'next-error-line-end' | 'kill-line' | 'clear-prompt' | 'undo' | 'redo' | 'paste' | 'replay-panel';
+/** Human-readable description for each action (used in /keybindings display). */
+export declare const ACTION_DESCRIPTIONS: Record<KeyAction, string>;
+/** Default key bindings for all actions. */
+export declare const DEFAULT_KEYBINDINGS: Record<KeyAction, KeyCombo[]>;
+export interface KeybindingsManagerOptions {
+    readonly configPath?: string;
+    readonly userRoot?: string;
+    readonly homeDirectory?: string;
+}
+/**
+ * KeybindingsManager — owns the resolved keybinding table.
+ *
+ * Call loadFromDisk() once at startup (in main.ts) to merge user config.
+ * Then use matches() anywhere a key token is being evaluated.
+ */
+export declare class KeybindingsManager {
+    private bindings;
+    private configPath;
+    constructor(options: KeybindingsManagerOptions);
+    private cloneDefaults;
+    /**
+     * Load user overrides from disk and merge into the binding table.
+     * Unknown actions are ignored with a debug log. Malformed entries are skipped.
+     * Safe to call multiple times (reloads on each call).
+     */
+    loadFromDisk(): void;
+    private validateCombos;
+    /**
+     * matches — Check whether a keyboard token matches the given action.
+     *
+     * @param action  The action to test.
+     * @param token   The parsed keyboard token from InputTokenizer.
+     *                Expects: { logicalName: string; ctrl?: boolean; shift?: boolean; alt?: boolean }
+     */
+    matches(action: KeyAction, token: {
+        logicalName?: string;
+        ctrl?: boolean;
+        shift?: boolean;
+        alt?: boolean;
+    }): boolean;
+    private comboMatches;
+    /**
+     * getAll — Return the full resolved binding table for display purposes.
+     */
+    getAll(): Array<{
+        action: KeyAction;
+        combos: KeyCombo[];
+        description: string;
+    }>;
+    /**
+     * getComboLabel — Return a human-readable label for the first combo of an action.
+     * Example: { key: 'f', ctrl: true } → "Ctrl+F"
+     */
+    getComboLabel(action: KeyAction): string;
+    /**
+     * formatCombo — Format a KeyCombo as a human-readable string.
+     */
+    formatCombo(combo: KeyCombo): string;
+    /** Return the config file path. */
+    getConfigPath(): string;
+}
+//# sourceMappingURL=keybindings.d.ts.map

package/dist/_internal/platform/input/keybindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keybindings.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/input/keybindings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,sDAAsD;AACtD,MAAM,WAAW,QAAQ;IACvB,sFAAsF;IACtF,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,uCAAuC;AACvC,MAAM,MAAM,SAAS,GACjB,gBAAgB,GAChB,cAAc,GACd,cAAc,GACd,cAAc,GACd,aAAa,GACb,iBAAiB,GACjB,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,QAAQ,GACR,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,aAAa,GACb,uBAAuB,GACvB,qBAAqB,GACrB,WAAW,GACX,cAAc,GACd,MAAM,GACN,MAAM,GACN,OAAO,GACP,cAAc,CAAC;AAEnB,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAuBzD,CAAC;AAEF,4CAA4C;AAC5C,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,SAAS,EAAE,QAAQ,EAAE,CAuB7D,CAAC;AAKF,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAaD;;;;;GAKG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,EAAE,yBAAyB;IAM9C,OAAO,CAAC,aAAa;IAQrB;;;;OAIG;IACH,YAAY,IAAI,IAAI;IA4BpB,OAAO,CAAC,cAAc;IAQtB;;;;;;OAMG;IACH,OAAO,CACL,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,GAC9E,OAAO;IAMV,OAAO,CAAC,YAAY;IAWpB;;OAEG;IACH,MAAM,IAAI,KAAK,CAAC;QAAE,MAAM,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,QAAQ,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAQ/E;;;OAGG;IACH,aAAa,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM;IAMxC;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM;IASpC,mCAAmC;IACnC,aAAa,IAAI,MAAM;CAGxB"}