Induction Framework

Build-time authorization system using TypeScript's conditional types for zero-cost runtime security.

🚀 Now Available on npm! Published under MIT License.

📚 Documentation

• Complete Documentation - Full guides and API reference
• Quick Start - Get started in 5 minutes
• Why Induction? - Understand the benefits
• GitHub Pages Setup - Deploy documentation site

📦 Packages

@inductionai/framework

Build-time authorization using conditional types

Enforces access control policies at compile-time with zero runtime overhead.

• Location: packages/framework/
• Status: ✅ Production Ready
• Documentation: packages/framework/README.md

@inductionai/plugin (NEW!)

Nx generators for flexible code generation

Create components with ANY naming - no hardcoded "Decider/Interactor" patterns!

• Location: packages/induction-plugin/
• Status: ✅ Production Ready
• Generators: 5 (project, component, api, policy, validate)
• Tests: 103/103 passing
• Documentation: packages/induction-plugin/README.md

create-induction-app

CLI tool for scaffolding Induction projects

Quickly create new projects with the Induction framework pre-configured.

• Location: packages/create-induction-app/
• Status: ✅ Production Ready
• Version: v3.0.0 - Requires plugin v2.0.0+
• Usage: npx create-induction-app my-app

---

🚀 Quick Start

# Create project
npx create-induction-app my-app
cd my-app
npm install

# Add components (any names!)
nx g @inductionai/plugin:component user-service --exposes="UserAPI"
nx g @inductionai/plugin:component admin-app --type=application --requires="UserAPI"

# Set authorization
nx g @inductionai/plugin:policy --allow="admin-app:user-service"

# Validate configuration
nx g @inductionai/plugin:validate

# Build and run
npm run build

Templates

Choose from four templates:

• quick ⭐ - Quick tutorial (~10 files, instant, offline)
• complete - Full example from GitHub (~66 files with tests & docs)
• config-only - Just config library (~8 files, instant)
• empty - Bare workspace (total freedom)

---

📖 Examples

Standalone Example Application

A complete example application is available at /examples/01-basic-framework-app/ demonstrating:

• Compile-time authorization enforcement
• Decider/Interactor pattern
• Service wiring and registration
• Comprehensive test suite (17 tests)

Running the Example

cd examples/01-basic-framework-app
npm install
npm test           # Run 17 unit tests (1.2s)
npm run build      # Build demo app
npm start          # Run demo application

From Root Directory

npm run example:test       # Run example tests
npm run example:build      # Build example
npm run example:serve      # Run demo

Create New Project with Example

Working examples can be scaffolded using the unified project generator.

# Quick tutorial (instant, offline)
npx create-induction-app my-app --template=quick

# Complete example from GitHub (with tests)
npx create-induction-app my-app --template=complete --include-tests

# Or use the generator directly
nx g @inductionai/plugin:project --template=quick
nx g @inductionai/plugin:project --template=complete

Available Examples

01-basic-example

Basic authorization pattern demonstration

Demonstrates:

• Compile-time authorization enforcement
• Component configuration with induction.config.ts
• Policy-based access control
• Accessible vs inaccessible component patterns

Structure:

apps/demo/              # Demo application
libs/config/            # Configuration library (IDs, APIs, policy, registry)
libs/deciders/          # Example decision components
  accessible/           # Authorized component
  inaccessible/         # Unauthorized component
libs/interactors/       # Example interaction components
  example/              # Demonstrates authorized API access
libs/wiring/            # Component wiring

Authorization Policy: The example interactor can only access the accessible decider - attempts to access the inaccessible decider will fail at compile-time with a TypeScript error.

Examples as Standalone Apps

Each bundled example is a fully working standalone application that can be:

• Deployed to your workspace with nx g @inductionai/plugin:example
• Used as a reference for authorization patterns
• Customized and extended for your use case

Development

# Build all packages
npm run build:all

# Build specific package
npx nx build framework
npx nx build create-induction-app

# Run tests
npm test

# Watch mode for development
npm run dev:framework
npm run dev:cli

---

🔧 Development Setup

The framework is not published to npm yet - we use npm link for local development.

Initial Setup (One-Time Per Machine)

# 1. Install dependencies
npm install

# 2. Build and link the framework globally
npm run link:framework

# 3. Verify the link
npm run link:status
# Should show: @inductionai/framework@1.0.0 -> .../packages/framework

Create Projects

# CLI automatically detects and links to your local framework
npx create-induction-app my-app --template=example

cd my-app
npm install
npm run build
node dist/apps/demo/main.js

What happens: CLI detects the global link and automatically runs npm link @inductionai/framework in your project!

Active Development Workflow

Option 1: Watch Mode (Recommended)

# Terminal 1: Run framework in watch mode
npm run dev:framework

# Terminal 2: Work on your app
cd my-app
# Framework automatically rebuilds on changes!

Option 2: Manual Rebuild

# Make changes to packages/framework/src/
npx nx build framework
# Changes now available to all linked projects

Troubleshooting

"Cannot find module @inductionai/framework"

# Check if framework is linked
npm run link:status

# If not linked, run:
npm run link:framework

"Framework changes not appearing"

# Rebuild the framework
npx nx build framework
# Or use watch mode: npm run dev:framework

"Link broken after npm install"

# Verify symlink still exists
ls -la node_modules/@inductionai/framework
# Should show: symlink → .../dist/packages/framework

# Re-link if needed
npm link @inductionai/framework

---

📁 Repository Structure

induction/
├── packages/
│   ├── framework/              # @inductionai/framework - Core framework
│   └── create-induction-app/   # CLI tool for project scaffolding
├── docs/                       # Documentation
│   └── archive/               # Historical documentation
├── nx.json                    # Nx workspace configuration
├── tsconfig.base.json         # Base TypeScript configuration
└── package.json               # Root workspace configuration

---

🛠 Development Commands

# Install dependencies
npm install

# Build all packages
npm run build:all

# Build with watch mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# View dependency graph
npm run graph

---

📝 Publishing

# Publish framework package
npm run publish:framework

# Publish CLI package
npm run publish:cli

---

📚 Documentation

• Framework Documentation
• Plugin Documentation
• CLI Documentation
• Historical Documentation

---

🏗 Architecture

The Induction framework uses TypeScript's type system to enforce authorization policies at compile time. This means:

• Zero runtime overhead - all checks happen during compilation
• Type-safe - violations are caught by the TypeScript compiler
• Composable - policies can be combined and extended
• Testable - full TypeScript support for testing authorization logic

See the framework README for detailed architecture information.

---

Built with TypeScript • Zero Runtime Overhead ⚡