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

package/dist/cli/commands/runtime.js

@@ -0,0 +1,263 @@
+import { resolve } from 'node:path';
+import { getPackageInfo, getPackageRoot } from '../../package-info.js';
+import { inspectRuntimeState, inspectRuntimeStatePassive, installRuntime, removeRuntime, resolveUserDataDir, runtimePaths, } from '../../install/runtime.js';
+import { updateMachineRuntime } from '../../install/apply.js';
+import { inspectMachineConfig } from '../../workspace/config.js';
+import { resolveWorkspaceRoot } from '../../workspace/resolve.js';
+export const runtimeUsage = 'pappra runtime <install|status|verify|remove> [options] [--json]\n' +
+    '  install [--from self|tarball|registry] [--tarball <file>] [--runtime-version <v>]\n' +
+    '          [--apply] [--bind]\n' +
+    '  status\n' +
+    '  verify [--runtime-version <v>]\n' +
+    '  remove [--runtime-version <v>] --apply [--force]\n\n' +
+    'Install keeps a durable copy of the package outside the checkout. --from self packs the\n' +
+    'package that is currently executing, which is what makes an npx/dlx bootstrap survive\n' +
+    'cache eviction. Writes require --apply; --bind records the copy in machine.json.\n';
+async function inspectBinding(cwd) {
+    const resolution = await resolveWorkspaceRoot({ startPath: cwd });
+    if (resolution.root === null)
+        return null;
+    const machine = await inspectMachineConfig(resolution.root);
+    return {
+        root: resolution.root,
+        machinePath: machine.path,
+        runtime: machine.value?.runtime === null || machine.value?.runtime === undefined
+            ? null
+            : {
+                version: machine.value.runtime.version,
+                executable: machine.value.runtime.executable,
+            },
+    };
+}
+function printDiagnostics(output, diagnostics) {
+    for (const diagnostic of diagnostics) {
+        output.stderr(`  ${diagnostic.severity} ${diagnostic.code}: ${diagnostic.message}\n`);
+    }
+}
+function sourceFor(options) {
+    const from = options.from ?? (options.tarball === null ? 'self' : 'tarball');
+    if (from === 'self')
+        return { kind: 'self' };
+    if (from === 'tarball') {
+        if (options.tarball === null)
+            return null;
+        return { kind: 'tarball', path: resolve(options.cwd, options.tarball) };
+    }
+    return { kind: 'version' };
+}
+async function runInstall(options, output, binding) {
+    const packageInfo = getPackageInfo();
+    const version = options.version ?? packageInfo.version;
+    const source = sourceFor(options);
+    if (source === null) {
+        output.stderr('pappra runtime install: --from tarball requires --tarball.\n');
+        return 2;
+    }
+    const dataDir = resolveUserDataDir();
+    const paths = runtimePaths(version, dataDir);
+    if (!options.apply) {
+        if (options.json) {
+            output.stdout(`${JSON.stringify({
+                ok: true,
+                command: 'runtime',
+                action: 'install',
+                mode: 'plan',
+                version,
+                source: source.kind,
+                dataDir,
+                runtimeRoot: paths.runtimeRoot,
+                bind: options.bind,
+                workspaceRoot: binding?.root ?? null,
+                nextActions: ['Rerun with --apply to install this exact runtime.'],
+            })}\n`);
+        }
+        else {
+            output.stdout(`Runtime plan: ${packageInfo.name}@${version}\n`);
+            output.stdout(`Source: ${source.kind}\n`);
+            output.stdout(`Target: ${paths.runtimeRoot}\n`);
+            output.stdout('Plan only; rerun with --apply to install it.\n');
+        }
+        return 0;
+    }
+    const installed = await installRuntime({
+        version,
+        source: source.kind === 'tarball'
+            ? { kind: 'tarball', path: source.path }
+            : source.kind === 'self'
+                ? { kind: 'self', path: getPackageRoot() }
+                : { kind: 'version' },
+        packageName: packageInfo.name,
+    });
+    let bindingResult = null;
+    if (installed.ok && installed.manifest !== null && options.bind) {
+        if (binding === null) {
+            output.stderr('pappra runtime install: --bind requires a registered workspace root.\n');
+            return 1;
+        }
+        const updated = await updateMachineRuntime(binding.root, installed.manifest);
+        bindingResult = { ok: updated.ok, diagnostics: updated.diagnostics };
+        if (!updated.ok) {
+            if (options.json) {
+                output.stdout(`${JSON.stringify({
+                    ok: false,
+                    command: 'runtime',
+                    action: 'install',
+                    version,
+                    runtime: installed,
+                    bind: { ok: false, diagnostics: updated.diagnostics },
+                })}\n`);
+            }
+            printDiagnostics(output, updated.diagnostics);
+            return 1;
+        }
+    }
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            ok: installed.ok,
+            command: 'runtime',
+            action: 'install',
+            version,
+            source: source.kind,
+            runtime: installed,
+            bind: bindingResult,
+            diagnostics: installed.diagnostics,
+        })}\n`);
+    }
+    else {
+        output.stdout(`Runtime: ${installed.status} ${version}\n`);
+        if (installed.runtimeRoot !== null) {
+            output.stdout(`Location: ${installed.runtimeRoot}\n`);
+        }
+        if (bindingResult?.ok === true) {
+            output.stdout('Machine binding updated.\n');
+        }
+        printDiagnostics(output, installed.diagnostics);
+    }
+    return installed.ok ? 0 : 1;
+}
+async function runStatus(options, output, binding) {
+    const packageInfo = getPackageInfo();
+    const version = options.version ?? binding?.runtime?.version ?? packageInfo.version;
+    const dataDir = resolveUserDataDir();
+    const state = await inspectRuntimeStatePassive(version, dataDir);
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            ok: true,
+            command: 'runtime',
+            action: 'status',
+            version,
+            dataDir,
+            workspaceRoot: binding?.root ?? null,
+            machineRuntime: binding?.runtime ?? null,
+            runtime: {
+                status: state.status,
+                runtimeRoot: state.runtimeRoot,
+                packageDigestMatch: state.packageDigestMatch,
+                executableExists: state.executableExists,
+                verifiedAt: state.manifest?.verifiedAt ?? null,
+                source: state.manifest?.source.kind ?? null,
+            },
+            diagnostics: state.diagnostics,
+        })}\n`);
+    }
+    else {
+        output.stdout(`Runtime ${version}: ${state.status}\n`);
+        output.stdout(`Location: ${state.runtimeRoot}\n`);
+        if (state.manifest !== null) {
+            output.stdout(`Verified at: ${state.manifest.verifiedAt}\n`);
+        }
+        output.stdout(`Bound in machine.json: ${binding?.runtime?.version === version ? 'yes' : 'no'}\n`);
+        printDiagnostics(output, state.diagnostics);
+    }
+    return 0;
+}
+async function runVerify(options, output, binding) {
+    const packageInfo = getPackageInfo();
+    const version = options.version ?? binding?.runtime?.version ?? packageInfo.version;
+    const state = await inspectRuntimeState(version, resolveUserDataDir());
+    const ok = state.status === 'complete';
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            ok,
+            command: 'runtime',
+            action: 'verify',
+            version,
+            status: state.status,
+            runtimeRoot: state.runtimeRoot,
+            manifest: state.manifest,
+            diagnostics: state.diagnostics,
+        })}\n`);
+    }
+    else {
+        output.stdout(`Runtime ${version}: ${state.status}\n`);
+        printDiagnostics(output, state.diagnostics);
+    }
+    return ok ? 0 : 1;
+}
+async function runRemove(options, output, binding) {
+    const version = options.version ?? binding?.runtime?.version ?? null;
+    if (version === null) {
+        output.stderr('pappra runtime remove: --version is required.\n');
+        return 2;
+    }
+    if (!options.apply) {
+        output.stderr('pappra runtime remove: rerun with --apply to remove it.\n');
+        return 2;
+    }
+    const boundHere = binding?.runtime?.version === version;
+    if (boundHere && !options.force) {
+        const message = 'machine.json still binds this runtime; pass --force to remove it anyway.';
+        if (options.json) {
+            output.stdout(`${JSON.stringify({
+                ok: false,
+                command: 'runtime',
+                action: 'remove',
+                version,
+                message,
+            })}\n`);
+        }
+        else {
+            output.stderr(`pappra runtime remove: ${message}\n`);
+        }
+        return 1;
+    }
+    const removed = await removeRuntime({
+        version,
+        dataDir: resolveUserDataDir(),
+        // The current workspace was already checked above; callers that need to
+        // protect other checkouts pass --force only after checking them.
+        activeReferences: [],
+    });
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            ok: removed.ok,
+            command: 'runtime',
+            action: 'remove',
+            version,
+            removed,
+            machineBindingRetained: boundHere,
+        })}\n`);
+    }
+    else {
+        output.stdout(`Runtime ${version}: ${removed.status}\n`);
+        printDiagnostics(output, removed.diagnostics);
+    }
+    return removed.ok ? 0 : 1;
+}
+export async function runRuntimeCommand(options, output) {
+    if (options.action === null) {
+        output.stderr(`${runtimeUsage}`);
+        return 2;
+    }
+    const binding = await inspectBinding(options.cwd);
+    switch (options.action) {
+        case 'install':
+            return runInstall(options, output, binding);
+        case 'status':
+            return runStatus(options, output, binding);
+        case 'verify':
+            return runVerify(options, output, binding);
+        case 'remove':
+            return runRemove(options, output, binding);
+    }
+}

package/dist/cli/run.js

@@ -7,6 +7,7 @@ import { checkpointUsage, resumeUsage, runCheckpointCommand, runResumeCommand, }
 import { codeUsage, runCodeCommand } from './commands/code.js';
 import { collaborationUsage, runCollaborationCommand, } from './commands/collaboration.js';
 import { hostUsage, runHostCommand } from './commands/host.js';
+import { runtimeUsage, runRuntimeCommand } from './commands/runtime.js';
 import { hostNameSchema } from '../schemas/host.js';
 function parseOptions(args) {
     const { values, positionals } = parseArgs({
@@ -17,6 +18,19 @@ function parseOptions(args) {
             json: { type: 'boolean' },
             config: { type: 'string' },
             apply: { type: 'boolean' },
+            yes: { type: 'boolean', short: 'y' },
+            'no-runtime': { type: 'boolean' },
+            reconfigure: { type: 'boolean' },
+            from: { type: 'string' },
+            tarball: { type: 'string' },
+            out: { type: 'string' },
+            mode: { type: 'string' },
+            marketplace: { type: 'boolean' },
+            scope: { type: 'string' },
+            bind: { type: 'boolean' },
+            force: { type: 'boolean' },
+            'no-interactive': { type: 'boolean' },
+            'print-choices': { type: 'boolean' },
             'install-runtime': { type: 'boolean' },
             'runtime-tarball': { type: 'string' },
             'runtime-version': { type: 'string' },
@@ -73,6 +87,7 @@ function parseOptions(args) {
             hostAction: null,
             collaborationAction: null,
             resumeTaskId: null,
+            runtimeAction: null,
         };
     }
     if (command === 'resume') {
@@ -88,6 +103,7 @@ function parseOptions(args) {
             hostAction: null,
             collaborationAction: null,
             resumeTaskId: positionals[1] ?? null,
+            runtimeAction: null,
         };
     }
     if (command === 'code') {
@@ -103,6 +119,7 @@ function parseOptions(args) {
             hostAction: null,
             collaborationAction: null,
             resumeTaskId: null,
+            runtimeAction: null,
         };
     }
     if (command === 'host') {
@@ -118,6 +135,23 @@ function parseOptions(args) {
             hostAction: positionals[1] ?? null,
             collaborationAction: null,
             resumeTaskId: null,
+            runtimeAction: null,
+        };
+    }
+    if (command === 'runtime') {
+        if (positionals.length > 2) {
+            throw new Error('runtime accepts one action: install, status, verify, or remove.');
+        }
+        return {
+            values,
+            command,
+            docsAction: null,
+            docsArgument: null,
+            codeAction: null,
+            hostAction: null,
+            collaborationAction: null,
+            resumeTaskId: null,
+            runtimeAction: positionals[1] ?? null,
         };
     }
     if (command === 'collab') {
@@ -133,6 +167,7 @@ function parseOptions(args) {
             hostAction: null,
             collaborationAction: positionals[1] ?? null,
             resumeTaskId: null,
+            runtimeAction: null,
         };
     }
     if (positionals.length > 1) {
@@ -147,10 +182,15 @@ function parseOptions(args) {
         hostAction: null,
         collaborationAction: null,
         resumeTaskId: null,
+        runtimeAction: null,
     };
 }
 function failure(output, json, code, error) {
-    const message = error instanceof Error ? error.message : 'Operation failed.';
+    const message = typeof error === 'string'
+        ? error
+        : error instanceof Error
+            ? error.message
+            : 'Operation failed.';
     if (json) {
         output.stdout(`${JSON.stringify({ ok: false, code, message })}\n`);
     }
@@ -176,7 +216,7 @@ function hasContinuityOptions(values, includeSession = true) {
         (includeSession && values.session !== undefined));
 }
 const globalUsage = 'pappra [--help | --version] [--json]\n' +
-    'pappra init [--config <file>] [--apply] [--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' +
     'pappra docs <list|check|archive> [options]\n' +
@@ -184,6 +224,7 @@ const globalUsage = 'pappra [--help | --version] [--json]\n' +
     'pappra resume <taskId> [--session <id>] [--json]\n' +
     'pappra code <status|prepare|query> --repo <id> [options] [--json]\n' +
     'pappra host <detect|describe|plan|install|verify> --host <name> [options] [--json]\n' +
+    'pappra runtime <install|status|verify|remove> [options] [--json]\n' +
     'pappra collab <prepare|run|query> [options]';
 export async function runCli(args, output) {
     const jsonRequested = args.includes('--json');
@@ -195,8 +236,56 @@ export async function runCli(args, output) {
         failure(output, jsonRequested, 'invalid_arguments', error);
         return 2;
     }
-    const { values, command, docsAction, docsArgument, codeAction, hostAction, collaborationAction, resumeTaskId, } = parsed;
+    const { values, command, docsAction, docsArgument, codeAction, hostAction, collaborationAction, resumeTaskId, runtimeAction, } = parsed;
     const json = values.json === true;
+    const applyRequested = values.apply === true;
+    if (command !== 'init' &&
+        (values.yes === 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.');
+        return 2;
+    }
+    if (command !== 'host' && values.out !== undefined) {
+        failure(output, json, 'invalid_arguments', '--out is only valid for host.');
+        return 2;
+    }
+    if (values.scope !== undefined &&
+        values.scope !== 'project' &&
+        values.scope !== 'user') {
+        failure(output, json, 'invalid_arguments', '--scope accepts project or user.');
+        return 2;
+    }
+    if (command !== 'host' && values.scope !== undefined) {
+        failure(output, json, 'invalid_arguments', '--scope 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') {
+        failure(output, json, 'invalid_arguments', '--mode is only valid for host.');
+        return 2;
+    }
+    if (values.mode !== undefined &&
+        values.mode !== 'project-settings' &&
+        values.mode !== 'plugin') {
+        failure(output, json, 'invalid_arguments', '--mode accepts project-settings or plugin.');
+        return 2;
+    }
+    if (command !== 'runtime' &&
+        (values.from !== undefined ||
+            values.tarball !== undefined ||
+            values.bind === true ||
+            values.force === true)) {
+        failure(output, json, 'invalid_arguments', '--from, --tarball, --bind and --force are only valid for runtime.');
+        return 2;
+    }
     let info;
     try {
         info = getPackageInfo();
@@ -231,7 +320,6 @@ export async function runCli(args, output) {
         if (action === null ||
             values.version ||
             values.config !== undefined ||
-            values.apply === true ||
             values['install-runtime'] === true ||
             values['runtime-tarball'] !== undefined ||
             values['runtime-version'] !== undefined ||
@@ -256,13 +344,12 @@ export async function runCli(args, output) {
     if (command === 'docs') {
         if (values.version ||
             values.config !== undefined ||
-            values.apply === true ||
             values['install-runtime'] === true ||
             values['runtime-tarball'] !== undefined ||
             values['runtime-version'] !== undefined ||
             values.root !== undefined ||
             hasContinuityOptions(values)) {
-            failure(output, json, 'invalid_arguments', 'docs only accepts list/check/archive, --include-private, --include-archived, --help, and --json.');
+            failure(output, json, 'invalid_arguments', 'docs only accepts list/check/archive/scan, --include-private, --include-archived, --apply (scan only), --help, and --json.');
             return 2;
         }
         if (values.help) {
@@ -281,6 +368,7 @@ export async function runCli(args, output) {
             json,
             includePrivate: values['include-private'] === true,
             includeArchived: values['include-archived'] === true,
+            apply: applyRequested,
         }, output);
     }
     if (command === 'doctor') {
@@ -339,6 +427,55 @@ export async function runCli(args, output) {
             installRuntime: values['install-runtime'] === true,
             runtimeTarball: values['runtime-tarball'] ?? null,
             runtimeVersion: values['runtime-version'] ?? null,
+            yes: values.yes === true || values['no-interactive'] === true,
+            printChoices: values['print-choices'] === true,
+            noRuntime: values['no-runtime'] === true,
+            reconfigure: values.reconfigure === true,
+        }, output);
+    }
+    if (command === 'runtime') {
+        if (values.help) {
+            if (json) {
+                output.stdout(`${JSON.stringify({ ...info, commands: ['runtime'], usage: runtimeUsage })}\n`);
+            }
+            else {
+                output.stdout(runtimeUsage);
+            }
+            return 0;
+        }
+        if (values.version ||
+            values.config !== undefined ||
+            values['install-runtime'] === true ||
+            values['runtime-tarball'] !== undefined ||
+            values.root !== undefined ||
+            values.host !== undefined ||
+            values.repo !== undefined ||
+            values.query !== undefined ||
+            values.kind !== undefined ||
+            hasContinuityOptions(values)) {
+            failure(output, json, 'invalid_arguments', 'runtime accepts only --from, --tarball, --version, --apply, --bind, --force, --help, and --json.');
+            return 2;
+        }
+        const action = runtimeAction === 'install' ||
+            runtimeAction === 'status' ||
+            runtimeAction === 'verify' ||
+            runtimeAction === 'remove'
+            ? runtimeAction
+            : null;
+        return runRuntimeCommand({
+            cwd: process.cwd(),
+            action,
+            json,
+            from: values.from === 'self' ||
+                values.from === 'tarball' ||
+                values.from === 'registry'
+                ? values.from
+                : null,
+            tarball: values.tarball ?? null,
+            version: values['runtime-version'] ?? null,
+            apply: values.apply === true,
+            bind: values.bind === true,
+            force: values.force === true,
         }, output);
     }
     if (command === 'checkpoint') {
@@ -516,6 +653,7 @@ export async function runCli(args, output) {
             'plan',
             'install',
             'verify',
+            'bundle',
         ];
         const action = allowedActions.find((item) => item === hostAction) ?? null;
         const parsedHost = hostNameSchema.safeParse(values.host);
@@ -536,6 +674,12 @@ export async function runCli(args, output) {
             values.rebuild === true ||
             hasContinuityOptions(values) ||
             (values.apply === true && action !== 'install') ||
+            (values.mode !== undefined && action !== 'install') ||
+            (values.marketplace === true && action !== 'bundle') ||
+            (values.scope !== undefined &&
+                action !== 'plan' &&
+                action !== 'install' &&
+                action !== 'verify') ||
             (values['host-root'] !== undefined && action === null) ||
             (values['host-version'] !== undefined && action === null);
         if (values.help) {
@@ -548,7 +692,7 @@ export async function runCli(args, output) {
             return 0;
         }
         if (action === null || host === null || invalid) {
-            failure(output, json, 'invalid_arguments', 'host requires detect/describe/plan/install/verify, --host, and action-compatible options.');
+            failure(output, json, 'invalid_arguments', 'host requires detect/describe/plan/install/verify/bundle, --host, and action-compatible options.');
             return 2;
         }
         return runHostCommand({
@@ -559,6 +703,14 @@ export async function runCli(args, output) {
             hostRoot: values['host-root'] ?? null,
             hostVersion: values['host-version'] ?? null,
             apply: values.apply === true,
+            out: values.out ?? null,
+            mode: values.mode === 'project-settings' || values.mode === 'plugin'
+                ? values.mode
+                : null,
+            marketplace: values.marketplace === true,
+            scope: values.scope === 'project' || values.scope === 'user'
+                ? values.scope
+                : null,
         }, output);
     }
     if (command !== null) {

package/dist/hosts/detect.d.ts

@@ -23,6 +23,7 @@ export interface HostDetectionOptions {
     readonly selectedHosts: readonly string[];
     readonly observedAt?: string;
 }
+export declare function executableOnPath(command: string, pathEnv: string): string | null;
 export declare function detectPassiveTool(command: string, pathEnv: string): PassiveToolObservation;
 /** Passive host discovery. It never starts a host or reads config contents. */
 export declare function detectPassiveHosts(options: HostDetectionOptions): readonly PassiveHostObservation[];

package/dist/hosts/detect.js

@@ -9,7 +9,7 @@ function evidence(path, observedAt) {
         scope: 'live-owned',
     };
 }
-function executableOnPath(command, pathEnv) {
+export function executableOnPath(command, pathEnv) {
     for (const directory of pathEnv.split(delimiter)) {
         if (directory === '')
             continue;

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

@@ -0,0 +1,24 @@
+import type { HostName } from '../../schemas/host.js';
+export interface HostPluginBundle {
+    readonly host: HostName;
+    readonly outDir: string;
+    readonly files: readonly string[];
+    readonly pluginManifest: string;
+    readonly hookConfig: string | null;
+    readonly registration: readonly string[];
+    /** Plugin registration and native callability are not verified here. */
+    readonly verification: 'unsupported';
+}
+/**
+ * Writes a host-native plugin/package directory. This is an artifact export: it
+ * does not register the plugin with a host, and it never claims the host will
+ * load or trust it.
+ */
+export declare function exportHostPluginBundle(options: {
+    readonly host: HostName;
+    readonly hostVersion: string;
+    readonly outDir: string;
+    readonly packageVersion: string;
+    /** Writes a marketplace root with the plugin under `pappra/`. */
+    readonly marketplace?: boolean;
+}): Promise<HostPluginBundle>;