@okfit/cli 0.5.0 → 0.5.2

package/README.md

@@ -278,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

@@ -4,8 +4,8 @@ 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 } from "effect";
-import { Git } from "@effected/git";
 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

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,13 +10,13 @@ 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
  */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/cli",
-	"version": "0.5.0",
+	"version": "0.5.2",
 	"private": false,
 	"description": "The okfit command line: validate, lint, index, and inspect Open Knowledge Format (OKF) bundles.",
 	"keywords": [
@@ -52,9 +52,9 @@
 		"@effected/toml": "^0.7.0",
 		"@effected/walker": "^0.9.0",
 		"@effected/yaml": "^0.15.1",
-		"@okfit/core": "0.4.0",
-		"@okfit/engine": "0.3.0",
-		"@okfit/profiles": "0.4.0",
+		"@okfit/core": "0.4.1",
+		"@okfit/engine": "0.4.1",
+		"@okfit/profiles": "0.6.0",
 		"effect": "4.0.0-rc.115"
 	},
 	"engines": {

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.5.0";
+const CLI_VERSION = "0.5.2";
 
 //#endregion
 export { CLI_VERSION };