IF Commons GitHub

Headless

The contract of a program that has no window, in layers: governance (what an action is and may do: its kind, effect, audience, confirmation, the problems it finds, the one table of exit statuses, redaction), the logical layer (the command model, the typed outcome, the closing block, JSON and SARIF, explain, hints, nested runs) and surfaces that draw it, of which the command line is the first (calm output, prompts, the run log, signals, generated help, completions and man pages; the tool server, the REST skeleton and the credential prompt are beside it). An optional OpenTelemetry adapter has an entry of its own. Composition builds one program from a host and plugin packages (compose), audience tiers decide which verbs a caller sees (tierGate), the credential port asks for a passphrase once per command and keeps it in memory only, and the executor runs a plan in check or apply mode with a hash a signature can cover. Published to npm as compiled modules with their declarations; it depends on Core, the terminal and the system, and on the telemetry only for the adapter.

FactValue
Version0.5.7
Conformance levelL1
Distributedgithub, npm
LicensePolyForm-Noncommercial-1.0.0, source-available: free for noncommercial use, commercial use needs a license from the owner (see Licensing in Start here)
Import it as@intellectual-frontiers/headless

Areas

Layers

LayerFolderMay import of this library
governancesrc/governance/nothing
logicalsrc/logical/governance
physicalsrc/surfaces/cli/src/governance/, src/logical/
physicalsrc/surfaces/ssh-inbound/src/governance/, src/logical/
physicalsrc/surfaces/askpass/src/governance/, src/logical/
physicalsrc/surfaces/mcp/src/governance/, src/logical/
physicalsrc/surfaces/rest/src/governance/, src/logical/
physicalsrc/targets/local/src/governance/, src/logical/
physicalsrc/targets/container/src/governance/, src/logical/
physicalsrc/targets/ssh/src/governance/, src/logical/
physicalsrc/otel/src/governance/, src/logical/, src/surfaces/cli/
physicalsrc/describe/src/governance/, src/logical/, src/surfaces/mcp/, src/surfaces/rest/

Imports

Core, Kanon, System, Telemetry, Terminal

Imported by

AnyFS command line, AnyFS S3, AnyFS SSH, Archon, Archon plugin: boot, Archon plugin: converge, Archon plugin: dns, Archon plugin: tool, Ergonex, Evidence Capture, GRC, Integrations, Lab, Linux Observe, Linux Services, Machine Probe, Planning, Repoctl

Specifications

Folders

FolderWhat it isMay import
spec-kit/The library's own specifications, numbered from 0001.nothing: Markdown and TSV
src/governance/Layer 1: the facts of an action, the decision, the problems, the exit statuses, redaction.core, by package name
src/logical/Layer 2: the command model, the outcome, verbosity, the closing block, JSON and SARIF, explain, hints, nested runs, the redaction of an outcome.governance, by package name; core and the terminal's args and commands, by package name
src/surfaces/cli/Layer 3: the command-line surface (the renderer, prompts, the run log and hints store, signals, help, completions, man, the run boundary, the launcher).governance and logical, by package name; core, the terminal and the system, by package name
src/surfaces/askpass/The credential port's terminal adapter (with the pure reader of its bytes and a row of devices for each system) and the contract of an SSH_ASKPASS helper with its launcher.governance and logical, by package name; core and the system, by package name
src/surfaces/mcp/The tool server: tools generated from governance by the caller's tier, the JSON-RPC 2.0 server of the Model Context Protocol as a function from a line to a line, and the standard streams as its transport.governance and logical, by package name; core and the system, by package name
src/surfaces/rest/The REST surface, as a skeleton: the OpenAPI 3.1 document of a program for the caller's tier.governance and logical, by package name
src/describe/The description of a program as layered models of Kanon, one for each tier: governance (the action of each verb, the problem codes, the exit statuses), the logical layer (the program, plugins, verbs, options, operands) and the command, tool and route that each surface draws.governance, logical, the tool server and the REST surface, by package name; core, the terminal's args and Kanon, by package name
src/otel/The OpenTelemetry adapter of the command line's observer port.the layers below, by package name; core and the telemetry, by package name
suite/The tests: every requirement of the four specifications, with golden outputs ported from the programs that gave the behaviour, properties and a real-process check.src/; fast-check; the test module of commons' runtime, by package name
tools/The layers check, the trace check and the packer bun run verify runs.the kernel, the runtime and the packer of commons, by package name

Quality

Quality: 163 tests: 163 passed, 0 failed, 0 skipped, 120 of 120 requirements proved, 0 open issues, 0 open tickets. The tests and issues of the library

Titles, headings, exports, tables, columns and requirements. Esc closes.