@hackage / okf-cli

Command-line interface for Open Knowledge Format bundles

Latest0.3.0.0

Changelog

Changelog

All notable changes to okf are recorded here.

The format follows Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[0.3.0.0] - 2026-07-29

Added
  • okf profile show and profile JSON expose local-prefix, external-scheme, and self-reference policies. okf validate renders path-precise dangling, wrong-prefix, malformed, disallowed-external, and self-reference deviations; the profiles help topic documents the offline local/external boundary.
  • okf profile show renders top-level and nested when predicates, while okf validate explains the activating condition on missing-field diagnostics. The profiles help topic documents same-scope resolution, compiler checks, strict recommendations, and no-cascade runtime behavior.
  • okf profile show renders bounded nested field rules, and okf validate reports missing nested fields, non-record list elements, and nested value violations with indexed paths such as reviews[2].outcome.
  • okf profile show and profile JSON expose named field formats, and okf validate renders parser-backed timestamp, date, URI, URI-scheme, and document-handle mismatches.
  • Profile detail output and validation diagnostics for Any, Scalar, and List field cardinality.
  • okf profile show now displays allowUnknownFields and each field's allowedValues; validation renders value-vocabulary and undeclared-field deviations.
  • okf profile show and --json now expose required and recommended frontmatter rules beneath each type.
  • okf validate --strict --profile ... checks profile-recommended fields and renders them as missing profile-recommended field; --profile-enforce continues to control whether the deviation fails the command.
  • An UPGRADING FROM 0.1.x section in the okf help profiles topic, summarizing how to move a 0.1.x profile descriptor onto the 0.2.0.0 schema.
  • Profile descriptions are surfaced everywhere a profile is displayed: okf profile show prints the profile's description, a - key: prose line per frontmatter key, and a description line in each type block; okf profile list gains a trailing DESCRIPTION column reading - when absent; and okf validate --profile appends the key's prose in parentheses to a missing profile-required field advisory. A DESCRIPTIONS section in the okf help profiles topic covers all of it.
Changed
  • Requires okf-core ^>=0.3.0.0. This major bound reflects the breaking compiled-profile API and the expanded profile-rule and diagnostic types.
  • Profile-definition output now reports invalid reference prefixes and schemes, undeclared target prefixes, missing idField, profile/type prefix conflicts, and reference-plus-format combinations. Mori and other exhaustive consumers must handle the five new reference violations and six definition errors, plus all previously accumulated profile API changes, before moving the matching cabal.project and flake.nix pins together.
  • Profile-definition output now reports every invalid condition category. Mori and other exhaustive consumers must handle the new definition errors and the condition payload added to missing-field violations before updating their okf-core pin.
  • Profile-definition output now reports invalid format parameters and contradictory profile/type formats. Mori and other exhaustive okf-core consumers must add cases for InvalidFormatParameter, ConflictingFieldFormat, and ValueFormatMismatch before updating their okf-core pin. Mori's renderer is mori-cli/src/Mori/Okf/Advisory.hs, and its matching cabal.project and flake.nix pins must move together.
  • Profile descriptors are compiled before validation. Duplicate type names and ambiguous required/recommended declarations are fatal profile-definition errors reported once, before any concept is checked.
  • Mori and other okf-core consumers must call compileProfile, handle its structured errors, pass PermissiveConformance or StrictAuthoring to validateProfile, and handle MissingRecommendedProfileField in exhaustive violation renderers.
  • okf profile show prints a non-empty frontmatter.required or frontmatter.recommended as a headed block, one key per line, rather than one comma-joined line — per-key prose cannot share a line. An empty list keeps the single-line (none) form, so every optional field still prints.

[0.2.0.0] - 2026-07-26

Added
  • okf id next and okf id list for allocating and listing profile-declared document handles, plus document-ID fallback in okf show so a handle such as ADR-7 resolves to the concept that carries it.
  • Optional BUNDLE and CONCEPT_ID arguments for okf show, filled in with fzf menus when omitted, plus the okf help interactive topic. Search roots default to the current directory and can be overridden with OKF_BUNDLE_ROOTS.
Changed
  • Requires okf-core >=0.2.0.0, whose profile Dhall schema gained the required idField and idPrefix record fields. Profile descriptors passed to okf validate --profile must add those values or adopt the new record-completion defaults.

[0.1.2.1] - 2026-07-20

Fixed
  • Ship the help/*.md topic sources in the sdist via extra-source-files. They are embedded at compile time by Okf.Cli.Help (file-embed), so their absence from the 0.1.2.0 Hackage tarball made that release fail to build from Hackage.

[0.1.2.0] - 2026-07-14

Added
  • okf kit command for installing reusable AI-agent skills and subagents from a configured okf-kit git repository (list, install, update, uninstall, status), with user and project (--project) scopes.
  • okf assist command that launches an interactive Claude session seeded with a prompt and your installed okf skills on its path; --print-command prints the command line without launching.
  • okf config command for managing the optional agent-assistance settings (show, path, init, init --global), sourced from okf-config.dhall, ~/.config/okf/config.dhall, or OKF_CONFIG with built-in defaults.
  • okf help topics for kit, config, and agents documenting the kit, configuration, and assist workflows.
Changed
  • Wired the baikai kit and agent-assist dependencies into the build.
  • Updated the bundled baikai packages.

[0.1.1.0] - 2026-06-28

Added
  • okf --version, including git SHA reporting for Cabal and Nix builds when available.
  • Shell completion generation for supported shells.
  • okf help command with embedded conceptual topic guides (okf, format, validation, profiles), including a guide explaining what the Open Knowledge Format is. The guides are plain text baked into the binary at compile time, so okf help <topic> works with no network or docs checkout.
  • Profile-based validation: okf validate --profile <descriptor>.dhall checks a bundle against a team's house conventions (allowed type strings, required frontmatter keys, resource: schemes, file layout, and # Schema columns) declared in a Dhall descriptor. Profiles are not part of the OKF standard, so deviations are advisory by default; --profile-enforce fails the command on drift. Ships an example bundle (examples/postgresql-sample), a sample descriptor (docs/profiles/postgresql.dhall), and a user guide (docs/user/profiles.md).
  • Log support: okf-core can parse, serialize, and validate log.md files; okf-cli can preview, validate, author log entries, and report drift between bundle logs and git history.
  • Canonical OKF profile schema Dhall modules with drift tests.
Changed
  • Expanded the README and user guides to cover the current CLI, profile validation, and log workflows.
  • Updated release, Nix, and repository metadata so both packages build and check as separate Hackage packages.

[0.1.0.0] - 2026-06-19

Initial release.

Added
  • okf-core library: OKF document parser (Okf.Document), bundle graph indexing (Okf.Index, Okf.Graph), bundle validation with referential integrity (Okf.Validation, Okf.Bundle), concept construction and bundle writing, concept-link rendering with a round-trip guarantee, and a frontmatter authoring API.
  • okf-cli library and okf executable: bundle validation and document authoring commands over the core API.