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

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 ||