@loggiecid/shell-kit

Shared shell-layer primitives for LoggieCID: hook recording, registry queries, persistence adapters, and typed execution history.

What This Is

Shell-kit is the cross-cutting infrastructure layer for hook lifecycle management across the Loggie OS system. It provides:

• Hook recording — recordHookExecution() with auto-generated IDs, truncation, and rotation
• Registry queries — getHookExecutions(), getPendingConfirmations(), getConfirmationStats(), getRecentFailures()
• Persistence adapters — Node.js (filesystem) and browser (localStorage) implementations behind a shared interface
• Typed execution history — HookExecution, InboxConfirmation, HookRegistryData types
• On-chain confirmation tracking — pending/confirmed/failed/timeout status with reconciliation

Status

Stable — extracted from loggie-sdk as standalone package. Zero external runtime dependencies.

Getting Started

pnpm install @loggiecid/shell-kit

Node.js (CLI, servers, dashboard)

import { configureHookRegistry } from '@loggiecid/shell-kit';
import { createNodeHookDeps } from '@loggiecid/shell-kit/node';

// Initialize once at startup
configureHookRegistry(createNodeHookDeps());

// Then use anywhere
import { getHookExecutions, getPendingConfirmations } from '@loggiecid/shell-kit';
const recent = getHookExecutions({ hookType: 'stop', limit: 50 });

Browser

import { configureHookRegistry } from '@loggiecid/shell-kit';
import { createBrowserHookDeps } from '@loggiecid/shell-kit/browser';

configureHookRegistry(createBrowserHookDeps());

Build

pnpm build    # tsup → dist/ (ESM + CJS + types)
pnpm test     # vitest
pnpm dev      # watch mode

Documentation

• Overview
• Use Cases
• Monetization Strategy
• Gaps & Tasks

Exports

| Subpath | Platform | Contents | |---------|----------|----------| | . | Neutral | Hook registry, types, query functions | | ./node | Node.js | Filesystem persistence, logger, event sink | | ./browser | Browser | localStorage persistence, console logger |

Consumed By

• loggie-sdk — CLI hook execution
• stophook-dashboard — ops audit plane
• Bash stop hooks — via inline Node.js calls

License

MIT