@okfit/cli 0.1.0 → 0.3.0

package/commands/sync.js

@@ -0,0 +1,108 @@
+import { setExitCode } from "../internal/exit.js";
+import { CLI_VERSION } from "../version.js";
+import { displayRoot } from "../render/human.js";
+import { humanSync } from "../render/sync.js";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import { SyncEnvelope, jsonError, provideConfig, resolveProjectConfig, runSync, syncEnvelope } from "@okfit/engine";
+import { Console, Effect, Layer, Option, Path, Schema } from "effect";
+import { Git } from "@effected/git";
+import { GitHistory } from "@okfit/profiles";
+
+//#region src/commands/sync.ts
+/** K-2: `[path]` is the PROJECT root, byte-identical to validate/init/context/verify's. */
+const pathArg = Argument.path("path", { pathType: "directory" }).pipe(Argument.optional, Argument.withDescription("project root to start config discovery from (default: current directory)"));
+/** K-1: no `mustExist` — the handler stats it via `provideConfig`. */
+const configFlag = Flag.file("config").pipe(Flag.optional, Flag.withDescription("explicit config file; skips discovery"));
+/**
+* S-13: a REPEATED `Flag.choice`, not a comma-separated `Flag.string`.
+* `Flag.atLeast(0)` allows zero occurrences (all three modes run) up
+* through any number. Each occurrence is independently validated by the
+* underlying `Choice` primitive, so a bad token (`--only badmode`) is a
+* genuine parse-time `CliError.InvalidValue` → `ShowHelp` → `bin.ts`'s
+* existing 64 remap — no new error class, no hand-built `ShowHelp`
+* (contract §11, S-13, judge note 9).
+*
+* Note: `Flag.choice`'s installed signature (`effect/unstable/cli/Flag.d.ts:161`)
+* takes `(name: string, choices: ReadonlyArray<string>)`, matching
+* `formatFlag` below — not the `[value, label]` tuple-pair form
+* `Flag.choiceWithValue` takes. The contract's own `onlyFlag` sketch
+* writes tuple pairs; since every pair's two elements are identical
+* (`["generated", "generated"]`, etc.), the plain string-array form
+* below is the same flag, verified against the installed primitive
+* rather than copied byte-for-byte from the contract's prose.
+*/
+const onlyFlag = Flag.choice("only", [
+	"generated",
+	"index",
+	"log"
+]).pipe(Flag.atLeast(0), Flag.withDescription("restrict the run to these modes (repeatable: --only generated --only index); default: all three"));
+const dryRunFlag = Flag.boolean("dry-run").pipe(Flag.withDefault(false), Flag.withDescription("compute every result and write nothing"));
+const formatFlag = Flag.choice("format", ["human", "json"]).pipe(Flag.withDefault("human"), Flag.withDescription("output format: human (default) or json"));
+/**
+* `okfit sync [path] [--config <file>] [--only <mode>]... [--dry-run]
+* [--format human|json]`.
+*
+* Handler order fixed by contract §4.3. Steps 1–3 are `context`'s/
+* `validate`'s handler in substance — stat `--config` (K-1) via
+* `provideConfig`, resolve the project and bundle roots through
+* `resolveProjectConfig` — then it diverges: build the `--only` mode
+* set (default: all three, order irrelevant — `runSync`'s own fixed
+* order wins, not `--only`'s occurrence order), run `runSync` with BOTH
+* `Git.layer` and `GitHistory.layer` provided (S-16, mirroring
+* `verify.ts:134`'s `Git.layer`-alone provision one layer up: here two
+* layers are needed because `GitHistory.layer` does not re-expose `Git`
+* even though it is built on it), render, and always exit `0`. There is
+* no content tier: every typed failure is exit `3` through `bin.ts`'s
+* existing `reportFailures`; an unknown `--only` token never reaches
+* this handler at all — it fails at parse time, exit `64`.
+*
+* @public
+*/
+const syncCommand = Command.make("sync", {
+	path: pathArg,
+	config: configFlag,
+	only: onlyFlag,
+	dryRun: dryRunFlag,
+	format: formatFlag
+}, (input) => Effect.gen(function* () {
+	const cwd = process.cwd();
+	const discoveryCwd = Option.getOrElse(input.path, () => cwd);
+	const body = Effect.gen(function* () {
+		const path = yield* Path.Path;
+		const resolved = yield* resolveProjectConfig({
+			pathArg: input.path,
+			explicitConfigPath: input.config,
+			cwd
+		});
+		const modes = input.only.length === 0 ? /* @__PURE__ */ new Set([
+			"generated",
+			"index",
+			"log"
+		]) : new Set(input.only);
+		const result = yield* runSync({
+			bundleRoot: resolved.bundleRoot,
+			config: resolved.config,
+			modes,
+			dryRun: input.dryRun
+		}).pipe(Effect.provide(Layer.mergeAll(Git.layer, GitHistory.layer)));
+		const displayPath = displayRoot(cwd, result.bundleRoot, path);
+		if (input.format === "json") {
+			const envelope = syncEnvelope({
+				okfitVersion: CLI_VERSION,
+				root: displayPath,
+				dryRun: result.dryRun,
+				result
+			});
+			yield* Console.log(JSON.stringify(Schema.encodeSync(SyncEnvelope)(envelope)));
+		} else for (const line of humanSync(result)) yield* Console.log(line);
+		setExitCode(0);
+	}).pipe(provideConfig({
+		explicitConfigPath: input.config,
+		discoveryCwd
+	}));
+	if (input.format === "json") return yield* body.pipe(Effect.tapError((error) => Console.log(JSON.stringify(jsonError(error, CLI_VERSION)))));
+	return yield* body;
+})).pipe(Command.withDescription("Regenerate the derived-content families that no other command produces: generated.at, index.md, and log.md, all from git history and the bundle's own concepts. Mechanical and agent-runnable; never an attestation and never touches verified."));
+
+//#endregion
+export { syncCommand };

package/commands/validate.js

@@ -0,0 +1,93 @@
+import { setExitCode } from "../internal/exit.js";
+import { CLI_VERSION } from "../version.js";
+import { useColor } from "../internal/tty.js";
+import { displayRoot, human, summary } from "../render/human.js";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import { JsonEnvelope, Now, collect, forDiagnostics, json, jsonError, provideConfig, resolveProjectConfig, run } from "@okfit/engine";
+import { Console, Effect, Layer, Option, Path, Schema } from "effect";
+import { Git } from "@effected/git";
+import { OKF_SPEC_VERSION } from "@okfit/core";
+import { GitHistory } from "@okfit/profiles";
+
+//#region src/commands/validate.ts
+/** `[path]` is the PROJECT root (K-2), never the bundle root. Absolute at parse time (K-50). */
+const pathArg = Argument.path("path", { pathType: "directory" }).pipe(Argument.optional, Argument.withDescription("project root to start config discovery from (default: current directory); never the bundle root"));
+/** K-1: no `mustExist` — the handler stats the path itself, before building any layer. */
+const configFlag = Flag.file("config").pipe(Flag.optional, Flag.withDescription("explicit config file; skips discovery"));
+/** K-6: `--format` is on `validate` only. */
+const formatFlag = Flag.choice("format", ["human", "json"]).pipe(Flag.withDefault("human"), Flag.withDescription("output format: human (default) or json"));
+/** S-31: skips `Provenance.lint`'s git tier for this invocation, without touching `[lint]`. */
+const skipProvenanceFlag = Flag.boolean("skip-provenance").pipe(Flag.withDefault(false), Flag.withDescription("skip the generated-at-drift lint's git tier for this run"));
+/**
+* `okfit validate [path] [--config <file>] [--format human|json] [--skip-provenance]`.
+*
+* Handler order fixed by the contract (§2 `src/commands/validate.ts`):
+* stat `--config` (K-1) via `provideConfig`, discover (`OkfitConfigFile.discover`),
+* resolve the profile with the K-4 warning, merge `DEFAULTS < profile < file`
+* (D-28), warn on an `okf_version` mismatch (K-15), resolve the project and
+* bundle roots (K-12), run (`@okfit/engine`'s `validate/run.ts#run`), collect and sort the
+* diagnostics, render per `--format` (K-18, K-20 to K-22), and set the exit
+* code without failing the Effect (K-7, K-8).
+*
+* @public
+*/
+const validateCommand = Command.make("validate", {
+	path: pathArg,
+	config: configFlag,
+	format: formatFlag,
+	skipProvenance: skipProvenanceFlag
+}, (input) => Effect.gen(function* () {
+	const cwd = process.cwd();
+	const discoveryCwd = Option.getOrElse(input.path, () => cwd);
+	const now = yield* Now;
+	const path = yield* Path.Path;
+	const body = Effect.gen(function* () {
+		const { bundleRoot, config: merged, profile } = yield* resolveProjectConfig({
+			pathArg: input.path,
+			explicitConfigPath: input.config,
+			cwd
+		});
+		const result = yield* run({
+			root: bundleRoot,
+			config: merged,
+			profile,
+			now,
+			skipProvenance: input.skipProvenance
+		}).pipe(Effect.provide(Layer.mergeAll(Git.layer, GitHistory.layer)));
+		const diagnostics = collect(result.report.conformance, result.report.lint, result.profileDiagnostics);
+		const code = forDiagnostics(diagnostics);
+		if (input.format === "json") {
+			const envelope = json({
+				okfitVersion: CLI_VERSION,
+				okfVersion: merged.okf_version ?? OKF_SPEC_VERSION,
+				root: bundleRoot,
+				profile: Option.match(profile, {
+					onNone: () => null,
+					onSome: (p) => p.name
+				}),
+				exitCode: code,
+				concepts: result.bundle.concepts.size,
+				diagnostics
+			});
+			yield* Console.log(JSON.stringify(Schema.encodeSync(JsonEnvelope)(envelope)));
+		} else {
+			for (const diagnosticLine of human(diagnostics, { color: useColor() })) yield* Console.log(diagnosticLine);
+			const counts = {
+				errors: diagnostics.filter((d) => d.severity === "error").length,
+				warnings: diagnostics.filter((d) => d.severity === "warning").length,
+				info: diagnostics.filter((d) => d.severity === "info").length,
+				concepts: result.bundle.concepts.size
+			};
+			yield* Console.error(summary(counts, displayRoot(cwd, bundleRoot, path)));
+		}
+		setExitCode(code);
+	}).pipe(provideConfig({
+		explicitConfigPath: input.config,
+		discoveryCwd
+	}));
+	if (input.format === "json") return yield* body.pipe(Effect.tapError((error) => Console.log(JSON.stringify(jsonError(error, CLI_VERSION)))));
+	return yield* body;
+})).pipe(Command.withDescription("Load config and bundle, run conformance and lint checks, and render the diagnostics."));
+
+//#endregion
+export { validateCommand };

package/commands/verify.js

@@ -0,0 +1,94 @@
+import { setExitCode } from "../internal/exit.js";
+import { CLI_VERSION } from "../version.js";
+import { displayRoot } from "../render/human.js";
+import { humanVerify } from "../render/verify.js";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import { Now, VerifyEnvelope, jsonError, provideConfig, resolveProjectConfig, runVerify, verifyEnvelope } from "@okfit/engine";
+import { Console, DateTime, Effect, Option, Path, Schema } from "effect";
+import { Git } from "@effected/git";
+import { Timestamp } from "@okfit/core";
+
+//#region src/commands/verify.ts
+/** V-6: tolerant id, normalised through `ConceptId.normalize`; never `Argument.path`. */
+const idArg = Argument.string("id").pipe(Argument.withDescription("concept id to verify, with or without a leading slash or trailing .md"));
+/** K-2: `[path]` is the PROJECT root, byte-identical to validate/init/context's. */
+const pathArg = Argument.path("path", { pathType: "directory" }).pipe(Argument.optional, Argument.withDescription("project root to start config discovery from (default: current directory); never the bundle root"));
+/** K-1: no `mustExist`; the handler stats it via `provideConfig`. */
+const configFlag = Flag.file("config").pipe(Flag.optional, Flag.withDescription("explicit config file; skips discovery"));
+/** V-6: `Flag.string`, decoded through core's `Timestamp` — never `Flag.date`, which yields a bare Date. */
+const atFlag = Flag.string("at").pipe(Flag.optional, Flag.withDescription("ISO 8601 timestamp with an explicit offset to record instead of now"));
+/** V-6/V-8: the preview is a flag, never a prompt. */
+const dryRunFlag = Flag.boolean("dry-run").pipe(Flag.withDefault(false), Flag.withDescription("print the exact fragment a real run would splice in; write nothing"));
+const formatFlag = Flag.choice("format", ["human", "json"]).pipe(Flag.withDefault("human"), Flag.withDescription("output format: human (default) or json"));
+/**
+* `okfit verify <id> [path] [--config <file>] [--at <iso>] [--dry-run]
+* [--format human|json]`.
+*
+* Handler order fixed by contract §2.3. Steps 1–3 are `context`'s handler
+* in substance — stat `--config` (K-1) via `provideConfig`, discover,
+* resolve the profile and roots through `resolveProjectConfig` — then it
+* diverges: resolve `at` (the `Now` service, or `--at` through
+* `Schema.decodeUnknownEffect(Timestamp)`, never the throwing sync
+* decoder), provide `Git` for `Derivation.generatedBy`, run the splice and
+* the atomic write, render, and always exit `0`. There is no content tier:
+* every typed failure is exit `3` through `bin.ts`'s existing
+* `reportFailures`.
+*
+* @public
+*/
+const verifyCommand = Command.make("verify", {
+	id: idArg,
+	path: pathArg,
+	config: configFlag,
+	at: atFlag,
+	dryRun: dryRunFlag,
+	format: formatFlag
+}, (input) => Effect.gen(function* () {
+	const cwd = process.cwd();
+	const discoveryCwd = Option.getOrElse(input.path, () => cwd);
+	const body = Effect.gen(function* () {
+		const path = yield* Path.Path;
+		const resolved = yield* resolveProjectConfig({
+			pathArg: input.path,
+			explicitConfigPath: input.config,
+			cwd
+		});
+		const at = Option.isNone(input.at) ? DateTime.startOf(yield* Now, "second") : yield* Schema.decodeUnknownEffect(Timestamp)(input.at.value);
+		const result = yield* runVerify({
+			id: input.id,
+			bundleRoot: resolved.bundleRoot,
+			projectRoot: resolved.projectRoot,
+			config: resolved.config,
+			at,
+			dryRun: input.dryRun
+		});
+		const displayPath = `${displayRoot(cwd, result.bundleRoot, path)}/${result.conceptPath}`;
+		if (input.format === "json") {
+			const envelope = verifyEnvelope({
+				okfitVersion: CLI_VERSION,
+				id: result.id,
+				path: displayPath,
+				by: result.by,
+				at: result.at,
+				dryRun: result.dryRun
+			});
+			yield* Console.log(JSON.stringify(Schema.encodeSync(VerifyEnvelope)(envelope)));
+		} else for (const line of humanVerify({
+			id: result.id,
+			by: result.by,
+			at: result.at,
+			priorAt: result.priorAt,
+			dryRun: result.dryRun,
+			fragment: result.fragment
+		})) yield* Console.log(line);
+		setExitCode(0);
+	}).pipe(Effect.provide(Git.layer), provideConfig({
+		explicitConfigPath: input.config,
+		discoveryCwd
+	}));
+	if (input.format === "json") return yield* body.pipe(Effect.tapError((error) => Console.log(JSON.stringify(jsonError(error, CLI_VERSION)))));
+	return yield* body;
+})).pipe(Command.withDescription("Record a human's attestation that a concept has been reviewed: append one verified entry, { by: human:<id>, at: <now> }, to its frontmatter. The actor is always your own git identity; there is no --by. This is a human-run command: no agent, hook, or MCP tool ever invokes it."));
+
+//#endregion
+export { verifyCommand };

package/errors.js

@@ -0,0 +1,70 @@
+import { ConfigMalformedError, ConfigPathNotFoundError, InitOverwriteError, VerifyConceptNotFoundError, VerifyUnsupportedFrontmatterError } from "@okfit/engine";
+import { ConfigIssueRenderer } from "@effected/cli";
+
+//#region src/errors.ts
+const hasTag = (error, tag) => typeof error === "object" && error !== null && "_tag" in error && error._tag === tag;
+/** `path` relative to `cwd` when it is under it, else the absolute path unchanged (K-51). */
+const relativeToCwd = (path, cwd) => {
+	if (path === cwd) return ".";
+	const prefix = cwd.endsWith("/") ? cwd : `${cwd}/`;
+	return path.startsWith(prefix) ? path.slice(prefix.length) : path;
+};
+/**
+* The `render` option for `CliRuntime.reportFailures` (K-30, K-46, K-51). One
+* string per stderr line; `reportFailures` emits each through its own
+* `Effect.logError`, which `CliLogger` routes to stderr.
+*
+* Rules, in order:
+*
+* 1. A `ShowHelp` (any `_tag === "ShowHelp"`) renders as `[]` — the empty
+*    array. `Command.runWith` has already rendered the help document and any
+*    parse errors before re-failing, so a second rendering here would print
+*    "Help requested" after the help text. This is why the K-30 remap in
+*    `bin.ts` can run ahead of `reportFailures` without corrupting `--help`
+*    output.
+* 2. `ConfigPathNotFoundError` renders as its own `error: <message>` line;
+*    `InitOverwriteError` renders as the K-51 header, one two-space-indented
+*    relativised path per conflict, and the literal `Nothing was written.`.
+* 3. `ConfigMalformedError` renders as its own `error: <message>` line —
+*    `error: malformed config <path>: <cause message>` — since it already
+*    carries the offending path (`config/layer.ts#provideConfig` wraps a
+*    `ConfigCodecError`/`ConfigValidationError` into this the moment the
+*    path is known).
+* 4. A `ConfigValidationError` NOT already wrapped above (detected by
+*    `_tag`, since the peer is optional and this module keeps it a
+*    type-only import — this is the "path unknown" case, K-46) renders as
+*    `error: ${String(error)}` followed by one two-space-indented
+*    `ConfigIssueRenderer.render(error)` line per entry.
+* 5. `VerifyConceptNotFoundError` and `VerifyUnsupportedFrontmatterError`
+*    each render as their own `error: <message>` line; both messages
+*    already name the concept id and what to do about it, and neither
+*    carries a filesystem path needing K-51 relativisation.
+* 6. Everything else — core's `BundleRootNotFoundError`/`BundleReadError`/
+*    `BundleDepthExceededError`, config-file's other errors, `XdgEnvError`
+*    (the K-13 `HOME`-unset case) — renders as the single line
+*    `error: ${String(error)}`. Each of those
+*    classes' own `message` already names the offending path, which is all
+*    K-46 asserts.
+*
+* @public
+*/
+const renderFailure = (error) => {
+	if (hasTag(error, "ShowHelp")) return [];
+	if (error instanceof ConfigPathNotFoundError) return [`error: ${error.message}`];
+	if (error instanceof ConfigMalformedError) return [`error: ${error.message}`];
+	if (error instanceof InitOverwriteError) return [
+		"error: refusing to overwrite existing files:",
+		...error.paths.map((path) => `  ${relativeToCwd(path, error.cwd)}`),
+		"Nothing was written."
+	];
+	if (error instanceof VerifyConceptNotFoundError) return [`error: ${error.message}`];
+	if (error instanceof VerifyUnsupportedFrontmatterError) return [`error: ${error.message}`];
+	if (hasTag(error, "ConfigValidationError")) {
+		const validationError = error;
+		return [`error: ${String(validationError)}`, ...ConfigIssueRenderer.render(validationError).map((line) => `  ${line}`)];
+	}
+	return [`error: ${String(error)}`];
+};
+
+//#endregion
+export { renderFailure };

package/index.d.ts

@@ -1,19 +1,160 @@
 import { Command } from "effect/unstable/cli";
+import { ContextEnvelope, RenderedDiagnostic } from "@okfit/engine";
+import "effect";
 //#region src/commands/root.d.ts
 /**
- * The `okfit` root command. Subcommands are attached in later releases.
+ * K-5. No handler: the framework's own default for a command with neither a
+ * `handle` nor a matched subcommand is
+ * `Effect.fail(new CliError.ShowHelp({ commandPath, errors: [] }))`, and a
+ * `ShowHelp` with no errors carries `[Runtime.errorExitCode] = 0`. Bare
+ * `okfit` therefore prints the root help and exits `0` with no code in this
+ * package at all.
+ *
+ * `validate`, `init`, `context`, `verify`, and `sync` are the whole command tree;
+ * nothing else is registered here. Each is appended in introduction order,
+ * never reordered in, so `--help`'s subcommand list reads that way too
+ * (contract §4.2). The top-level description is left unchanged: neither
+ * `context` nor `verify` validates or scaffolds, but widening the sentence
+ * for the orientation- and attestation-only commands buys nothing
+ * (contract §4.2).
+ *
+ * @public
+ */
+export declare const rootCommand: Command.Command<"okfit", {} | {}, {}, import("@okfit/profiles").AgentActorUnconfiguredError | import("@okfit/core").BundleDepthExceededError | import("@okfit/core").BundleReadError | import("@okfit/core").BundleRootNotFoundError | import("@effected/config-file").ConfigCodecError | import("@effected/config-file").ConfigFileReadError | import("@okfit/engine").ConfigMalformedError | import("@okfit/engine").ConfigPathNotFoundError | import("@effected/config-file").ConfigValidationError | import("@effected/markdown").FrontmatterEncodeError | import("@effected/markdown").FrontmatterFormatMismatchError | import("@effected/markdown").FrontmatterValidationError | import("@effected/git").GitCommandError | import("@okfit/profiles").GitHistoryError | import("@okfit/profiles").HumanActorUnresolvedError | import("@okfit/engine").InitOverwriteError | import("@effected/markdown").MarkdownParseError | import("@effected/git").NotARepositoryError | import("effect/PlatformError").PlatformError | import("effect/Schema").SchemaError | import("@effected/git").UnknownRefError | import("@okfit/engine").VerifyConceptNotFoundError | import("@okfit/engine").VerifyUnsupportedFrontmatterError | import("@effected/yaml").YamlParseError, import("@effected/xdg").AppDirs | import("effect/unstable/process/ChildProcessSpawner").ChildProcessSpawner | import("effect/FileSystem").FileSystem | import("@okfit/engine").Now | import("effect/Path").Path | import("@effected/xdg").Xdg>;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * The `render` option for `CliRuntime.reportFailures` (K-30, K-46, K-51). One
+ * string per stderr line; `reportFailures` emits each through its own
+ * `Effect.logError`, which `CliLogger` routes to stderr.
+ *
+ * Rules, in order:
+ *
+ * 1. A `ShowHelp` (any `_tag === "ShowHelp"`) renders as `[]` — the empty
+ *    array. `Command.runWith` has already rendered the help document and any
+ *    parse errors before re-failing, so a second rendering here would print
+ *    "Help requested" after the help text. This is why the K-30 remap in
+ *    `bin.ts` can run ahead of `reportFailures` without corrupting `--help`
+ *    output.
+ * 2. `ConfigPathNotFoundError` renders as its own `error: <message>` line;
+ *    `InitOverwriteError` renders as the K-51 header, one two-space-indented
+ *    relativised path per conflict, and the literal `Nothing was written.`.
+ * 3. `ConfigMalformedError` renders as its own `error: <message>` line —
+ *    `error: malformed config <path>: <cause message>` — since it already
+ *    carries the offending path (`config/layer.ts#provideConfig` wraps a
+ *    `ConfigCodecError`/`ConfigValidationError` into this the moment the
+ *    path is known).
+ * 4. A `ConfigValidationError` NOT already wrapped above (detected by
+ *    `_tag`, since the peer is optional and this module keeps it a
+ *    type-only import — this is the "path unknown" case, K-46) renders as
+ *    `error: ${String(error)}` followed by one two-space-indented
+ *    `ConfigIssueRenderer.render(error)` line per entry.
+ * 5. `VerifyConceptNotFoundError` and `VerifyUnsupportedFrontmatterError`
+ *    each render as their own `error: <message>` line; both messages
+ *    already name the concept id and what to do about it, and neither
+ *    carries a filesystem path needing K-51 relativisation.
+ * 6. Everything else — core's `BundleRootNotFoundError`/`BundleReadError`/
+ *    `BundleDepthExceededError`, config-file's other errors, `XdgEnvError`
+ *    (the K-13 `HOME`-unset case) — renders as the single line
+ *    `error: ${String(error)}`. Each of those
+ *    classes' own `message` already names the offending path, which is all
+ *    K-46 asserts.
+ *
+ * @public
+ */
+export declare const renderFailure: (error: unknown) => ReadonlyArray<string>;
+//#endregion
+//#region src/render/context.d.ts
+/**
+ * The `human` format: a short header block, then one line per type and one
+ * per tag. Pure; the caller pipes each line through `Console.log`.
+ *
+ * The `profile:` line reads `profile: (none) (requested NAME, unknown)`
+ * when `profile` and `profile_requested` disagree over an actually-unknown
+ * profile — never for the `"none"` or no-config cases, where a `null`
+ * `profile` is expected, not an error.
+ *
+ * @public
+ */
+export declare const humanContext: (envelope: ContextEnvelope) => ReadonlyArray<string>;
+//#endregion
+//#region src/render/human.d.ts
+/** The counts the summary line reports. @public */
+interface Counts {
+  readonly errors: number;
+  readonly warnings: number;
+  readonly info: number;
+  readonly concepts: number;
+}
+/**
+ * K-16. With a range:
+ * `<file>:<range.line + 1>:<range.character + 1> <severity> <code> <message>`.
+ * Without one: `<file> <severity> <code> <message>`. `file: ""` renders as
+ * the literal `(bundle)`. Core's range is zero-based (D-32,
+ * `CORE/Diagnostic.ts:49-57`); the `+ 1`s here are the only place it becomes
+ * one-based. Colour, when `color` is `true`, wraps ONLY the severity word
+ * (K-19) — never the code, the path, or the message.
+ *
+ * @public
+ */
+export declare const line: (diagnostic: RenderedDiagnostic, options?: {
+  readonly color?: boolean;
+}) => string;
+/**
+ * `sort` then `line` over the whole set: the exact stdout body of
+ * `--format human`, one array element per stdout line.
+ *
+ * @public
+ */
+export declare const human: (diagnostics: ReadonlyArray<RenderedDiagnostic>, options?: {
+  readonly color?: boolean;
+}) => ReadonlyArray<string>;
+/**
+ * K-20, verbatim and unpluralised —
+ * `<E> errors, <W> warnings, <I> info in <N> concepts (<root>)`. `root` is
+ * pre-rendered by the caller: relative to cwd when under it, absolute
+ * otherwise (K-51).
+ *
+ * @public
+ */
+export declare const summary: (counts: Counts, root: string) => string;
+//#endregion
+//#region src/render/verify.d.ts
+/** @public */
+interface VerifyLines {
+  readonly id: string;
+  readonly by: string;
+  readonly at: string;
+  /** Every prior entry by the SAME actor, in list order (V-2). */
+  readonly priorAt: ReadonlyArray<string>;
+  readonly dryRun: boolean;
+  /** The exact bytes a real run would splice in; printed only when `dryRun`. */
+  readonly fragment: string;
+}
+/**
+ * V-11's human output: one line per fact. One `already verified` line per
+ * prior entry by the same actor, in list order (V-2 says "entries",
+ * plural), then the success line. A prior entry by a DIFFERENT actor is
+ * not called out: it stays on disk untouched (V-1) and is simply not this
+ * line's subject. Under `--dry-run` (I3), a `would write:` header and the
+ * exact fragment a real run would splice in follow, so the preview
+ * exercises — and shows — the same edit the write path would make.
  *
  * @public
  */
-declare const rootCommand: Command.Command<"okfit", {}, {}, never, never>;
+export declare const humanVerify: (input: VerifyLines) => ReadonlyArray<string>;
 //#endregion
-//#region src/index.d.ts
+//#region src/version.d.ts
 /**
- * The version string reported by `okfit --version`.
+ * The version string reported by `okfit --version`. `@savvy-web/bundler`
+ * replaces `process.env.__PACKAGE_VERSION__` with this package's own
+ * version at build time (K-32), so a release can never desync from the
+ * printed version. `"0.0.0"` is the unbuilt-source fallback and reads as
+ * dev mode.
  *
  * @public
  */
-declare const CLI_VERSION = "0.0.0";
+export declare const CLI_VERSION: string;
 //#endregion
-export { CLI_VERSION, rootCommand };
+export type { Counts, VerifyLines };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,12 +1,8 @@
+import { humanContext } from "./render/context.js";
+import { CLI_VERSION } from "./version.js";
+import { human, line, summary } from "./render/human.js";
+import { humanVerify } from "./render/verify.js";
 import { rootCommand } from "./commands/root.js";
+import { renderFailure } from "./errors.js";
 
-//#region src/index.ts
-/**
-* The version string reported by `okfit --version`.
-*
-* @public
-*/
-const CLI_VERSION = "0.0.0";
-
-//#endregion
-export { CLI_VERSION, rootCommand };
+export { CLI_VERSION, human, humanContext, humanVerify, line, renderFailure, rootCommand, summary };

package/internal/exit.js

@@ -0,0 +1,14 @@
+//#region src/internal/exit.ts
+/**
+* K-7: exits `1` and `2` are a SUCCESSFUL run that found diagnostics, never
+* an Effect failure. The handler writes the code here and returns `void`.
+* The only writer of `process.exitCode` in this package.
+*
+* @public
+*/
+const setExitCode = (code) => {
+	process.exitCode = code;
+};
+
+//#endregion
+export { setExitCode };

package/internal/tty.js

@@ -0,0 +1,13 @@
+//#region src/internal/tty.ts
+/**
+* K-19: exactly the framework's own colour rule. Evaluated once per run at
+* the command boundary and passed to the renderers as a boolean, so every
+* renderer stays pure. The only reader of `process.stdout.isTTY`/`NO_COLOR`
+* in this package.
+*
+* @public
+*/
+const useColor = () => process.stdout.isTTY === true && process.env.NO_COLOR !== "1";
+
+//#endregion
+export { useColor };

package/main.d.ts

@@ -0,0 +1,15 @@
+//#region src/main.d.ts
+/**
+ * The assembled okfit CLI program.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Run the okfit CLI. Owns the process: installs the runtime teardown and
+ * sets the exit code. `NodeRuntime.runMain` does not return a promise.
+ *
+ * @public
+ */
+export declare const main: () => void;
+//#endregion
+//# sourceMappingURL=main.d.ts.map

package/main.js

@@ -0,0 +1,44 @@
+import { CLI_VERSION } from "./version.js";
+import { rootCommand } from "./commands/root.js";
+import { renderFailure } from "./errors.js";
+import { Command } from "effect/unstable/cli";
+import { Now, OkfitPlatform } from "@okfit/engine";
+import { DateTime, Effect, Option } from "effect";
+import { CliLogger, CliRuntime } from "@effected/cli";
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+
+//#region src/main.ts
+/**
+* The assembled okfit CLI program.
+*
+* @packageDocumentation
+*/
+/**
+* K-47: an ISO-8601 `OKFIT_NOW` when set, else the wall clock. A documented
+* test hook, not user-facing. Resolved exactly once, here, and provided to
+* the whole command tree through the `Now` tag so no command handler ever
+* reads `process.env["OKFIT_NOW"]` itself.
+*/
+const nowEffect = Option.fromNullishOr(process.env.OKFIT_NOW).pipe(Option.flatMap((iso) => DateTime.make(iso)), Option.match({
+	onNone: () => DateTime.now,
+	onSome: Effect.succeed
+}));
+/**
+* Run the okfit CLI. Owns the process: installs the runtime teardown and
+* sets the exit code. `NodeRuntime.runMain` does not return a promise.
+*
+* @public
+*/
+const main = () => {
+	const program = Effect.gen(function* () {
+		const now = yield* nowEffect;
+		return yield* Command.run(rootCommand, { version: CLI_VERSION }).pipe(Effect.provideService(Now, now), Effect.catchTag("ShowHelp", (help) => Effect.fail(CliRuntime.reported(help, help.errors.length > 0 ? 64 : 0))));
+	}).pipe(Effect.provide(OkfitPlatform), CliRuntime.reportFailures({
+		exitCode: 3,
+		render: renderFailure
+	}));
+	NodeRuntime.runMain(program.pipe(Effect.provide(CliLogger.layer())));
+};
+
+//#endregion
+export { main };