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

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

@@ -0,0 +1,16 @@
+import type { CodeQueryKind } from '../../schemas/code.js';
+import type { CliOutput } from '../output.js';
+export declare const codeUsage: string;
+export interface CodeCommandOptions {
+    readonly cwd: string;
+    readonly json: boolean;
+    readonly action: 'status' | 'prepare' | 'query' | null;
+    readonly repositoryId: string | null;
+    readonly kind: CodeQueryKind | null;
+    readonly query: string | null;
+    readonly maxResults: number | null;
+    readonly maxBytes: number | null;
+    readonly apply: boolean;
+    readonly rebuild: boolean;
+}
+export declare function runCodeCommand(options: CodeCommandOptions, output: CliOutput): Promise<number>;

package/dist/cli/commands/code.js

@@ -0,0 +1,127 @@
+import { formatDiagnostic } from '../../schemas/diagnostics.js';
+import { CodeIntelligenceService } from '../../code/service.js';
+import { resolveWorkspaceRoot } from '../../workspace/resolve.js';
+export const codeUsage = 'pappra code status --repo <id> [--json]\n' +
+    'pappra code prepare --repo <id> [--apply] [--rebuild] [--json]\n' +
+    'pappra code query --repo <id> --kind explore|symbol|references|impact|text --query <text>\n' +
+    '  [--limit <1-100>] [--max-bytes <bytes>] [--json]';
+function printDiagnostics(output, diagnostics) {
+    for (const diagnostic of diagnostics) {
+        output.stderr(`${formatDiagnostic(diagnostic)}\n`);
+    }
+}
+async function serviceRoot(cwd) {
+    const resolution = await resolveWorkspaceRoot({ startPath: cwd });
+    return resolution.root ?? cwd;
+}
+function statusJson(result) {
+    return {
+        schema: 'pappra/code-status-result/1',
+        ok: result.ok,
+        identity: result.identity,
+        health: result.health,
+        registrationPath: result.registrationPath,
+        registrationPresent: result.registrationPresent,
+        diagnostics: result.diagnostics,
+    };
+}
+export async function runCodeCommand(options, output) {
+    if (options.action === null) {
+        output.stderr('pappra: code requires status, prepare, or query.\n');
+        return 2;
+    }
+    if (options.repositoryId === null) {
+        output.stderr('pappra: code requires --repo <id>.\n');
+        return 2;
+    }
+    const root = await serviceRoot(options.cwd);
+    const service = new CodeIntelligenceService(root);
+    if (options.action === 'status') {
+        const result = await service.status({ repositoryId: options.repositoryId });
+        if (options.json) {
+            output.stdout(`${JSON.stringify(statusJson(result))}\n`);
+        }
+        else {
+            output.stdout(`Repository: ${options.repositoryId}\n`);
+            output.stdout(`Identity: ${result.identity?.checkoutId ?? 'unavailable'}\n`);
+            output.stdout(`Index: ${result.health.state}\n`);
+            output.stdout(`Registration: ${result.registrationPresent ? 'present' : 'missing'}\n`);
+            for (const reason of result.health.reasons)
+                output.stdout(`Reason: ${reason}\n`);
+            printDiagnostics(output, result.diagnostics);
+        }
+        return result.ok ? 0 : 1;
+    }
+    if (options.action === 'prepare') {
+        const result = await service.prepare({
+            root,
+            repositoryId: options.repositoryId,
+            apply: options.apply,
+            rebuild: options.rebuild,
+        });
+        if (options.json) {
+            output.stdout(`${JSON.stringify(result)}\n`);
+        }
+        else {
+            output.stdout(`Prepare plan: ${result.plan.action}\n`);
+            output.stdout(`Mutates index: ${result.plan.mutates ? 'yes' : 'no'}\n`);
+            output.stdout(`Index: ${result.health.state}\n`);
+            if (result.registrationPath !== null) {
+                output.stdout(`Registration: ${result.registrationPath}\n`);
+            }
+            for (const reason of result.plan.reasons)
+                output.stdout(`Reason: ${reason}\n`);
+            printDiagnostics(output, result.diagnostics);
+        }
+        return result.ok || result.status === 'planned' ? 0 : 1;
+    }
+    if (options.kind === null || options.query === null) {
+        output.stderr('pappra: code query requires --kind and --query.\n');
+        return 2;
+    }
+    const result = await service.query({
+        root,
+        repositoryId: options.repositoryId,
+        kind: options.kind,
+        query: options.query,
+        ...(options.maxResults === null && options.maxBytes === null
+            ? {}
+            : {
+                limits: {
+                    ...(options.maxResults === null
+                        ? {}
+                        : { maxResults: options.maxResults }),
+                    ...(options.maxBytes === null
+                        ? {}
+                        : { maxBytes: options.maxBytes }),
+                },
+            }),
+    });
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            schema: 'pappra/code-query-result/1',
+            ok: result.ok,
+            health: result.health,
+            result: result.result,
+            diagnostics: result.diagnostics,
+        })}\n`);
+    }
+    else if (result.result !== null) {
+        output.stdout(`Query: ${result.result.kind} ${result.result.query}\n`);
+        output.stdout(`Coverage: ${result.result.coverage}\n`);
+        output.stdout(`Provider: ${result.result.provider}\n`);
+        for (const item of result.result.items) {
+            output.stdout(`${item.path}:${item.line ?? '?'}:${item.column ?? '?'} ${item.kind} ${item.name ?? ''}\n`);
+            if (item.snippet !== '')
+                output.stdout(`  ${item.snippet}\n`);
+        }
+        if (result.result.unsupportedReason !== null) {
+            output.stdout(`Note: ${result.result.unsupportedReason}\n`);
+        }
+        printDiagnostics(output, result.diagnostics);
+    }
+    else {
+        printDiagnostics(output, result.diagnostics);
+    }
+    return result.ok ? 0 : 1;
+}

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

@@ -0,0 +1,13 @@
+import type { CliOutput } from '../output.js';
+export declare const collaborationUsage: string;
+export interface CollaborationCommandOptions {
+    readonly cwd: string;
+    readonly action: string | null;
+    readonly json: boolean;
+    readonly goalFile: string | null;
+    readonly preparedFile: string | null;
+    readonly capabilitiesFile: string | null;
+    readonly controller: string | null;
+    readonly domainRoot: string | null;
+}
+export declare function runCollaborationCommand(options: CollaborationCommandOptions, output: CliOutput, input?: NodeJS.ReadableStream): Promise<number>;

package/dist/cli/commands/collaboration.js

@@ -0,0 +1,186 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { FixtureController, PiRpcController, driveRun, inspectPreparedHistory, prepareCollaboration, startPrepared, } from '../../app/collaboration.js';
+export const collaborationUsage = 'pappra collab <prepare|run|query> [options]\n' +
+    '  prepare --goal <file> --domain-root <dir> [--json]\n' +
+    '  run --prepared <file> --capabilities <card> --controller <fixture|pi-rpc>\n' +
+    '  query --prepared <file> [--json]\n' +
+    '  run reads pappra/collaboration-command/1 JSONL from stdin and writes\n' +
+    '  pappra/collaboration-event/1 JSONL to stdout.';
+function failure(code, message) {
+    return { schema: 'pappra/collaboration-result/1', ok: false, code, message };
+}
+function readGoal(file) {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.size > 1024 * 1024) {
+        throw new Error('goal file must be a regular file no larger than 1 MiB');
+    }
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+function controllerFor(name) {
+    if (name === 'fixture')
+        return new FixtureController();
+    if (name === 'pi-rpc')
+        return new PiRpcController();
+    return null;
+}
+const MAX_COMMAND_LINE_BYTES = 256 * 1024;
+const MAX_COMMAND_TOTAL_BYTES = 4 * 1024 * 1024;
+const MAX_QUEUED_COMMANDS = 64;
+function lines(stream) {
+    let buffer = '';
+    const queue = [];
+    let ended = false;
+    let error = null;
+    let total = 0;
+    let notify = null;
+    stream.setEncoding('utf8');
+    stream.on('data', (chunk) => {
+        if (error !== null)
+            return;
+        total += Buffer.byteLength(chunk);
+        if (total > MAX_COMMAND_TOTAL_BYTES) {
+            error = new Error('run command input exceeded its aggregate bound');
+            ended = true;
+            notify?.();
+            return;
+        }
+        buffer += chunk;
+        if (Buffer.byteLength(buffer) > MAX_COMMAND_LINE_BYTES) {
+            error = new Error('run command line exceeded its bound');
+            ended = true;
+            notify?.();
+            return;
+        }
+        for (;;) {
+            const newline = buffer.indexOf('\n');
+            if (newline < 0)
+                break;
+            queue.push(buffer.slice(0, newline));
+            buffer = buffer.slice(newline + 1);
+            if (queue.length > MAX_QUEUED_COMMANDS) {
+                error = new Error('run command queue exceeded its bound');
+                ended = true;
+                notify?.();
+                return;
+            }
+        }
+        notify?.();
+    });
+    stream.on('error', (streamError) => {
+        error = streamError;
+        ended = true;
+        notify?.();
+    });
+    stream.on('end', () => {
+        if (buffer.length > 0)
+            queue.push(buffer);
+        ended = true;
+        notify?.();
+    });
+    return {
+        async *[Symbol.asyncIterator]() {
+            for (;;) {
+                if (error !== null)
+                    throw error;
+                if (queue.length > 0) {
+                    yield queue.shift();
+                    continue;
+                }
+                if (ended)
+                    return;
+                await new Promise((resolve) => {
+                    notify = resolve;
+                });
+                notify = null;
+            }
+        },
+    };
+}
+export async function runCollaborationCommand(options, output, input = process.stdin) {
+    if (options.action === 'prepare') {
+        if (options.goalFile === null) {
+            output.stderr('pappra: collab prepare requires --goal <file>\n');
+            return 2;
+        }
+        if (options.domainRoot === null) {
+            output.stdout(`${JSON.stringify(failure('domain_root_required', 'collab prepare requires --domain-root so shared-resource conflicts use one explicit domain'))}\n`);
+            return 2;
+        }
+        const domainRoot = options.domainRoot;
+        let goal;
+        try {
+            goal = readGoal(options.goalFile);
+        }
+        catch (error) {
+            output.stdout(`${JSON.stringify(failure('goal_unreadable', error instanceof Error ? error.message : String(error)))}\n`);
+            return 2;
+        }
+        const result = await prepareCollaboration(goal, {
+            domainRoot: path.resolve(domainRoot),
+        });
+        if (!result.ok) {
+            output.stdout(`${JSON.stringify(result)}\n`);
+            return 1;
+        }
+        output.stdout(`${JSON.stringify({
+            schema: 'pappra/collaboration-prepared/1',
+            ok: true,
+            status: 'prepared',
+            prepared: result.value.prepared,
+        })}\n`);
+        return 0;
+    }
+    if (options.action === 'query') {
+        if (options.preparedFile === null) {
+            output.stderr('pappra: collab query requires --prepared <file>\n');
+            return 2;
+        }
+        const result = inspectPreparedHistory(path.resolve(options.preparedFile));
+        output.stdout(`${JSON.stringify(result)}\n`);
+        return result.ok ? 0 : 1;
+    }
+    if (options.action === 'run') {
+        if (options.preparedFile === null || options.capabilitiesFile === null) {
+            output.stderr('pappra: collab run requires --prepared <file> and --capabilities <card>\n');
+            return 2;
+        }
+        const controller = controllerFor(options.controller);
+        if (controller === null) {
+            output.stderr('pappra: collab run requires --controller <fixture|pi-rpc>\n');
+            return 2;
+        }
+        const started = await startPrepared(path.resolve(options.preparedFile), {
+            capabilitiesFile: path.resolve(options.capabilitiesFile),
+            controller,
+            controllerId: controller.id,
+        });
+        if (!started.ok) {
+            output.stdout(`${JSON.stringify(started)}\n`);
+            return 1;
+        }
+        const commands = (async function* () {
+            for await (const line of lines(input)) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    yield JSON.parse(trimmed);
+                }
+                catch {
+                    yield { schema: 'pappra/collaboration-command/1', action: 'invalid' };
+                }
+            }
+        })();
+        const result = await driveRun(started.value, commands, (event) => {
+            output.stdout(`${JSON.stringify(event)}\n`);
+        });
+        if (!result.ok) {
+            output.stderr(`pappra: ${result.code}: ${result.message}\n`);
+            return 1;
+        }
+        return result.value.ok ? 0 : 1;
+    }
+    output.stderr('pappra: collab requires prepare, run, or query\n');
+    return 2;
+}

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

@@ -0,0 +1,29 @@
+import type { CliOutput } from '../output.js';
+export declare const checkpointUsage: string;
+export declare const resumeUsage = "pappra resume <taskId> [--session <native-session-id>] [--json]";
+export interface CheckpointCommandOptions {
+    readonly cwd: string;
+    readonly json: boolean;
+    readonly task: string | null;
+    readonly objective: string | null;
+    readonly acceptance: readonly string[];
+    readonly constraints: readonly string[];
+    readonly decisions: readonly string[];
+    readonly attempted: readonly string[];
+    readonly nextActions: readonly string[];
+    readonly limitations: readonly string[];
+    readonly artifacts: readonly string[];
+    readonly collaborationRecordRef: string | null;
+    readonly contextCompleteness: 'complete' | 'partial' | null;
+    readonly authorSession: string | null;
+    readonly nativeHarness: 'pi' | 'codex' | 'claude' | 'unknown' | null;
+    readonly nativeSession: string | null;
+}
+export interface ResumeCommandOptions {
+    readonly cwd: string;
+    readonly json: boolean;
+    readonly taskId: string;
+    readonly currentSession: string | null;
+}
+export declare function runCheckpointCommand(options: CheckpointCommandOptions, output: CliOutput): Promise<number>;
+export declare function runResumeCommand(options: ResumeCommandOptions, output: CliOutput): Promise<number>;

package/dist/cli/commands/continuity.js

@@ -0,0 +1,133 @@
+import { formatDiagnostic } from '../../schemas/diagnostics.js';
+import { CheckpointService, } from '../../continuity/index.js';
+import { resolveWorkspaceRoot } from '../../workspace/resolve.js';
+export const checkpointUsage = 'pappra checkpoint --task <id> [options]\n' +
+    '  --objective <text> --acceptance <text> [--acceptance <text> ...]\n' +
+    '  [--constraint <text> ...] [--decision <text> ...]\n' +
+    '  [--attempted <text> ...] [--next-action <text> ...]\n' +
+    '  [--limitation <text> ...] [--artifact <path> ...]\n' +
+    '  [--collaboration-record <path>] [--context-completeness complete|partial]\n' +
+    '  [--author-session <id>] [--native-harness pi|codex|claude|unknown]\n' +
+    '  [--native-session <id>] [--json]';
+export const resumeUsage = 'pappra resume <taskId> [--session <native-session-id>] [--json]';
+function printDiagnostics(output, diagnostics) {
+    for (const diagnostic of diagnostics) {
+        output.stderr(`${formatDiagnostic(diagnostic)}\n`);
+    }
+}
+async function serviceRoot(cwd) {
+    const resolution = await resolveWorkspaceRoot({ startPath: cwd });
+    return resolution.root ?? cwd;
+}
+export async function runCheckpointCommand(options, output) {
+    if (options.task === null) {
+        output.stderr('pappra: checkpoint requires --task\n');
+        return 2;
+    }
+    const root = await serviceRoot(options.cwd);
+    const service = new CheckpointService(root);
+    const nativeSession = options.nativeSession ?? options.authorSession;
+    const input = {
+        taskId: options.task,
+        ...(options.objective === null ? {} : { objective: options.objective }),
+        ...(options.acceptance.length === 0
+            ? {}
+            : { acceptance: options.acceptance }),
+        constraints: options.constraints,
+        decisions: options.decisions,
+        attempted: options.attempted,
+        nextActions: options.nextActions,
+        limitations: options.limitations,
+        artifacts: options.artifacts,
+        ...(options.collaborationRecordRef === null
+            ? {}
+            : { collaborationRecordRef: options.collaborationRecordRef }),
+        ...(options.contextCompleteness === null
+            ? {}
+            : { contextCompleteness: options.contextCompleteness }),
+        authorSession: options.authorSession,
+        ...(nativeSession === null
+            ? {}
+            : {
+                nativeRefs: [
+                    {
+                        harness: options.nativeHarness ?? 'pi',
+                        sessionId: nativeSession,
+                        turnId: null,
+                        runId: null,
+                    },
+                ],
+            }),
+    };
+    const result = await service.save(input);
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            schema: 'pappra/checkpoint-result/1',
+            ok: result.ok,
+            status: result.status,
+            checkpoint: result.checkpoint,
+            checkpointPath: result.checkpointPath,
+            latestPath: result.latestPath,
+            diagnostics: result.diagnostics,
+            residualPaths: result.residualPaths,
+        })}\n`);
+    }
+    else if (result.checkpoint !== null) {
+        output.stdout(`checkpoint ${result.checkpoint.revision} saved: ${result.checkpointPath ?? 'unknown'}\n`);
+        printDiagnostics(output, result.diagnostics);
+    }
+    else {
+        printDiagnostics(output, result.diagnostics);
+    }
+    return result.ok ? 0 : 1;
+}
+export async function runResumeCommand(options, output) {
+    const root = await serviceRoot(options.cwd);
+    const service = new CheckpointService(root);
+    const result = await service.resume({
+        taskId: options.taskId,
+        currentSession: options.currentSession,
+    });
+    if (options.json) {
+        if (result.packet !== null) {
+            output.stdout(`${JSON.stringify(result.packet)}\n`);
+        }
+        else {
+            output.stdout(`${JSON.stringify({
+                schema: 'pappra/resume-result/1',
+                ok: false,
+                status: result.status,
+                diagnostics: result.diagnostics,
+            })}\n`);
+        }
+    }
+    else if (result.packet !== null) {
+        const packet = result.packet;
+        output.stdout(`Task: ${packet.taskId}\n`);
+        output.stdout(`Checkpoint: ${packet.checkpoint.ref}@${packet.checkpoint.revision}\n`);
+        output.stdout(`Execution allowed: ${packet.executionAllowed ? 'yes' : 'no'}\n`);
+        output.stdout(`Context: ${packet.contextCompleteness}\n`);
+        output.stdout(`Code drift: ${packet.codeDrift.status}\n`);
+        output.stdout(`Verification: ${packet.verificationStatus}\n`);
+        output.stdout(`Objective: ${packet.boundedContext.objective}\n`);
+        for (const reason of packet.blockingReasons) {
+            output.stdout(`Blocked: ${reason.code}: ${reason.message}\n`);
+        }
+        for (const action of packet.boundedContext.nextActions) {
+            output.stdout(`Next: ${action}\n`);
+        }
+        for (const observation of packet.executionObservations) {
+            output.stdout(`Observation: ${observation.harness}/${observation.sessionId ?? 'unknown'} stored-snapshot live=${observation.liveStatus}\n`);
+        }
+        printDiagnostics(output, result.diagnostics);
+    }
+    else {
+        printDiagnostics(output, result.diagnostics);
+    }
+    return result.ok &&
+        result.packet !== null &&
+        result.packet.executionAllowed &&
+        result.packet.verificationStatus === 'current'
+        ? 0
+        : 1;
+}

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

@@ -0,0 +1,11 @@
+import type { CliOutput } from '../output.js';
+export declare const docsUsage: string;
+export interface DocsCommandOptions {
+    readonly cwd: string;
+    readonly action: string | null;
+    readonly argument: string | null;
+    readonly json: boolean;
+    readonly includePrivate: boolean;
+    readonly includeArchived: boolean;
+}
+export declare function runDocsCommand(options: DocsCommandOptions, output: CliOutput): Promise<number>;

package/dist/cli/commands/docs.js

@@ -0,0 +1,133 @@
+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' +
+    '  list   [--include-private] [--include-archived] [--json]\n' +
+    '  check  [--include-private] [--json]\n' +
+    '  archive <documentId> [--json]';
+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'].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 === '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;