@hstm-labs/forge-apps-generator 0.1.11

package/README.md

@@ -0,0 +1,35 @@
+# @hstm-labs/forge-apps-generator
+
+Apps (UI) layer generation stage for Forge — produces pages, components, layouts, forms, and navigation for web/ and mobile-web/ from specification workflows, architecture, and services (API) output.
+
+## Installation
+
+```bash
+npm install @hstm-labs/forge-apps-generator
+```
+
+## Public API
+
+### Types
+
+- `UiArtifact` — complete UI layer output
+- `UiPage`, `UiComponent`, `UiLayout`, `UiForm`, `UiNavigation`, `UiRoute`
+
+### Classes
+
+- `AppsGenerateStage` — pipeline stage implementing `PipelineStage` interface
+- `UiOutputValidator` — validates LLM-produced UI output
+
+## Usage
+
+```typescript
+import { AppsGenerateStage } from '@hstm-labs/forge-apps-generator';
+
+const stage = new AppsGenerateStage();
+const result = await stage.execute(input);
+// result.data contains UiArtifact
+```
+
+## License
+
+[MIT](../../LICENSE)

package/dist/apps-generate-stage.d.ts

@@ -0,0 +1,57 @@
+/**
+ * UI generation pipeline stage.
+ *
+ * Produces pages, components, layouts, forms, and navigation from
+ * specification workflows, architecture, API endpoints, and technology
+ * profile. Follows the same stage implementation pattern established by
+ * {@link ArchitectStage} and {@link ServicesGenerateStage}.
+ *
+ * In API mode, renders prompt templates, calls the LLM via
+ * {@link ApiStageExecutor}, validates the output, unpacks individual
+ * files into subdirectories, and returns the parsed {@link UiArtifact}
+ * in the stage output data.
+ *
+ * In agent mode, the pipeline runner intercepts before calling
+ * `execute()` and exports a prompt via {@link AgentStageExecutor}.
+ */
+import type { StageName } from '@hstm-labs/forge-common';
+import type { PipelineStage, PipelineStageInput, PipelineStageOutput, PipelineContext, AgentPromptContext } from '@hstm-labs/forge-core';
+/**
+ * Pipeline stage that generates the UI layer.
+ *
+ * Produces a {@link UiArtifact} containing pages, components, layouts,
+ * forms, and navigation configuration. Each element is written as a
+ * separate file artifact grouped into subdirectories.
+ *
+ * @example
+ * ```ts
+ * const stage = new AppsGenerateStage();
+ * const output = await stage.execute(input, context);
+ * const ui = output.data?.ui as UiArtifact;
+ * ```
+ */
+export declare class AppsGenerateStage implements PipelineStage {
+    readonly name: StageName;
+    readonly dependsOn: StageName[];
+    readonly requiresLLM = true;
+    /**
+     * Return rendered agent-mode prompt context using `apps-generate-agent.hbs`.
+     *
+     * @param input - Input from prior stages
+     * @param context - Pipeline context with config, workspace, and runId
+     * @returns Agent prompt context with rendered template and output schema
+     */
+    getAgentContext(input: PipelineStageInput, context: PipelineContext): AgentPromptContext;
+    /**
+     * Execute the UI generation stage.
+     *
+     * @param input - Input from prior stages (expects validate + architect + services-generate output)
+     * @param context - Pipeline context with config, workspace, and adapter
+     * @returns Stage output with UI artifacts and parsed UiArtifact in data
+     * @throws {ForgeError} FORGE-PIPE-003 if dependency stage output is missing
+     * @throws {ForgeError} FORGE-PIPE-001 if adapter is missing
+     * @throws {ForgeError} FORGE-GEN-003 if max retries exhausted
+     */
+    execute(input: PipelineStageInput, context: PipelineContext): Promise<PipelineStageOutput>;
+}
+//# sourceMappingURL=apps-generate-stage.d.ts.map

package/dist/apps-generate-stage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apps-generate-stage.d.ts","sourceRoot":"","sources":["../src/apps-generate-stage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EAEf,kBAAkB,EACnB,MAAM,uBAAuB,CAAC;AAY/B;;;;;;;;;;;;;GAaG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAmB;IAC3C,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,CAAsC;IACrE,QAAQ,CAAC,WAAW,QAAQ;IAE5B;;;;;;OAMG;IACH,eAAe,CACb,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,eAAe,GACvB,kBAAkB;IA+CrB;;;;;;;;;OASG;IACG,OAAO,CACX,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,mBAAmB,CAAC;CAqNhC"}

package/dist/apps-generate-stage.js

@@ -0,0 +1,232 @@
+/**
+ * UI generation pipeline stage.
+ *
+ * Produces pages, components, layouts, forms, and navigation from
+ * specification workflows, architecture, API endpoints, and technology
+ * profile. Follows the same stage implementation pattern established by
+ * {@link ArchitectStage} and {@link ServicesGenerateStage}.
+ *
+ * In API mode, renders prompt templates, calls the LLM via
+ * {@link ApiStageExecutor}, validates the output, unpacks individual
+ * files into subdirectories, and returns the parsed {@link UiArtifact}
+ * in the stage output data.
+ *
+ * In agent mode, the pipeline runner intercepts before calling
+ * `execute()` and exports a prompt via {@link AgentStageExecutor}.
+ */
+import { join } from 'node:path';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { ForgeError, ErrorCodes, hashContent } from '@hstm-labs/forge-common';
+import { ApiStageExecutor } from '@hstm-labs/forge-core';
+import { resolveApiStyle } from '@hstm-labs/forge-architect';
+import { loadProfile } from '@hstm-labs/forge-profiles';
+import { loadTemplate, renderTemplate } from '@hstm-labs/forge-templates';
+import { UiOutputValidator } from './validator.js';
+/**
+ * Pipeline stage that generates the UI layer.
+ *
+ * Produces a {@link UiArtifact} containing pages, components, layouts,
+ * forms, and navigation configuration. Each element is written as a
+ * separate file artifact grouped into subdirectories.
+ *
+ * @example
+ * ```ts
+ * const stage = new AppsGenerateStage();
+ * const output = await stage.execute(input, context);
+ * const ui = output.data?.ui as UiArtifact;
+ * ```
+ */
+export class AppsGenerateStage {
+    name = 'apps-generate';
+    dependsOn = ['architect', 'services-generate'];
+    requiresLLM = true;
+    /**
+     * Return rendered agent-mode prompt context using `apps-generate-agent.hbs`.
+     *
+     * @param input - Input from prior stages
+     * @param context - Pipeline context with config, workspace, and runId
+     * @returns Agent prompt context with rendered template and output schema
+     */
+    getAgentContext(input, context) {
+        const parsedSpec = input['validate']?.data?.['parsedSpec'];
+        const architecture = input['architect']?.data?.['architecture'];
+        const api = input['services-generate']?.data?.['api'];
+        const profile = loadProfile(context.config.profileName, context.workspace.rootDir);
+        const resolvedApiStyle = parsedSpec
+            ? resolveApiStyle(parsedSpec, profile)
+            : 'graphql';
+        const outputDir = join(context.workspace.forgeDir, 'runs', context.runId, 'stages', 'apps-generate', 'artifacts');
+        const agentTemplate = loadTemplate('apps-generate-agent', context.workspace.rootDir);
+        const rendered = renderTemplate(agentTemplate, {
+            spec: (parsedSpec ?? {}),
+            profile: profile,
+            architecture: (architecture ?? {}),
+            api: (api ?? {}),
+            stage: { resolvedApiStyle, outputDir },
+        });
+        return {
+            prompt: rendered.content,
+            outputSchema: { format: 'json' },
+        };
+    }
+    /**
+     * Execute the UI generation stage.
+     *
+     * @param input - Input from prior stages (expects validate + architect + services-generate output)
+     * @param context - Pipeline context with config, workspace, and adapter
+     * @returns Stage output with UI artifacts and parsed UiArtifact in data
+     * @throws {ForgeError} FORGE-PIPE-003 if dependency stage output is missing
+     * @throws {ForgeError} FORGE-PIPE-001 if adapter is missing
+     * @throws {ForgeError} FORGE-GEN-003 if max retries exhausted
+     */
+    async execute(input, context) {
+        // 1. Get parsed spec from validate stage output
+        const validateOutput = input['validate'];
+        if (validateOutput === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.DEPENDENCY_UNMET, "Apps generate stage requires 'validate' stage output, but it was not found. " +
+                'Ensure the validate stage runs before the apps-generate stage.');
+        }
+        const parsedSpec = validateOutput.data?.['parsedSpec'];
+        if (parsedSpec === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.STAGE_FAILURE, 'Validate stage did not produce a parsed specification in its output data. ' +
+                'Ensure the validate stage includes parsedSpec in its data output.');
+        }
+        // 2. Get architecture from architect stage output
+        const architectOutput = input['architect'];
+        if (architectOutput === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.DEPENDENCY_UNMET, "Apps generate stage requires 'architect' stage output, but it was not found. " +
+                'Ensure the architect stage runs before the apps-generate stage.');
+        }
+        const architecture = architectOutput.data?.['architecture'];
+        if (architecture === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.STAGE_FAILURE, 'Architect stage did not produce an architecture in its output data. ' +
+                'Ensure the architect stage includes architecture in its data output.');
+        }
+        // 3. Get API artifact from services-generate stage output
+        const servicesGenerateOutput = input['services-generate'];
+        if (servicesGenerateOutput === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.DEPENDENCY_UNMET, "Apps generate stage requires 'services-generate' stage output, but it was not found. " +
+                'Ensure the services-generate stage runs before the apps-generate stage.');
+        }
+        const api = servicesGenerateOutput.data?.['api'];
+        if (api === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.STAGE_FAILURE, 'Services generate stage did not produce an API artifact in its output data. ' +
+                'Ensure the services-generate stage includes api in its data output.');
+        }
+        // 4. Load profile, resolve API style
+        const profile = loadProfile(context.config.profileName, context.workspace.rootDir);
+        const resolvedApiStyle = resolveApiStyle(parsedSpec, profile);
+        // 5. Compute output directory
+        const outputDir = join(context.workspace.forgeDir, 'runs', context.runId, 'stages', 'apps-generate', 'artifacts');
+        // 6. Load and render templates
+        const systemTemplate = loadTemplate('apps-generate-system', context.workspace.rootDir);
+        const userTemplate = loadTemplate('apps-generate-user', context.workspace.rootDir);
+        const templateContext = {
+            spec: parsedSpec,
+            profile: profile,
+            architecture: architecture,
+            api: api,
+            stage: {
+                resolvedApiStyle,
+                outputDir,
+            },
+        };
+        const systemPrompt = renderTemplate(systemTemplate, templateContext);
+        const userPrompt = renderTemplate(userTemplate, templateContext);
+        // 7. Execute via API mode StageExecutor
+        if (context.adapter === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.STAGE_FAILURE, 'Apps generate stage requires an LLM adapter in API mode, but none was provided. ' +
+                'Configure an LLM provider in forge.config.json or use agent mode.');
+        }
+        const entityNames = architecture.dataModel.map((e) => e.name);
+        const validator = new UiOutputValidator(entityNames);
+        const executor = new ApiStageExecutor({
+            adapter: context.adapter,
+            validator,
+            retryPolicy: {
+                maxRetries: 3,
+                backoffMs: 1000,
+                includeErrorInRetry: true,
+            },
+        });
+        const result = await executor.execute({
+            prompt: userPrompt.content,
+            systemPrompt: systemPrompt.content,
+            stageName: 'apps-generate',
+            outputDir,
+            runId: context.runId,
+            mode: 'api',
+            outputSchema: { format: 'json' },
+        });
+        // 8. Parse UiArtifact from LLM output
+        const rawContent = result.artifacts[0]?.content ?? '';
+        const uiArtifact = JSON.parse(rawContent);
+        // 9. Write individual files to artifacts directory in subdirectories
+        const artifacts = [];
+        // Pages
+        const pagesDir = join(outputDir, 'pages');
+        mkdirSync(pagesDir, { recursive: true });
+        for (const page of uiArtifact.pages) {
+            writeFileSync(join(pagesDir, page.fileName), page.content, 'utf-8');
+            artifacts.push({
+                filePath: join('pages', page.fileName),
+                content: page.content,
+                contentHash: hashContent(page.content),
+                sizeBytes: Buffer.byteLength(page.content, 'utf-8'),
+            });
+        }
+        // Components
+        const componentsDir = join(outputDir, 'components');
+        mkdirSync(componentsDir, { recursive: true });
+        for (const component of uiArtifact.components) {
+            writeFileSync(join(componentsDir, component.fileName), component.content, 'utf-8');
+            artifacts.push({
+                filePath: join('components', component.fileName),
+                content: component.content,
+                contentHash: hashContent(component.content),
+                sizeBytes: Buffer.byteLength(component.content, 'utf-8'),
+            });
+        }
+        // Layouts
+        const layoutsDir = join(outputDir, 'layouts');
+        mkdirSync(layoutsDir, { recursive: true });
+        for (const layout of uiArtifact.layouts) {
+            writeFileSync(join(layoutsDir, layout.fileName), layout.content, 'utf-8');
+            artifacts.push({
+                filePath: join('layouts', layout.fileName),
+                content: layout.content,
+                contentHash: hashContent(layout.content),
+                sizeBytes: Buffer.byteLength(layout.content, 'utf-8'),
+            });
+        }
+        // Forms
+        const formsDir = join(outputDir, 'forms');
+        mkdirSync(formsDir, { recursive: true });
+        for (const form of uiArtifact.forms) {
+            writeFileSync(join(formsDir, form.fileName), form.content, 'utf-8');
+            artifacts.push({
+                filePath: join('forms', form.fileName),
+                content: form.content,
+                contentHash: hashContent(form.content),
+                sizeBytes: Buffer.byteLength(form.content, 'utf-8'),
+            });
+        }
+        // Navigation
+        mkdirSync(outputDir, { recursive: true });
+        writeFileSync(join(outputDir, uiArtifact.navigation.fileName), uiArtifact.navigation.content, 'utf-8');
+        artifacts.push({
+            filePath: uiArtifact.navigation.fileName,
+            content: uiArtifact.navigation.content,
+            contentHash: hashContent(uiArtifact.navigation.content),
+            sizeBytes: Buffer.byteLength(uiArtifact.navigation.content, 'utf-8'),
+        });
+        // 10. Return PipelineStageOutput with all artifacts and data
+        return {
+            artifacts,
+            data: {
+                ui: uiArtifact,
+            },
+        };
+    }
+}
+//# sourceMappingURL=apps-generate-stage.js.map

package/dist/apps-generate-stage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apps-generate-stage.js","sourceRoot":"","sources":["../src/apps-generate-stage.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { UiArtifact, UiPage, UiComponent, UiLayout, UiForm, UiNavigation, UiRoute, } from './types.js';
+export { AppsGenerateStage } from './apps-generate-stage.js';
+export { UiOutputValidator } from './validator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,UAAU,EACV,MAAM,EACN,WAAW,EACX,QAAQ,EACR,MAAM,EACN,YAAY,EACZ,OAAO,GACR,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { AppsGenerateStage } from './apps-generate-stage.js';
+export { UiOutputValidator } from './validator.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * UI artifact type definitions for the Forge UI generation stage.
+ *
+ * Defines the output schema produced by the UI generation stage,
+ * including pages, components, layouts, forms, and navigation.
+ */
+/** Complete UI layer output produced by the apps-generate stage. */
+export interface UiArtifact {
+    /** Frontend framework used. */
+    framework: string;
+    /** Generated pages (route-level components). */
+    pages: UiPage[];
+    /** Shared/reusable components. */
+    components: UiComponent[];
+    /** Layout components (shells, navigation). */
+    layouts: UiLayout[];
+    /** Form definitions for entity CRUD. */
+    forms: UiForm[];
+    /** Navigation/routing configuration. */
+    navigation: UiNavigation;
+}
+/** A route-level page component. */
+export interface UiPage {
+    /** Page name (e.g., "PetListPage"). */
+    name: string;
+    /** Route path (e.g., "/pets"). */
+    route: string;
+    /** File name (e.g., "PetListPage.tsx"). */
+    fileName: string;
+    /** File content (source code). */
+    content: string;
+    /** Entity this page relates to (if any). */
+    entity?: string | undefined;
+    /** Description. */
+    description: string;
+}
+/** A reusable UI component. */
+export interface UiComponent {
+    /** Component name (e.g., "PetCard"). */
+    name: string;
+    /** File name. */
+    fileName: string;
+    /** File content. */
+    content: string;
+    /** Reusability scope: page-specific or shared. */
+    scope: 'shared' | 'page';
+    /** Description. */
+    description: string;
+}
+/** A layout/shell component. */
+export interface UiLayout {
+    /** Layout name (e.g., "AppShell", "DashboardLayout"). */
+    name: string;
+    /** File name. */
+    fileName: string;
+    /** File content. */
+    content: string;
+    /** Description. */
+    description: string;
+}
+/** A form component for entity CRUD operations. */
+export interface UiForm {
+    /** Form name (e.g., "CreatePetForm"). */
+    name: string;
+    /** Entity this form operates on. */
+    entity: string;
+    /** Operation: create, edit, or search. */
+    operation: 'create' | 'edit' | 'search';
+    /** File name. */
+    fileName: string;
+    /** File content. */
+    content: string;
+}
+/** Navigation/routing configuration. */
+export interface UiNavigation {
+    /** Route definitions. */
+    routes: UiRoute[];
+    /** Navigation file name. */
+    fileName: string;
+    /** File content (router config). */
+    content: string;
+}
+/** A single route definition. */
+export interface UiRoute {
+    /** Route path. */
+    path: string;
+    /** Page component name. */
+    page: string;
+    /** Display label in navigation. */
+    label: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,kCAAkC;IAClC,UAAU,EAAE,WAAW,EAAE,CAAC;IAC1B,8CAA8C;IAC9C,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,wCAAwC;IACxC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,wCAAwC;IACxC,UAAU,EAAE,YAAY,CAAC;CAC1B;AAMD,oCAAoC;AACpC,MAAM,WAAW,MAAM;IACrB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD,+BAA+B;AAC/B,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,KAAK,EAAE,QAAQ,GAAG,MAAM,CAAC;IACzB,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD,gCAAgC;AAChC,MAAM,WAAW,QAAQ;IACvB,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD,mDAAmD;AACnD,MAAM,WAAW,MAAM;IACrB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,SAAS,EAAE,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;IACxC,iBAAiB;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,yBAAyB;IACzB,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,iCAAiC;AACjC,MAAM,WAAW,OAAO;IACtB,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;CACf"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * UI artifact type definitions for the Forge UI generation stage.
+ *
+ * Defines the output schema produced by the UI generation stage,
+ * including pages, components, layouts, forms, and navigation.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/ui-generate-stage.d.ts

@@ -0,0 +1,57 @@
+/**
+ * UI generation pipeline stage.
+ *
+ * Produces pages, components, layouts, forms, and navigation from
+ * specification workflows, architecture, API endpoints, and technology
+ * profile. Follows the same stage implementation pattern established by
+ * {@link ArchitectStage} in Task 5.1 and {@link ApiGenerateStage} in Task 5.2.
+ *
+ * In API mode, renders prompt templates, calls the LLM via
+ * {@link ApiStageExecutor}, validates the output, unpacks individual
+ * files into subdirectories, and returns the parsed {@link UiArtifact}
+ * in the stage output data.
+ *
+ * In agent mode, the pipeline runner intercepts before calling
+ * `execute()` and exports a prompt via {@link AgentStageExecutor}.
+ */
+import type { StageName } from '@hstm-labs/forge-common';
+import type { PipelineStage, PipelineStageInput, PipelineStageOutput, PipelineContext, AgentPromptContext } from '@hstm-labs/forge-core';
+/**
+ * Pipeline stage that generates the UI layer.
+ *
+ * Produces a {@link UiArtifact} containing pages, components, layouts,
+ * forms, and navigation configuration. Each element is written as a
+ * separate file artifact grouped into subdirectories.
+ *
+ * @example
+ * ```ts
+ * const stage = new UiGenerateStage();
+ * const output = await stage.execute(input, context);
+ * const ui = output.data?.ui as UiArtifact;
+ * ```
+ */
+export declare class UiGenerateStage implements PipelineStage {
+    readonly name: StageName;
+    readonly dependsOn: StageName[];
+    readonly requiresLLM = true;
+    /**
+     * Return rendered agent-mode prompt context using `ui-generate-agent.hbs`.
+     *
+     * @param input - Input from prior stages
+     * @param context - Pipeline context with config, workspace, and runId
+     * @returns Agent prompt context with rendered template and output schema
+     */
+    getAgentContext(input: PipelineStageInput, context: PipelineContext): AgentPromptContext;
+    /**
+     * Execute the UI generation stage.
+     *
+     * @param input - Input from prior stages (expects validate + architect + api-generate output)
+     * @param context - Pipeline context with config, workspace, and adapter
+     * @returns Stage output with UI artifacts and parsed UiArtifact in data
+     * @throws {ForgeError} FORGE-PIPE-003 if dependency stage output is missing
+     * @throws {ForgeError} FORGE-PIPE-001 if adapter is missing
+     * @throws {ForgeError} FORGE-GEN-003 if max retries exhausted
+     */
+    execute(input: PipelineStageInput, context: PipelineContext): Promise<PipelineStageOutput>;
+}
+//# sourceMappingURL=ui-generate-stage.d.ts.map

package/dist/ui-generate-stage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-generate-stage.d.ts","sourceRoot":"","sources":["../src/ui-generate-stage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EAEf,kBAAkB,EACnB,MAAM,uBAAuB,CAAC;AAY/B;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAgB,YAAW,aAAa;IACnD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAiB;IACzC,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,CAAiC;IAChE,QAAQ,CAAC,WAAW,QAAQ;IAE5B;;;;;;OAMG;IACH,eAAe,CACb,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,eAAe,GACvB,kBAAkB;IA+CrB;;;;;;;;;OASG;IACG,OAAO,CACX,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,mBAAmB,CAAC;CAqNhC"}

package/dist/ui-generate-stage.js

@@ -0,0 +1,232 @@
+/**
+ * UI generation pipeline stage.
+ *
+ * Produces pages, components, layouts, forms, and navigation from
+ * specification workflows, architecture, API endpoints, and technology
+ * profile. Follows the same stage implementation pattern established by
+ * {@link ArchitectStage} in Task 5.1 and {@link ApiGenerateStage} in Task 5.2.
+ *
+ * In API mode, renders prompt templates, calls the LLM via
+ * {@link ApiStageExecutor}, validates the output, unpacks individual
+ * files into subdirectories, and returns the parsed {@link UiArtifact}
+ * in the stage output data.
+ *
+ * In agent mode, the pipeline runner intercepts before calling
+ * `execute()` and exports a prompt via {@link AgentStageExecutor}.
+ */
+import { join } from 'node:path';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { ForgeError, ErrorCodes, hashContent } from '@hstm-labs/forge-common';
+import { ApiStageExecutor } from '@hstm-labs/forge-core';
+import { resolveApiStyle } from '@hstm-labs/forge-architect';
+import { loadProfile } from '@hstm-labs/forge-profiles';
+import { loadTemplate, renderTemplate } from '@hstm-labs/forge-templates';
+import { UiOutputValidator } from './validator.js';
+/**
+ * Pipeline stage that generates the UI layer.
+ *
+ * Produces a {@link UiArtifact} containing pages, components, layouts,
+ * forms, and navigation configuration. Each element is written as a
+ * separate file artifact grouped into subdirectories.
+ *
+ * @example
+ * ```ts
+ * const stage = new UiGenerateStage();
+ * const output = await stage.execute(input, context);
+ * const ui = output.data?.ui as UiArtifact;
+ * ```
+ */
+export class UiGenerateStage {
+    name = 'ui-generate';
+    dependsOn = ['architect', 'api-generate'];
+    requiresLLM = true;
+    /**
+     * Return rendered agent-mode prompt context using `ui-generate-agent.hbs`.
+     *
+     * @param input - Input from prior stages
+     * @param context - Pipeline context with config, workspace, and runId
+     * @returns Agent prompt context with rendered template and output schema
+     */
+    getAgentContext(input, context) {
+        const parsedSpec = input['validate']?.data?.['parsedSpec'];
+        const architecture = input['architect']?.data?.['architecture'];
+        const api = input['api-generate']?.data?.['api'];
+        const profile = loadProfile(context.config.profileName, context.workspace.rootDir);
+        const resolvedApiStyle = parsedSpec
+            ? resolveApiStyle(parsedSpec, profile)
+            : 'graphql';
+        const outputDir = join(context.workspace.forgeDir, 'runs', context.runId, 'stages', 'ui-generate', 'artifacts');
+        const agentTemplate = loadTemplate('ui-generate-agent', context.workspace.rootDir);
+        const rendered = renderTemplate(agentTemplate, {
+            spec: (parsedSpec ?? {}),
+            profile: profile,
+            architecture: (architecture ?? {}),
+            api: (api ?? {}),
+            stage: { resolvedApiStyle, outputDir },
+        });
+        return {
+            prompt: rendered.content,
+            outputSchema: { format: 'json' },
+        };
+    }
+    /**
+     * Execute the UI generation stage.
+     *
+     * @param input - Input from prior stages (expects validate + architect + api-generate output)
+     * @param context - Pipeline context with config, workspace, and adapter
+     * @returns Stage output with UI artifacts and parsed UiArtifact in data
+     * @throws {ForgeError} FORGE-PIPE-003 if dependency stage output is missing
+     * @throws {ForgeError} FORGE-PIPE-001 if adapter is missing
+     * @throws {ForgeError} FORGE-GEN-003 if max retries exhausted
+     */
+    async execute(input, context) {
+        // 1. Get parsed spec from validate stage output
+        const validateOutput = input['validate'];
+        if (validateOutput === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.DEPENDENCY_UNMET, "UI generate stage requires 'validate' stage output, but it was not found. " +
+                'Ensure the validate stage runs before the ui-generate stage.');
+        }
+        const parsedSpec = validateOutput.data?.['parsedSpec'];
+        if (parsedSpec === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.STAGE_FAILURE, 'Validate stage did not produce a parsed specification in its output data. ' +
+                'Ensure the validate stage includes parsedSpec in its data output.');
+        }
+        // 2. Get architecture from architect stage output
+        const architectOutput = input['architect'];
+        if (architectOutput === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.DEPENDENCY_UNMET, "UI generate stage requires 'architect' stage output, but it was not found. " +
+                'Ensure the architect stage runs before the ui-generate stage.');
+        }
+        const architecture = architectOutput.data?.['architecture'];
+        if (architecture === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.STAGE_FAILURE, 'Architect stage did not produce an architecture in its output data. ' +
+                'Ensure the architect stage includes architecture in its data output.');
+        }
+        // 3. Get API artifact from api-generate stage output
+        const apiGenerateOutput = input['api-generate'];
+        if (apiGenerateOutput === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.DEPENDENCY_UNMET, "UI generate stage requires 'api-generate' stage output, but it was not found. " +
+                'Ensure the api-generate stage runs before the ui-generate stage.');
+        }
+        const api = apiGenerateOutput.data?.['api'];
+        if (api === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.STAGE_FAILURE, 'API generate stage did not produce an API artifact in its output data. ' +
+                'Ensure the api-generate stage includes api in its data output.');
+        }
+        // 4. Load profile, resolve API style
+        const profile = loadProfile(context.config.profileName, context.workspace.rootDir);
+        const resolvedApiStyle = resolveApiStyle(parsedSpec, profile);
+        // 5. Compute output directory
+        const outputDir = join(context.workspace.forgeDir, 'runs', context.runId, 'stages', 'ui-generate', 'artifacts');
+        // 6. Load and render templates
+        const systemTemplate = loadTemplate('ui-generate-system', context.workspace.rootDir);
+        const userTemplate = loadTemplate('ui-generate-user', context.workspace.rootDir);
+        const templateContext = {
+            spec: parsedSpec,
+            profile: profile,
+            architecture: architecture,
+            api: api,
+            stage: {
+                resolvedApiStyle,
+                outputDir,
+            },
+        };
+        const systemPrompt = renderTemplate(systemTemplate, templateContext);
+        const userPrompt = renderTemplate(userTemplate, templateContext);
+        // 7. Execute via API mode StageExecutor
+        if (context.adapter === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.STAGE_FAILURE, 'UI generate stage requires an LLM adapter in API mode, but none was provided. ' +
+                'Configure an LLM provider in forge.config.json or use agent mode.');
+        }
+        const entityNames = architecture.dataModel.map((e) => e.name);
+        const validator = new UiOutputValidator(entityNames);
+        const executor = new ApiStageExecutor({
+            adapter: context.adapter,
+            validator,
+            retryPolicy: {
+                maxRetries: 3,
+                backoffMs: 1000,
+                includeErrorInRetry: true,
+            },
+        });
+        const result = await executor.execute({
+            prompt: userPrompt.content,
+            systemPrompt: systemPrompt.content,
+            stageName: 'ui-generate',
+            outputDir,
+            runId: context.runId,
+            mode: 'api',
+            outputSchema: { format: 'json' },
+        });
+        // 8. Parse UiArtifact from LLM output
+        const rawContent = result.artifacts[0]?.content ?? '';
+        const uiArtifact = JSON.parse(rawContent);
+        // 9. Write individual files to artifacts directory in subdirectories
+        const artifacts = [];
+        // Pages
+        const pagesDir = join(outputDir, 'pages');
+        mkdirSync(pagesDir, { recursive: true });
+        for (const page of uiArtifact.pages) {
+            writeFileSync(join(pagesDir, page.fileName), page.content, 'utf-8');
+            artifacts.push({
+                filePath: join('pages', page.fileName),
+                content: page.content,
+                contentHash: hashContent(page.content),
+                sizeBytes: Buffer.byteLength(page.content, 'utf-8'),
+            });
+        }
+        // Components
+        const componentsDir = join(outputDir, 'components');
+        mkdirSync(componentsDir, { recursive: true });
+        for (const component of uiArtifact.components) {
+            writeFileSync(join(componentsDir, component.fileName), component.content, 'utf-8');
+            artifacts.push({
+                filePath: join('components', component.fileName),
+                content: component.content,
+                contentHash: hashContent(component.content),
+                sizeBytes: Buffer.byteLength(component.content, 'utf-8'),
+            });
+        }
+        // Layouts
+        const layoutsDir = join(outputDir, 'layouts');
+        mkdirSync(layoutsDir, { recursive: true });
+        for (const layout of uiArtifact.layouts) {
+            writeFileSync(join(layoutsDir, layout.fileName), layout.content, 'utf-8');
+            artifacts.push({
+                filePath: join('layouts', layout.fileName),
+                content: layout.content,
+                contentHash: hashContent(layout.content),
+                sizeBytes: Buffer.byteLength(layout.content, 'utf-8'),
+            });
+        }
+        // Forms
+        const formsDir = join(outputDir, 'forms');
+        mkdirSync(formsDir, { recursive: true });
+        for (const form of uiArtifact.forms) {
+            writeFileSync(join(formsDir, form.fileName), form.content, 'utf-8');
+            artifacts.push({
+                filePath: join('forms', form.fileName),
+                content: form.content,
+                contentHash: hashContent(form.content),
+                sizeBytes: Buffer.byteLength(form.content, 'utf-8'),
+            });
+        }
+        // Navigation
+        mkdirSync(outputDir, { recursive: true });
+        writeFileSync(join(outputDir, uiArtifact.navigation.fileName), uiArtifact.navigation.content, 'utf-8');
+        artifacts.push({
+            filePath: uiArtifact.navigation.fileName,
+            content: uiArtifact.navigation.content,
+            contentHash: hashContent(uiArtifact.navigation.content),
+            sizeBytes: Buffer.byteLength(uiArtifact.navigation.content, 'utf-8'),
+        });
+        // 10. Return PipelineStageOutput with all artifacts and data
+        return {
+            artifacts,
+            data: {
+                ui: uiArtifact,
+            },
+        };
+    }
+}
+//# sourceMappingURL=ui-generate-stage.js.map

package/dist/ui-generate-stage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-generate-stage.js","sourceRoot":"","sources":["../src/ui-generate-stage.ts"],"names":[],"mappings":"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"}

package/dist/validator.d.ts

@@ -0,0 +1,41 @@
+/**
+ * UI output validator for the Forge UI generation stage.
+ *
+ * Validates LLM-generated UI output against the
+ * {@link UiArtifact} schema with structural and semantic checks.
+ */
+import type { OutputValidator, OutputSchema, ValidationResult } from '@hstm-labs/forge-core';
+/**
+ * Validator for UI generation stage output.
+ *
+ * Performs the following checks:
+ * 1. JSON parse validation
+ * 2. Required top-level keys
+ * 3. Non-empty pages with required fields
+ * 4. Entity coverage (every entity has at least one page)
+ * 5. Form coverage (every entity has create and edit forms)
+ * 6. Navigation routes non-empty and cover all pages
+ * 7. Non-empty layouts (at least one)
+ *
+ * @example
+ * ```ts
+ * const validator = new UiOutputValidator(['User', 'Post']);
+ * const result = validator.validate(llmOutput, { format: 'json' });
+ * ```
+ */
+export declare class UiOutputValidator implements OutputValidator {
+    private readonly entityNames;
+    /**
+     * @param entityNames - Entity names from architecture data model for coverage checks
+     */
+    constructor(entityNames: string[]);
+    /**
+     * Validate UI output against the UiArtifact schema.
+     *
+     * @param output - Raw LLM output text
+     * @param _schema - Output schema (format expected to be 'json')
+     * @returns Validation result with descriptive errors
+     */
+    validate(output: string, _schema: OutputSchema): ValidationResult;
+}
+//# sourceMappingURL=validator.d.ts.map

package/dist/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EAEjB,MAAM,uBAAuB,CAAC;AAmB/B;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,iBAAkB,YAAW,eAAe;IACvD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAW;IAEvC;;OAEG;gBACS,WAAW,EAAE,MAAM,EAAE;IAIjC;;;;;;OAMG;IAEH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,gBAAgB;CAkLlE"}

package/dist/validator.js

@@ -0,0 +1,220 @@
+/**
+ * UI output validator for the Forge UI generation stage.
+ *
+ * Validates LLM-generated UI output against the
+ * {@link UiArtifact} schema with structural and semantic checks.
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const REQUIRED_TOP_LEVEL_KEYS = [
+    'framework',
+    'pages',
+    'components',
+    'layouts',
+    'forms',
+    'navigation',
+];
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Validator for UI generation stage output.
+ *
+ * Performs the following checks:
+ * 1. JSON parse validation
+ * 2. Required top-level keys
+ * 3. Non-empty pages with required fields
+ * 4. Entity coverage (every entity has at least one page)
+ * 5. Form coverage (every entity has create and edit forms)
+ * 6. Navigation routes non-empty and cover all pages
+ * 7. Non-empty layouts (at least one)
+ *
+ * @example
+ * ```ts
+ * const validator = new UiOutputValidator(['User', 'Post']);
+ * const result = validator.validate(llmOutput, { format: 'json' });
+ * ```
+ */
+export class UiOutputValidator {
+    entityNames;
+    /**
+     * @param entityNames - Entity names from architecture data model for coverage checks
+     */
+    constructor(entityNames) {
+        this.entityNames = entityNames;
+    }
+    /**
+     * Validate UI output against the UiArtifact schema.
+     *
+     * @param output - Raw LLM output text
+     * @param _schema - Output schema (format expected to be 'json')
+     * @returns Validation result with descriptive errors
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    validate(output, _schema) {
+        const errors = [];
+        // 1. Parse as JSON
+        let parsed;
+        try {
+            parsed = JSON.parse(output);
+        }
+        catch {
+            errors.push({
+                message: 'UI output is not valid JSON. Ensure the LLM produces only raw JSON without markdown fences or explanatory text.',
+                severity: 'error',
+            });
+            return { valid: false, errors };
+        }
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            errors.push({
+                message: 'UI output must be a JSON object, not an array or primitive.',
+                severity: 'error',
+            });
+            return { valid: false, errors };
+        }
+        const obj = parsed;
+        // 2. Verify required top-level keys
+        for (const key of REQUIRED_TOP_LEVEL_KEYS) {
+            if (!(key in obj)) {
+                errors.push({
+                    message: `Missing required top-level key: '${key}'.`,
+                    path: key,
+                    severity: 'error',
+                });
+            }
+        }
+        if (errors.length > 0) {
+            return { valid: false, errors };
+        }
+        // 3. Verify pages is non-empty array with required fields
+        const pages = obj['pages'];
+        if (!Array.isArray(pages) || pages.length === 0) {
+            errors.push({
+                message: "Key 'pages' must be a non-empty array of page definitions.",
+                path: 'pages',
+                severity: 'error',
+            });
+        }
+        else {
+            for (let i = 0; i < pages.length; i++) {
+                const page = pages[i];
+                if (page === undefined || typeof page !== 'object' || page === null) {
+                    errors.push({
+                        message: `pages[${String(i)}] is not a valid object.`,
+                        path: `pages[${String(i)}]`,
+                        severity: 'error',
+                    });
+                    continue;
+                }
+                for (const field of ['name', 'route', 'fileName', 'content']) {
+                    if (typeof page[field] !== 'string' || page[field].length === 0) {
+                        errors.push({
+                            message: `pages[${String(i)}] is missing required field '${field}'.`,
+                            path: `pages[${String(i)}].${field}`,
+                            severity: 'error',
+                        });
+                    }
+                }
+            }
+        }
+        // 4. Entity coverage — every entity has at least one page
+        if (Array.isArray(pages) && pages.length > 0) {
+            const pageEntities = new Set();
+            for (const page of pages) {
+                // Check page.entity field
+                if (typeof page['entity'] === 'string' && page['entity'].length > 0) {
+                    pageEntities.add(page['entity'].toLowerCase());
+                }
+                // Also check page name containing entity name
+                if (typeof page['name'] === 'string') {
+                    const pageName = page['name'].toLowerCase();
+                    for (const entityName of this.entityNames) {
+                        if (pageName.includes(entityName.toLowerCase())) {
+                            pageEntities.add(entityName.toLowerCase());
+                        }
+                    }
+                }
+            }
+            for (const entityName of this.entityNames) {
+                if (!pageEntities.has(entityName.toLowerCase())) {
+                    errors.push({
+                        message: `Entity '${entityName}' has no corresponding page. Every entity must have at least one page.`,
+                        path: 'pages',
+                        severity: 'error',
+                    });
+                }
+            }
+        }
+        // 5. Form coverage — every entity has create and edit forms
+        const forms = obj['forms'];
+        if (!Array.isArray(forms) || forms.length === 0) {
+            errors.push({
+                message: "Key 'forms' must be a non-empty array of form definitions.",
+                path: 'forms',
+                severity: 'error',
+            });
+        }
+        else {
+            const entityFormOps = new Map();
+            for (const form of forms) {
+                const entity = typeof form['entity'] === 'string' ? form['entity'].toLowerCase() : '';
+                const operation = typeof form['operation'] === 'string' ? form['operation'] : '';
+                if (entity.length > 0 && operation.length > 0) {
+                    if (!entityFormOps.has(entity)) {
+                        entityFormOps.set(entity, new Set());
+                    }
+                    entityFormOps.get(entity).add(operation);
+                }
+            }
+            for (const entityName of this.entityNames) {
+                const ops = entityFormOps.get(entityName.toLowerCase());
+                if (ops === undefined || !ops.has('create')) {
+                    errors.push({
+                        message: `Entity '${entityName}' is missing a 'create' form.`,
+                        path: 'forms',
+                        severity: 'error',
+                    });
+                }
+                if (ops === undefined || !ops.has('edit')) {
+                    errors.push({
+                        message: `Entity '${entityName}' is missing an 'edit' form.`,
+                        path: 'forms',
+                        severity: 'error',
+                    });
+                }
+            }
+        }
+        // 6. Navigation routes non-empty and cover all pages
+        const navigation = obj['navigation'];
+        if (typeof navigation !== 'object' || navigation === null || Array.isArray(navigation)) {
+            errors.push({
+                message: "Key 'navigation' must be an object with routes and content.",
+                path: 'navigation',
+                severity: 'error',
+            });
+        }
+        else {
+            const nav = navigation;
+            const routes = nav['routes'];
+            if (!Array.isArray(routes) || routes.length === 0) {
+                errors.push({
+                    message: "Navigation 'routes' must be a non-empty array.",
+                    path: 'navigation.routes',
+                    severity: 'error',
+                });
+            }
+        }
+        // 7. Verify layouts is non-empty
+        const layouts = obj['layouts'];
+        if (!Array.isArray(layouts) || layouts.length === 0) {
+            errors.push({
+                message: "Key 'layouts' must be a non-empty array — at least one layout is required.",
+                path: 'layouts',
+                severity: 'error',
+            });
+        }
+        return { valid: errors.length === 0, errors };
+    }
+}
+//# sourceMappingURL=validator.js.map

package/dist/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@hstm-labs/forge-apps-generator",
+  "version": "0.1.11",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@hstm-labs/forge-common": "0.1.11",
+    "@hstm-labs/forge-core": "0.1.11",
+    "@hstm-labs/forge-architect": "0.1.11",
+    "@hstm-labs/forge-services-generator": "0.1.11",
+    "@hstm-labs/forge-spec-parser": "0.1.11",
+    "@hstm-labs/forge-profiles": "0.1.11",
+    "@hstm-labs/forge-templates": "0.1.11"
+  }
+}