npm package: @inductionai/plugin
Description: Nx plugin for Induction framework - capability-based code generation for compile-time authorization
Author: Induction Framework Contributors
Latest version: 2.0.3

# @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

```bash
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.

```bash
# 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.

```bash
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.

```bash
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.

```bash
# 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.

```bash
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

```bash
# 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:

```typescript
// 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:

```json
{
  "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/plugin@1.x`, 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](./CHANGELOG.md) for full v2.0.0 migration guide.

## License

MIT