# @kosdev-code/kos-nx-plugin

Nx plugin providing generators and executors for KOS UI application development.

## Overview

This plugin provides a complete development workflow for KOS applications, including:

- **Workspace Creation**: Bootstrap new KOS workspaces with data-driven plugin development
- **Plugin Development**: Create and manage UI plugins with automatic registration
- **Development Servers**: Metadata-driven development server orchestration via `koscli dev`
- **Model Generation**: Create KOS models with decorators and reactive state management
- **Component Generation**: Generate React components for KOS applications

## Quick Start

### Create a New Workspace

```bash
npx create-nx-workspace@latest my-workspace --preset=@kosdev-code/kos-nx-plugin
cd my-workspace
```

During setup, you'll be prompted:

- Workspace name
- Whether to enable plugin support (default: yes)

This creates a workspace with:

- Host application configured for plugin development
- `.kos.json` with development metadata
- npm scripts for development workflow

### Start Development

```bash
# Interactive mode - select host and plugins
npm run dev

# Or specify host directly
koscli dev --host my-workspace-ui

# Verbose logging
npm run dev:verbose
```

## Plugin Development Workflow

### Creating Your First Plugin

```bash
# Create a new plugin
nx g @kosdev-code/kos-nx-plugin:kos-plugin-project my-plugin --uiType=kos.ui.plugin

# The generator will:
# 1. Prompt for which host to register with
# 2. Auto-assign a port from the host's range
# 3. Register plugin in .kos.json
# 4. Update plugin project.json with port
```

### Plugin Auto-Registration

When you create a plugin, it's automatically registered in `.kos.json`:

```json
{
  "development": {
    "hosts": [
      {
        "name": "my-workspace-ui",
        "plugins": [
          {
            "project": "my-plugin",
            "port": 4201,
            "alias": "my-plugin",
            "enabled": true
          }
        ]
      }
    ],
    "portRanges": {
      "my-workspace-ui": {
        "start": 4200,
        "next": 4202
      }
    }
  }
}
```

### Development Modes

**Internal Development Mode** (Default)

- Starts host app + plugin dev servers
- Server-side plugin aggregation
- Hot module reloading for plugins
- Access at `http://localhost:4200`

```bash
koscli dev --host my-workspace-ui
```

**Third-Party Development Mode** (Plugins Only)

- For developing plugins without host source code
- Starts only plugin dev servers
- Connect to deployed device via query parameters

```bash
koscli dev --host my-workspace-ui --plugins-only
```

**Selective Plugin Loading**

```bash
# Start specific plugins
koscli dev --host my-workspace-ui --plugins my-plugin,another-plugin

# Disable specific plugins
koscli dev --host my-workspace-ui --disable my-plugin
```

## Available Generators

### Workspace & Projects

- `workspace` - Create new KOS workspace
- `project` - Create KOS UI app project
- `plugin` - Create KOS plugin project
- `i18n` - Create localization project
- `content` - Create content project
- `theme` - Create theme project

### Models

- `model` - Create KOS model
- `container` - Create container model
- `model:companion` - Create companion model
- `add-future` - Add Future support to model

### Components

- `component` - Create React component
- `context` - Create model React context
- `hook` - Create model React hook

### Plugin Components

- `plugin:cp` - Plugin control pour
- `plugin:custom` - Custom plugin contribution

DDK plugin projects, themes and contributions come from the
`@kosdev-code/kos-ddk-cli` extension (`npm install -D @kosdev-code/kos-ddk-cli`).

### Development

- `dev` - Start development servers (via `koscli dev`)
- `serve` - Run serve target for a project
- `kab` - Run KAB packaging target

### Artifacts

`kab` and `zip` write into `{projectRoot}/target/` — a peer of the project's
`src/`, matching where the Maven half of a polyglot repo drops its KABs
(`java/<module>/target/*.kab`). `target/` is gitignored and excluded from Nx's
`default` named input.

`descriptor` and `sbom` write into the build output dir (`dist/{projectRoot}`)
instead, because archiver zips that directory wholesale — both ride inside
`ui.zip`, and therefore inside the KAB. The SBOM in particular has to travel
with the distribution it describes. That is why `zip` depends on `sbom`:
kabtool packages an already-sealed zip, so anything ordered after `zip` misses
the artifact entirely.

The paths are Nx `{projectRoot}` tokens, so moving a project needs no
project.json rewrite. Nx only interpolates tokens in a target's `outputs`, not
in arbitrary `options`, and the artifact scripts read those options straight
off the cached project graph — so `tools/scripts/{kabtool.mjs, archiver.js,
descriptor.mjs, splashtool.mjs}` and the `sbom` executor expand the token
themselves. Any new consumer of these options must do the same.

Workspaces created before this layout move over with
`nx migrate @kosdev-code/kos-nx-plugin` (`move-kab-output-to-target`).

## Documentation

- [koscli dev Usage Guide](./docs/dev-script-usage.md) - Complete guide to development server
- [.kos.json Schema](./docs/kos-json-schema.md) - Configuration schema reference
- [Migration Guide](./docs/migration-to-data-driven.md) - Migrate existing workspaces

## Configuration

### .kos.json Root Configuration

```json
{
  "type": "root",
  "generator": {
    "defaults": {
      "model": "my-models",
      "ui": "my-ui"
    }
  },
  "development": {
    "hosts": [...],
    "portRanges": {...},
    "logDir": "/tmp/my-workspace-logs"
  }
}
```

See [.kos.json Schema Documentation](./docs/kos-json-schema.md) for complete reference.

## Building

```bash
npx nx build @kosdev-code/kos-nx-plugin
```

## Publishing

This package is published to npm as part of the KOS SDK release process.

## Version

See package.json for current version. This plugin follows semantic versioning and is released alongside the KOS UI SDK.