@induction/plugin

Nx plugin for the Induction framework - capability-based code generation for compile-time authorization.

Overview

This plugin provides generators to create and manage Induction components in an Nx workspace. Unlike traditional template-based approaches, this plugin uses a capability-based architecture that allows you to define any component structure without being forced into predefined patterns like "deciders" or "interactors".

Installation

npm install --save-dev @inductionai/plugin

Generators

project ⭐ Primary Scaffolding Tool

Scaffold an Induction project from a template. This is the primary way to get started.

# Quick tutorial (instant, offline, ~10 files)
nx g @induction/plugin:project --template=quick

# Complete example from GitHub (~66 files with tests & docs)
nx g @induction/plugin:project --template=complete

# Config library only (instant, ~8 files)
nx g @induction/plugin:project --template=config-only

# Empty workspace (minimal)
nx g @induction/plugin:project --template=empty

# Custom GitHub repository
nx g @induction/plugin:project --template=user/repo
nx g @induction/plugin:project --template=github:user/repo/subdirectory

Options:

• --template - Template to use: quick, complete, config-only, empty, or GitHub repo (default: "quick")
• --includeTests - Include test files from complete template (default: false)
• --skipFormat - Skip formatting files (default: false)

Templates:

quick (Embedded, instant):

• ~10 files demonstrating compile-time authorization
• Simple DemoApp → GreeterService example
• Works offline
• Perfect for learning

complete (GitHub, ~5-10s):

• Full example from GitHub with tests, docs, multiple components
• Version-locked to plugin version (fetches from #v2.0.0 tag for reproducibility)
• Get latest: use --template=inductionAI/fwk/examples/01-basic-framework-app
• Includes: deciders, interactors, wiring, demo app, WALKTHROUGH.md
• 17 unit tests included (with --includeTests flag)
• Production-ready patterns

config-only (Embedded, instant):

• Just the config library (libs/config/)
• Build your own architecture
• No demo app

empty (Embedded, instant):

• Bare workspace with .induction/config.json marker file
• Total freedom to structure as needed

GitHub repos (Runtime fetch):

• Fetch any GitHub repository as template
• Supports monorepo subdirectories, branches, tags, commits
• Syntax: user/repo, user/repo#branch, user/repo#v1.0.0, user/repo/path#ref
• Automatic caching for repeat use (in ~/.degit/)

component

Create a component with capabilities.

nx g @induction/plugin:component my-service --exposes="MyAPI"
nx g @induction/plugin:component my-app --type=application --requires="MyAPI"

Options:

• name (required) - Component name
• --directory - Directory path (e.g., "libs/services/my-service")
• --exposes - Comma-separated list of APIs this component exposes
• --requires - Comma-separated list of APIs this component needs
• --type - "library" or "application" (default: "library")
• --tags - Comma-separated tags
• --skipTests - Skip generating test files
• --generateImplementation - Generate implementation boilerplate (default: true)

What it does:

• Creates a new library or application
• Adds component ID to ids.ts
• Generates API interfaces for exposed capabilities
• Updates ComponentRegistry mapping
• Generates implementation boilerplate with TODO markers
• Provides guidance for required API access

api

Define an API interface.

nx g @induction/plugin:api UserAPI

Options:

• name (required) - API interface name (e.g., "UserAPI")
• --methods - Comma-separated list of method names

What it does:

• Creates a new API interface in apis.ts
• Provides a skeleton for you to fill in method signatures

policy

Manage authorization rules.

# Grant access
nx g @induction/plugin:policy --allow="caller:callee"

# Revoke access
nx g @induction/plugin:policy --deny="caller:callee"

Options:

• --allow - Grant access in format "caller:callee"
• --deny - Revoke access in format "caller:callee"

What it does:

• Updates policy.ts with authorization rules
• Creates or updates caller's access list
• Removes rules when using --deny
• Enforces compile-time authorization

validate

Validate Induction configuration for errors and warnings.

nx g @induction/plugin:validate
nx g @induction/plugin:validate --saveReport

Options:

• --fix - Automatically fix issues where possible (default: false)
• --saveReport - Save validation report to .induction/validation-report.json (default: false)

What it detects:

• Circular dependencies in policy
• Invalid component references
• Orphaned components (not in policy or registry)
• Unused API interfaces
• Missing components

Output:

• Summary of configuration
• List of errors with suggestions
• List of warnings
• Validation report (optional)

Usage Example

Creating an E-Commerce System

# 1. Initialize Induction
nx g @induction/plugin:project --template=config-only

# 2. Create product service
nx g @induction/plugin:component product-service \
  --exposes="ProductAPI,InventoryAPI" \
  --directory="libs/services/product"

# 3. Create order service
nx g @induction/plugin:component order-service \
  --exposes="OrderAPI" \
  --directory="libs/services/order"

# 4. Create admin application
nx g @induction/plugin:component admin-portal \
  --type=application \
  --requires="ProductAPI,OrderAPI,InventoryAPI" \
  --directory="apps/admin"

# 5. Create customer application (limited access)
nx g @induction/plugin:component customer-app \
  --type=application \
  --requires="ProductAPI,OrderAPI" \
  --directory="apps/customer"

# 6. Set up authorization
nx g @induction/plugin:policy --allow="adminPortal:productService"
nx g @induction/plugin:policy --allow="adminPortal:orderService"
nx g @induction/plugin:policy --allow="customerApp:productService"
nx g @induction/plugin:policy --allow="customerApp:orderService"

# 7. Validate configuration
nx g @induction/plugin:validate

Key Concepts

Capability-Based Architecture

Components are defined by what they can do (capabilities), not what they're called:

• Exposes: APIs/capabilities a component provides
• Requires: APIs/capabilities a component needs

This approach is generic - you can use any naming conventions:

• Services, modules, handlers, workers
• Any directory structure
• Any architectural pattern

Compile-Time Authorization

Authorization is enforced by TypeScript's type system:

// In component that requires UserAPI
import { authorize } from '@induction/config';

// ✅ Authorized - returns full API
const userService = authorize('adminApp', 'userService');
await userService.getUser('123');

// ❌ Unauthorized - returns 'never', TypeScript error
const forbidden = authorize('adminApp', 'unauthorizedService');
await forbidden.doSomething(); // Type error: Property 'doSomething' does not exist on type 'never'

Benefits

1. No Hardcoded Patterns: Define any architecture (no forced "decider/interactor" concepts)
2. Type-Safe: Full TypeScript type safety and IntelliSense
3. Zero Runtime Overhead: Authorization checked at compile-time
4. Flexible Structure: Use any directory organization
5. Incremental Adoption: Works in existing Nx workspaces
6. Clear Errors: TypeScript provides helpful error messages

Development Workflow

1. Scaffold: nx g @induction/plugin:project --template=config-only
2. Create Components: nx g @induction/plugin:component <name> --exposes=<APIs>
   • Implementation boilerplate auto-generated with TODO markers
   • Registration guidance included
3. Set Authorization: nx g @induction/plugin:policy --allow=<caller>:<callee>
4. Validate: nx g @induction/plugin:validate (check for errors)
5. Implement: Fill in API method signatures and implementations
6. Register: Use register() from @induction/config to wire up implementations
7. Authorize: Use authorize() to get type-safe, authorized access
8. Validate Again: Run validation before commits/deployments

Type Safety

Critical: Run tsc --noEmit before deploying to enforce authorization:

{
  "scripts": {
    "typecheck": "tsc -p tsconfig.base.json --noEmit",
    "build": "npm run typecheck && nx build"
  }
}

Running with tsx or transpilers bypasses type checking - always run tsc to enforce authorization.

Migration from v1.x

If upgrading from @inductionai/[email protected], the deprecated generators have been removed:

• nx g init → nx g project --template=config-only
• nx g example → nx g project --template=quick (or --template=complete)
• nx g minimal → nx g project --template=config-only
• nx g migrate → Removed (was for legacy template migration)

See CHANGELOG.md for full v2.0.0 migration guide.

License

MIT