@northern/cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luke Schreur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,238 @@
+# @northern/cli
+
+A lightweight, typed CLI program framework for building command-driven tools with consistent help output and parameter parsing.
+
+## Feature overview
+
+- **Typed program model** with `Program`, `Command`, `Argument`, and `Option` definitions.
+- **Built-in parsing** for required arguments and optional flags.
+- **Three parameter modes**: `value`, `switch`, and `enum`.
+- **Automatic help output** for global and command-specific options.
+- **Validation and errors** via `ParameterError` when arguments are invalid or duplicated.
+- **Pluggable console** powered by `@northern/console` for consistent styled output.
+
+## Install
+
+```bash
+npm install @northern/cli
+```
+
+## How to use
+
+### 1) Define your program
+
+```ts
+import { Interpreter, ParameterType, Program } from '@northern/cli';
+
+const program: Program = {
+	title: 'Acme Tool',
+	version: '1.2.3',
+	name: 'acme',
+	options: [
+		{
+			name: 'verbose',
+			description: 'Enable verbose output',
+			type: ParameterType.SWITCH,
+			directives: ['-v', '--verbose'],
+			example: '--verbose',
+			default: false,
+		},
+	],
+	commands: [
+		{
+			name: 'build',
+			description: 'Build the project',
+			arguments: [
+				{
+					name: 'source',
+					description: 'Source file',
+					type: ParameterType.VALUE,
+					directives: ['-s', '--source'],
+					example: '--source ./app.yaml',
+				},
+			],
+			options: [
+				{
+					name: 'mode',
+					description: 'Build mode',
+					type: ParameterType.ENUM,
+					directives: ['-m', '--mode'],
+					example: '--mode production',
+					values: ['development', 'production'],
+					default: 'development',
+				},
+			],
+		},
+	],
+};
+```
+
+### 2) Parse arguments and execute
+
+```ts
+const interpreter = new Interpreter(program, process.argv.slice(2));
+
+if (!interpreter.init()) {
+	process.exit(1);
+}
+
+const command = interpreter.getCommand();
+if (!command) {
+	interpreter.displayHelp(process.argv[2]);
+	process.exit(1);
+}
+
+const params = interpreter.getParameters(command);
+if (!params) {
+	interpreter.displayCommandHelp(command);
+	process.exit(1);
+}
+
+const globalOptions = interpreter.getGlobalOptions() ?? {};
+
+// Execute your command using parsed values
+// e.g. runBuild(params, globalOptions)
+```
+
+### 3) What parsing does
+
+- **Required arguments** must be present or `getParameters()` returns `null`.
+- **Options** default to their `default` value when not specified.
+- **Switch options** (`ParameterType.SWITCH`) resolve to `true` if present.
+- **Enum options** (`ParameterType.ENUM`) must match one of the configured `values`.
+- **Duplicate directives** (e.g. `--verbose --verbose`) trigger a parse error.
+
+## Reference documentation
+
+### Types
+
+#### `ParameterType`
+
+- `ParameterType.VALUE` — a directive that requires a value (e.g. `--config path`).
+- `ParameterType.SWITCH` — a boolean flag (e.g. `--verbose`).
+- `ParameterType.ENUM` — a directive that accepts one of a predefined set of values.
+
+#### `Argument`
+
+Required parameter definition:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Internal key used in parsed output. |
+| `description` | `string` | Human-readable help text. |
+| `type` | `ParameterType` | Parameter type. |
+| `directives` | `string[]` | Accepted flags (e.g. `['-s', '--source']`). |
+| `example` | `string` | Example usage shown in help. |
+| `values?` | `string[]` | Allowed values for `ENUM` parameters. |
+
+#### `Option`
+
+Optional parameter definition. Same as `Argument` plus:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `default` | `unknown` | Default value when option is omitted. |
+
+#### `Command`
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Command name (e.g. `build`). |
+| `description` | `string` | Help summary. |
+| `arguments?` | `Argument[]` | Required parameters. |
+| `options?` | `Option[]` | Command-specific options. |
+
+#### `Program`
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | Display title shown in the banner. |
+| `version` | `string` | Version string. |
+| `name` | `string` | Executable name for usage output. |
+| `options` | `Option[]` | Global options. |
+| `commands` | `Command[]` | Available commands. |
+
+#### `Parameters`
+
+`Record<string, unknown>` containing parsed values keyed by `Argument`/`Option` `name`.
+
+#### `ICommand`
+
+```
+interface ICommand {
+	run(parameters: Parameters): Promise<unknown>
+}
+```
+
+Use this to define an execution contract for command handlers.
+
+### Errors
+
+#### `ParameterError`
+
+Thrown internally when parsing fails (missing values, invalid enums, duplicate directives).
+The interpreter returns `null` from `getParameters()`/`getGlobalOptions()` to preserve backward compatibility.
+
+### `Interpreter`
+
+#### Constructor
+
+```
+new Interpreter(program: Program, args: string[], console?: Console)
+```
+
+Creates a parser instance. Provide `args` (typically `process.argv.slice(2)`).
+
+#### `init()`
+
+```
+init(): boolean
+```
+
+Displays general help when no arguments are provided and returns `false`.
+
+#### `getCommand()`
+
+```
+getCommand(): Command | null
+```
+
+Returns the command matching the first argument (case-insensitive), or `null`.
+
+#### `getBanner()`
+
+```
+getBanner(): string
+```
+
+Returns a formatted banner string with title and version.
+
+#### `displayHelp(command?: string)`
+
+Displays general help and optionally an “unknown command” message.
+
+#### `displayCommandHelp(command: Command)`
+
+Shows command-specific usage, required arguments, options, and global options.
+
+#### `getParameters(command: Command)`
+
+```
+getParameters(command: Command): Parameters | null
+```
+
+Parses required arguments and command options. Returns `null` on validation failure.
+
+#### `getGlobalOptions()`
+
+```
+getGlobalOptions(): Parameters | null
+```
+
+Parses global options only. Returns `null` on validation failure.
+
+#### `setConsole(console: Console)`
+
+Replaces the internal console instance (useful for testing).
+
+

package/lib/cjs/index.js

@@ -0,0 +1,192 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Interpreter = exports.ParameterError = exports.ParameterType = void 0;
+const console_1 = __importDefault(require("@northern/console"));
+var ParameterType;
+(function (ParameterType) {
+    ParameterType["VALUE"] = "value";
+    ParameterType["SWITCH"] = "switch";
+    ParameterType["ENUM"] = "enum";
+})(ParameterType || (exports.ParameterType = ParameterType = {}));
+class ParameterError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ParameterError';
+    }
+}
+exports.ParameterError = ParameterError;
+const c = console;
+class Interpreter {
+    constructor(program, args, console) {
+        this.program = program;
+        this.args = args;
+        c.log(console_1.default);
+        this.console = console !== null && console !== void 0 ? console : (new console_1.default());
+    }
+    setConsole(console) {
+        this.console = console;
+    }
+    init() {
+        if (!this.args.length) {
+            this.displayHelp();
+            return false;
+        }
+        return true;
+    }
+    getCommand() {
+        var _a, _b;
+        const commandName = (_a = this.args[0]) === null || _a === void 0 ? void 0 : _a.trim().toLowerCase();
+        if (!commandName) {
+            return null;
+        }
+        return (_b = this.program.commands.find((cmd) => cmd.name.trim().toLowerCase() === commandName)) !== null && _b !== void 0 ? _b : null;
+    }
+    getBanner() {
+        return `<command>${this.program.title}</command> version <highlight>${this.program.version}</highlight>\n`;
+    }
+    displayHelp(command) {
+        this.console.write(this.getBanner());
+        if (command) {
+            this.console.write(`<error>Unknown command: '${command}'</error>\n`);
+        }
+        this.console.write(`<highlight>Usage:</highlight>\n  ${this.program.name} <command> [arguments] [options]\n`);
+        this.console.write('<highlight>>Available commands:</highlight>');
+        for (const cmd of this.program.commands) {
+            this.console.write(`  <command>${cmd.name.padEnd(30)}</command> ${cmd.description}`);
+        }
+        this.console.write('');
+        this.displayOptions(this.program.options, 'Global options:');
+    }
+    displayCommandHelp(command) {
+        this.console.write(this.getBanner());
+        this.console.write(`<error>Missing or invalid arguments for command: ${command.name}</error>\n`);
+        if (command.arguments && command.arguments.length > 0) {
+            this.console.write('<highlight>Example:</highlight>');
+            const exampleArgs = command.arguments.map((arg) => arg.example).join(' ');
+            this.console.write(`  ${command.name} ${exampleArgs}`);
+            this.console.write('');
+        }
+        this.console.write(`<highlight>Usage:</highlight>\n  ${this.program.name} ${command.name} [arguments] [options]\n`);
+        if (command.arguments && command.arguments.length > 0) {
+            this.console.write('<highlight>Arguments (required):</highlight>');
+            for (const arg of command.arguments) {
+                this.displayParameter(arg);
+            }
+            this.console.write('');
+        }
+        if (command.options && command.options.length > 0) {
+            this.displayOptions(command.options, 'Options:');
+        }
+        this.displayOptions(this.program.options, 'Global options:');
+    }
+    displayParameter(param) {
+        const directives = param.directives.join(', ').padEnd(30);
+        const values = param.values ? ` Possible values: ${param.values.join(', ')}` : '';
+        this.console.write(`  <command>${directives}</command> ${param.description}${values}`);
+    }
+    displayOptions(options, title) {
+        if (options.length === 0) {
+            return;
+        }
+        this.console.write(`<highlight>${title}</highlight>`);
+        for (const option of options) {
+            this.displayParameter(option);
+        }
+        this.console.write('');
+    }
+    getGlobalOptions() {
+        try {
+            const parameters = {};
+            for (const option of this.program.options) {
+                this.parseParameter(option, parameters, false);
+            }
+            return parameters;
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    getParameters(command) {
+        try {
+            const parameters = {};
+            if (command.arguments) {
+                for (const arg of command.arguments) {
+                    this.parseParameter(arg, parameters, true);
+                }
+            }
+            if (command.options) {
+                for (const option of command.options) {
+                    this.parseParameter(option, parameters, false);
+                }
+            }
+            return parameters;
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    parseParameter(param, parameters, required) {
+        const { directive, index } = this.findDirective(param.directives);
+        if (!directive) {
+            if (required) {
+                throw new ParameterError(`Missing required argument: ${param.name}`);
+            }
+            parameters[param.name] = param.default;
+            return;
+        }
+        const value = this.parseParameterValue(param, directive, index);
+        parameters[param.name] = value;
+    }
+    findDirective(directives) {
+        for (const directive of directives) {
+            const index = this.args.indexOf(directive);
+            if (index !== -1) {
+                const lastIndex = this.args.lastIndexOf(directive);
+                if (lastIndex !== index) {
+                    throw new ParameterError(`Directive '${directive}' specified multiple times`);
+                }
+                return { directive, index };
+            }
+        }
+        return { directive: null, index: -1 };
+    }
+    parseParameterValue(param, directive, index) {
+        switch (param.type) {
+            case ParameterType.SWITCH:
+                return true;
+            case ParameterType.VALUE: {
+                if (index + 1 >= this.args.length) {
+                    throw new ParameterError(`Directive '${directive}' requires a value`);
+                }
+                const value = this.args[index + 1];
+                if (value.startsWith('-')) {
+                    throw new ParameterError(`Directive '${directive}' requires a value, got '${value}'`);
+                }
+                if (value === '') {
+                    throw new ParameterError(`Directive '${directive}' requires a non-empty value`);
+                }
+                return value;
+            }
+            case ParameterType.ENUM: {
+                if (index + 1 >= this.args.length) {
+                    throw new ParameterError(`Directive '${directive}' requires a value`);
+                }
+                const value = this.args[index + 1];
+                if (!param.values || param.values.length === 0) {
+                    throw new ParameterError(`No valid values defined for '${param.name}'`);
+                }
+                if (!param.values.includes(value)) {
+                    const validValues = param.values.join(', ');
+                    throw new ParameterError(`Invalid value '${value}' for '${directive}'. Valid values: ${validValues}`);
+                }
+                return value;
+            }
+            default:
+                throw new ParameterError(`Unknown parameter type: ${param.type}`);
+        }
+    }
+}
+exports.Interpreter = Interpreter;

package/lib/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/lib/esm/index.js

@@ -0,0 +1,184 @@
+import Console from '@northern/console';
+export var ParameterType;
+(function (ParameterType) {
+    ParameterType["VALUE"] = "value";
+    ParameterType["SWITCH"] = "switch";
+    ParameterType["ENUM"] = "enum";
+})(ParameterType || (ParameterType = {}));
+export class ParameterError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ParameterError';
+    }
+}
+const c = console;
+export class Interpreter {
+    constructor(program, args, console) {
+        this.program = program;
+        this.args = args;
+        c.log(Console);
+        this.console = console !== null && console !== void 0 ? console : (new Console());
+    }
+    setConsole(console) {
+        this.console = console;
+    }
+    init() {
+        if (!this.args.length) {
+            this.displayHelp();
+            return false;
+        }
+        return true;
+    }
+    getCommand() {
+        var _a, _b;
+        const commandName = (_a = this.args[0]) === null || _a === void 0 ? void 0 : _a.trim().toLowerCase();
+        if (!commandName) {
+            return null;
+        }
+        return (_b = this.program.commands.find((cmd) => cmd.name.trim().toLowerCase() === commandName)) !== null && _b !== void 0 ? _b : null;
+    }
+    getBanner() {
+        return `<command>${this.program.title}</command> version <highlight>${this.program.version}</highlight>\n`;
+    }
+    displayHelp(command) {
+        this.console.write(this.getBanner());
+        if (command) {
+            this.console.write(`<error>Unknown command: '${command}'</error>\n`);
+        }
+        this.console.write(`<highlight>Usage:</highlight>\n  ${this.program.name} <command> [arguments] [options]\n`);
+        this.console.write('<highlight>>Available commands:</highlight>');
+        for (const cmd of this.program.commands) {
+            this.console.write(`  <command>${cmd.name.padEnd(30)}</command> ${cmd.description}`);
+        }
+        this.console.write('');
+        this.displayOptions(this.program.options, 'Global options:');
+    }
+    displayCommandHelp(command) {
+        this.console.write(this.getBanner());
+        this.console.write(`<error>Missing or invalid arguments for command: ${command.name}</error>\n`);
+        if (command.arguments && command.arguments.length > 0) {
+            this.console.write('<highlight>Example:</highlight>');
+            const exampleArgs = command.arguments.map((arg) => arg.example).join(' ');
+            this.console.write(`  ${command.name} ${exampleArgs}`);
+            this.console.write('');
+        }
+        this.console.write(`<highlight>Usage:</highlight>\n  ${this.program.name} ${command.name} [arguments] [options]\n`);
+        if (command.arguments && command.arguments.length > 0) {
+            this.console.write('<highlight>Arguments (required):</highlight>');
+            for (const arg of command.arguments) {
+                this.displayParameter(arg);
+            }
+            this.console.write('');
+        }
+        if (command.options && command.options.length > 0) {
+            this.displayOptions(command.options, 'Options:');
+        }
+        this.displayOptions(this.program.options, 'Global options:');
+    }
+    displayParameter(param) {
+        const directives = param.directives.join(', ').padEnd(30);
+        const values = param.values ? ` Possible values: ${param.values.join(', ')}` : '';
+        this.console.write(`  <command>${directives}</command> ${param.description}${values}`);
+    }
+    displayOptions(options, title) {
+        if (options.length === 0) {
+            return;
+        }
+        this.console.write(`<highlight>${title}</highlight>`);
+        for (const option of options) {
+            this.displayParameter(option);
+        }
+        this.console.write('');
+    }
+    getGlobalOptions() {
+        try {
+            const parameters = {};
+            for (const option of this.program.options) {
+                this.parseParameter(option, parameters, false);
+            }
+            return parameters;
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    getParameters(command) {
+        try {
+            const parameters = {};
+            if (command.arguments) {
+                for (const arg of command.arguments) {
+                    this.parseParameter(arg, parameters, true);
+                }
+            }
+            if (command.options) {
+                for (const option of command.options) {
+                    this.parseParameter(option, parameters, false);
+                }
+            }
+            return parameters;
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    parseParameter(param, parameters, required) {
+        const { directive, index } = this.findDirective(param.directives);
+        if (!directive) {
+            if (required) {
+                throw new ParameterError(`Missing required argument: ${param.name}`);
+            }
+            parameters[param.name] = param.default;
+            return;
+        }
+        const value = this.parseParameterValue(param, directive, index);
+        parameters[param.name] = value;
+    }
+    findDirective(directives) {
+        for (const directive of directives) {
+            const index = this.args.indexOf(directive);
+            if (index !== -1) {
+                const lastIndex = this.args.lastIndexOf(directive);
+                if (lastIndex !== index) {
+                    throw new ParameterError(`Directive '${directive}' specified multiple times`);
+                }
+                return { directive, index };
+            }
+        }
+        return { directive: null, index: -1 };
+    }
+    parseParameterValue(param, directive, index) {
+        switch (param.type) {
+            case ParameterType.SWITCH:
+                return true;
+            case ParameterType.VALUE: {
+                if (index + 1 >= this.args.length) {
+                    throw new ParameterError(`Directive '${directive}' requires a value`);
+                }
+                const value = this.args[index + 1];
+                if (value.startsWith('-')) {
+                    throw new ParameterError(`Directive '${directive}' requires a value, got '${value}'`);
+                }
+                if (value === '') {
+                    throw new ParameterError(`Directive '${directive}' requires a non-empty value`);
+                }
+                return value;
+            }
+            case ParameterType.ENUM: {
+                if (index + 1 >= this.args.length) {
+                    throw new ParameterError(`Directive '${directive}' requires a value`);
+                }
+                const value = this.args[index + 1];
+                if (!param.values || param.values.length === 0) {
+                    throw new ParameterError(`No valid values defined for '${param.name}'`);
+                }
+                if (!param.values.includes(value)) {
+                    const validValues = param.values.join(', ');
+                    throw new ParameterError(`Invalid value '${value}' for '${directive}'. Valid values: ${validValues}`);
+                }
+                return value;
+            }
+            default:
+                throw new ParameterError(`Unknown parameter type: ${param.type}`);
+        }
+    }
+}

package/lib/types/index.d.ts

@@ -0,0 +1,60 @@
+import Console from '@northern/console';
+export type OutputFunction = (...args: unknown[]) => void;
+export declare enum ParameterType {
+    VALUE = "value",
+    SWITCH = "switch",
+    ENUM = "enum"
+}
+type BaseParameter = {
+    name: string;
+    description: string;
+    type: ParameterType;
+    directives: string[];
+    example: string;
+    values?: string[];
+    value?: unknown;
+};
+export type Argument = BaseParameter;
+export type Option = BaseParameter & {
+    default: unknown;
+};
+export type Command = {
+    name: string;
+    description: string;
+    arguments?: Argument[];
+    options?: Option[];
+};
+export type Program = {
+    title: string;
+    version: string;
+    name: string;
+    options: Option[];
+    commands: Command[];
+};
+export type Parameters = Record<string, unknown>;
+export interface ICommand {
+    run(parameters: Parameters): Promise<unknown>;
+}
+export declare class ParameterError extends Error {
+    constructor(message: string);
+}
+export declare class Interpreter {
+    private readonly program;
+    private readonly args;
+    private console;
+    constructor(program: Program, args: string[], console?: Console);
+    setConsole(console: Console): void;
+    init(): boolean;
+    getCommand(): Command | null;
+    getBanner(): string;
+    displayHelp(command?: string): void;
+    displayCommandHelp(command: Command): void;
+    private displayParameter;
+    private displayOptions;
+    getGlobalOptions(): Parameters | null;
+    getParameters(command: Command): Parameters | null;
+    private parseParameter;
+    private findDirective;
+    private parseParameterValue;
+}
+export {};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@northern/cli",
+  "version": "1.0.0",
+  "description": "A lightweight CLI program framework.",
+  "main": "./lib/cjs/index.js",
+  "module": "./lib/esm/index.js",
+  "types": "./lib/types/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "import": "./lib/esm/index.js",
+      "require": "./lib/cjs/index.js"
+    }
+  },
+  "files": [
+    "lib/**/*"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs && npm run build:types && npm run build:cjs-package",
+    "build:esm": "tsc --project tsconfig.esm.json --removeComments",
+    "build:cjs": "tsc --project tsconfig.cjs.json --removeComments",
+    "build:types": "tsc --project tsconfig.types.json --removeComments",
+    "build:cjs-package": "echo '{\"type\":\"commonjs\"}' > lib/cjs/package.json",
+    "test": "jest",
+    "test:watch": "jest --watch --no-coverage",
+    "test:coverage": "jest --coverage",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/northern/cli.git"
+  },
+  "keywords": [
+    "console",
+    "terminal",
+    "cli",
+    "framework"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "author": "northern",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/northern/cli/issues"
+  },
+  "homepage": "https://github.com/northern/cli#readme",
+  "devDependencies": {
+    "@types/jest": "^29",
+    "jest": "^29",
+    "ts-jest": "^29",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@northern/console": "^1"
+  }
+}