Library entry

@phuthuycoding/kanban-flow/lib exposes kf’s readers to another program — the hosted ledger service (#182), or a script — so it reads replicated task-loop ledgers, lifecycle logs and item folders with the code the CLI runs. Import that path:

import { readLedgerState, readItemLog, listFeatures } from "@phuthuycoding/kanban-flow/lib";

The bare @phuthuycoding/kanban-flow is the CLI entry: importing it runs a kf command from process.argv. Import @phuthuycoding/kanban-flow/lib, never the bare package, to use the library. Importing /lib runs no command, reads no argv, prints nothing and leaves the exit code alone. No other path resolves: a deep import such as @phuthuycoding/kanban-flow/dist/workflow/status.js is refused by the package’s exports map. The package is ESM only and ships type declarations for this path.

The readers need a filesystem: the item readers read .works/<stage>/<item>/ folders under the project root the caller passes, so a service materialises the folders before calling them. The library runs no git and reads no host config: no export starts git or another child process, and none reads the global ~/.kf/config.json or a .kf/workspace.json, whatever folder it is given, so a path a replicated .kfw.json names steers nothing on the reading host. Nothing here writes a file or runs a hook. kf’s status read models (computeStatus, kf dashboard’s data) and findWorksRoot run git or read those layers, so the library does not export them; a status computed without git belongs to the cloud service (#187).

Trust and cost

The readers were written for the CLI, which runs one command over the user’s own checkout. A long-running service that calls them should know these things:

• No git, no host config. The library runs no git and reads no host config. No reader writes a file under .works/; the readers open only paths inside the folder they are given, plus whatever a link there points to (see Links are followed).
• Synchronous, without a timeout. Every reader blocks: they read files with the synchronous fs calls. Call them off a request path, in a worker or a job. The ledger remote port is asynchronous (its methods return promises); the readers stay synchronous.
• A lookup is a full scan. listFeatures is a full scan of .works/: it lists every stage folder and reads and checks every .kfw.json. findFeature runs one listFeatures per call, so a service that resolves many items calls listFeatures once and indexes the result by name or folder.
• Whole files in memory. readItemLog and readStageRecords read the whole file into memory, and so do the other readers; no reader bounds file size.
• The fold checks only the keys. foldItemLog and readItemLog keep only the shared metadata keys a record sets, and the fold refuses a log that does not set schema, feature, context and created as strings (ok: false, naming the first missing key). Beyond that they check only the keys, not the values: a replicated log can give feature, issue or approval a value readFeatureMeta would refuse, although the result is typed SharedMeta. A service checks the values before it builds a path, a link or a page from them.
• Stage records skip bad lines. readStageRecords skips a line that is not JSON or not a stage record, and says nothing. kf’s own gate reads only the latest record and reports an unreadable last line, so after a cut-off or edited last line the last element of readStageRecords is an older record, not the gate’s answer.
• Links are followed. The readers follow symbolic links, and a FIFO blocks them, so a link in a materialised tree makes a reader open a path outside the folder it was given. A service materialises regular files only: no links, no FIFOs, with a size limit of its own.
• TypeScript resolution. The types resolve through the exports map, so a TypeScript consumer needs moduleResolution node16, nodenext or bundler.

Stability

• stable — removing or renaming the export, or changing a parameter or the shape it returns in a way existing callers notice, is a breaking change: a major version. While the package is 0.x, this package bumps the minor for such a change (0.19 → 0.20) and lists it under Changed in the changelog — SemVer itself promises nothing for 0.y.z; from 1.0 the change bumps the major.
• experimental — may change in any minor release. These are the task-loop scheduler’s internals and the shapes the CLI prints as text; they are exported so a service can run the same fold, not because their shape is settled.

A new optional field on a returned object is not breaking. A new member of an exported union (an event, a stage, a cause) is listed under Changed in the changelog: TypeScript code that switches on the union exhaustively stops compiling.

Exports