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

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

@@ -4,11 +4,13 @@ export declare const hostUsage: string;
 export interface HostCommandOptions {
     readonly cwd: string;
     readonly json: boolean;
-    readonly action: 'detect' | 'describe' | 'plan' | 'install' | 'verify' | 'bundle' | null;
+    readonly action: 'detect' | 'describe' | 'plan' | 'install' | 'verify' | 'bundle' | 'mcp' | 'probe' | null;
     readonly host: HostName | null;
     readonly hostRoot: string | null;
     readonly hostVersion: string | null;
     readonly apply: boolean;
+    readonly force: boolean;
+    readonly subAction: string | null;
     readonly out: string | null;
     readonly mode: 'project-settings' | 'plugin' | null;
     readonly marketplace: boolean;

package/dist/cli/commands/host.js

@@ -2,9 +2,11 @@ import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { HostIntegrationService } from '../../hosts/integration/service.js';
 import { exportHostPluginBundle } from '../../hosts/integration/bundle-export.js';
+import { applyHostMcp, planHostMcp, verifyHostMcp, } from '../../app/host-mcp.js';
+import { probeHost } from '../../app/host-probe.js';
 import { HOST_SUPPORT, isSupportedVersion, } from '../../hosts/integration/support.js';
 import { getPackageInfo } from '../../package-info.js';
-export const hostUsage = 'pappra host <detect|describe|plan|install|verify|bundle> --host <pi|codex|claude>\n' +
+export const hostUsage = 'pappra host <detect|describe|plan|install|verify|bundle|mcp> --host <pi|codex|claude>\n' +
     '  [--host-root <dir>] [--host-version <version>] [--out <dir>]\n' +
     '  [--mode project-settings|plugin] [--apply] [--json]\n' +
     '\n' +
@@ -80,6 +82,58 @@ export async function runHostCommand(options, output) {
             ? {}
             : { hostVersion: options.hostVersion }),
     };
+    if (options.action === 'mcp') {
+        if (options.subAction !== 'plan' &&
+            options.subAction !== 'install' &&
+            options.subAction !== 'verify') {
+            output.stderr('pappra host mcp requires plan, install, or verify.\n');
+            return 2;
+        }
+        const mcpPlan = await planHostMcp(options.host, options.cwd);
+        const result = options.subAction === 'verify'
+            ? await verifyHostMcp(mcpPlan)
+            : options.subAction === 'install' && options.apply
+                ? await applyHostMcp(mcpPlan, { force: options.force })
+                : {
+                    ...mcpPlan,
+                    applied: false,
+                    verified: false,
+                    detail: null,
+                };
+        if (options.json) {
+            output.stdout(`${JSON.stringify({ schema: 'pappra/host-mcp/1', ...result })}\n`);
+        }
+        else {
+            output.stdout(`Host ${result.host} MCP: ${result.state}\n`);
+            if (result.target !== null)
+                output.stdout(`  target: ${result.target}\n`);
+            if (result.command !== null) {
+                output.stdout(`  command: ${result.command.join(' ')}\n`);
+            }
+            output.stdout(`  ${result.message}\n`);
+            if (result.detail !== null)
+                output.stdout(`  detail: ${result.detail}\n`);
+            if (options.subAction === 'install' && !options.apply) {
+                output.stdout('  plan only; rerun with --apply to write it.\n');
+            }
+        }
+        return result.verified || (!options.apply && options.subAction !== 'verify')
+            ? 0
+            : 1;
+    }
+    if (options.action === 'probe') {
+        const result = probeHost(options.host);
+        if (options.json) {
+            output.stdout(`${JSON.stringify({ schema: 'pappra/host-probe/1', ...result })}\n`);
+        }
+        else {
+            output.stdout(`Host ${result.host} probe: ${result.ok ? 'ok' : 'failed'}\n`);
+            output.stdout(`  version: ${result.version ?? '(missing)'} / pinned ${result.pinnedVersion}\n`);
+            output.stdout(`  protocol: ${result.protocol}\n`);
+            output.stdout(`  ${result.message}\n`);
+        }
+        return result.ok ? 0 : 1;
+    }
     if (options.action === 'detect' || options.action === 'describe') {
         const capabilities = service.describe(options.host);
         if (options.json) {

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

@@ -1,6 +1,4 @@
-import type { Diagnostic } from '../../schemas/diagnostics.js';
 import { type InitChoices } from '../../schemas/init.js';
-import { type RuntimeInstallResult } from '../../install/runtime.js';
 import { type InitContext } from '../../app/init.js';
 import type { CliOutput } from '../output.js';
 export interface SelectOption {
@@ -41,12 +39,6 @@ export interface InitCommandOptions {
     /** Rebuilds workspace.json from the selections even when a valid config exists. */
     readonly reconfigure?: boolean;
 }
-export interface RuntimeFlowResult {
-    readonly ok: boolean;
-    readonly completion: boolean;
-    readonly runtime: RuntimeInstallResult | null;
-    readonly diagnostics: readonly Diagnostic[];
-}
 export interface InitCommandDeps {
     readonly ui?: WizardUi;
     readonly interactive?: boolean;

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/mcp.d.ts

@@ -0,0 +1,8 @@
+import type { CliOutput } from '../output.js';
+export declare const mcpUsage: string;
+export interface McpCommandOptions {
+    readonly cwd: string;
+    readonly root: string | null;
+    readonly json: boolean;
+}
+export declare function runMcpCommand(options: McpCommandOptions, output: CliOutput): Promise<number>;

package/dist/cli/commands/mcp.js

@@ -0,0 +1,13 @@
+import { runMcpServer } from '../../mcp/server.js';
+export const mcpUsage = 'pappra mcp [--root <dir>] [--json]\n\n' +
+    'Starts the Pappra MCP server on stdio for the selected workspace. The server exposes\n' +
+    'read-only tools (workspace_status, resume, docs_list, docs_check, code_status,\n' +
+    'code_query, runtime_status). stdout carries MCP JSON-RPC; use --help outside a host.';
+export async function runMcpCommand(options, output) {
+    const root = options.root ?? options.cwd;
+    if (options.json) {
+        output.stderr('pappra mcp: --json is not used; the server speaks MCP JSON-RPC on stdout.\n');
+    }
+    await runMcpServer(root);
+    return 0;
+}

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/commands/task.d.ts

@@ -0,0 +1,10 @@
+import type { CliOutput } from '../output.js';
+export declare const taskUsage: string;
+export interface TaskCommandOptions {
+    readonly cwd: string;
+    readonly action: 'pin' | 'unpin' | 'show' | null;
+    readonly taskId: string | null;
+    readonly autoResume: boolean;
+    readonly json: boolean;
+}
+export declare function runTaskCommand(options: TaskCommandOptions, output: CliOutput): Promise<number>;

package/dist/cli/commands/task.js

@@ -0,0 +1,76 @@
+import { resolveWorkspaceRoot } from '../../workspace/resolve.js';
+import { pinTask, readAutoResume, readTaskPin, setAutoResume, unpinTask, } from '../../app/task-pin.js';
+export const taskUsage = 'pappra task <pin|unpin|show> [taskId] [--auto-resume] [--json]\n\n' +
+    'pin records the current task in .pappra/local/current-task. Hooks inject a resume\n' +
+    'packet only when the workspace continuity.autoResume switch is on (--auto-resume).';
+function failure(output, options, message) {
+    if (options.json) {
+        output.stdout(`${JSON.stringify({ ok: false, code: 'task_invalid', message })}\n`);
+    }
+    else {
+        output.stderr(`pappra task: ${message}\n`);
+    }
+    return 2;
+}
+export async function runTaskCommand(options, output) {
+    const resolution = await resolveWorkspaceRoot({ startPath: options.cwd });
+    const root = resolution.root;
+    if (root === null) {
+        return failure(output, options, 'task requires a registered Pappra workspace above the current directory.');
+    }
+    if (options.action === 'pin') {
+        if (options.taskId === null) {
+            return failure(output, options, 'task pin requires a task id.');
+        }
+        const pinned = await pinTask(root, options.taskId);
+        if ('message' in pinned) {
+            return failure(output, options, pinned.message);
+        }
+        if (options.autoResume) {
+            const switched = await setAutoResume(root, true);
+            if ('message' in switched) {
+                return failure(output, options, switched.message);
+            }
+        }
+        const report = {
+            ok: true,
+            action: 'pin',
+            task: pinned.taskId,
+            autoResume: options.autoResume ? true : await readAutoResume(root),
+        };
+        output.stdout(options.json
+            ? `${JSON.stringify(report)}\n`
+            : `Pinned task ${report.task}; autoResume ${report.autoResume ? 'on' : 'off'}.\n`);
+        return 0;
+    }
+    if (options.action === 'unpin') {
+        await unpinTask(root);
+        const report = { ok: true, action: 'unpin' };
+        output.stdout(options.json
+            ? `${JSON.stringify(report)}\n`
+            : 'Task pin removed; autoResume stays unchanged.\n');
+        return 0;
+    }
+    if (options.action === 'show') {
+        const pin = await readTaskPin(root);
+        const report = {
+            ok: true,
+            action: 'show',
+            pin,
+            autoResume: await readAutoResume(root),
+        };
+        output.stdout(options.json
+            ? `${JSON.stringify(report)}\n`
+            : pin === null
+                ? `No task pin; autoResume ${report.autoResume ? 'on' : 'off'}.\n`
+                : `Pinned task ${pin.taskId} at ${pin.pinnedAt}; autoResume ${report.autoResume ? 'on' : 'off'}.\n`);
+        return 0;
+    }
+    if (options.json) {
+        output.stdout(`${JSON.stringify({ commands: ['pin', 'unpin', 'show'], usage: taskUsage })}\n`);
+    }
+    else {
+        output.stdout(taskUsage);
+    }
+    return 0;
+}