@okfit/engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @okfit/engine
+
+The shared engine behind [okfit](https://github.com/spencerbeggs/okfit): the platform layer, config discovery, and the `validate`, `verify`, `sync`, `init` and `context` programs, plus the JSON envelope contracts that `@okfit/cli` and `@okfit/mcp` both emit.
+
+You probably want `@okfit/plugin` (both bins), `@okfit/cli` (the `okfit` bin) or `@okfit/mcp` (the `okfit-mcp` bin) instead. This package is what they are built from.
+
+## License
+
+[MIT](LICENSE)

package/config/anchor.js

@@ -0,0 +1,57 @@
+//#region src/config/anchor.ts
+/**
+* The explicit `--config` anchor rule (C-8): the parent of `.config` "if the
+* file sits in a `.config` directory, else the file's directory", with no
+* exception for a custom name. Upstream's `ConfigResolver.explicitPath`
+* reports no `dir` in its `match` by design, so this stays a hand-rolled,
+* basename-based rule rather than reading `ConfigMatch.dir` — the one
+* remaining path-tail string match in the CLI outside `init/scaffold.ts`
+* (C1-4).
+*/
+const anchorForExplicit = (configPath, path) => {
+	const parent = path.dirname(configPath);
+	return path.basename(parent) === ".config" ? path.dirname(parent) : parent;
+};
+/**
+* K-12's project root, as amended by K-58 and C1-2, in order:
+*
+* 1. `pathArg`, if given. `Argument.path` has already resolved it absolute.
+* 2. otherwise, if `--config` was given: `anchorForExplicit` applied to that
+*    path.
+* 3. otherwise, if a config was discovered by the `"project"` resolver
+*    (`ConfigResolver.upwardWalk`, named `"project"` in `layer.ts`) AND it
+*    reported a `dir`: that `dir` verbatim — it is already the ancestor
+*    `upwardWalk` anchored the match against (the parent of `.config` for a
+*    `.config/okfit.toml` candidate, the candidate's own directory
+*    otherwise), so no path-tail test is needed here any more.
+* 4. otherwise `cwd` — this covers every other resolver name (`"xdg"`,
+*    `"native"`, `"system"`) as defence in depth, a `"project"` match with no
+*    `dir` (should not happen, since `upwardWalk` always reports one), and
+*    no discovery at all.
+*
+* The CLI never probes for `.git` (K-12), even though
+* `ConfigResolver.gitRoot` exists.
+*
+* @public
+*/
+const resolveProjectRoot = (input) => {
+	if (input.pathArg._tag === "Some") return input.pathArg.value;
+	if (input.explicitConfigPath._tag === "Some") return anchorForExplicit(input.explicitConfigPath.value, input.path);
+	if (input.discovered._tag === "Some") {
+		const discovered = input.discovered.value;
+		if (discovered.resolver === "project" && discovered.dir !== void 0) return discovered.dir;
+	}
+	return input.cwd;
+};
+/**
+* `<project root>/<bundle.path>`, absolute (K-2). `config` is the MERGED
+* config, so `bundle.path` is `OkfitConfig.DEFAULTS.bundle.path` (`"okf"`)
+* unless a file or profile overrode it. The bundle root is never what
+* `[path]` names.
+*
+* @public
+*/
+const resolveBundleRoot = (projectRoot, config, path) => path.resolve(projectRoot, config.bundle?.path ?? "okf");
+
+//#endregion
+export { resolveBundleRoot, resolveProjectRoot };

package/config/layer.js

@@ -0,0 +1,129 @@
+import { ConfigMalformedError, ConfigPathNotFoundError } from "../errors.js";
+import { AppConfig } from "@effected/app";
+import { ConfigCodecError, ConfigResolver, ConfigValidationError, MergeStrategy, TomlCodec } from "@effected/config-file";
+import { OkfitConfig, OkfitConfigFile } from "@okfit/core";
+import { Cause, Effect, FileSystem, Option, Result } from "effect";
+
+//#region src/config/layer.ts
+/**
+* The `OkfitConfigFile` layer for one invocation (K-9 to K-11, K-57, C-6),
+* now one `AppConfig.layer(OkfitConfigFile, ...)` call in both branches; only
+* the chain options vary:
+*
+* - `explicitConfigPath` is `Some`: `resolvers: [ConfigResolver.explicitPath(path)]`
+*   and `xdg: false` — K-10's "only that path" rule, so the chain is exactly
+*   one resolver and no `systemEtc` tier is added either.
+* - `explicitConfigPath` is `None`: `resolvers: [ConfigResolver.upwardWalk({ filenames, ... })]`
+*   carrying C-1's three per-directory candidates (`.okfit.toml`,
+*   `okfit.toml`, `.config/okfit.toml`, directory-major so a child's later
+*   candidate beats a parent's earlier one — C-2's ascent to the filesystem
+*   root is `upwardWalk`'s own default with no `stopAt`), named `"project"`
+*   so `resolve.ts`/`anchor.ts` can identify it without string-matching a
+*   path tail. `systemEtc` is C-5's `/etc` tier, present unless
+*   `systemConfigDir` overrides its root (tests only — no production call
+*   site sets it). `xdg` and `native` stay on their defaults (C-4), which is
+*   what puts personal defaults at `$XDG_CONFIG_HOME/okfit/config.toml` and
+*   the native probe behind it.
+*
+* `filename: "config.toml"` is the same in both branches — it is the XDG/
+* native/system tiers' filename, unrelated to the C-1 project names above.
+* `defaultPath` is `AppConfig.layer`'s own `XdgConfig.savePath(filename)`, so
+* `save`/`update` do not fail with `ConfigDefaultPathMissingError`; nothing
+* here sets it explicitly any more.
+*
+* `discoveryCwd` is `[path]` when given, else `process.cwd()` (K-2), passed
+* straight through as `upwardWalk`'s own `cwd` so nothing in this module
+* reads the process.
+*
+* `App.layer`, `AppStore` and `AppCache` appear nowhere, so no
+* `store.db`/`cache.db` is ever created (K-9).
+*
+* @public
+*/
+const buildConfigLayer = (options) => Option.isSome(options.explicitConfigPath) ? AppConfig.layer(OkfitConfigFile, {
+	filename: "config.toml",
+	schema: OkfitConfig,
+	codec: TomlCodec,
+	strategy: MergeStrategy.firstMatch(),
+	resolvers: [ConfigResolver.explicitPath(options.explicitConfigPath.value)],
+	xdg: false
+}) : AppConfig.layer(OkfitConfigFile, {
+	filename: "config.toml",
+	schema: OkfitConfig,
+	codec: TomlCodec,
+	strategy: MergeStrategy.firstMatch(),
+	resolvers: [ConfigResolver.upwardWalk({
+		filenames: [
+			".okfit.toml",
+			"okfit.toml",
+			".config/okfit.toml"
+		],
+		cwd: options.discoveryCwd,
+		name: "project"
+	})],
+	systemEtc: options.systemConfigDir === void 0 ? true : { dir: options.systemConfigDir }
+});
+/**
+* The K-1 pre-flight and the provide, in that order and in one place: stat
+* `explicitConfigPath` with `FileSystem.exists` and fail with
+* `ConfigPathNotFoundError` BEFORE `buildConfigLayer` is called at all. This
+* is why the CLI does not use `Command.provide(cmd, (input) => layer)`,
+* which would construct the layer first (Judge notes 9) — here the stat
+* runs as the first step of one `Effect.gen`, and `buildConfigLayer` is only
+* reached, and only then actually run, on the step after it.
+*
+* `FileSystem.FileSystem.exists` is `(path: string) => Effect.Effect<boolean, PlatformError>`
+* (`EF/FileSystem.ts:143-145`), not infallible, so
+* `PlatformError.PlatformError` joins the error channel here (decision 7):
+* an unusual stat failure (e.g. a permission error on a parent directory)
+* renders through `renderFailure`'s catch-all rule rather than being
+* uncatchable by the type checker.
+*
+* K-46/K-63 fix: a `ConfigCodecError`/`ConfigValidationError` from
+* `buildConfigLayer`'s provided layer is wrapped into `ConfigMalformedError`
+* whenever the failing path is known, so `renderFailure` can name it:
+*
+* - `ConfigCodecError` now carries its own `path: string | undefined`
+*   (config-file 0.7.0, `ConfigFile.discover` re-raises with `path` attached
+*   at every site that fed the codec a path it resolved) — used when
+*   present, so a malformed file found during DISCOVERY (no `--config`) now
+*   also wraps into `ConfigMalformedError` naming the candidate that failed,
+*   closing the K-63 gap. It falls back to `explicitConfigPath` only when
+*   the library's own `path` is `undefined` and `--config` was given; only
+*   when neither is known does the cause pass through unwrapped.
+* - `ConfigValidationError` carries its own `path: Option<string>` — used
+*   when present (either branch), falling back to `explicitConfigPath` when
+*   the library's own `path` is `None` and `--config` was given.
+*
+* @public
+*/
+const provideConfig = (options) => (effect) => Effect.gen(function* () {
+	if (Option.isSome(options.explicitConfigPath)) {
+		const path = options.explicitConfigPath.value;
+		if (!(yield* (yield* FileSystem.FileSystem).exists(path))) return yield* Effect.fail(new ConfigPathNotFoundError({ path }));
+	}
+	return yield* effect.pipe(Effect.provide(buildConfigLayer(options)), Effect.catchCause((cause) => {
+		const found = Cause.findFail(cause);
+		if (Result.isSuccess(found)) {
+			const error = found.success.error;
+			if (error instanceof ConfigCodecError) {
+				const path = error.path !== void 0 ? error.path : Option.isSome(options.explicitConfigPath) ? options.explicitConfigPath.value : void 0;
+				if (path !== void 0) return Effect.fail(new ConfigMalformedError({
+					path,
+					cause: error
+				}));
+			}
+			if (error instanceof ConfigValidationError) {
+				const path = Option.isSome(options.explicitConfigPath) ? options.explicitConfigPath : error.path;
+				if (Option.isSome(path)) return Effect.fail(new ConfigMalformedError({
+					path: path.value,
+					cause: error
+				}));
+			}
+		}
+		return Effect.failCause(cause);
+	}));
+});
+
+//#endregion
+export { buildConfigLayer, provideConfig };

package/config/resolve.js

@@ -0,0 +1,67 @@
+import { resolveBundleRoot, resolveProjectRoot } from "./anchor.js";
+import { OKF_SPEC_VERSION, OkfitConfig, OkfitConfigFile } from "@okfit/core";
+import { Console, Effect, Option, Path } from "effect";
+import { Profiles } from "@okfit/profiles";
+
+//#region src/config/resolve.ts
+/**
+* `OkfitConfig.DEFAULTS.bundle.profile` is `"software-project"` at runtime
+* (the frozen literal always sets it), but `bundle` and `profile` are both
+* `optionalKey` in the schema, so the type checker sees `string | undefined`
+* two levels deep. The `?? "software-project"` fallback here is unreachable
+* in practice; it exists only to satisfy `noUncheckedIndexedAccess`-style
+* strictness without a non-null assertion. Formerly duplicated identically
+* in `commands/validate.ts` and `commands/context.ts`; this is its one home
+* now that both commands delegate to {@link resolveProjectConfig}.
+*
+* @public
+*/
+const DEFAULT_PROFILE_NAME = OkfitConfig.DEFAULTS.bundle?.profile ?? "software-project";
+/**
+* The config-resolution step byte-identical between `validate` and
+* `context`'s handlers (A2 review finding): discover, pick `sources[0]`,
+* default `{ extensions: {} }`, resolve the profile name and the K-4
+* unknown-profile warning, merge `DEFAULTS < profile < file` (D-28), warn on
+* an `okf_version` mismatch (K-15), then resolve the project and bundle
+* roots (K-12). Every message string and the merge order are unchanged from
+* the two commands' former inline copies.
+*
+* @public
+*/
+const resolveProjectConfig = (input) => Effect.gen(function* () {
+	const path = yield* Path.Path;
+	const discoveredSource = (yield* (yield* OkfitConfigFile).discover)[0];
+	const fileConfig = discoveredSource === void 0 ? { extensions: {} } : discoveredSource.value;
+	const profileName = fileConfig.bundle?.profile ?? DEFAULT_PROFILE_NAME;
+	const profile = profileName === "none" ? Option.none() : Profiles.get(profileName);
+	if (profileName !== "none" && Option.isNone(profile)) yield* Console.error(`warning: unknown profile "${profileName}"; continuing with defaults`);
+	const base = Option.match(profile, {
+		onNone: () => OkfitConfig.DEFAULTS,
+		onSome: (p) => OkfitConfig.merge(OkfitConfig.DEFAULTS, p.config)
+	});
+	const merged = OkfitConfig.merge(base, fileConfig);
+	if (merged.okf_version !== void 0 && merged.okf_version !== OKF_SPEC_VERSION) yield* Console.error(`warning: okf_version "${merged.okf_version}" does not match this okfit's spec version "${OKF_SPEC_VERSION}"; continuing`);
+	const discovered = discoveredSource === void 0 ? Option.none() : Option.some({
+		path: discoveredSource.path,
+		resolver: discoveredSource.resolver,
+		...discoveredSource.match?.dir !== void 0 ? { dir: discoveredSource.match.dir } : {}
+	});
+	const projectRoot = resolveProjectRoot({
+		pathArg: input.pathArg,
+		explicitConfigPath: input.explicitConfigPath,
+		discovered,
+		cwd: input.cwd,
+		path
+	});
+	return {
+		projectRoot,
+		bundleRoot: resolveBundleRoot(projectRoot, merged, path),
+		config: merged,
+		profile,
+		profileName,
+		discovered
+	};
+});
+
+//#endregion
+export { DEFAULT_PROFILE_NAME, resolveProjectConfig };

package/context/run.js

@@ -0,0 +1,35 @@
+import { Effect, FileSystem, Path } from "effect";
+
+//#region src/context/run.ts
+/**
+* The whole of `context`'s filesystem work: join `index.md` onto the bundle
+* root and stat it. Loading a bundle and running conformance/lint checks
+* over it never happen here — that is what makes `context` cheap enough
+* for a hook to run on every session start and every in-bundle write
+* (M-15).
+*
+* `"index.md"` is a literal here, not read from the profile's layout: the
+* spec fixes the reserved filename regardless of profile, and a
+* profile-less merge (`profile = "none"`) has no layout to read from at
+* all — `context` behaves identically with and without a profile.
+*
+* `exists` is `(path) => Effect.Effect<boolean, PlatformError>`, so an
+* unreadable parent directory would otherwise fail the command; here it is
+* absorbed to `false`, because "the hook could not stat index.md" and
+* "index.md is not there" are the same fact from a consumer's point of
+* view.
+*
+* @public
+*/
+const runContext = (options) => Effect.gen(function* () {
+	const path = yield* Path.Path;
+	const fs = yield* FileSystem.FileSystem;
+	const indexPath = path.join(options.bundleRoot, "index.md");
+	return {
+		indexPath,
+		indexExists: yield* fs.exists(indexPath).pipe(Effect.orElseSucceed(() => false))
+	};
+});
+
+//#endregion
+export { runContext };

package/errors.js

@@ -0,0 +1,109 @@
+import { Runtime, Schema } from "effect";
+
+//#region src/errors.ts
+/**
+* `--config <path>` named a path that does not exist. Every `ConfigResolver`
+* has a `never` error channel and `explicitPath` absorbs a missing target
+* into `Option.none()`, so a bad `--config` would otherwise fall through to
+* the XDG file silently. The CLI checks it itself before building any layer
+* (K-1, spec 4.1).
+*
+* @public
+*/
+var ConfigPathNotFoundError = class extends Schema.TaggedError()("ConfigPathNotFoundError", { path: Schema.String }) {
+	[Runtime.errorExitCode] = 3;
+	get message() {
+		return `config path not found: ${this.path}`;
+	}
+};
+/**
+* `okfit init` found one or more of its target paths already present (K-28).
+* Carries the whole conflicting-path list so the renderer prints every one.
+* `paths` are absolute; `renderFailure` relativises them to `cwd` (K-51).
+*
+* @public
+*/
+var InitOverwriteError = class extends Schema.TaggedError()("InitOverwriteError", {
+	paths: Schema.Array(Schema.String),
+	cwd: Schema.String
+}) {
+	[Runtime.errorExitCode] = 3;
+	get message() {
+		return "refusing to overwrite existing files";
+	}
+};
+/**
+* V-9: `<id>` did not resolve to a verifiable concept. `reason` is
+* `"not-a-concept"` (no such file, or an id that normalises to nothing),
+* `"reserved"` (the id names `index.md` or `log.md`), or `"undecodable"`
+* (a file exists but `bundle.diagnostics` names it — `diagnosticCode`
+* carries which). `root` is the absolute bundle root, kept OFF `message`
+* so K-51's relativisation rule has nothing to apply to and the human
+* line and the JSON envelope's `message` are identical.
+*
+* @public
+*/
+var VerifyConceptNotFoundError = class extends Schema.TaggedError()("VerifyConceptNotFoundError", {
+	id: Schema.String,
+	root: Schema.String,
+	reason: Schema.Literals([
+		"not-a-concept",
+		"reserved",
+		"undecodable"
+	]),
+	diagnosticCode: Schema.optionalKey(Schema.String)
+}) {
+	[Runtime.errorExitCode] = 3;
+	get message() {
+		const detail = this.diagnosticCode === void 0 ? this.reason : `${this.reason}: ${this.diagnosticCode}`;
+		return `no concept "${this.id}" in this bundle (${detail})`;
+	}
+};
+/**
+* V-14: fail closed on a `verified` shape the classifier does not name.
+* `shape` is one of `"alias"`, `"merge-key"`, `"scalar"`, `"empty"` (and,
+* defensively, `"no-frontmatter"` or `"not-a-mapping"`, neither reachable
+* for a concept that reached `bundle.concepts`). The file is never opened
+* for writing when this is raised.
+*
+* @public
+*/
+var VerifyUnsupportedFrontmatterError = class extends Schema.TaggedError()("VerifyUnsupportedFrontmatterError", {
+	id: Schema.String,
+	shape: Schema.String
+}) {
+	[Runtime.errorExitCode] = 3;
+	get message() {
+		return `"${this.id}"'s verified value is a shape okfit verify cannot edit (${this.shape}); edit it by hand`;
+	}
+};
+/** The error's `message` when it has one as a string, else `String(error)`. */
+const messageOf = (error) => {
+	if (typeof error === "object" && error !== null && "message" in error) {
+		const message = error.message;
+		if (typeof message === "string") return message;
+	}
+	return String(error);
+};
+/**
+* A config file at a KNOWN path failed to parse or validate (K-46's own
+* intent — "each class' message already names the offending path" does not
+* hold for `@effected/config-file`'s `ConfigCodecError`, which carries no
+* `path` field at all; this wraps it, and `ConfigValidationError`, with the
+* path the caller already knows). `cause` is the original config-file error,
+* preserved structurally, never stringified early.
+*
+* @public
+*/
+var ConfigMalformedError = class extends Schema.TaggedError()("ConfigMalformedError", {
+	path: Schema.String,
+	cause: Schema.Defect()
+}) {
+	[Runtime.errorExitCode] = 3;
+	get message() {
+		return `malformed config ${this.path}: ${messageOf(this.cause)}`;
+	}
+};
+
+//#endregion
+export { ConfigMalformedError, ConfigPathNotFoundError, InitOverwriteError, VerifyConceptNotFoundError, VerifyUnsupportedFrontmatterError };