insignia

This library was generated with Nx.

Building

Run nx build insignia to build the library.

Running unit tests

Run nx test insignia to execute the unit tests via Jest.

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.

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

// 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):

{
  "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:

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

// 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 = () => { /* ... */ } }