@phyzess/pappra 0.1.0-beta.10 → 0.1.0-beta.12

package/dist/cli/commands/init.js

@@ -2,12 +2,10 @@ import { basename, resolve } from 'node:path';
 import * as prompts from '@clack/prompts';
 import { diagnosticCodes } from '../../schemas/errors.js';
 import { INIT_CHOICES_SCHEMA, parseInitChoices, } from '../../schemas/init.js';
-import { observePath, readTextFileBounded } from '../../infra/fs.js';
-import { getPackageInfo, getPackageRoot } from '../../package-info.js';
-import { installRuntime, } from '../../install/runtime.js';
-import { updateMachineRuntime } from '../../install/apply.js';
-import { inspectMachineConfig } from '../../workspace/config.js';
-import { applyInitPlan, inspectInitContext, listKnowledgeCandidates, deriveInitChoices, listRepositoryCandidates, planWorkspaceInit, } from '../../app/init.js';
+import { readTextFileBounded } from '../../infra/fs.js';
+import { getPackageInfo } from '../../package-info.js';
+import { installRuntime } from '../../install/runtime.js';
+import { applyInitPlan, bindAndRecordRuntime, ensureDefaultRuntime, inspectInitContext, listKnowledgeCandidates, deriveInitChoices, listRepositoryCandidates, planWorkspaceInit, } from '../../app/init.js';
 export const clackWizardUi = {
     intro: (message) => prompts.intro(message),
     outro: (message) => prompts.outro(message),
@@ -250,84 +248,6 @@ function runtimeOptionsFailure(message, nextAction) {
         nextAction,
     };
 }
-async function bindAndRecordRuntime(root, installed) {
-    if (!installed.ok || installed.manifest === null) {
-        return {
-            ok: false,
-            completion: false,
-            runtime: installed,
-            diagnostics: installed.diagnostics,
-        };
-    }
-    const updated = await updateMachineRuntime(root, installed.manifest);
-    if (!updated.ok) {
-        return {
-            ok: false,
-            completion: false,
-            runtime: installed,
-            diagnostics: updated.diagnostics,
-        };
-    }
-    const followUp = await planWorkspaceInit({ root });
-    if (!followUp.ok) {
-        return {
-            ok: false,
-            completion: false,
-            runtime: installed,
-            diagnostics: followUp.diagnostics,
-        };
-    }
-    if (followUp.bundle.plan.files.length > 0 ||
-        followUp.bundle.plan.externalActions.length > 0) {
-        return {
-            ok: false,
-            completion: false,
-            runtime: installed,
-            diagnostics: [
-                {
-                    code: diagnosticCodes.initRuntimeSourceRequired,
-                    severity: 'error',
-                    message: 'Runtime installation succeeded but init still has pending file or external actions.',
-                    source: 'init runtime',
-                    pointer: null,
-                    hint: 'Run pappra init again to review the remaining plan; initialization is not complete.',
-                },
-            ],
-        };
-    }
-    return {
-        ok: true,
-        completion: true,
-        runtime: installed,
-        diagnostics: [],
-    };
-}
-/**
- * Converges the runtime binding by installing a durable copy of the package that
- * is currently executing. Reusing an already verified copy is cheap: the install
- * machinery short-circuits before packing.
- */
-async function ensureDefaultRuntime(root, targetVersion) {
-    const machine = await inspectMachineConfig(root);
-    const binding = machine.value?.runtime ?? null;
-    if (binding !== null && binding.version === targetVersion) {
-        const executable = await observePath(binding.executable);
-        if (executable.kind === 'file') {
-            return {
-                ok: true,
-                completion: true,
-                runtime: null,
-                diagnostics: [],
-            };
-        }
-    }
-    const installed = await installRuntime({
-        version: targetVersion,
-        source: { kind: 'self', path: getPackageRoot() },
-        packageName: getPackageInfo().name,
-    });
-    return bindAndRecordRuntime(root, installed);
-}
 async function installAndRecordRuntime(root, targetVersion, options) {
     const tarball = options.runtimeTarball ?? null;
     const requestedVersion = options.runtimeVersion ?? null;
@@ -400,48 +320,7 @@ async function installAndRecordRuntime(root, targetVersion, options) {
             diagnostics: installed.diagnostics,
         };
     }
-    const updated = await updateMachineRuntime(root, installed.manifest);
-    if (!updated.ok) {
-        return {
-            ok: false,
-            completion: false,
-            runtime: installed,
-            diagnostics: updated.diagnostics,
-        };
-    }
-    const followUp = await planWorkspaceInit({ root });
-    if (!followUp.ok) {
-        return {
-            ok: false,
-            completion: false,
-            runtime: installed,
-            diagnostics: followUp.diagnostics,
-        };
-    }
-    if (followUp.bundle.plan.files.length > 0 ||
-        followUp.bundle.plan.externalActions.length > 0) {
-        return {
-            ok: false,
-            completion: false,
-            runtime: installed,
-            diagnostics: [
-                {
-                    code: diagnosticCodes.initRuntimeSourceRequired,
-                    severity: 'error',
-                    message: 'Runtime installation succeeded but init still has pending file or external actions.',
-                    source: 'init runtime',
-                    pointer: null,
-                    hint: 'Run pappra init again to review the remaining plan; initialization is not complete.',
-                },
-            ],
-        };
-    }
-    return {
-        ok: true,
-        completion: true,
-        runtime: installed,
-        diagnostics: [],
-    };
+    return bindAndRecordRuntime(root, installed);
 }
 function formatFailure(failure) {
     switch (failure.status) {

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

@@ -0,0 +1,14 @@
+import type { CliOutput } from '../output.js';
+export declare const onboardUsage: string;
+export interface OnboardCommandOptions {
+    readonly cwd: string;
+    readonly root: string | null;
+    readonly configPath: string | null;
+    readonly hosts: string | null;
+    readonly apply: boolean;
+    readonly applyHosts: boolean;
+    readonly dryRun: boolean;
+    readonly printHandoff: boolean;
+    readonly json: boolean;
+}
+export declare function runOnboardCommand(options: OnboardCommandOptions, output: CliOutput): Promise<number>;

package/dist/cli/commands/onboard.js

@@ -0,0 +1,225 @@
+import { readTextFileBounded } from '../../infra/fs.js';
+import { parseInitChoices } from '../../schemas/init.js';
+import { getPackageInfo } from '../../package-info.js';
+import { applyOnboard, parseHostList, planOnboard, } from '../../app/onboard.js';
+export const onboardUsage = 'pappra onboard [--root <dir>] [--config <file>] [--hosts claude,codex,pi]\n' +
+    '  [--yes] [--apply-host] [--dry-run] [--print-handoff] [--json]\n\n' +
+    'Plans (default) or applies a workspace setup: init files, durable runtime, and with\n' +
+    '--apply-host the verified host wiring. Trust prompts are never approved automatically.\n' +
+    '--print-handoff lists the files to copy to another machine and the commands to run there.';
+function printDiagnostics(output, diagnostics) {
+    for (const entry of diagnostics) {
+        output.stderr(`  ${entry.severity} ${entry.code}: ${entry.message}\n`);
+    }
+}
+function failureExit(failure) {
+    return failure.reason === 'invalid'
+        ? 2
+        : failure.reason === 'unavailable'
+            ? 3
+            : 1;
+}
+function writeFailure(output, options, failure) {
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            schema: 'pappra/onboard/1',
+            ok: false,
+            dryRun: !options.apply,
+            reason: failure.reason,
+            message: failure.message,
+            diagnostics: failure.diagnostics,
+        })}\n`);
+    }
+    else {
+        output.stderr(`pappra onboard: ${failure.message}\n`);
+        printDiagnostics(output, failure.diagnostics);
+    }
+    return failureExit(failure);
+}
+async function loadChoices(path) {
+    const read = await readTextFileBounded(path);
+    if (!read.ok) {
+        return {
+            ok: false,
+            failure: {
+                ok: false,
+                reason: 'unavailable',
+                message: read.message,
+                diagnostics: [],
+            },
+        };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(read.value.text);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            failure: {
+                ok: false,
+                reason: 'invalid',
+                message: `Invalid onboard config JSON: ${error instanceof Error ? error.message : String(error)}`,
+                diagnostics: [],
+            },
+        };
+    }
+    const parsed = parseInitChoices(raw, path);
+    if (parsed.value === null) {
+        return {
+            ok: false,
+            failure: {
+                ok: false,
+                reason: 'invalid',
+                message: parsed.diagnostics[0]?.message ??
+                    'Onboard config does not match pappra/init-choices/1.',
+                diagnostics: parsed.diagnostics,
+            },
+        };
+    }
+    return { ok: true, choices: parsed.value };
+}
+function plannedHosts(plan) {
+    return plan.hosts.map((host) => ({
+        ...host,
+        action: 'planned',
+        appliedFiles: [],
+        nextActions: ['Rerun with --apply-host to write this host integration.'],
+        diagnostics: [],
+    }));
+}
+function planReport(plan) {
+    const nextActions = ['Rerun with --yes to apply this plan.'];
+    if (plan.choices.knowledge.sources.length > 0) {
+        nextActions.push('pappra docs scan --apply');
+    }
+    if (plan.choices.code.graph !== 'none' &&
+        plan.choices.repositories.length > 0) {
+        nextActions.push('pappra code prepare --repo <repo> --apply');
+    }
+    return {
+        schema: 'pappra/onboard/1',
+        ok: true,
+        dryRun: true,
+        workspaceRoot: plan.bundle.scope.workspaceRoot,
+        files: plan.bundle.plan.files.map((file) => ({
+            path: file.path,
+            operation: file.operation,
+        })),
+        runtime: {
+            version: plan.bundle.scope.runtimeVersion,
+            status: 'pending',
+        },
+        initComplete: false,
+        hosts: plannedHosts(plan),
+        manualSteps: plan.hosts.map((host) => `${host.command}: detected ${host.detectedVersion ?? '(missing)'}, pinned ${host.pinnedVersion} (${host.state})`),
+        nextActions,
+        diagnostics: plan.bundle.diagnostics.filter((entry) => entry.severity !== 'info'),
+    };
+}
+function printResult(output, result) {
+    output.stdout(`Workspace: ${result.workspaceRoot}\n`);
+    output.stdout(`Status: ${result.initComplete ? 'complete' : 'planned'}\n`);
+    for (const file of result.files) {
+        output.stdout(`  ${file.operation} ${file.path}\n`);
+    }
+    if (result.runtime !== null) {
+        output.stdout(`Runtime: ${result.runtime.status} ${result.runtime.version}\n`);
+    }
+    for (const host of result.hosts) {
+        output.stdout(`Host ${host.host}: detected ${host.detectedVersion ?? '(missing)'} / pinned ${host.pinnedVersion} (${host.state}) -> ${host.action}\n`);
+    }
+    for (const step of result.manualSteps) {
+        output.stdout(`  manual: ${step}\n`);
+    }
+    for (const action of result.nextActions) {
+        output.stdout(`  next: ${action}\n`);
+    }
+    printDiagnostics(output, result.diagnostics);
+}
+function printHandoff(output, options, root) {
+    const report = {
+        schema: 'pappra/handoff/1',
+        workspaceRoot: root,
+        share: [
+            '.pappra/workspace.json',
+            '.pappra-choices.json (or the choices file used for onboard)',
+            'repository checkouts at the same relative paths',
+        ],
+        doNotCopy: [
+            '.pappra/local/machine.json',
+            '.pappra/local/code/*.json',
+            '.pappra/local/knowledge/catalog.json',
+            '.pappra/local/host-events/**',
+        ],
+        commands: [
+            `npm install -g @phyzess/pappra@${getPackageInfo().version}`,
+            `cd ${root}`,
+            'pappra onboard --yes --apply-host',
+            'pappra doctor --json',
+        ],
+    };
+    if (options.json) {
+        output.stdout(`${JSON.stringify(report)}\n`);
+    }
+    else {
+        output.stdout('Share:\n');
+        for (const entry of report.share)
+            output.stdout(`  ${entry}\n`);
+        output.stdout('Do not copy:\n');
+        for (const entry of report.doNotCopy)
+            output.stdout(`  ${entry}\n`);
+        output.stdout('On the new machine:\n');
+        for (const entry of report.commands)
+            output.stdout(`  ${entry}\n`);
+    }
+    return 0;
+}
+export async function runOnboardCommand(options, output) {
+    const root = options.root ?? options.cwd;
+    if (options.printHandoff) {
+        return printHandoff(output, options, root);
+    }
+    let hosts;
+    try {
+        hosts = parseHostList(options.hosts);
+    }
+    catch (error) {
+        return writeFailure(output, options, {
+            ok: false,
+            reason: 'invalid',
+            message: error instanceof Error ? error.message : String(error),
+            diagnostics: [],
+        });
+    }
+    let choices = null;
+    if (options.configPath !== null) {
+        const loaded = await loadChoices(options.configPath);
+        if (!loaded.ok)
+            return writeFailure(output, options, loaded.failure);
+        choices = loaded.choices;
+    }
+    const planned = await planOnboard({ root, choices, hosts });
+    if ('reason' in planned)
+        return writeFailure(output, options, planned);
+    if (!options.apply || options.dryRun) {
+        const report = planReport(planned);
+        if (options.json) {
+            output.stdout(`${JSON.stringify(report)}\n`);
+        }
+        else {
+            printResult(output, report);
+        }
+        return 0;
+    }
+    const result = await applyOnboard(planned, {
+        applyHosts: options.applyHosts,
+    });
+    if (options.json) {
+        output.stdout(`${JSON.stringify(result)}\n`);
+    }
+    else {
+        printResult(output, result);
+    }
+    return result.ok ? 0 : 1;
+}

package/dist/cli/run.js

@@ -1,6 +1,7 @@
 import { parseArgs } from 'node:util';
 import { getPackageInfo } from '../package-info.js';
 import { initUsage, runInitCommand } from './commands/init.js';
+import { onboardUsage, runOnboardCommand } from './commands/onboard.js';
 import { doctorUsage, runDoctorCommand } from './commands/doctor.js';
 import { docsUsage, runDocsCommand } from './commands/docs.js';
 import { checkpointUsage, resumeUsage, runCheckpointCommand, runResumeCommand, } from './commands/continuity.js';
@@ -21,6 +22,10 @@ function parseOptions(args) {
             yes: { type: 'boolean', short: 'y' },
             'no-runtime': { type: 'boolean' },
             reconfigure: { type: 'boolean' },
+            hosts: { type: 'string' },
+            'apply-host': { type: 'boolean' },
+            'dry-run': { type: 'boolean' },
+            'print-handoff': { type: 'boolean' },
             from: { type: 'string' },
             tarball: { type: 'string' },
             out: { type: 'string' },
@@ -216,6 +221,8 @@ function hasContinuityOptions(values, includeSession = true) {
         (includeSession && values.session !== undefined));
 }
 const globalUsage = 'pappra [--help | --version] [--json]\n' +
+    'pappra onboard [--root <dir>] [--config <file>] [--hosts <list>] [--yes]\n' +
+    '               [--apply-host] [--dry-run] [--print-handoff] [--json]\n' +
     'pappra init [--config <file> | --yes] [--apply] [--json] [--print-choices]\n' +
     '              [--install-runtime (--runtime-tarball <file> | --runtime-version <version>)]\n' +
     'pappra doctor [--root <path>] [--json]\n' +
@@ -240,12 +247,23 @@ export async function runCli(args, output) {
     const json = values.json === true;
     const applyRequested = values.apply === true;
     if (command !== 'init' &&
-        (values.yes === true ||
-            values['no-interactive'] === true ||
+        (values['no-interactive'] === true ||
             values['print-choices'] === true ||
             values['no-runtime'] === true ||
             values.reconfigure === true)) {
-        failure(output, json, 'invalid_arguments', '--yes, --no-interactive, --print-choices, --no-runtime and --reconfigure are only valid for init.');
+        failure(output, json, 'invalid_arguments', '--no-interactive, --print-choices, --no-runtime and --reconfigure are only valid for init.');
+        return 2;
+    }
+    if (command !== 'init' && command !== 'onboard' && values.yes === true) {
+        failure(output, json, 'invalid_arguments', '--yes is only valid for init and onboard.');
+        return 2;
+    }
+    if (command !== 'onboard' &&
+        (values.hosts !== undefined ||
+            values['apply-host'] === true ||
+            values['dry-run'] === true ||
+            values['print-handoff'] === true)) {
+        failure(output, json, 'invalid_arguments', '--hosts, --apply-host, --dry-run and --print-handoff are only valid for onboard.');
         return 2;
     }
     if (command !== 'host' && values.out !== undefined) {
@@ -398,6 +416,57 @@ export async function runCli(args, output) {
             json,
         }, output);
     }
+    if (command === 'onboard') {
+        if (values.apply === true ||
+            values['install-runtime'] === true ||
+            values['runtime-tarball'] !== undefined ||
+            values['runtime-version'] !== undefined ||
+            values['host-root'] !== undefined ||
+            values['host-version'] !== undefined ||
+            values.mode !== undefined ||
+            values.from !== undefined ||
+            values.tarball !== undefined ||
+            values.bind === true ||
+            values.force === true ||
+            values.marketplace === true ||
+            values.scope !== undefined ||
+            values.repo !== undefined ||
+            values.kind !== undefined ||
+            values.query !== undefined ||
+            values.limit !== undefined ||
+            values['max-bytes'] !== undefined ||
+            values.rebuild === true ||
+            values['include-private'] === true ||
+            values['include-archived'] === true ||
+            hasContinuityOptions(values)) {
+            failure(output, json, 'invalid_arguments', 'onboard accepts --root, --config, --hosts, --yes, --apply-host, --dry-run, --print-handoff, --help, and --json.');
+            return 2;
+        }
+        if (values.help) {
+            if (json) {
+                output.stdout(`${JSON.stringify({ ...info, commands: ['onboard'], usage: onboardUsage })}\n`);
+            }
+            else {
+                output.stdout(onboardUsage);
+            }
+            return 0;
+        }
+        if (values.version) {
+            failure(output, json, 'invalid_arguments', '--version cannot be combined with onboard.');
+            return 2;
+        }
+        return runOnboardCommand({
+            cwd: process.cwd(),
+            root: values.root ?? null,
+            configPath: values.config ?? null,
+            hosts: values.hosts ?? null,
+            apply: values.yes === true,
+            applyHosts: values['apply-host'] === true,
+            dryRun: values['dry-run'] === true,
+            printHandoff: values['print-handoff'] === true,
+            json,
+        }, output);
+    }
     if (command === 'init') {
         if (values.root !== undefined ||
             values['include-private'] === true ||

package/dist/code/service.js

@@ -177,7 +177,10 @@ async function observeCode(input) {
         : fallbackHealth('unsupported', raw.code, versionValue);
     if (!raw.ok)
         diagnostics.push(outcomeDiagnostic(raw, repository.root));
-    const registrationRead = await readCodeRegistration(repository.root, input.repositoryId);
+    // Registrations belong to the workspace, not to a repository checkout: writing
+    // <repo>/.pappra/local/code would make that checkout look like a nested workspace
+    // and hide it from the outer workspace discovery.
+    const registrationRead = await readCodeRegistration(input.root, input.repositoryId);
     let registration = null;
     let registrationFailure = null;
     if (registrationRead.ok) {
@@ -193,7 +196,7 @@ async function observeCode(input) {
         rawHealth,
         health,
         registration,
-        registrationPath: codeRegistrationPath(repository.root, input.repositoryId),
+        registrationPath: codeRegistrationPath(input.root, input.repositoryId),
         excludedRoots,
         access: repository.access,
         diagnostics,
@@ -345,9 +348,12 @@ export class CodeIntelligenceService {
                 diagnostics: [...observed.diagnostics],
             };
         }
-        const registrationTarget = codeRegistrationPath(observed.identity.root, observed.identity.repositoryId);
-        for (const target of [plan.indexPath, registrationTarget]) {
-            const boundary = await ensureCodeMutationBoundary(observed.identity.root, target, observed.excludedRoots);
+        const registrationTarget = codeRegistrationPath(input.root, observed.identity.repositoryId);
+        const boundaries = await Promise.all([
+            ensureCodeMutationBoundary(observed.identity.root, plan.indexPath, observed.excludedRoots),
+            ensureCodeMutationBoundary(input.root, registrationTarget),
+        ]);
+        for (const boundary of boundaries) {
             if (!boundary.ok) {
                 return {
                     schema: 'pappra/code-prepare-result/1',
@@ -364,12 +370,12 @@ export class CodeIntelligenceService {
                     registrationPath: null,
                     diagnostics: [
                         ...observed.diagnostics,
-                        outcomeDiagnostic(boundary, target),
+                        outcomeDiagnostic(boundary, registrationTarget),
                     ],
                 };
             }
         }
-        const lock = await acquireCodePrepareLock(observed.identity.root, observed.excludedRoots);
+        const lock = await acquireCodePrepareLock(input.root);
         if (!lock.ok) {
             return {
                 schema: 'pappra/code-prepare-result/1',
@@ -507,7 +513,7 @@ export class CodeIntelligenceService {
                 preparedAt: new Date().toISOString(),
                 coverage: prepared.value.coverage,
             };
-            const written = await writeCodeRegistration(afterIdentity.value.root, registration, observed.excludedRoots);
+            const written = await writeCodeRegistration(input.root, registration);
             if (!written.ok) {
                 return {
                     schema: 'pappra/code-prepare-result/1',