@okfit/engine 0.3.0 → 0.4.0

package/graph/run.js

@@ -0,0 +1,20 @@
+import { Bundle, Graph } from "@okfit/core";
+import { Effect } from "effect";
+
+//#region src/graph/run.ts
+/**
+* Load the bundle and build its link graph (D-6, D-26). Pure over the
+* loaded bundle once loading succeeds; `okfit graph` always exits `0`.
+*
+* @public
+*/
+const runGraph = (options) => Effect.gen(function* () {
+	const bundle = yield* Bundle.load({ root: options.root });
+	return {
+		bundle,
+		graph: Graph.fromBundle(bundle)
+	};
+});
+
+//#endregion
+export { runGraph };

package/index.d.ts

@@ -1,4 +1,4 @@
-import { BundleLoadError, ConceptId, Diagnostic, DiagnosticRange, DiagnosticSeverity, LoadedBundle, OkfitConfig, OkfitConfigFile, ValidationReport } from "@okfit/core";
+import { BundleLoadError, ConceptId, Diagnostic, DiagnosticRange, DiagnosticSeverity, GraphLink, GraphNode, LinkGraph, LoadedBundle, OkfitConfig, OkfitConfigFile, StaleConcept, ValidationReport } from "@okfit/core";
 import { Context, Crypto, DateTime, Effect, FileSystem, Layer, Option, Path, PlatformError, Runtime, Schema } from "effect";
 import { AppDirs, Xdg } from "@effected/xdg";
 import { ConfigReadError } from "@effected/config-file";
@@ -331,6 +331,25 @@ interface ContextResult {
  */
 export declare const runContext: (options: ContextRunOptions) => Effect.Effect<ContextResult, never, FileSystem.FileSystem | Path.Path>;
 //#endregion
+//#region src/graph/run.d.ts
+/** @public */
+interface GraphRunOptions {
+  /** Absolute bundle root; `Bundle.load` never reads cwd (D-8). */
+  readonly root: string;
+}
+/** @public */
+interface GraphRunResult {
+  readonly bundle: LoadedBundle;
+  readonly graph: LinkGraph;
+}
+/**
+ * Load the bundle and build its link graph (D-6, D-26). Pure over the
+ * loaded bundle once loading succeeds; `okfit graph` always exits `0`.
+ *
+ * @public
+ */
+export declare const runGraph: (options: GraphRunOptions) => Effect.Effect<GraphRunResult, BundleLoadError, FileSystem.FileSystem | Path.Path>;
+//#endregion
 //#region src/init/scaffold.d.ts
 /** `.config/okfit.toml`, relative to the project root (C-10). @public */
 export declare const CONFIG_RELATIVE_PATH = ".config/okfit.toml";
@@ -626,6 +645,79 @@ export declare const tally: (diagnostics: ReadonlyArray<RenderedDiagnostic>) =>
  */
 export declare const forDiagnostics: (diagnostics: ReadonlyArray<RenderedDiagnostic>) => 0 | 1 | 2;
 //#endregion
+//#region src/render/graph.d.ts
+/** One entry of the `nodes` array. @public */
+export declare const GraphNodeEnvelope: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly kind: Schema.Literals<readonly ["concept", "file", "missing"]>;
+}>;
+/** @public */
+export type GraphNodeEnvelope = typeof GraphNodeEnvelope.Type;
+/** One entry of the `edges` array; `field` is omitted, never `null` (exactOptionalPropertyTypes). @public */
+export declare const GraphEdgeEnvelope: Schema.Struct<{
+  readonly from: Schema.String;
+  readonly to: Schema.String;
+  readonly source: Schema.Literals<readonly ["body", "frontmatter"]>;
+  readonly field: Schema.optionalKey<Schema.String>;
+  readonly raw: Schema.String;
+}>;
+/** @public */
+export type GraphEdgeEnvelope = typeof GraphEdgeEnvelope.Type;
+/** @public */
+export declare const GraphSummary: Schema.Struct<{
+  readonly nodes: Schema.Number;
+  readonly edges: Schema.Number;
+}>;
+/** @public */
+export type GraphSummary = typeof GraphSummary.Type;
+/**
+ * `okfit graph --format json`'s envelope, schema 1, snake_case — the same
+ * convention as `render/json.ts`'s `JsonEnvelope`. Built from
+ * `LinkGraph.nodes`/`LinkGraph.edges` (D-26).
+ *
+ * @public
+ */
+export declare const GraphEnvelope: Schema.Struct<{
+  readonly schema: Schema.Literal<1>;
+  readonly okfit_version: Schema.String;
+  readonly producer: Schema.String;
+  readonly okf_version: Schema.String;
+  readonly root: Schema.String;
+  readonly profile: Schema.NullOr<Schema.String>;
+  readonly summary: Schema.Struct<{
+    readonly nodes: Schema.Number;
+    readonly edges: Schema.Number;
+  }>;
+  readonly nodes: Schema.$Array<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly kind: Schema.Literals<readonly ["concept", "file", "missing"]>;
+  }>>;
+  readonly edges: Schema.$Array<Schema.Struct<{
+    readonly from: Schema.String;
+    readonly to: Schema.String;
+    readonly source: Schema.Literals<readonly ["body", "frontmatter"]>;
+    readonly field: Schema.optionalKey<Schema.String>;
+    readonly raw: Schema.String;
+  }>>;
+}>;
+/** @public */
+export type GraphEnvelope = typeof GraphEnvelope.Type;
+/**
+ * Build the envelope from a loaded `LinkGraph`'s own `nodes`/`edges`
+ * arrays.
+ *
+ * @public
+ */
+export declare const graphEnvelope: (input: {
+  readonly okfitVersion: string;
+  readonly producer: string;
+  readonly okfVersion: string;
+  readonly root: string;
+  readonly profile: string | null;
+  readonly nodes: ReadonlyArray<GraphNode>;
+  readonly edges: ReadonlyArray<GraphLink>;
+}) => GraphEnvelope;
+//#endregion
 //#region src/render/json.d.ts
 /** One entry of the `diagnostics` array (K-21). @public */
 export declare const JsonDiagnostic: Schema.Struct<{
@@ -652,13 +744,18 @@ export type JsonSummary = typeof JsonSummary.Type;
 /**
  * K-21's success envelope, snake_case. `exit_code` is `0 | 1 | 2` only: an
  * infrastructure failure never produces this envelope, it produces the
- * `JsonErrorEnvelope` (K-22).
+ * `JsonErrorEnvelope` (K-22). `okfit_version` names the version of the
+ * package that produced the report (J-2), so the CLI and the MCP server
+ * legitimately report different numbers over one bundle; `producer` names
+ * that package (`okfit` or `@okfit/mcp`) so the difference reads as two
+ * producers, not as drift (okfit #75).
  *
  * @public
  */
 export declare const JsonEnvelope: Schema.Struct<{
   readonly schema: Schema.Literal<1>;
   readonly okfit_version: Schema.String;
+  readonly producer: Schema.String;
   readonly okf_version: Schema.String;
   readonly root: Schema.String;
   readonly profile: Schema.NullOr<Schema.String>;
@@ -707,6 +804,7 @@ export type JsonErrorEnvelope = typeof JsonErrorEnvelope.Type;
  */
 export declare const json: (input: {
   readonly okfitVersion: string;
+  readonly producer: string;
   readonly okfVersion: string;
   readonly root: string;
   readonly profile: string | null;
@@ -717,6 +815,69 @@ export declare const json: (input: {
 /** K-22. `tag` is the error's `_tag` when it has one, else its constructor name. @public */
 export declare const jsonError: (error: unknown, okfitVersion: string) => JsonErrorEnvelope;
 //#endregion
+//#region src/render/stale.d.ts
+/** One entry of the `items` array. @public */
+export declare const StaleItem: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly stale_after: Schema.String;
+  readonly days_past: Schema.Number;
+}>;
+/** @public */
+export type StaleItem = typeof StaleItem.Type;
+/** @public */
+export declare const StaleSummary: Schema.Struct<{
+  readonly concepts: Schema.Number;
+  readonly stale: Schema.Number;
+}>;
+/** @public */
+export type StaleSummary = typeof StaleSummary.Type;
+/**
+ * `okfit stale --format json`'s envelope, schema 1, snake_case — the same
+ * convention as `render/json.ts`'s `JsonEnvelope`. `as_of` and each item's
+ * `stale_after` are `DateTime.formatIso` strings (mirrors
+ * `packages/mcp/src/tools/staleReport.ts`). `stale` is always `0` (the
+ * report never fails a run).
+ *
+ * @public
+ */
+export declare const StaleEnvelope: Schema.Struct<{
+  readonly schema: Schema.Literal<1>;
+  readonly okfit_version: Schema.String;
+  readonly producer: Schema.String;
+  readonly okf_version: Schema.String;
+  readonly root: Schema.String;
+  readonly profile: Schema.NullOr<Schema.String>;
+  readonly as_of: Schema.String;
+  readonly summary: Schema.Struct<{
+    readonly concepts: Schema.Number;
+    readonly stale: Schema.Number;
+  }>;
+  readonly items: Schema.$Array<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly stale_after: Schema.String;
+    readonly days_past: Schema.Number;
+  }>>;
+}>;
+/** @public */
+export type StaleEnvelope = typeof StaleEnvelope.Type;
+/**
+ * Build the envelope. `items` is `Derive.staleReport`'s output verbatim
+ * (already sorted by id); this just reshapes it to snake_case and formats
+ * the two `DateTime.Utc` fields.
+ *
+ * @public
+ */
+export declare const staleEnvelope: (input: {
+  readonly okfitVersion: string;
+  readonly producer: string;
+  readonly okfVersion: string;
+  readonly root: string;
+  readonly profile: string | null;
+  readonly now: DateTime.Utc;
+  readonly concepts: number;
+  readonly items: ReadonlyArray<StaleConcept>;
+}) => StaleEnvelope;
+//#endregion
 //#region src/sync/run.d.ts
 /** The three families `okfit sync` regenerates (contract §5). @public */
 type SyncMode = "generated" | "index" | "log";
@@ -886,6 +1047,30 @@ export declare const verifyEnvelope: (input: {
   readonly dryRun: boolean;
 }) => VerifyEnvelope;
 //#endregion
+//#region src/stale/run.d.ts
+/** @public */
+interface StaleRunOptions {
+  /** Absolute bundle root; `Bundle.load` never reads cwd (D-8). */
+  readonly root: string;
+  /** `OKFIT_NOW` or `DateTime.now`, from the caller's own `Now` service (K-47). */
+  readonly now: DateTime.Utc;
+}
+/** @public */
+interface StaleRunResult {
+  readonly bundle: LoadedBundle;
+  /** `Derive.staleReport`'s output verbatim: every stale concept, sorted by id. */
+  readonly items: ReadonlyArray<StaleConcept>;
+}
+/**
+ * Load the bundle and derive the stale report against `now` (D-10, D-36:
+ * `Derive.staleReport` is pure and takes `now` as an argument, never a
+ * clock). This is a report, not a check — `okfit stale` always exits `0`;
+ * the `stale` lint rule is where staleness fails a run.
+ *
+ * @public
+ */
+export declare const runStale: (options: StaleRunOptions) => Effect.Effect<StaleRunResult, BundleLoadError, FileSystem.FileSystem | Path.Path>;
+//#endregion
 //#region src/validate/run.d.ts
 declare const Now_base: Context.ServiceClass<Now, "@okfit/engine/Now", DateTime.Utc>;
 /**
@@ -1016,5 +1201,5 @@ export declare const runVerify: (options: VerifyOptions) => Effect.Effect<{
   fragment: string;
 }, import("effect/PlatformError").PlatformError | VerifyConceptNotFoundError | VerifyUnsupportedFrontmatterError | import("@effected/yaml").YamlParseError | import("@okfit/core").BundleLoadError | import("@okfit/profiles").GeneratedByError, FileSystem.FileSystem | import("@effected/git").Git | Path.Path>;
 //#endregion
-export type { ContextResult, ContextRunOptions, DiagnosticSource, DiscoveredConfig, RenderedDiagnostic, ResolveProjectConfigInput, ResolvedProjectConfig, RunOptions, RunResult, ScaffoldFile, ScaffoldOptions, SyncMode, SyncModeResult, SyncOptions, SyncResult, Tally, VerifyOptions, VerifyResult };
+export type { ContextResult, ContextRunOptions, DiagnosticSource, DiscoveredConfig, GraphRunOptions, GraphRunResult, RenderedDiagnostic, ResolveProjectConfigInput, ResolvedProjectConfig, RunOptions, RunResult, ScaffoldFile, ScaffoldOptions, StaleRunOptions, StaleRunResult, SyncMode, SyncModeResult, SyncOptions, SyncResult, Tally, VerifyOptions, VerifyResult };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -3,16 +3,20 @@ import { ConfigMalformedError, ConfigPathNotFoundError, InitOverwriteError, Veri
 import { buildConfigLayer, provideConfig } from "./config/layer.js";
 import { DEFAULT_PROFILE_NAME, resolveProjectConfig } from "./config/resolve.js";
 import { runContext } from "./context/run.js";
+import { runGraph } from "./graph/run.js";
 import { CONFIG_RELATIVE_PATH, SCHEMA_DIRECTIVE, configValue, files, targetPaths } from "./init/scaffold.js";
 import { OkfitPlatform } from "./platform.js";
 import { ContextEnvelope, ContextField, ContextFieldValue, ContextTag, ContextType, contextEnvelope } from "./render/context.js";
 import { forDiagnostics, tally } from "./render/exit.js";
+import { GraphEdgeEnvelope, GraphEnvelope, GraphNodeEnvelope, GraphSummary, graphEnvelope } from "./render/graph.js";
 import { collect, sort } from "./render/sort.js";
 import { JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, json, jsonError } from "./render/json.js";
+import { StaleEnvelope, StaleItem, StaleSummary, staleEnvelope } from "./render/stale.js";
 import { SkipReason, runSync } from "./sync/run.js";
 import { SyncEnvelope, SyncModeEnvelope, syncEnvelope } from "./render/sync.js";
 import { VerifyEnvelope, verifyEnvelope } from "./render/verify.js";
+import { runStale } from "./stale/run.js";
 import { Now, run } from "./validate/run.js";
 import { runVerify } from "./verify/run.js";
 
-export { CONFIG_RELATIVE_PATH, ConfigMalformedError, ConfigPathNotFoundError, ContextEnvelope, ContextField, ContextFieldValue, ContextTag, ContextType, DEFAULT_PROFILE_NAME, InitOverwriteError, JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, Now, OkfitPlatform, SCHEMA_DIRECTIVE, SkipReason, SyncEnvelope, SyncModeEnvelope, VerifyConceptNotFoundError, VerifyEnvelope, VerifyUnsupportedFrontmatterError, buildConfigLayer, collect, configValue, contextEnvelope, files, forDiagnostics, json, jsonError, provideConfig, resolveBundleRoot, resolveProjectConfig, resolveProjectRoot, run, runContext, runSync, runVerify, sort, syncEnvelope, tally, targetPaths, verifyEnvelope };
+export { CONFIG_RELATIVE_PATH, ConfigMalformedError, ConfigPathNotFoundError, ContextEnvelope, ContextField, ContextFieldValue, ContextTag, ContextType, DEFAULT_PROFILE_NAME, GraphEdgeEnvelope, GraphEnvelope, GraphNodeEnvelope, GraphSummary, InitOverwriteError, JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, Now, OkfitPlatform, SCHEMA_DIRECTIVE, SkipReason, StaleEnvelope, StaleItem, StaleSummary, SyncEnvelope, SyncModeEnvelope, VerifyConceptNotFoundError, VerifyEnvelope, VerifyUnsupportedFrontmatterError, buildConfigLayer, collect, configValue, contextEnvelope, files, forDiagnostics, graphEnvelope, json, jsonError, provideConfig, resolveBundleRoot, resolveProjectConfig, resolveProjectRoot, run, runContext, runGraph, runStale, runSync, runVerify, sort, staleEnvelope, syncEnvelope, tally, targetPaths, verifyEnvelope };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/engine",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"private": false,
 	"description": "The okfit engine: platform layer, config discovery, and the validate, verify, sync, init and context programs shared by the okfit CLI and MCP server.",
 	"keywords": [
@@ -46,8 +46,8 @@
 		"@effected/walker": "^0.9.0",
 		"@effected/xdg": "^0.5.1",
 		"@effected/yaml": "^0.15.1",
-		"@okfit/core": "0.4.0",
-		"@okfit/profiles": "0.4.0",
+		"@okfit/core": "0.4.1",
+		"@okfit/profiles": "0.5.0",
 		"effect": "4.0.0-rc.115"
 	},
 	"engines": {

package/render/graph.js

@@ -0,0 +1,77 @@
+import { Schema } from "effect";
+
+//#region src/render/graph.ts
+/** One entry of the `nodes` array. @public */
+const GraphNodeEnvelope = Schema.Struct({
+	id: Schema.String,
+	kind: Schema.Literals([
+		"concept",
+		"file",
+		"missing"
+	])
+});
+/** One entry of the `edges` array; `field` is omitted, never `null` (exactOptionalPropertyTypes). @public */
+const GraphEdgeEnvelope = Schema.Struct({
+	from: Schema.String,
+	to: Schema.String,
+	source: Schema.Literals(["body", "frontmatter"]),
+	field: Schema.optionalKey(Schema.String),
+	raw: Schema.String
+});
+/** @public */
+const GraphSummary = Schema.Struct({
+	nodes: Schema.Number,
+	edges: Schema.Number
+});
+/**
+* `okfit graph --format json`'s envelope, schema 1, snake_case — the same
+* convention as `render/json.ts`'s `JsonEnvelope`. Built from
+* `LinkGraph.nodes`/`LinkGraph.edges` (D-26).
+*
+* @public
+*/
+const GraphEnvelope = Schema.Struct({
+	schema: Schema.Literal(1),
+	okfit_version: Schema.String,
+	producer: Schema.String,
+	okf_version: Schema.String,
+	root: Schema.String,
+	profile: Schema.NullOr(Schema.String),
+	summary: GraphSummary,
+	nodes: Schema.Array(GraphNodeEnvelope),
+	edges: Schema.Array(GraphEdgeEnvelope)
+});
+const toNode = (node) => ({
+	id: node.id,
+	kind: node.kind
+});
+const toEdge = (edge) => ({
+	from: edge.from,
+	to: edge.to,
+	source: edge.data.source,
+	...edge.data.field === void 0 ? {} : { field: edge.data.field },
+	raw: edge.data.raw
+});
+/**
+* Build the envelope from a loaded `LinkGraph`'s own `nodes`/`edges`
+* arrays.
+*
+* @public
+*/
+const graphEnvelope = (input) => ({
+	schema: 1,
+	okfit_version: input.okfitVersion,
+	producer: input.producer,
+	okf_version: input.okfVersion,
+	root: input.root,
+	profile: input.profile,
+	summary: {
+		nodes: input.nodes.length,
+		edges: input.edges.length
+	},
+	nodes: input.nodes.map(toNode),
+	edges: input.edges.map(toEdge)
+});
+
+//#endregion
+export { GraphEdgeEnvelope, GraphEnvelope, GraphNodeEnvelope, GraphSummary, graphEnvelope };

package/render/json.js

@@ -29,13 +29,18 @@ const JsonSummary = Schema.Struct({
 /**
 * K-21's success envelope, snake_case. `exit_code` is `0 | 1 | 2` only: an
 * infrastructure failure never produces this envelope, it produces the
-* `JsonErrorEnvelope` (K-22).
+* `JsonErrorEnvelope` (K-22). `okfit_version` names the version of the
+* package that produced the report (J-2), so the CLI and the MCP server
+* legitimately report different numbers over one bundle; `producer` names
+* that package (`okfit` or `@okfit/mcp`) so the difference reads as two
+* producers, not as drift (okfit #75).
 *
 * @public
 */
 const JsonEnvelope = Schema.Struct({
 	schema: Schema.Literal(1),
 	okfit_version: Schema.String,
+	producer: Schema.String,
 	okf_version: Schema.String,
 	root: Schema.String,
 	profile: Schema.NullOr(Schema.String),
@@ -81,6 +86,7 @@ const json = (input) => {
 	return {
 		schema: 1,
 		okfit_version: input.okfitVersion,
+		producer: input.producer,
 		okf_version: input.okfVersion,
 		root: input.root,
 		profile: input.profile,

package/render/stale.js

@@ -0,0 +1,62 @@
+import { DateTime, Schema } from "effect";
+
+//#region src/render/stale.ts
+/** One entry of the `items` array. @public */
+const StaleItem = Schema.Struct({
+	id: Schema.String,
+	stale_after: Schema.String,
+	days_past: Schema.Number
+});
+/** @public */
+const StaleSummary = Schema.Struct({
+	concepts: Schema.Number,
+	stale: Schema.Number
+});
+/**
+* `okfit stale --format json`'s envelope, schema 1, snake_case — the same
+* convention as `render/json.ts`'s `JsonEnvelope`. `as_of` and each item's
+* `stale_after` are `DateTime.formatIso` strings (mirrors
+* `packages/mcp/src/tools/staleReport.ts`). `stale` is always `0` (the
+* report never fails a run).
+*
+* @public
+*/
+const StaleEnvelope = Schema.Struct({
+	schema: Schema.Literal(1),
+	okfit_version: Schema.String,
+	producer: Schema.String,
+	okf_version: Schema.String,
+	root: Schema.String,
+	profile: Schema.NullOr(Schema.String),
+	as_of: Schema.String,
+	summary: StaleSummary,
+	items: Schema.Array(StaleItem)
+});
+/**
+* Build the envelope. `items` is `Derive.staleReport`'s output verbatim
+* (already sorted by id); this just reshapes it to snake_case and formats
+* the two `DateTime.Utc` fields.
+*
+* @public
+*/
+const staleEnvelope = (input) => ({
+	schema: 1,
+	okfit_version: input.okfitVersion,
+	producer: input.producer,
+	okf_version: input.okfVersion,
+	root: input.root,
+	profile: input.profile,
+	as_of: DateTime.formatIso(input.now),
+	summary: {
+		concepts: input.concepts,
+		stale: input.items.length
+	},
+	items: input.items.map((item) => ({
+		id: item.id,
+		stale_after: DateTime.formatIso(item.staleAfter),
+		days_past: item.daysPast
+	}))
+});
+
+//#endregion
+export { StaleEnvelope, StaleItem, StaleSummary, staleEnvelope };

package/stale/run.js

@@ -0,0 +1,22 @@
+import { Bundle, Derive } from "@okfit/core";
+import { Effect } from "effect";
+
+//#region src/stale/run.ts
+/**
+* Load the bundle and derive the stale report against `now` (D-10, D-36:
+* `Derive.staleReport` is pure and takes `now` as an argument, never a
+* clock). This is a report, not a check — `okfit stale` always exits `0`;
+* the `stale` lint rule is where staleness fails a run.
+*
+* @public
+*/
+const runStale = (options) => Effect.gen(function* () {
+	const bundle = yield* Bundle.load({ root: options.root });
+	return {
+		bundle,
+		items: Derive.staleReport(bundle, options.now)
+	};
+});
+
+//#endregion
+export { runStale };