@worktif/runtime 0.3.0-edge.0

package/LICENSE

@@ -0,0 +1,101 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+Licensed Work: Work Target Insight Function (Work TIF Platform, including all associated components)
+Licensor: Raman Marozau <raman@worktif.com>
+Re-licensed from: Business Source License 1.1 (BUSL-1.1) on 2025-09-22
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.
+
+Additional Notices:
+For attribution notices and full license texts of included third-party dependencies,
+see THIRD_PARTY_LICENSES.txt.

package/README.md

@@ -0,0 +1,495 @@
+# @worktif/runtime
+
+[![npm version](https://img.shields.io/npm/v/@worktif/runtime.svg)](https://www.npmjs.com/package/@worktif/runtime)
+![Node Support](https://img.shields.io/badge/node-%3E%3D18.0.0-43853d)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.8.3-3178c6)
+![License](https://img.shields.io/badge/license-Elastic--2.0-blue.svg)
+
+---
+
+## Overview
+
+**@worktif/runtime** is an extension package that builds upon the [@worktif/purenow](https://www.npmjs.com/package/@worktif/purenow) framework, adding three-stack deployment capabilities and enhanced development tools while preserving ALL existing purenow functionality.
+
+**Extension Relationship:** This package extends @worktif/purenow using its established architectural patterns (CLI inheritance, deployment strategies, dependency injection) rather than replacing any functionality.
+
+**What @worktif/purenow provides (included automatically):**
+- **Complete SSR Framework** - Server-side rendering with React Router v7
+- **AWS Infrastructure** - CloudFront CDN, API Gateway, Lambda, S3 caching
+- **SEO Management** - DynamoDB-based metadata with CLI tools
+- **Two-Stack Deployment** - Infrastructure and Runtime stacks
+- **Development Server** - Local development with HMR
+- **CLI Tools** - Complete command-line interface for all operations
+
+**What @worktif/runtime adds:**
+- **Three-Stack Architecture** - Extends two-stack deployment with additional runtime stack
+- **Enhanced CLI** - Additional commands using purenow's extensible CLI architecture
+- **Runtime Extensions** - Additional development and deployment capabilities
+- **Extended Configuration** - Additional options that merge with purenow config
+
+### Key Features
+
+**All @worktif/purenow Features (Preserved):**
+- **Server-Side Rendering** - React Router v7 with Lambda execution
+- **Multi-Layer Caching** - CloudFront edge + S3 storage caching
+- **SEO Management** - DynamoDB metadata with sync/clear commands
+- **CDK Infrastructure** - Complete AWS stack deployment
+- **Development Server** - Local development with hot module replacement
+- **CLI Tools** - Full command-line interface (deploy, destroy, cache-clear, seo, etc.)
+
+**Additional Runtime Extensions:**
+- **Three-Stack Deployment** - Extends purenow's two-stack architecture with third stack
+- **Extended CLI Commands** - Additional commands integrated via purenow's extensible CLI
+- **Runtime Configuration** - Extended config options that merge with purenow settings
+- **Enhanced Development Tools** - Additional debugging and diagnostic capabilities
+
+### Architecture
+
+**Extension Relationship:**
+```
+@worktif/runtime (Extension Package)
+        ↓ extends via dependency
+@worktif/purenow (Base Framework)
+        ↓ provides complete infrastructure
+CloudFront → API Gateway → Lambda (SSR) → S3 (Cache)
+                                       ↓
+                                   DynamoDB (SEO)
+```
+
+**Deployment Architecture:**
+```
+Runtime Three-Stack Deployment:
+├── Infrastructure Stack (from purenow)
+├── Runtime Stack (from purenow) 
+└── Additional Runtime Stack (added by runtime)
+```
+
+This package extends purenow's two-stack deployment to three stacks while preserving all existing functionality.
+
+---
+
+## Installation
+
+### Extension Relationship
+
+**@worktif/runtime extends @worktif/purenow** - When you install runtime, you automatically get the complete purenow framework plus additional three-stack deployment capabilities.
+
+### New Projects (Recommended)
+
+Initialize a new project with runtime extensions:
+
+```bash
+npx @worktif/runtime init
+```
+
+This creates a complete project structure with:
+- All @worktif/purenow functionality (SSR, CDK, CLI, caching, SEO)
+- Three-stack deployment architecture
+- Extended CLI commands
+- Enhanced development capabilities
+
+### Existing Purenow Projects
+
+Add runtime extensions to your existing purenow project:
+
+```bash
+npm install @worktif/runtime
+```
+
+**Migration:** Your existing purenow commands and configuration continue to work unchanged. Runtime adds new capabilities without breaking existing functionality.
+
+### Prerequisites
+
+- Node.js >= 18
+- AWS Account with CLI configured
+- AWS CDK CLI installed globally: `npm install -g aws-cdk`
+
+**Dependency Structure:** Installing @worktif/runtime automatically includes @worktif/purenow as a dependency, ensuring you have the complete base framework plus runtime extensions.
+
+---
+
+## Quick Start
+
+Get your application running with runtime extensions in 3 minutes:
+
+### 1. Initialize Project
+
+```bash
+mkdir my-app && cd my-app
+npx @worktif/runtime init
+```
+
+You'll be prompted to set up AWS CDK infrastructure with three-stack deployment. Choose **Yes** to have everything configured automatically.
+
+### 2. Start Development
+
+```bash
+# Start development server (from purenow base framework)
+npx purenow dev
+```
+
+Your app runs at `http://localhost:3000` with all purenow features (SSR, HMR, caching) plus runtime extensions.
+
+### 3. Deploy to AWS
+
+```bash
+# Configure AWS credentials (if not already done)
+aws configure
+
+# Deploy with three-stack architecture (runtime extension)
+npx purenow deploy --stage dev
+```
+
+Your application is now live on CloudFront with three-stack deployment architecture!
+
+**Clean Up Resources:**
+```bash
+# When you're done, destroy all stacks to avoid AWS charges
+npx purenow destroy --stage dev
+```
+
+**Next Steps:**
+- Use all [Purenow CLI Commands](https://www.npmjs.com/package/@worktif/purenow#cli-commands) (unchanged)
+- Explore [Three-Stack Architecture](#three-stack-deployment)
+- Learn about [Extended CLI Commands](#extended-cli-commands)
+- Read the [Base Framework Documentation](https://www.npmjs.com/package/@worktif/purenow)
+
+---
+
+## Usage
+
+### CLI Commands
+
+**All Purenow Commands Available (Unchanged):**
+The runtime package preserves all base purenow CLI functionality:
+
+```bash
+# Development (from purenow base framework)
+npx purenow dev                    # Start development server
+npx purenow dev --port 8080        # Custom port
+
+# Building (from purenow base framework)  
+npx purenow build                  # Build for deployment
+npx purenow build --target lambda  # Build specific target
+
+# Deployment (from purenow base framework)
+npx purenow deploy --stage dev     # Deploy to AWS (now uses three stacks)
+npx purenow destroy --stage dev    # Destroy all stacks
+
+# Resource Management (from purenow base framework)
+npx purenow stacks list --outputs  # List stack outputs
+npx purenow cache-clear --stage dev # Clear CloudFront/S3 cache
+
+# SEO Management (from purenow base framework)
+npx purenow seo sync --stage dev   # Sync SEO metadata
+npx purenow seo clear --stage dev  # Clear SEO data
+
+# Diagnostics (from purenow base framework)
+npx purenow doctor                 # System diagnostics
+npx purenow info                   # Display configuration
+```
+
+### Extended CLI Commands
+
+Runtime adds additional commands using purenow's extensible CLI architecture:
+
+```bash
+# Runtime-specific diagnostics
+npx purenow runtime:info           # Display runtime extension information
+npx purenow runtime:stacks         # Show three-stack deployment status
+```
+
+**Complete CLI Reference:** See [@worktif/purenow CLI documentation](https://www.npmjs.com/package/@worktif/purenow#cli-commands) for all base commands
+
+### Programmatic Usage
+
+Initialize your application using runtime (includes all purenow functionality):
+
+```typescript
+import { purenow, purenowRouter, ErrorBoundary } from '@worktif/runtime';
+import { routes } from './routes';
+import App from './App';
+
+// Initialize with all purenow functionality + runtime extensions
+purenow({
+  app: ({ router }) => <App router={router} />,
+  router: purenowRouter({
+    router: routes,
+    defaults: {
+      HydrateFallback: () => <div>Loading...</div>,
+      ErrorBoundary,
+    },
+  }),
+  config: {
+    serviceName: process.env.PURE_ENV_STACK_NAME || 'my-app',
+    stage: (process.env.PURE_ENV_STAGE as 'dev' | 'staging' | 'prod') || 'dev',
+    // Runtime extensions can add additional config options here
+  },
+});
+```
+
+**Extension Relationship:** This package re-exports all @worktif/purenow functionality unchanged, plus adds runtime-specific extensions.
+
+### Three-Stack Deployment
+
+Runtime extends purenow's two-stack deployment to three stacks:
+
+```typescript
+// When you deploy with runtime, you get three stacks instead of two:
+// 1. Infrastructure Stack (from purenow)
+// 2. Runtime Stack (from purenow)  
+// 3. Additional Runtime Stack (added by runtime)
+
+// All purenow functionality remains unchanged
+// Runtime adds additional deployment capabilities
+```
+
+**Three-Stack Benefits:**
+- **Extended Infrastructure**: Additional AWS resources for enhanced functionality
+- **Deployment Strategy**: Uses purenow's deployment strategy pattern
+- **Resource Isolation**: Better separation of concerns across stacks
+- **Backward Compatibility**: All existing purenow deployments continue to work
+
+**Base Framework Features:** All SSR, caching, SEO, CLI tools, and other features from @worktif/purenow are available unchanged.
+
+### CDK Construct Library
+
+The runtime package provides access to purenow constructs plus runtime extensions:
+
+```typescript
+import * as cdk from 'aws-cdk-lib';
+import { PurenowStack } from '@worktif/runtime/infra';
+import { RuntimeStack } from '@worktif/runtime/infra';
+
+const app = new cdk.App();
+
+// Base Purenow stacks (re-exported from @worktif/purenow)
+const infraStack = new PurenowStack(app, 'MyApp-Infra-Dev', {
+  stage: 'dev',
+  serviceName: 'my-app',
+  enableSeo: true,
+  env: {
+    account: process.env.CDK_DEFAULT_ACCOUNT,
+    region: 'us-east-1',
+  },
+});
+
+// Additional runtime stack (extends purenow's two-stack architecture)
+new RuntimeStack(app, 'MyApp-Runtime-Dev', {
+  stage: 'dev',
+  serviceName: 'my-app',
+  // Extends existing purenow infrastructure
+  dependsOn: [infraStack],
+});
+
+app.synth();
+```
+
+**Extension Relationship:** Runtime constructs extend purenow's existing CDK patterns and integrate with the two-stack architecture.
+
+**CDK Documentation:** See [@worktif/purenow CDK documentation](https://www.npmjs.com/package/@worktif/purenow#cdk-construct-library) for base constructs
+
+---
+
+## Runtime Extensions
+
+### Three-Stack Deployment Architecture
+
+Runtime extends purenow's deployment from two stacks to three:
+
+**Stack Architecture:**
+1. **Infrastructure Stack** (from purenow) - Core AWS resources
+2. **Runtime Stack** (from purenow) - Lambda functions and API Gateway  
+3. **Additional Runtime Stack** (added by runtime) - Extended functionality
+
+**Deployment Commands:**
+```bash
+# Deploy all three stacks (runtime extension)
+npx purenow deploy --stage dev
+
+# Destroy all three stacks (runtime extension)
+npx purenow destroy --stage dev
+
+# List all stack outputs (includes third stack)
+npx purenow stacks list --outputs
+```
+
+### Extended CLI Architecture
+
+Runtime uses purenow's extensible CLI architecture to add commands:
+
+```bash
+# Runtime-specific commands (added via CLI extension)
+npx purenow runtime:info     # Display runtime extension information
+npx purenow runtime:stacks   # Show three-stack deployment status
+```
+
+### Complete Purenow Features (Preserved)
+
+All features from @worktif/purenow are available unchanged:
+
+- **SEO Integration** with DynamoDB (`npx purenow seo sync/clear`)
+- **Cache Management** for S3, CloudFront (`npx purenow cache-clear`)
+- **Development Server** with HMR (`npx purenow dev`)
+- **CloudFormation Resource Resolution** (`npx purenow stacks list`)
+- **HTML Template Customization** (all configuration options)
+- **Complete CLI Commands** (deploy, destroy, build, doctor, info)
+
+See the [@worktif/purenow documentation](https://www.npmjs.com/package/@worktif/purenow) for complete details on all base framework features.
+
+---
+
+## Documentation
+
+### Runtime Extension Documentation
+- [Three-Stack Architecture](#three-stack-deployment-architecture) - Extended deployment architecture
+- [Extended CLI Commands](#extended-cli-architecture) - Runtime-specific CLI additions
+- [CDK Extensions](#cdk-construct-library) - Runtime CDK constructs
+
+### Complete Base Framework Documentation
+For complete documentation on all base framework features (which runtime extends), see [@worktif/purenow documentation](https://www.npmjs.com/package/@worktif/purenow):
+
+- **Getting Started** - Project initialization and setup
+- **CLI Commands** - Complete command reference (all available in runtime)
+- **CDK & Deployment** - Infrastructure and deployment patterns
+- **Development** - Local development server and workflows
+- **SEO Integration** - DynamoDB metadata management
+- **Cache Management** - S3, CloudFront, and CloudFormation caching
+- **Architecture** - Complete framework architecture
+- **API Reference** - Complete TypeScript API documentation
+
+---
+
+## Package Exports
+
+The runtime package provides multiple entry points that extend purenow functionality:
+
+| Export | Path | Description |
+|--------|------|-------------|
+| Main Library | `@worktif/runtime` | All @worktif/purenow exports + runtime extensions |
+| Runtime Extensions | `@worktif/runtime/runtime-web` | Runtime-specific functionality |
+| Extended CLI | `@worktif/runtime/cli` | CLI with runtime commands (extends purenow CLI) |
+| CDK Constructs | `@worktif/runtime/infra` | Purenow constructs + runtime extensions |
+
+**Example:**
+```typescript
+// Import runtime library (includes all purenow functionality + extensions)
+import { purenow, PurenowRouter } from '@worktif/runtime';
+
+// Import runtime-specific functionality
+import { RuntimeExtensions } from '@worktif/runtime/runtime-web';
+
+// Import CDK constructs (purenow + runtime extensions)
+import { PurenowStack, RuntimeStack } from '@worktif/runtime/infra';
+```
+
+**Extension Relationship:** All exports include the complete @worktif/purenow functionality plus runtime-specific additions.
+
+---
+
+## Examples
+
+### Basic Application with Runtime Extensions
+
+```typescript
+import { purenow, purenowRouter } from '@worktif/runtime';
+import { RouteObject } from 'react-router';
+import { HomePage } from './pages/HomePage';
+import { AboutPage } from './pages/AboutPage';
+import App from './App';
+
+const routes: RouteObject[] = [
+  {
+    path: '/',
+    element: <HomePage />,
+  },
+  {
+    path: '/about',
+    element: <AboutPage />,
+  },
+];
+
+// Uses all purenow functionality + runtime extensions
+purenow({
+  app: ({ router }) => <App router={router} />,
+  router: purenowRouter({
+    router: routes,
+  }),
+  config: {
+    serviceName: 'my-app',
+    stage: 'dev',
+    // Runtime can extend config options here
+  },
+});
+```
+
+### Three-Stack CDK Deployment
+
+```typescript
+import { PurenowStack, RuntimeStack } from '@worktif/runtime/infra';
+import * as cdk from 'aws-cdk-lib';
+
+const app = new cdk.App();
+
+// Infrastructure stack (from purenow)
+const infraStack = new PurenowStack(app, 'MyApp-Infra-Prod', {
+  stage: 'prod',
+  serviceName: 'my-app',
+  enableSeo: true,
+  lambdaMemorySize: 1024,
+  lambdaTimeout: 30,
+});
+
+// Additional runtime stack (extends purenow architecture)
+new RuntimeStack(app, 'MyApp-Runtime-Prod', {
+  stage: 'prod',
+  serviceName: 'my-app',
+  dependsOn: [infraStack], // Extends existing infrastructure
+});
+
+app.synth();
+```
+
+**More Examples:** See [@worktif/purenow examples](https://www.npmjs.com/package/@worktif/purenow#examples) for all base framework examples (all work with runtime)
+
+---
+
+## Contributing
+
+We welcome contributions! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes with tests
+4. Submit a pull request
+
+For detailed contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+**Security:** Report vulnerabilities privately to [raman@worktif.com](mailto:raman@worktif.com)
+
+---
+
+## License
+
+This project is licensed under the [Elastic License 2.0](https://raw.githubusercontent.com/elastic/elasticsearch/v7.16.3/licenses/ELASTIC-LICENSE-2.0.txt).
+
+- See [LICENSE](LICENSE) for the full license text
+- See [NOTICE](NOTICE) for attribution and relicensing details
+- See [CHANGELOG.md](CHANGELOG.md) for version history
+
+---
+
+## Support
+
+**Maintainer:** Raman Marozau - [raman@worktif.com](mailto:raman@worktif.com)
+
+**Get Help:**
+- [Documentation](docs/README.md)
+- [GitHub Issues](https://github.com/worktif/purenow/issues)
+- [Email Support](mailto:raman@worktif.com) (use "[purenow]" in subject)
+
+For enterprise support and integration guidance, contact us via email.
+
+---
+
+**Ready to get started?** Run `npx @worktif/runtime init` to create your first serverless React application with three-stack deployment and all purenow features!