@okfit/cli 0.6.4 → 0.6.6

package/README.md

@@ -8,7 +8,7 @@ The `okfit` command line for [Open Knowledge Format (OKF)](https://github.com/Go
 
 ```text
 okfit [--help] [--version]
-okfit validate [path] [--config <file>] [--format human|json] [--skip-provenance] [--help]
+okfit validate [path] [--config <file>] [--format human|json] [--skip-provenance] [--document <bundle-path>] [--help]
 okfit init [path] [--profile <name>] [--config <file>] [--help]
 okfit context [path] [--config <file>] [--format human|json] [--help]
 okfit verify <id> [path] [--config <file>] [--at <iso>] [--dry-run] [--format human|json] [--help]
@@ -69,6 +69,14 @@ every edit-time `validate` call so a git spawn per concept never runs on
 keystroke-level edits; CI and the MCP `validate_bundle` tool omit it and
 keep both tiers.
 
+`--document <bundle-path>` validates one unsaved document: its text is
+read from stdin and stands in for that file (bundle-relative, posix, a
+`.md` path; a file not yet written under an existing directory is walked
+like any other), and nothing is written. A path that is absolute, escapes
+the bundle, is not `.md`, or sits under a directory that does not exist,
+and a terminal stdin, are usage errors (exit `64`). The MCP
+`validate_bundle` tool's `documents` input is the same overlay.
+
 ### `okfit init`
 
 Scaffolds a fresh OKF bundle: a thin `.config/okfit.toml`, the

package/commands/validate.js

@@ -3,8 +3,9 @@ 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 { readDocumentText } from "../internal/stdin.js";
 import { Argument, Command, Flag } from "effect/unstable/cli";
-import { JsonEnvelope, Now, collect, forDiagnostics, json, jsonError, provideConfig, resolveProjectConfig, run } from "@okfit/engine";
+import { JsonEnvelope, Now, collect, forDiagnostics, json, jsonError, provideConfig, provideDocuments, 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";
@@ -19,8 +20,10 @@ const configFlag = Flag.File("config").pipe(Flag.optional, Flag.withDescription(
 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"));
+/** Spec 4.5: validate one unsaved document, its text read from stdin, in place of the file on disk. */
+const documentFlag = Flag.String("document").pipe(Flag.optional, Flag.withDescription("bundle-relative path of a document whose unsaved text is read from stdin and validated in place of the file on disk"));
 /**
-* `okfit validate [path] [--config <file>] [--format human|json] [--skip-provenance]`.
+* `okfit validate [path] [--config <file>] [--format human|json] [--skip-provenance] [--document <bundle-path>]`.
 *
 * Handler order fixed by the contract (§2 `src/commands/validate.ts`):
 * stat `--config` (K-1) via `provideConfig`, discover (`OkfitConfigFile.discover`),
@@ -36,7 +39,8 @@ const validateCommand = Command.make("validate", {
 	path: pathArg,
 	config: configFlag,
 	format: formatFlag,
-	skipProvenance: skipProvenanceFlag
+	skipProvenance: skipProvenanceFlag,
+	document: documentFlag
 }, (input) => Effect.gen(function* () {
 	const cwd = process.cwd();
 	const discoveryCwd = Option.getOrElse(input.path, () => cwd);
@@ -49,13 +53,17 @@ const validateCommand = Command.make("validate", {
 			explicitConfigPath: input.config,
 			cwd
 		});
+		const documents = Option.isSome(input.document) ? [{
+			path: input.document.value,
+			text: yield* readDocumentText(input.document.value)
+		}] : [];
 		const result = yield* run({
 			root: bundleRoot,
 			config: merged,
 			profile,
 			now,
 			skipProvenance: input.skipProvenance
-		}).pipe(Effect.provide(Layer.mergeAll(Git.layer, GitHistory.layer)));
+		}).pipe(provideDocuments(bundleRoot, documents), 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") {

package/errors.js

@@ -1,4 +1,5 @@
-import { ConfigMalformedError, ConfigPathNotFoundError, InitOverwriteError, SyncStagedLogError, VerifyConceptNotFoundError, VerifySelectionError, VerifyUnsupportedFrontmatterError } from "@okfit/engine";
+import { DocumentStdinIsTerminalError } from "./internal/stdin.js";
+import { ConfigMalformedError, ConfigPathNotFoundError, DocumentPathError, InitOverwriteError, SyncStagedLogError, VerifyConceptNotFoundError, VerifySelectionError, VerifyUnsupportedFrontmatterError } from "@okfit/engine";
 import { ConfigIssueRenderer } from "@effected/cli";
 
 //#region src/errors.ts
@@ -45,6 +46,8 @@ const relativeToCwd = (path, cwd) => {
 * 5b. `VerifySelectionError` (issue #138) renders the same way, one
 *    `error: <message>` line naming why `okfit verify`'s selection was
 *    contradictory, empty, or named an undeclared type.
+* 5c. `DocumentPathError` and `DocumentStdinIsTerminalError` (`--document`)
+*    each render as one `error: <message>` line.
 * 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
@@ -67,6 +70,8 @@ const renderFailure = (error) => {
 	if (error instanceof VerifyUnsupportedFrontmatterError) return [`error: ${error.message}`];
 	if (error instanceof SyncStagedLogError) return [`error: ${error.message}`];
 	if (error instanceof VerifySelectionError) return [`error: ${error.message}`];
+	if (error instanceof DocumentPathError) return [`error: ${error.message}`];
+	if (error instanceof DocumentStdinIsTerminalError) return [`error: ${error.message}`];
 	if (hasTag(error, "ConfigValidationError")) {
 		const validationError = error;
 		return [`error: ${String(validationError)}`, ...ConfigIssueRenderer.render(validationError).map((line) => `  ${line}`)];

package/index.d.ts

@@ -1,6 +1,6 @@
 import { Command } from "effect/unstable/cli";
+import { Runtime, Schema } from "effect";
 import { ContextEnvelope, RenderedDiagnostic } from "@okfit/engine";
-import "effect";
 //#region src/commands/root.d.ts
 /**
  * K-5. No handler: the framework's own default for a command with neither a
@@ -20,7 +20,7 @@ import "effect";
  *
  * @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("@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("@okfit/engine").SyncStagedLogError | import("@effected/git").UnknownRefError | import("@okfit/engine").VerifyConceptNotFoundError | import("@okfit/engine").VerifySelectionError | 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("@okfit/engine").DocumentPathError | DocumentStdinIsTerminalError | 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("@okfit/engine").SyncStagedLogError | import("@effected/git").UnknownRefError | import("@okfit/engine").VerifyConceptNotFoundError | import("@okfit/engine").VerifySelectionError | 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("effect/Stdio").Stdio | import("@effected/xdg").Xdg>;
 //#endregion
 //#region src/errors.d.ts
 /**
@@ -59,6 +59,8 @@ export declare const rootCommand: Command.Command<"okfit", {} | {}, {}, import("
  * 5b. `VerifySelectionError` (issue #138) renders the same way, one
  *    `error: <message>` line naming why `okfit verify`'s selection was
  *    contradictory, empty, or named an undeclared type.
+ * 5c. `DocumentPathError` and `DocumentStdinIsTerminalError` (`--document`)
+ *    each render as one `error: <message>` line.
  * 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
@@ -70,6 +72,21 @@ export declare const rootCommand: Command.Command<"okfit", {} | {}, {}, import("
  */
 export declare const renderFailure: (error: unknown) => ReadonlyArray<string>;
 //#endregion
+//#region src/internal/stdin.d.ts
+declare const DocumentStdinIsTerminalError_base: Schema.Class<DocumentStdinIsTerminalError, Schema.TaggedStruct<"DocumentStdinIsTerminalError", {
+  readonly path: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * `--document` reads the draft from stdin, and stdin is a terminal: reading would
+ * block forever waiting for input nobody is piping. Exit 64: a usage error.
+ *
+ * @public
+ */
+export declare class DocumentStdinIsTerminalError extends DocumentStdinIsTerminalError_base {
+  readonly [Runtime.errorExitCode] = 64;
+  get message(): string;
+}
+//#endregion
 //#region src/render/context.d.ts
 /**
  * The `human` format: a short header block, then one line per type (plus

package/index.js

@@ -1,8 +1,9 @@
 import { humanContext } from "./render/context.js";
 import { CLI_VERSION } from "./version.js";
 import { human, line, summary } from "./render/human.js";
+import { DocumentStdinIsTerminalError } from "./internal/stdin.js";
 import { humanVerify } from "./render/verify.js";
 import { rootCommand } from "./commands/root.js";
 import { renderFailure } from "./errors.js";
 
-export { CLI_VERSION, human, humanContext, humanVerify, line, renderFailure, rootCommand, summary };
+export { CLI_VERSION, DocumentStdinIsTerminalError, human, humanContext, humanVerify, line, renderFailure, rootCommand, summary };

package/internal/stdin.js

@@ -0,0 +1,28 @@
+import { Effect, Runtime, Schema, Stdio, Stream } from "effect";
+
+//#region src/internal/stdin.ts
+/**
+* `--document` reads the draft from stdin, and stdin is a terminal: reading would
+* block forever waiting for input nobody is piping. Exit 64: a usage error.
+*
+* @public
+*/
+var DocumentStdinIsTerminalError = class extends Schema.TaggedError()("DocumentStdinIsTerminalError", { path: Schema.String }) {
+	[Runtime.errorExitCode] = 64;
+	get message() {
+		return `--document reads the document's text from stdin, but stdin is a terminal; pipe it in, for example: okfit validate --document ${this.path} < draft.md`;
+	}
+};
+/**
+* The whole of stdin as UTF-8 text, for `okfit validate --document <path>` (spec 4.5).
+*
+* @internal
+*/
+const readDocumentText = (path) => Effect.gen(function* () {
+	const stdio = yield* Stdio.Stdio;
+	if (yield* stdio.stdinIsTerminal) return yield* new DocumentStdinIsTerminalError({ path });
+	return yield* stdio.stdin.pipe(Stream.decodeText(), Stream.mkString);
+});
+
+//#endregion
+export { DocumentStdinIsTerminalError, readDocumentText };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/cli",
-	"version": "0.6.4",
+	"version": "0.6.6",
 	"private": false,
 	"description": "The okfit command line: validate, lint, index, and inspect Open Knowledge Format (OKF) bundles.",
 	"keywords": [
@@ -42,20 +42,20 @@
 		"okfit": "bin/okfit.js"
 	},
 	"dependencies": {
-		"@effect/platform-node": "4.0.0-rc.116",
-		"@effected/cli": "^0.6.0",
-		"@effected/config-file": "^0.11.1",
-		"@effected/git": "^0.16.0",
-		"@effected/glob": "^0.7.0",
-		"@effected/jsonc": "^0.12.0",
-		"@effected/markdown": "^0.11.0",
-		"@effected/toml": "^0.8.0",
-		"@effected/walker": "^0.11.0",
-		"@effected/yaml": "^0.16.0",
-		"@okfit/core": "0.7.3",
-		"@okfit/engine": "0.7.4",
-		"@okfit/profiles": "0.7.4",
-		"effect": "4.0.0-rc.116"
+		"@effect/platform-node": "4.0.0-rc.117",
+		"@effected/cli": "^0.7.0",
+		"@effected/config-file": "^0.12.0",
+		"@effected/git": "^0.17.0",
+		"@effected/glob": "^0.8.0",
+		"@effected/jsonc": "^0.13.0",
+		"@effected/markdown": "^0.12.0",
+		"@effected/toml": "^0.9.0",
+		"@effected/walker": "^0.12.0",
+		"@effected/yaml": "^0.17.0",
+		"@okfit/core": "0.8.0",
+		"@okfit/engine": "0.8.0",
+		"@okfit/profiles": "0.8.0",
+		"effect": "4.0.0-rc.117"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/version.js

@@ -11,7 +11,7 @@
 *
 * @public
 */
-const CLI_VERSION = "0.6.4";
+const CLI_VERSION = "0.6.6";
 
 //#endregion
 export { CLI_VERSION };