create-principles-disciple 1.82.0 → 1.83.0

package/console/dist/server/routes/config.js

@@ -0,0 +1,213 @@
+/**
+ * Config API Routes — PRI-309
+ *
+ * Console backend APIs for the Control Center:
+ * - GET  /api/v1/config/summary          — redacted config summary
+ * - GET  /api/v1/config/catalog           — available runtime/model catalog
+ * - PATCH /api/v1/config/agents/:name/binding — update agent runtime binding
+ * - GET  /api/v1/config/readiness/:name   — readiness test for agent
+ *
+ * Security:
+ * - Never returns raw provider objects, tokens, API keys, or env values
+ * - Validates before write, rejects malformed existing config
+ * - Rejects payloads with secret-like fields
+ *
+ * ERR entries:
+ * - ERR-001/ERR-005: No `as` bypasses on untrusted input
+ * - ERR-002: Graceful degradation includes reason
+ * - ERR-009/ERR-010: Required fields fail loud
+ * - ERR-013: Object.hasOwn() for untrusted keys
+ * - ERR-014/ERR-016/ERR-017: Safe serialization for previews
+ * - ERR-045: ANY-segment redaction for sensitive keys
+ */
+import { sendSuccess, sendError, sendNotFound, sendMethodNotAllowed, sendBadRequest } from '../utils/response.js';
+import { getConfigSummary, getConfigCatalog, updateAgentBinding, updateDefaultRuntime, checkReadiness, getPrinciplesOutputLanguage, updatePrinciplesOutputLanguage, } from '../config/pd-config-store.js';
+// ── Constants ────────────────────────────────────────────────────────────────
+const MAX_BODY_SIZE = 1024 * 64; // 64 KB — generous for config binding updates
+// ── Request Body Reader ──────────────────────────────────────────────────────
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let totalSize = 0;
+        req.on('data', (chunk) => {
+            totalSize += chunk.length;
+            if (totalSize > MAX_BODY_SIZE) {
+                reject(new Error('Request body exceeds maximum allowed size'));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+function safeParseBody(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+// ── Route Handler ────────────────────────────────────────────────────────────
+export async function handleConfigRoute(req, res, ctx) {
+    const { workspaceDir, subPath } = ctx;
+    const method = req.method ?? 'GET';
+    // GET /summary
+    if (subPath === '/summary') {
+        if (method !== 'GET') {
+            sendMethodNotAllowed(res);
+            return;
+        }
+        const { summary, errors } = getConfigSummary(workspaceDir);
+        sendSuccess(res, { ...summary, ...(errors ? { errors } : {}) });
+        return;
+    }
+    // GET /catalog
+    if (subPath === '/catalog') {
+        if (method !== 'GET') {
+            sendMethodNotAllowed(res);
+            return;
+        }
+        const catalog = getConfigCatalog(workspaceDir);
+        sendSuccess(res, catalog);
+        return;
+    }
+    // PATCH /default-runtime
+    if (subPath === '/default-runtime') {
+        if (method !== 'PATCH') {
+            sendMethodNotAllowed(res);
+            return;
+        }
+        let bodyText;
+        try {
+            bodyText = await readBody(req);
+        }
+        catch {
+            sendBadRequest(res, 'Request body exceeds maximum allowed size');
+            return;
+        }
+        const payload = safeParseBody(bodyText);
+        if (payload === null) {
+            sendBadRequest(res, 'Invalid JSON body');
+            return;
+        }
+        const result = updateDefaultRuntime(workspaceDir, payload);
+        if (!result.ok) {
+            sendError(res, result.statusCode, result.error, result.message);
+            return;
+        }
+        sendSuccess(res, { defaultRuntime: result.defaultRuntime });
+        return;
+    }
+    // PATCH /agents/:agentName/binding
+    const agentBindingMatch = /^\/agents\/([^/]+)\/binding$/.exec(subPath);
+    if (agentBindingMatch) {
+        if (method !== 'PATCH') {
+            sendMethodNotAllowed(res);
+            return;
+        }
+        let agentName;
+        try {
+            agentName = decodeURIComponent(agentBindingMatch[1] ?? '');
+        }
+        catch {
+            sendBadRequest(res, 'Invalid agent name encoding');
+            return;
+        }
+        let bodyText;
+        try {
+            bodyText = await readBody(req);
+        }
+        catch {
+            sendBadRequest(res, 'Request body exceeds maximum allowed size');
+            return;
+        }
+        const payload = safeParseBody(bodyText);
+        if (payload === null) {
+            sendBadRequest(res, 'Invalid JSON body');
+            return;
+        }
+        const result = updateAgentBinding(workspaceDir, agentName, payload);
+        if (!result.ok) {
+            sendError(res, result.statusCode, result.error, result.message);
+            return;
+        }
+        sendSuccess(res, {
+            agent: result.agent,
+            runtimeProfile: result.runtimeProfile,
+            enabled: result.enabled,
+        });
+        return;
+    }
+    // GET /readiness/:agentName
+    const readinessMatch = /^\/readiness\/([^/]+)$/.exec(subPath);
+    if (readinessMatch) {
+        if (method !== 'GET') {
+            sendMethodNotAllowed(res);
+            return;
+        }
+        let agentName;
+        try {
+            agentName = decodeURIComponent(readinessMatch[1] ?? '');
+        }
+        catch {
+            sendBadRequest(res, 'Invalid agent name encoding');
+            return;
+        }
+        const result = checkReadiness(workspaceDir, agentName);
+        if (!result.ok) {
+            sendError(res, result.statusCode, result.error, result.message);
+            return;
+        }
+        sendSuccess(res, {
+            agent: result.agent,
+            readiness: result.readiness,
+            profileId: result.profileId,
+            profileLabel: result.profileLabel,
+            ...(result.reason ? { reason: result.reason } : {}),
+            ...(result.nextAction ? { nextAction: result.nextAction } : {}),
+        });
+        return;
+    }
+    // GET/PATCH /principles/output-language — PRI-332 P1-1
+    if (subPath === '/principles/output-language') {
+        if (method === 'GET') {
+            const result = getPrinciplesOutputLanguage(workspaceDir);
+            if (!result.ok) {
+                sendError(res, result.statusCode, result.error, result.message);
+                return;
+            }
+            sendSuccess(res, { outputLanguage: result.outputLanguage, source: result.source });
+            return;
+        }
+        if (method === 'PATCH') {
+            let bodyText;
+            try {
+                bodyText = await readBody(req);
+            }
+            catch {
+                sendBadRequest(res, 'Request body is too large or unreadable');
+                return;
+            }
+            const body = safeParseBody(bodyText);
+            const result = updatePrinciplesOutputLanguage(workspaceDir, body);
+            if (!result.ok) {
+                sendError(res, result.statusCode, result.error, result.message);
+                return;
+            }
+            // Re-read to confirm actual persisted state — fail loud if re-read fails (ERR-002)
+            const confirmResult = getPrinciplesOutputLanguage(workspaceDir);
+            if (!confirmResult.ok) {
+                sendError(res, confirmResult.statusCode, 'confirm_read_failed', `Write succeeded but re-read failed: ${confirmResult.message}`);
+                return;
+            }
+            sendSuccess(res, { outputLanguage: confirmResult.outputLanguage, source: confirmResult.source });
+            return;
+        }
+        sendMethodNotAllowed(res);
+        return;
+    }
+    // 404 fallback
+    sendNotFound(res, `Route /api/v1/config${subPath} not found`);
+}

package/console/dist/server/routes/evidence-chain.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Evidence Chain API — exposes behavior evidence chain records for the Pain page.
+ *
+ * GET /api/v1/evidence-chain
+ *   Returns evidence chain records from pain_events, tasks, candidates, and ledger.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare function handleEvidenceChainRoute(req: IncomingMessage, res: ServerResponse, workspaceDir: string): Promise<void>;
+export declare function disposeEvidenceChainModels(): void;

package/console/dist/server/routes/evidence-chain.js

@@ -0,0 +1,32 @@
+import { EvidenceChainConsoleModel } from '../models/EvidenceChainConsoleModel.js';
+import { sendSuccess, sendError } from '../utils/response.js';
+const models = new Map();
+function getModel(workspaceDir) {
+    let model = models.get(workspaceDir);
+    if (!model) {
+        model = new EvidenceChainConsoleModel(workspaceDir);
+        models.set(workspaceDir, model);
+    }
+    return model;
+}
+export async function handleEvidenceChainRoute(req, res, workspaceDir) {
+    if (req.method !== 'GET') {
+        sendError(res, 405, 'method_not_allowed', 'Only GET is allowed for this route');
+        return;
+    }
+    const model = getModel(workspaceDir);
+    try {
+        const result = await model.getEvidenceChain();
+        sendSuccess(res, result);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        sendError(res, 500, 'evidence_chain_error', message);
+    }
+}
+export function disposeEvidenceChainModels() {
+    for (const model of models.values()) {
+        model.dispose();
+    }
+    models.clear();
+}

package/console/dist/server/routes/governance.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare function handleGovernanceRoute(req: IncomingMessage, res: ServerResponse, workspaceDir: string): Promise<void>;
+export declare function disposeGovernanceModels(): void;

package/console/dist/server/routes/governance.js

@@ -0,0 +1,32 @@
+import { GovernanceConsoleModel } from '../models/GovernanceConsoleModel.js';
+import { sendSuccess, sendError, sendNotFound } from '../utils/response.js';
+const models = new Map();
+function getModel(workspaceDir) {
+    let model = models.get(workspaceDir);
+    if (!model) {
+        model = new GovernanceConsoleModel(workspaceDir);
+        models.set(workspaceDir, model);
+    }
+    return model;
+}
+export async function handleGovernanceRoute(req, res, workspaceDir) {
+    if (req.method !== 'GET') {
+        sendNotFound(res, 'Route /api/v1/governance/queue not found');
+        return;
+    }
+    const model = getModel(workspaceDir);
+    try {
+        const result = await model.getGovernanceQueue();
+        sendSuccess(res, result);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        sendError(res, 500, 'governance_queue_error', message);
+    }
+}
+export function disposeGovernanceModels() {
+    for (const model of models.values()) {
+        model.dispose();
+    }
+    models.clear();
+}

package/console/dist/server/routes/{evolution.d.ts → lifecycle.d.ts}

@@ -1,3 +1,3 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-export declare function handleEvolutionRoute(req: IncomingMessage, res: ServerResponse, workspaceDir: string, subPath: string): Promise<void>;
-export declare function disposeEvolutionModels(): void;
+export declare function handleLifecycleRoute(req: IncomingMessage, res: ServerResponse, workspaceDir: string, subPath: string): Promise<void>;
+export declare function disposeLifecycleModels(): void;

package/console/dist/server/routes/lifecycle.js

@@ -0,0 +1,48 @@
+import { LifecycleConsoleModel } from '../models/LifecycleConsoleModel.js';
+import { sendSuccess, sendError, sendNotFound } from '../utils/response.js';
+const models = new Map();
+function getModel(workspaceDir) {
+    let model = models.get(workspaceDir);
+    if (!model) {
+        model = new LifecycleConsoleModel(workspaceDir);
+        models.set(workspaceDir, model);
+    }
+    return model;
+}
+/* eslint-disable @typescript-eslint/max-params */
+export async function handleLifecycleRoute(req, res, workspaceDir, subPath) {
+    if (req.method !== 'GET') {
+        sendNotFound(res, `Route /api/v1/lifecycle${subPath} not found`);
+        return;
+    }
+    // GET /api/v1/lifecycle/principles/:principleId
+    const principleMatch = /^[/]principles[/]([^/]+)$/.exec(subPath);
+    if (principleMatch) {
+        let principleId;
+        try {
+            principleId = decodeURIComponent(principleMatch[1]);
+        }
+        catch {
+            sendError(res, 400, 'invalid_encoding', 'Principle ID contains invalid percent encoding');
+            return;
+        }
+        const model = getModel(workspaceDir);
+        try {
+            const result = model.getLifecycleMetrics(principleId);
+            if (!result) {
+                sendNotFound(res, `Principle "${principleId}" not found in lifecycle read model`);
+                return;
+            }
+            sendSuccess(res, result);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            sendError(res, 500, 'lifecycle_metrics_error', message);
+        }
+        return;
+    }
+    sendNotFound(res, `Route /api/v1/lifecycle${subPath} not found`);
+}
+export function disposeLifecycleModels() {
+    models.clear();
+}

package/console/dist/server/routes/principles.js

@@ -1,3 +1,5 @@
+import * as path from 'path';
+import * as fs from 'fs';
 import { PrinciplesConsoleModel } from '../models/PrinciplesConsoleModel.js';
 import { sendSuccess, sendError, sendNotFound } from '../utils/response.js';
 const models = new Map();
@@ -9,6 +11,65 @@ function getModel(workspaceDir) {
     }
     return model;
 }
+/**
+ * Safely read an own string property from an unknown object.
+ * Returns the string value if the key exists and the value is a string,
+ * otherwise undefined. Uses Object.getOwnPropertyDescriptor to avoid
+ * any `as` cast on the row (EP-01 Rule 2).
+ */
+function getOwnStringField(obj, key) {
+    if (typeof obj !== 'object' || obj === null)
+        return undefined;
+    const desc = Object.getOwnPropertyDescriptor(obj, key);
+    if (desc === undefined)
+        return undefined;
+    return typeof desc.value === 'string' ? desc.value : undefined;
+}
+/**
+ * Query the SQLite state.db for principle IDs that have been decided
+ * (approved or rejected) via the approval queue.
+ *
+ * Returns { ids, unavailableReason } — if the DB is not available or the
+ * query fails, ids is empty and unavailableReason explains why, so the
+ * caller can surface this to the UI (ERR-002: no silent degradation).
+ */
+async function getDecidedPrincipleIds(workspaceDir) {
+    // Runtime V2 uses <workspace>/.pd/state.db (NOT .state/state.db)
+    const dbPath = path.join(workspaceDir, '.pd', 'state.db');
+    if (!fs.existsSync(dbPath)) {
+        return { ids: new Set(), unavailableReason: 'approval_db_not_found' };
+    }
+    let closeFn = null;
+    try {
+        const { SqliteConnection } = await import('@principles/core/runtime-v2');
+        const conn = new SqliteConnection({ workspaceDir, readonly: true });
+        closeFn = () => conn.close();
+        const db = conn.getDb();
+        // Join approvals with pi_artifacts to find decided principle IDs
+        const rows = db.prepare("SELECT DISTINCT a.source_principle_id " +
+            "FROM approvals ap " +
+            "JOIN pi_artifacts a ON a.artifact_id = ap.artifact_id " +
+            "WHERE ap.status IN ('approved', 'rejected') " +
+            "AND a.source_principle_id IS NOT NULL").all();
+        // EP-01 Rule 1: treat DB rows as unknown; validate before use
+        // EP-01 Rule 2: no `as` cast — use getOwnStringField instead
+        const ids = new Set();
+        for (const row of rows) {
+            const val = getOwnStringField(row, 'source_principle_id');
+            if (val !== undefined) {
+                ids.add(val);
+            }
+        }
+        return { ids };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ids: new Set(), unavailableReason: `approval_query_failed: ${message}` };
+    }
+    finally {
+        closeFn?.();
+    }
+}
 export async function handlePrinciplesRoute({ req, res, workspaceDir, subPath, }) {
     if (req.method !== 'GET') {
         sendNotFound(res, `Route /api/principles${subPath} not found`);
@@ -17,7 +78,19 @@ export async function handlePrinciplesRoute({ req, res, workspaceDir, subPath, }
     const model = getModel(workspaceDir);
     if (subPath === '' || subPath === '/') {
         try {
-            const result = await model.listPrinciples();
+            // Parse query string for filter parameter
+            const urlParts = (req.url ?? '').split('?');
+            const queryString = urlParts[1] ?? '';
+            const params = new URLSearchParams(queryString);
+            const filterRaw = params.get('filter');
+            const VALID_FILTERS = new Set(['all', 'actionable']);
+            const filter = (filterRaw !== null && VALID_FILTERS.has(filterRaw) ? filterRaw : 'actionable');
+            const decidedResult = await getDecidedPrincipleIds(workspaceDir);
+            const result = await model.listPrinciples(filter, decidedResult.ids);
+            // Surface approval cross-check unavailability to the UI (ERR-002)
+            if (decidedResult.unavailableReason) {
+                result.approvalCrossCheckUnavailable = decidedResult.unavailableReason;
+            }
             sendSuccess(res, result);
         }
         catch (err) {

package/console/dist/server/routes/workspaces.js

@@ -56,7 +56,14 @@ export function createWorkspacesRoutes(configStore, workspaceService) {
             return;
         }
         const [, wsName, rest] = nameMatch;
-        const decodedWsName = decodeURIComponent(wsName);
+        let decodedWsName;
+        try {
+            decodedWsName = decodeURIComponent(wsName);
+        }
+        catch {
+            sendError(res, 400, 'invalid_name', 'Workspace name contains invalid URI encoding');
+            return;
+        }
         if (req.method === 'GET' && (rest === '' || rest === '/')) {
             const entry = configStore.getWorkspace(decodedWsName);
             if (!entry) {

package/console/dist/server/utils/response.d.ts

@@ -1,7 +1,7 @@
 import type { ServerResponse } from 'node:http';
 export declare function sendJson(res: ServerResponse, statusCode: number, payload: unknown): void;
 export declare function sendSuccess<T>(res: ServerResponse, data: T): void;
-export declare function sendError(res: ServerResponse, statusCode: number, error: string, message?: string): void;
+export declare function sendError(res: ServerResponse, statusCode: number, error: string, message?: string, extras?: Record<string, unknown>): void;
 export declare function sendNotFound(res: ServerResponse, message?: string): void;
 export declare function sendUnauthorized(res: ServerResponse, message?: string): void;
 export declare function sendMethodNotAllowed(res: ServerResponse): void;

package/console/dist/server/utils/response.js

@@ -14,8 +14,12 @@ export function sendSuccess(res, data) {
     sendJson(res, 200, { success: true, data });
 }
 /* eslint-disable @typescript-eslint/max-params */
-export function sendError(res, statusCode, error, message) {
-    sendJson(res, statusCode, { success: false, error, message: message ?? error });
+export function sendError(res, statusCode, error, message, extras) {
+    const payload = { success: false, error, message: message ?? error };
+    if (extras) {
+        Object.assign(payload, extras);
+    }
+    sendJson(res, statusCode, payload);
 }
 export function sendNotFound(res, message = 'Not found') {
     sendError(res, 404, 'not_found', message);

package/console/dist/types.d.ts

@@ -82,4 +82,5 @@ export type ApiResponse<T> = {
 } | {
     success: false;
     error: string;
+    nextAction?: string;
 };