@hackage / okf-cli

Command-line interface for Open Knowledge Format bundles

Latest0.5.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.5.0.0] - 2026-08-01

Added
  • okf trust BUNDLE reports every concept's derived trust tier, status, and staleness as one aligned row per concept. A tier is computed from verified on each run and never read from the bundle.
  • okf sources BUNDLE lists the OKF v0.2 provenance each concept records, with the credibility signals author, usage_count, and last_modified, and the effective usage window per entry. Concepts with no sources are skipped, and entries are never sorted or ranked by usage_count.
  • okf index BUNDLE --write --okf-version MAJOR.MINOR declares an OKF version in the bundle root index.md. Without the flag, an existing declaration is preserved and an absent one stays absent — previously, regenerating indexes silently destroyed a declaration.
  • okf show prints the v0.2 families a concept carries — generated, the derived trust tier, the latest verified date, status, stale_after with its staleness verdict, and a sources count.
  • okf validate renders the new core diagnostics, including the join between a body's footnote labels and its sources ids in both directions.
  • okf validate --profile reports deviations inside an object-valued frontmatter key, at paths such as generated.by, and refuses a descriptor that pairs objectFields with an explicit scalar or list cardinality: objectFields at generated cannot be combined with cardinality scalar. okf profile document renders the new rule kind as an - Object fields: bullet, which changes generated output for every profile; the committed examples/postgresql-profile/ bundle is regenerated accordingly.
  • okf computations BUNDLE lists every attested computation a bundle declares, one aligned row each, in the house style of okf trust and okf sources: the concept ID, the runtime, the parameters, where the computation lives, and which of §10.2's two run-and-check halves the concept declares. Selection is on the type frontmatter value being exactly Attested Computation. Every column restates frontmatter and none says anything about a run — a receipt and a verdict live outside the bundle and okf never executes or attests anything. An absent value prints as (no runtime), (no computation), (2 computations), or (neither) rather than as a blank cell, so the report hides nothing that okf validate --strict reports. A bundle with no computations prints nothing and exits 0.
  • okf show CONCEPT --computation prints a concept's computation and nothing else, in whichever of §10.3's two forms its producer chose — reading the file named by computation rather than printing its path. Offering none, or more than one, exits non-zero rather than guessing.
  • okf show renders the §10.2 contract in the specification's own field order, printing each line only when the concept declares it.
  • examples/ddd-ordering ships a worked attested computation at computations/order-total.md, with a references/skills/ executor and a references/attesters/ attester, and a test asserting it validates strictly.
  • okf profile document --generated-by ACTOR sets the actor recorded in generated.by on every generated page. Accepts any OKF v0.2 actor shape: <producer>/<version>, human:<id>, or process:<id>.
  • okf profile document --generated-at RFC3339 records a timestamp in generated.at. Omitted entirely when not given, because generation never reads the clock.
  • okf profile document --okf-version MAJOR.MINOR declares the OKF version in the generated bundle's root index, spelled and validated exactly as the flag of the same name on okf index. Omitting it preserves any declaration the destination already carries rather than deleting one.
  • okf validate --profile reports a bundle whose okf_version declaration does not meet the profile's requireBundleVersion, as bundle does not declare okf_version; this profile requires 0.2 or later or bundle declares okf_version 0.1; …. Advisory like every other profile deviation and fatal under --profile-enforce. It is the one violation that names no concept.
  • okf profile show prints a requireBundleVersion: line, and --json gains the matching key.
Changed
  • okf profile show renders objectFields. It printed elementFields and not its counterpart, so a profile constraining the members of a mapping-valued key displayed that rule nowhere. The gap was not hypothetical: the shipped docs/profiles/okf-v0-2.dhall constrains the members of generated, verified, and usage_window, and none of it was visible. The two nested shapes now print together, objectFields first, matching okf profile document, which already rendered its object-fields bullet in that position. Every field rule gains at least an objectFields: (none) line, so the output of this command changes for every profile.
  • The embedded okf help topics describe OKF v0.2. okf help format listed timestamp among current frontmatter fields and # Citations as a conventional body heading, and named no v0.2 family at all; okf help validation required timestamp under --strict and opened its conformance section with "OKF v0.1 conformance"; and okf help okf asserted the tool tracks the v0.1 specification while listing five of fourteen commands. All three are current. format gains the six v0.2 families, an ATTESTED COMPUTATIONS section, the references/ convention, and the §6.2 path grammar; validation gains the strict-mode diagnostics, a VERSION DECLARATION section, and one statement of why every optional-family check is strict-only.
  • okf validate --strict reports a path in a frontmatter value that names a file the bundle does not hold, which no check saw before. Only resource and the three attested-computation path fields; sources[].resource is deliberately exempt because §5.1 sanctions a scope descriptor there.
  • okf index lists a directory's non-Markdown files, so a references/attesters/ directory holding only .py files no longer generates a one-byte index.md.
  • okf validate --profile resolves a path rule against every file in the bundle rather than only .md concepts.
  • A missing member of a nested record now carries the member's description prose in parentheses — missing profile-required field: generated.by (Who or what produced this content.) — as a missing top-level key already did. This applies to list-element members too, and adds nothing where a member declares no description.
  • okf validate names a declared OKF version in its success line: OK: 4 concepts (okf_version 0.2). The suffix appears only when the bundle's root index.md declares a version, so a bundle that declares nothing prints exactly OK: N concepts as before.
  • Strict validation asks for generated rather than timestamp. It falls back to a legacy timestamp, so nothing that passed before fails now, but the message for a concept with neither changes to missing generated field (or legacy timestamp). In a bundle that declares okf_version: "0.2", a concept still carrying timestamp is additionally reported under --strict; an undeclared bundle never is.
  • okf log --check-stale and okf validate --log-enforce read generated.at first, falling back to timestamp, and the advisory says generated date rather than timestamp date.
  • The shipped docs/profiles/postgresql.dhall now requires its bundles to declare okf_version at 0.2 or later, since its own rules are written for v0.2 and examples/postgresql-sample already declares it. The shipped docs/profiles/okf-v0-2.dhall deliberately does not: §12 makes the declaration a MAY, and a format-level reference profile that demanded one would advise the opposite of the specification.
  • okf profile document now writes generated.by: process:okf-profile-document on every page by default, so default output passes okf validate --strict without --timestamp. The default actor is deliberately version-free: a version-bearing one would change every generated byte on every okf release and break the drift check that committed documentation exists to provide.
  • --timestamp still writes the superseded OKF v0.1 timestamp key and is unchanged, but is now needed only when producing a v0.1 bundle.
  • Requires okf-core ^>=0.5.0.0 with the OKF v0.2 core semantics, the attested computation contract, the path-valued frontmatter rules, and the profile-declared bundle version requirement.
Fixed
  • okf-cli-test passes from the released sdist. Nine tests assert against artifacts committed to the okf repository — docs/profiles/, examples/, and okf-core's fixtures — none of which cabal will package into okf-cli's tarball, because they sit outside the package tree. They previously aborted the whole suite on the first missing file, so cabal test failed for anyone building from Hackage, nixpkgs included. Each now reports SKIP when the repository tree is absent and runs unchanged inside it.

[0.4.0.0] - 2026-07-30

Added
  • okf profile show prints frontmatter.optional at profile scope, under each type rule, and inside elementFields, using (none) when empty, so all three presence lists always print in the same order. Profile JSON emits the matching optional key in both rule records.
  • okf validate renders the new OptionalFieldWithCondition profile-definition error, and the ConflictingFieldRequirement message now names all three presence lists. The profiles help topic gains an OPTIONAL FIELDS section and documents when to prefer optional over recommended.
Changed
  • Requires okf-core ^>=0.4.0.0. That release adds the optional field to FrontmatterRules and NestedRules, so a descriptor annotated against okf's current Profile.dhall by relative path must declare the third list.

[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.