@phyzess/pappra 0.0.0-stage → 0.1.0-beta.10

package/dist/hosts/integration/support.d.ts

@@ -0,0 +1,59 @@
+import type { HostLifecycleEvent, HostName } from '../../schemas/host.js';
+export declare const HOST_SUPPORT: {
+    readonly pi: {
+        readonly surface: 'pi-extension';
+        readonly version: '1.3.0';
+        readonly hookScope: 'project';
+        readonly events: {
+            readonly startup: 'session_start';
+            readonly resume: 'session_start';
+            readonly compact: 'session_before_compact';
+            readonly 'checkpoint-request': 'pappra-checkpoint';
+        };
+    };
+    readonly codex: {
+        readonly surface: 'codex-hooks';
+        readonly version: '0.163.0';
+        readonly hookScope: 'user';
+        readonly events: {
+            readonly startup: 'SessionStart';
+            readonly resume: 'SessionStart';
+            readonly compact: null;
+            readonly 'checkpoint-request': null;
+        };
+    };
+    readonly claude: {
+        readonly surface: 'claude-hooks';
+        readonly version: '2.1.292';
+        readonly hookScope: 'project';
+        readonly events: {
+            readonly startup: 'SessionStart';
+            readonly resume: 'SessionStart';
+            readonly compact: 'PostCompact';
+            readonly 'checkpoint-request': null;
+        };
+    };
+};
+export declare function nativeEventFor(host: HostName, event: HostLifecycleEvent): string | null;
+export declare function isSupportedVersion(host: HostName, version: string | null): boolean;
+export declare function surfaceFor(host: HostName): (typeof HOST_SUPPORT)[HostName]['surface'];
+/**
+ * Observed plugin-hook support. `verified` means a real host session produced a
+ * `.pappra/local/host-events/<host>` record; `unsupported` means a control hook
+ * fired while the bundled plugin hook did not; `unverified` means no
+ * authenticated session was available. See docs/host-plugin-validation.md.
+ */
+export declare const HOST_PLUGIN_HOOKS: {
+    readonly pi: {
+        readonly state: 'verified';
+        readonly evidence: 'Pi 1.3.0 fires the packaged extension: `pi install <dir> -l -a` plus `pi -p -a` wrote a session_start event.';
+    };
+    readonly codex: {
+        readonly state: 'unsupported';
+        readonly evidence: 'Codex 0.163.0 does not load plugin hooks: a control hook in CODEX_HOME fired during `codex exec --dangerously-bypass-hook-trust` while the bundled plugin hook never ran, including with a .codex-plugin/plugin.json copy.';
+    };
+    readonly claude: {
+        readonly state: 'verified';
+        readonly evidence: 'Claude Code 2.1.292 passed `claude plugin validate`, then a project-scope marketplace install and `claude -p` wrote a SessionStart event from ${CLAUDE_PLUGIN_ROOT}/hooks/pappra-hook.mjs.';
+    };
+};

package/dist/hosts/integration/support.js

@@ -0,0 +1,66 @@
+export const HOST_SUPPORT = {
+    pi: {
+        surface: 'pi-extension',
+        version: '1.3.0',
+        hookScope: 'project',
+        events: {
+            startup: 'session_start',
+            resume: 'session_start',
+            compact: 'session_before_compact',
+            'checkpoint-request': 'pappra-checkpoint',
+        },
+    },
+    codex: {
+        surface: 'codex-hooks',
+        version: '0.163.0',
+        // Codex 0.163.0 loads lifecycle hooks only from its user configuration
+        // directory (CODEX_HOME); project `.codex/hooks.json` is not loaded.
+        hookScope: 'user',
+        events: {
+            startup: 'SessionStart',
+            resume: 'SessionStart',
+            compact: null,
+            'checkpoint-request': null,
+        },
+    },
+    claude: {
+        surface: 'claude-hooks',
+        version: '2.1.292',
+        hookScope: 'project',
+        events: {
+            startup: 'SessionStart',
+            resume: 'SessionStart',
+            compact: 'PostCompact',
+            'checkpoint-request': null,
+        },
+    },
+};
+export function nativeEventFor(host, event) {
+    return HOST_SUPPORT[host].events[event];
+}
+export function isSupportedVersion(host, version) {
+    return version === HOST_SUPPORT[host].version;
+}
+export function surfaceFor(host) {
+    return HOST_SUPPORT[host].surface;
+}
+/**
+ * Observed plugin-hook support. `verified` means a real host session produced a
+ * `.pappra/local/host-events/<host>` record; `unsupported` means a control hook
+ * fired while the bundled plugin hook did not; `unverified` means no
+ * authenticated session was available. See docs/host-plugin-validation.md.
+ */
+export const HOST_PLUGIN_HOOKS = {
+    pi: {
+        state: 'verified',
+        evidence: 'Pi 1.3.0 fires the packaged extension: `pi install <dir> -l -a` plus `pi -p -a` wrote a session_start event.',
+    },
+    codex: {
+        state: 'unsupported',
+        evidence: 'Codex 0.163.0 does not load plugin hooks: a control hook in CODEX_HOME fired during `codex exec --dangerously-bypass-hook-trust` while the bundled plugin hook never ran, including with a .codex-plugin/plugin.json copy.',
+    },
+    claude: {
+        state: 'verified',
+        evidence: 'Claude Code 2.1.292 passed `claude plugin validate`, then a project-scope marketplace install and `claude -p` wrote a SessionStart event from ${CLAUDE_PLUGIN_ROOT}/hooks/pappra-hook.mjs.',
+    },
+};

package/dist/hosts/integration/templates.d.ts

@@ -0,0 +1,22 @@
+import type { HostName, HostLifecycleEvent } from '../../schemas/host.js';
+export declare const PAPPRA_MANAGED_MARKER = "pappra-managed";
+export interface RenderedHostTemplate {
+    readonly path: string;
+    readonly bytes: Buffer;
+    readonly kind: 'extension' | 'hook';
+}
+export declare function renderHookCommand(host: HostName, event: HostLifecycleEvent, hookExpression: string): string;
+interface HookEntry {
+    readonly hooks: readonly {
+        readonly type: 'command';
+        readonly command: string;
+        readonly timeout: number;
+    }[];
+}
+export declare function renderHookConfigPatch(host: 'codex' | 'claude', hookExpression: string): {
+    readonly hooks: Record<string, readonly HookEntry[]>;
+};
+export declare function renderHostTemplate(host: HostName, hookExpression: string): RenderedHostTemplate;
+export declare function hostConfigRelativePath(host: HostName): 'settings.json' | 'hooks.json' | null;
+export declare function hostConfigName(host: HostName): string;
+export {};

package/dist/hosts/integration/templates.js

@@ -0,0 +1,75 @@
+import { basename } from 'node:path';
+export const PAPPRA_MANAGED_MARKER = 'pappra-managed';
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+/**
+ * Host placeholders such as ${CLAUDE_PROJECT_DIR} only expand inside double
+ * quotes; absolute paths are single-quoted to survive spaces and quotes.
+ */
+function pathExpression(value) {
+    return value.includes('${') ? `"${value}"` : shellQuote(value);
+}
+export function renderHookCommand(host, event, hookExpression) {
+    return `${shellQuote(process.execPath)} ${pathExpression(hookExpression)} ${shellQuote(host)} ${shellQuote(event)} # ${PAPPRA_MANAGED_MARKER}`;
+}
+export function renderHookConfigPatch(host, hookExpression) {
+    const entry = (event) => ({
+        hooks: [
+            {
+                type: 'command',
+                command: renderHookCommand(host, event, hookExpression),
+                timeout: 1,
+            },
+        ],
+    });
+    return host === 'claude'
+        ? {
+            hooks: {
+                SessionStart: [entry('startup')],
+                PostCompact: [entry('compact')],
+            },
+        }
+        : {
+            hooks: {
+                SessionStart: [entry('startup')],
+            },
+        };
+}
+export function renderHostTemplate(host, hookExpression) {
+    if (host === 'pi') {
+        const source = `/**
+ * Generated Pappra Pi extension. It registers bounded local lifecycle handlers;
+ * it does not start processes, models, network requests or background work.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createPiExtension } from "./runtime.mjs";
+
+export default function (pi: ExtensionAPI): void {
+  createPiExtension(pi);
+}
+`;
+        return {
+            path: 'templates/pi/entry.ts',
+            bytes: Buffer.from(source),
+            kind: 'extension',
+        };
+    }
+    const patch = renderHookConfigPatch(host, hookExpression);
+    return {
+        path: `templates/${host}/hooks.json`,
+        bytes: Buffer.from(`${JSON.stringify(patch, null, 2)}\n`),
+        kind: 'hook',
+    };
+}
+export function hostConfigRelativePath(host) {
+    if (host === 'claude')
+        return 'settings.json';
+    if (host === 'codex')
+        return 'hooks.json';
+    return null;
+}
+export function hostConfigName(host) {
+    const path = hostConfigRelativePath(host);
+    return path === null ? 'pi-extension' : basename(path);
+}

package/dist/hosts/pi/protocol.d.ts

@@ -0,0 +1,22 @@
+export interface PiData {
+    [key: string]: unknown;
+    sessionId?: string;
+    sessionFile?: string;
+    isStreaming?: boolean;
+    isCompacting?: boolean;
+    pendingMessageCount?: number;
+    messageCount?: number;
+    disposition?: string;
+    steering?: unknown[];
+    followUp?: unknown[];
+}
+export interface PiRecord {
+    [key: string]: unknown;
+    type: string;
+    id?: string;
+    command?: string;
+    success?: boolean;
+    error?: string;
+    data?: PiData;
+}
+export declare function isPiRecord(value: unknown): value is PiRecord;

package/dist/hosts/pi/protocol.js

@@ -0,0 +1,28 @@
+import { object } from '../../collab/validation.js';
+export function isPiRecord(value) {
+    if (!object(value) || typeof value['type'] !== 'string')
+        return false;
+    for (const key of ['id', 'command', 'error'])
+        if (value[key] !== undefined && typeof value[key] !== 'string')
+            return false;
+    if (value['success'] !== undefined && typeof value['success'] !== 'boolean')
+        return false;
+    const data = value['data'];
+    if (data === undefined)
+        return true;
+    if (!object(data))
+        return false;
+    for (const key of ['sessionId', 'sessionFile', 'disposition'])
+        if (data[key] !== undefined && typeof data[key] !== 'string')
+            return false;
+    for (const key of ['isStreaming', 'isCompacting'])
+        if (data[key] !== undefined && typeof data[key] !== 'boolean')
+            return false;
+    for (const key of ['pendingMessageCount', 'messageCount'])
+        if (data[key] !== undefined && typeof data[key] !== 'number')
+            return false;
+    for (const key of ['steering', 'followUp'])
+        if (data[key] !== undefined && !Array.isArray(data[key]))
+            return false;
+    return true;
+}

package/dist/hosts/pi/query-result.d.ts

@@ -0,0 +1,22 @@
+export interface QueryOptions {
+    session: string;
+    cwd: string;
+    expectedSession: string;
+    taskId: string;
+    assignmentId: string;
+    attempt: number;
+    inputDigest: string;
+    output?: string;
+    evidenceDir?: string;
+    piBin?: string;
+    timeoutMs?: number;
+    graceMs?: number;
+}
+export interface RecoveryResult {
+    schema: string;
+    status: string;
+    blockers: string[];
+    recovered?: unknown;
+    [key: string]: unknown;
+}
+export declare function queryPiResult(options: QueryOptions): Promise<RecoveryResult>;