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

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

@@ -0,0 +1,51 @@
+export interface NativeItem {
+    [key: string]: unknown;
+    type?: string;
+    text?: string;
+    status?: string;
+    exitCode?: number;
+    aggregatedOutput?: string;
+}
+export interface NativeEntry {
+    [key: string]: unknown;
+    id?: string;
+    status?: string;
+    item?: NativeItem;
+}
+export interface NativeThread {
+    [key: string]: unknown;
+    id?: string;
+    cwd?: string;
+    status?: {
+        type: string;
+    };
+}
+export interface NativeReply {
+    [key: string]: unknown;
+    thread?: NativeThread;
+    turn?: NativeEntry;
+    data?: NativeEntry[];
+}
+export interface NativeParams {
+    [key: string]: unknown;
+    threadId?: string;
+    turn?: NativeEntry;
+}
+export interface NativeRecord {
+    id?: string | number;
+    method?: string;
+    params?: NativeParams;
+    result?: NativeReply;
+    error?: {
+        message?: string;
+    };
+}
+export interface NativeEvent {
+    seq: number;
+    method: string;
+    params: NativeParams | null;
+    at: string;
+    error?: never;
+}
+export declare function isReply(value: unknown): value is NativeReply;
+export declare function isRecord(value: unknown): value is NativeRecord;

package/dist/hosts/codex/protocol.js

@@ -0,0 +1,42 @@
+import { object } from '../../collab/validation.js';
+const optionalString = (value) => value === undefined || typeof value === 'string';
+function isEntry(value) {
+    const item = object(value) ? value['item'] : undefined;
+    return (object(value) &&
+        optionalString(value['id']) &&
+        optionalString(value['status']) &&
+        (value['item'] === undefined ||
+            (object(value['item']) &&
+                object(item) &&
+                ['type', 'text', 'status', 'aggregatedOutput'].every((key) => optionalString(item[key])) &&
+                (value['item']['exitCode'] === undefined ||
+                    typeof value['item']['exitCode'] === 'number'))));
+}
+export function isReply(value) {
+    return (object(value) &&
+        (value['thread'] === undefined ||
+            (object(value['thread']) &&
+                optionalString(value['thread']['id']) &&
+                optionalString(value['thread']['cwd']) &&
+                (value['thread']['status'] === undefined ||
+                    (object(value['thread']['status']) &&
+                        typeof value['thread']['status']['type'] === 'string')))) &&
+        (value['turn'] === undefined || isEntry(value['turn'])) &&
+        (value['data'] === undefined ||
+            (Array.isArray(value['data']) && value['data'].every(isEntry))));
+}
+export function isRecord(value) {
+    return (object(value) &&
+        (value['id'] === undefined ||
+            typeof value['id'] === 'string' ||
+            typeof value['id'] === 'number') &&
+        optionalString(value['method']) &&
+        (value['params'] === undefined ||
+            (object(value['params']) &&
+                optionalString(value['params']['threadId']) &&
+                (value['params']['turn'] === undefined ||
+                    isEntry(value['params']['turn'])))) &&
+        (value['result'] === undefined || isReply(value['result'])) &&
+        (value['error'] === undefined ||
+            (object(value['error']) && optionalString(value['error']['message']))));
+}

package/dist/hosts/detect.d.ts

@@ -0,0 +1,29 @@
+import type { EvidenceRef } from '../schemas/evidence.js';
+export type HostName = 'pi' | 'codex' | 'claude';
+export interface PassiveToolObservation {
+    readonly name: string;
+    readonly command: string;
+    readonly executablePath: string | null;
+    readonly discovered: boolean;
+}
+export interface PassiveHostObservation {
+    readonly host: HostName;
+    readonly selected: boolean;
+    readonly executablePath: string | null;
+    readonly discovered: boolean;
+    readonly configPaths: readonly string[];
+    readonly configured: boolean;
+    readonly callable: 'unknown';
+    readonly verification: 'unsupported';
+    readonly evidence: readonly EvidenceRef[];
+}
+export interface HostDetectionOptions {
+    readonly homeDir: string;
+    readonly pathEnv: string;
+    readonly selectedHosts: readonly string[];
+    readonly observedAt?: string;
+}
+export declare function executableOnPath(command: string, pathEnv: string): string | null;
+export declare function detectPassiveTool(command: string, pathEnv: string): PassiveToolObservation;
+/** Passive host discovery. It never starts a host or reads config contents. */
+export declare function detectPassiveHosts(options: HostDetectionOptions): readonly PassiveHostObservation[];

package/dist/hosts/detect.js

@@ -0,0 +1,73 @@
+import { accessSync, constants, existsSync, statSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+function evidence(path, observedAt) {
+    return {
+        kind: 'file',
+        ref: path,
+        digest: null,
+        observedAt,
+        scope: 'live-owned',
+    };
+}
+export function executableOnPath(command, pathEnv) {
+    for (const directory of pathEnv.split(delimiter)) {
+        if (directory === '')
+            continue;
+        const candidate = join(directory, command);
+        try {
+            const stats = statSync(candidate);
+            if (!stats.isFile())
+                continue;
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // Continue probing the remaining PATH entries.
+        }
+    }
+    return null;
+}
+export function detectPassiveTool(command, pathEnv) {
+    const executablePath = executableOnPath(command, pathEnv);
+    return {
+        name: command,
+        command,
+        executablePath,
+        discovered: executablePath !== null,
+    };
+}
+/** Passive host discovery. It never starts a host or reads config contents. */
+export function detectPassiveHosts(options) {
+    const observedAt = options.observedAt ?? new Date().toISOString();
+    const configs = {
+        pi: [join(options.homeDir, '.pi')],
+        codex: [join(options.homeDir, '.codex', 'config.toml')],
+        claude: [join(options.homeDir, '.claude', 'settings.json')],
+    };
+    const commands = {
+        pi: 'pi',
+        codex: 'codex',
+        claude: 'claude',
+    };
+    const selected = new Set(options.selectedHosts);
+    return ['pi', 'codex', 'claude'].map((host) => {
+        const executablePath = executableOnPath(commands[host], options.pathEnv);
+        const configPaths = configs[host].filter((path) => existsSync(path));
+        const evidenceRefs = [];
+        if (executablePath !== null)
+            evidenceRefs.push(evidence(executablePath, observedAt));
+        for (const path of configPaths)
+            evidenceRefs.push(evidence(path, observedAt));
+        return {
+            host,
+            selected: selected.has(host),
+            executablePath,
+            discovered: executablePath !== null,
+            configPaths,
+            configured: configPaths.length > 0,
+            callable: 'unknown',
+            verification: 'unsupported',
+            evidence: evidenceRefs,
+        };
+    });
+}

package/dist/hosts/index.d.ts

@@ -0,0 +1,10 @@
+export * as detect from './detect.js';
+export * as codex from './codex/native.js';
+export * as claude from './claude/native.js';
+export * as piRpc from './pi/rpc.js';
+export * as piHistory from './pi/query-result.js';
+export * as pilot from './pilot.js';
+export { HostAdapter, HostIntegrationService, type HostIntegrationOptions, type HostTargetOptions, } from './integration/service.js';
+export { mapNativeHookEvent, readHookInput, runHostHook, type HostHookOptions, type NativeHookMapping, } from './integration/hook.js';
+export { createPiExtension, type PiExtensionLike, } from './integration/pi-extension-runtime.js';
+export { HOST_SUPPORT, nativeEventFor, isSupportedVersion, } from './integration/support.js';

package/dist/hosts/index.js

@@ -0,0 +1,10 @@
+export * as detect from './detect.js';
+export * as codex from './codex/native.js';
+export * as claude from './claude/native.js';
+export * as piRpc from './pi/rpc.js';
+export * as piHistory from './pi/query-result.js';
+export * as pilot from './pilot.js';
+export { HostAdapter, HostIntegrationService, } from './integration/service.js';
+export { mapNativeHookEvent, readHookInput, runHostHook, } from './integration/hook.js';
+export { createPiExtension, } from './integration/pi-extension-runtime.js';
+export { HOST_SUPPORT, nativeEventFor, isSupportedVersion, } from './integration/support.js';

package/dist/hosts/integration/bundle-export.d.ts

@@ -0,0 +1,24 @@
+import type { HostName } from '../../schemas/host.js';
+export interface HostPluginBundle {
+    readonly host: HostName;
+    readonly outDir: string;
+    readonly files: readonly string[];
+    readonly pluginManifest: string;
+    readonly hookConfig: string | null;
+    readonly registration: readonly string[];
+    /** Plugin registration and native callability are not verified here. */
+    readonly verification: 'unsupported';
+}
+/**
+ * Writes a host-native plugin/package directory. This is an artifact export: it
+ * does not register the plugin with a host, and it never claims the host will
+ * load or trust it.
+ */
+export declare function exportHostPluginBundle(options: {
+    readonly host: HostName;
+    readonly hostVersion: string;
+    readonly outDir: string;
+    readonly packageVersion: string;
+    /** Writes a marketplace root with the plugin under `pappra/`. */
+    readonly marketplace?: boolean;
+}): Promise<HostPluginBundle>;

package/dist/hosts/integration/bundle-export.js

@@ -0,0 +1,128 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { getPackageRoot } from '../../package-info.js';
+import { isPathInside } from '../../schemas/paths.js';
+import { loadHostBundle } from './bundle.js';
+import { renderHookConfigPatch } from './templates.js';
+function pluginHookExpression(host) {
+    return host === 'claude'
+        ? '${CLAUDE_PLUGIN_ROOT}/hooks/pappra-hook.mjs'
+        : './hooks/pappra-hook.mjs';
+}
+function hostManifest(host, version) {
+    if (host === 'claude' || host === 'codex') {
+        // Codex reads the Claude plugin manifest path, so one manifest serves both.
+        return {
+            path: '.claude-plugin/plugin.json',
+            value: {
+                name: 'pappra',
+                version,
+                description: 'Portable workspace knowledge and continuity for coding agents.',
+                author: { name: 'phyzess' },
+                hooks: './hooks/hooks.json',
+            },
+        };
+    }
+    return {
+        path: 'package.json',
+        value: {
+            name: '@phyzess/pappra-pi',
+            version,
+            description: 'Pappra Pi package: bounded lifecycle hooks and skill.',
+            type: 'module',
+            pi: {
+                extensions: ['./extensions/pappra/index.ts'],
+                skills: ['./skills'],
+            },
+            peerDependencies: { '@earendil-works/pi-coding-agent': '*' },
+        },
+    };
+}
+/**
+ * Writes a host-native plugin/package directory. This is an artifact export: it
+ * does not register the plugin with a host, and it never claims the host will
+ * load or trust it.
+ */
+export async function exportHostPluginBundle(options) {
+    const outRoot = resolve(options.outDir);
+    if (options.marketplace === true && options.host === 'pi') {
+        throw new Error('Pi installs a directory directly; a marketplace wrapper is not supported.');
+    }
+    const pluginPrefix = options.marketplace === true ? 'pappra/' : '';
+    const pluginRoot = options.marketplace === true ? join(outRoot, 'pappra') : outRoot;
+    const payload = await loadHostBundle(options.host, options.packageVersion, {
+        hookSource: join(getPackageRoot(), 'dist/hosts/integration/pappra-hook.mjs'),
+        hookExpression: pluginHookExpression(options.host),
+    });
+    const written = [];
+    const writeEntry = async (path, bytes) => {
+        const target = join(outRoot, ...path.split('/'));
+        if (!isPathInside(outRoot, target)) {
+            throw new Error(`Unsafe plugin bundle path: ${path}`);
+        }
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, bytes);
+        written.push(path);
+    };
+    for (const [path, bytes] of payload.contents) {
+        // Plugin manifests point at hooks/hooks.json directly; the rendered
+        // templates are only an intermediate artifact.
+        if (path.startsWith('templates/'))
+            continue;
+        await writeEntry(`${pluginPrefix}${path}`, bytes);
+    }
+    const expression = pluginHookExpression(options.host);
+    if (options.host === 'pi') {
+        const entry = payload.contents.get('templates/pi/entry.ts');
+        const runtime = payload.contents.get('templates/pi/runtime.mjs');
+        if (entry === undefined || runtime === undefined) {
+            throw new Error('Pi plugin bundle is missing its extension entry.');
+        }
+        // The generated entry imports ./runtime.mjs, so both files share one directory.
+        await writeEntry(`${pluginPrefix}extensions/pappra/index.ts`, entry);
+        await writeEntry(`${pluginPrefix}extensions/pappra/runtime.mjs`, runtime);
+    }
+    else {
+        const patch = renderHookConfigPatch(options.host, expression);
+        await writeEntry(`${pluginPrefix}hooks/hooks.json`, Buffer.from(`${JSON.stringify(patch, null, 2)}\n`));
+    }
+    const manifest = hostManifest(options.host, options.packageVersion);
+    await writeEntry(`${pluginPrefix}${manifest.path}`, Buffer.from(`${JSON.stringify(manifest.value, null, 2)}\n`));
+    if (options.marketplace === true) {
+        await writeEntry('.claude-plugin/marketplace.json', Buffer.from(`${JSON.stringify({
+            name: 'pappra-local',
+            owner: { name: 'phyzess' },
+            description: 'Local Pappra plugin marketplace exported by pappra host bundle.',
+            plugins: [
+                {
+                    name: 'pappra',
+                    source: './pappra',
+                    description: 'Portable workspace knowledge and continuity for coding agents.',
+                    author: { name: 'phyzess' },
+                },
+            ],
+        }, null, 2)}\n`));
+    }
+    return {
+        host: options.host,
+        outDir: pluginRoot,
+        files: written.sort((left, right) => left.localeCompare(right)),
+        pluginManifest: `${pluginPrefix}${manifest.path}`,
+        hookConfig: options.host === 'pi' ? null : `${pluginPrefix}hooks/hooks.json`,
+        registration: options.host === 'claude'
+            ? [
+                'Register the directory as a local plugin or marketplace entry; Pappra does not add it to host settings.',
+                'Claude Code substitutes ${CLAUDE_PLUGIN_ROOT} at hook execution time.',
+            ]
+            : options.host === 'codex'
+                ? [
+                    'Package the directory as a Codex plugin; hook paths are relative to the plugin root.',
+                    'Review the plugin before trusting it; Pappra does not install or trust it.',
+                ]
+                : [
+                    'Install the directory as a Pi package, for example `pi install ./pappra-pi`.',
+                    'Pi installs package dependencies and requires project trust before loading.',
+                ],
+        verification: 'unsupported',
+    };
+}

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

@@ -0,0 +1,19 @@
+import type { HostBundle, HostName } from '../../schemas/host.js';
+export declare const SHARED_SKILL_ID = "pappra";
+export interface HostBundlePayload {
+    readonly bundle: HostBundle;
+    readonly contents: ReadonlyMap<string, Buffer>;
+}
+export declare function installPathForBundleFile(host: HostName, sourcePath: string): string;
+/**
+ * Loads the complete shared skill plus the generated host template. The
+ * digest covers every packaged support file and the exact native template.
+ */
+export declare function loadHostBundle(host: HostName, packageVersion: string, options?: {
+    readonly assetsRoot?: string;
+    /** Absolute path of the bundled, dependency-free hook file. */
+    readonly hookSource?: string;
+    /** Command-line path expression used inside the host hook configuration. */
+    readonly hookExpression?: string;
+    readonly observedAt?: string;
+}): Promise<HostBundlePayload>;

package/dist/hosts/integration/bundle.js

@@ -0,0 +1,99 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { dirname, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { HOST_BUNDLE_SCHEMA } from '../../schemas/host.js';
+import { sha256Digest } from '../../infra/fs.js';
+import { renderHostTemplate } from './templates.js';
+export const SHARED_SKILL_ID = 'pappra';
+function packageRoot() {
+    return dirname(fileURLToPath(import.meta.resolve('@phyzess/pappra/package.json')));
+}
+async function listFiles(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory())
+            files.push(...(await listFiles(path)));
+        else if (entry.isFile())
+            files.push(path);
+    }
+    return files;
+}
+function portableRelative(root, path) {
+    return relative(root, path).split(sep).join('/');
+}
+export function installPathForBundleFile(host, sourcePath) {
+    if (host === 'pi' && sourcePath === 'templates/pi/entry.ts') {
+        return 'extensions/pappra/index.ts';
+    }
+    return sourcePath;
+}
+/**
+ * Loads the complete shared skill plus the generated host template. The
+ * digest covers every packaged support file and the exact native template.
+ */
+export async function loadHostBundle(host, packageVersion, options = {}) {
+    const root = options.assetsRoot ?? join(packageRoot(), 'assets', 'integrations');
+    const skillRoot = join(root, 'skills', SHARED_SKILL_ID);
+    const paths = await listFiles(skillRoot);
+    if (paths.length === 0) {
+        throw new Error(`No packaged skill files found in ${skillRoot}`);
+    }
+    const contents = new Map();
+    const files = [];
+    for (const path of paths) {
+        const source = portableRelative(root, path);
+        if (source.includes('..') || source.startsWith('/')) {
+            throw new Error(`Unsafe packaged skill path: ${source}`);
+        }
+        const bytes = await readFile(path);
+        contents.set(source, bytes);
+        files.push({
+            path: source,
+            digest: sha256Digest(bytes),
+            kind: source.endsWith('/SKILL.md') ? 'skill' : 'reference',
+        });
+    }
+    const hookSource = options.hookSource ??
+        join(packageRoot(), 'dist/hosts/integration/pappra-hook.mjs');
+    const hookBytes = await readFile(hookSource);
+    contents.set('hooks/pappra-hook.mjs', hookBytes);
+    files.push({
+        path: 'hooks/pappra-hook.mjs',
+        digest: sha256Digest(hookBytes),
+        kind: 'hook',
+    });
+    if (host === 'pi') {
+        const runtimePath = join(dirname(hookSource), 'pappra-extension-runtime.mjs');
+        const runtimeBytes = await readFile(runtimePath);
+        contents.set('templates/pi/runtime.mjs', runtimeBytes);
+        files.push({
+            path: 'templates/pi/runtime.mjs',
+            digest: sha256Digest(runtimeBytes),
+            kind: 'extension',
+        });
+    }
+    const template = renderHostTemplate(host, options.hookExpression ?? hookSource);
+    contents.set(template.path, template.bytes);
+    files.push({
+        path: template.path,
+        digest: sha256Digest(template.bytes),
+        kind: template.kind,
+    });
+    files.sort((left, right) => left.path.localeCompare(right.path));
+    const bundleDigest = sha256Digest(files.map((file) => `${file.path}\0${file.digest}`).join('\n'));
+    const observedAt = options.observedAt ?? new Date().toISOString();
+    return {
+        bundle: {
+            schema: HOST_BUNDLE_SCHEMA,
+            host,
+            skillId: SHARED_SKILL_ID,
+            packageVersion,
+            bundleDigest,
+            files,
+            observedAt,
+        },
+        contents,
+    };
+}

package/dist/hosts/integration/hook-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hosts/integration/hook-entry.js

@@ -0,0 +1,68 @@
+import { mapNativeHookEvent, readHookInput, renderHostHookOutput, runHostHook, } from './hook.js';
+import { hostNameSchema } from '../../schemas/host.js';
+import { formatDiagnostic } from '../../schemas/diagnostics.js';
+const EVENTS = [
+    'startup',
+    'resume',
+    'compact',
+    'checkpoint-request',
+];
+function parseEvent(value) {
+    return EVENTS.find((event) => event === value) ?? 'startup';
+}
+function parseHost(value) {
+    const parsed = hostNameSchema.safeParse(value);
+    return parsed.success ? parsed.data : null;
+}
+function writeError(message) {
+    process.stderr.write(`pappra hook: ${message}\n`);
+}
+/**
+ * Command-hook entrypoint. It reads one bounded event, records only a local
+ * observation, and never writes a checkpoint or starts work.
+ */
+async function main() {
+    const host = parseHost(process.argv[2]);
+    if (host === null) {
+        writeError('unknown host');
+        return 1;
+    }
+    const fallbackEvent = parseEvent(process.argv[3]);
+    const input = await readHookInput(process.stdin, 1024 * 1024, 1000);
+    if (!input.ok) {
+        if (typeof process.stdin.destroy === 'function')
+            process.stdin.destroy();
+        writeError(formatDiagnostic(input.diagnostic));
+        process.exit(1);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(input.bytes.toString('utf8'));
+    }
+    catch {
+        writeError('native hook input is not JSON');
+        return 1;
+    }
+    const mapped = mapNativeHookEvent(host, raw, fallbackEvent, process.cwd());
+    if (!mapped.ok) {
+        writeError(formatDiagnostic(mapped.diagnostic));
+        return mapped.event === null ? 1 : 0;
+    }
+    const result = await runHostHook(mapped.input);
+    if (!result.ok) {
+        for (const entry of result.diagnostics) {
+            if (typeof entry === 'object' && entry !== null && 'message' in entry) {
+                const message = entry['message'];
+                if (typeof message === 'string')
+                    writeError(message);
+            }
+        }
+        return result.status === 'invalid' || result.status === 'failed' ? 1 : 0;
+    }
+    const advisory = renderHostHookOutput(host, result);
+    if (advisory !== null)
+        process.stdout.write(advisory);
+    return 0;
+}
+const code = await main();
+process.exitCode = code;

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

@@ -0,0 +1,32 @@
+import type { Diagnostic } from '../../schemas/diagnostics.js';
+import type { HostHookInput, HostHookResult, HostLifecycleEvent, HostName } from '../../schemas/host.js';
+export declare function renderHostHookOutput(host: HostName, result: HostHookResult): string | null;
+export type NativeHookMapping = {
+    readonly ok: true;
+    readonly input: HostHookInput;
+} | {
+    readonly ok: false;
+    readonly diagnostic: Diagnostic;
+    readonly host: HostName;
+    readonly event: HostLifecycleEvent | null;
+};
+export declare function mapNativeHookEvent(host: HostName, raw: unknown, _fallbackEvent: HostLifecycleEvent, _fallbackCwd: string | null): NativeHookMapping;
+export interface HostHookOptions {
+    readonly deadlineMs?: number;
+    readonly observedAt?: string;
+    /** Test seam; production uses the monotonic wall clock. */
+    readonly now?: () => number;
+}
+/**
+ * Records one bounded local lifecycle observation. It never reads transcripts,
+ * starts a host/model/network/index, writes a checkpoint, or continues a run.
+ */
+export declare function runHostHook(input: HostHookInput, options?: HostHookOptions): Promise<HostHookResult>;
+export declare function readHookInput(stream: AsyncIterable<Uint8Array | string>, maxBytes?: number, deadlineMs?: number): Promise<{
+    readonly ok: true;
+    readonly bytes: Buffer;
+} | {
+    readonly ok: false;
+    readonly diagnostic: Diagnostic;
+}>;
+export declare function readBoundedHookFile(path: string): Promise<Buffer | null>;