okfcli 0.0.0-stage → 0.1.0

package/dist/src/generate/agents.js

@@ -0,0 +1,128 @@
+import { join } from 'node:path';
+import { AGENT_NAMES, AGENT_TARGETS } from './targets.js';
+import { typeAlias } from '../core/profile.js';
+import { UserError, readIfExists, writeWithStatus } from '../core/util.js';
+// Files generated for the coding agents (SPEC.md section 10; paths per agent in targets.ts):
+//  - a marked block in the instructions file the agent always loads
+//  - three agent skills (open standard: agentskills.io)
+// They belong to okfcli: running `okfcli init` again regenerates them.
+export const BLOCK_START = '<!-- okfcli:start -->';
+export const BLOCK_END = '<!-- okfcli:end -->';
+export function pointerBlock(wiki) {
+    return [
+        BLOCK_START,
+        '## Project wiki',
+        '',
+        `This project keeps its knowledge (architecture, patterns, conventions, workflows, testing) in an OKF wiki at \`${wiki}/\`.`,
+        '',
+        `- Before changing code, read \`${wiki}/index.md\` and the pages relevant to the task (skill \`okf-consult-wiki\`).`,
+        '- When a change affects documented rules, patterns or conventions, update the wiki (skill `okf-update-wiki`). Use the `okfcli` CLI to create pages; never edit `index.md` files by hand or write `verified` entries.',
+        '- Never mark a page as reviewed on your own: only a person reviews pages (skill `okf-review-wiki`).',
+        BLOCK_END,
+        '',
+    ].join('\n');
+}
+const skill = (name, description, body, version) => `---\nname: ${name}\ndescription: ${description}\n---\n<!-- Generated by okfcli ${version}. Regenerated by "okfcli init": do not edit. -->\n\n${body.trim()}\n`;
+function typeList(profile) {
+    return profile.folders.map((f) => `   - \`${typeAlias(f.type)}\` -> \`${f.name}/\` (sections: ${f.sections.map((s) => `\`# ${s}\``).join(', ') || 'none'})`).join('\n');
+}
+export function skillFiles({ wiki, profile, version }) {
+    // Quoted only when needed, so paths with spaces still work in the commands agents run.
+    const wikiArg = /^[\w./@+-]+$/.test(wiki) ? wiki : JSON.stringify(wiki);
+    const consult = skill('okf-consult-wiki', 'Find project knowledge in the wiki before writing or changing code: architecture, patterns, conventions, workflows and testing rules. Use at the start of any task that touches the codebase.', `
+# Consult the project wiki
+
+The wiki lives in \`${wiki}/\`. Read only what the task needs.
+
+1. Read \`${wiki}/index.md\`. It lists the folders: overview, architecture, patterns, conventions, workflows, testing, and any optional ones (features, modules, interfaces, operations, troubleshooting).
+2. Open the \`index.md\` of the folders that matter for the task, then the pages it points to.
+3. For "how do I do X" questions start with \`workflows/\`; each workflow links to the \`patterns/\` it relies on. Rules and structure are in \`architecture/\` and \`conventions/\`; how to run and write tests is in \`testing/\`.
+4. Follow what the pages say. If the wiki is silent or contradicts the code, say so instead of guessing, and propose a wiki update (skill \`okf-update-wiki\`).
+5. A page without a \`verified\` entry has not been reviewed by a person: use it, but flag the uncertainty when the answer depends on it.
+`, version);
+    const update = skill('okf-update-wiki', 'Update the project wiki after a change affects documented knowledge, or document something new. Uses the okfcli CLI so structure and indexes stay correct.', `
+# Update the project wiki
+
+The wiki lives in \`${wiki}/\`. The \`okfcli\` CLI does the mechanical work; you only write content.
+
+1. Check whether the change touches knowledge that is already documented. If so, **edit that page in place**. Do not create a duplicate, and do not add a page that only records a decision: put the reason in the page's \`# Why\` section.
+2. For new knowledge, create the page with the CLI, not by hand:
+
+   \`okfcli new <type> <name> --description "<one sentence>" --wiki ${wikiArg}\`
+
+   It creates the file with its frontmatter and required sections, and registers it in the folder index. Types:
+
+${typeList(profile)}
+
+   \`<name>\` is kebab-case and relative to the folder (for example \`state-management\` or \`ui/forms\`).
+3. Fill in every section and delete the \`<!-- TODO -->\` comments. Write in the language the existing pages use.
+4. Never edit \`index.md\` files and never write \`verified\` entries: you are not a reviewer. New and edited pages stay unreviewed until a person verifies them.
+5. If something no longer applies, set \`status: deprecated\` in that page's frontmatter instead of deleting it.
+6. Run \`okfcli validate --fix --wiki ${wikiArg}\`, then fix whatever it still reports (it names the file, the rule and how to fix it).
+`, version);
+    const review = skill('okf-review-wiki', 'Walk a person through the wiki pages nobody has reviewed yet and record their review. Use when asked to review, verify or sign off wiki pages.', `
+# Review wiki pages with a person
+
+Reviewing is a human act. You prepare the review; the person decides.
+
+1. Run \`okfcli validate --json --wiki ${wikiArg}\`. The pages to review are the issues with rule \`frontmatter.verified\` (never reviewed) or \`frontmatter.verified-outdated\` (changed after being verified). The \`review\` field has the totals.
+2. Pick one page at a time (ask the person where to start if there are many). Summarise it, check it against the code, and point out anything that looks wrong or missing. Fix problems with the person's agreement.
+3. A page with unfilled \`<!-- TODO -->\` comments is not ready: complete it first.
+4. Ask the person explicitly whether they confirm the page. Only after a clear yes, run:
+
+   \`okfcli verify <path> --by human:<id> --wiki ${wikiArg}\`
+
+   where \`<id>\` identifies that person (ask if you do not know it).
+5. Never use a \`human:\` actor for yourself, never verify a page the person has not confirmed, and never write \`verified\` entries by hand.
+6. If the person does not confirm a page, leave it as it is and move on.
+7. Finish with \`okfcli validate --wiki ${wikiArg}\` and report how many pages are still unreviewed.
+`, version);
+    return [
+        { path: 'okf-consult-wiki/SKILL.md', text: consult },
+        { path: 'okf-update-wiki/SKILL.md', text: update },
+        { path: 'okf-review-wiki/SKILL.md', text: review },
+    ];
+}
+// Inserts the block into the file text, or replaces it if the markers are already there.
+export function upsertBlock(current, block, file) {
+    if (current === null)
+        return block;
+    const start = current.indexOf(BLOCK_START);
+    if (start === -1)
+        return `${current.replace(/\s+$/, '')}${current.trim() ? '\n\n' : ''}${block}`;
+    const end = current.indexOf(BLOCK_END, start);
+    if (end === -1) {
+        throw new UserError(`${file} has "${BLOCK_START}" without "${BLOCK_END}". Fix or remove the marker, then run "okfcli init" again.`);
+    }
+    return current.slice(0, start) + block.trimEnd() + current.slice(end + BLOCK_END.length);
+}
+// Which of the candidate files carries the pointer block: the one that already
+// has it, else the first that exists, else the first candidate (created).
+export function pointerFile(projectRoot, candidates) {
+    const withBlock = candidates.find((f) => readIfExists(join(projectRoot, f))?.includes(BLOCK_START));
+    return withBlock ?? candidates.find((f) => readIfExists(join(projectRoot, f)) !== null) ?? candidates[0];
+}
+// Writes (or refreshes) the agent files of the chosen agents. Agents that share
+// a destination (several read AGENTS.md or .agents/skills) write it only once.
+export function writeAgentFiles({ projectRoot, wiki, profile, version, agents }) {
+    // Fixed order (not the caller's), so the result never depends on how the flags were typed.
+    const targets = AGENT_NAMES.filter((a) => agents.includes(a)).map((a) => AGENT_TARGETS[a]);
+    const abs = (rel) => join(projectRoot, rel);
+    const files = new Map();
+    for (const { instructions } of targets) {
+        const path = pointerFile(projectRoot, instructions);
+        if (files.has(path))
+            continue;
+        let current = readIfExists(abs(path));
+        // A new CLAUDE.md hides AGENTS.md from Claude Code, so it imports it.
+        if (current === null && instructions[0] === 'CLAUDE.md' && (files.has('AGENTS.md') || readIfExists(abs('AGENTS.md')) !== null)) {
+            current = '@AGENTS.md\n';
+        }
+        files.set(path, upsertBlock(current, pointerBlock(wiki), path));
+    }
+    for (const dir of new Set(targets.map((t) => t.skillsDir))) {
+        for (const skill of skillFiles({ wiki, profile, version }))
+            files.set(`${dir}/${skill.path}`, skill.text);
+    }
+    return [...files].map(([path, text]) => ({ path, status: writeWithStatus(abs(path), text) }));
+}

package/dist/src/generate/targets.d.ts

@@ -0,0 +1,26 @@
+export declare const AGENT_TARGETS: {
+    readonly copilot: {
+        readonly skillsDir: '.github/skills';
+        readonly instructions: readonly ["AGENTS.md", ".github/copilot-instructions.md"];
+    };
+    readonly claude: {
+        readonly skillsDir: '.claude/skills';
+        readonly instructions: readonly ["CLAUDE.md", ".claude/CLAUDE.md"];
+    };
+    readonly codex: {
+        readonly skillsDir: '.agents/skills';
+        readonly instructions: readonly ["AGENTS.md"];
+    };
+    readonly opencode: {
+        readonly skillsDir: '.agents/skills';
+        readonly instructions: readonly ["AGENTS.md"];
+    };
+    readonly cursor: {
+        readonly skillsDir: '.agents/skills';
+        readonly instructions: readonly ["AGENTS.md"];
+    };
+};
+export type AgentName = keyof typeof AGENT_TARGETS;
+export declare const AGENT_NAMES: AgentName[];
+/** Used when `init` is run without any agent flag. */
+export declare const DEFAULT_AGENTS: AgentName[];

package/dist/src/generate/targets.js

@@ -0,0 +1,18 @@
+// Where each coding agent reads the project instructions and the skills.
+// This table is the single source of truth: the CLI flags, the help text and
+// the validation all derive from it, so supporting a tool is one line.
+//
+//  - skillsDir: folder with <skill>/SKILL.md (open standard: agentskills.io)
+//  - instructions: files that carry the pointer block, in order of preference
+//    (the first is created when none of them exists)
+export const AGENT_TARGETS = {
+    copilot: { skillsDir: '.github/skills', instructions: ['AGENTS.md', '.github/copilot-instructions.md'] },
+    // Claude Code reads AGENTS.md only when the project has no CLAUDE.md at all.
+    claude: { skillsDir: '.claude/skills', instructions: ['CLAUDE.md', '.claude/CLAUDE.md'] },
+    codex: { skillsDir: '.agents/skills', instructions: ['AGENTS.md'] },
+    opencode: { skillsDir: '.agents/skills', instructions: ['AGENTS.md'] },
+    cursor: { skillsDir: '.agents/skills', instructions: ['AGENTS.md'] },
+};
+export const AGENT_NAMES = Object.keys(AGENT_TARGETS);
+/** Used when `init` is run without any agent flag. */
+export const DEFAULT_AGENTS = ['copilot'];

package/dist/src/generate/templates.d.ts

@@ -0,0 +1,13 @@
+import type { Folder } from '../core/types.js';
+export interface TemplatePage {
+    path: string;
+    text: string;
+}
+export declare const sectionSkeleton: (section: string) => string;
+export declare function renderPage({ folder, title, description }: {
+    folder: Pick<Folder, 'type' | 'sections'>;
+    title: string;
+    description: string;
+}): string;
+export declare function testingStrategyPage(): TemplatePage;
+export declare function requiredPages(): TemplatePage[];

package/dist/src/generate/templates.js

@@ -0,0 +1,54 @@
+import { yamlScalar } from '../core/util.js';
+import { coreFolder } from '../core/profile.js';
+// What a section looks like until someone writes it. Used by new pages and by `validate --fix`.
+export const sectionSkeleton = (section) => `# ${section}\n\n<!-- TODO: ${section} -->\n`;
+export function renderPage({ folder, title, description }) {
+    const front = ['---', `type: ${yamlScalar(folder.type)}`, `title: ${yamlScalar(title)}`, `description: ${yamlScalar(description)}`, '---'];
+    const sections = folder.sections.map(sectionSkeleton);
+    return `${front.join('\n')}\n\n${sections.join('\n')}`;
+}
+// Scaffold of the testing strategy page. `init` and `validate --fix` create it
+// when testing/ has no page; it is not a required name, any testing page counts.
+export function testingStrategyPage() {
+    return {
+        path: 'testing/strategy.md',
+        text: renderPage({ folder: coreFolder('testing'), title: 'Testing strategy', description: 'How testing is done in this project.' }),
+    };
+}
+// Required core pages (SPEC.md section 3). Created by `init`.
+export function requiredPages() {
+    return [
+        {
+            path: 'overview/project.md',
+            text: renderPage({
+                folder: coreFolder('overview'),
+                title: 'Project',
+                description: 'What the project is and who it is for.',
+            }),
+        },
+        {
+            path: 'workflows/update-wiki.md',
+            text: [
+                renderPage({
+                    folder: { type: 'Workflow', sections: [] },
+                    title: 'Update the wiki',
+                    description: 'When and how this wiki is updated.',
+                }).trimEnd(),
+                '',
+                UPDATE_WIKI_BODY,
+            ].join('\n'),
+        },
+    ];
+}
+const UPDATE_WIKI_BODY = `# Goal
+
+Keep the wiki faithful to the project with as little manual work as possible. The \`okfcli\` CLI does the mechanical parts (indexes, frontmatter, validation); whoever edits only writes content.
+
+# Steps
+
+1. If a change affects a rule, a pattern or a convention, edit the existing page. Do not create a new page for something that is already documented.
+2. If a new page is needed, create it with \`okfcli new <type> <name> --description "..."\`. It registers the page in the index. Do not edit \`index.md\` by hand.
+3. Fill in the page sections. Explain the reason in \`# Why\` when the page asks for it.
+4. If something no longer applies, mark its page with \`status: deprecated\` instead of just deleting it.
+5. Run \`okfcli validate\` and fix whatever it reports.
+`;

package/dist/src/index.d.ts

@@ -0,0 +1,6 @@
+export { run } from './cli.js';
+export { loadProfile } from './core/profile.js';
+export { validateWiki } from './wiki/rules.js';
+export { parseFrontmatter } from './core/frontmatter.js';
+export { contentHash, trustState } from './core/trust.js';
+export type { Folder, Frontmatter, Issue, Page, Profile, Severity, TrustTier } from './core/types.js';

package/dist/src/index.js

@@ -0,0 +1,7 @@
+// Public API. The CLI is the main interface; these are the pieces other tools
+// (editors, CI scripts) are most likely to reuse.
+export { run } from './cli.js';
+export { loadProfile } from './core/profile.js';
+export { validateWiki } from './wiki/rules.js';
+export { parseFrontmatter } from './core/frontmatter.js';
+export { contentHash, trustState } from './core/trust.js';

package/dist/src/wiki/fixes.d.ts

@@ -0,0 +1,2 @@
+import type { Profile } from '../core/types.js';
+export declare function applyFixes(root: string, profile: Profile): string[];

package/dist/src/wiki/fixes.js

@@ -0,0 +1,45 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CORE_FOLDERS, folderByName } from '../core/profile.js';
+import { loadWiki, missingSections, scanBody } from './pages.js';
+import { regenerateIndexes } from './indexer.js';
+import { requiredPages, sectionSkeleton, testingStrategyPage } from '../generate/templates.js';
+import { writeText } from '../core/util.js';
+// Repairs only what can be decided mechanically. Returns a list of what was done.
+export function applyFixes(root, profile) {
+    const done = [];
+    for (const folder of CORE_FOLDERS) {
+        if (!existsSync(join(root, folder.name))) {
+            mkdirSync(join(root, folder.name), { recursive: true });
+            done.push(`Created folder ${folder.name}/`);
+        }
+    }
+    for (const page of requiredPages()) {
+        if (!existsSync(join(root, page.path))) {
+            writeText(join(root, page.path), page.text);
+            done.push(`Recreated ${page.path}`);
+        }
+    }
+    if (!loadWiki(root).concepts.some((c) => c.folder === 'testing')) {
+        const page = testingStrategyPage();
+        writeText(join(root, page.path), page.text);
+        done.push(`Created ${page.path}`);
+    }
+    for (const page of loadWiki(root).concepts) {
+        const folder = page.folder ? folderByName(profile, page.folder) : undefined;
+        if (!folder || !page.data)
+            continue;
+        const { headings } = scanBody(page.body);
+        const missing = missingSections(folder, headings);
+        if (!missing.length)
+            continue;
+        const file = join(root, page.rel);
+        const text = readFileSync(file, 'utf8').replace(/\s+$/, '');
+        const add = missing.map(sectionSkeleton).join('\n');
+        writeText(file, `${text}\n\n${add}`);
+        done.push(`Added ${missing.map((s) => `"# ${s}"`).join(', ')} to ${page.rel}`);
+    }
+    for (const rel of regenerateIndexes(root, profile))
+        done.push(`Regenerated ${rel}`);
+    return done;
+}

package/dist/src/wiki/indexer.d.ts

@@ -0,0 +1,5 @@
+import type { Profile } from '../core/types.js';
+export declare function renderIndex(root: string, relDir: string, profile: Profile): string;
+export declare function regenerateIndexes(root: string, profile: Profile, { check }?: {
+    check?: boolean;
+}): string[];

package/dist/src/wiki/indexer.js

@@ -0,0 +1,47 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseFrontmatter } from '../core/frontmatter.js';
+import { listDir, wikiDirs } from './pages.js';
+import { humanize, readIfExists, toPosix, writeText, RESERVED } from '../core/util.js';
+import { OKF_VERSION, folderByName } from '../core/profile.js';
+const entryLine = (title, url, description) => `* [${title}](${url})${description ? ` - ${description}` : ''}`;
+// Single line: multi-line descriptions would break the list format.
+const oneLine = (s) => String(s ?? '').replace(/\s+/g, ' ').trim();
+export function renderIndex(root, relDir, profile) {
+    const absDir = join(root, relDir);
+    const { md, dirs } = listDir(absDir);
+    const pages = md.filter((name) => !RESERVED.has(name));
+    const folderMeta = (name) => (relDir === '' ? folderByName(profile, name) : undefined);
+    const prefix = relDir === '' ? '' : `/${relDir}`;
+    const ownMeta = relDir === '' ? undefined : folderByName(profile, relDir);
+    const heading = relDir === '' ? 'Index' : ownMeta?.title ?? humanize(relDir.split('/').pop() ?? relDir);
+    const lines = [`# ${heading}`, ''];
+    const subs = dirs.map((d) => {
+        const meta = folderMeta(d);
+        return entryLine(meta?.title ?? humanize(d), `${prefix}/${d}/index.md`, oneLine(meta?.description));
+    });
+    const files = pages.map((p) => {
+        const { data } = parseFrontmatter(readFileSync(join(absDir, p), 'utf8'));
+        const title = oneLine(data?.title) || humanize(p.replace(/\.md$/, ''));
+        return entryLine(title, `${prefix}/${p}`, oneLine(data?.description));
+    });
+    const entries = [...subs, ...files];
+    lines.push(...(entries.length ? entries : ['_No pages yet._']), '');
+    const body = lines.join('\n');
+    return relDir === '' ? `---\nokf_version: "${OKF_VERSION}"\n---\n${body}` : body;
+}
+// Regenerates every index.md. With check=true it writes nothing and only reports.
+export function regenerateIndexes(root, profile, { check = false } = {}) {
+    const changed = [];
+    for (const rel of ['', ...wikiDirs(root)]) {
+        const file = join(root, rel, 'index.md');
+        const text = renderIndex(root, rel, profile);
+        const current = readIfExists(file);
+        if (current !== null && current.replace(/\r\n/g, '\n') === text)
+            continue;
+        if (!check)
+            writeText(file, text);
+        changed.push(toPosix(rel ? `${rel}/index.md` : 'index.md'));
+    }
+    return changed;
+}

package/dist/src/wiki/pages.d.ts

@@ -0,0 +1,19 @@
+import type { Folder, Page } from '../core/types.js';
+export declare function listDir(absDir: string): {
+    md: string[];
+    dirs: string[];
+};
+export declare function wikiDirs(root: string): string[];
+export declare function loadWiki(root: string): {
+    concepts: Page[];
+    indexes: {
+        rel: string;
+        text: string;
+    }[];
+    dirs: string[];
+};
+export declare const missingSections: (folder: Pick<Folder, 'sections'>, headings: string[]) => string[];
+export declare function scanBody(body: string): {
+    headings: string[];
+    links: string[];
+};

package/dist/src/wiki/pages.js

@@ -0,0 +1,70 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseFrontmatter } from '../core/frontmatter.js';
+import { RESERVED } from '../core/util.js';
+// The one place that decides what is part of the wiki: hidden entries and
+// node_modules are skipped. Names are sorted by code unit, so output is the
+// same on every machine. `md` holds regular .md files (reserved ones included).
+export function listDir(absDir) {
+    const entries = readdirSync(absDir, { withFileTypes: true }).filter((e) => !e.name.startsWith('.') && e.name !== 'node_modules');
+    const names = (keep) => entries.filter(keep).map((e) => e.name).sort();
+    return {
+        md: names((e) => e.isFile() && e.name.endsWith('.md')),
+        dirs: names((e) => e.isDirectory()),
+    };
+}
+// Every directory of the wiki, relative to the root, parents before children.
+export function wikiDirs(root) {
+    const result = [];
+    const walk = (rel) => {
+        for (const d of listDir(join(root, rel)).dirs) {
+            const child = rel ? `${rel}/${d}` : d;
+            result.push(child);
+            walk(child);
+        }
+    };
+    walk('');
+    return result;
+}
+// Loads every markdown file of the wiki.
+export function loadWiki(root) {
+    const concepts = [];
+    const indexes = [];
+    const dirs = wikiDirs(root);
+    for (const dir of ['', ...dirs]) {
+        for (const name of listDir(join(root, dir)).md) {
+            const rel = dir ? `${dir}/${name}` : name;
+            const text = readFileSync(join(root, rel), 'utf8');
+            if (name === 'index.md')
+                indexes.push({ rel, text });
+            else if (!RESERVED.has(name)) {
+                const { data, body } = parseFrontmatter(text);
+                concepts.push({ rel, text, data, body, folder: dir ? (dir.split('/')[0] ?? null) : null });
+            }
+        }
+    }
+    return { concepts, indexes, dirs };
+}
+// The sections a page of this folder still lacks, given its level-1 headings.
+export const missingSections = (folder, headings) => folder.sections.filter((s) => !headings.includes(s));
+// Level-1 headings and markdown links, ignoring fenced code blocks.
+export function scanBody(body) {
+    const headings = [];
+    const links = [];
+    let fenced = false;
+    for (const line of body.split('\n')) {
+        if (/^\s*(```|~~~)/.test(line)) {
+            fenced = !fenced;
+            continue;
+        }
+        if (fenced)
+            continue;
+        const h = /^# (.+?)\s*$/.exec(line);
+        if (h?.[1])
+            headings.push(h[1]);
+        for (const m of line.matchAll(/\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g))
+            if (m[1])
+                links.push(m[1]);
+    }
+    return { headings, links };
+}

package/dist/src/wiki/root.d.ts

@@ -0,0 +1 @@
+export declare function findWikiRoot(cwd: string, explicit?: string): string;

package/dist/src/wiki/root.js

@@ -0,0 +1,29 @@
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { PROFILE_FILE } from '../core/profile.js';
+import { UserError } from '../core/util.js';
+// The wiki root is the folder that contains .okf-profile.yaml.
+export function findWikiRoot(cwd, explicit) {
+    if (explicit) {
+        const root = resolve(cwd, explicit);
+        if (!existsSync(join(root, PROFILE_FILE))) {
+            throw new UserError(`${explicit} is not an okfcli wiki (${PROFILE_FILE} is missing).`);
+        }
+        return root;
+    }
+    let dir = resolve(cwd);
+    for (;;) {
+        if (existsSync(join(dir, PROFILE_FILE)))
+            return dir;
+        // Wiki in ./wiki or ./docs/wiki relative to the current directory.
+        for (const sub of ['wiki', 'docs/wiki']) {
+            if (existsSync(join(dir, sub, PROFILE_FILE)))
+                return join(dir, sub);
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new UserError(`No okfcli wiki found from ${cwd}. Run "okfcli init" or use --wiki <folder>.`);
+}

package/dist/src/wiki/rules.d.ts

@@ -0,0 +1,3 @@
+import type { Issue, Profile } from '../core/types.js';
+export declare const DEFAULT_SEVERITY: Record<string, 'error' | 'warning'>;
+export declare function validateWiki(root: string, profile: Profile): Issue[];

package/dist/src/wiki/rules.js

@@ -0,0 +1,150 @@
+import { existsSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { CORE_FOLDERS, folderByName } from '../core/profile.js';
+import { loadWiki, missingSections, scanBody } from './pages.js';
+import { regenerateIndexes } from './indexer.js';
+import { KEBAB } from '../core/util.js';
+import { requiredPages } from '../generate/templates.js';
+import { countTodos, trustState } from '../core/trust.js';
+export const DEFAULT_SEVERITY = {
+    'okf.frontmatter': 'error',
+    'okf.type': 'error',
+    'okf.index': 'error',
+    'structure.core-folder': 'error',
+    'structure.required-page': 'error',
+    'structure.testing-page': 'error',
+    'structure.unknown-folder': 'warning',
+    'page.type': 'error',
+    'page.sections': 'error',
+    'page.todo': 'warning',
+    'frontmatter.title': 'error',
+    'frontmatter.description': 'error',
+    'frontmatter.status': 'error',
+    'frontmatter.verified': 'warning',
+    'frontmatter.verified-outdated': 'warning',
+    'name.kebab-case': 'error',
+    'index.out-of-date': 'error',
+    'link.broken': 'warning',
+    'page.orphan': 'warning',
+};
+const STATUSES = ['draft', 'stable', 'deprecated'];
+const isBlank = (v) => v === undefined || v === null || String(v).trim() === '';
+// Returns the list of issues: { rule, severity, file, message, fix }.
+export function validateWiki(root, profile) {
+    const issues = [];
+    const add = (rule, file, message, fix) => {
+        const severity = profile.severity[rule] ?? DEFAULT_SEVERITY[rule];
+        if (severity === 'off' || severity === undefined)
+            return;
+        issues.push({ rule, severity, file, message, fix });
+    };
+    const wiki = loadWiki(root);
+    // Structure
+    for (const folder of CORE_FOLDERS) {
+        if (!existsSync(join(root, folder.name))) {
+            add('structure.core-folder', `${folder.name}/`, `Core folder "${folder.name}/" is missing.`, 'Run "okfcli validate --fix" to create it.');
+        }
+    }
+    for (const page of requiredPages()) {
+        if (!existsSync(join(root, page.path))) {
+            add('structure.required-page', page.path, `Required page ${page.path} is missing.`, 'Run "okfcli validate --fix" to recreate it.');
+        }
+    }
+    if (existsSync(join(root, 'testing')) && !wiki.concepts.some((c) => c.folder === 'testing')) {
+        add('structure.testing-page', 'testing/', 'testing/ has no strategy page.', 'Run "okfcli validate --fix" to scaffold testing/strategy.md, or create one with "okfcli new testing <name>".');
+    }
+    // Names
+    for (const rel of [...wiki.dirs, ...wiki.concepts.map((c) => c.rel.replace(/\.md$/, ''))]) {
+        const bad = rel.split('/').find((seg) => !KEBAB.test(seg));
+        if (bad) {
+            add('name.kebab-case', rel, `"${bad}" is not kebab-case.`, 'Rename it using lowercase letters, digits and hyphens, then run "okfcli validate --fix".');
+        }
+    }
+    // Reserved files
+    for (const idx of wiki.indexes) {
+        const hasFront = /^---\r?\n/.test(idx.text);
+        if (hasFront) {
+            const keys = [...idx.text.matchAll(/^([A-Za-z_][\w-]*):/gm)].map((m) => m[1]);
+            const allowed = idx.rel === 'index.md' && keys.every((k) => k === 'okf_version');
+            if (!allowed) {
+                add('okf.index', idx.rel, 'index.md must not have frontmatter (only the root one may carry okf_version).', 'Run "okfcli validate --fix" to regenerate it.');
+            }
+        }
+    }
+    // Concept pages
+    const linkedFrom = new Map();
+    for (const page of wiki.concepts) {
+        const { rel, data, body } = page;
+        if (!data) {
+            add('okf.frontmatter', rel, 'Missing or unparseable YAML frontmatter.', 'Start the file with a "---" block containing at least type, title and description.');
+            continue;
+        }
+        if (isBlank(data.type)) {
+            add('okf.type', rel, 'Frontmatter has no "type".', 'Add a "type:" field.');
+        }
+        const folder = page.folder ? folderByName(profile, page.folder) : undefined;
+        if (!folder) {
+            add('structure.unknown-folder', rel, page.folder ? `Folder "${page.folder}/" is not part of the profile.` : 'Pages must live inside a profile folder, not at the wiki root.', 'Move the page to a profile folder, or declare the folder in extra_folders of .okf-profile.yaml.');
+        }
+        else {
+            if (!isBlank(data.type) && data.type !== folder.type) {
+                add('page.type', rel, `type is "${String(data.type)}" but pages in ${folder.name}/ must be "${folder.type}".`, `Set "type: ${folder.type}" or move the page.`);
+            }
+        }
+        if (isBlank(data.title))
+            add('frontmatter.title', rel, 'Frontmatter has no "title".', 'Add a "title:" field.');
+        if (isBlank(data.description))
+            add('frontmatter.description', rel, 'Frontmatter has no "description".', 'Add a one-sentence "description:" field.');
+        if (data.status !== undefined && !STATUSES.includes(String(data.status))) {
+            add('frontmatter.status', rel, `status "${String(data.status)}" is not valid.`, `Use one of: ${STATUSES.join(', ')}.`);
+        }
+        if (data.status !== 'deprecated') {
+            const { tier, outdated, last } = trustState(data, body);
+            const review = `Review the page and run "okfcli verify ${rel} --by human:<id>".`;
+            if (outdated) {
+                add('frontmatter.verified-outdated', rel, `Page changed after it was verified (last by ${String(last?.by ?? 'unknown')} on ${String(last?.at ?? '?').slice(0, 10)}).`, review);
+            }
+            else if (tier === 'unverified') {
+                add('frontmatter.verified', rel, 'Page has not been reviewed.', review);
+            }
+        }
+        const { headings, links } = scanBody(body);
+        if (folder) {
+            for (const section of missingSections(folder, headings)) {
+                add('page.sections', rel, `Missing required section "# ${section}".`, 'Run "okfcli validate --fix" to add the skeleton, then fill it in.');
+            }
+        }
+        const todos = countTodos(body);
+        if (todos)
+            add('page.todo', rel, `${todos} unfilled TODO placeholder${todos > 1 ? 's' : ''}.`, 'Write the section content and remove the "<!-- TODO -->" comment.');
+        for (const target of links) {
+            if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith('#'))
+                continue;
+            const path = target.split('#')[0] ?? '';
+            if (!path.endsWith('.md'))
+                continue;
+            const resolved = path.startsWith('/') ? path.slice(1) : posix.normalize(posix.join(posix.dirname(rel), path));
+            if (!existsSync(join(root, resolved))) {
+                add('link.broken', rel, `Broken link to ${target}.`, 'Fix the path or remove the link.');
+            }
+            else if (resolved !== rel) {
+                const from = linkedFrom.get(resolved) ?? new Set();
+                from.add(rel);
+                linkedFrom.set(resolved, from);
+            }
+        }
+    }
+    const entryPoints = new Set(requiredPages().map((p) => p.path));
+    for (const page of wiki.concepts) {
+        if (page.data && !entryPoints.has(page.rel) && !linkedFrom.has(page.rel)) {
+            add('page.orphan', page.rel, 'No other page links to this one.', 'Link it from a related page (for example the workflow or architecture page that uses it).');
+        }
+    }
+    // Indexes
+    for (const rel of regenerateIndexes(root, profile, { check: true })) {
+        add('index.out-of-date', rel, 'This index does not match the pages in its folder (or is missing).', 'Run "okfcli validate --fix" to regenerate it.');
+    }
+    const order = { error: 0, warning: 1 };
+    issues.sort((a, b) => order[a.severity] - order[b.severity] || a.file.localeCompare(b.file) || a.rule.localeCompare(b.rule));
+    return issues;
+}