@phyzess/pappra 0.1.0-beta.2 → 0.1.0-beta.3

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

@@ -12,6 +12,8 @@ export interface HostTargetOptions {
     readonly hostRoot?: string;
     readonly runtimeEntry?: string;
     readonly hostVersion?: string | null;
+    /** Rewrites a manifest previously pinned to a package checkout path. */
+    readonly migrate?: boolean;
 }
 export interface HostPlanBundle {
     readonly plan: HostIntegrationPlan;

package/dist/hosts/integration/service.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { link, mkdir, open, realpath, rename, rm } from 'node:fs/promises';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createDiagnostic } from '../../schemas/diagnostics.js';
 import { diagnosticCodes } from '../../schemas/errors.js';
@@ -26,7 +26,20 @@ function now() {
 }
 function packageRuntimeEntry() {
     const packageJson = fileURLToPath(import.meta.resolve('@phyzess/pappra/package.json'));
-    return join(dirname(packageJson), 'dist', 'hosts', 'integration', 'hook-entry.js');
+    return join(dirname(packageJson), 'dist', 'hosts', 'integration', 'pappra-hook.mjs');
+}
+/**
+ * Uses the host's project placeholder when the hook copy lives inside the
+ * workspace, so a moved checkout or an evicted npx cache cannot break the hook.
+ */
+function hookTarget(host, workspaceRoot, hostRoot, hookSource) {
+    const installedPath = join(hostRoot, 'hooks', 'pappra-hook.mjs');
+    const relativePath = relative(workspaceRoot, installedPath);
+    const insideWorkspace = !relativePath.startsWith('..') && !isAbsolute(relativePath);
+    const expression = host === 'claude' && insideWorkspace
+        ? `\${CLAUDE_PROJECT_DIR}/${relativePath.split(sep).join('/')}`
+        : installedPath;
+    return { installedPath, expression, source: hookSource };
 }
 function diagnostic(code, message, source, hint) {
     return createDiagnostic({
@@ -211,7 +224,7 @@ function isExactManagedHook(value, commands) {
         typeof value.command === 'string' &&
         commands.has(value.command));
 }
-function managedConfig(host, existing, runtimeEntry, path) {
+function managedConfig(host, existing, hookExpression, path) {
     let base = {};
     if (existing !== null) {
         const parsed = parseJsonObject(existing, path);
@@ -219,7 +232,7 @@ function managedConfig(host, existing, runtimeEntry, path) {
             return parsed;
         base = parsed.value;
     }
-    const patch = renderHookConfigPatch(host, runtimeEntry);
+    const patch = renderHookConfigPatch(host, hookExpression);
     const rawHooks = base['hooks'];
     if (rawHooks !== undefined &&
         (typeof rawHooks !== 'object' ||
@@ -271,11 +284,11 @@ function managedConfig(host, existing, runtimeEntry, path) {
         bytes: Buffer.from(`${JSON.stringify(next, null, 2)}\n`),
     };
 }
-function validateManifestIdentity(manifest, host, hostRoot, configPath, runtimeEntry) {
+function validateManifestIdentity(manifest, host, hostRoot, configPath, hookExpression, migrate) {
     if (manifest.host !== host ||
         resolve(manifest.hostRoot) !== hostRoot ||
         manifest.configPath !== configPath ||
-        resolve(manifest.runtimeEntry) !== runtimeEntry) {
+        (!migrate && manifest.runtimeEntry !== hookExpression)) {
         return diagnostic(diagnosticCodes.host_install_conflict, `Host manifest identity does not match the selected target: ${hostRoot}`, join(hostRoot, BUNDLE_FILE), 'Inspect the manifest and target; Pappra does not adopt a foreign installation.');
     }
     const seen = new Set();
@@ -290,11 +303,11 @@ function validateManifestIdentity(manifest, host, hostRoot, configPath, runtimeE
     }
     return null;
 }
-function configHasExpectedHooks(host, bytes, runtimeEntry, path) {
+function configHasExpectedHooks(host, bytes, hookExpression, path) {
     const parsed = parseJsonObject(bytes, path);
     if (!parsed.ok)
         return false;
-    const patch = renderHookConfigPatch(host, runtimeEntry);
+    const patch = renderHookConfigPatch(host, hookExpression);
     const hooks = parsed.value['hooks'];
     if (typeof hooks !== 'object' || hooks === null || Array.isArray(hooks)) {
         return false;
@@ -329,7 +342,7 @@ function configHasExpectedHooks(host, bytes, runtimeEntry, path) {
     }
     return true;
 }
-function bundleManifestContent(bundle, hostRoot, runtimeEntry, configPath, files, observedAt) {
+function bundleManifestContent(bundle, hostRoot, hookExpression, configPath, files, observedAt) {
     return Buffer.from(`${JSON.stringify({
         schema: 'pappra/host-install/1',
         host: bundle.host,
@@ -337,7 +350,7 @@ function bundleManifestContent(bundle, hostRoot, runtimeEntry, configPath, files
         bundleDigest: bundle.bundleDigest,
         installedAt: observedAt,
         hostRoot,
-        runtimeEntry,
+        runtimeEntry: hookExpression,
         configPath,
         files: files.map((file) => ({
             path: file.path,
@@ -352,11 +365,13 @@ function bundleManifestContent(bundle, hostRoot, runtimeEntry, configPath, files
         trustRequired: true,
     }, null, 2)}\n`);
 }
-async function hostPlanFiles(host, hostRoot, runtimeEntry, observedAt) {
+async function hostPlanFiles(host, workspaceRoot, hostRoot, hookSource, observedAt, migrate = false) {
+    const target = hookTarget(host, workspaceRoot, hostRoot, hookSource);
     let payload;
     try {
         payload = await loadHostBundle(host, getPackageInfo().version, {
-            runtimeEntry,
+            hookSource,
+            hookExpression: target.expression,
             observedAt,
         });
     }
@@ -401,7 +416,7 @@ async function hostPlanFiles(host, hostRoot, runtimeEntry, observedAt) {
                 diagnostic: diagnostic(diagnosticCodes.host_install_conflict, `Host manifest is invalid and was preserved: ${manifestPath}`, manifestPath, 'Fix or remove the manifest explicitly; no managed file was overwritten.'),
             };
         }
-        const identityError = validateManifestIdentity(parsed.data, host, hostRoot, hostConfigRelativePath(host), runtimeEntry);
+        const identityError = validateManifestIdentity(parsed.data, host, hostRoot, hostConfigRelativePath(host), target.expression, migrate);
         if (identityError !== null) {
             return { ok: false, conflict: true, diagnostic: identityError };
         }
@@ -477,7 +492,7 @@ async function hostPlanFiles(host, hostRoot, runtimeEntry, observedAt) {
             };
         }
         const before = existing.ok ? existing.value.bytes : null;
-        const merged = managedConfig(host === 'codex' ? 'codex' : 'claude', before, runtimeEntry, configPath);
+        const merged = managedConfig(host === 'codex' ? 'codex' : 'claude', before, target.expression, configPath);
         if (!merged.ok) {
             return {
                 ...merged,
@@ -510,7 +525,7 @@ async function hostPlanFiles(host, hostRoot, runtimeEntry, observedAt) {
         })) {
         installedAt = installedManifest.installedAt;
     }
-    const manifest = bundleManifestContent(payload.bundle, hostRoot, runtimeEntry, hostConfigRelativePath(host), files, installedAt);
+    const manifest = bundleManifestContent(payload.bundle, hostRoot, target.expression, hostConfigRelativePath(host), files, installedAt);
     contents.set(BUNDLE_FILE, manifest);
     files.push({
         path: BUNDLE_FILE,
@@ -527,14 +542,14 @@ async function hostPlanFiles(host, hostRoot, runtimeEntry, observedAt) {
         configPath,
     };
 }
-function planFromFiles(host, workspaceRoot, hostRoot, runtimeEntry, bundleDigest, files) {
+function planFromFiles(host, workspaceRoot, hostRoot, hookExpression, bundleDigest, files) {
     return hostIntegrationPlanSchema.parse({
         schema: 'pappra/host-integration/1',
         planId: randomUUID(),
         host,
         workspaceRoot,
         hostRoot,
-        runtimeEntry,
+        runtimeEntry: hookExpression,
         bundleDigest,
         files,
         reloadRequired: true,
@@ -854,25 +869,26 @@ export class HostIntegrationService {
     }
     async plan(host, options = {}) {
         const hostRoot = resolve(options.hostRoot ?? join(this.#root, '.pappra', 'local', 'hosts', host));
-        const runtimeEntry = resolve(options.runtimeEntry ?? this.#runtimeEntry);
+        const hookSource = resolve(options.runtimeEntry ?? this.#runtimeEntry);
         const version = options.hostVersion ?? this.#hostVersion;
         if (!isSupportedVersion(host, version)) {
             throw new Error(`Host ${host} version ${version ?? '(unknown)'} is outside the pinned support matrix.`);
         }
-        if (!(await runtimeEntryReady(runtimeEntry))) {
-            throw new Error(`Fixed Pappra runtime entry is missing: ${runtimeEntry}`);
+        if (!(await runtimeEntryReady(hookSource))) {
+            throw new Error(`Bundled Pappra hook is missing: ${hookSource}`);
         }
-        const built = await hostPlanFiles(host, hostRoot, runtimeEntry, this.#observedAt);
+        const target = hookTarget(host, this.#root, hostRoot, hookSource);
+        const built = await hostPlanFiles(host, this.#root, hostRoot, hookSource, this.#observedAt, options.migrate === true);
         if (!built.ok)
             throw new Error(built.diagnostic.message);
-        return planFromFiles(host, this.#root, hostRoot, runtimeEntry, built.bundle.bundleDigest, built.files);
+        return planFromFiles(host, this.#root, hostRoot, target.expression, built.bundle.bundleDigest, built.files);
     }
     async install(host, options) {
         let plan;
         let contents;
         try {
             const hostRoot = resolve(options.hostRoot ?? join(this.#root, '.pappra', 'local', 'hosts', host));
-            const runtimeEntry = resolve(options.runtimeEntry ?? this.#runtimeEntry);
+            const hookSource = resolve(options.runtimeEntry ?? this.#runtimeEntry);
             const version = options.hostVersion ?? this.#hostVersion;
             if (!isSupportedVersion(host, version)) {
                 return hostIntegrationResultSchema.parse({
@@ -887,7 +903,7 @@ export class HostIntegrationService {
                     ],
                 });
             }
-            if (!(await runtimeEntryReady(runtimeEntry))) {
+            if (!(await runtimeEntryReady(hookSource))) {
                 return hostIntegrationResultSchema.parse({
                     schema: 'pappra/host-integration/1',
                     ok: false,
@@ -896,11 +912,12 @@ export class HostIntegrationService {
                     appliedFiles: [],
                     residualPaths: [],
                     diagnostics: [
-                        diagnostic(diagnosticCodes.host_unavailable, `Fixed Pappra runtime entry is missing: ${runtimeEntry}`, runtimeEntry, 'Install or select a complete Pappra runtime before wiring a host.'),
+                        diagnostic(diagnosticCodes.host_unavailable, `Bundled Pappra hook is missing: ${hookSource}`, hookSource, 'Install or select a complete Pappra runtime before wiring a host.'),
                     ],
                 });
             }
-            const built = await hostPlanFiles(host, hostRoot, runtimeEntry, this.#observedAt);
+            const target = hookTarget(host, this.#root, hostRoot, hookSource);
+            const built = await hostPlanFiles(host, this.#root, hostRoot, hookSource, this.#observedAt, options.migrate === true);
             if (!built.ok) {
                 return hostIntegrationResultSchema.parse({
                     schema: 'pappra/host-integration/1',
@@ -912,7 +929,7 @@ export class HostIntegrationService {
                     diagnostics: [built.diagnostic],
                 });
             }
-            plan = planFromFiles(host, this.#root, hostRoot, runtimeEntry, built.bundle.bundleDigest, built.files);
+            plan = planFromFiles(host, this.#root, hostRoot, target.expression, built.bundle.bundleDigest, built.files);
             contents = built.contents;
         }
         catch (error) {
@@ -1138,7 +1155,8 @@ export class HostIntegrationService {
             });
         }
         const expectedConfigPath = hostConfigRelativePath(host);
-        const identityError = validateManifestIdentity(manifest, host, hostRoot, expectedConfigPath, this.#runtimeEntry);
+        const target = hookTarget(host, this.#root, hostRoot, this.#runtimeEntry);
+        const identityError = validateManifestIdentity(manifest, host, hostRoot, expectedConfigPath, target.expression, false);
         if (identityError !== null) {
             return hostVerificationSchema.parse({
                 schema: 'pappra/host-verification/1',
@@ -1162,7 +1180,8 @@ export class HostIntegrationService {
         let currentBundle;
         try {
             currentBundle = await loadHostBundle(host, getPackageInfo().version, {
-                runtimeEntry: this.#runtimeEntry,
+                hookSource: this.#runtimeEntry,
+                hookExpression: target.expression,
                 observedAt: this.#observedAt,
             });
         }
@@ -1306,7 +1325,7 @@ export class HostIntegrationService {
             const config = await readFileBounded(configPath, DEFAULT_MAX_CONFIG_BYTES);
             if (!config.ok ||
                 manifestFiles.get(manifest.configPath) !== config.value.digest ||
-                !configHasExpectedHooks(host === 'codex' ? 'codex' : 'claude', config.value.bytes, this.#runtimeEntry, configPath)) {
+                !configHasExpectedHooks(host === 'codex' ? 'codex' : 'claude', config.value.bytes, target.expression, configPath)) {
                 status = 'conflict';
                 checks.push({
                     id: 'host.config',

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

@@ -5,7 +5,7 @@ export interface RenderedHostTemplate {
     readonly bytes: Buffer;
     readonly kind: 'extension' | 'hook';
 }
-export declare function renderHookCommand(host: HostName, event: HostLifecycleEvent, runtimeEntry: string): string;
+export declare function renderHookCommand(host: HostName, event: HostLifecycleEvent, hookExpression: string): string;
 interface HookEntry {
     readonly hooks: readonly {
         readonly type: 'command';
@@ -13,10 +13,10 @@ interface HookEntry {
         readonly timeout: number;
     }[];
 }
-export declare function renderHookConfigPatch(host: 'codex' | 'claude', runtimeEntry: string): {
+export declare function renderHookConfigPatch(host: 'codex' | 'claude', hookExpression: string): {
     readonly hooks: Record<string, readonly HookEntry[]>;
 };
-export declare function renderHostTemplate(host: HostName, runtimeEntry: string): RenderedHostTemplate;
+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

@@ -1,18 +1,24 @@
-import { pathToFileURL } from 'node:url';
-import { basename, dirname } from 'node:path';
+import { basename } from 'node:path';
 export const PAPPRA_MANAGED_MARKER = 'pappra-managed';
 function shellQuote(value) {
     return `'${value.replaceAll("'", "'\\''")}'`;
 }
-export function renderHookCommand(host, event, runtimeEntry) {
-    return `${shellQuote(process.execPath)} ${shellQuote(runtimeEntry)} ${shellQuote(host)} ${shellQuote(event)} # ${PAPPRA_MANAGED_MARKER}`;
+/**
+ * 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, runtimeEntry) {
+export function renderHookConfigPatch(host, hookExpression) {
     const entry = (event) => ({
         hooks: [
             {
                 type: 'command',
-                command: renderHookCommand(host, event, runtimeEntry),
+                command: renderHookCommand(host, event, hookExpression),
                 timeout: 1,
             },
         ],
@@ -30,15 +36,14 @@ export function renderHookConfigPatch(host, runtimeEntry) {
             },
         };
 }
-export function renderHostTemplate(host, runtimeEntry) {
+export function renderHostTemplate(host, hookExpression) {
     if (host === 'pi') {
-        const runtimeUrl = pathToFileURL(`${dirname(runtimeEntry)}/pi-extension-runtime.js`).href;
         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 ${JSON.stringify(runtimeUrl)};
+import { createPiExtension } from "./runtime.mjs";
 
 export default function (pi: ExtensionAPI): void {
   createPiExtension(pi);
@@ -50,7 +55,7 @@ export default function (pi: ExtensionAPI): void {
             kind: 'extension',
         };
     }
-    const patch = renderHookConfigPatch(host, runtimeEntry);
+    const patch = renderHookConfigPatch(host, hookExpression);
     return {
         path: `templates/${host}/hooks.json`,
         bytes: Buffer.from(`${JSON.stringify(patch, null, 2)}\n`),