@phyzess/pappra 0.1.0-beta.12 → 0.1.0-beta.14

package/dist/app/task-pin.js

@@ -0,0 +1,113 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { readTextFileBounded } from '../infra/fs.js';
+import { workspaceConfigSchema } from '../schemas/workspace.js';
+export const TASK_PIN_SCHEMA = 'pappra/task-pin/1';
+const TASK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function pinPath(root) {
+    return join(root, '.pappra', 'local', 'current-task');
+}
+export async function readTaskPin(root) {
+    const read = await readTextFileBounded(pinPath(root), 64 * 1024);
+    if (!read.ok)
+        return null;
+    try {
+        const value = JSON.parse(read.value.text);
+        if (typeof value !== 'object' ||
+            value === null ||
+            !('schema' in value) ||
+            value.schema !== TASK_PIN_SCHEMA ||
+            !('taskId' in value) ||
+            typeof value.taskId !== 'string' ||
+            !TASK_ID.test(value.taskId)) {
+            return null;
+        }
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+export async function pinTask(root, taskId) {
+    if (!TASK_ID.test(taskId)) {
+        return {
+            ok: false,
+            message: 'task id must be a short identifier (letters, digits, dot, dash, underscore).',
+        };
+    }
+    const pin = {
+        schema: TASK_PIN_SCHEMA,
+        taskId,
+        pinnedAt: new Date().toISOString(),
+    };
+    const target = pinPath(root);
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    const temporary = `${target}.tmp-${randomUUID()}`;
+    await writeFile(temporary, `${JSON.stringify(pin, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    await rename(temporary, target);
+    return pin;
+}
+export async function unpinTask(root) {
+    const target = pinPath(root);
+    const { rm } = await import('node:fs/promises');
+    await rm(target, { force: true });
+    return { ok: true };
+}
+/**
+ * Toggles the workspace-level auto-resume switch. The hook only injects a resume
+ * packet when this switch is on and a task pin exists; neither is inferred.
+ */
+export async function setAutoResume(root, enabled) {
+    const configPath = join(root, '.pappra', 'workspace.json');
+    const read = await readTextFileBounded(configPath, 1024 * 1024);
+    if (!read.ok) {
+        return { ok: false, message: read.message };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(read.value.text);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: `workspace.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const parsed = workspaceConfigSchema.safeParse({
+        ...(typeof raw === 'object' && raw !== null ? raw : {}),
+        continuity: { autoResume: enabled },
+    });
+    if (!parsed.success) {
+        return {
+            ok: false,
+            message: `workspace.json rejected the continuity switch: ${parsed.error.issues[0]?.message ?? 'invalid'}`,
+        };
+    }
+    const backup = join(root, '.pappra', 'local', 'backups', `task-pin-${randomUUID()}`, 'workspace.json');
+    await mkdir(dirname(backup), { recursive: true, mode: 0o700 });
+    await writeFile(backup, read.value.text, { mode: 0o600 });
+    const temporary = `${configPath}.tmp-${randomUUID()}`;
+    await writeFile(temporary, `${JSON.stringify(parsed.data, null, 2)}\n`);
+    await rename(temporary, configPath);
+    return { ok: true };
+}
+export async function readAutoResume(root) {
+    const read = await readFile(join(root, '.pappra', 'workspace.json'), 'utf8');
+    try {
+        const raw = JSON.parse(read);
+        if (typeof raw !== 'object' || raw === null || !('continuity' in raw)) {
+            return false;
+        }
+        const continuity = raw.continuity;
+        return (typeof continuity === 'object' &&
+            continuity !== null &&
+            'autoResume' in continuity &&
+            continuity.autoResume === true);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cli/commands/docs.js

@@ -1,5 +1,5 @@
-import { discoverWorkspace } from '../../workspace/discover.js';
 import { resolveWorkspaceRoot } from '../../workspace/resolve.js';
+import { scanDiscoveredDocuments } from '../../knowledge/scan.js';
 import { formatDiagnostic } from '../../schemas/diagnostics.js';
 import { docsArchiveReportSchema, docsCheckReportSchema, docsListReportSchema, } from '../../schemas/document.js';
 import { KnowledgeService, } from '../../knowledge/index.js';
@@ -10,96 +10,32 @@ export const docsUsage = 'pappra docs <list|check|archive|scan> [options]\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 }];
-    });
+    const result = await scanDiscoveredDocuments(root, { apply: options.apply });
+    if ('message' in result) {
+        return invalidArguments(output, options.json, result.message);
+    }
     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`);
+            output.stdout(`${JSON.stringify(result)}\n`);
         }
         else {
-            output.stdout(`Scan candidates: ${candidates.length}\n`);
-            for (const candidate of candidates) {
+            output.stdout(`Scan candidates: ${result.candidates.length}\n`);
+            for (const candidate of result.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`);
+        output.stdout(`${JSON.stringify(result)}\n`);
     }
     else {
-        output.stdout(`Registered ${registeredNow.length} document(s).\n`);
-        printDiagnostics(output, diagnostics);
+        output.stdout(`Registered ${result.registered.length} document(s).\n`);
+        printDiagnostics(output, result.diagnostics);
     }
-    return ok ? 0 : 1;
+    return result.ok ? 0 : 1;
 }
 function printDiagnostics(output, diagnostics) {
     for (const diagnostic of diagnostics) {

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

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

package/dist/cli/commands/host.js

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

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

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

package/dist/cli/commands/mcp.js

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

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

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

package/dist/cli/commands/task.js

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