@protoyard/blueprint 0.0.0-stage → 1.1.1

package/dist/app-model.js

@@ -0,0 +1,287 @@
+import { screenPath, } from "./schema.js";
+/**
+ * The app model (ADR-029): a blueprint's routes, navigation, navigation
+ * groups and layout as plain data. `protoyard generate` prints it into
+ * `src/generated/routes.ts` and `layout.ts`; the player renders it directly.
+ * Framework-free: icons are `SCREEN_NAV_ICONS` ids, and each renderer maps
+ * them to its own components.
+ */
+/** Screen kinds that render through their own view component instead of the entity page. */
+const VIEW_COMPONENT_KINDS = [
+    'board',
+    'calendar',
+    'map',
+    'analytics',
+    'timeline',
+    'dashboard',
+    'settings',
+    'sheet',
+    'canvas',
+];
+/** Kinds listed under the "Views" navigation group. */
+const VIEW_GROUP_KINDS = [
+    'board',
+    'calendar',
+    'timeline',
+    'map',
+    'analytics',
+    'dashboard',
+    'sheet',
+    'canvas',
+];
+const DEFAULT_ICONS = {
+    dashboard: 'layout-dashboard',
+    settings: 'settings',
+    board: 'kanban',
+    calendar: 'calendar-days',
+    timeline: 'chart-gantt',
+    map: 'map',
+    analytics: 'chart-line',
+    sheet: 'table',
+    canvas: 'layout-dashboard',
+};
+/** `support-tickets` → `Support tickets`, unless the entity sets `label`. */
+export function entityLabel(entity) {
+    if (entity.label)
+        return entity.label;
+    const words = entity.plural.replace(/-/g, ' ');
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+/** `support-ticket` → `SupportTicket` (names are lowercase kebab-case). */
+function pascal(name) {
+    return name
+        .split('-')
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+}
+const capitalize = (text) => `${text.charAt(0).toUpperCase()}${text.slice(1)}`;
+/** The icon a screen shows in navigation: its `nav.icon`, or the default for its kind. */
+export function screenNavIcon(screen) {
+    return screen.nav?.icon ?? DEFAULT_ICONS[screen.type] ?? 'database';
+}
+function screenTitle(screen, blueprint) {
+    if (screen.nav?.label)
+        return screen.nav.label;
+    if (screen.title)
+        return screen.title;
+    if ('entity' in screen) {
+        const entity = blueprint.entities.find((candidate) => candidate.name === screen.entity);
+        if (entity)
+            return `${entityLabel(entity)} ${screen.type === 'list' ? '' : screen.type}`.trim();
+    }
+    return capitalize(screen.type);
+}
+function screenComponent(screen, index, previous) {
+    const entity = 'entity' in screen ? screen.entity : undefined;
+    const base = screen.type === 'dashboard'
+        ? `Dashboard${index + 1}Screen`
+        : screen.type === 'settings'
+            ? 'SettingsScreen'
+            : `${pascal(screen.type)}${entity ? pascal(entity) : index + 1}Screen`;
+    let name = base;
+    for (let suffix = 2; previous.has(name); suffix += 1)
+        name = base.replace(/Screen$/, `${suffix}Screen`);
+    previous.add(name);
+    return name;
+}
+/** True when a screen renders through its own component rather than the entity page. */
+export function screenHasOwnView(screen) {
+    if (screen.type === 'detail')
+        return Boolean(screen.tabs?.length);
+    return VIEW_COMPONENT_KINDS.includes(screen.type);
+}
+function screenEntries(blueprint) {
+    const names = new Set();
+    return blueprint.screens.flatMap((screen, index) => {
+        const path = screenPath(screen, blueprint.entities);
+        if (!path)
+            return [];
+        const entityName = 'entity' in screen ? screen.entity : undefined;
+        const entity = entityName
+            ? blueprint.entities.find((item) => item.name === entityName)
+            : undefined;
+        return [
+            {
+                screen,
+                index,
+                path,
+                component: screenComponent(screen, index, names),
+                ownView: screenHasOwnView(screen),
+                label: screenTitle(screen, blueprint),
+                description: `${capitalize(screen.type)} screen${entity ? ` for ${entityLabel(entity)}` : ''}`,
+                ...(entityName ? { entity: entityName } : {}),
+            },
+        ];
+    });
+}
+function hasDefaultListRoute(blueprint, entity) {
+    if (!entity.screenDefaults)
+        return true;
+    const explicit = blueprint.screens.find((screen) => 'entity' in screen && screen.entity === entity.name && screen.type === 'list');
+    if (explicit)
+        return screenPath(explicit, blueprint.entities) === `/${entity.plural}`;
+    return entity.screenDefaults.views.includes('list');
+}
+function hasDefaultDetailRoute(blueprint, entity) {
+    if (!entity.screenDefaults)
+        return true;
+    const explicit = blueprint.screens.find((screen) => 'entity' in screen && screen.entity === entity.name && screen.type === 'detail');
+    if (explicit)
+        return screenPath(explicit, blueprint.entities) === `/${entity.plural}/:id`;
+    return entity.screenDefaults.views.includes('detail');
+}
+/** The route fields an entry renders with: its own view, or the entity page it belongs to. */
+function entryTarget(entry) {
+    if (entry.ownView) {
+        return {
+            view: 'screen',
+            screenIndex: entry.index,
+            screenType: entry.screen.type,
+            component: entry.component,
+            ...(entry.entity ? { entity: entry.entity } : {}),
+        };
+    }
+    return {
+        view: 'entity',
+        entity: entry.entity ?? '',
+        screenIndex: entry.index,
+        screenType: entry.screen.type,
+    };
+}
+function deriveRoutes(blueprint, entries) {
+    const rootDashboard = entries.find((entry) => entry.screen.type === 'dashboard' && entry.path === '/');
+    // Keyed by path: a later route on the same path replaces the earlier one in place.
+    const routes = new Map();
+    routes.set('/', rootDashboard
+        ? {
+            name: 'home',
+            description: rootDashboard.description,
+            path: '/',
+            title: rootDashboard.screen.title ?? rootDashboard.label,
+            ...entryTarget(rootDashboard),
+        }
+        : {
+            name: 'home',
+            description: 'Overview with a count per entity',
+            path: '/',
+            title: 'Home',
+            view: 'home',
+        });
+    for (const entity of blueprint.entities) {
+        const label = entityLabel(entity);
+        const page = { view: 'entity', entity: entity.name };
+        const detail = entries.find((entry) => entry.screen.type === 'detail' &&
+            entry.entity === entity.name &&
+            Boolean(entry.screen.tabs?.length));
+        const list = entries.find((entry) => entry.screen.type === 'list' && entry.entity === entity.name);
+        const listPath = `/${entity.plural}`;
+        const detailPath = `/${entity.plural}/:id`;
+        if (hasDefaultListRoute(blueprint, entity)) {
+            routes.set(listPath, {
+                name: `${entity.name}-list`,
+                description: `${label}: list, create, edit and delete`,
+                path: listPath,
+                title: label,
+                ...(list?.path === listPath ? entryTarget(list) : page),
+            });
+        }
+        if (hasDefaultDetailRoute(blueprint, entity)) {
+            routes.set(detailPath, {
+                name: `${entity.name}-detail`,
+                description: detail
+                    ? `${label}: record detail with tabs`
+                    : `One ${entity.name.replace(/-/g, ' ')}: edit form`,
+                path: detailPath,
+                title: label,
+                ...(detail?.path === detailPath ? entryTarget(detail) : page),
+            });
+        }
+    }
+    for (const entry of entries) {
+        if (entry.path === '/' && entry.screen.type === 'dashboard')
+            continue;
+        routes.set(entry.path, {
+            name: `screen-${entry.component.replace(/Screen$/, '')}`,
+            description: entry.description,
+            path: entry.path,
+            title: entry.label,
+            ...entryTarget(entry),
+        });
+    }
+    routes.set('/members', {
+        name: 'members',
+        description: 'Workspace people and their simulated roles',
+        path: '/members',
+        title: 'Members',
+        view: 'members',
+    });
+    return [...routes.values()];
+}
+function deriveNav(blueprint, entries) {
+    const rootDashboard = entries.find((entry) => entry.screen.type === 'dashboard' && entry.path === '/');
+    const visible = entries.filter((entry) => entry.screen.nav?.hidden !== true);
+    const homeIcon = rootDashboard ? screenNavIcon(rootDashboard.screen) : 'layout-dashboard';
+    const icons = new Set(['database', 'users', homeIcon]);
+    for (const { screen } of visible)
+        icons.add(screenNavIcon(screen));
+    const entityNav = blueprint.entities.flatMap((entity) => {
+        if (entries.some((entry) => entry.screen.type === 'list' && entry.entity === entity.name)) {
+            return [];
+        }
+        if (entity.screenDefaults)
+            return [];
+        return [{ path: `/${entity.plural}`, label: entityLabel(entity), icon: 'database' }];
+    });
+    const screenNav = visible
+        .filter(({ screen, path }) => screen.type !== 'form' && screen.type !== 'detail' && path !== '/')
+        .sort((a, b) => (a.screen.nav?.order ?? Number.POSITIVE_INFINITY) -
+        (b.screen.nav?.order ?? Number.POSITIVE_INFINITY) || a.index - b.index)
+        .map(({ screen, path, label }) => ({ path, label, icon: screenNavIcon(screen) }));
+    const nav = [
+        { path: '/', label: rootDashboard?.label ?? 'Home', icon: homeIcon, exact: true },
+        ...entityNav,
+        ...screenNav,
+        { path: '/members', label: 'Members', icon: 'users' },
+    ];
+    return { nav, icons: [...icons] };
+}
+function deriveNavGroups(blueprint, entries) {
+    const visible = entries.filter((entry) => entry.screen.nav?.hidden !== true);
+    const recordPaths = blueprint.entities.flatMap((entity) => {
+        if (!hasDefaultListRoute(blueprint, entity))
+            return [];
+        const list = visible.find(({ screen, entity: name }) => screen.type === 'list' && name === entity.name);
+        return [list?.path ?? `/${entity.plural}`];
+    });
+    const viewPaths = visible
+        .filter(({ screen, path }) => path !== '/' && VIEW_GROUP_KINDS.includes(screen.type))
+        .map(({ path }) => path);
+    const settingsPaths = visible
+        .filter(({ screen }) => screen.type === 'settings')
+        .map(({ path }) => path);
+    return [
+        { label: 'Overview', paths: ['/'] },
+        { label: 'Records', paths: recordPaths },
+        { label: 'Views', paths: viewPaths },
+        { label: 'Workspace', paths: ['/members', ...settingsPaths] },
+    ].filter((group) => group.paths.length > 0);
+}
+/**
+ * Derives the app model from a parsed blueprint. Pure and deterministic: the
+ * same blueprint always yields the same model, which matches what
+ * `protoyard generate` writes to `routes.ts` and `layout.ts`.
+ */
+export function deriveAppModel(blueprint) {
+    const entries = screenEntries(blueprint);
+    const { nav, icons } = deriveNav(blueprint, entries);
+    return {
+        routes: deriveRoutes(blueprint, entries),
+        nav,
+        navGroups: deriveNavGroups(blueprint, entries),
+        layout: {
+            id: blueprint.layout?.id ?? 'sidebar',
+            ...(blueprint.layout?.mobile ? { mobile: blueprint.layout.mobile } : {}),
+        },
+        icons,
+    };
+}

package/dist/archetypes/index.d.ts

@@ -0,0 +1 @@
+export { ARCHETYPE_IDS, ARCHETYPE_KIT_ENTRY_POINTS, type ArchetypeKitEntryPoint, ArchetypeSchema, type BlueprintArchetype, type BlueprintArchetypeInput, } from './schema.ts';

package/dist/archetypes/index.js

@@ -0,0 +1 @@
+export { ARCHETYPE_IDS, ARCHETYPE_KIT_ENTRY_POINTS, ArchetypeSchema, } from "./schema.js";

package/dist/archetypes/schema.d.ts

@@ -0,0 +1,126 @@
+import { z } from 'zod';
+/** Kit entry points understood by the player. This list is data; it never imports a kit. */
+export declare const ARCHETYPE_KIT_ENTRY_POINTS: readonly ["@protoyard/ai", "@protoyard/ai-ui", "@protoyard/saas", "@protoyard/saas-ui", "@protoyard/analytics", "@protoyard/analytics-ui/grid", "@protoyard/analytics-ui/date-range"];
+export type ArchetypeKitEntryPoint = (typeof ARCHETYPE_KIT_ENTRY_POINTS)[number];
+export declare const ARCHETYPE_IDS: readonly ["assistant", "team-chat", "saas-onboarding", "analytics"];
+/**
+ * Portable runtime configuration for one of the player's kit-backed product
+ * archetypes. Package identifiers are an allow-list, never module specifiers
+ * resolved from arbitrary blueprint text.
+ */
+export declare const ArchetypeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodLiteral<"assistant">;
+    kits: z.ZodTuple<[z.ZodLiteral<"@protoyard/ai">, z.ZodLiteral<"@protoyard/ai-ui">], null>;
+    entities: z.ZodObject<{
+        conversations: z.ZodString;
+        messages: z.ZodString;
+    }, z.core.$strict>;
+    screens: z.ZodTuple<[z.ZodObject<{
+        kind: z.ZodLiteral<"assistant-workspace">;
+        path: z.ZodString;
+    }, z.core.$strict>], null>;
+    scenarioDefaults: z.ZodDefault<z.ZodObject<{
+        density: z.ZodDefault<z.ZodEnum<{
+            empty: "empty";
+            sparse: "sparse";
+            normal: "normal";
+            dense: "dense";
+            massive: "massive";
+        }>>;
+        activity: z.ZodDefault<z.ZodEnum<{
+            none: "none";
+            normal: "normal";
+            low: "low";
+            intense: "intense";
+            dormant: "dormant";
+            reactivated: "reactivated";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodLiteral<"team-chat">;
+    kits: z.ZodTuple<[z.ZodLiteral<"@protoyard/ai">, z.ZodLiteral<"@protoyard/ai-ui">], null>;
+    entities: z.ZodObject<{
+        rooms: z.ZodString;
+        messages: z.ZodString;
+        members: z.ZodString;
+    }, z.core.$strict>;
+    screens: z.ZodTuple<[z.ZodObject<{
+        kind: z.ZodLiteral<"team-chat">;
+        path: z.ZodString;
+    }, z.core.$strict>], null>;
+    scenarioDefaults: z.ZodDefault<z.ZodObject<{
+        density: z.ZodDefault<z.ZodEnum<{
+            empty: "empty";
+            sparse: "sparse";
+            normal: "normal";
+            dense: "dense";
+            massive: "massive";
+        }>>;
+        activity: z.ZodDefault<z.ZodEnum<{
+            none: "none";
+            normal: "normal";
+            low: "low";
+            intense: "intense";
+            dormant: "dormant";
+            reactivated: "reactivated";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodLiteral<"saas-onboarding">;
+    kits: z.ZodTuple<[z.ZodLiteral<"@protoyard/saas">, z.ZodLiteral<"@protoyard/saas-ui">], null>;
+    entities: z.ZodObject<{
+        workspaces: z.ZodString;
+        members: z.ZodString;
+    }, z.core.$strict>;
+    screens: z.ZodTuple<[z.ZodObject<{
+        kind: z.ZodLiteral<"saas-onboarding">;
+        path: z.ZodString;
+    }, z.core.$strict>], null>;
+    scenarioDefaults: z.ZodDefault<z.ZodObject<{
+        density: z.ZodDefault<z.ZodEnum<{
+            empty: "empty";
+            sparse: "sparse";
+            normal: "normal";
+            dense: "dense";
+            massive: "massive";
+        }>>;
+        activity: z.ZodDefault<z.ZodEnum<{
+            none: "none";
+            normal: "normal";
+            low: "low";
+            intense: "intense";
+            dormant: "dormant";
+            reactivated: "reactivated";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodLiteral<"analytics">;
+    kits: z.ZodTuple<[z.ZodLiteral<"@protoyard/analytics">, z.ZodLiteral<"@protoyard/analytics-ui/grid">, z.ZodLiteral<"@protoyard/analytics-ui/date-range">], null>;
+    entities: z.ZodObject<{
+        events: z.ZodString;
+        metrics: z.ZodString;
+    }, z.core.$strict>;
+    screens: z.ZodTuple<[z.ZodObject<{
+        kind: z.ZodLiteral<"analytics-dashboard">;
+        path: z.ZodString;
+    }, z.core.$strict>], null>;
+    scenarioDefaults: z.ZodDefault<z.ZodObject<{
+        density: z.ZodDefault<z.ZodEnum<{
+            empty: "empty";
+            sparse: "sparse";
+            normal: "normal";
+            dense: "dense";
+            massive: "massive";
+        }>>;
+        activity: z.ZodDefault<z.ZodEnum<{
+            none: "none";
+            normal: "normal";
+            low: "low";
+            intense: "intense";
+            dormant: "dormant";
+            reactivated: "reactivated";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>], "id">;
+export type BlueprintArchetype = z.infer<typeof ArchetypeSchema>;
+export type BlueprintArchetypeInput = z.input<typeof ArchetypeSchema>;

package/dist/archetypes/schema.js

@@ -0,0 +1,77 @@
+import { ActivityLevelSchema, DataDensitySchema } from '@protoyard/core';
+import { z } from 'zod';
+/** Kit entry points understood by the player. This list is data; it never imports a kit. */
+export const ARCHETYPE_KIT_ENTRY_POINTS = [
+    '@protoyard/ai',
+    '@protoyard/ai-ui',
+    '@protoyard/saas',
+    '@protoyard/saas-ui',
+    '@protoyard/analytics',
+    '@protoyard/analytics-ui/grid',
+    '@protoyard/analytics-ui/date-range',
+];
+export const ARCHETYPE_IDS = ['assistant', 'team-chat', 'saas-onboarding', 'analytics'];
+const ArchetypeEntitySlotsSchema = z.strictObject({
+    conversations: z.string().regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/),
+    messages: z.string().regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/),
+});
+const TeamChatEntitySlotsSchema = z.strictObject({
+    rooms: z.string().regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/),
+    messages: z.string().regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/),
+    members: z.string().regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/),
+});
+const SaasEntitySlotsSchema = z.strictObject({
+    workspaces: z.string().regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/),
+    members: z.string().regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/),
+});
+const AnalyticsEntitySlotsSchema = z.strictObject({
+    events: z.string().regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/),
+    metrics: z.string().regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/),
+});
+const ScreenRouteSchema = z
+    .string()
+    .regex(/^\/[a-z0-9/:-]*$/, { message: 'screen path must be a hash route such as "/assistant"' });
+const ScenarioDefaultsSchema = z.strictObject({
+    density: DataDensitySchema.default('normal'),
+    activity: ActivityLevelSchema.default('normal'),
+});
+const screen = (kind) => z.strictObject({ kind: z.literal(kind), path: ScreenRouteSchema });
+/**
+ * Portable runtime configuration for one of the player's kit-backed product
+ * archetypes. Package identifiers are an allow-list, never module specifiers
+ * resolved from arbitrary blueprint text.
+ */
+export const ArchetypeSchema = z.discriminatedUnion('id', [
+    z.strictObject({
+        id: z.literal('assistant'),
+        kits: z.tuple([z.literal('@protoyard/ai'), z.literal('@protoyard/ai-ui')]),
+        entities: ArchetypeEntitySlotsSchema,
+        screens: z.tuple([screen('assistant-workspace')]),
+        scenarioDefaults: ScenarioDefaultsSchema.default({ density: 'normal', activity: 'normal' }),
+    }),
+    z.strictObject({
+        id: z.literal('team-chat'),
+        kits: z.tuple([z.literal('@protoyard/ai'), z.literal('@protoyard/ai-ui')]),
+        entities: TeamChatEntitySlotsSchema,
+        screens: z.tuple([screen('team-chat')]),
+        scenarioDefaults: ScenarioDefaultsSchema.default({ density: 'normal', activity: 'intense' }),
+    }),
+    z.strictObject({
+        id: z.literal('saas-onboarding'),
+        kits: z.tuple([z.literal('@protoyard/saas'), z.literal('@protoyard/saas-ui')]),
+        entities: SaasEntitySlotsSchema,
+        screens: z.tuple([screen('saas-onboarding')]),
+        scenarioDefaults: ScenarioDefaultsSchema.default({ density: 'normal', activity: 'normal' }),
+    }),
+    z.strictObject({
+        id: z.literal('analytics'),
+        kits: z.tuple([
+            z.literal('@protoyard/analytics'),
+            z.literal('@protoyard/analytics-ui/grid'),
+            z.literal('@protoyard/analytics-ui/date-range'),
+        ]),
+        entities: AnalyticsEntitySlotsSchema,
+        screens: z.tuple([screen('analytics-dashboard')]),
+        scenarioDefaults: ScenarioDefaultsSchema.default({ density: 'dense', activity: 'normal' }),
+    }),
+]);

package/dist/audit.d.ts

@@ -0,0 +1,52 @@
+import { type PrototypeRuntime, type Row } from '@protoyard/core';
+import type { Blueprint, BlueprintEntity } from './schema.ts';
+/** Placeholder stored instead of a sensitive field's real value. */
+export declare const AUDIT_REDACTED = "[redacted]";
+export type AuditAction = 'create' | 'update' | 'delete' | 'restore' | 'purge' | 'import';
+export interface AuditChange {
+    before: unknown;
+    after: unknown;
+}
+export interface AuditEntry extends Row {
+    id: string;
+    entity: string;
+    recordId: string;
+    actorId: string;
+    action: AuditAction;
+    at: string;
+    /**
+     * Monotonic per writer instance so entries that share the same simulated
+     * `at` still sort newest-first.
+     */
+    seq: number;
+    /** Only fields that changed; sensitive values are `AUDIT_REDACTED`. */
+    changes: Record<string, AuditChange>;
+}
+/**
+ * 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 declare function auditDiff(entity: BlueprintEntity, before: Row | null | undefined, after: Row | null | undefined): Record<string, AuditChange>;
+export interface AuditEvent {
+    readonly action: AuditAction;
+    readonly entity: BlueprintEntity;
+    readonly recordId: string;
+    readonly before?: Row | null;
+    readonly after?: Row | null;
+}
+/**
+ * Writes audit rows into the caller's open mutation transaction.
+ * No-op when the entity does not enable `features.audit`.
+ */
+export declare function createAuditWriter(runtime: PrototypeRuntime, blueprint: Blueprint): (event: AuditEvent) => Promise<AuditEntry | null>;
+export interface BlueprintAuditService {
+    /** Newest-first history for one record. Requires `<entity>:read`. */
+    listForRecord(entityName: string, recordId: string): Promise<AuditEntry[]>;
+    /** Newest-first entries across every audited entity (capped). Requires any audited entity read. */
+    listRecent(limit?: number): Promise<AuditEntry[]>;
+}
+/** Read API for the shared `auditEntries` table. */
+export declare function createAuditService(runtime: PrototypeRuntime, blueprint: Blueprint): BlueprintAuditService;
+/** True when at least one entity opts into audit logging. */
+export declare function blueprintUsesAudit(blueprint: Blueprint): boolean;