@okfit/engine 0.1.0

package/render/verify.js

@@ -0,0 +1,47 @@
+import { Schema } from "effect";
+
+//#region src/render/verify.ts
+/**
+* V-11's success envelope, schema 1, snake_case — the same convention as
+* `render/json.ts`'s `JsonEnvelope`. Identical in shape for a dry run,
+* which sets `dry_run: true` and still exits 0. There is no content tier,
+* so `exit_code` is the literal `0`; a failure produces K-22's
+* `JsonErrorEnvelope` instead, unchanged.
+*
+* @public
+*/
+const VerifyEnvelope = Schema.Struct({
+	schema: Schema.Literal(1),
+	okfit_version: Schema.String,
+	id: Schema.String,
+	path: Schema.String,
+	verified: Schema.Struct({
+		by: Schema.String,
+		at: Schema.String
+	}),
+	dry_run: Schema.Boolean,
+	exit_code: Schema.Literal(0)
+});
+/**
+* `path` is already the display form — `displayRoot(cwd, bundle.root, path)`
+* joined to the bundle-relative `concept.path` — because `LoadedConcept.path`
+* alone would print `decisions/cli-exit-codes.md`, not
+* `okf/decisions/cli-exit-codes.md` (contract §12 note 5).
+*
+* @public
+*/
+const verifyEnvelope = (input) => ({
+	schema: 1,
+	okfit_version: input.okfitVersion,
+	id: input.id,
+	path: input.path,
+	verified: {
+		by: input.by,
+		at: input.at
+	},
+	dry_run: input.dryRun,
+	exit_code: 0
+});
+
+//#endregion
+export { VerifyEnvelope, verifyEnvelope };

package/sync/generated.js

@@ -0,0 +1,111 @@
+import { detectNewline, locateGenerated, stripBom } from "../verify/locate.js";
+import { spliceGenerated } from "../verify/splice.js";
+import { writeAtomic } from "./write.js";
+import { Timestamp } from "@okfit/core";
+import { DateTime, Effect, FileSystem, Path, Schema } from "effect";
+import { MarkdownEdit } from "@effected/markdown";
+
+//#region src/sync/generated.ts
+/**
+* The five `SkipReason` members contract §6.2's algorithm can actually
+* produce — a strict subset of contract §5's six-member `SkipReason`
+* (`sync/run.ts`, Task B3; the sixth, `"log-unparseable"`, is log mode's
+* alone). Declared locally because `sync/run.ts` does not exist when this
+* task lands (fixed order A1 -> A2 -> B1 -> B2 -> B3); every member here is
+* spelled identically to its `SkipReason` counterpart, so Task B3 assigns
+* a `GeneratedSkipReason` value into a `SkipReason`-typed field with no
+* cast.
+*
+* @internal
+*/
+const GeneratedSkipReason = Schema.Literals([
+	"untracked",
+	"dirty",
+	"unborn",
+	"generated-missing",
+	"generated-unsupported"
+]);
+const encodeAt = Schema.encodeSync(Timestamp);
+/**
+* Contract §6.2's twelve-step algorithm, run once per `bundle.concepts`
+* entry (S-22: `index.md`/`log.md` are reserved files, never concepts,
+* never seen here). `provenance` is the single `Derivation.generatedAt`
+* walk `runSync` (Task B3) computes once and shares with log mode; this
+* function never calls git itself and never substitutes `now` for an
+* uncommitted body (design §3 rule 2). Every write is atomic (temp file
+* plus rename in the same directory), matching `verify`'s own discipline
+* (`verify/run.ts`'s `runVerify`).
+*
+* `locateGenerated`'s `YamlParseError` is folded into a defect here
+* (`Effect.orDie`), not widened into this function's typed error channel:
+* the frontmatter it re-parses already decoded once, successfully, for
+* this concept to be a member of `bundle.concepts` at all -- the same
+* reasoning `locate.ts`'s own `locate` documents for its identical
+* failure mode. `runSync`'s stated error union (`BundleLoadError |
+* GeneratedAtError`, contract §5) already includes `PlatformError.
+* PlatformError` inside `GeneratedAtError` (contract §14 note 2), so this
+* function's own `PlatformError.PlatformError` channel composes with no
+* widening on either side.
+*
+* @internal
+*/
+const syncGenerated = Effect.fn("okfit/sync/syncGenerated")(function* (bundle, provenance, dryRun) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const written = [];
+	const unchanged = [];
+	const skipped = [];
+	for (const [id, concept] of bundle.concepts) {
+		const derived = provenance.get(id);
+		if (derived === void 0) return yield* Effect.die(/* @__PURE__ */ new Error(`syncGenerated: no provenance computed for concept ${id}`));
+		if (derived._tag === "uncommitted") {
+			skipped.push({
+				id,
+				reason: derived.reason
+			});
+			continue;
+		}
+		const generated = concept.frontmatter.generated;
+		if (generated === void 0) {
+			skipped.push({
+				id,
+				reason: "generated-missing"
+			});
+			continue;
+		}
+		const recorded = generated.at;
+		if (recorded !== void 0 && DateTime.Equivalence(recorded, derived.at)) {
+			unchanged.push(id);
+			continue;
+		}
+		const absolutePath = path.join(bundle.root, concept.path);
+		const source = yield* fs.readFileString(absolutePath);
+		const { text, bom } = stripBom(source);
+		const newline = detectNewline(text);
+		const located = yield* locateGenerated(text).pipe(Effect.orDie);
+		if (located._tag === "unsupported") {
+			skipped.push({
+				id,
+				reason: "generated-unsupported"
+			});
+			continue;
+		}
+		const encodedAt = encodeAt(derived.at);
+		const edit = spliceGenerated(located, encodedAt, newline);
+		const finalText = bom + MarkdownEdit.applyAll(text, [edit]);
+		if (dryRun) {
+			written.push(id);
+			continue;
+		}
+		yield* writeAtomic(absolutePath, finalText);
+		written.push(id);
+	}
+	return {
+		written,
+		unchanged,
+		skipped
+	};
+});
+
+//#endregion
+export { syncGenerated };

package/sync/index.js

@@ -0,0 +1,73 @@
+import { writeAtomic } from "./write.js";
+import { Derive, OKF_SPEC_VERSION } from "@okfit/core";
+import { Effect, FileSystem, Path } from "effect";
+
+//#region src/sync/index.ts
+/**
+* Immediate child directories of `dir`, unioned from `bundle.directories`
+* and `bundle.indexes.keys()` -- the same union `Derive.synthesizeIndex`
+* walks (S-29, amending S-20's wording): a directory holding only an
+* `index.md` and no concepts is never a member of `bundle.directories`
+* (`Bundle.load` records a directory there only when it holds a concept),
+* but it is still a key of `bundle.indexes`, so omitting that map would
+* silently drop it from the root's `# Subdirectories` section while every
+* other directory's own `synthesizeIndex` call still lists it as a child.
+*/
+const childDirectoriesOf = (bundle, dir) => {
+	const prefix = dir === "" ? "" : `${dir}/`;
+	const children = /* @__PURE__ */ new Set();
+	for (const candidate of [...bundle.directories, ...bundle.indexes.keys()]) {
+		if (candidate === "" || candidate === dir || !candidate.startsWith(prefix)) continue;
+		const head = candidate.slice(prefix.length).split("/")[0];
+		if (head !== void 0 && head !== "") children.add(head);
+	}
+	return [...children];
+};
+const writeOrCompare = Effect.fn("okfit/sync/index/writeOrCompare")(function* (targetPath, relativeId, rendered, dryRun, written, unchanged) {
+	if ((yield* (yield* FileSystem.FileSystem).readFileString(targetPath).pipe(Effect.map((text) => text), Effect.catchReason("PlatformError", "NotFound", () => Effect.succeed(void 0)))) === rendered) {
+		unchanged.push(relativeId);
+		return;
+	}
+	if (dryRun) {
+		written.push(relativeId);
+		return;
+	}
+	yield* writeAtomic(targetPath, rendered);
+	written.push(relativeId);
+});
+/**
+* Contract §7. Directories: the bundle root plus every directory in
+* `bundle.directories` that holds at least one concept -- the same set
+* `Derive.synthesizeIndex` already walks (S-20). A directory with an
+* `index.md` but no concepts is left untouched (design §4: "nothing to
+* derive") because such a directory is never a member of
+* `bundle.directories` in the first place (`Bundle.load` only records a
+* directory there when it holds a concept -- `Bundle.ts:301-323`).
+*
+* @internal
+*/
+const syncIndex = Effect.fn("okfit/sync/syncIndex")(function* (bundle, dryRun) {
+	const path = yield* Path.Path;
+	const written = [];
+	const unchanged = [];
+	const rootConcepts = [...bundle.concepts.values()].filter((concept) => !concept.path.includes("/"));
+	const rootRendered = Derive.renderIndex("", rootConcepts, {
+		okfVersion: OKF_SPEC_VERSION,
+		subdirectories: childDirectoriesOf(bundle, "")
+	});
+	yield* writeOrCompare(path.join(bundle.root, "index.md"), "index.md", rootRendered, dryRun, written, unchanged);
+	for (const dir of bundle.directories) {
+		if (dir === "") continue;
+		const rendered = Derive.synthesizeIndex(bundle, dir);
+		yield* writeOrCompare(path.join(bundle.root, dir, "index.md"), `${dir}/index.md`, rendered, dryRun, written, unchanged);
+	}
+	return {
+		selected: true,
+		written,
+		unchanged,
+		skipped: []
+	};
+});
+
+//#endregion
+export { syncIndex };

package/sync/log.js

@@ -0,0 +1,127 @@
+import { writeAtomic } from "./write.js";
+import { Derive } from "@okfit/core";
+import { DateTime, Effect, FileSystem, Path } from "effect";
+
+//#region src/sync/log.ts
+const byTitle = (a, b) => a.title < b.title ? -1 : a.title > b.title ? 1 : 0;
+const renderItem = (item) => item.added ? `Added ${item.title}` : `Updated ${item.title}`;
+/**
+* S-10: takes STRUCTURED additions (`{date, title, added}`), not
+* pre-rendered strings -- this is the corrected shape of CP §2's own
+* proposal (contract §14 note 4): rendering "Added <title>"/
+* "Updated <title>" happens INSIDE `mergeLog`, so "sort by title" (design
+* §5 step 4) sorts the actual title field, never a substring of a
+* pre-rendered line. Renders a NEW group's items via
+* `Derive.renderLogEntry` (S-11's per-group renderer); an EXISTING
+* group's text (heading and items) is re-emitted verbatim by slicing
+* `existing.source` on the group's own `LogGroup.range` -- never
+* re-serialised, so a hand-written item, comment, or unusual formatting
+* inside an existing group survives byte-for-byte.
+*
+* @internal
+*/
+const mergeLog = (existing, additions) => {
+	const title = existing?.doc.title ?? "Log";
+	const byDate = /* @__PURE__ */ new Map();
+	if (existing !== void 0) for (const group of existing.doc.groups) {
+		const verbatim = existing.source.slice(group.range.offset, group.range.offset + group.range.length);
+		byDate.set(group.date, {
+			verbatim,
+			pending: []
+		});
+	}
+	for (const addition of additions) {
+		const bucket = byDate.get(addition.date) ?? {
+			verbatim: void 0,
+			pending: []
+		};
+		bucket.pending.push({
+			title: addition.title,
+			added: addition.added
+		});
+		byDate.set(addition.date, bucket);
+	}
+	const dates = [...byDate.keys()].sort((a, b) => a < b ? 1 : a > b ? -1 : 0);
+	const pieces = dates.map((date, index) => {
+		const bucket = byDate.get(date);
+		let piece;
+		if (bucket === void 0) piece = "";
+		else if (bucket.verbatim === void 0) {
+			const items = [...bucket.pending].sort(byTitle).map(renderItem);
+			piece = Derive.renderLogEntry({
+				date,
+				items
+			});
+		} else if (bucket.pending.length === 0) piece = bucket.verbatim;
+		else {
+			const trailingNewlines = /\n+$/.exec(bucket.verbatim)?.[0] ?? "";
+			const base = bucket.verbatim.slice(0, bucket.verbatim.length - trailingNewlines.length);
+			const trailer = trailingNewlines.slice(1);
+			piece = `${base}\n${[...bucket.pending].sort(byTitle).map((item) => `* ${renderItem(item)}\n`).join("")}${trailer}`;
+		}
+		return !(index === dates.length - 1) && !piece.endsWith("\n\n") ? `${piece}\n` : piece;
+	});
+	return dates.length === 0 ? `# ${title}\n` : `# ${title}\n\n${pieces.join("")}`;
+};
+/**
+* Contract §8.2. Only the root `log.md`; `bundle.concepts` is the only
+* thing scanned -- `index.md`/`log.md` are reserved files, never concepts
+* (S-22, contract §14 note 8 -- closes PB's Open question 1 outright: an
+* `Updated index`/`Updated log` line can never occur).
+*
+* @internal
+*/
+const syncLog = Effect.fn("okfit/sync/syncLog")(function* (bundle, provenance, dryRun) {
+	const fs = yield* FileSystem.FileSystem;
+	const logPath = (yield* Path.Path).join(bundle.root, "log.md");
+	const source = yield* fs.readFileString(logPath).pipe(Effect.map((text) => text), Effect.catchReason("PlatformError", "NotFound", () => Effect.succeed(void 0)));
+	const existingDoc = bundle.logs.get("");
+	if (source !== void 0 && existingDoc === void 0) return {
+		selected: true,
+		written: [],
+		unchanged: [],
+		skipped: [{
+			id: "log.md",
+			reason: "log-unparseable"
+		}]
+	};
+	const newestLogged = (existingDoc?.groups ?? []).map((entryGroup) => entryGroup.date).reduce((max, date) => max === void 0 || date > max ? date : max, void 0);
+	const additions = [];
+	for (const [id, concept] of bundle.concepts) {
+		const derived = provenance.get(id);
+		if (derived === void 0 || derived._tag !== "committed") continue;
+		const date = DateTime.formatIsoDate(derived.at);
+		if (newestLogged !== void 0 && date <= newestLogged) continue;
+		additions.push({
+			date,
+			title: Derive.title(concept),
+			added: derived.creating
+		});
+	}
+	const merged = mergeLog(source === void 0 || existingDoc === void 0 ? void 0 : {
+		doc: existingDoc,
+		source
+	}, additions);
+	if (merged === (source ?? "")) return {
+		selected: true,
+		written: [],
+		unchanged: ["log.md"],
+		skipped: []
+	};
+	if (dryRun) return {
+		selected: true,
+		written: ["log.md"],
+		unchanged: [],
+		skipped: []
+	};
+	yield* writeAtomic(logPath, merged);
+	return {
+		selected: true,
+		written: ["log.md"],
+		unchanged: [],
+		skipped: []
+	};
+});
+
+//#endregion
+export { mergeLog, syncLog };

package/sync/run.js

@@ -0,0 +1,65 @@
+import { syncGenerated } from "./generated.js";
+import { syncIndex } from "./index.js";
+import { syncLog } from "./log.js";
+import { Bundle } from "@okfit/core";
+import { Effect, Schema } from "effect";
+import { Derivation } from "@okfit/profiles";
+
+//#region src/sync/run.ts
+/**
+* S-14: a closed union, not free text. The human renderer maps each member
+* to one fixed sentence (`render/sync.ts#humanSync`); the JSON envelope's
+* `skipped[].reason` is this exact union.
+*
+* @public
+*/
+const SkipReason = Schema.Literals([
+	"untracked",
+	"dirty",
+	"unborn",
+	"generated-missing",
+	"generated-unsupported",
+	"log-unparseable"
+]);
+/** A selected-`false` placeholder for a mode `--only` excluded from (contract §5). */
+const UNSELECTED = {
+	selected: false,
+	written: [],
+	unchanged: [],
+	skipped: []
+};
+/**
+* Contract §5's six-step algorithm: one `Bundle.load`, one
+* `Derivation.generatedAt` per concept shared by the generated and log
+* modes (skipped entirely when neither is selected), then the three modes
+* in a FIXED order — generated, index, log — regardless of `--only`'s own
+* occurrence order, so a generated write never invalidates an index or log
+* rendered in the same run (design §2).
+*
+* @public
+*/
+const runSync = Effect.fn("okfit/sync/runSync")(function* (options) {
+	const bundle = yield* Bundle.load({ root: options.bundleRoot });
+	const needsGit = options.modes.has("generated") || options.modes.has("log");
+	const provenance = /* @__PURE__ */ new Map();
+	if (needsGit) for (const [id, concept] of bundle.concepts) {
+		const derived = yield* Derivation.generatedAt({ file: `${bundle.root}/${concept.path}` });
+		provenance.set(id, derived);
+	}
+	const generated = options.modes.has("generated") ? {
+		selected: true,
+		...yield* syncGenerated(bundle, provenance, options.dryRun)
+	} : UNSELECTED;
+	const index = options.modes.has("index") ? yield* syncIndex(bundle, options.dryRun) : UNSELECTED;
+	const log = options.modes.has("log") ? yield* syncLog(bundle, provenance, options.dryRun) : UNSELECTED;
+	return {
+		bundleRoot: options.bundleRoot,
+		dryRun: options.dryRun,
+		generated,
+		index,
+		log
+	};
+});
+
+//#endregion
+export { SkipReason, runSync };

package/sync/write.js

@@ -0,0 +1,48 @@
+import { Effect, FileSystem, Option, Path } from "effect";
+import { randomUUID } from "node:crypto";
+
+//#region src/sync/write.ts
+/**
+* S-33: the one atomic write every sync mode shares. Resolves `target`'s
+* real path first when it already exists (so a symlinked
+* `index.md`/`log.md`/concept file is replaced by writing through the
+* link rather than over it -- `generated` mode's own discipline, formerly
+* not shared with `index`/`log`) and falls back to `target` itself for a
+* file `sync` is about to create for the first time (`index`/`log` modes
+* both write files that may not exist yet; `generated` mode's targets
+* always exist, since they come from an already-loaded concept). Writes
+* `contents` to a uniquely-scoped temp file beside the resolved target (so
+* two concurrent `sync` runs never collide on a fixed name), preserves an
+* existing target's mode via `stat` + `chmod` (a brand-new file keeps
+* whatever mode `writeFileString` gives it), and renames the temp file
+* over the target. On any failure -- including a failed `rename` -- the
+* temp file is removed (`Effect.onError`), so a partial write never
+* leaves a stray `<file>.okfit-sync.<token>.tmp` behind (F-5/S-33).
+*
+* DISCREPANCY from S-33's literal "the temp name carries the pid": `src/`
+* outside `bin.ts`/`commands/*`/`internal/exit.ts`/`internal/tty.ts` never
+* reads the global `process` (K-39, enforced by `__test__/boundaries.test.ts`),
+* and `sync/write.ts` is not on that allowlist. A `randomUUID()` token
+* (`node:crypto`, not `process`) satisfies S-33's actual requirement --
+* two concurrent `sync` runs never collide on a fixed temp name -- without
+* widening the process-access boundary for one helper. Recorded here per
+* the Global Constraints' "record the discrepancy" instruction.
+*
+* @internal
+*/
+const writeAtomic = Effect.fn("okfit/sync/writeAtomic")(function* (target, contents) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const resolved = yield* fs.realPath(target).pipe(Effect.catchReason("PlatformError", "NotFound", () => Effect.succeed(target)));
+	const dir = path.dirname(resolved);
+	const base = path.basename(resolved);
+	const tempPath = path.join(dir, `${base}.okfit-sync.${randomUUID()}.tmp`);
+	const originalMode = yield* fs.stat(resolved).pipe(Effect.map((info) => Option.some(info.mode)), Effect.catchReason("PlatformError", "NotFound", () => Effect.succeed(Option.none())));
+	yield* fs.writeFileString(tempPath, contents).pipe(Effect.tap(() => Option.match(originalMode, {
+		onNone: () => Effect.void,
+		onSome: (mode) => fs.chmod(tempPath, mode)
+	})), Effect.tap(() => fs.rename(tempPath, resolved)), Effect.onError(() => fs.remove(tempPath, { force: true }).pipe(Effect.ignore)));
+});
+
+//#endregion
+export { writeAtomic };

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.59.0"
+    }
+  ]
+}

package/validate/run.js

@@ -0,0 +1,63 @@
+import { Bundle, OkfitConfig, Validate } from "@okfit/core";
+import { Context, Effect, Option } from "effect";
+import { Provenance } from "@okfit/profiles";
+
+//#region src/validate/run.ts
+/**
+* K-47's ambient clock. `bin.ts` resolves `OKFIT_NOW` (or the wall clock)
+* exactly once and provides it with `Effect.provideService(Now, value)`
+* around the whole command tree; `commands/validate.ts` and
+* `commands/init.ts` each read it with `const now = yield* Now;` before
+* building {@link RunOptions} or a scaffold's `today`. Not re-exported from
+* `index.ts`: like `internal/exit.ts` and `internal/tty.ts`, it means
+* nothing outside a spawned process (K-49). `Context.Tag` does not exist on
+* the Effect v4 line; the v4 shape is
+* `Context.Service<Self, Shape>()(id)`, the same form core and profiles use
+* for their own services (`PROFILES/GitHistory.ts:140`) — source wins over
+* the contract's literal snippet here (K-62).
+*
+* @internal
+*/
+var Now = class extends Context.Service()("@okfit/engine/Now") {};
+/**
+* Load, validate both tiers, run the profile check, then — UNLESS the
+* `generated-at-drift` lint is `off` OR `options.skipProvenance` is `true`
+* — run `Provenance.lint` and append its `Diagnostic`s to `report.lint`.
+* The "skip the git walk entirely" gate lives HERE, in `run`, not inside
+* `Provenance.lint` (S-8's own wording): a bundle configured `off`, or a
+* caller that passed `--skip-provenance`, never pays for a git spawn
+* (S-31). An `error` severity on the appended diagnostics yields exit `1`
+* through the EXISTING lint-tier rule in `render/exit.ts` — no renderer
+* branch, no new `DiagnosticSource`, since these diagnostics flow through
+* the same `report.lint` array every other core lint diagnostic already
+* does.
+*
+* K-52 holds structurally: `Bundle.load`'s failure short-circuits the
+* generator, so `profile.check` never runs on a bundle that did not load.
+*
+* This is a BREAKING signature change: `@okfit/mcp`'s `validateBundle.ts`
+* calls this function directly and must be updated to match (Task C1);
+* `commands/validate.ts` is the other caller.
+*
+* @public
+*/
+const run = (options) => Effect.gen(function* () {
+	const bundle = yield* Bundle.load({ root: options.root });
+	const report = Validate.all(bundle, options.config, { now: options.now });
+	const profileDiagnostics = Option.match(options.profile, {
+		onNone: () => [],
+		onSome: (profile) => profile.check(bundle)
+	});
+	const provenance = OkfitConfig.severityFor(options.config, "generated-at-drift") === "off" || options.skipProvenance === true ? [] : yield* Provenance.lint(bundle, options.config);
+	return {
+		bundle,
+		report: {
+			...report,
+			lint: [...report.lint, ...provenance]
+		},
+		profileDiagnostics
+	};
+});
+
+//#endregion
+export { Now, run };