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

package/dist/cli/commands/docs.js

@@ -1,11 +1,106 @@
+import { discoverWorkspace } from '../../workspace/discover.js';
 import { resolveWorkspaceRoot } from '../../workspace/resolve.js';
 import { formatDiagnostic } from '../../schemas/diagnostics.js';
 import { docsArchiveReportSchema, docsCheckReportSchema, docsListReportSchema, } from '../../schemas/document.js';
 import { KnowledgeService, } from '../../knowledge/index.js';
-export const docsUsage = 'pappra docs <list|check|archive> [options]\n' +
+export const docsUsage = 'pappra docs <list|check|archive|scan> [options]\n' +
     '  list   [--include-private] [--include-archived] [--json]\n' +
     '  check  [--include-private] [--json]\n' +
-    '  archive <documentId> [--json]';
+    '  archive <documentId> [--json]\n' +
+    '  scan   [--apply] [--json]\n\n' +
+    'scan registers documents discovered under the configured knowledge sources; without\n' +
+    '--apply it only reports the candidates.';
+function classifyScanKind(path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith('agents.md') || lower.endsWith('claude.md'))
+        return 'rule';
+    if (lower.includes('/research/'))
+        return 'research';
+    if (lower.includes('/adr/') || lower.includes('decision'))
+        return 'decision';
+    if (lower.includes('review') || lower.includes('retro'))
+        return 'review';
+    if (lower.includes('plan'))
+        return 'plan';
+    return 'architecture';
+}
+async function runDocsScan(options, output, root) {
+    const discovery = await discoverWorkspace(root);
+    const config = discovery.config;
+    if (config === null) {
+        return invalidArguments(output, options.json, 'docs scan requires a valid .pappra/workspace.json; run pappra init first.');
+    }
+    const service = new KnowledgeService(root);
+    const listed = await service.list({ includePrivate: true });
+    const registered = new Set(listed.records.flatMap((record) => record.location.kind === 'workspace' ? [record.location.path] : []));
+    const sources = config.knowledge.sources;
+    const visibility = config.knowledge.taskVisibility === 'shared' ? 'shareable' : 'private';
+    const candidates = (discovery.documents ?? []).flatMap((document) => {
+        const path = document.workspaceRelativePath;
+        if (path === null)
+            return [];
+        if (!sources.some((source) => path === source || path.startsWith(`${source}/`))) {
+            return [];
+        }
+        if (registered.has(path))
+            return [];
+        return [{ path, kind: classifyScanKind(path), visibility }];
+    });
+    if (!options.apply) {
+        if (options.json) {
+            output.stdout(`${JSON.stringify({
+                ok: true,
+                schema: 'pappra/docs-scan/1',
+                mode: 'plan',
+                workspaceRoot: root,
+                candidates,
+                registered: registered.size,
+                nextActions: [
+                    'Rerun with --apply to register these documents in the knowledge catalog.',
+                ],
+            })}\n`);
+        }
+        else {
+            output.stdout(`Scan candidates: ${candidates.length}\n`);
+            for (const candidate of candidates) {
+                output.stdout(`  ${candidate.kind}  ${candidate.path}\n`);
+            }
+            output.stdout('Plan only; rerun with --apply to register them.\n');
+        }
+        return 0;
+    }
+    const registeredNow = [];
+    const diagnostics = [];
+    for (const candidate of candidates) {
+        const result = await service.register({
+            location: { kind: 'workspace', path: candidate.path },
+            kind: candidate.kind,
+            maturity: 'draft',
+            owner: 'human',
+            visibility: candidate.visibility,
+        });
+        diagnostics.push(...result.diagnostics);
+        if (result.ok)
+            registeredNow.push(result.record);
+    }
+    const ok = diagnostics.every((entry) => entry.severity !== 'error');
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            ok,
+            schema: 'pappra/docs-scan/1',
+            mode: 'apply',
+            workspaceRoot: root,
+            registered: registeredNow,
+            skipped: candidates.length - registeredNow.length,
+            diagnostics,
+        })}\n`);
+    }
+    else {
+        output.stdout(`Registered ${registeredNow.length} document(s).\n`);
+        printDiagnostics(output, diagnostics);
+    }
+    return ok ? 0 : 1;
+}
 function printDiagnostics(output, diagnostics) {
     for (const diagnostic of diagnostics) {
         output.stderr(`${formatDiagnostic(diagnostic)}\n`);
@@ -55,7 +150,7 @@ export async function runDocsCommand(options, output) {
     }
     const resolution = await resolveWorkspaceRoot({ startPath: options.cwd });
     const serviceRoot = resolution.root ?? options.cwd;
-    if (!['list', 'check', 'archive'].includes(options.action)) {
+    if (!['list', 'check', 'archive', 'scan'].includes(options.action)) {
         return invalidArguments(output, options.json, `unknown docs action: ${options.action}`);
     }
     if (options.action === 'archive' && options.argument === null) {
@@ -64,6 +159,12 @@ export async function runDocsCommand(options, output) {
     if (options.action !== 'archive' && options.argument !== null) {
         return invalidArguments(output, options.json, `docs ${options.action} does not accept an argument`);
     }
+    if (options.action === 'scan') {
+        return runDocsScan(options, output, serviceRoot);
+    }
+    if (options.apply) {
+        return invalidArguments(output, options.json, 'only docs scan accepts --apply');
+    }
     if (options.action === 'archive' && options.argument !== null) {
         const service = new KnowledgeService(serviceRoot);
         const result = await service.archive(options.argument);

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

@@ -4,10 +4,12 @@ export declare const hostUsage: string;
 export interface HostCommandOptions {
     readonly cwd: string;
     readonly json: boolean;
-    readonly action: 'detect' | 'describe' | 'plan' | 'install' | 'verify' | null;
+    readonly action: 'detect' | 'describe' | 'plan' | 'install' | 'verify' | 'bundle' | null;
     readonly host: HostName | null;
     readonly hostRoot: string | null;
     readonly hostVersion: string | null;
     readonly apply: boolean;
+    readonly out: string | null;
+    readonly mode: 'project-settings' | 'plugin' | null;
 }
 export declare function runHostCommand(options: HostCommandOptions, output: CliOutput): Promise<number>;

package/dist/cli/commands/host.js

@@ -1,8 +1,15 @@
 import { homedir } from 'node:os';
 import { resolve } from 'node:path';
 import { HostIntegrationService } from '../../hosts/integration/service.js';
-export const hostUsage = 'pappra host <detect|describe|plan|install|verify> --host <pi|codex|claude>\n' +
-    '  [--host-root <dir>] [--host-version <version>] [--apply] [--json]';
+import { exportHostPluginBundle } from '../../hosts/integration/bundle-export.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' +
+    '  [--host-root <dir>] [--host-version <version>] [--out <dir>]\n' +
+    '  [--mode project-settings|plugin] [--apply] [--json]\n' +
+    '\n' +
+    'bundle exports a host-native plugin/package directory and never registers it or\n' +
+    'claims host callability.';
 function printDiagnostics(output, diagnostics) {
     for (const entry of diagnostics) {
         if (typeof entry === 'object' &&
@@ -96,6 +103,7 @@ export async function runHostCommand(options, output) {
         const result = await service.install(options.host, {
             ...target,
             apply: options.apply,
+            ...(options.mode === null ? {} : { mode: options.mode }),
         });
         if (options.json) {
             output.stdout(`${JSON.stringify(result)}\n`);
@@ -110,6 +118,46 @@ export async function runHostCommand(options, output) {
         }
         return diagnosticStatus(result.status);
     }
+    if (options.action === 'bundle') {
+        if (options.out === null) {
+            output.stderr('pappra host bundle requires --out <dir>.\n');
+            return 2;
+        }
+        if (!isSupportedVersion(options.host, options.hostVersion)) {
+            output.stderr(`Host ${options.host} version ${options.hostVersion ?? '(unknown)'} is outside the pinned ${HOST_SUPPORT[options.host].version} support matrix.\n`);
+            return 1;
+        }
+        try {
+            const exported = await exportHostPluginBundle({
+                host: options.host,
+                hostVersion: options.hostVersion ?? HOST_SUPPORT[options.host].version,
+                outDir: options.out,
+                packageVersion: getPackageInfo().version,
+            });
+            if (options.json) {
+                output.stdout(`${JSON.stringify({ ok: true, command: 'host', action: 'bundle', ...exported })}\n`);
+            }
+            else {
+                output.stdout(`Exported ${exported.host} bundle to ${exported.outDir}\n`);
+                for (const file of exported.files)
+                    output.stdout(`  ${file}\n`);
+                for (const hint of exported.registration)
+                    output.stdout(`  note: ${hint}\n`);
+                output.stdout('Registration and host callability remain unverified.\n');
+            }
+            return 0;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (options.json) {
+                output.stdout(`${JSON.stringify({ ok: false, command: 'host', action: 'bundle', message })}\n`);
+            }
+            else {
+                output.stderr(`pappra host bundle: ${message}\n`);
+            }
+            return 1;
+        }
+    }
     const result = await service.verify(options.host, target);
     if (options.json) {
         output.stdout(`${JSON.stringify(result)}\n`);

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

@@ -32,6 +32,14 @@ export interface InitCommandOptions {
     readonly installRuntime?: boolean;
     readonly runtimeTarball?: string | null;
     readonly runtimeVersion?: string | null;
+    /** Derives deterministic selections from discovery instead of prompting. */
+    readonly yes?: boolean;
+    /** Prints the derived selections and writes nothing. */
+    readonly printChoices?: boolean;
+    /** Leaves the runtime action pending instead of installing a durable copy. */
+    readonly noRuntime?: boolean;
+    /** Rebuilds workspace.json from the selections even when a valid config exists. */
+    readonly reconfigure?: boolean;
 }
 export interface RuntimeFlowResult {
     readonly ok: boolean;

package/dist/cli/commands/init.js

@@ -2,11 +2,12 @@ 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 { readTextFileBounded } from '../../infra/fs.js';
-import { getPackageInfo } from '../../package-info.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 { applyInitPlan, inspectInitContext, listKnowledgeCandidates, listRepositoryCandidates, planWorkspaceInit, } from '../../app/init.js';
+import { inspectMachineConfig } from '../../workspace/config.js';
+import { applyInitPlan, inspectInitContext, listKnowledgeCandidates, deriveInitChoices, listRepositoryCandidates, planWorkspaceInit, } from '../../app/init.js';
 export const clackWizardUi = {
     intro: (message) => prompts.intro(message),
     outro: (message) => prompts.outro(message),
@@ -249,6 +250,84 @@ 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;
@@ -385,6 +464,7 @@ function writeFailure(output, options, failure) {
             message: failure.message,
             nextAction: failure.nextAction,
             diagnostics: failure.diagnostics,
+            ...(failure.details ?? {}),
         })}\n`);
     }
     else {
@@ -506,12 +586,26 @@ function printApply(output, result, runtimeRequested) {
             : 'Only planned config files were applied. Initialization is not complete until runtime/provider actions are authorized and executed.\n');
     }
 }
+function advisoryNextActions(bundle) {
+    const actions = [];
+    const repositoryId = bundle.scope.repositories[0]?.id;
+    if (bundle.scope.code.graph !== 'none' &&
+        bundle.scope.repositories.length > 0 &&
+        repositoryId !== undefined) {
+        actions.push(`pappra code prepare --repo ${repositoryId} --apply   # register the ${bundle.scope.code.graph} index for this checkout`);
+    }
+    if (bundle.scope.knowledge.sources.length > 0) {
+        actions.push('pappra docs scan --apply   # register discovered knowledge documents in the catalog');
+    }
+    return actions;
+}
 function planJson(bundle) {
     return {
         command: 'init',
         mode: 'plan',
         plan: bundle.plan,
         scope: bundle.scope,
+        nextActions: advisoryNextActions(bundle),
         diagnostics: bundle.diagnostics,
     };
 }
@@ -520,7 +614,11 @@ function planJson(bundle) {
  * exactly one JSON document. Interactive selection is injected for tests.
  */
 export async function runInitCommand(options, output, deps = {}) {
+    const yes = options.yes === true;
+    const printChoices = options.printChoices === true;
     const interactive = !options.json &&
+        !yes &&
+        !printChoices &&
         options.configPath === null &&
         (deps.interactive ??
             (process.stdin.isTTY === true && process.stdout.isTTY === true));
@@ -542,29 +640,82 @@ export async function runInitCommand(options, output, deps = {}) {
         options.runtimeVersion !== undefined) {
         return writeFailure(output, options, runtimeOptionsFailure('Use either --runtime-tarball or --runtime-version, not both.', 'Choose one explicit runtime source.'));
     }
+    if (printChoices &&
+        (options.configPath !== null ||
+            options.apply ||
+            wantsRuntime ||
+            hasRuntimeSource)) {
+        return writeFailure(output, options, {
+            ok: false,
+            status: 'invalid',
+            code: diagnosticCodes.initInvalidInput,
+            message: '--print-choices cannot be combined with --config, --apply, or runtime flags.',
+            diagnostics: [],
+            nextAction: 'Run pappra init --print-choices on its own to print the derived selections.',
+        });
+    }
+    if (yes && options.configPath !== null) {
+        return writeFailure(output, options, {
+            ok: false,
+            status: 'invalid',
+            code: diagnosticCodes.initInvalidInput,
+            message: 'Use either --config or --yes, not both.',
+            diagnostics: [],
+            nextAction: 'Pass explicit selections with --config, or derive them with --yes.',
+        });
+    }
     const contextResult = await inspectInitContext(options.cwd);
     if (!contextResult.ok) {
         return writeFailure(output, options, contextResult);
     }
     const context = contextResult.context;
     let choices = null;
+    if (printChoices) {
+        const derived = await deriveInitChoices(context.discovery);
+        if (options.json) {
+            output.stdout(`${JSON.stringify({
+                ok: true,
+                command: 'init',
+                mode: 'choices',
+                choices: derived.choices,
+                rules: derived.rules,
+                candidates: derived.candidates,
+            })}\n`);
+        }
+        else {
+            output.stdout(`${JSON.stringify(derived.choices, null, 2)}\n`);
+            for (const rule of derived.rules) {
+                output.stderr(`  ${rule.field} = ${rule.value} (${rule.reason})\n`);
+            }
+        }
+        return 0;
+    }
     if (options.configPath !== null) {
         const loaded = await loadChoices(options.configPath);
         if (!loaded.ok)
             return writeFailure(output, options, loaded.failure);
         choices = loaded.choices;
     }
+    else if (yes) {
+        choices = (await deriveInitChoices(context.discovery)).choices;
+    }
     else {
         const needsChoices = context.discovery.configState !== 'valid' ||
             context.discovery.machineState !== 'valid';
         if (needsChoices && !interactive) {
+            const derived = await deriveInitChoices(context.discovery);
             return writeFailure(output, options, {
                 ok: false,
                 status: 'needs_input',
                 code: diagnosticCodes.initNoTty,
                 message: 'Missing init selections in a non-interactive session.',
                 diagnostics: context.diagnostics,
-                nextAction: 'Provide --config with pappra/init-choices/1, or run in a TTY for the interactive wizard.',
+                nextAction: 'Rerun with --yes to apply the derived selections, provide --config with pappra/init-choices/1, or run in a TTY for the interactive wizard.',
+                details: {
+                    candidates: derived.candidates,
+                    suggestedChoices: derived.choices,
+                    rules: derived.rules,
+                },
             });
         }
         if (needsChoices && interactive) {
@@ -579,6 +730,7 @@ export async function runInitCommand(options, output, deps = {}) {
         root: context.root,
         choices,
         context,
+        ...(options.reconfigure === true ? { reconfigure: true } : {}),
     });
     if (!prepared.ok)
         return writeFailure(output, options, prepared);
@@ -592,13 +744,16 @@ export async function runInitCommand(options, output, deps = {}) {
             return 0;
         }
         const applied = await applyInitPlan(bundle);
-        const runtimeFlow = wantsRuntime && applied.ok && applied.residualPaths.length === 0
-            ? await installAndRecordRuntime(bundle.scope.workspaceRoot, bundle.scope.runtimeVersion, options)
+        const runtimeRequested = wantsRuntime || options.noRuntime !== true;
+        const runtimeFlow = runtimeRequested && applied.ok && applied.residualPaths.length === 0
+            ? wantsRuntime
+                ? await installAndRecordRuntime(bundle.scope.workspaceRoot, bundle.scope.runtimeVersion, options)
+                : await ensureDefaultRuntime(bundle.scope.workspaceRoot, bundle.scope.runtimeVersion)
             : null;
         const initComplete = runtimeFlow?.completion === true;
         const ok = applied.ok &&
             applied.residualPaths.length === 0 &&
-            (!wantsRuntime || (runtimeFlow?.ok === true && initComplete));
+            (!runtimeRequested || (runtimeFlow?.ok === true && initComplete));
         output.stdout(`${JSON.stringify({
             ok,
             command: 'init',
@@ -608,6 +763,7 @@ export async function runInitCommand(options, output, deps = {}) {
             apply: applied,
             runtime: runtimeFlow?.runtime ?? null,
             initComplete,
+            nextActions: advisoryNextActions(bundle),
             diagnostics: [
                 ...bundle.diagnostics,
                 ...(runtimeFlow?.diagnostics ?? []),
@@ -615,7 +771,7 @@ export async function runInitCommand(options, output, deps = {}) {
         })}\n`);
         if (!applied.ok || applied.residualPaths.length > 0)
             return 1;
-        if (wantsRuntime)
+        if (runtimeRequested)
             return ok ? 0 : 1;
         return applied.status === 'external-actions-pending' ? 1 : 0;
     }
@@ -632,7 +788,7 @@ export async function runInitCommand(options, output, deps = {}) {
         }
     }
     const applied = await applyInitPlan(bundle);
-    printApply(output, applied, wantsRuntime);
+    printApply(output, applied, wantsRuntime || options.noRuntime !== true);
     if (!applied.ok) {
         return applied.status === 'failed' ? 3 : 1;
     }
@@ -658,6 +814,27 @@ export async function runInitCommand(options, output, deps = {}) {
         output.stdout('Runtime installed and verified. Initialization complete for P04 scope; provider/index preferences were not executed.\n');
         return 0;
     }
+    if (options.noRuntime !== true) {
+        const runtimeFlow = await ensureDefaultRuntime(bundle.scope.workspaceRoot, bundle.scope.runtimeVersion);
+        if (runtimeFlow.runtime !== null) {
+            output.stdout(`Runtime: ${runtimeFlow.runtime.status} ${runtimeFlow.runtime.version}${runtimeFlow.runtime.runtimeRoot === null
+                ? ''
+                : ` at ${runtimeFlow.runtime.runtimeRoot}`}\n`);
+            if (runtimeFlow.runtime.residualPaths.length > 0) {
+                output.stderr(`Runtime residual paths: ${runtimeFlow.runtime.residualPaths.join(', ')}\n`);
+            }
+        }
+        if (!runtimeFlow.ok || !runtimeFlow.completion) {
+            output.stderr(`${diagnosticLines(runtimeFlow.diagnostics)}\n`);
+            output.stderr('The durable runtime copy could not be installed or bound. Initialization is not complete; --no-runtime leaves this action pending intentionally.\n');
+            return 1;
+        }
+        output.stdout('Durable runtime copy installed and bound. Initialization complete.\n');
+        for (const action of advisoryNextActions(bundle)) {
+            output.stdout(`  next: ${action}\n`);
+        }
+        return 0;
+    }
     return applied.status === 'external-actions-pending' ? 1 : 0;
 }
 export const initUsage = 'pappra init [--config <file>] [--apply] [--json]\n' +

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

@@ -0,0 +1,14 @@
+import type { CliOutput } from '../output.js';
+export declare const runtimeUsage: string;
+export interface RuntimeCommandOptions {
+    readonly cwd: string;
+    readonly action: 'install' | 'status' | 'verify' | 'remove' | null;
+    readonly json: boolean;
+    readonly from: 'self' | 'tarball' | 'registry' | null;
+    readonly tarball: string | null;
+    readonly version: string | null;
+    readonly apply: boolean;
+    readonly bind: boolean;
+    readonly force: boolean;
+}
+export declare function runRuntimeCommand(options: RuntimeCommandOptions, output: CliOutput): Promise<number>;