npm package: @nest-insignia/insignia
Description: This library was generated with [Nx](https://nx.dev).
Latest version: 0.1.0

# insignia

This library was generated with [Nx](https://nx.dev).

## Building

Run `nx build insignia` to build the library.

## Running unit tests

Run `nx test insignia` to execute the unit tests via [Jest](https://jestjs.io).

## RC file

Insignia reads an rc file from the project root to resolve kernel entrypoints.

- Supported kinds: `http`, `cli`, `rpc`
- Each kind maps entrypoint `name -> path`
- A special `default` name is used when no name is specified

Create `.insigniarc.json` in your project root:

```
{
  "http": {
    "default": "apps/api/src/main.ts",
    "admin": "apps/admin/src/main.ts"
  },
  "cli": {
    "default": "apps/tools/src/cli.ts"
  },
  "rpc": {
    "default": "apps/worker/src/main.ts",
    "billing": "apps/billing/src/main.ts"
  }
}
```

Alternatively, you may put the same object under `package.json` as the `insignia` field.

CLI helpers:

- `insignia entrypoints [http|cli|rpc] [--json]` – list configured entrypoints
- `insignia resolve <http|cli|rpc> [name]` – print the resolved path

## Project CLI Integration

Expose your app’s commands under the root `insignia` CLI by exporting a registrar from your compiled CLI entry.

1) Create a CLI module that imports `CommandsModule` and provides your `@Command` classes.

```ts
// apps/cli/src/cli.module.ts
import { Module } from '@nestjs/common';
import { CommandsModule } from '@nest-insignia/insignia';
import { HelloCliCommand } from './commands/hello.cli-command';

@Module({ imports: [CommandsModule], providers: [HelloCliCommand] })
export class CliModule {}
```

2) In your CLI entry, export a registrar via the builder:

```ts
// apps/cli/src/main.ts
import { Kernel } from '@nest-insignia/insignia';
import { CliModule } from './cli.module';

export const registerInsignia = Kernel.cli().module(CliModule).registrar();
```

3) Point rc to the compiled file (not TS):

```json
{
  "cli": { "default": "dist/apps/cli/main.js" }
}
```

When `insignia` runs, it will `require()` your compiled entry and call `registerInsignia(y)` to register your project’s commands.

### Property Binding and Getters

Insignia’s registry automatically binds parsed argv values to your command class properties based on the `@Positional()` and `@Option()` decorators.

- Before `execute` is called, it assigns writable properties: `this.<prop> = argv[<name>]`.
- It also wraps your instance in a proxy so reading a decorated property returns the corresponding argv value even if there is no concrete field — perfect for getters.

Example:

```ts
@Command({ name: 'start' })
export class StartCommand {
  @Positional({ type: 'string' })
  kernel!: 'http' | 'cli' | 'rpc';

  @Option({ type: 'string' })
  name?: string;

  // You can rely on bound properties or define getters
  get target() {
    return `${this.kernel}:${this.name ?? 'default'}`;
  }

  async execute() {
    // Use bound values directly; no need to read argv
    console.log('Starting', this.target);
  }
}
```

Typescript convenience:

```ts
// If you want an explicit type, both signatures are supported
import type { ExecuteSignature } from '@nest-insignia/insignia';

type Exec = ExecuteSignature<{ kernel: string; name?: string }>;
class C { execute: Exec = () => { /* ... */ } }
```