@decantr/core 1.0.0-beta.9 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Decantr AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @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. `@decantr/core` is part of the supported Decantr public foundation surface, but it is intentionally lower-level than the usual integration entrypoints.
+
+## 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 bundle compilation and pack selection helpers
+- canonical pack adapter resolution used by higher-level Decantr surfaces
+- execution-pack schema URLs
+- markdown rendering for compiled packs
+- IR and pipeline helpers used by higher-level Decantr surfaces
+
+In the current workflow architecture, `@decantr/core` owns the canonical adapter labels used by compiled packs, while runnable greenfield bootstrap adapters are resolved in the CLI on top of those labels.
+
+## Example
+
+```ts
+import {
+  buildReviewPack,
+  renderExecutionPackMarkdown,
+  resolvePackAdapter,
+} from '@decantr/core';
+
+const pack = buildReviewPack({
+  projectName: 'Acme Console',
+  target: 'react',
+  routeCount: 4,
+  sections: ['overview', 'settings'],
+});
+
+const adapter = resolvePackAdapter('react', 'spa');
+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`
+- `@decantr/core/schema/execution-pack-bundle.v1.json`
+- `@decantr/core/schema/selected-execution-pack.v1.json`
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { EssenceFile, StructurePage } from '@decantr/essence-spec';
-import { Pattern, ResolvedPreset, Theme, 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[];
 }
@@ -78,6 +78,7 @@ interface IRTheme {
 interface IRRoute {
     path: string;
     pageId: string;
+    shell: string;
 }
 /** Which v3 essence layer sourced this node */
 type IRLayer = 'dna' | 'blueprint' | 'meta';
@@ -94,7 +95,7 @@ interface IRAppNode extends IRNode {
     type: 'app';
     theme: IRTheme;
     routes: IRRoute[];
-    routing: 'hash' | 'history';
+    routing: 'hash' | 'history' | 'pathname';
     shell: IRShellNode;
     store: IRStoreNode;
     features: string[];
@@ -136,13 +137,301 @@ 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[];
+    shell?: string;
+}
+interface ScaffoldPackData {
+    shell: string;
+    theme: {
+        id: string;
+        mode: string;
+        shape: string | null;
+    };
+    routing: 'hash' | 'history' | 'pathname';
+    features: string[];
+    navigation?: {
+        commandPalette: boolean;
+        hotkeys: Array<{
+            key: string;
+            route?: string;
+            label?: 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[];
+    shell?: 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>;
+    navigation?: {
+        commandPalette: boolean;
+        hotkeys: Array<{
+            key: string;
+            route?: string;
+            label?: string;
+        }>;
+    };
+}
+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, themes) */
-    contentRoot: string;
+    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 */
@@ -205,4 +494,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 IRRoute, type IRShellConfig, type IRShellNode, type IRSpatial, type IRStoreNode, type IRTheme, type IRThemeDecoration, 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 };