@worktif/runtime 0.3.0-edge.0

package/out/dist/src/bin/services/purenow-runtime-deployment.strategy.d.ts

@@ -0,0 +1,37 @@
+import { DeploymentStrategy, PurenowCliContext } from '@worktif/purenow/bin';
+import { PurenowRuntimeStacksDeployService } from './purenow-runtime-stacks-deploy.service';
+/**
+ * Represents the runtime context for the Purenow CLI, extending the base Purenow CLI context
+ * with additional properties specific to the runtime environment.
+ */
+export interface PurenowRuntimeCliContext extends PurenowCliContext {
+    stacksDeployService: PurenowRuntimeStacksDeployService;
+}
+/**
+ * Runtime deployment strategy that implements Runtime Target deployment
+ *
+ * This strategy extends purenow's two-stack deployment to support three stacks:
+ * 1. Infrastructure Stack (existing)
+ * 2. Runtime Stack (existing)
+ * 3. Additional Runtime Stack (new)
+ */
+export declare class RuntimeDeploymentStrategy implements DeploymentStrategy {
+    readonly role = "deployment";
+    readonly name = "runtime-purenow-runtime-stacks";
+    /**
+     * Pre-deployment validation for runtime-specific requirements
+     */
+    validateDeployment<T extends PurenowCliContext = PurenowCliContext>(context: T): Promise<boolean>;
+    /**
+     * Execute Runtime Target deployment instead of two stacks
+     */
+    executeDeployment<T extends PurenowCliContext = PurenowCliContext>(context: T, config: unknown): Promise<void>;
+    /**
+     * Post-deployment actions for runtime-specific tasks
+     */
+    postDeployment(result: {
+        success: boolean;
+        error?: unknown;
+    }): Promise<void>;
+}
+//# sourceMappingURL=purenow-runtime-deployment.strategy.d.ts.map

package/out/dist/src/bin/services/purenow-runtime-stacks-deploy.service.d.ts

@@ -0,0 +1,58 @@
+import { PurenowInfraResourceOptions, PurenowInfraResources } from '@worktif/purenow/infra';
+import { type DeploymentOutputs, StacksDeployOptions, StacksDeployService } from '@worktif/purenow/bin';
+import { PurenowRuntimeStacksDeployResult } from './purenow-runtime-stacks-deploy.service.types';
+export declare class PurenowRuntimeStacksDeployService extends StacksDeployService implements PurenowInfraResources {
+    protected readonly cwd: string;
+    protected readonly DEFAULT_CDK_DIR = "cdk";
+    /**
+     * Creates a new TwoStackDeployService instance.
+     *
+     * @param cwd - Current working directory (project root)
+     */
+    constructor(cwd?: string);
+    /**
+     * Executes first deployment workflow: deploy Infra → read outputs → deploy Runtime.
+     *
+     * @param options - Deployment options
+     * @param startTime - Deployment start timestamp
+     * @returns Promise that resolves to deployment result
+     * @throws {DeploymentError} If Infra or Runtime deployment fails
+     *
+     * @todo: complete extensible deployment approach with duration metric attendance
+     *
+     * @private
+     */
+    protected executeDeploy<T extends PurenowRuntimeStacksDeployResult = PurenowRuntimeStacksDeployResult>(options: StacksDeployOptions, startTime: number): Promise<T>;
+    /**
+     * Parses deployment outputs from CDK outputs file.
+     *
+     * @param stackName - Name of the CloudFormation stack
+     * @returns Deployment outputs map
+     *
+     * @important: OPTIMISE THIS SOLUTION
+     *
+     * @private
+     * @param outputsPath
+     */
+    protected parseStackOutputs(stackName: string, outputsPath: string): DeploymentOutputs;
+    /**
+     * Generates a signature for the provided region by extracting the first character of each segment in the region string, delimited by hyphens.
+     *
+     * @param {string} region - The region string to generate the signature from. It is expected to be a hyphen-separated string.
+     * @return {string} The generated region signature, formed by concatenating the first character of each valid segment. Returns an empty string if the input is invalid or empty.
+     */
+    protected getRegionSignature(region: string): string;
+    /**
+     * Generates a resource name by concatenating service name, resource name,
+     * simplified region, and stage with hyphens as separators.
+     *
+     * @param {Object} params - An object containing the required parameters.
+     * @param {string} params.name - The name of the resource.
+     * @param {string} params.serviceName - The name of the service associated with the resource.
+     * @param {string} params.regionSimplified - The simplified region identifier.
+     * @param {string} params.stage - The deployment stage of the resource.
+     * @returns {string} The concatenated resource name.
+     */
+    resourceName({ name, serviceName, stage, region }: PurenowInfraResourceOptions): string;
+}
+//# sourceMappingURL=purenow-runtime-stacks-deploy.service.d.ts.map

package/out/dist/src/bin/services/purenow-runtime-stacks-deploy.service.types.d.ts

@@ -0,0 +1,18 @@
+import 'reflect-metadata';
+import { type DeploymentResult, StacksDeployResult, DeploymentOutputs } from '@worktif/purenow/bin';
+/**
+ * Represents the result of deploying runtime stacks in the Purenow system.
+ * This type extends the StacksDeployResult, adding a specific result for the runtime stack deployment.
+ *
+ * Properties:
+ * - runtimeStack: Provides the deployment result specific to the runtime stack, containing details and status of the runtime stack deployment process.
+ *
+ * Use this type to encapsulate and manage results related to both general stack deployments and specific runtime stack deployments.
+ */
+export type PurenowRuntimeStacksDeployResult = StacksDeployResult & {
+    runtimeStack: DeploymentResult;
+};
+export type PurenowRuntimeDeploymentOutputs = DeploymentOutputs & {
+    lambdaArnList: string[];
+};
+//# sourceMappingURL=purenow-runtime-stacks-deploy.service.types.d.ts.map

package/out/dist/src/bin/services/runtime-web-cli-extensions.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runtime-web-cli-extensions.d.ts.map

package/out/dist/src/bin/services/template.service.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Options for scaffolding a new project
+ */
+export interface ScaffoldOptions {
+    /** Project name */
+    projectName: string;
+    /** Force overwrite existing files */
+    force: boolean;
+}
+/**
+ * Template variable substitution context
+ */
+export interface TemplateContext {
+    projectName: string;
+    [key: string]: string;
+}
+/**
+ * Service for project scaffolding and template management
+ */
+export declare class TemplateService {
+    private cwd;
+    private readonly templatesDir;
+    constructor(cwd?: string);
+    /**
+     * Scaffold a new project from a template
+     */
+    scaffold(templateName: string, targetDir: string, options: ScaffoldOptions, coreDir?: string): Promise<void>;
+    /**
+     * Generate purenow.config.ts file
+     */
+    generateConfig(targetDir: string, projectName: string): Promise<void>;
+    /**
+     * Generate tsconfig.json file
+     */
+    generateTsConfig(targetDir: string): Promise<void>;
+    /**
+     * Validate target directory
+     */
+    private validateTargetDirectory;
+    /**
+     * Check if CDK directory already exists
+     */
+    cdkDirectoryExists(cwd?: string): boolean;
+    /**
+     * Copy template files recursively with variable substitution
+     */
+    private copyTemplateFiles;
+    /**
+     * Substitute template variables in content
+     */
+    private substituteVariables;
+}
+//# sourceMappingURL=template.service.d.ts.map

package/out/dist/src/bin/services/utils/index.d.ts

@@ -0,0 +1,2 @@
+export declare function buildStaticHtml(shouldExit?: boolean): void;
+//# sourceMappingURL=index.d.ts.map

package/out/dist/src/bin/utils/errors.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Base error class for all Runtime CLI errors
+ * Follows purenow error patterns without emoji
+ */
+export declare class RuntimeCliError extends Error {
+    readonly code: string;
+    readonly hint?: string | undefined;
+    constructor(message: string, code: string, hint?: string | undefined);
+}
+/**
+ * Error thrown when runtime configuration is invalid or missing
+ * Extends purenow ConfigError pattern
+ */
+export declare class RuntimeConfigError extends RuntimeCliError {
+    constructor(message: string, hint?: string);
+}
+/**
+ * Error thrown when runtime build operations fail
+ * Extends purenow BuildError pattern
+ */
+export declare class RuntimeBuildError extends RuntimeCliError {
+    constructor(message: string, hint?: string);
+}
+/**
+ * Error thrown when runtime deployment operations fail
+ * Extends purenow DeploymentError pattern
+ */
+export declare class RuntimeDeploymentError extends RuntimeCliError {
+    constructor(message: string, hint?: string);
+}
+/**
+ * Error thrown when runtime validation checks fail
+ * Extends purenow ValidationError pattern
+ */
+export declare class RuntimeValidationError extends RuntimeCliError {
+    constructor(message: string, hint?: string);
+}
+/**
+ * Friendly error formatter for runtime workspace
+ * Follows purenow FriendlyErrorFormatter pattern without emoji
+ */
+export declare class RuntimeFriendlyErrorFormatter {
+    /**
+     * Format error as human-readable message without emoji
+     */
+    formatError(error: Error, verbose?: boolean): string;
+    /**
+     * Format validation error without emoji
+     */
+    formatValidationError(fieldName: string, message: string, verbose?: boolean): string;
+    /**
+     * Format deployment error without emoji
+     */
+    formatDeploymentError(stackName: string, operation: string, message: string, verbose?: boolean): string;
+}
+/**
+ * Structured logger for runtime workspace
+ * Follows purenow logging patterns without emoji
+ */
+export declare class RuntimeStructuredLogger {
+    private verbose;
+    constructor(verbose?: boolean);
+    info(message: string, metadata?: Record<string, any>): void;
+    warn(message: string, metadata?: Record<string, any>): void;
+    error(message: string, metadata?: Record<string, any>): void;
+    debug(message: string, metadata?: Record<string, any>): void;
+}
+//# sourceMappingURL=errors.d.ts.map

package/out/dist/src/lib/runtime-web/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Runtime Web Core - Library (Isomorphic/Browser)
+ *
+ * **ARCHITECTURE NOTE**: This module contains browser-safe code that:
+ * - Runs in browser environment (client-side)
+ * - Uses browser APIs (window, document, hydrateRoot)
+ * - Must be isomorphic-safe (no Node.js APIs)
+ * - NEVER runs in Lambda
+ * - Bundled into browser builds
+ *
+ * **Exports**:
+ * - BrowserPipeline: Client-side React hydration and routing
+ */
+export * from './pipelines';
+export * from './types';
+export * from './pureweb';
+//# sourceMappingURL=index.d.ts.map

package/out/dist/src/lib/runtime-web/pipelines/browser-pipeline.d.ts

@@ -0,0 +1,110 @@
+import type { BrowserMetadata, RuntimeWebConfig } from '../../runtime-web/types';
+/**
+ * Browser execution pipeline for Runtime Target Core.
+ *
+ * @todo: ordinate this class to infra or core cause we have Node.js responsibility
+ *      ---- OR –> REMOVE LOGGER
+ *
+ * **ARCHITECTURE NOTE**: This file is in `src/lib/` because it:
+ * - Uses browser-only APIs (window, document, hydrateRoot)
+ * - Runs ONLY in browser environment
+ * - Must be isomorphic-safe (no Node.js APIs)
+ * - NEVER runs in Lambda
+ *
+ * Handles client-side hydration of React applications with pre-loaded data
+ * from server-side rendering. Sets up client-side routing and HTTP client
+ * for post-hydration API calls to Lambda endpoints.
+ *
+ * **Execution Flow**:
+ * 1. Hydrate React app with existing PurenowRouter
+ * 2. Call config.app({ router }) to get React element
+ * 3. Initialize client-side navigation
+ * 4. Set up HTTP client for Lambda endpoint calls
+ *
+ * **Requirements**: REQ-06, REQ-12
+ */
+export declare class BrowserPipeline {
+    /**
+     * Execute browser pipeline for client-side hydration.
+     *
+     * Hydrates the React application with pre-loaded data from SSR and sets up
+     * client-side routing. Uses React hydration (not render) to match the
+     * server-rendered HTML exactly.
+     *
+     * @param config - Purenow configuration with app factory and router
+     * @param context - Browser environment context with metadata
+     *
+     * @example
+     * ```typescript
+     * const pipeline = new BrowserPipeline();
+     * await pipeline.execute(config, {
+     *   type: 'browser',
+     *   metadata: {
+     *     userAgent: navigator.userAgent,
+     *     url: window.location.href,
+     *     viewport: { width: window.innerWidth, height: window.innerHeight }
+     *   }
+     * });
+     * ```
+     */
+    execute(config: RuntimeWebConfig, context: {
+        type: 'browser';
+        metadata: BrowserMetadata;
+    }): Promise<void>;
+    /**
+     * Create browser router from PurenowRouter configuration.
+     *
+     * Uses the existing PurenowRouter to get routes and creates a React Router
+     * browser router for client-side navigation.
+     *
+     * @param config - Purenow configuration
+     * @returns Browser router instance
+     * @private
+     */
+    private createBrowserRouter;
+    /**
+     * Create React element from app factory function.
+     *
+     * Calls the user's app factory function with the router dependency
+     * to get the root React element for the application.
+     *
+     * @param config - Purenow configuration
+     * @returns Root React element
+     * @private
+     */
+    private createAppElement;
+    /**
+     * Hydrate the React application in the browser.
+     *
+     * Uses React's hydrateRoot to hydrate the server-rendered HTML with
+     * the client-side React application. This ensures the client matches
+     * the server exactly to avoid hydration mismatches.
+     *
+     * @param routerProvider - Router provider element to hydrate
+     * @private
+     */
+    private hydrateApplication;
+    /**
+     * Set up HTTP client for Lambda endpoint calls.
+     *
+     * Configures the HTTP client for making API calls to Lambda endpoints
+     * after hydration. This is used for post-hydration interactions that
+     * require server-side data.
+     *
+     * @param config - Purenow configuration
+     * @private
+     */
+    private setupHttpClient;
+    /**
+     * Get API base URL based on deployment stage.
+     *
+     * Determines the appropriate API base URL for making HTTP requests
+     * to Lambda endpoints based on the deployment stage.
+     *
+     * @param stage - Deployment stage
+     * @returns API base URL
+     * @private
+     */
+    private getApiBaseUrl;
+}
+//# sourceMappingURL=browser-pipeline.d.ts.map

package/out/dist/src/lib/runtime-web/pipelines/index.d.ts

@@ -0,0 +1,2 @@
+export { BrowserPipeline } from './browser-pipeline';
+//# sourceMappingURL=index.d.ts.map

package/out/dist/src/lib/runtime-web/pureweb.d.ts

@@ -0,0 +1,65 @@
+import type { RuntimeWebConfig } from './types';
+/**
+ * Error thrown when configuration validation fails.
+ * Follows purenow error patterns without emoji.
+ */
+export declare class ConfigValidationError extends Error {
+    /** Array of validation error messages */
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+/**
+ * Error thrown when environment detection fails.
+ * Follows purenow error patterns without emoji.
+ */
+export declare class EnvironmentDetectionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Unified entry point for Runtime Target Core.
+ *
+ * This function provides a single API that works across all execution contexts:
+ * - **Browser**: Hydrates React application with client-side routing
+ * - **Lambda**: Executes server-side rendering and business logic with DI
+ * - **CDK**: Synthesizes CloudFormation infrastructure templates
+ *
+ * The function automatically detects the runtime environment and routes
+ * execution to the appropriate pipeline without user intervention.
+ *
+ * **Note**: For Lambda and CDK contexts, use the server-side entry point
+ * from `@core/runtime-web` instead. This browser-compatible version
+ * only supports browser hydration.
+ *
+ * @param config - Unified configuration for all contexts
+ * @returns Promise that resolves when execution completes
+ * @throws ConfigValidationError if configuration is invalid
+ * @throws EnvironmentDetectionError if environment cannot be detected
+ * @throws Error if execution fails
+ *
+ * @example
+ * ```typescript
+ * import { purenow } from '@worktif/purenow/runtime-web';
+ * import { PurenowRouter } from '@worktif/purenow';
+ *
+ * purenow({
+ *   app: ({ router }) => <App router={router} />,
+ *   router: new PurenowRouter({ routes, defaults: {} }),
+ *   serviceName: 'my-app',
+ *   stage: 'dev',
+ *   register: {
+ *     payments: {
+ *       ties: [PaymentsTies],
+ *       lambdas: [chargeHandler, refundHandler]
+ *     }
+ *   },
+ *   infra: {
+ *     env: { account: '123456789012', region: 'us-east-1' },
+ *     stage: 'dev',
+ *     reactEntry: './src/index.tsx',
+ *     apiMode: 'apiGateway'
+ *   }
+ * });
+ * ```
+ */
+export declare function pureweb(config: RuntimeWebConfig): void;
+//# sourceMappingURL=pureweb.d.ts.map