@open-nav/cli 0.1.0

package/src/config.ts

@@ -0,0 +1,246 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import type { SoftwareType } from '@open-nav/core';
+import type { NavCredentials } from '@open-nav/client';
+import { UsageError } from './errors.js';
+import { VERSION } from './version.js';
+
+/**
+ * Configuration comes from the environment, optionally seeded from a local
+ * env file. Credentials are never accepted as command line arguments: they
+ * would end up in shell history, in process listings and in any agent
+ * transcript that records the command.
+ */
+export const ENV_VARS = {
+  environment: 'NAV_ENVIRONMENT',
+  login: 'NAV_LOGIN',
+  password: 'NAV_PASSWORD',
+  signKey: 'NAV_SIGN_KEY',
+  exchangeKey: 'NAV_EXCHANGE_KEY',
+  taxNumber: 'NAV_TAX_NUMBER',
+  softwareId: 'NAV_SOFTWARE_ID',
+  softwareName: 'NAV_SOFTWARE_NAME',
+  softwareVersion: 'NAV_SOFTWARE_VERSION',
+  softwareDevName: 'NAV_SOFTWARE_DEV_NAME',
+  softwareDevContact: 'NAV_SOFTWARE_DEV_CONTACT',
+  softwareDevTaxNumber: 'NAV_SOFTWARE_DEV_TAX_NUMBER',
+  softwareOperation: 'NAV_SOFTWARE_OPERATION',
+  baseUrl: 'NAV_BASE_URL',
+} as const;
+
+/** Variables that hold secrets and must never be printed. */
+export const SECRET_VARS = new Set<string>([
+  ENV_VARS.password,
+  ENV_VARS.signKey,
+  ENV_VARS.exchangeKey,
+]);
+
+const ENV_FILE_NAMES = ['.env.open-nav', '.env.local', '.env'];
+
+/** Variables without which nothing can talk to NAV. */
+export const REQUIRED_VARS: readonly string[] = [
+  ENV_VARS.login,
+  ENV_VARS.password,
+  ENV_VARS.signKey,
+  ENV_VARS.exchangeKey,
+  ENV_VARS.taxNumber,
+  ENV_VARS.softwareId,
+];
+
+/** Defaults applied when an optional variable is unset. */
+export const DEFAULTS: Readonly<Record<string, string>> = {
+  [ENV_VARS.environment]: 'test',
+  [ENV_VARS.softwareName]: 'open-nav',
+  [ENV_VARS.softwareVersion]: VERSION,
+  [ENV_VARS.softwareOperation]: 'LOCAL_SOFTWARE',
+  [ENV_VARS.softwareDevName]: 'open-nav',
+  [ENV_VARS.softwareDevContact]: 'unknown',
+};
+
+export interface LoadedConfig {
+  credentials: NavCredentials;
+  software: SoftwareType;
+  environment: 'test' | 'production';
+  baseUrl?: string;
+  /** Env files that were read, nearest first. */
+  envFiles: string[];
+}
+
+/**
+ * Parse a `.env` file.
+ *
+ * Deliberately minimal: `KEY=value`, `#` comments, optional `export`, and
+ * single or double quotes stripped. Anything more elaborate belongs in a real
+ * secret manager, not in a file next to the source.
+ */
+export function parseEnvFile(contents: string): Record<string, string> {
+  const values: Record<string, string> = {};
+  for (const rawLine of contents.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line === '' || line.startsWith('#')) continue;
+    const withoutExport = line.startsWith('export ') ? line.slice('export '.length) : line;
+    const separator = withoutExport.indexOf('=');
+    if (separator === -1) continue;
+    const key = withoutExport.slice(0, separator).trim();
+    let value = withoutExport.slice(separator + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"') && value.length > 1) ||
+      (value.startsWith("'") && value.endsWith("'") && value.length > 1)
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (key !== '') values[key] = value;
+  }
+  return values;
+}
+
+/**
+ * Find env files, walking up from a starting directory.
+ *
+ * Walking up means a project-level env file is picked up from any
+ * subdirectory, which is how an agent invoked in a nested working directory
+ * still finds the credentials.
+ */
+export function discoverEnvFiles(from: string): string[] {
+  const found: string[] = [];
+  let directory = resolve(from);
+  for (;;) {
+    for (const name of ENV_FILE_NAMES) {
+      const candidate = resolve(directory, name);
+      if (existsSync(candidate)) found.push(candidate);
+    }
+    const parent = dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  return found;
+}
+
+export interface LoadOptions {
+  /** Explicit env file, from `--env-file`. Takes precedence over discovery. */
+  envFile?: string;
+  /** Where to start looking. Defaults to the working directory. */
+  cwd?: string;
+  /** Process environment. Injectable for tests. */
+  env?: Record<string, string | undefined>;
+  /** Skip env file discovery entirely. */
+  noEnvFile?: boolean;
+}
+
+/** Read the environment, seeded from env files, without requiring credentials. */
+export function loadEnvironment(options: LoadOptions = {}): {
+  env: Record<string, string | undefined>;
+  envFiles: string[];
+} {
+  const base = { ...(options.env ?? process.env) };
+  const envFiles: string[] = [];
+
+  if (options.envFile) {
+    if (!existsSync(options.envFile)) {
+      throw new UsageError(`Env file not found: ${options.envFile}`);
+    }
+    envFiles.push(resolve(options.envFile));
+  } else if (!options.noEnvFile) {
+    envFiles.push(...discoverEnvFiles(options.cwd ?? process.cwd()));
+  }
+
+  // Real environment variables win over files, and a nearer file wins over a
+  // more distant one.
+  for (const file of envFiles) {
+    for (const [key, value] of Object.entries(parseEnvFile(readFileSync(file, 'utf8')))) {
+      base[key] ??= value;
+    }
+  }
+
+  return { env: base, envFiles };
+}
+
+export interface ConfigVariableReport {
+  variable: string;
+  set: boolean;
+  required: boolean;
+  secret: boolean;
+  /** Present for non-secret variables that are set. */
+  value?: string;
+  /** Value that applies when the variable is left unset. */
+  default?: string;
+}
+
+/**
+ * Which configuration variables are present, for the `config` command.
+ *
+ * Required and optional are reported separately: an unset optional variable
+ * with a working default is not a problem, and listing it as "missing" sends
+ * people hunting for something that is not wrong.
+ */
+export function describeConfig(env: Record<string, string | undefined>): ConfigVariableReport[] {
+  return Object.values(ENV_VARS).map((variable) => {
+    const value = env[variable];
+    const secret = SECRET_VARS.has(variable);
+    const set = value !== undefined && value !== '';
+    const fallback = DEFAULTS[variable];
+    return {
+      variable,
+      set,
+      required: REQUIRED_VARS.includes(variable),
+      secret,
+      ...(set && !secret ? { value } : {}),
+      ...(!set && fallback !== undefined ? { default: fallback } : {}),
+    };
+  });
+}
+
+/**
+ * Assemble the full configuration, failing with a list of everything missing
+ * rather than one variable at a time.
+ */
+export function loadConfig(options: LoadOptions = {}): LoadedConfig {
+  const { env, envFiles } = loadEnvironment(options);
+
+  const missing = REQUIRED_VARS.filter((variable) => !env[variable]);
+  if (missing.length > 0) {
+    throw new UsageError(
+      `Missing configuration: ${missing.join(', ')}.\n` +
+        `Set them in the environment or in a .env file, then run "open-nav config" to check.\n` +
+        `See "open-nav help config" for the full list.`,
+    );
+  }
+
+  const environmentRaw = env[ENV_VARS.environment] ?? 'test';
+  if (environmentRaw !== 'test' && environmentRaw !== 'production') {
+    throw new UsageError(
+      `${ENV_VARS.environment} must be "test" or "production", got ${JSON.stringify(environmentRaw)}`,
+    );
+  }
+
+  const operationRaw = env[ENV_VARS.softwareOperation] ?? 'LOCAL_SOFTWARE';
+  if (operationRaw !== 'LOCAL_SOFTWARE' && operationRaw !== 'ONLINE_SERVICE') {
+    throw new UsageError(
+      `${ENV_VARS.softwareOperation} must be "LOCAL_SOFTWARE" or "ONLINE_SERVICE", got ${JSON.stringify(operationRaw)}`,
+    );
+  }
+
+  return {
+    credentials: {
+      login: env[ENV_VARS.login]!,
+      password: env[ENV_VARS.password]!,
+      signKey: env[ENV_VARS.signKey]!,
+      exchangeKey: env[ENV_VARS.exchangeKey]!,
+      taxNumber: env[ENV_VARS.taxNumber]!,
+    },
+    software: {
+      softwareId: env[ENV_VARS.softwareId]!,
+      softwareName: env[ENV_VARS.softwareName] ?? 'open-nav',
+      softwareOperation: operationRaw,
+      softwareMainVersion: env[ENV_VARS.softwareVersion] ?? VERSION,
+      softwareDevName: env[ENV_VARS.softwareDevName] ?? 'open-nav',
+      softwareDevContact: env[ENV_VARS.softwareDevContact] ?? 'unknown',
+      ...(env[ENV_VARS.softwareDevTaxNumber]
+        ? { softwareDevTaxNumber: env[ENV_VARS.softwareDevTaxNumber] }
+        : {}),
+    },
+    environment: environmentRaw,
+    ...(env[ENV_VARS.baseUrl] ? { baseUrl: env[ENV_VARS.baseUrl] } : {}),
+    envFiles,
+  };
+}

package/src/errors.ts

@@ -0,0 +1,27 @@
+/**
+ * Exit codes, so a caller — a shell script or an agent — can branch on the
+ * outcome without parsing the output.
+ */
+export const EXIT = {
+  ok: 0,
+  /** Something went wrong that the tool did not anticipate. */
+  failure: 1,
+  /** The command line or configuration was wrong. */
+  usage: 2,
+  /** A document failed local validation and was not sent. */
+  invalid: 3,
+  /** NAV rejected the request or the invoices in it. */
+  rejected: 4,
+  /**
+   * The work could not be completed because something it depends on was
+   * unavailable: the network, a NAV verdict that has not arrived, or a
+   * browser to convert a document with.
+   */
+  unavailable: 5,
+} as const;
+
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+
+export class UsageError extends Error {
+  readonly exitCode = EXIT.usage;
+}

package/src/main.ts

@@ -0,0 +1,264 @@
+import { parseArgs } from 'node:util';
+import { NavApiError, NavTransportError, NavValidationError } from '@open-nav/core';
+import { PdfConversionError, ThemeError } from '@open-nav/invoicing';
+import { COMMANDS, describeCommands, findCommand, type CommandContext } from './commands.js';
+import { ENV_VARS } from './config.js';
+import { EXIT, UsageError, type ExitCode } from './errors.js';
+import { consoleWriter, resolveFormat, writeError, type Format, type Writer } from './output.js';
+import { VERSION } from './version.js';
+
+export interface RunOptions {
+  argv: string[];
+  writer?: Writer;
+  /** Whether stdout is a terminal, which decides the default output format. */
+  isTty?: boolean;
+  env?: Record<string, string | undefined>;
+  cwd?: string;
+  readFile?: (path: string) => string;
+  writeFile?: (path: string, contents: string) => void;
+  writeBinaryFile?: (path: string, contents: Buffer) => void;
+  readBinaryFile?: (path: string) => Buffer;
+  fileExists?: (path: string) => boolean;
+}
+
+const GLOBAL_OPTIONS = {
+  json: { type: 'boolean' },
+  pretty: { type: 'boolean' },
+  'env-file': { type: 'string' },
+  'no-env-file': { type: 'boolean' },
+  help: { type: 'boolean', short: 'h' },
+  version: { type: 'boolean' },
+  describe: { type: 'boolean' },
+} as const;
+
+/**
+ * Run the CLI and return an exit code.
+ *
+ * Everything is injectable so the whole surface can be tested without
+ * spawning a process or touching the filesystem.
+ */
+export async function run(options: RunOptions): Promise<ExitCode> {
+  const writer = options.writer ?? consoleWriter;
+
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: options.argv,
+      options: {
+        ...GLOBAL_OPTIONS,
+        // Command options are accepted loosely here and validated by the
+        // command, so a new option never needs registering in two places.
+        operation: { type: 'string' },
+        language: { type: 'string' },
+        direction: { type: 'string' },
+        supplier: { type: 'string' },
+        from: { type: 'string' },
+        to: { type: 'string' },
+        page: { type: 'string' },
+        wait: { type: 'boolean' },
+        compress: { type: 'boolean' },
+        xml: { type: 'boolean' },
+        'skip-validation': { type: 'boolean' },
+        out: { type: 'string' },
+        note: { type: 'string' },
+        pdf: { type: 'string' },
+        theme: { type: 'string' },
+        logo: { type: 'string' },
+        browser: { type: 'string' },
+        'no-sandbox': { type: 'boolean' },
+        engine: { type: 'string' },
+        delay: { type: 'string' },
+        refresh: { type: 'boolean' },
+        'number-from': { type: 'string' },
+        'number-to': { type: 'string' },
+        'warnings-as-errors': { type: 'boolean' },
+      },
+      allowPositionals: true,
+      strict: true,
+    });
+  } catch (cause) {
+    writer.err((cause as Error).message);
+    writer.err('Run "open-nav --help" for usage.');
+    return EXIT.usage;
+  }
+
+  const flags = parsed.values as Record<string, string | boolean | undefined>;
+  const explicitFormat: Format | undefined =
+    flags['json'] === true ? 'json' : flags['pretty'] === true ? 'text' : undefined;
+  const format = resolveFormat(explicitFormat, options.isTty ?? false);
+
+  if (flags['describe'] === true) {
+    writer.out(JSON.stringify(describeCommands(), null, 2));
+    return EXIT.ok;
+  }
+
+  if (flags['version'] === true) {
+    writer.out(VERSION);
+    return EXIT.ok;
+  }
+
+  const [commandName, ...positionals] = parsed.positionals;
+
+  if (flags['help'] === true || commandName === undefined || commandName === 'help') {
+    const topic = commandName === 'help' ? positionals[0] : undefined;
+    writeHelp(writer, topic);
+    return commandName === undefined && flags['help'] !== true ? EXIT.usage : EXIT.ok;
+  }
+
+  const command = findCommand(commandName);
+  if (!command) {
+    writer.err(`Unknown command: ${commandName}`);
+    writer.err(`Available: ${COMMANDS.map((entry) => entry.name).join(', ')}`);
+    return EXIT.usage;
+  }
+
+  const context: CommandContext = {
+    format,
+    writer,
+    load: {
+      ...(flags['env-file'] ? { envFile: String(flags['env-file']) } : {}),
+      ...(flags['no-env-file'] === true ? { noEnvFile: true } : {}),
+      ...(options.env ? { env: options.env } : {}),
+      ...(options.cwd ? { cwd: options.cwd } : {}),
+    },
+    ...(options.readFile ? { readFile: options.readFile } : {}),
+    ...(options.writeFile ? { writeFile: options.writeFile } : {}),
+    ...(options.writeBinaryFile ? { writeBinaryFile: options.writeBinaryFile } : {}),
+    ...(options.readBinaryFile ? { readBinaryFile: options.readBinaryFile } : {}),
+    ...(options.fileExists ? { fileExists: options.fileExists } : {}),
+  };
+
+  try {
+    return await command.run(positionals, flags, context);
+  } catch (error) {
+    return reportError(writer, format, command.name, error);
+  }
+}
+
+function reportError(writer: Writer, format: Format, command: string, error: unknown): ExitCode {
+  if (error instanceof UsageError) {
+    writeError(writer, format, command, { message: error.message, code: 'USAGE' });
+    return EXIT.usage;
+  }
+  if (error instanceof NavApiError) {
+    writeError(writer, format, command, {
+      message: error.message,
+      ...(error.errorCode ? { code: error.errorCode } : {}),
+      details: {
+        status: error.status,
+        funcCode: error.funcCode,
+        validationMessages: error.validationMessages,
+      },
+    });
+    return EXIT.rejected;
+  }
+  if (error instanceof NavValidationError) {
+    writeError(writer, format, command, {
+      message: error.message,
+      code: 'INVALID',
+      details: error.issues,
+    });
+    return EXIT.invalid;
+  }
+  if (error instanceof NavTransportError) {
+    writeError(writer, format, command, { message: error.message, code: 'UNAVAILABLE' });
+    return EXIT.unavailable;
+  }
+  if (error instanceof ThemeError) {
+    // A malformed theme is a configuration mistake, like a bad flag.
+    writeError(writer, format, command, { message: error.message, code: 'THEME' });
+    return EXIT.usage;
+  }
+  if (error instanceof PdfConversionError) {
+    // Nothing wrong with the document; the machine lacks a browser.
+    writeError(writer, format, command, { message: error.message, code: 'PDF_CONVERSION' });
+    return EXIT.unavailable;
+  }
+  writeError(writer, format, command, { message: (error as Error).message ?? String(error) });
+  return EXIT.failure;
+}
+
+function writeHelp(writer: Writer, topic: string | undefined): void {
+  if (topic === 'config') {
+    writer.out('Configuration is read from the environment, or from a .env file');
+    writer.out('discovered by walking up from the working directory.');
+    writer.out('');
+    writer.out('Required:');
+    for (const variable of [
+      ENV_VARS.login,
+      ENV_VARS.password,
+      ENV_VARS.signKey,
+      ENV_VARS.exchangeKey,
+      ENV_VARS.taxNumber,
+      ENV_VARS.softwareId,
+    ]) {
+      writer.out(`  ${variable}`);
+    }
+    writer.out('');
+    writer.out('Optional:');
+    for (const variable of [
+      ENV_VARS.environment,
+      ENV_VARS.softwareName,
+      ENV_VARS.softwareVersion,
+      ENV_VARS.softwareOperation,
+      ENV_VARS.softwareDevName,
+      ENV_VARS.softwareDevContact,
+      ENV_VARS.softwareDevTaxNumber,
+      ENV_VARS.baseUrl,
+    ]) {
+      writer.out(`  ${variable}`);
+    }
+    writer.out('');
+    writer.out(`${ENV_VARS.environment} defaults to "test". Set it to "production" deliberately.`);
+    writer.out(`${ENV_VARS.taxNumber} is the 8 digit core tax number, not the 11 digit form.`);
+    writer.out('');
+    writer.out('Credentials are never taken as command line arguments: they would');
+    writer.out('be recorded in shell history, process listings and agent transcripts.');
+    return;
+  }
+
+  if (topic !== undefined) {
+    const command = findCommand(topic);
+    if (!command) {
+      writer.err(`Unknown command: ${topic}`);
+      return;
+    }
+    writer.out(command.summary);
+    writer.out('');
+    writer.out(`  ${command.usage}`);
+    if (command.options && command.options.length > 0) {
+      writer.out('');
+      const width = Math.max(...command.options.map((option) => option.flag.length));
+      for (const option of command.options) {
+        writer.out(`  ${option.flag.padEnd(width)}  ${option.description}`);
+      }
+    }
+    if (command.needsCredentials) {
+      writer.out('');
+      writer.out('Needs credentials. Run "open-nav config" to check them.');
+    }
+    return;
+  }
+
+  writer.out('open-nav — command line access to the NAV Online Számla invoice service');
+  writer.out('');
+  writer.out('  open-nav <command> [options]');
+  writer.out('');
+  const width = Math.max(...COMMANDS.map((command) => command.name.length));
+  for (const command of COMMANDS) {
+    writer.out(`  ${command.name.padEnd(width)}  ${command.summary}`);
+  }
+  writer.out('');
+  writer.out('Options:');
+  writer.out('  --json              Output JSON (the default when not a terminal)');
+  writer.out('  --pretty            Output human readable text');
+  writer.out('  --env-file <path>   Read configuration from this file');
+  writer.out('  --no-env-file       Ignore .env files entirely');
+  writer.out('  --describe          Print the command surface as JSON, for tooling');
+  writer.out('  --version           Print the version');
+  writer.out('');
+  writer.out('Exit codes: 0 ok, 2 usage, 3 invalid document, 4 rejected by NAV, 5 unavailable.');
+  writer.out('');
+  writer.out('Help on a command:      open-nav help <command>');
+  writer.out('Help on configuration:  open-nav help config');
+}

package/src/output.ts

@@ -0,0 +1,85 @@
+import type { InvoiceValidationIssue } from '@open-nav/core';
+
+/**
+ * Output format.
+ *
+ * JSON is the default whenever output is not a terminal, so a program or an
+ * agent calling this tool always gets something parseable without having to
+ * remember a flag. A human at a terminal gets readable text.
+ */
+export type Format = 'json' | 'text';
+
+export function resolveFormat(explicit: Format | undefined, isTty: boolean): Format {
+  return explicit ?? (isTty ? 'text' : 'json');
+}
+
+export interface Writer {
+  out: (line: string) => void;
+  err: (line: string) => void;
+}
+
+export const consoleWriter: Writer = {
+  out: (line) => process.stdout.write(`${line}\n`),
+  err: (line) => process.stderr.write(`${line}\n`),
+};
+
+/** Envelope every JSON result shares, so callers can branch on `ok` alone. */
+export interface ResultEnvelope {
+  ok: boolean;
+  command: string;
+  data?: unknown;
+  error?: { message: string; code?: string; details?: unknown };
+}
+
+export function writeResult(
+  writer: Writer,
+  format: Format,
+  command: string,
+  data: unknown,
+  renderText: (data: never) => string[],
+): void {
+  if (format === 'json') {
+    const envelope: ResultEnvelope = { ok: true, command, data };
+    writer.out(JSON.stringify(envelope, null, 2));
+    return;
+  }
+  for (const line of renderText(data as never)) writer.out(line);
+}
+
+export function writeError(
+  writer: Writer,
+  format: Format,
+  command: string,
+  error: { message: string; code?: string; details?: unknown },
+): void {
+  if (format === 'json') {
+    const envelope: ResultEnvelope = { ok: false, command, error };
+    writer.out(JSON.stringify(envelope, null, 2));
+    return;
+  }
+  writer.err(error.code ? `${error.code}: ${error.message}` : error.message);
+  if (error.details !== undefined) {
+    writer.err(
+      typeof error.details === 'string' ? error.details : JSON.stringify(error.details, null, 2),
+    );
+  }
+}
+
+/** Render validation issues as aligned text. */
+export function renderIssues(issues: InvoiceValidationIssue[]): string[] {
+  return issues.map((issue) => {
+    const marker = issue.severity === 'error' ? 'error' : 'warn ';
+    const nav = issue.navMessage ? `\n         NAV: ${issue.navMessage}` : '';
+    return `  ${marker}  ${issue.code}\n         ${issue.path}\n         ${issue.message}${nav}`;
+  });
+}
+
+/** A compact `key: value` block. */
+export function renderFields(
+  fields: Array<[string, string | number | boolean | undefined]>,
+): string[] {
+  const width = Math.max(...fields.map(([label]) => label.length));
+  return fields
+    .filter(([, value]) => value !== undefined)
+    .map(([label, value]) => `  ${label.padEnd(width)}  ${String(value)}`);
+}

package/src/version.ts

@@ -0,0 +1,10 @@
+import { createRequire } from 'node:module';
+
+/**
+ * The package's own version, read from its manifest rather than duplicated
+ * here. A hardcoded copy is a release-day footgun: it drifts silently, and
+ * the first thing a bug report quotes is `open-nav --version`.
+ */
+export const VERSION: string = (
+  createRequire(import.meta.url)('../package.json') as { version: string }
+).version;