okf-kit 0.3.0

package/dist/templates.js

@@ -0,0 +1,293 @@
+/**
+ * Scaffold content for `okf-kit init`. Everything here is static except the
+ * `timestamp` value, which the caller (src/init.ts) fills in with the real
+ * current instant at generation time: never hardcode an artificial
+ * midnight datetime here, that is exactly the lesson this kit is built to
+ * enforce (see FRONTMATTER_GUIDANCE below).
+ */
+const FRONTMATTER_GUIDANCE = `<!--
+okf-kit init guidance (delete this comment once the doc is written):
+- \`timestamp\` means "last verified against sources", not "created on".
+  Bump it (and add a line to this bundle's log.md) every time you
+  re-verify this doc against its sources; never hand-write an artificial
+  midnight datetime, use the real instant you did the verification.
+- \`sources\` lists the repo-root-relative paths this doc DESCRIBES (code,
+  config, or other docs elsewhere in the repo). Never list this bundle's
+  own directory: a bundle directory changes on every doc edit, so a
+  self-referential \`sources\` entry goes permanently stale. This happened
+  to the OKF pilot's own BENCHMARK.md (agent-tasks docs/okf/BENCHMARK.md),
+  which is why this template ships with a placeholder instead of a real
+  path: \`okf-kit check\` will report that placeholder as a missing source
+  path until you replace it, and that is intentional, not a bug.
+-->`;
+const BENCHMARK_FRONTMATTER_GUIDANCE = `<!--
+okf-kit init guidance (delete this comment once the doc is written):
+- \`timestamp\` means "last verified", not "created on"; bump it (and add a
+  line to this bundle's log.md) whenever this record is updated. Never
+  hand-write an artificial midnight datetime.
+- This template intentionally has no \`sources:\` key. A benchmark record
+  documents a measurement protocol and its results, not a piece of the
+  codebase, so there is nothing it "describes" in the sources-shape sense.
+  The OKF pilot's own BENCHMARK.md carried \`sources: [docs/okf/]\`,
+  pointing at its own bundle directory; that "source" changed on every
+  edit to the bundle and was permanently, uselessly stale. Don't repeat
+  that mistake: omit \`sources\` here rather than pointing it at yourself.
+-->`;
+const BODY_GUIDANCE = `<!--
+Write dense, source-verified prose: name exact mechanisms (function/class/
+route names), exact file paths, and exact identifiers (config keys, env
+vars, error codes). Avoid filler like "this module handles X" without
+naming the function that does it. Every sentence here should be checkable
+against a source in \`sources:\` above.
+-->`;
+export function indexTemplate() {
+    return `# Knowledge bundle index
+
+Scaffolded by \`okf-kit init\`. Replace this placeholder index with a real
+map of the docs in this bundle as you add and rename them.
+
+## Overview
+
+- [Overview template](overview-template.md), start here for the big picture: what this area covers and where to read next.
+
+## Modules
+
+- [Module template](module-template.md), one doc per module: responsibility, entry points, key files.
+
+## Invariants
+
+- [Invariant template](invariant-template.md), one doc per invariant: the guarantee, where it's enforced, what would break it.
+
+## Runbooks
+
+- [Runbook template](runbook-template.md), one doc per operational procedure: preconditions, steps, verification.
+
+## Benchmark
+
+- [Benchmark template](benchmark-template.md), measure whether this bundle actually improves discovery, before and after it lands.
+`;
+}
+export function logTemplate(timestamp) {
+    return `# Log
+
+<!-- Add new entries at the top, newest first. -->
+
+- ${timestamp}, bundle scaffolded by \`okf-kit init\`.
+`;
+}
+export function overviewTemplate(timestamp) {
+    return `---
+type: overview
+title: <component/area> overview
+description: Orientation doc, what this area covers and where to start reading.
+tags: [overview]
+timestamp: ${timestamp}
+sources:
+  - path/to/covered/source
+---
+
+${FRONTMATTER_GUIDANCE}
+
+# <Component/area> overview
+
+${BODY_GUIDANCE}
+
+## What this covers
+
+- <One or two sentences: what area of the system this overview orients a reader to.>
+
+## Where to start reading
+
+- <Exact entry-point file and function/route, e.g. \`src/server.ts\`, \`createApp()\`.>
+
+## Key modules
+
+- [Module template](module-template.md), <one line: what this module doc models, once renamed.>
+`;
+}
+export function moduleTemplate(timestamp) {
+    return `---
+type: module
+title: <module name>
+description: What this module owns, its entry points, and its key files.
+tags: [module]
+timestamp: ${timestamp}
+sources:
+  - path/to/covered/source
+---
+
+${FRONTMATTER_GUIDANCE}
+
+# <Module name>
+
+${BODY_GUIDANCE}
+
+## Responsibility
+
+- <One sentence: what this module owns, and one sentence on what it explicitly does NOT own.>
+
+## Entry points
+
+- <Exact function/class/route name>, \`<file path>\`
+
+## Key files
+
+- \`<path>\`, <one line: what lives here>
+
+## Invariants enforced here
+
+- [Invariant template](invariant-template.md), <link to the specific invariant doc, once renamed, if this module enforces one>
+`;
+}
+export function invariantTemplate(timestamp) {
+    return `---
+type: invariant
+title: <invariant name>
+description: A falsifiable invariant, where it is enforced, and what breaks it.
+tags: [invariant]
+timestamp: ${timestamp}
+sources:
+  - path/to/covered/source
+---
+
+${FRONTMATTER_GUIDANCE}
+
+# <Invariant name>
+
+${BODY_GUIDANCE}
+
+## The invariant
+
+- <State the invariant as a single falsifiable sentence.>
+
+## Where it's enforced
+
+- \`<path>:<line or function>\`, <mechanism: a check, a type, a DB constraint, a migration, ...>
+
+## What breaks it
+
+- <A concrete scenario that would violate the invariant if the enforcement above were removed or bypassed.>
+`;
+}
+export function runbookTemplate(timestamp) {
+    return `---
+type: runbook
+title: <runbook name>
+description: Step-by-step operational procedure with preconditions and verification.
+tags: [runbook]
+timestamp: ${timestamp}
+sources:
+  - path/to/covered/source
+---
+
+${FRONTMATTER_GUIDANCE}
+
+# <Runbook name>
+
+${BODY_GUIDANCE}
+
+## When to use this
+
+- <Trigger condition or symptom that means this runbook applies.>
+
+## Preconditions
+
+- <Access, tools, or system state required before starting.>
+
+## Steps
+
+1. <Exact command or action.>
+2. <Exact command or action.>
+
+## Verification
+
+- <How to confirm the runbook actually worked.>
+`;
+}
+export function benchmarkTemplate(timestamp) {
+    return `---
+type: benchmark
+title: <bundle name> discovery benchmark
+description: Before/after measurement of discovery quality for this bundle.
+tags: [benchmark]
+timestamp: ${timestamp}
+---
+
+${BENCHMARK_FRONTMATTER_GUIDANCE}
+
+# <Bundle name> discovery benchmark
+
+${BODY_GUIDANCE}
+
+Measures whether this curated OKF bundle improves discovery quality (for
+example via [codebase-oracle](https://github.com/LanNguyenSi/codebase-oracle)
+or whatever search/retrieval tool your agents use) for this repo. Distilled
+from the OKF Phase-0 pilot protocol (agent-tasks \`docs/okf/BENCHMARK.md\`).
+
+## Methodology
+
+Two runs, identical protocol:
+
+- **Baseline:** current index, no bundle concept docs present.
+- **Post-bundle:** after the bundle is merged and the index has been rebuilt.
+
+Record the environment for both runs (index/tool version, embeddings model,
+answer-generation model) so a result can be attributed to the bundle and not
+to environment drift between runs.
+
+### Integrity rules
+
+- Write the question set and scoring rubric, and commit them, BEFORE any
+  bundle authoring starts.
+- Keep the bundle author blind to the question set.
+- Verify the ground-truth answer key against source with exact evidence
+  (file path, line, or identifier), but do not commit it and do not let it
+  reach the index until scoring is complete.
+- Filter out any search/query hit whose only source is this benchmark
+  document itself (self-match): it contains the questions verbatim and
+  would otherwise inflate its own post-bundle score.
+
+### Scoring rubric
+
+- **Answer correctness**, judged against the answer key, same judge both runs:
+  - 2 = correct: the key facts are present, no materially wrong claim is
+    made, AND the answer text itself names at least one concrete pointer to
+    a ground-truth file (a path, identifier, or line reference actually
+    written in the prose, not merely present in a separate citations list).
+  - 1 = partial: right area or mechanism, but a key fact is missing, a minor
+    claim is wrong, or the answer never names a concrete pointer in its own
+    text.
+  - 0 = wrong or missing.
+- **Retrieval hit@5**: 1 if a ground-truth file appears in the top-5
+  retrieved chunks for that question, else 0.
+
+Do not count citation metadata (a "sources" or "cited from" list attached by
+the tool) as satisfying the pointer requirement above. The pilot's original
+rubric did exactly that, and it rewarded answers whose retrieved chunks
+happened to carry a \`sources:\` frontmatter pointer even when the answer
+text itself never named a concrete file or identifier. That is a metric
+artifact, not evidence the reader learned anything precise: require the
+pointer in the text itself.
+
+## Questions
+
+| # | Question |
+|---|----------|
+| Q1 | <question> |
+
+## Results
+
+### Baseline
+
+<!-- fill in after the baseline run -->
+
+### Post-bundle
+
+<!-- fill in after the post-bundle run -->
+
+### Decision
+
+<!-- go / no-go, and what you'd change next time -->
+`;
+}
+//# sourceMappingURL=templates.js.map

package/dist/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;IAczB,CAAC;AAEL,MAAM,8BAA8B,GAAG;;;;;;;;;;;;IAYnC,CAAC;AAEL,MAAM,aAAa,GAAG;;;;;;IAMlB,CAAC;AAEL,MAAM,UAAU,aAAa;IAC3B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;CAwBR,CAAC;AACF,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,SAAiB;IAC3C,OAAO;;;;IAIL,SAAS;CACZ,CAAC;AACF,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,SAAiB;IAChD,OAAO;;;;;aAKI,SAAS;;;;;EAKpB,oBAAoB;;;;EAIpB,aAAa;;;;;;;;;;;;;CAad,CAAC;AACF,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,OAAO;;;;;aAKI,SAAS;;;;;EAKpB,oBAAoB;;;;EAIpB,aAAa;;;;;;;;;;;;;;;;;CAiBd,CAAC;AACF,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,OAAO;;;;;aAKI,SAAS;;;;;EAKpB,oBAAoB;;;;EAIpB,aAAa;;;;;;;;;;;;;CAad,CAAC;AACF,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,OAAO;;;;;aAKI,SAAS;;;;;EAKpB,oBAAoB;;;;EAIpB,aAAa;;;;;;;;;;;;;;;;;;CAkBd,CAAC;AACF,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,OAAO;;;;;aAKI,SAAS;;;EAGpB,8BAA8B;;;;EAI9B,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuEd,CAAC;AACF,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,43 @@
+export type Severity = "error" | "warning" | "notice";
+export interface Finding {
+    ruleId: string;
+    severity: Severity;
+    /** Bundle-relative path, forward-slash separated. */
+    file: string;
+    message: string;
+    detail?: string;
+}
+export interface FrontmatterInfo {
+    present: boolean;
+    parsed?: unknown;
+    parseError?: string;
+}
+export interface BundleDoc {
+    /** Bundle-relative path, forward-slash separated. */
+    relPath: string;
+    basename: string;
+    isReserved: boolean;
+    raw: string;
+    frontmatter: FrontmatterInfo;
+    body: string;
+}
+/**
+ * Runs `git <args>` in `cwd`. Returns trimmed stdout on success (git exit
+ * code 0), or null on any failure (non-zero exit, not a git work tree, git
+ * binary missing). Never throws. Injectable so rules that shell out to git
+ * (currently only sources-fresh) can be tested with a stub instead of a
+ * real git process.
+ */
+export type RunGit = (args: string[], cwd: string) => string | null;
+export interface BundleContext {
+    bundleDir: string;
+    repoRoot?: string;
+    docs: BundleDoc[];
+    /** Defaults to a real `git` child-process call (see src/git.ts) when a rule needs it and none was injected. */
+    runGit?: RunGit;
+}
+export interface Rule {
+    id: string;
+    description: string;
+    run(ctx: BundleContext): Finding[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/util.d.ts

@@ -0,0 +1,23 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Whether parsed frontmatter has a `sources` key at all, regardless of shape validity. */
+export declare function hasSourcesKey(parsed: unknown): boolean;
+/**
+ * Returns the frontmatter `sources` array when it is shaped correctly (a
+ * non-empty array of non-empty strings), or undefined otherwise (absent, or
+ * present but malformed). Shared between sources-shape (which reports the
+ * shape violation) and sources-fresh (which only assesses staleness for a
+ * validly-shaped sources list, leaving the shape error itself to
+ * sources-shape).
+ */
+export declare function getValidSources(parsed: unknown): string[] | undefined;
+/**
+ * Returns the frontmatter `timestamp` as a Unix epoch (seconds), or
+ * undefined when absent, not a Date/string, or not parseable as a date.
+ * Used by sources-fresh to compare against a source path's last-commit
+ * time. Accepts a `Date` instance first: the `yaml` package's default
+ * (core) schema resolves timestamp scalars to strings, but a YAML 1.1
+ * `!!timestamp` tag (or a caller constructing frontmatter programmatically)
+ * can hand back a native `Date`, and that should be assessed rather than
+ * degrade to the no-valid-timestamp notice.
+ */
+export declare function getTimestampEpoch(parsed: unknown): number | undefined;

package/dist/util.js

@@ -0,0 +1,50 @@
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Whether parsed frontmatter has a `sources` key at all, regardless of shape validity. */
+export function hasSourcesKey(parsed) {
+    return isRecord(parsed) && "sources" in parsed;
+}
+/**
+ * Returns the frontmatter `sources` array when it is shaped correctly (a
+ * non-empty array of non-empty strings), or undefined otherwise (absent, or
+ * present but malformed). Shared between sources-shape (which reports the
+ * shape violation) and sources-fresh (which only assesses staleness for a
+ * validly-shaped sources list, leaving the shape error itself to
+ * sources-shape).
+ */
+export function getValidSources(parsed) {
+    if (!hasSourcesKey(parsed))
+        return undefined;
+    const sources = parsed.sources;
+    const isValidShape = Array.isArray(sources) &&
+        sources.length > 0 &&
+        sources.every((s) => typeof s === "string" && s.trim() !== "");
+    return isValidShape ? sources : undefined;
+}
+/**
+ * Returns the frontmatter `timestamp` as a Unix epoch (seconds), or
+ * undefined when absent, not a Date/string, or not parseable as a date.
+ * Used by sources-fresh to compare against a source path's last-commit
+ * time. Accepts a `Date` instance first: the `yaml` package's default
+ * (core) schema resolves timestamp scalars to strings, but a YAML 1.1
+ * `!!timestamp` tag (or a caller constructing frontmatter programmatically)
+ * can hand back a native `Date`, and that should be assessed rather than
+ * degrade to the no-valid-timestamp notice.
+ */
+export function getTimestampEpoch(parsed) {
+    if (!isRecord(parsed))
+        return undefined;
+    const timestamp = parsed.timestamp;
+    if (timestamp instanceof Date) {
+        const ms = timestamp.getTime();
+        return Number.isNaN(ms) ? undefined : Math.floor(ms / 1000);
+    }
+    if (typeof timestamp !== "string" || timestamp.trim() === "")
+        return undefined;
+    const ms = Date.parse(timestamp);
+    if (Number.isNaN(ms))
+        return undefined;
+    return Math.floor(ms / 1000);
+}
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,aAAa,CAAC,MAAe;IAC3C,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,SAAS,IAAI,MAAM,CAAC;AACjD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,MAAe;IAC7C,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAC7C,MAAM,OAAO,GAAI,MAAkC,CAAC,OAAO,CAAC;IAC5D,MAAM,YAAY,GAChB,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QACtB,OAAO,CAAC,MAAM,GAAG,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACjE,OAAO,YAAY,CAAC,CAAC,CAAE,OAAoB,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAe;IAC/C,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;IACnC,IAAI,SAAS,YAAY,IAAI,EAAE,CAAC;QAC9B,MAAM,EAAE,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE;QAC1D,OAAO,SAAS,CAAC;IACnB,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACjC,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IACvC,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;AAC/B,CAAC"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "okf-kit",
+  "version": "0.3.0",
+  "description": "CLI that validates OKF v0.1 knowledge bundles for structural correctness",
+  "type": "module",
+  "bin": {
+    "okf-kit": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx src/cli.ts",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\""
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "okf",
+    "knowledge",
+    "lint",
+    "dx"
+  ],
+  "author": "Lan Nguyen Si",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LanNguyenSi/agent-dx.git",
+    "directory": "packages/okf-kit"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "yaml": "^2.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "prettier": "^3.8.1",
+    "tsx": "^4.22.4",
+    "typescript": "^5.3.3",
+    "vitest": "^4.1.6"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}