@okfit/cli 0.4.0 → 0.5.0

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

package/commands/context.js

@@ -7,11 +7,11 @@ import { Console, Effect, Option, Schema } from "effect";
 
 //#region src/commands/context.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"));
+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 configFlag = Flag.File("config").pipe(Flag.optional, Flag.withDescription("explicit config file; skips discovery"));
 /** No `--profile` flag: M-15's exact ruling; that flag belongs to `init` alone. */
-const formatFlag = Flag.choice("format", ["human", "json"]).pipe(Flag.withDefault("human"), Flag.withDescription("output format: human (default) or json"));
+const formatFlag = Flag.Literals("format", ["human", "json"]).pipe(Flag.withDefault("human"), Flag.withDescription("output format: human (default) or json"));
 /**
 * `okfit context [path] [--config <file>] [--format human|json]`.
 *

package/commands/init.js

@@ -3,8 +3,7 @@ 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 { Console, DateTime, Effect, FileSystem, Layer, Option, Path } from "effect";
 import { Git } from "@effected/git";
 import { OKF_SPEC_VERSION, OkfitConfig, OkfitConfigFile } from "@okfit/core";
 import { GitHistory, Profiles } from "@okfit/profiles";
@@ -12,19 +11,19 @@ import { GitHistory, Profiles } from "@okfit/profiles";
 //#region src/commands/init.ts
 /**
 * `[path]` is the PROJECT root (K-2), never the bundle root — identical to
-* `validate`'s own argument (`Argument.path` resolves it absolute at the
+* `validate`'s own argument (`Argument.Path` resolves it absolute at the
 * parse boundary, satisfying 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"));
+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` — existence is checked by `provideConfig`, identical to `validate`'s flag. */
-const configFlag = Flag.file("config").pipe(Flag.optional, Flag.withDescription("explicit config file; skips discovery"));
+const configFlag = Flag.File("config").pipe(Flag.optional, Flag.withDescription("explicit config file; skips discovery"));
 /**
-* K-3: `Flag.string`, deliberately not `Flag.choice` against
+* K-3: `Flag.String`, deliberately not `Flag.Literals` against
 * `PROFILE_NAMES` (`PROFILES/Profile.ts:10`) — an unrecognised name is a
 * CLI-rendered warning (K-4), matching `Profiles.get`'s own `Option.none`
 * contract (P-38), not a parser-level `CliError.InvalidValue`.
 */
-const profileFlag = Flag.string("profile").pipe(Flag.optional, Flag.withDescription("profile to scaffold with (default: the config's bundle.profile or software-project)"));
+const profileFlag = Flag.String("profile").pipe(Flag.optional, Flag.withDescription("profile to scaffold with (default: the config's bundle.profile or software-project)"));
 /**
 * Stands in for `profile.config` when `Profiles.get` returns `None`.
 * `OkfitConfig.merge` only visits `Object.keys(override)`
@@ -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/sync.js

@@ -10,11 +10,11 @@ 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)"));
+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"));
+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`.
+* S-13: a REPEATED `Flag.Literals`, 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
@@ -22,22 +22,22 @@ const configFlag = Flag.file("config").pipe(Flag.optional, Flag.withDescription(
 * 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
+* Note: `Flag.Literals`'s installed signature (`effect/unstable/cli/Flag.ts:169-172`)
+* takes `(name: string, literals: ReadonlyArray<string>)`, matching
 * `formatFlag` below — not the `[value, label]` tuple-pair form
-* `Flag.choiceWithValue` takes. The contract's own `onlyFlag` sketch
+* `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", [
+const onlyFlag = Flag.Literals("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"));
+const dryRunFlag = Flag.Boolean("dry-run").pipe(Flag.withDefault(false), Flag.withDescription("compute every result and write nothing"));
+const formatFlag = Flag.Literals("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]`.

package/commands/validate.js

@@ -11,13 +11,13 @@ 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"));
+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 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"));
+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"));
+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]`.
 *

package/commands/verify.js

@@ -9,17 +9,17 @@ 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"));
+/** 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"));
+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"));
+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"));
+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.Literals("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]`.

package/index.d.ts

@@ -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("@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.0",
+	"version": "0.5.0",
 	"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.112",
-		"@effected/cli": "^0.3.1",
-		"@effected/config-file": "^0.7.0",
-		"@effected/git": "^0.12.0",
-		"@effected/glob": "^0.5.0",
-		"@effected/jsonc": "^0.9.0",
-		"@effected/markdown": "^0.9.1",
-		"@effected/toml": "^0.6.0",
-		"@effected/walker": "^0.7.0",
-		"@effected/yaml": "^0.14.0",
-		"@okfit/core": "0.3.0",
-		"@okfit/engine": "0.2.0",
-		"@okfit/profiles": "0.3.0",
-		"effect": "4.0.0-rc.112"
+		"@effect/platform-node": "4.0.0-rc.115",
+		"@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.9.0",
+		"@effected/yaml": "^0.15.1",
+		"@okfit/core": "0.4.0",
+		"@okfit/engine": "0.3.0",
+		"@okfit/profiles": "0.4.0",
+		"effect": "4.0.0-rc.115"
 	},
 	"engines": {
 		"node": ">=24.11.0"

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/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.59.0"
+      "packageVersion": "7.59.1"
     }
   ]
 }

package/version.js

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