@phyzess/pappra 0.0.0-stage → 0.1.0-beta.10

package/dist/cli/commands/docs.js

@@ -0,0 +1,234 @@
+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|scan> [options]\n' +
+    '  list   [--include-private] [--include-archived] [--json]\n' +
+    '  check  [--include-private] [--json]\n' +
+    '  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`);
+    }
+}
+function printDocument(output, record) {
+    output.stdout(`${record.documentId}  ${record.lifecycle}/${record.maturity}  ${record.visibility}  ${record.kind}  ${record.location.kind === 'workspace' ? record.location.path : `${record.location.sourceId}:${record.location.path}`}\n`);
+}
+function listReport(result) {
+    return {
+        schema: 'pappra/docs-list/1',
+        ok: result.ok,
+        includePrivate: result.includePrivate,
+        includeArchived: result.includeArchived,
+        catalogDigest: result.catalogDigest,
+        documents: result.records,
+        diagnostics: result.diagnostics,
+    };
+}
+function checkReport(result) {
+    return {
+        schema: 'pappra/docs-check/1',
+        ...result,
+    };
+}
+function invalidArguments(output, json, message) {
+    if (json) {
+        output.stdout(`${JSON.stringify({ ok: false, code: 'invalid_arguments', message })}\n`);
+    }
+    else {
+        output.stderr(`pappra: ${message}\n`);
+    }
+    return 2;
+}
+export async function runDocsCommand(options, output) {
+    if (options.action === null || options.action === 'help') {
+        if (options.json) {
+            output.stdout(`${JSON.stringify({
+                commands: ['list', 'check', 'archive'],
+                usage: docsUsage,
+            })}\n`);
+        }
+        else {
+            output.stdout(`${docsUsage}\n`);
+        }
+        return 0;
+    }
+    const resolution = await resolveWorkspaceRoot({ startPath: options.cwd });
+    const serviceRoot = resolution.root ?? options.cwd;
+    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) {
+        return invalidArguments(output, options.json, 'docs archive requires a documentId');
+    }
+    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);
+        if (options.json) {
+            const report = docsArchiveReportSchema.safeParse({
+                schema: 'pappra/docs-archive/1',
+                ok: result.ok,
+                status: result.status,
+                document: result.record,
+                diagnostics: result.diagnostics,
+            });
+            if (!report.success) {
+                return invalidArguments(output, true, `docs archive report is invalid: ${report.error.issues[0]?.message ?? 'unknown issue'}`);
+            }
+            output.stdout(`${JSON.stringify(report.data)}\n`);
+        }
+        else if (result.record !== null) {
+            printDocument(output, result.record);
+            printDiagnostics(output, result.diagnostics);
+        }
+        else {
+            printDiagnostics(output, result.diagnostics);
+        }
+        return result.ok ? 0 : 1;
+    }
+    const service = new KnowledgeService(serviceRoot);
+    if (options.action === 'list') {
+        const result = await service.list({
+            includePrivate: options.includePrivate,
+            includeArchived: options.includeArchived,
+        });
+        if (options.json) {
+            const report = docsListReportSchema.safeParse(listReport(result));
+            if (!report.success) {
+                return invalidArguments(output, true, `docs list report is invalid: ${report.error.issues[0]?.message ?? 'unknown issue'}`);
+            }
+            output.stdout(`${JSON.stringify(report.data)}\n`);
+        }
+        else {
+            for (const record of result.records)
+                printDocument(output, record);
+            printDiagnostics(output, result.diagnostics);
+        }
+        return result.ok ? 0 : 1;
+    }
+    const result = await service.check({
+        includePrivate: options.includePrivate,
+    });
+    if (options.json) {
+        const report = docsCheckReportSchema.safeParse(checkReport(result));
+        if (!report.success) {
+            return invalidArguments(output, true, `docs check report is invalid: ${report.error.issues[0]?.message ?? 'unknown issue'}`);
+        }
+        output.stdout(`${JSON.stringify(report.data)}\n`);
+    }
+    else {
+        for (const entry of result.entries) {
+            output.stdout(`${entry.documentId}  ${entry.freshness}  ${entry.lifecycle}/${entry.maturity}  record=${entry.recordDigest}  file=${entry.fileDigest ?? 'missing'}\n`);
+            for (const reason of entry.reasons) {
+                output.stdout(`  ${reason.code}: ${reason.message}\n`);
+            }
+        }
+        output.stdout(`total=${result.summary.total} current=${result.summary.current} needs-review=${result.summary.needsReview} unknown=${result.summary.unknown}\n`);
+        printDiagnostics(output, result.diagnostics);
+    }
+    return result.ok ? 0 : 1;
+}

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

@@ -0,0 +1,14 @@
+import type { CliOutput } from '../output.js';
+export interface DoctorCommandOptions {
+    readonly root: string;
+    readonly json: boolean;
+    readonly dataDir?: string;
+    readonly homeDir?: string;
+    readonly pathEnv?: string;
+}
+/**
+ * Runs one read-only doctor report. JSON mode writes exactly one JSON document
+ * to stdout and never opens prompts or emits progress logs.
+ */
+export declare function runDoctorCommand(options: DoctorCommandOptions, output: CliOutput): Promise<number>;
+export declare const doctorUsage: string;

package/dist/cli/commands/doctor.js

@@ -0,0 +1,57 @@
+import { runDoctor } from '../../app/doctor.js';
+function printHuman(output, report) {
+    output.stdout(`Pappra doctor ${report.generatedAt}\n`);
+    output.stdout(`Workspace: ${report.workspace.root ?? '(not registered)'}\n`);
+    output.stdout(`Runtime target: ${report.runtime.targetVersion ?? '(none)'}; machine: ${report.runtime.machineRuntime?.version ?? '(none)'}; passive state: ${report.runtime.passiveStatus ?? '(unknown)'}\n`);
+    for (const check of report.checks) {
+        output.stdout(`\n[${check.status.toUpperCase()}] ${check.id}: ${check.title}\n`);
+        output.stdout(`  ${check.summary}\n`);
+        output.stdout(`  source: ${check.source}\n`);
+        if (check.coverage !== null)
+            output.stdout(`  coverage: ${check.coverage}\n`);
+        for (const action of check.nextActions) {
+            output.stdout(`  next: ${action}\n`);
+        }
+    }
+    output.stdout(`\nSummary: ${report.summary.status} (exit ${report.summary.exitCode}); ` +
+        `ok=${report.summary.counts.ok}, warning=${report.summary.counts.warning}, ` +
+        `error=${report.summary.counts.error}, unknown=${report.summary.counts.unknown}, ` +
+        `partial=${report.summary.counts.partial}, unsupported=${report.summary.counts.unsupported}\n`);
+    if (report.scope.notChecked.length > 0) {
+        output.stdout(`Not checked: ${report.scope.notChecked.join(', ')}\n`);
+    }
+}
+/**
+ * Runs one read-only doctor report. JSON mode writes exactly one JSON document
+ * to stdout and never opens prompts or emits progress logs.
+ */
+export async function runDoctorCommand(options, output) {
+    try {
+        const report = await runDoctor({
+            root: options.root,
+            ...(options.dataDir === undefined ? {} : { dataDir: options.dataDir }),
+            ...(options.homeDir === undefined ? {} : { homeDir: options.homeDir }),
+            ...(options.pathEnv === undefined ? {} : { pathEnv: options.pathEnv }),
+        });
+        if (options.json) {
+            output.stdout(`${JSON.stringify(report)}\n`);
+        }
+        else {
+            printHuman(output, report);
+        }
+        return report.summary.exitCode;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (options.json) {
+            output.stdout(`${JSON.stringify({ ok: false, command: 'doctor', code: 'doctor_failed', message })}\n`);
+        }
+        else {
+            output.stderr(`pappra doctor: ${message}\n`);
+        }
+        return 1;
+    }
+}
+export const doctorUsage = 'pappra doctor [--root <path>] [--json]\n\n' +
+    'Read-only workspace, runtime, install-state, host, and tool diagnostics.\n' +
+    'Doctor never installs, repairs, indexes, starts hosts/models, or removes locks/runtimes.\n';

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

@@ -0,0 +1,17 @@
+import type { HostName } from '../../schemas/host.js';
+import type { CliOutput } from '../output.js';
+export declare const hostUsage: string;
+export interface HostCommandOptions {
+    readonly cwd: string;
+    readonly json: boolean;
+    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;
+    readonly marketplace: boolean;
+    readonly scope: 'project' | 'user' | null;
+}
+export declare function runHostCommand(options: HostCommandOptions, output: CliOutput): Promise<number>;

package/dist/cli/commands/host.js

@@ -0,0 +1,199 @@
+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 { 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.';
+/** Codex only loads lifecycle hooks from its user configuration directory. */
+function codexHome() {
+    const configured = process.env['CODEX_HOME'];
+    return configured === undefined || configured === ''
+        ? join(homedir(), '.codex')
+        : resolve(configured);
+}
+function printDiagnostics(output, diagnostics) {
+    for (const entry of diagnostics) {
+        if (typeof entry === 'object' &&
+            entry !== null &&
+            'message' in entry &&
+            typeof entry.message === 'string') {
+            if ('hint' in entry && typeof entry.hint === 'string') {
+                output.stderr(`${entry.message} Hint: ${entry.hint}\n`);
+            }
+            else {
+                output.stderr(`${entry.message}\n`);
+            }
+        }
+    }
+}
+function diagnosticStatus(status) {
+    return status === 'planned' ||
+        status === 'applied' ||
+        status === 'unchanged' ||
+        status === 'verified' ||
+        status === 'duplicate'
+        ? 0
+        : 1;
+}
+export async function runHostCommand(options, output) {
+    if (options.action === null || options.host === null) {
+        output.stderr('pappra: host requires an action and --host.\n');
+        return 2;
+    }
+    const service = new HostIntegrationService({
+        root: options.cwd,
+        homeDir: homedir(),
+        pathEnv: process.env.PATH ?? '',
+        hostVersion: options.hostVersion,
+        observedAt: new Date().toISOString(),
+    });
+    if (options.scope === 'user') {
+        if (HOST_SUPPORT[options.host].hookScope !== 'user') {
+            output.stderr(`pappra host: ${options.host} loads hooks from ${HOST_SUPPORT[options.host].hookScope} scope; --scope user is only valid for a user-scoped host (codex).\n`);
+            return 2;
+        }
+        if (options.hostRoot !== null) {
+            output.stderr('pappra host: --scope user resolves CODEX_HOME and cannot be combined with --host-root.\n');
+            return 2;
+        }
+        if (options.action !== 'plan' &&
+            options.action !== 'install' &&
+            options.action !== 'verify') {
+            output.stderr('pappra host: --scope user is only valid for plan, install, or verify.\n');
+            return 2;
+        }
+    }
+    const hostRoot = options.scope === 'user'
+        ? codexHome()
+        : options.hostRoot === null
+            ? undefined
+            : resolve(options.cwd, options.hostRoot);
+    const target = {
+        ...(hostRoot === undefined ? {} : { hostRoot }),
+        ...(options.hostVersion === null
+            ? {}
+            : { hostVersion: options.hostVersion }),
+    };
+    if (options.action === 'detect' || options.action === 'describe') {
+        const capabilities = service.describe(options.host);
+        if (options.json) {
+            output.stdout(`${JSON.stringify(capabilities)}\n`);
+        }
+        else {
+            output.stdout(`Host: ${capabilities.host} ${capabilities.version ?? '(unknown)'}\n`);
+            output.stdout(`Surface: ${capabilities.surface}\n`);
+            output.stdout(`Executable: ${capabilities.executablePath ?? 'missing'}\n`);
+            output.stdout(`Reload required: ${capabilities.reloadRequired ? 'yes' : 'no'}\n`);
+            output.stdout(`Trust required: ${capabilities.trustRequired ? 'yes' : 'no'}\n`);
+            for (const capability of capabilities.capabilities) {
+                output.stdout(`  ${capability.event}: ${capability.state}${capability.nativeEvent === null ? '' : ` (${capability.nativeEvent})`}\n`);
+            }
+        }
+        return 0;
+    }
+    if (options.action === 'plan') {
+        try {
+            const plan = await service.plan(options.host, target);
+            if (options.json) {
+                output.stdout(`${JSON.stringify(plan)}\n`);
+            }
+            else {
+                output.stdout(`Host: ${plan.host} @ ${plan.hostRoot}\n`);
+                output.stdout(`Bundle: ${plan.bundleDigest}\n`);
+                for (const file of plan.files) {
+                    output.stdout(`  ${file.operation} ${file.path}\n`);
+                }
+                printDiagnostics(output, plan.diagnostics);
+            }
+            return 0;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (options.json) {
+                output.stdout(`${JSON.stringify({ ok: false, command: 'host', code: 'host_plan_failed', message })}\n`);
+            }
+            else {
+                output.stderr(`pappra host: ${message}\n`);
+            }
+            return 1;
+        }
+    }
+    if (options.action === 'install') {
+        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`);
+        }
+        else {
+            output.stdout(`Status: ${result.status}\n`);
+            for (const file of result.appliedFiles)
+                output.stdout(`  applied ${file}\n`);
+            for (const path of result.residualPaths)
+                output.stdout(`  residual ${path}\n`);
+            printDiagnostics(output, result.diagnostics);
+        }
+        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,
+                marketplace: options.marketplace,
+            });
+            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`);
+    }
+    else {
+        output.stdout(`Status: ${result.status}\n`);
+        for (const check of result.checks) {
+            output.stdout(`  [${check.status}] ${check.id}: ${check.detail}\n`);
+        }
+        printDiagnostics(output, result.diagnostics);
+    }
+    return diagnosticStatus(result.status);
+}

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

@@ -0,0 +1,59 @@
+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 {
+    readonly value: string;
+    readonly label: string;
+    readonly hint?: string;
+}
+export interface WizardUi {
+    intro(message: string): void;
+    outro(message: string): void;
+    note(message: string, title: string): void;
+    text(message: string, initialValue?: string): Promise<string | symbol>;
+    select(message: string, options: readonly SelectOption[], initialValue?: string): Promise<string | symbol>;
+    multiselect(message: string, options: readonly SelectOption[], initialValues?: readonly string[]): Promise<readonly string[] | symbol>;
+    confirm(message: string, initialValue?: boolean): Promise<boolean | symbol>;
+    cancel(message: string): void;
+}
+export declare const clackWizardUi: WizardUi;
+/**
+ * UI-only selection collection. All validation and plan generation remains in
+ * the app service; cancelling this function never writes to the workspace.
+ */
+export declare function collectInitChoices(context: InitContext, ui: WizardUi): Promise<InitChoices | null>;
+export interface InitCommandOptions {
+    readonly cwd: string;
+    readonly configPath: string | null;
+    readonly apply: boolean;
+    readonly json: boolean;
+    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;
+    readonly completion: boolean;
+    readonly runtime: RuntimeInstallResult | null;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface InitCommandDeps {
+    readonly ui?: WizardUi;
+    readonly interactive?: boolean;
+}
+/**
+ * CLI command entry. In JSON mode no prompt is ever opened and stdout contains
+ * exactly one JSON document. Interactive selection is injected for tests.
+ */
+export declare function runInitCommand(options: InitCommandOptions, output: CliOutput, deps?: InitCommandDeps): Promise<number>;
+export declare const initUsage: string;