@decantr/core 1.0.0-beta.8 → 1.0.0

package/README.md

@@ -0,0 +1,55 @@
+# @decantr/core
+
+Support status: `core-supported`  
+Release channel: `stable`
+
+Low-level Decantr compiler and execution-pack foundation.
+
+Most teams should use `@decantr/cli`, `@decantr/registry`, or `@decantr/mcp-server` directly. This package remains inside the Decantr implementation boundary and is not part of the supported public package contract.
+
+## Install
+
+```bash
+npm install @decantr/core
+```
+
+## Stability
+
+`@decantr/core` is published for advanced package consumers that need low-level execution-pack primitives. It is stable in the `1.x` line for the documented exports in this package, but it is still not the recommended first integration surface for most Decantr adopters.
+
+## What It Exports
+
+- execution-pack builders for scaffold, section, page, mutation, and review scopes
+- execution-pack schema URLs
+- markdown rendering for compiled packs
+- IR and pipeline helpers used by higher-level Decantr surfaces
+
+## Example
+
+```ts
+import { buildReviewPack, renderExecutionPackMarkdown } from '@decantr/core';
+
+const pack = buildReviewPack({
+  projectName: 'Acme Console',
+  target: 'react',
+  routeCount: 4,
+  sections: ['overview', 'settings'],
+});
+
+const markdown = renderExecutionPackMarkdown(pack);
+```
+
+## Schema Exports
+
+This package publishes execution-pack schemas under:
+
+- `@decantr/core/schema/scaffold-pack.v1.json`
+- `@decantr/core/schema/section-pack.v1.json`
+- `@decantr/core/schema/page-pack.v1.json`
+- `@decantr/core/schema/mutation-pack.v1.json`
+- `@decantr/core/schema/review-pack.v1.json`
+- `@decantr/core/schema/pack-manifest.v1.json`
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { EssenceFile, StructurePage } from '@decantr/essence-spec';
-import { Pattern, ResolvedPreset, Recipe, ContentResolver } from '@decantr/registry';
+import { EssenceFile, EssenceV3, StructurePage } from '@decantr/essence-spec';
+import { ContentResolver, Pattern, ResolvedPreset, Theme } from '@decantr/registry';
 
 type IRNodeType = 'app' | 'shell' | 'page' | 'pattern' | 'grid' | 'nav' | 'store';
 interface IRSpatial {
@@ -31,8 +31,8 @@ interface IRPatternMeta {
     contained: boolean;
     standalone: boolean;
     code: {
-        imports: string;
-        example: string;
+        imports?: string;
+        example?: string;
     } | null;
     components: string[];
 }
@@ -43,7 +43,6 @@ interface IRVisualEffect {
 interface IRCardWrapping {
     mode: 'always' | 'minimal' | 'none';
     headerLabel: string;
-    background?: string;
 }
 interface IRNavItem {
     href: string;
@@ -55,9 +54,9 @@ interface IRShellConfig {
     brand: string;
     nav: IRNavItem[];
     inset: boolean;
-    recipe: IRRecipeDecoration | null;
+    decoration: IRThemeDecoration | null;
 }
-interface IRRecipeDecoration {
+interface IRThemeDecoration {
     root: string;
     nav: string;
     header: string;
@@ -71,10 +70,9 @@ interface IRRecipeDecoration {
     } | null;
 }
 interface IRTheme {
-    style: string;
+    id: string;
     mode: string;
     shape: string | null;
-    recipe: string;
     isAddon: boolean;
 }
 interface IRRoute {
@@ -96,7 +94,7 @@ interface IRAppNode extends IRNode {
     type: 'app';
     theme: IRTheme;
     routes: IRRoute[];
-    routing: 'hash' | 'history';
+    routing: 'hash' | 'history' | 'pathname';
     shell: IRShellNode;
     store: IRStoreNode;
     features: string[];
@@ -138,13 +136,283 @@ interface IRStoreNode extends IRNode {
     }[];
 }
 
+type ExecutionPackType = 'scaffold' | 'section' | 'page' | 'mutation' | 'review';
+declare const EXECUTION_PACK_SCHEMA_URLS: {
+    readonly scaffold: "https://decantr.ai/schemas/scaffold-pack.v1.json";
+    readonly section: "https://decantr.ai/schemas/section-pack.v1.json";
+    readonly page: "https://decantr.ai/schemas/page-pack.v1.json";
+    readonly mutation: "https://decantr.ai/schemas/mutation-pack.v1.json";
+    readonly review: "https://decantr.ai/schemas/review-pack.v1.json";
+};
+declare const PACK_MANIFEST_SCHEMA_URL = "https://decantr.ai/schemas/pack-manifest.v1.json";
+declare const EXECUTION_PACK_BUNDLE_SCHEMA_URL = "https://decantr.ai/schemas/execution-pack-bundle.v1.json";
+declare const SELECTED_EXECUTION_PACK_SCHEMA_URL = "https://decantr.ai/schemas/selected-execution-pack.v1.json";
+interface ExecutionPackTarget {
+    platform: 'web';
+    framework: string | null;
+    runtime: string | null;
+    adapter: string;
+}
+interface ExecutionPackScope {
+    appId: string;
+    pageIds: string[];
+    patternIds: string[];
+}
+interface ExecutionPackExample {
+    id: string;
+    label: string;
+    language: string;
+    snippet: string;
+}
+interface ExecutionPackAntiPattern {
+    id: string;
+    summary: string;
+    guidance: string;
+}
+interface ExecutionPackSuccessCheck {
+    id: string;
+    label: string;
+    severity: 'error' | 'warn' | 'info';
+}
+interface ExecutionPackTokenBudget {
+    target: number;
+    max: number;
+    strategy: string[];
+}
+interface ExecutionPackBase<TData> {
+    $schema: string;
+    packVersion: '1.0.0';
+    packType: ExecutionPackType;
+    objective: string;
+    target: ExecutionPackTarget;
+    preset: string | null;
+    scope: ExecutionPackScope;
+    requiredSetup: string[];
+    allowedVocabulary: string[];
+    examples: ExecutionPackExample[];
+    antiPatterns: ExecutionPackAntiPattern[];
+    successChecks: ExecutionPackSuccessCheck[];
+    tokenBudget: ExecutionPackTokenBudget;
+    data: TData;
+    renderedMarkdown: string;
+}
+interface PackManifestEntry {
+    id: string;
+    markdown: string;
+    json: string;
+}
+interface PackManifestSectionEntry extends PackManifestEntry {
+    pageIds: string[];
+}
+interface PackManifestPageEntry extends PackManifestEntry {
+    sectionId: string | null;
+    sectionRole: string | null;
+}
+interface PackManifestMutationEntry extends PackManifestEntry {
+    mutationType: MutationPackKind;
+}
+interface ExecutionPackManifest {
+    $schema: string;
+    version: '1.0.0';
+    generatedAt: string;
+    scaffold: PackManifestEntry | null;
+    review: PackManifestEntry | null;
+    sections: PackManifestSectionEntry[];
+    pages: PackManifestPageEntry[];
+    mutations: PackManifestMutationEntry[];
+}
+interface ScaffoldPackRoute {
+    pageId: string;
+    path: string;
+    patternIds: string[];
+}
+interface ScaffoldPackData {
+    shell: string;
+    theme: {
+        id: string;
+        mode: string;
+        shape: string | null;
+    };
+    routing: 'hash' | 'history' | 'pathname';
+    features: string[];
+    routes: ScaffoldPackRoute[];
+}
+interface ScaffoldExecutionPack extends ExecutionPackBase<ScaffoldPackData> {
+    packType: 'scaffold';
+}
+interface SectionPackInput {
+    id: string;
+    role: string;
+    shell: string;
+    description: string;
+    features: string[];
+    pageIds: string[];
+}
+interface SectionPackRoute {
+    pageId: string;
+    path: string;
+    patternIds: string[];
+}
+interface SectionPackData {
+    sectionId: string;
+    role: string;
+    shell: string;
+    description: string;
+    features: string[];
+    theme: {
+        id: string;
+        mode: string;
+        shape: string | null;
+    };
+    routes: SectionPackRoute[];
+}
+interface SectionExecutionPack extends ExecutionPackBase<SectionPackData> {
+    packType: 'section';
+}
+interface PagePackInput {
+    pageId: string;
+    shell: string;
+    sectionId: string | null;
+    sectionRole: string | null;
+    features: string[];
+}
+interface PagePackPattern {
+    id: string;
+    alias: string;
+    preset: string;
+    layout: string;
+}
+interface PagePackData {
+    pageId: string;
+    path: string;
+    shell: string;
+    sectionId: string | null;
+    sectionRole: string | null;
+    features: string[];
+    surface: string;
+    theme: {
+        id: string;
+        mode: string;
+        shape: string | null;
+    };
+    wiringSignals: string[];
+    patterns: PagePackPattern[];
+}
+interface PageExecutionPack extends ExecutionPackBase<PagePackData> {
+    packType: 'page';
+}
+type MutationPackKind = 'add-page' | 'modify';
+interface MutationPackData {
+    mutationType: MutationPackKind;
+    shell: string;
+    theme: {
+        id: string;
+        mode: string;
+        shape: string | null;
+    };
+    routing: 'hash' | 'history' | 'pathname';
+    features: string[];
+    routes: ScaffoldPackRoute[];
+    workflow: string[];
+}
+interface MutationExecutionPack extends ExecutionPackBase<MutationPackData> {
+    packType: 'mutation';
+}
+type ReviewPackKind = 'app';
+interface ReviewPackData {
+    reviewType: ReviewPackKind;
+    shell: string;
+    theme: {
+        id: string;
+        mode: string;
+        shape: string | null;
+    };
+    routing: 'hash' | 'history' | 'pathname';
+    features: string[];
+    routes: ScaffoldPackRoute[];
+    focusAreas: string[];
+    workflow: string[];
+}
+interface ReviewExecutionPack extends ExecutionPackBase<ReviewPackData> {
+    packType: 'review';
+}
+interface ExecutionPackBundle {
+    $schema: string;
+    generatedAt: string;
+    sourceEssenceVersion: string;
+    manifest: ExecutionPackManifest;
+    scaffold: ScaffoldExecutionPack;
+    review: ReviewExecutionPack;
+    sections: SectionExecutionPack[];
+    pages: PageExecutionPack[];
+    mutations: MutationExecutionPack[];
+}
+type SelectedExecutionPack = ScaffoldExecutionPack | ReviewExecutionPack | SectionExecutionPack | PageExecutionPack | MutationExecutionPack;
+interface ExecutionPackSelector {
+    packType: ExecutionPackType;
+    id?: string | null;
+}
+interface SelectedExecutionPackResponse {
+    $schema: string;
+    generatedAt: string;
+    sourceEssenceVersion: string;
+    manifest: ExecutionPackManifest;
+    selector: {
+        packType: ExecutionPackType;
+        id: string | null;
+    };
+    pack: SelectedExecutionPack;
+}
+interface ScaffoldPackBuilderOptions {
+    objective?: string;
+    target?: Partial<ExecutionPackTarget>;
+    preset?: string | null;
+    requiredSetup?: string[];
+    examples?: ExecutionPackExample[];
+    antiPatterns?: ExecutionPackAntiPattern[];
+    successChecks?: ExecutionPackSuccessCheck[];
+    tokenBudget?: Partial<ExecutionPackTokenBudget>;
+}
+interface SectionPackBuilderOptions extends ScaffoldPackBuilderOptions {
+}
+interface PagePackBuilderOptions extends ScaffoldPackBuilderOptions {
+}
+interface MutationPackBuilderOptions extends ScaffoldPackBuilderOptions {
+    mutationType: MutationPackKind;
+    workflow?: string[];
+}
+interface ReviewPackBuilderOptions extends ScaffoldPackBuilderOptions {
+    reviewType?: ReviewPackKind;
+    focusAreas?: string[];
+    workflow?: string[];
+}
+interface CompileExecutionPackBundleOptions {
+    contentRoot?: string;
+    overridePaths?: string[];
+    resolver?: ContentResolver;
+}
+declare function renderExecutionPackMarkdown(pack: ExecutionPackBase<unknown>): string;
+declare function resolvePackAdapter(target: string | undefined, platformType: string | undefined): string;
+declare function listPackSections(essence: EssenceV3): SectionPackInput[];
+declare function listPackPages(essence: EssenceV3): PagePackInput[];
+declare function buildScaffoldPack(appNode: IRAppNode, options?: ScaffoldPackBuilderOptions): ScaffoldExecutionPack;
+declare function buildSectionPack(appNode: IRAppNode, input: SectionPackInput, options?: SectionPackBuilderOptions): SectionExecutionPack;
+declare function buildPagePack(appNode: IRAppNode, input: PagePackInput, options?: PagePackBuilderOptions): PageExecutionPack;
+declare function buildMutationPack(appNode: IRAppNode, options: MutationPackBuilderOptions): MutationExecutionPack;
+declare function buildReviewPack(appNode: IRAppNode, options?: ReviewPackBuilderOptions): ReviewExecutionPack;
+declare function compileExecutionPackBundle(essence: EssenceFile, options?: CompileExecutionPackBundleOptions): Promise<ExecutionPackBundle>;
+declare function selectExecutionPackFromBundle(bundle: ExecutionPackBundle, selector: ExecutionPackSelector): SelectedExecutionPackResponse | null;
+declare function compileSelectedExecutionPack(essence: EssenceFile, selector: ExecutionPackSelector, options?: CompileExecutionPackBundleOptions): Promise<SelectedExecutionPackResponse | null>;
+
 interface PipelineOptions {
-    /** Path to content directory (patterns, archetypes, recipes) */
-    contentRoot: string;
+    /** Path to content directory (patterns, archetypes, themes) */
+    contentRoot?: string;
     /** Override paths for local content resolution */
     overridePaths?: string[];
     /** Only resolve specific page(s) */
     pageFilter?: string;
+    /** Optional custom resolver for hosted or in-memory execution */
+    resolver?: ContentResolver;
 }
 interface PipelineResult {
     /** The framework-agnostic intermediate representation */
@@ -153,7 +421,7 @@ interface PipelineResult {
 /**
  * Run the Design Pipeline:
  *   1. Validate Essence against schema + guard rules
- *   2. Resolve all references (patterns, recipe, wiring) from registry
+ *   2. Resolve all references (patterns, theme, wiring) from registry
  *   3. Build framework-agnostic IR tree
  *   4. Return IR (no code generation — that's the consumer's job)
  */
@@ -164,7 +432,7 @@ interface ResolvedPatternEntry {
     preset: ResolvedPreset;
 }
 /** Build IR tree for a single page from its resolved structure + patterns */
-declare function buildPageIR(page: StructurePage, resolvedPatterns: Map<string, ResolvedPatternEntry>, wiring: IRWiring | null, recipe: Recipe | null, density: {
+declare function buildPageIR(page: StructurePage, resolvedPatterns: Map<string, ResolvedPatternEntry>, wiring: IRWiring | null, theme: Theme | null, density: {
     gap: string;
 }, layer?: IRLayer): IRPageNode;
 
@@ -179,7 +447,7 @@ interface ResolvedPage {
 interface ResolvedEssence {
     essence: EssenceFile;
     pages: ResolvedPage[];
-    recipe: Recipe | null;
+    registryTheme: Theme | null;
     density: {
         gap: string;
         level: string;
@@ -191,7 +459,7 @@ interface ResolvedEssence {
     /** True when the source essence was v3 (DNA/Blueprint/Meta) */
     isV3Source: boolean;
 }
-declare function resolveVisualEffects(recipe: Recipe, pattern: Pattern, _slot?: string): IRVisualEffect | null;
+declare function resolveVisualEffects(theme: Theme, pattern: Pattern, _slot?: string): IRVisualEffect | null;
 /** Resolve all external references in an Essence file */
 declare function resolveEssence(essence: EssenceFile, resolver: ContentResolver): Promise<ResolvedEssence>;
 
@@ -207,4 +475,4 @@ declare function validateIR(root: IRNode): string[];
 /** Convert a kebab-case or snake_case string to PascalCase */
 declare function pascalCase(str: string): string;
 
-export { type IRAppNode, type IRBreakpointEntry, type IRCardWrapping, type IRGridNode, type IRHookType, type IRLayer, type IRNavItem, type IRNode, type IRNodeType, type IRPageNode, type IRPatternMeta, type IRPatternNode, type IRRecipeDecoration, type IRRoute, type IRShellConfig, type IRShellNode, type IRSpatial, type IRStoreNode, type IRTheme, type IRVisualEffect, type IRWiring, type IRWiringSignal, type PipelineOptions, type PipelineResult, type ResolvedEssence, type ResolvedPage, buildPageIR, countPatterns, findNodes, pascalCase, resolveEssence, resolveVisualEffects, runPipeline, validateIR, walkIR };
+export { type CompileExecutionPackBundleOptions, EXECUTION_PACK_BUNDLE_SCHEMA_URL, EXECUTION_PACK_SCHEMA_URLS, type ExecutionPackAntiPattern, type ExecutionPackBase, type ExecutionPackBundle, type ExecutionPackExample, type ExecutionPackManifest, type ExecutionPackScope, type ExecutionPackSelector, type ExecutionPackSuccessCheck, type ExecutionPackTarget, type ExecutionPackTokenBudget, type ExecutionPackType, type IRAppNode, type IRBreakpointEntry, type IRCardWrapping, type IRGridNode, type IRHookType, type IRLayer, type IRNavItem, type IRNode, type IRNodeType, type IRPageNode, type IRPatternMeta, type IRPatternNode, type IRRoute, type IRShellConfig, type IRShellNode, type IRSpatial, type IRStoreNode, type IRTheme, type IRThemeDecoration, type IRVisualEffect, type IRWiring, type IRWiringSignal, type MutationExecutionPack, type MutationPackBuilderOptions, type MutationPackData, type MutationPackKind, PACK_MANIFEST_SCHEMA_URL, type PackManifestEntry, type PackManifestMutationEntry, type PackManifestPageEntry, type PackManifestSectionEntry, type PageExecutionPack, type PagePackBuilderOptions, type PagePackData, type PagePackInput, type PagePackPattern, type PipelineOptions, type PipelineResult, type ResolvedEssence, type ResolvedPage, type ReviewExecutionPack, type ReviewPackBuilderOptions, type ReviewPackData, type ReviewPackKind, SELECTED_EXECUTION_PACK_SCHEMA_URL, type ScaffoldExecutionPack, type ScaffoldPackBuilderOptions, type ScaffoldPackData, type ScaffoldPackRoute, type SectionExecutionPack, type SectionPackBuilderOptions, type SectionPackData, type SectionPackInput, type SectionPackRoute, type SelectedExecutionPack, type SelectedExecutionPackResponse, buildMutationPack, buildPageIR, buildPagePack, buildReviewPack, buildScaffoldPack, buildSectionPack, compileExecutionPackBundle, compileSelectedExecutionPack, countPatterns, findNodes, listPackPages, listPackSections, pascalCase, renderExecutionPackMarkdown, resolveEssence, resolvePackAdapter, resolveVisualEffects, runPipeline, selectExecutionPackFromBundle, validateIR, walkIR };