@okfit/cli 0.4.1 → 0.5.1

package/README.md

@@ -113,6 +113,34 @@ $ echo $?
 and names every colliding file in one error. An ancestor directory's config
 is a legitimate discovery hit, not a collision, and is never probed.
 
+If the repository lints markdown, the bundle needs two exemptions from
+markdownlint's defaults, and neither can be satisfied at the source: MD025
+(one top-level heading) counts a concept's frontmatter `title:` as its H1,
+so the body H1 the spec requires reads as a second one, and the spec shapes
+every `index.md` as `# Section` groups, one H1 per concept type. `log.md`
+is fine: `init` and `sync` both start it with `# Log`. Add this to a
+`.markdownlint-cli2.jsonc` at the repository root, adjusting the bundle
+path if `bundle.path` is not `okf`:
+
+```jsonc
+"overrides": [
+ {
+  "combine": "merge",
+  "config": { "MD025": { "front_matter_title": "" } },
+  "filter": ["okf/**/*.md", "!okf/**/index.md"]
+ },
+ {
+  "combine": "merge",
+  "config": { "MD025": false },
+  "filter": ["okf/**/index.md"]
+ }
+]
+```
+
+A repository whose lint config cannot express overrides can drop a nested
+`okf/.markdownlint-cli2.jsonc` carrying `{ "config": { "MD025": false } }`
+instead; the bundle loader ignores non-markdown files.
+
 `--profile <name>` picks the profile `init` scaffolds for (default: the
 config's `bundle.profile`, itself defaulting to `software-project`); an
 unrecognised name is a warning, not a failure — `init` continues with the
@@ -250,6 +278,7 @@ nothing else (no summary line, no warnings — those still go to stderr):
 {
  "schema": 1,
  "okfit_version": "0.1.0",
+ "producer": "okfit",
  "okf_version": "0.2",
  "root": "/abs/path/to/my-repo/okf",
  "profile": "software-project",

package/commands/graph.js

@@ -0,0 +1,75 @@
+import { setExitCode } from "../internal/exit.js";
+import { CLI_VERSION } from "../version.js";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import { GraphEnvelope, graphEnvelope, jsonError, provideConfig, resolveProjectConfig, runGraph } from "@okfit/engine";
+import { Console, Effect, Option, Schema } from "effect";
+import { OKF_SPEC_VERSION } from "@okfit/core";
+
+//#region src/commands/graph.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"));
+/** Default `mermaid`, unlike every other command's `--format` (which defaults `human`). */
+const formatFlag = Flag.Literals("format", [
+	"mermaid",
+	"dot",
+	"json"
+]).pipe(Flag.withDefault("mermaid"), Flag.withDescription("output format: mermaid (default), dot, or json"));
+/**
+* `okfit graph [path] [--config <file>] [--format mermaid|dot|json]`.
+*
+* Same handler skeleton as `commands/validate.ts`/`commands/context.ts` —
+* stat `--config` (K-1) via `provideConfig`, resolve the project and
+* bundle roots through `resolveProjectConfig` — then it diverges:
+* `@okfit/engine`'s `runGraph` (`Bundle.load` then `Graph.fromBundle`),
+* render, and always exit `0`. `mermaid`/`dot` print the graph's own
+* `toMermaid()`/`toGraphViz()` text raw to stdout — nothing else on
+* stdout, no summary line — since either is meant to be piped straight
+* into a renderer. Only `--format json` failures get the K-22 `jsonError`
+* envelope; a `mermaid`/`dot` failure renders the usual way through
+* `bin.ts`'s `CliRuntime.reportFailures` and carries no stdout envelope.
+*
+* @public
+*/
+const graphCommand = Command.make("graph", {
+	path: pathArg,
+	config: configFlag,
+	format: formatFlag
+}, (input) => Effect.gen(function* () {
+	const cwd = process.cwd();
+	const discoveryCwd = Option.getOrElse(input.path, () => cwd);
+	const body = Effect.gen(function* () {
+		const { bundleRoot, config: merged, profile } = yield* resolveProjectConfig({
+			pathArg: input.path,
+			explicitConfigPath: input.config,
+			cwd
+		});
+		const result = yield* runGraph({ root: bundleRoot });
+		if (input.format === "json") {
+			const envelope = graphEnvelope({
+				okfitVersion: CLI_VERSION,
+				producer: "okfit",
+				okfVersion: merged.okf_version ?? OKF_SPEC_VERSION,
+				root: bundleRoot,
+				profile: Option.match(profile, {
+					onNone: () => null,
+					onSome: (p) => p.name
+				}),
+				nodes: result.graph.nodes,
+				edges: result.graph.edges
+			});
+			yield* Console.log(JSON.stringify(Schema.encodeSync(GraphEnvelope)(envelope)));
+		} else if (input.format === "dot") yield* Console.log(result.graph.toGraphViz());
+		else yield* Console.log(result.graph.toMermaid());
+		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("Render the bundle's link graph: frontmatter path fields and body links, as Mermaid, DOT, or JSON."));
+
+//#endregion
+export { graphCommand };

package/commands/init.js

@@ -3,10 +3,9 @@ import { useColor } from "../internal/tty.js";
 import { displayRoot, human, summary } from "../render/human.js";
 import { Argument, Command, Flag } from "effect/unstable/cli";
 import { CONFIG_RELATIVE_PATH, InitOverwriteError, Now, SCHEMA_DIRECTIVE, collect, configValue, files, forDiagnostics, provideConfig, resolveBundleRoot, resolveProjectRoot, run, targetPaths } from "@okfit/engine";
-import { Console, DateTime, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
-import { TomlCodec } from "@effected/config-file";
-import { Git } from "@effected/git";
+import { Console, DateTime, Effect, FileSystem, Layer, Option, Path } from "effect";
 import { OKF_SPEC_VERSION, OkfitConfig, OkfitConfigFile } from "@okfit/core";
+import { Git } from "@effected/git";
 import { GitHistory, Profiles } from "@okfit/profiles";
 
 //#region src/commands/init.ts
@@ -100,7 +99,8 @@ const initCommand = Command.make("init", {
 		explicitConfigPath: input.config,
 		discoveryCwd
 	})(Effect.gen(function* () {
-		const winner = (yield* (yield* OkfitConfigFile).discover)[0];
+		const configFile = yield* OkfitConfigFile;
+		const winner = (yield* configFile.discover)[0];
 		const fileConfig = winner === void 0 ? { extensions: {} } : winner.value;
 		const profileName = Option.getOrElse(input.profile, () => fileConfig.bundle?.profile ?? DEFAULT_PROFILE_NAME);
 		const profile = Profiles.get(profileName);
@@ -145,12 +145,10 @@ const initCommand = Command.make("init", {
 		});
 		for (const target of paths) yield* fs.makeDirectory(path.dirname(target), { recursive: true });
 		const bundlePath = merged.bundle?.path ?? DEFAULT_BUNDLE_PATH;
-		const encoded = yield* Schema.encodeEffect(OkfitConfig)(configValue({
+		yield* configFile.write(configValue({
 			...scaffoldOptions,
 			bundlePath
-		}));
-		const toml = yield* TomlCodec.stringify(encoded);
-		yield* fs.writeFileString(`${projectRoot}/${CONFIG_RELATIVE_PATH}`, `${SCHEMA_DIRECTIVE}${toml}`);
+		}), `${projectRoot}/${CONFIG_RELATIVE_PATH}`, { header: SCHEMA_DIRECTIVE });
 		const scaffoldFiles = yield* files(scaffoldOptions);
 		for (const file of scaffoldFiles) yield* fs.writeFileString(file.path, file.contents);
 		yield* Console.log(`Initialized ${displayRoot(cwd, bundleRoot, path)} with the ${profileName} profile`);

package/commands/lint.js

@@ -0,0 +1,95 @@
+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 { OKF_SPEC_VERSION } from "@okfit/core";
+import { Git } from "@effected/git";
+import { GitHistory } from "@okfit/profiles";
+
+//#region src/commands/lint.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"));
+const formatFlag = Flag.Literals("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 lint [path] [--config <file>] [--format human|json] [--skip-provenance]`.
+*
+* Same handler skeleton as `commands/validate.ts` — stat `--config` (K-1)
+* via `provideConfig`, discover, resolve the profile and roots through
+* `resolveProjectConfig`, run the engine's `validate/run.ts#run` (both
+* conformance AND lint tiers still run — core's `Validate.all` does not
+* separate them), render, and set the exit code — except the CONFORMANCE
+* tier is dropped from what this command collects and reports:
+* `collect([], result.report.lint, result.profileDiagnostics)`, never
+* `result.report.conformance`. `conformance_errors` in the JSON envelope's
+* `summary` is therefore always `0`.
+*
+* @public
+*/
+const lintCommand = Command.make("lint", {
+	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.lint, result.profileDiagnostics);
+		const code = forDiagnostics(diagnostics);
+		if (input.format === "json") {
+			const envelope = json({
+				okfitVersion: CLI_VERSION,
+				producer: "okfit",
+				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 lint checks (and the profile check), and render the diagnostics; never conformance."));
+
+//#endregion
+export { lintCommand };

package/commands/root.js

@@ -1,5 +1,8 @@
 import { contextCommand } from "./context.js";
+import { graphCommand } from "./graph.js";
 import { initCommand } from "./init.js";
+import { lintCommand } from "./lint.js";
+import { staleCommand } from "./stale.js";
 import { syncCommand } from "./sync.js";
 import { validateCommand } from "./validate.js";
 import { verifyCommand } from "./verify.js";
@@ -14,13 +17,13 @@ import { Command } from "effect/unstable/cli";
 * `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).
+* `validate`, `init`, `context`, `verify`, `sync`, `lint`, `graph`, and
+* `stale` 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
 */
@@ -29,7 +32,10 @@ const rootCommand = Command.make("okfit", {}).pipe(Command.withDescription("Open
 	initCommand,
 	contextCommand,
 	verifyCommand,
-	syncCommand
+	syncCommand,
+	lintCommand,
+	graphCommand,
+	staleCommand
 ]));
 
 //#endregion

package/commands/stale.js

@@ -0,0 +1,76 @@
+import { setExitCode } from "../internal/exit.js";
+import { CLI_VERSION } from "../version.js";
+import { displayRoot } from "../render/human.js";
+import { humanStale, staleSummary } from "../render/stale.js";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import { Now, StaleEnvelope, jsonError, provideConfig, resolveProjectConfig, runStale, staleEnvelope } from "@okfit/engine";
+import { Console, Effect, Option, Path, Schema } from "effect";
+import { OKF_SPEC_VERSION } from "@okfit/core";
+
+//#region src/commands/stale.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"));
+const formatFlag = Flag.Literals("format", ["human", "json"]).pipe(Flag.withDefault("human"), Flag.withDescription("output format: human (default) or json"));
+/**
+* `okfit stale [path] [--config <file>] [--format human|json]`.
+*
+* Same handler skeleton as `commands/validate.ts`/`commands/context.ts` —
+* stat `--config` (K-1) via `provideConfig`, resolve the project and
+* bundle roots through `resolveProjectConfig` — then it diverges:
+* `@okfit/engine`'s `runStale` (`Bundle.load` then
+* `Derive.staleReport(bundle, now)`), render, and always exit `0`: this is
+* a report, not a check, and the `stale` lint rule (part of `okfit
+* validate`/`okfit lint`) is where staleness fails a run.
+*
+* @public
+*/
+const staleCommand = Command.make("stale", {
+	path: pathArg,
+	config: configFlag,
+	format: formatFlag
+}, (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* runStale({
+			root: bundleRoot,
+			now
+		});
+		const envelope = staleEnvelope({
+			okfitVersion: CLI_VERSION,
+			producer: "okfit",
+			okfVersion: merged.okf_version ?? OKF_SPEC_VERSION,
+			root: bundleRoot,
+			profile: Option.match(profile, {
+				onNone: () => null,
+				onSome: (p) => p.name
+			}),
+			now,
+			concepts: result.bundle.concepts.size,
+			items: result.items
+		});
+		if (input.format === "json") yield* Console.log(JSON.stringify(Schema.encodeSync(StaleEnvelope)(envelope)));
+		else {
+			for (const line of humanStale(envelope.items)) yield* Console.log(line);
+			yield* Console.error(staleSummary(envelope.summary.stale, envelope.summary.concepts, displayRoot(cwd, bundleRoot, path)));
+		}
+		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("List every concept whose stale_after instant has passed as of now, with how many whole days past it."));
+
+//#endregion
+export { staleCommand };

package/commands/validate.js

@@ -5,8 +5,8 @@ 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 { Git } from "@effected/git";
 import { GitHistory } from "@okfit/profiles";
 
 //#region src/commands/validate.ts
@@ -59,6 +59,7 @@ const validateCommand = Command.make("validate", {
 		if (input.format === "json") {
 			const envelope = json({
 				okfitVersion: CLI_VERSION,
+				producer: "okfit",
 				okfVersion: merged.okf_version ?? OKF_SPEC_VERSION,
 				root: bundleRoot,
 				profile: Option.match(profile, {

package/commands/verify.js

@@ -5,8 +5,8 @@ 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";
+import { Git } from "@effected/git";
 
 //#region src/commands/verify.ts
 /** V-6: tolerant id, normalised through `ConceptId.normalize`; never `Argument.Path`. */

package/index.d.ts

@@ -10,17 +10,17 @@ import "effect";
  * `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).
+ * `validate`, `init`, `context`, `verify`, `sync`, `lint`, `graph`, and
+ * `stale` 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/Crypto").Crypto | import("effect/FileSystem").FileSystem | import("@okfit/engine").Now | import("effect/Path").Path | import("@effected/xdg").Xdg>;
+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("@effected/config-file").ConfigFileWriteError | 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/Crypto").Crypto | import("effect/FileSystem").FileSystem | import("@okfit/engine").Now | import("effect/Path").Path | import("@effected/xdg").Xdg>;
 //#endregion
 //#region src/errors.d.ts
 /**
@@ -66,8 +66,9 @@ 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 `human` format: a short header block, then one line per type (plus
+ * its constraint lines, when it has any) 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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/cli",
-	"version": "0.4.1",
+	"version": "0.5.1",
 	"private": false,
 	"description": "The okfit command line: validate, lint, index, and inspect Open Knowledge Format (OKF) bundles.",
 	"keywords": [
@@ -43,18 +43,18 @@
 	},
 	"dependencies": {
 		"@effect/platform-node": "4.0.0-rc.115",
-		"@effected/cli": "^0.4.0",
-		"@effected/config-file": "^0.8.0",
-		"@effected/git": "^0.15.0",
+		"@effected/cli": "^0.4.1",
+		"@effected/config-file": "^0.9.0",
+		"@effected/git": "^0.15.1",
 		"@effected/glob": "^0.6.0",
 		"@effected/jsonc": "^0.11.0",
 		"@effected/markdown": "^0.10.0",
 		"@effected/toml": "^0.7.0",
-		"@effected/walker": "^0.8.0",
-		"@effected/yaml": "^0.15.0",
-		"@okfit/core": "0.3.1",
-		"@okfit/engine": "0.2.1",
-		"@okfit/profiles": "0.3.1",
+		"@effected/walker": "^0.9.0",
+		"@effected/yaml": "^0.15.1",
+		"@okfit/core": "0.4.1",
+		"@okfit/engine": "0.4.0",
+		"@okfit/profiles": "0.5.0",
 		"effect": "4.0.0-rc.115"
 	},
 	"engines": {

package/render/context.js

@@ -1,7 +1,20 @@
 //#region src/render/context.ts
+/** `kind (a | b)` for an enum field, `resource (path)` for a path field, bare `layer` for free text. */
+const renderField = (field) => field.values !== null ? `${field.name} (${field.values.map((v) => v.name).join(" | ")})` : field.kind !== null ? `${field.name} (${field.kind})` : field.name;
 /**
-* 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 constraint lines under one type bullet (issue #33): what `validate`
+* will require of a concept of this type, so an agent learns it here and
+* not from a lint error. Empty for a type that declares none.
+*/
+const constraintLines = (type) => [
+	...type.required !== null && type.required.length > 0 ? [`    required: ${type.required.join(", ")}`] : [],
+	...type.require_verified === true ? ["    verified: required"] : [],
+	...type.fields.length > 0 ? [`    fields: ${type.fields.map(renderField).join(", ")}`] : []
+];
+/**
+* The `human` format: a short header block, then one line per type (plus
+* its constraint lines, when it has any) 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
@@ -19,7 +32,7 @@ const humanContext = (envelope) => [
 	`agent: ${envelope.actors.agent ?? "(unset)"}`,
 	"",
 	"types:",
-	...envelope.types.map((t) => `  ${t.name}  ${t.description ?? ""}`),
+	...envelope.types.flatMap((t) => [`  ${t.name}  ${t.description ?? ""}`, ...constraintLines(t)]),
 	"",
 	"tags:",
 	...envelope.tags.map((t) => `  ${t.name}  ${t.description ?? ""}`)

package/render/stale.js

@@ -0,0 +1,18 @@
+//#region src/render/stale.ts
+/**
+* One line per stale concept: `<id>  <stale_after ISO>  (<N> days past)`.
+* `items` is `StaleEnvelope`'s own `items` array — already sorted by id
+* (`Derive.staleReport`) — so this renderer never re-sorts.
+*
+* @public
+*/
+const humanStale = (items) => items.map((item) => `${item.id}  ${item.stale_after}  (${item.days_past} days past)`);
+/**
+* `<N> stale concepts of <M> in <root>` — the one-line stderr summary.
+*
+* @public
+*/
+const staleSummary = (stale, concepts, root) => `${stale} stale concepts of ${concepts} in ${root}`;
+
+//#endregion
+export { humanStale, staleSummary };

package/version.js

@@ -8,7 +8,7 @@
 *
 * @public
 */
-const CLI_VERSION = "0.4.1";
+const CLI_VERSION = "0.5.1";
 
 //#endregion
 export { CLI_VERSION };