@anarchitects/governance-cli 0.0.1

package/README.md

@@ -0,0 +1,137 @@
+# `@anarchitects/governance-cli`
+
+Standalone Governance CLI and runtime host for running Governance checks outside Nx.
+
+## Overview
+
+`@anarchitects/governance-cli` provides the packaged `agov` executable and the programmatic host APIs for running Governance checks against canonical workspace documents or dynamically loaded adapters.
+
+The package depends on `@anarchitects/governance-core` and stays adapter-agnostic. Concrete adapters are loaded by package name and validated against Core-owned contracts at runtime.
+
+## Responsibilities
+
+This package is responsible for:
+
+- exposing the `agov` command surface
+- parsing arguments and resolving option precedence
+- loading config, profile, and canonical workspace inputs
+- discovering generic adapter candidates from config or package metadata
+- dynamically loading adapter packages and selecting them through Core-owned probe contracts
+- rendering table, markdown, text, and JSON output
+- mapping runtime outcomes to stable exit codes
+
+This package is not responsible for:
+
+- canonical Governance contracts
+- concrete adapter implementations
+- TypeScript-specific adapter detection heuristics
+- Nx graph loading
+- Nx plugin runtime behavior
+- Nx executors or generators
+
+## Public API
+
+The public package surface is intentionally small:
+
+```ts
+import {
+  runAgovCheck,
+  type AgovCheckOptions,
+  type AgovCheckResult,
+  type AgovCheckWithAdapterOptions,
+  type AgovCheckWithWorkspacePathOptions,
+} from '@anarchitects/governance-cli';
+```
+
+The root export currently includes:
+
+- `runAgovCheck(...)`
+- `AgovCheckOptions`
+- `AgovCheckResult`
+- `AgovCheckWithAdapterOptions`
+- `AgovCheckWithWorkspacePathOptions`
+
+The executable command parser and runtime host internals remain internal modules.
+
+## Executable Usage
+
+This package publishes an `agov` executable through `package.json#bin`.
+
+Current command surface:
+
+- `agov --help`
+- `agov --version`
+- `agov check`
+- `agov check --workspace <path> --profile <path>`
+- `agov check --adapter <package> --root <path> --profile <path>`
+
+The CLI resolves values in this order:
+
+- explicit flags
+- config file
+- conventional file discovery
+- generic adapter candidate discovery and probe-based selection
+- error with guidance
+
+## Runtime Modes
+
+The standalone host currently supports:
+
+- canonical workspace documents in `.json`, `.yaml`, or `.yml`
+- standalone profile documents in `.json`
+- explicit adapter mode through `--adapter <package> --root <path>`
+- generic adapter candidate discovery through config or package metadata
+- output formats `table`, `markdown`, and `json`
+- `text` as a compatibility alias for `table`
+
+Example programmatic usage:
+
+```ts
+import { runAgovCheck } from '@anarchitects/governance-cli';
+
+const result = runAgovCheck({
+  workspacePath: './governance.workspace.json',
+  profilePath: './governance.profile.json',
+});
+
+console.log(result.success);
+console.log(result.assessment.health.status);
+```
+
+## Adapter Model
+
+`@anarchitects/governance-cli` is adapter-agnostic.
+
+That means:
+
+- the package depends on `@anarchitects/governance-core`, not on concrete adapter packages
+- concrete adapters implement Core-owned contracts
+- adapters may be injected, discovered, or dynamically loaded by package name
+- future adapters must not require CLI package dependency changes
+
+If you want to use a concrete adapter such as `@anarchitects/governance-adapter-typescript`, that adapter must be installed separately in the consuming workspace.
+
+For detailed package-boundary rules and adapter-loading expectations, see
+[ADR 0001: Governance Package Boundaries for Core, CLI, Adapters, and Extensions](../../../docs/adr/0001-governance-package-boundaries.md).
+
+## Package Boundaries
+
+`@anarchitects/governance-cli` is a standalone runtime host.
+
+It should:
+
+- orchestrate Core-owned contracts
+- own command behavior, configuration, and output
+- remain reusable outside Nx
+
+It should not:
+
+- become the home of canonical Governance contracts
+- statically import concrete adapter packages
+- own adapter-specific detection heuristics
+- take on Nx-only responsibilities
+
+## Related Packages
+
+- `@anarchitects/governance-core` owns canonical Governance contracts and deterministic evaluation logic
+- `@anarchitects/governance-adapter-typescript` is a sibling concrete adapter package for TypeScript workspace discovery

package/dist/agov.d.ts

@@ -0,0 +1,71 @@
+import { Violation } from '@anarchitects/governance-core';
+import { AgovCheckOptions, AgovCheckResult } from './check.js';
+import { AgovOutputFormat } from './render-report.js';
+export interface AgovCliIo {
+    stdout(message: string): void;
+    stderr(message: string): void;
+}
+export interface AgovCliEnvironment {
+    cwd(): string;
+    moduleLoader(specifier: string): Promise<unknown>;
+    packageVersion(): string;
+}
+type MaybePromise<T> = T | Promise<T>;
+export interface AgovCliRuntime {
+    runAgovCheck<TInput = unknown>(options: AgovCheckOptions<TInput>): MaybePromise<AgovCheckResult>;
+}
+export interface AgovCliConfig {
+    profile?: string;
+    adapter?: string;
+    adapters?: string[];
+    root?: string;
+    workspace?: string;
+    format?: string;
+    output?: string;
+}
+export interface ParsedAgovCheckOptions {
+    command: 'check';
+    configPath?: string;
+    profilePath?: string;
+    workspacePath?: string;
+    adapterPackage?: string;
+    rootPath?: string;
+    format?: AgovOutputFormat;
+    outputPath?: string;
+    showHelp: boolean;
+}
+export interface AgovResolvedCheckCommand {
+    command: 'check';
+    rootPath: string;
+    profilePath: string;
+    format: AgovOutputFormat;
+    outputPath?: string;
+    configPath?: string;
+    mode: 'workspace' | 'adapter' | 'adapter-discovery';
+    workspacePath?: string;
+    adapterPackage?: string;
+    adapterCandidates?: string[];
+}
+export declare const AGOV_EXIT_SUCCESS = 0;
+export declare const AGOV_EXIT_GOVERNANCE_FAILURE = 1;
+export declare const AGOV_EXIT_CONFIGURATION_FAILURE = 2;
+export declare const AGOV_EXIT_RUNTIME_FAILURE = 3;
+export declare class AgovCliUsageError extends Error {
+    readonly code: 'agov.cli.unknown_command' | 'agov.cli.unknown_option' | 'agov.cli.missing_option_value' | 'agov.cli.unsupported_format' | 'agov.cli.missing_profile' | 'agov.cli.missing_workspace_or_adapter' | 'agov.cli.ambiguous_workspace_and_adapter' | 'agov.cli.invalid_config' | 'agov.cli.invalid_json';
+    constructor(message: string, code: 'agov.cli.unknown_command' | 'agov.cli.unknown_option' | 'agov.cli.missing_option_value' | 'agov.cli.unsupported_format' | 'agov.cli.missing_profile' | 'agov.cli.missing_workspace_or_adapter' | 'agov.cli.ambiguous_workspace_and_adapter' | 'agov.cli.invalid_config' | 'agov.cli.invalid_json');
+}
+export declare class AgovCliOutputError extends Error {
+    readonly code: 'agov.cli.output_write_failed';
+    readonly filePath: string;
+    constructor(message: string, code: 'agov.cli.output_write_failed', filePath: string);
+}
+export declare class AgovCliRuntimeError extends Error {
+    readonly code: 'agov.cli.adapter_not_found' | 'agov.cli.adapter_contract_mismatch' | 'agov.cli.no_supported_adapter' | 'agov.cli.unhandled_error';
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: 'agov.cli.adapter_not_found' | 'agov.cli.adapter_contract_mismatch' | 'agov.cli.no_supported_adapter' | 'agov.cli.unhandled_error', details?: Record<string, unknown> | undefined);
+}
+export declare function runAgovCli(argv: string[], io?: AgovCliIo, runtime?: AgovCliRuntime, environment?: AgovCliEnvironment): Promise<number>;
+export declare function resolveAgovCheckCommand(options: ParsedAgovCheckOptions, environment: Pick<AgovCliEnvironment, 'cwd'>): AgovResolvedCheckCommand;
+export declare function compareViolationsForBlocking(violations: readonly Violation[]): boolean;
+export {};
+//# sourceMappingURL=agov.d.ts.map

package/dist/agov.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agov.d.ts","sourceRoot":"","sources":["../src/agov.ts"],"names":[],"mappings":"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"}

package/dist/bin/agov.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=agov.d.ts.map

package/dist/bin/agov.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agov.d.ts","sourceRoot":"","sources":["../../src/bin/agov.ts"],"names":[],"mappings":""}