@protoyard/blueprint 0.0.0-stage → 1.1.1

package/dist/brief/draft-bodies.js

@@ -0,0 +1,224 @@
+const PAGE_ROLES = new Set(['hero', 'body', 'footer', 'cta', 'features', 'pricing', 'faq']);
+/** Lowercase kebab id for document/section anchors (BlockIdSchema). */
+export function draftSlugId(value, fallback) {
+    const slug = value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 48);
+    if (slug && /^[a-z]/.test(slug))
+        return slug;
+    return fallback;
+}
+function mapPageRole(role) {
+    if (PAGE_ROLES.has(role))
+        return role;
+    return 'body';
+}
+/**
+ * Convert outline draft blocks into strict block objects the pages schema accepts.
+ * `defaultHref` is a resolved in-document fragment (`#section-id`) for CTA actions.
+ */
+export function outlineBlocksToSchema(blocks, defaultHref = '#section-hero') {
+    const out = [];
+    const safeDefault = defaultHref.startsWith('#') ? defaultHref : `#${defaultHref}`;
+    for (const block of blocks) {
+        switch (block.type) {
+            case 'heading':
+                out.push({
+                    type: 'heading',
+                    text: block.text.slice(0, 200),
+                    level: block.level ?? 2,
+                });
+                break;
+            case 'text':
+                out.push({ type: 'text', markdown: block.markdown.slice(0, 4_000) });
+                break;
+            case 'list':
+                out.push({
+                    type: 'list',
+                    style: block.style === 'check' ? 'check' : block.style === 'number' ? 'number' : undefined,
+                    items: block.items
+                        .slice(0, 12)
+                        .map((item) => ({ text: String(item).slice(0, 600) }))
+                        .filter((item) => item.text.length > 0),
+                });
+                break;
+            case 'cta': {
+                const raw = block.href && block.href.length > 0 ? block.href : safeDefault;
+                // Only keep in-page fragments; external http(s) is fine for schema fragment checks.
+                const href = raw.startsWith('#') || /^https?:\/\//i.test(raw) || raw.startsWith('mailto:')
+                    ? raw
+                    : safeDefault;
+                out.push({
+                    type: 'cta',
+                    actions: [
+                        {
+                            label: block.label.slice(0, 60),
+                            href: href.slice(0, 512),
+                        },
+                    ],
+                });
+                break;
+            }
+            case 'stat':
+                out.push({
+                    type: 'stat',
+                    items: block.items.slice(0, 6).map((item) => ({
+                        value: String(item.value).slice(0, 32),
+                        label: String(item.label).slice(0, 80),
+                    })),
+                });
+                break;
+            case 'quote':
+                out.push({
+                    type: 'quote',
+                    quote: block.quote.slice(0, 280),
+                    ...(block.cite ? { cite: block.cite.slice(0, 120) } : {}),
+                });
+                break;
+            case 'callout':
+                out.push({
+                    type: 'callout',
+                    body: block.body.slice(0, 1_000),
+                    ...(block.title ? { title: block.title.slice(0, 80) } : {}),
+                });
+                break;
+            case 'divider':
+                out.push({
+                    type: 'divider',
+                    ...(block.label ? { label: block.label.slice(0, 80) } : {}),
+                });
+                break;
+            default:
+                break;
+        }
+    }
+    return out.filter((block) => {
+        if (block.type === 'list') {
+            const items = block.items;
+            return Array.isArray(items) && items.length > 0;
+        }
+        if (block.type === 'stat') {
+            const items = block.items;
+            return Array.isArray(items) && items.length > 0;
+        }
+        if (block.type === 'cta') {
+            const actions = block.actions;
+            return Array.isArray(actions) && actions.length > 0;
+        }
+        return true;
+    });
+}
+/** Page body: id + title + sections of valid blocks (no draft-only keys). */
+export function pageBodyFromOutline(input) {
+    const used = new Set();
+    const sectionIds = input.sections.map((section, index) => {
+        let id = draftSlugId(section.id || section.title, `section-${index + 1}`);
+        if (used.has(id))
+            id = `${id}-${index + 1}`;
+        used.add(id);
+        return id;
+    });
+    const firstHref = `#${sectionIds[0] ?? 'section-1'}`;
+    const sections = input.sections.map((section, index) => {
+        const id = sectionIds[index] ?? `section-${index + 1}`;
+        const blocks = outlineBlocksToSchema(section.blocks, firstHref);
+        // Rewrite unknown in-page fragments to the first section so fragment lint passes.
+        for (const block of blocks) {
+            if (block.type !== 'cta' || !Array.isArray(block.actions))
+                continue;
+            for (const action of block.actions) {
+                if (typeof action.href === 'string' && action.href.startsWith('#')) {
+                    const target = action.href.slice(1);
+                    if (!used.has(target))
+                        action.href = firstHref;
+                }
+            }
+        }
+        const role = mapPageRole(section.role);
+        return {
+            id,
+            ...(section.title ? { title: section.title.slice(0, 120) } : {}),
+            ...(role ? { role } : {}),
+            blocks: blocks.length > 0 ? blocks : [{ type: 'text', markdown: section.body.slice(0, 600) }],
+        };
+    });
+    return {
+        id: draftSlugId(input.id, 'page-draft'),
+        title: input.title.slice(0, 120) || 'Page draft',
+        ...(input.description ? { description: input.description.slice(0, 500) } : {}),
+        sections,
+    };
+}
+/**
+ * Doc body: continuous block flow. Section titles become headings with stable ids
+ * so a TOC has entries and fragment targets stay unique.
+ */
+export function docBodyFromOutline(input) {
+    const blocks = [];
+    const used = new Set();
+    for (const section of input.sections) {
+        let headingId = draftSlugId(section.id || section.title, 'section');
+        if (used.has(headingId))
+            headingId = `${headingId}-${used.size + 1}`;
+        used.add(headingId);
+        const level = section.role === 'title' ? 1 : 2;
+        blocks.push({
+            type: 'heading',
+            id: headingId,
+            level,
+            text: section.title.slice(0, 200) || headingId,
+        });
+        for (const block of outlineBlocksToSchema(section.blocks, `#${headingId}`)) {
+            if (block.type === 'heading' &&
+                typeof block.text === 'string' &&
+                block.text === section.title &&
+                (block.level === 1 || block.level === 2)) {
+                continue;
+            }
+            if (block.type === 'cta' && Array.isArray(block.actions)) {
+                for (const action of block.actions) {
+                    if (typeof action.href === 'string' && action.href.startsWith('#')) {
+                        const target = action.href.slice(1);
+                        if (!used.has(target))
+                            action.href = `#${headingId}`;
+                    }
+                }
+            }
+            if (block.type === 'heading' && typeof block.id === 'string') {
+                let id = block.id;
+                if (used.has(id))
+                    id = `${id}-${used.size + 1}`;
+                used.add(id);
+                blocks.push({ ...block, id });
+            }
+            else {
+                blocks.push(block);
+            }
+        }
+    }
+    if (blocks.length === 0) {
+        blocks.push({ type: 'heading', id: 'title', level: 1, text: input.title.slice(0, 200) });
+        blocks.push({ type: 'text', markdown: 'Add the document body here.' });
+    }
+    const hasTocHeading = blocks.some((block) => block.type === 'heading' &&
+        typeof block.level === 'number' &&
+        block.level >= 2 &&
+        block.level <= 3);
+    if (!hasTocHeading) {
+        blocks.push({
+            type: 'heading',
+            id: 'summary',
+            level: 2,
+            text: 'Summary',
+        });
+    }
+    return {
+        id: draftSlugId(input.id, 'doc-draft'),
+        title: input.title.slice(0, 120) || 'Document draft',
+        ...(input.description ? { description: input.description.slice(0, 500) } : {}),
+        toc: { depth: 3, sticky: true },
+        blocks,
+    };
+}

package/dist/brief/fields.d.ts

@@ -0,0 +1,19 @@
+import type { FieldInput } from './archetypes.ts';
+/** A field for a phrase from a brief, or null when nothing usable remains. */
+export declare function fieldFromPhrase(phrase: string): {
+    field: FieldInput;
+    cue: string | null;
+} | null;
+/** Brief-wide cues that add a field to the focus entity when it lacks that kind. */
+export declare const GLOBAL_CUES: readonly {
+    kind: string;
+    cues: readonly string[];
+    field: FieldInput;
+}[];
+/**
+ * Entity names that describe people. They get an `avatar` field (a face from
+ * the avatar library), so generated lists and details show real-looking people.
+ */
+export declare const PEOPLE_ENTITIES: ReadonlySet<string>;
+/** The avatar field added to people-like entities: `avatar`, or `photo` when the name is taken. */
+export declare function avatarFieldFor(fieldNames: readonly string[]): FieldInput | null;

package/dist/brief/fields.js

@@ -0,0 +1,229 @@
+import { camel } from "./text.js";
+const enumField = (name, values) => ({ name, kind: 'enum', values, default: values[0], required: true });
+const ENUM_VALUES = {
+    status: ['new', 'active', 'done'],
+    state: ['new', 'active', 'done'],
+    stage: ['lead', 'qualified', 'won', 'lost'],
+    priority: ['low', 'normal', 'high', 'urgent'],
+    severity: ['low', 'medium', 'high', 'critical'],
+    level: ['beginner', 'intermediate', 'advanced'],
+    type: ['standard', 'premium', 'other'],
+    category: ['general', 'special', 'other'],
+    kind: ['standard', 'premium', 'other'],
+};
+const RULES = [
+    {
+        cues: ['location', 'address', 'place', 'coordinates', 'map', 'site', 'gps'],
+        build: (name) => ({ name, kind: 'geo' }),
+    },
+    {
+        cues: [
+            'owner',
+            'assignee',
+            'assigned',
+            'manager',
+            'responsible',
+            'agent',
+            'author',
+            'reviewer',
+        ],
+        build: (name) => ({ name, kind: 'persona' }),
+    },
+    {
+        cues: ['time', 'at', 'hour', 'timestamp'],
+        build: (name) => ({ name, kind: 'datetime', window: 'around' }),
+    },
+    {
+        cues: [
+            'date',
+            'day',
+            'deadline',
+            'due',
+            'when',
+            'start',
+            'end',
+            'birthday',
+            'expiry',
+            'expires',
+        ],
+        build: (name) => ({ name, kind: 'date', window: 'around' }),
+    },
+    {
+        cues: [
+            'price',
+            'amount',
+            'cost',
+            'total',
+            'budget',
+            'fee',
+            'revenue',
+            'salary',
+            'payment',
+            'balance',
+            'value',
+        ],
+        build: (name) => ({ name, kind: 'money', min: 0, max: 1_000_000 }),
+    },
+    {
+        cues: ['rating', 'score', 'percent', 'percentage', 'weight', 'distance', 'temperature'],
+        build: (name) => ({ name, kind: 'number', min: 0, max: 100 }),
+    },
+    {
+        cues: [
+            'count',
+            'quantity',
+            'qty',
+            'hours',
+            'size',
+            'capacity',
+            'stock',
+            'seats',
+            'guests',
+            'number',
+        ],
+        build: (name) => ({ name, kind: 'integer', min: 0, max: 500 }),
+    },
+    {
+        cues: Object.keys(ENUM_VALUES),
+        build: (name) => {
+            const cue = Object.keys(ENUM_VALUES).find((key) => name.toLowerCase().endsWith(key));
+            return enumField(name, ENUM_VALUES[cue ?? 'status']);
+        },
+    },
+    { cues: ['email'], build: (name) => ({ name, kind: 'email' }) },
+    { cues: ['phone', 'mobile'], build: (name) => ({ name, kind: 'phone' }) },
+    { cues: ['website', 'url', 'link'], build: (name) => ({ name, kind: 'url' }) },
+    { cues: ['tags', 'labels'], build: (name) => ({ name, kind: 'tags' }) },
+    {
+        cues: ['notes', 'description', 'body', 'details', 'summary', 'comments'],
+        build: (name) => ({ name, kind: 'longText', fake: 'lorem.paragraph' }),
+    },
+    {
+        cues: ['paid', 'active', 'archived', 'approved', 'verified', 'flagged'],
+        build: (name) => ({ name, kind: 'boolean' }),
+    },
+];
+/** Words dropped from field phrases ("the due date" → `dueDate`). */
+const FILLER = new Set([
+    'the',
+    'a',
+    'an',
+    'their',
+    'its',
+    'his',
+    'her',
+    'our',
+    'your',
+    'each',
+    'every',
+    'some',
+    'of',
+    'any',
+]);
+/** Names the platform manages; a brief asking for one gets a suffixed name instead. */
+const RESERVED = new Set(['id', 'createdAt', 'updatedAt', 'deletedAt', 'deletedBy']);
+/** A field for a phrase from a brief, or null when nothing usable remains. */
+export function fieldFromPhrase(phrase) {
+    const all = phrase.toLowerCase().match(/[a-z]+/g) ?? [];
+    // "a live map of delivery locations" describes a screen, not a field.
+    if (all.includes('of'))
+        return null;
+    const parts = all.filter((w) => !FILLER.has(w));
+    if (parts.length === 0 || parts.length > 3)
+        return null;
+    let name = camel(parts);
+    if (RESERVED.has(name))
+        name = `${name}Value`;
+    if (name.length > 40)
+        return null;
+    const rule = RULES.find((r) => r.cues.some((cue) => parts.includes(cue)));
+    const cue = rule ? (rule.cues.find((c) => parts.includes(c)) ?? null) : null;
+    return { field: rule ? rule.build(name) : { name, kind: 'text' }, cue };
+}
+/** Brief-wide cues that add a field to the focus entity when it lacks that kind. */
+export const GLOBAL_CUES = [
+    {
+        kind: 'geo',
+        cues: ['location', 'locations', 'address', 'addresses', 'map', 'maps', 'nearby', 'gps'],
+        field: { name: 'location', kind: 'geo' },
+    },
+    {
+        kind: 'money',
+        cues: [
+            'price',
+            'prices',
+            'pricing',
+            'revenue',
+            'cost',
+            'costs',
+            'budget',
+            'invoice',
+            'invoices',
+            'payment',
+            'payments',
+            'amount',
+        ],
+        field: {
+            name: 'amount',
+            kind: 'money',
+            min: 0,
+            max: 1_000_000,
+            trend: 'growth',
+        },
+    },
+    {
+        kind: 'date',
+        cues: ['deadline', 'deadlines', 'due', 'calendar', 'schedule', 'scheduled', 'dates'],
+        field: { name: 'dueOn', kind: 'date', window: 'around' },
+    },
+    {
+        kind: 'persona',
+        cues: ['assign', 'assigns', 'assigned', 'assignee', 'owner', 'owners', 'team'],
+        field: { name: 'owner', kind: 'persona' },
+    },
+];
+/**
+ * Entity names that describe people. They get an `avatar` field (a face from
+ * the avatar library), so generated lists and details show real-looking people.
+ */
+export const PEOPLE_ENTITIES = new Set([
+    'agent',
+    'athlete',
+    'attendee',
+    'author',
+    'candidate',
+    'client',
+    'coach',
+    'contact',
+    'courier',
+    'customer',
+    'doctor',
+    'driver',
+    'employee',
+    'follower',
+    'groomer',
+    'guest',
+    'instructor',
+    'lead',
+    'member',
+    'mentor',
+    'nurse',
+    'patient',
+    'player',
+    'resident',
+    'rider',
+    'student',
+    'subscriber',
+    'teacher',
+    'technician',
+    'tenant',
+    'trainer',
+    'tutor',
+    'volunteer',
+    'worker',
+]);
+/** The avatar field added to people-like entities: `avatar`, or `photo` when the name is taken. */
+export function avatarFieldFor(fieldNames) {
+    const name = ['avatar', 'photo', 'face'].find((candidate) => !fieldNames.includes(candidate));
+    return name ? { name, kind: 'avatar', label: 'Photo' } : null;
+}

package/dist/brief/index.d.ts

@@ -0,0 +1,8 @@
+export { ARCHETYPE_IDS, ARCHETYPES, type Archetype, GENERIC_ARCHETYPE } from './archetypes.ts';
+export { type ContentBriefOptions, type ContentBriefResult, MAX_CONTENT_BRIEF_LENGTH, synthesizeContentFromBrief, synthesizeDeckFromBrief, synthesizeDocFromBrief, synthesizePageFromBrief, } from './content-synthesize.ts';
+export { chooseDeckOutline, DECK_OUTLINE_IDS, DECK_OUTLINE_LIMITS, DECK_OUTLINES, type DeckOutlineId, type DeckOutlineOptions, type DeckOutlineResult, type DeckOutlineSlide, type DeckPacing, type DeckSlidePlan, deckOutlineRange, deckTitleFromBrief, requestedSlideCount, synthesizeDeckOutline, } from './deck-outlines.ts';
+export { fieldFromPhrase, PEOPLE_ENTITIES } from './fields.ts';
+export { APP_CUES, type BriefKindDetection, type CueStrength, type DetectKindOptions, detectBriefKind, KIND_CUES, type KindConfidence, type KindCue, } from './kind-detection.ts';
+export { type ApplyOutlineBoundsResult, applyOutlineBounds, type BoundBriefInput, type BriefLimitCode, type BriefLimitIssue, boundBriefInput, checkOutlineBounds, OUTLINE_LIMITS, type OutlineBoundsInput, type OutlineLimits, type OutlineUnitInput, prepareBriefForSynthesis, } from './limits.ts';
+export { buildDocOutline, buildPageOutline, DOC_OUTLINE_IDS, type DocOutlineId, type DocOutlineResult, detectPageDocOmissions, type OutlineBlock, type OutlineBuildOptions, type OutlineSection, PAGE_OUTLINE_IDS, type PageOutlineId, type PageOutlineResult, sectionIds, selectDocOutline, selectPageOutline, } from './page-doc-outlines.ts';
+export { type AppBriefResult, type BriefOptions, type BriefResult, blueprintFromBrief, isAppBriefResult, isContentBriefResult, MAX_BRIEF_LENGTH, type SuggestedLayout, synthesizeAppFromBrief, } from './synthesize.ts';

package/dist/brief/index.js

@@ -0,0 +1,8 @@
+export { ARCHETYPE_IDS, ARCHETYPES, GENERIC_ARCHETYPE } from "./archetypes.js";
+export { MAX_CONTENT_BRIEF_LENGTH, synthesizeContentFromBrief, synthesizeDeckFromBrief, synthesizeDocFromBrief, synthesizePageFromBrief, } from "./content-synthesize.js";
+export { chooseDeckOutline, DECK_OUTLINE_IDS, DECK_OUTLINE_LIMITS, DECK_OUTLINES, deckOutlineRange, deckTitleFromBrief, requestedSlideCount, synthesizeDeckOutline, } from "./deck-outlines.js";
+export { fieldFromPhrase, PEOPLE_ENTITIES } from "./fields.js";
+export { APP_CUES, detectBriefKind, KIND_CUES, } from "./kind-detection.js";
+export { applyOutlineBounds, boundBriefInput, checkOutlineBounds, OUTLINE_LIMITS, prepareBriefForSynthesis, } from "./limits.js";
+export { buildDocOutline, buildPageOutline, DOC_OUTLINE_IDS, detectPageDocOmissions, PAGE_OUTLINE_IDS, sectionIds, selectDocOutline, selectPageOutline, } from "./page-doc-outlines.js";
+export { blueprintFromBrief, isAppBriefResult, isContentBriefResult, MAX_BRIEF_LENGTH, synthesizeAppFromBrief, } from "./synthesize.js";

package/dist/brief/kind-detection.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Brief kind detection (ADR-036): decides whether a prose brief asks for an
+ * app, a deck, a page or a doc before any app archetype is scored.
+ *
+ * The rules are deliberately conservative, because `app` is what every brief
+ * meant before kinds existed:
+ *
+ * 1. An explicit kind always wins.
+ * 2. A content kind is chosen only on a strong cue ("slides", "keynote",
+ *    "landing page", "report", "one-pager"…). Weak cues ("talk", "hero",
+ *    "article") are reported as a suggestion but never switch the kind.
+ * 3. A cue followed by a tool noun ("slide deck builder", "report generator")
+ *    describes an app that makes that content, so it counts for `app`.
+ * 4. Strong cues for two content kinds, or an app noun ("app", "dashboard",
+ *    "platform"…) before the first strong cue, make the brief ambiguous: the
+ *    result is `app`, with a reason that names the conflict and how to pick.
+ *
+ * Matching is on whole lowercase words (`normalize`), longest phrase first,
+ * so the same brief always gives the same result.
+ */
+import { type BlueprintKind, type ContentKind } from '../kinds/kind.ts';
+export type CueStrength = 'strong' | 'weak';
+/**
+ * - `explicit`: the caller chose the kind.
+ * - `high`: strong cues for one content kind and no app cue at all.
+ * - `medium`: strong cues for one content kind, with app words only after them
+ *   ("slides about our CRM app").
+ * - `fallback`: no deciding cue, or an ambiguous brief; the kind is `app`.
+ */
+export type KindConfidence = 'explicit' | 'high' | 'medium' | 'fallback';
+export interface KindCue {
+    kind: BlueprintKind;
+    /** The phrase as matched, in normalized words (`"one pager"`). */
+    phrase: string;
+    strength: CueStrength;
+    /** Word offset in the normalized brief, for ordering and highlighting. */
+    index: number;
+}
+export interface BriefKindDetection {
+    kind: BlueprintKind;
+    confidence: KindConfidence;
+    /** True when cues pointed to more than one kind and `app` was kept. */
+    ambiguous: boolean;
+    /** One sentence a CLI or UI can show as is. */
+    reason: string;
+    /** Every cue found, in brief order. */
+    cues: KindCue[];
+    /** The content kind the cues lean to when they were not enough to switch. */
+    suggestion: ContentKind | null;
+}
+export interface DetectKindOptions {
+    /** An explicit kind (for example from `--kind`); overrides every cue. */
+    kind?: BlueprintKind;
+}
+interface CueList {
+    strong: readonly string[];
+    weak: readonly string[];
+}
+/** Content cues per kind, in normalized words ("one-pager" normalizes to "one pager"). */
+export declare const KIND_CUES: Readonly<Record<ContentKind, CueList>>;
+/** Nouns that name an app; before the first content cue, they keep the brief an app. */
+export declare const APP_CUES: readonly string[];
+/**
+ * Detects the kind a brief asks for. Deterministic: the same brief and options
+ * always give the same result. Throws a `RangeError` for an explicit kind this
+ * version does not know.
+ */
+export declare function detectBriefKind(brief: string, options?: DetectKindOptions): BriefKindDetection;
+export {};