@phyzess/pappra 0.1.0-beta.4 → 0.1.0-beta.6

package/README.md

@@ -63,7 +63,7 @@ requires an explicit controller. They are not needed for the core workflow above
 - **Knowledge:** workspace and private document catalogs with explicit preview/apply operations.
 - **Continuity:** private task checkpoints and bounded advisory resume packets. Resume never grants execution by itself.
 - **Code intelligence:** status, explicit preparation and bounded query for selected repositories. Text/structure fallback is available when the optional graph engine is absent.
-- **Host integrations:** optional Pi, Codex and Claude Code adapters that merge Pappra-owned entries without taking over user configuration. Hooks are copied as a dependency-free bundle into the host root; `host bundle` exports a native plugin/package directory without registering it. `host install --mode plugin` fails closed until plugin registration and callability are verified.
+- **Host integrations:** optional Pi, Codex and Claude Code adapters that merge Pappra-owned entries without taking over user configuration. Hooks are copied as a dependency-free bundle into the host root; `host bundle --marketplace` exports a local marketplace that Claude Code and Codex accept, without registering it. `host install --mode plugin` fails closed with per-host evidence; see [host plugin validation](docs/host-plugin-validation.md).
 - **Bounded collaboration:** an optional, explicitly controlled one-request workflow. It is not a scheduler or daemon.
 
 ## Optional integrations and support
@@ -87,7 +87,7 @@ The check runs the source policy, type checks, formatting, deterministic tests a
 
 ## Status and limits
 
-Pappra is development software (`0.1.0-beta.4`) published as `@phyzess/pappra` under the `beta` dist-tag. Releases are published from GitHub Actions with npm trusted publishing (OIDC), so no npm token is stored in this repository. Pin either the moving `beta` tag or an exact version such as `@phyzess/pappra@0.1.0-beta.4`, because pre-release versions are never republished.
+Pappra is development software (`0.1.0-beta.6`) published as `@phyzess/pappra` under the `beta` dist-tag. Releases are published from GitHub Actions with npm trusted publishing (OIDC), so no npm token is stored in this repository. Pin either the moving `beta` tag or an exact version such as `@phyzess/pappra@0.1.0-beta.6`, because pre-release versions are never republished.
 
 The deterministic suite covers synthetic workspaces, fixtures and local process boundaries. It does not establish real-model behavior, native host callability on every platform, CodeGraph completeness, Windows/Linux parity or production performance. A host adapter version pin is an observed support claim, not proof that a particular native installation will load or run correctly.
 

package/dist/cli/commands/host.d.ts

@@ -11,5 +11,6 @@ export interface HostCommandOptions {
     readonly apply: boolean;
     readonly out: string | null;
     readonly mode: 'project-settings' | 'plugin' | null;
+    readonly marketplace: boolean;
 }
 export declare function runHostCommand(options: HostCommandOptions, output: CliOutput): Promise<number>;

package/dist/cli/commands/host.js

@@ -133,6 +133,7 @@ export async function runHostCommand(options, output) {
                 hostVersion: options.hostVersion ?? HOST_SUPPORT[options.host].version,
                 outDir: options.out,
                 packageVersion: getPackageInfo().version,
+                marketplace: options.marketplace,
             });
             if (options.json) {
                 output.stdout(`${JSON.stringify({ ok: true, command: 'host', action: 'bundle', ...exported })}\n`);

package/dist/cli/run.js

@@ -25,6 +25,7 @@ function parseOptions(args) {
             tarball: { type: 'string' },
             out: { type: 'string' },
             mode: { type: 'string' },
+            marketplace: { type: 'boolean' },
             bind: { type: 'boolean' },
             force: { type: 'boolean' },
             'no-interactive': { type: 'boolean' },
@@ -250,6 +251,10 @@ export async function runCli(args, output) {
         failure(output, json, 'invalid_arguments', '--out is only valid for host.');
         return 2;
     }
+    if (command !== 'host' && values.marketplace === true) {
+        failure(output, json, 'invalid_arguments', '--marketplace is only valid for host bundle.');
+        return 2;
+    }
     if (command !== 'host' &&
         values.mode !== undefined &&
         command !== 'runtime') {
@@ -659,6 +664,7 @@ export async function runCli(args, output) {
             hasContinuityOptions(values) ||
             (values.apply === true && action !== 'install') ||
             (values.mode !== undefined && action !== 'install') ||
+            (values.marketplace === true && action !== 'bundle') ||
             (values['host-root'] !== undefined && action === null) ||
             (values['host-version'] !== undefined && action === null);
         if (values.help) {
@@ -686,6 +692,7 @@ export async function runCli(args, output) {
             mode: values.mode === 'project-settings' || values.mode === 'plugin'
                 ? values.mode
                 : null,
+            marketplace: values.marketplace === true,
         }, output);
     }
     if (command !== null) {

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

@@ -19,4 +19,6 @@ export declare function exportHostPluginBundle(options: {
     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

@@ -10,24 +10,15 @@ function pluginHookExpression(host) {
         : './hooks/pappra-hook.mjs';
 }
 function hostManifest(host, version) {
-    if (host === 'claude') {
+    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.',
-                hooks: './hooks/hooks.json',
-            },
-        };
-    }
-    if (host === 'codex') {
-        return {
-            path: 'plugin.json',
-            value: {
-                name: 'pappra',
-                version,
-                description: 'Portable workspace knowledge and continuity for coding agents.',
+                author: { name: 'phyzess' },
                 hooks: './hooks/hooks.json',
             },
         };
@@ -53,15 +44,20 @@ function hostManifest(host, version) {
  * load or trust it.
  */
 export async function exportHostPluginBundle(options) {
-    const outDir = resolve(options.outDir);
+    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(outDir, ...path.split('/'));
-        if (!isPathInside(outDir, target)) {
+        const target = join(outRoot, ...path.split('/'));
+        if (!isPathInside(outRoot, target)) {
             throw new Error(`Unsafe plugin bundle path: ${path}`);
         }
         await mkdir(dirname(target), { recursive: true });
@@ -71,30 +67,48 @@ export async function exportHostPluginBundle(options) {
     for (const [path, bytes] of payload.contents) {
         // Plugin manifests point at hooks/hooks.json directly; the rendered
         // templates are only an intermediate artifact.
-        if (options.host !== 'pi' && path.startsWith('templates/'))
+        if (path.startsWith('templates/'))
             continue;
-        await writeEntry(path, bytes);
+        await writeEntry(`${pluginPrefix}${path}`, bytes);
     }
     const expression = pluginHookExpression(options.host);
     if (options.host === 'pi') {
         const entry = payload.contents.get('templates/pi/entry.ts');
-        if (entry === undefined) {
+        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.');
         }
-        await writeEntry('extensions/pappra/index.ts', 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('hooks/hooks.json', Buffer.from(`${JSON.stringify(patch, null, 2)}\n`));
+        await writeEntry(`${pluginPrefix}hooks/hooks.json`, Buffer.from(`${JSON.stringify(patch, null, 2)}\n`));
     }
     const manifest = hostManifest(options.host, options.packageVersion);
-    await writeEntry(manifest.path, Buffer.from(`${JSON.stringify(manifest.value, null, 2)}\n`));
+    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,
+        outDir: pluginRoot,
         files: written.sort((left, right) => left.localeCompare(right)),
-        pluginManifest: manifest.path,
-        hookConfig: options.host === 'pi' ? null : 'hooks/hooks.json',
+        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.',

package/dist/hosts/integration/service.js

@@ -12,7 +12,7 @@ import { getPackageInfo } from '../../package-info.js';
 import { detectPassiveHosts } from '../detect.js';
 import { installPathForBundleFile, loadHostBundle } from './bundle.js';
 import { hostConfigRelativePath, renderHookConfigPatch } from './templates.js';
-import { HOST_SUPPORT, isSupportedVersion, nativeEventFor, surfaceFor, } from './support.js';
+import { HOST_PLUGIN_HOOKS, HOST_SUPPORT, isSupportedVersion, nativeEventFor, surfaceFor, } from './support.js';
 const LIFECYCLE_EVENTS = [
     'startup',
     'resume',
@@ -885,6 +885,12 @@ export class HostIntegrationService {
     }
     async install(host, options) {
         if (options.mode === 'plugin') {
+            const support = HOST_PLUGIN_HOOKS[host];
+            const guidance = support.state === 'verified'
+                ? 'Export the package with `pappra host bundle --host pi --out <dir> --json`, then run `pi install <dir> -l -a`; project-settings install is still available with --mode project-settings.'
+                : support.state === 'unsupported'
+                    ? 'This host does not load plugin hooks at its pinned version; keep --mode project-settings. See docs/host-plugin-validation.md.'
+                    : 'Plugin hooks are not verified for this host yet; an authenticated lifecycle session is required. Use --mode project-settings meanwhile.';
             return hostIntegrationResultSchema.parse({
                 schema: 'pappra/host-integration/1',
                 ok: false,
@@ -893,7 +899,7 @@ export class HostIntegrationService {
                 appliedFiles: [],
                 residualPaths: [],
                 diagnostics: [
-                    diagnostic(diagnosticCodes.host_unavailable, 'Plugin install mode is not wired: host registration, trust and callability are unverified.', this.#root, 'Use `pappra host bundle --host <name> --out <dir>` to export the plugin directory and register it yourself; project-settings install remains the verified mode.'),
+                    diagnostic(diagnosticCodes.host_unavailable, `Plugin install mode is not wired for ${host}: ${support.state}. ${support.evidence}`, this.#root, guidance),
                 ],
             });
         }

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

@@ -34,3 +34,23 @@ export declare const HOST_SUPPORT: {
 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: 'unverified';
+        readonly evidence: 'Claude Code 2.1.292 validation passes, but no authenticated session was available to run a lifecycle event.';
+    };
+};

package/dist/hosts/integration/support.js

@@ -39,3 +39,23 @@ export function isSupportedVersion(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: 'unverified',
+        evidence: 'Claude Code 2.1.292 validation passes, but no authenticated session was available to run a lifecycle event.',
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phyzess/pappra",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.6",
   "description": "Portable workspace knowledge and continuity for coding agents.",
   "publishConfig": {
     "access": "public"