create-principles-disciple 1.94.0 → 1.96.0

package/console/dist/server/models/IntentDecisionModel.js

@@ -0,0 +1,207 @@
+/**
+ * IntentDecisionModel — Console model for IntentDecisionRecord (PRI-470).
+ *
+ * Holds the workspaceDir (like ApprovalsConsoleModel) and opens a per-request
+ * SqliteConnection inside each method: open → delegate to SqliteIntentDecisionStore
+ * → close. This keeps each operation isolated and safe across workspaces.
+ *
+ * Graceful degradation (SPEC §21.7 / ERR-002):
+ * - Missing state.db → reads return null/empty/zero summary; writes return a
+ *   structured `not_initialized` result so the route can map to a clear HTTP
+ *   error instead of silently creating a half-initialized workspace.
+ * - Missing intent_decisions table → reads degrade to empty; writes re-throw
+ *   (the table is created by SqliteConnection.initSchema, so its absence
+ *   signals a corrupted or pre-PD workspace that should not be written to).
+ *
+ * ERR checklist:
+ * - EP-01 / ERR-001, ERR-005: store rows validated via core type guards
+ * - EP-03 / ERR-002: every degraded path carries reason + nextAction
+ * - EP-09: model is a thin I/O adapter over the pure store contract
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { SqliteConnection, SqliteIntentDecisionStore, } from '@principles/core/runtime-v2';
+function stateDbExists(workspaceDir) {
+    return fs.existsSync(path.join(workspaceDir, '.pd', 'state.db'));
+}
+function isMissingTableError(err) {
+    if (!(err instanceof Error))
+        return false;
+    return err.message.includes('no such table');
+}
+function emptySummary() {
+    return {
+        counts: {
+            confirm_drift: 0,
+            revise_intent: 0,
+            observe: 0,
+            dismiss: 0,
+            promote_to_principle: 0,
+            promote_to_rulehost: 0,
+        },
+        lastDecisionAt: null,
+    };
+}
+export class IntentDecisionModel {
+    workspaceDir;
+    constructor(workspaceDir) {
+        this.workspaceDir = workspaceDir;
+    }
+    async record(input) {
+        if (!stateDbExists(this.workspaceDir)) {
+            return {
+                ok: false,
+                reason: 'state_db_not_found',
+                nextAction: 'Initialize the workspace with PD (run a diagnosis or pd config) before recording intent decisions.',
+            };
+        }
+        const connection = new SqliteConnection({ workspaceDir: this.workspaceDir });
+        try {
+            const store = new SqliteIntentDecisionStore(connection);
+            const result = await store.record(input);
+            return { ok: true, record: result.record, created: result.created };
+        }
+        catch (err) {
+            if (isMissingTableError(err)) {
+                return {
+                    ok: false,
+                    reason: 'intent_decisions_table_missing',
+                    nextAction: 'Run pd config doctor or re-initialize the workspace so the intent_decisions table is created.',
+                };
+            }
+            throw err;
+        }
+        finally {
+            try {
+                connection.close();
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    async getById(id) {
+        if (!stateDbExists(this.workspaceDir))
+            return null;
+        const connection = new SqliteConnection({ workspaceDir: this.workspaceDir, readonly: true });
+        try {
+            const store = new SqliteIntentDecisionStore(connection);
+            return await store.getById(id);
+        }
+        catch (err) {
+            if (isMissingTableError(err))
+                return null;
+            throw err;
+        }
+        finally {
+            try {
+                connection.close();
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    async listByPainId(painId) {
+        if (!stateDbExists(this.workspaceDir))
+            return [];
+        const connection = new SqliteConnection({ workspaceDir: this.workspaceDir, readonly: true });
+        try {
+            const store = new SqliteIntentDecisionStore(connection);
+            return await store.listByPainId(painId);
+        }
+        catch (err) {
+            if (isMissingTableError(err))
+                return [];
+            throw err;
+        }
+        finally {
+            try {
+                connection.close();
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    async listByTaskId(taskId) {
+        if (!stateDbExists(this.workspaceDir))
+            return [];
+        const connection = new SqliteConnection({ workspaceDir: this.workspaceDir, readonly: true });
+        try {
+            const store = new SqliteIntentDecisionStore(connection);
+            return await store.listByTaskId(taskId);
+        }
+        catch (err) {
+            if (isMissingTableError(err))
+                return [];
+            throw err;
+        }
+        finally {
+            try {
+                connection.close();
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    async getSummary() {
+        if (!stateDbExists(this.workspaceDir))
+            return emptySummary();
+        const connection = new SqliteConnection({ workspaceDir: this.workspaceDir, readonly: true });
+        try {
+            const store = new SqliteIntentDecisionStore(connection);
+            return await store.getSummary();
+        }
+        catch (err) {
+            if (isMissingTableError(err))
+                return emptySummary();
+            throw err;
+        }
+        finally {
+            try {
+                connection.close();
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    /**
+     * Update follow-up action fields on an existing IntentDecisionRecord
+     * (PRI-471, SPEC §22.1.4).
+     *
+     * Called by the follow-up route after the Owner decision has been
+     * persisted. Only fields present in `patch` are written; the rest stay
+     * unchanged. Returns the updated record or a structured failure.
+     */
+    async updateFollowUp(id, patch) {
+        if (!stateDbExists(this.workspaceDir)) {
+            return {
+                ok: false,
+                reason: 'state_db_not_found',
+                nextAction: 'Initialize the workspace with PD (run a diagnosis or pd config) before dispatching follow-up actions.',
+            };
+        }
+        const connection = new SqliteConnection({ workspaceDir: this.workspaceDir });
+        try {
+            const store = new SqliteIntentDecisionStore(connection);
+            const record = await store.updateFollowUp(id, patch);
+            if (record === null) {
+                return {
+                    ok: false,
+                    reason: 'decision_not_found',
+                    nextAction: 'Intent decision ' + id + ' does not exist. Refresh the page and try again.',
+                };
+            }
+            return { ok: true, record };
+        }
+        catch (err) {
+            if (isMissingTableError(err)) {
+                return {
+                    ok: false,
+                    reason: 'intent_decisions_table_missing',
+                    nextAction: 'Run pd config doctor or re-initialize the workspace so the intent_decisions table is created.',
+                };
+            }
+            throw err;
+        }
+        finally {
+            try {
+                connection.close();
+            }
+            catch { /* best-effort */ }
+        }
+    }
+}

package/console/dist/server/models/IntentPageModel.d.ts

@@ -0,0 +1,52 @@
+import { type IntentDocWarning, type IntentDocVersion, type IntentLang } from '@principles/core/runtime-v2';
+export interface IntentPageResult {
+    ok: boolean;
+    found: boolean;
+    flagEnabled: boolean;
+    warnings: IntentDocWarning[];
+    path?: string;
+    contentHash?: string;
+    lastEditedAt?: string;
+    sections?: Record<string, string>;
+    reason?: string;
+    nextAction?: string;
+}
+export interface IntentInitResult {
+    ok: boolean;
+    created: boolean;
+    path?: string;
+    reason?: string;
+    nextAction?: string;
+}
+export interface IntentSaveResult {
+    ok: boolean;
+    saved: boolean;
+    path?: string;
+    contentHash?: string;
+    lastEditedAt?: string;
+    warnings?: IntentDocWarning[];
+    reason?: string;
+    nextAction?: string;
+}
+export interface IntentRawContentResult {
+    ok: boolean;
+    content?: string;
+    path?: string;
+    reason?: string;
+    nextAction?: string;
+}
+export interface IntentVersionResult {
+    ok: boolean;
+    versions?: IntentDocVersion[];
+    reason?: string;
+    nextAction?: string;
+}
+export declare class IntentPageModel {
+    private readonly workspaceDir;
+    constructor(workspaceDir: string);
+    getSummary(flagEnabled: boolean, lang: IntentLang): Promise<IntentPageResult>;
+    getRawContent(flagEnabled: boolean, lang: IntentLang): Promise<IntentRawContentResult>;
+    createTemplate(flagEnabled: boolean, force: boolean, lang: IntentLang): Promise<IntentInitResult>;
+    saveContent(flagEnabled: boolean, content: unknown, lang: IntentLang): Promise<IntentSaveResult>;
+    getVersions(lang: IntentLang): Promise<IntentVersionResult>;
+}

package/console/dist/server/models/IntentPageModel.js

@@ -0,0 +1,292 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { INTENT_MAX_BYTES, getIntentFilename, createIntentTemplate, parseIntentDocSections, computeIntentContentHash, validateIntentDocSections, SqliteConnection, SqliteIntentDocVersionStore, } from '@principles/core/runtime-v2';
+const INTENT_DIR = '.principles';
+function stateDbExists(workspaceDir) {
+    return fs.existsSync(path.join(workspaceDir, '.pd', 'state.db'));
+}
+/** Best-effort version record — never blocks save on failure. */
+function recordVersion(args) {
+    // Note: no stateDbExists short-circuit. SqliteConnection creates the .pd
+    // dir and state.db file (with intent_doc_versions table via CREATE TABLE
+    // IF NOT EXISTS) on first open. Short-circuiting here would silently drop
+    // the first-write version history on fresh workspaces — the operator
+    // would see an empty history panel after their very first save.
+    try {
+        const connection = new SqliteConnection({ workspaceDir: args.workspaceDir });
+        try {
+            const store = new SqliteIntentDocVersionStore(connection);
+            store.saveVersion({ lang: args.lang, content: args.content, reason: args.reason });
+        }
+        finally {
+            try {
+                connection.close();
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    catch {
+        // Version recording is best-effort — never block save on failure.
+    }
+}
+export class IntentPageModel {
+    workspaceDir;
+    constructor(workspaceDir) {
+        this.workspaceDir = workspaceDir;
+    }
+    async getSummary(flagEnabled, lang) {
+        if (!flagEnabled) {
+            return {
+                ok: false,
+                found: false,
+                flagEnabled: false,
+                warnings: [],
+                reason: 'flag_disabled',
+                nextAction: `Enable the intent_engineering feature flag in .pd/config.yaml to read ${getIntentFilename(lang)}.`,
+            };
+        }
+        const filePath = path.join(this.workspaceDir, INTENT_DIR, getIntentFilename(lang));
+        try {
+            if (!fs.existsSync(filePath)) {
+                return {
+                    ok: false,
+                    found: false,
+                    flagEnabled: true,
+                    warnings: [],
+                    reason: 'not_found',
+                    nextAction: `Create .principles/${getIntentFilename(lang)} using "pd intent init".`,
+                };
+            }
+            const stat = fs.statSync(filePath);
+            if (stat.size > INTENT_MAX_BYTES) {
+                return {
+                    ok: false,
+                    found: true,
+                    flagEnabled: true,
+                    warnings: [],
+                    reason: 'oversized',
+                    nextAction: `${getIntentFilename(lang)} exceeds ${INTENT_MAX_BYTES} bytes (${stat.size} bytes). Reduce content.`,
+                };
+            }
+            const raw = fs.readFileSync(filePath, 'utf8');
+            const sections = parseIntentDocSections(raw);
+            const warnings = validateIntentDocSections(sections);
+            const contentHash = computeIntentContentHash(raw);
+            const sectionRecord = {};
+            if (sections.why !== undefined) {
+                sectionRecord.why = sections.why;
+            }
+            if (sections.desiredOutcome !== undefined) {
+                sectionRecord.desiredOutcome = sections.desiredOutcome;
+            }
+            if (sections.nonNegotiables !== undefined) {
+                sectionRecord.nonNegotiables = sections.nonNegotiables;
+            }
+            if (sections.stopEscalation !== undefined) {
+                sectionRecord.stopEscalation = sections.stopEscalation;
+            }
+            if (sections.currentStrategicFocus !== undefined) {
+                sectionRecord.currentStrategicFocus = sections.currentStrategicFocus;
+            }
+            return {
+                ok: true,
+                found: true,
+                flagEnabled: true,
+                warnings,
+                path: filePath,
+                contentHash,
+                lastEditedAt: stat.mtime.toISOString(),
+                sections: sectionRecord,
+            };
+        }
+        catch (err) {
+            console.error(`[IntentPageModel] failed to read ${getIntentFilename(lang)}:`, err);
+            return {
+                ok: false,
+                found: false,
+                flagEnabled: true,
+                warnings: [],
+                reason: 'read_error',
+                nextAction: `Check filesystem permissions for .principles/${getIntentFilename(lang)}.`,
+            };
+        }
+    }
+    async getRawContent(flagEnabled, lang) {
+        if (!flagEnabled) {
+            return {
+                ok: false,
+                reason: 'flag_disabled',
+                nextAction: 'Enable the intent_engineering feature flag first.',
+            };
+        }
+        const filePath = path.join(this.workspaceDir, INTENT_DIR, getIntentFilename(lang));
+        try {
+            if (!fs.existsSync(filePath)) {
+                return {
+                    ok: false,
+                    reason: 'not_found',
+                    nextAction: `${getIntentFilename(lang)} does not exist. Create it first using POST /api/v1/intent/init.`,
+                };
+            }
+            const stat = fs.statSync(filePath);
+            if (stat.size > INTENT_MAX_BYTES) {
+                return {
+                    ok: false,
+                    reason: 'oversized',
+                    nextAction: `${getIntentFilename(lang)} exceeds ${INTENT_MAX_BYTES} bytes (${stat.size} bytes). Reduce content before opening the editor.`,
+                };
+            }
+            const content = fs.readFileSync(filePath, 'utf8');
+            return { ok: true, content, path: filePath };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[IntentPageModel] failed to read raw ${getIntentFilename(lang)}:`, err);
+            return {
+                ok: false,
+                reason: 'read_error',
+                nextAction: `Could not read ${getIntentFilename(lang)}: ${message}. Check filesystem permissions.`,
+            };
+        }
+    }
+    async createTemplate(flagEnabled, force, lang) {
+        if (!flagEnabled) {
+            return {
+                ok: false,
+                created: false,
+                reason: 'flag_disabled',
+                nextAction: 'Enable the intent_engineering feature flag first.',
+            };
+        }
+        const dirPath = path.join(this.workspaceDir, INTENT_DIR);
+        const filePath = path.join(dirPath, getIntentFilename(lang));
+        try {
+            if (!fs.existsSync(dirPath)) {
+                fs.mkdirSync(dirPath, { recursive: true });
+            }
+            if (fs.existsSync(filePath) && !force) {
+                return {
+                    ok: true,
+                    created: false,
+                    path: filePath,
+                    reason: 'already_exists',
+                    nextAction: 'Use force=true to overwrite, or edit the existing file instead.',
+                };
+            }
+            const templateContent = createIntentTemplate(lang);
+            fs.writeFileSync(filePath, templateContent, 'utf8');
+            recordVersion({ workspaceDir: this.workspaceDir, lang, content: templateContent, reason: 'init' });
+            return {
+                ok: true,
+                created: true,
+                path: filePath,
+            };
+        }
+        catch (err) {
+            console.error(`[IntentPageModel] failed to create ${getIntentFilename(lang)}:`, err);
+            return {
+                ok: false,
+                created: false,
+                reason: 'write_error',
+                nextAction: 'Check filesystem permissions for .principles/ directory.',
+            };
+        }
+    }
+    async saveContent(flagEnabled, content, lang) {
+        if (!flagEnabled) {
+            return {
+                ok: false,
+                saved: false,
+                reason: 'flag_disabled',
+                nextAction: 'Enable the intent_engineering feature flag first.',
+            };
+        }
+        if (typeof content !== 'string') {
+            return {
+                ok: false,
+                saved: false,
+                reason: 'invalid_content',
+                nextAction: 'Content must be a string.',
+            };
+        }
+        if (content.length === 0) {
+            return {
+                ok: false,
+                saved: false,
+                reason: 'empty_content',
+                nextAction: 'Content cannot be empty.',
+            };
+        }
+        const byteLength = Buffer.byteLength(content, 'utf8');
+        if (byteLength > INTENT_MAX_BYTES) {
+            return {
+                ok: false,
+                saved: false,
+                reason: 'oversized',
+                nextAction: `Content exceeds ${INTENT_MAX_BYTES} bytes (${byteLength} bytes). Reduce content.`,
+            };
+        }
+        const dirPath = path.join(this.workspaceDir, INTENT_DIR);
+        const filePath = path.join(dirPath, getIntentFilename(lang));
+        try {
+            if (!fs.existsSync(dirPath)) {
+                fs.mkdirSync(dirPath, { recursive: true });
+            }
+            fs.writeFileSync(filePath, content, 'utf8');
+            const sections = parseIntentDocSections(content);
+            const warnings = validateIntentDocSections(sections);
+            const contentHash = computeIntentContentHash(content);
+            const stat = fs.statSync(filePath);
+            recordVersion({ workspaceDir: this.workspaceDir, lang, content, reason: 'save' });
+            return {
+                ok: true,
+                saved: true,
+                path: filePath,
+                contentHash,
+                lastEditedAt: stat.mtime.toISOString(),
+                warnings,
+            };
+        }
+        catch (err) {
+            console.error(`[IntentPageModel] failed to save ${getIntentFilename(lang)}:`, err);
+            return {
+                ok: false,
+                saved: false,
+                reason: 'write_error',
+                nextAction: `Check filesystem permissions for .principles/${getIntentFilename(lang)}.`,
+            };
+        }
+    }
+    async getVersions(lang) {
+        if (!stateDbExists(this.workspaceDir)) {
+            return {
+                ok: false,
+                reason: 'state_db_not_found',
+                nextAction: 'Run a PD command that creates state.db first (e.g. pd pain list).',
+            };
+        }
+        try {
+            const connection = new SqliteConnection({ workspaceDir: this.workspaceDir, readonly: true });
+            try {
+                const store = new SqliteIntentDocVersionStore(connection);
+                const versions = await store.listVersions(lang);
+                return { ok: true, versions };
+            }
+            finally {
+                try {
+                    connection.close();
+                }
+                catch { /* best-effort */ }
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[IntentPageModel] failed to list versions:`, err);
+            return {
+                ok: false,
+                reason: 'read_error',
+                nextAction: `Could not read version history: ${message}`,
+            };
+        }
+    }
+}

package/console/dist/server/models/PrinciplesConsoleModel.d.ts

@@ -77,4 +77,6 @@ export declare class PrinciplesConsoleModel {
     private loadLedger;
     listPrinciples(filter?: PrincipleFilter, decidedPrincipleIds?: Set<string>): Promise<PrinciplesListOutput>;
     getPrincipleDetail(principleId: string): Promise<PrincipleDetailOutput | null>;
+    archivePrinciple(principleId: string): Promise<boolean>;
+    unarchivePrinciple(principleId: string): Promise<boolean>;
 }

package/console/dist/server/models/PrinciplesConsoleModel.js

@@ -1,6 +1,7 @@
 import * as path from 'path';
 import * as fs from 'fs';
 import { classifyPrinciples, filterOwnerActionable } from './PrincipleClassifier.js';
+import { updatePrinciple } from '@principles/core/principle-tree-ledger';
 const VALID_STATUSES = ['candidate', 'active', 'archived', 'deprecated', 'probation'];
 const VALID_PRIORITIES = ['P0', 'P1', 'P2'];
 const VALID_SCOPES = ['general', 'domain'];
@@ -92,7 +93,8 @@ function readLedgerFromFile(filePath) {
             tree: parseTree(treeRaw),
         };
     }
-    catch {
+    catch (e) {
+        console.warn('PrinciplesConsoleModel: failed to parse principle_training_state.json, returning empty tree:', e);
         return { trainingStore: {}, tree: createEmptyTree() };
     }
 }
@@ -244,4 +246,38 @@ export class PrinciplesConsoleModel {
         };
         return { principle };
     }
+    async archivePrinciple(principleId) {
+        try {
+            const stateDir = path.join(this.workspaceDir, '.state');
+            updatePrinciple(stateDir, principleId, {
+                status: 'archived',
+                updatedAt: new Date().toISOString(),
+            });
+            // Clear cache to force reload
+            this.cachedLedger = null;
+            this.cacheTimestamp = 0;
+            return true;
+        }
+        catch (e) {
+            console.error(`Failed to archive principle ${principleId}:`, e);
+            return false;
+        }
+    }
+    async unarchivePrinciple(principleId) {
+        try {
+            const stateDir = path.join(this.workspaceDir, '.state');
+            updatePrinciple(stateDir, principleId, {
+                status: 'active',
+                updatedAt: new Date().toISOString(),
+            });
+            // Clear cache to force reload
+            this.cachedLedger = null;
+            this.cacheTimestamp = 0;
+            return true;
+        }
+        catch (e) {
+            console.error(`Failed to unarchive principle ${principleId}:`, e);
+            return false;
+        }
+    }
 }

package/console/dist/server/models/WorkspaceService.d.ts

@@ -1,35 +1,7 @@
 import type { WorkspaceConfigStore } from '../config/WorkspaceConfigStore.js';
 import type { SyncResult } from '../types/index.js';
-export interface CentralOverviewOutput {
-    generatedAt: string;
-    workspaceCount: number;
-    workspaces: {
-        name: string;
-        path: string;
-        status: 'healthy' | 'degraded' | 'error';
-        gfi: number;
-        principleCount: number;
-    }[];
-}
-export interface CentralHealthOutput {
-    generatedAt: string;
-    overallStatus: 'healthy' | 'degraded' | 'error';
-    workspaces: {
-        name: string;
-        status: 'healthy' | 'degraded' | 'error';
-        gfi: number;
-        activePrinciples: number;
-        pendingTasks: number;
-    }[];
-}
 export declare class WorkspaceService {
     private readonly configStore;
-    private readonly models;
     constructor(configStore: WorkspaceConfigStore);
-    getCentralOverview(): Promise<CentralOverviewOutput>;
-    getCentralHealth(): Promise<CentralHealthOutput>;
     syncWorkspace(name: string): Promise<SyncResult>;
-    dispose(): void;
-    private disposeWorkspace;
-    private getModels;
 }