@protoyard/blueprint 0.0.0-stage → 1.1.0

package/dist/audit.js

@@ -0,0 +1,149 @@
+import { createRuntimeId } from '@protoyard/core';
+import { FEATURE_TABLES } from "./storage.js";
+import { inputProperty } from "./validation.js";
+/** Placeholder stored instead of a sensitive field's real value. */
+export const AUDIT_REDACTED = '[redacted]';
+const META = new Set(['id', 'createdAt', 'updatedAt', 'deletedAt', 'deletedBy']);
+function same(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (a === null || a === undefined || b === null || b === undefined)
+        return a === b;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((item, i) => same(item, b[i]));
+    }
+    if (typeof a === 'object' && typeof b === 'object') {
+        try {
+            return JSON.stringify(a) === JSON.stringify(b);
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+function redact(field, value) {
+    if (value === undefined)
+        return null;
+    if (field?.sensitive)
+        return AUDIT_REDACTED;
+    return value;
+}
+/**
+ * Field-level diff for an audit row. Only changed input properties are listed;
+ * `sensitive` fields store {@link AUDIT_REDACTED} instead of the real value.
+ * Platform meta columns (`id`, timestamps, soft-delete markers) are omitted.
+ */
+export function auditDiff(entity, before, after) {
+    const byProp = new Map(entity.fields.map((field) => [inputProperty(field), field]));
+    const keys = new Set([...byProp.keys()]);
+    if (before)
+        for (const key of Object.keys(before))
+            if (!META.has(key))
+                keys.add(key);
+    if (after)
+        for (const key of Object.keys(after))
+            if (!META.has(key))
+                keys.add(key);
+    const changes = {};
+    for (const key of [...keys].sort()) {
+        if (META.has(key))
+            continue;
+        const field = byProp.get(key);
+        const prev = before ? before[key] : undefined;
+        const next = after ? after[key] : undefined;
+        if (same(prev, next))
+            continue;
+        // Create: skip pure empties on the "before" side only when both empty.
+        if (before == null && (next === null || next === undefined))
+            continue;
+        changes[key] = {
+            before: before == null ? null : redact(field, prev),
+            after: after == null ? null : redact(field, next),
+        };
+    }
+    return changes;
+}
+/**
+ * Writes audit rows into the caller's open mutation transaction.
+ * No-op when the entity does not enable `features.audit`.
+ */
+export function createAuditWriter(runtime, blueprint) {
+    const db = runtime.db;
+    const enabled = new Set(blueprint.entities.filter((entity) => entity.features.audit).map((entity) => entity.name));
+    let seq = 0;
+    return async (event) => {
+        if (!enabled.has(event.entity.name))
+            return null;
+        const actorId = runtime.session.principal()?.persona.id;
+        if (!actorId)
+            throw new Error('No active persona. Load a scenario first.');
+        const changes = auditDiff(event.entity, event.before, event.after);
+        // Always record the action even when the diff is empty (e.g. no-op update
+        // is rare; delete/create still carry structural meaning).
+        const entry = {
+            id: createRuntimeId('audit'),
+            entity: event.entity.name,
+            recordId: event.recordId,
+            actorId,
+            action: event.action,
+            at: runtime.clock.now().toISOString(),
+            seq: ++seq,
+            changes,
+        };
+        await db.table(FEATURE_TABLES.audit).put(entry);
+        return entry;
+    };
+}
+/** Read API for the shared `auditEntries` table. */
+export function createAuditService(runtime, blueprint) {
+    const db = runtime.db;
+    const byName = new Map(blueprint.entities.map((entity) => [entity.name, entity]));
+    const audited = blueprint.entities.filter((entity) => entity.features.audit);
+    const assertCanRead = (entityName) => {
+        const entity = byName.get(entityName);
+        if (!entity?.features.audit) {
+            throw new Error(`Entity "${entityName}" does not enable audit logging.`);
+        }
+        runtime.session.assert(`${entity.name}:read`);
+    };
+    const sortNewest = (rows) => rows.sort((a, b) => {
+        if (a.at !== b.at)
+            return a.at < b.at ? 1 : -1;
+        const seqA = typeof a.seq === 'number' ? a.seq : 0;
+        const seqB = typeof b.seq === 'number' ? b.seq : 0;
+        if (seqA !== seqB)
+            return seqB - seqA;
+        return a.id < b.id ? 1 : a.id > b.id ? -1 : 0;
+    });
+    return {
+        async listForRecord(entityName, recordId) {
+            assertCanRead(entityName);
+            const rows = (await db.table(FEATURE_TABLES.audit).toArray());
+            return sortNewest(rows.filter((row) => row.entity === entityName && row.recordId === recordId));
+        },
+        async listRecent(limit = 50) {
+            if (audited.length === 0)
+                return [];
+            // Any audited entity the actor can read unlocks the feed.
+            const allowed = new Set();
+            for (const entity of audited) {
+                if (runtime.session.can(`${entity.name}:read`))
+                    allowed.add(entity.name);
+            }
+            if (allowed.size === 0) {
+                const first = audited[0];
+                if (first)
+                    runtime.session.assert(`${first.name}:read`);
+            }
+            const rows = (await db.table(FEATURE_TABLES.audit).toArray());
+            return sortNewest(rows.filter((row) => allowed.has(row.entity))).slice(0, Math.max(0, limit));
+        },
+    };
+}
+/** True when at least one entity opts into audit logging. */
+export function blueprintUsesAudit(blueprint) {
+    return blueprint.entities.some((entity) => entity.features.audit);
+}

package/dist/authoring/deck-lint.d.ts

@@ -0,0 +1,32 @@
+export type DeckLintSeverity = 'error' | 'warning';
+/** Stable structural diagnostic returned by the deck authoring lint. */
+export type DeckLintDiagnostic = {
+    code: string;
+    severity: DeckLintSeverity;
+    path: (string | number)[];
+    jsonPath: string;
+    message: string;
+};
+/** Pure result suitable for CLI output and editor integrations. */
+export type DeckLintResult = {
+    valid: boolean;
+    diagnostics: DeckLintDiagnostic[];
+};
+/**
+ * Check the structure and navigation references in an untrusted deck body.
+ * This function is deterministic, does not mutate input, render content or
+ * access the network. Diagnostics use paths relative to the deck object.
+ */
+export declare function lintDeckStructure(input: unknown): DeckLintResult;
+/**
+ * Check accessible content and static readability guidance for an untrusted
+ * deck. Schema omissions are errors; word-count estimates and missing speaker
+ * notes are warnings. Rendered contrast, font size and fit still need visual QA.
+ */
+export declare function lintDeckContent(input: unknown): DeckLintResult;
+/**
+ * Inspect media references in raw deck JSON without fetching, parsing remote
+ * content, or invoking object accessors. HTTPS is syntax-checked only; runtime
+ * hosts apply their own media policy. Embedded-app data is walked recursively.
+ */
+export declare function lintDeckAssets(input: unknown): DeckLintResult;