okfcli 0.0.0-stage → 0.1.0

package/dist/src/commands/new.js

@@ -0,0 +1,53 @@
+import { join } from 'node:path';
+import { findFolderByType, loadProfile, typeAlias } from '../core/profile.js';
+import { regenerateIndexes } from '../wiki/indexer.js';
+import { renderPage } from '../generate/templates.js';
+import { UserError, assertKebabPath, createText, errorCode, humanize } from '../core/util.js';
+export const newHelp = `okfcli new <type> <name> --description "..." [--title "..."]
+
+Creates a page with frontmatter and a section skeleton, and registers it in
+the index.md of its folder. The name is relative to the folder of the type
+(e.g. "state-management" or "ui/forms"). The type is the singular name: overview, architecture, pattern, convention, workflow,
+testing, feature, module, interface, operation, troubleshooting.`;
+export function newPage({ root, type, name, title, description }) {
+    const profile = loadProfile(root);
+    const folder = findFolderByType(profile, type);
+    if (!folder) {
+        const valid = profile.folders.map((f) => typeAlias(f.type)).join(', ');
+        throw new UserError(`Unknown type "${type}". Available types: ${valid}.`);
+    }
+    if (!description?.trim()) {
+        throw new UserError('Missing --description: one sentence saying what the page is about.');
+    }
+    const slug = name.replace(/\.md$/, '').replace(/^\/+|\/+$/g, '');
+    assertKebabPath(slug);
+    const rel = `${folder.name}/${slug}.md`;
+    const file = join(root, rel);
+    const pageTitle = title?.trim() || humanize(slug.split('/').pop() ?? slug);
+    const text = renderPage({
+        folder,
+        title: pageTitle,
+        description: description.trim(),
+    });
+    try {
+        createText(file, text);
+    }
+    catch (err) {
+        if (errorCode(err) === 'EEXIST')
+            throw new UserError(`${rel} already exists. Edit it instead of creating it again.`);
+        throw err;
+    }
+    const indexes = regenerateIndexes(root, profile);
+    const sections = folder.sections.map((s) => `# ${s}`);
+    return {
+        path: rel,
+        type: folder.type,
+        sections,
+        updated: indexes,
+        text: [
+            `Created ${rel} (type: ${folder.type}).`,
+            `Indexes updated: ${indexes.join(', ') || 'none'}.`,
+            `Fill in these sections: ${sections.join(', ')}.`,
+        ].join('\n'),
+    };
+}

package/dist/src/commands/validate.d.ts

@@ -0,0 +1,7 @@
+import type { CommandResult } from '../core/types.js';
+export declare const validateHelp = "okfcli validate [--fix] [--strict]\n\nChecks the wiki against OKF v0.2 and the base profile (see SPEC.md section 8):\nstructure, sections, links, indexes and review state (which pages nobody has\nreviewed, or that changed after being verified). Exits with code 1 if there is\nany error (with --strict, any warning too).\n  --fix     repair what can be decided mechanically (folders, required pages,\n            missing section skeletons, indexes), then validate again\n  --strict  treat warnings as failures\n  --json    print { ok, errors, warnings, fixed, review, issues }, each issue as\n            { rule, severity, file, message, fix }";
+export declare function validateCommand({ root, fix, strict }: {
+    root: string;
+    fix?: boolean | undefined;
+    strict?: boolean | undefined;
+}): CommandResult;

package/dist/src/commands/validate.js

@@ -0,0 +1,49 @@
+import { folderByName, loadProfile } from '../core/profile.js';
+import { validateWiki } from '../wiki/rules.js';
+import { applyFixes } from '../wiki/fixes.js';
+import { loadWiki } from '../wiki/pages.js';
+import { trustState } from '../core/trust.js';
+export const validateHelp = `okfcli validate [--fix] [--strict]
+
+Checks the wiki against OKF v0.2 and the base profile (see SPEC.md section 8):
+structure, sections, links, indexes and review state (which pages nobody has
+reviewed, or that changed after being verified). Exits with code 1 if there is
+any error (with --strict, any warning too).
+  --fix     repair what can be decided mechanically (folders, required pages,
+            missing section skeletons, indexes), then validate again
+  --strict  treat warnings as failures
+  --json    print { ok, errors, warnings, fixed, review, issues }, each issue as
+            { rule, severity, file, message, fix }`;
+// How many pages are at each trust tier. Deprecated pages are not asked to be
+// reviewed, so they are counted apart.
+function reviewSummary(root, profile) {
+    const pages = loadWiki(root).concepts.filter((c) => c.data && c.folder && folderByName(profile, c.folder));
+    const active = pages.filter((p) => p.data?.status !== 'deprecated');
+    const states = active.map((p) => trustState(p.data, p.body));
+    const count = (pred) => states.filter(pred).length;
+    return {
+        pages: pages.length,
+        deprecated: pages.length - active.length,
+        'human-reviewed': count((s) => s.tier === 'human-reviewed'),
+        'machine-confirmed': count((s) => s.tier === 'machine-confirmed'),
+        unverified: count((s) => s.tier === 'unverified' && !s.outdated),
+        outdated: count((s) => s.outdated),
+    };
+}
+export function validateCommand({ root, fix = false, strict = false }) {
+    const profile = loadProfile(root);
+    const fixed = fix ? applyFixes(root, profile) : [];
+    const issues = validateWiki(root, profile);
+    const errors = issues.filter((i) => i.severity === 'error').length;
+    const warnings = issues.length - errors;
+    const ok = errors === 0 && !(strict && warnings > 0);
+    const review = reviewSummary(root, profile);
+    const lines = [];
+    if (fixed.length)
+        lines.push('Fixed:', ...fixed.map((f) => `  ${f}`), '');
+    for (const i of issues) {
+        lines.push(`${i.severity.padEnd(7)} ${i.rule}  ${i.file}`, `        ${i.message} ${i.fix}`);
+    }
+    lines.push(issues.length ? '' : null, `Review: ${review['human-reviewed']} human-reviewed, ${review['machine-confirmed']} machine-confirmed, ${review.unverified} unverified, ${review.outdated} outdated (${review.deprecated} deprecated pages not counted).`, `${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'}.${ok ? '' : ' Validation failed.'}`);
+    return { ok, errors, warnings, fixed, review, issues, text: lines.filter((l) => l !== null).join('\n') };
+}

package/dist/src/commands/verify.d.ts

@@ -0,0 +1,12 @@
+import type { CommandResult } from '../core/types.js';
+export declare const verifyHelp = "okfcli verify <path> [--by <actor>] [--force]\n\nRecords that a page has been reviewed: adds { by, at, hash } to \"verified\".\nThe hash fingerprints the content that was read; if the page is edited later,\nthe verification is reported as outdated until it is verified again.\nOne entry per actor: a repeat verification replaces the previous one.\nThe path is relative to the wiki, with or without \".md\".\n  --by     actor: human:<id>, process:<id> or <tool>/<version>.\n           Default: $OKFCLI_ACTOR, else okfcli/<version> (machine-confirmed).\n           Use human:<id> only when a person has actually reviewed the page.\n  --force  verify even if the page still has unfilled TODO placeholders\n\nA person can also verify by hand, by adding to the page frontmatter:\n  verified:\n    - { by: human:<id>, at: <ISO date-time> }\n(entries without a hash are never reported as outdated).";
+export interface VerifyOptions {
+    root: string;
+    cwd: string;
+    path: string | undefined;
+    by?: string | undefined;
+    force?: boolean | undefined;
+    now?: Date;
+    version: string;
+}
+export declare function verifyCommand({ root, cwd, path, by, force, now, version }: VerifyOptions): CommandResult;

package/dist/src/commands/verify.js

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { join, relative, resolve, isAbsolute, sep } from 'node:path';
+import { isMap } from 'yaml';
+import { loadProfile } from '../core/profile.js';
+import { editFrontmatter, parseFrontmatter } from '../core/frontmatter.js';
+import { contentHash, countTodos, trustState, validVerifications } from '../core/trust.js';
+import { UserError, isoNow, toPosix, writeText } from '../core/util.js';
+const ACTOR = /^(?:(?:human|process):\S+|[^\s/:]+\/\S+)$/;
+export const verifyHelp = `okfcli verify <path> [--by <actor>] [--force]
+
+Records that a page has been reviewed: adds { by, at, hash } to "verified".
+The hash fingerprints the content that was read; if the page is edited later,
+the verification is reported as outdated until it is verified again.
+One entry per actor: a repeat verification replaces the previous one.
+The path is relative to the wiki, with or without ".md".
+  --by     actor: human:<id>, process:<id> or <tool>/<version>.
+           Default: $OKFCLI_ACTOR, else okfcli/<version> (machine-confirmed).
+           Use human:<id> only when a person has actually reviewed the page.
+  --force  verify even if the page still has unfilled TODO placeholders
+
+A person can also verify by hand, by adding to the page frontmatter:
+  verified:
+    - { by: human:<id>, at: <ISO date-time> }
+(entries without a hash are never reported as outdated).`;
+// Accepts a path relative to the wiki or to the current directory.
+function locatePage(root, cwd, arg) {
+    const withExt = arg.endsWith('.md') ? arg : `${arg}.md`;
+    const candidates = [join(root, withExt)];
+    if (!isAbsolute(withExt))
+        candidates.push(resolve(cwd, withExt));
+    for (const file of candidates) {
+        if (!existsSync(file))
+            continue;
+        // Resolve symlinks too, so a link inside the wiki cannot point at a file outside it.
+        const rel = relative(realpathSync(root), realpathSync(file));
+        if (rel && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
+            return { file, rel: toPosix(rel) };
+    }
+    throw new UserError(`Page not found: ${arg}. Use a path relative to the wiki, e.g. patterns/state-management.md.`);
+}
+export function verifyCommand({ root, cwd, path, by, force = false, now = new Date(), version }) {
+    loadProfile(root);
+    if (!path)
+        throw new UserError('Usage: okfcli verify <path> [--by <actor>]');
+    const actor = by ?? process.env.OKFCLI_ACTOR ?? `okfcli/${version}`;
+    if (!ACTOR.test(actor)) {
+        throw new UserError(`Invalid actor "${actor}". Use human:<id>, process:<id> or <tool>/<version>.`);
+    }
+    const { file, rel } = locatePage(root, cwd, path);
+    const text = readFileSync(file, 'utf8');
+    const { data, body } = parseFrontmatter(text);
+    if (!data)
+        throw new UserError(`${rel} has no parseable frontmatter; fix it first (okfcli validate).`);
+    const todos = countTodos(body);
+    if (todos && !force) {
+        throw new UserError(`${rel} still has ${todos} unfilled TODO placeholder${todos > 1 ? 's' : ''}. Fill them in before verifying (or use --force).`);
+    }
+    const entry = { by: actor, at: isoNow(now), hash: contentHash(data, body) };
+    // Keep the verifications that still describe this content; drop outdated ones and the actor's previous entry.
+    const kept = validVerifications(data, body).filter((e) => e.by !== actor);
+    const next = editFrontmatter(text, (doc) => {
+        const seq = doc.createNode([...kept, entry]);
+        for (const item of seq.items)
+            if (isMap(item))
+                item.flow = true;
+        doc.set('verified', seq);
+    });
+    writeText(file, next);
+    const after = parseFrontmatter(next);
+    const { tier } = trustState(after.data, after.body);
+    return {
+        path: rel,
+        tier,
+        verified: [...kept, entry],
+        text: `Verified ${rel} as ${actor} (${tier}).`,
+    };
+}

package/dist/src/core/frontmatter.d.ts

@@ -0,0 +1,7 @@
+import { type Document } from 'yaml';
+import type { Frontmatter } from './types.js';
+export declare function parseFrontmatter(text: string): {
+    data: Frontmatter | null;
+    body: string;
+};
+export declare function editFrontmatter(text: string, mutate: (doc: Document) => void): string;

package/dist/src/core/frontmatter.js

@@ -0,0 +1,27 @@
+import { parse, parseDocument } from 'yaml';
+import { UserError } from './util.js';
+const FENCE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+// Returns { data, body }. data is null when there is no parseable frontmatter.
+export function parseFrontmatter(text) {
+    const match = FENCE.exec(text);
+    if (!match)
+        return { data: null, body: text };
+    const body = text.slice(match[0].length);
+    try {
+        const data = parse(match[1] ?? '');
+        return { data: data && typeof data === 'object' && !Array.isArray(data) ? data : null, body };
+    }
+    catch {
+        return { data: null, body };
+    }
+}
+// Edits the frontmatter through a YAML document, keeping comments, order and
+// the rest of the file untouched. Returns the new text.
+export function editFrontmatter(text, mutate) {
+    const match = FENCE.exec(text);
+    if (!match)
+        throw new UserError('The page has no frontmatter to edit.');
+    const doc = parseDocument(match[1] ?? '');
+    mutate(doc);
+    return `---\n${doc.toString({ lineWidth: 0 }).trimEnd()}\n---\n${text.slice(match[0].length)}`;
+}

package/dist/src/core/profile.d.ts

@@ -0,0 +1,12 @@
+import type { Folder, Profile } from './types.js';
+export declare const PROFILE_ID = "base@0.1";
+export declare const PROFILE_FILE = ".okf-profile.yaml";
+export declare const OKF_VERSION = "0.2";
+export declare const CORE_FOLDERS: Folder[];
+export declare const OPTIONAL_FOLDERS: Folder[];
+export declare const typeAlias: (type: string) => string;
+export declare function loadProfile(wikiRoot: string): Profile;
+export declare const folderByName: (profile: Profile, name: string) => Folder | undefined;
+/** One of the base profile folders; they always exist. */
+export declare function coreFolder(name: string): Folder;
+export declare function findFolderByType(profile: Profile, alias: string): Folder | undefined;

package/dist/src/core/profile.js

@@ -0,0 +1,101 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+import { KEBAB, UserError } from './util.js';
+export const PROFILE_ID = 'base@0.1';
+export const PROFILE_FILE = '.okf-profile.yaml';
+export const OKF_VERSION = '0.2';
+const SEVERITIES = ['error', 'warning', 'off'];
+// Base profile folders. Names and `type` are fixed; see SPEC.md section 3.
+const folder = (core, name, type, title, description, sections) => ({
+    name,
+    type,
+    title,
+    description,
+    sections,
+    core,
+});
+const core = (...args) => folder(true, ...args);
+const optional = (...args) => folder(false, ...args);
+export const CORE_FOLDERS = [
+    core('overview', 'Overview', 'Overview', 'What the project is, its scope and its glossary.', ['Purpose', 'Scope']),
+    core('architecture', 'Architecture', 'Architecture', 'Structure, layers and dependency rules.', ['Overview', 'Rules', 'Why']),
+    core('patterns', 'Pattern', 'Patterns', 'How each thing is implemented, with a real example.', ['When to use', 'How', 'Example', 'Why']),
+    core('conventions', 'Convention', 'Conventions', 'Style, naming and working conventions.', ['Rule', 'Examples']),
+    core('workflows', 'Workflow', 'Workflows', 'How we work: setup, build, PRs, releases, onboarding.', ['Goal', 'Steps']),
+    core('testing', 'Testing', 'Testing', 'Testing strategy, how to run it and rules.', ['Scope', 'How to run', 'Rules']),
+];
+export const OPTIONAL_FOLDERS = [
+    optional('features', 'Feature', 'Features', 'Business capabilities and flows.', ['Summary', 'Behavior']),
+    optional('modules', 'Module', 'Modules', 'Internal packages and components.', ['Responsibility', 'Public API']),
+    optional('interfaces', 'Interface', 'Interfaces', 'External contracts: APIs, events, integrations.', ['Contract', 'Consumers']),
+    optional('operations', 'Operation', 'Operations', 'Deployment, runbooks and incidents.', ['When', 'Steps']),
+    optional('troubleshooting', 'Troubleshooting', 'Troubleshooting', 'Known problems and how to fix them.', ['Symptom', 'Cause', 'Fix']),
+];
+// Command-line alias for a type: "Pattern" -> "pattern".
+export const typeAlias = (type) => type.toLowerCase().replace(/\s+/g, '-');
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+export function loadProfile(wikiRoot) {
+    const file = join(wikiRoot, PROFILE_FILE);
+    if (!existsSync(file)) {
+        throw new UserError(`${PROFILE_FILE} not found in ${wikiRoot}. Is this an okfcli wiki? Run "okfcli init".`);
+    }
+    let config;
+    try {
+        config = parse(readFileSync(file, 'utf8')) ?? {};
+    }
+    catch (err) {
+        throw new UserError(`${PROFILE_FILE} is not valid YAML: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!isRecord(config)) {
+        throw new UserError(`${PROFILE_FILE} must be a YAML mapping.`);
+    }
+    if (config.extra_folders != null && !Array.isArray(config.extra_folders)) {
+        throw new UserError(`${PROFILE_FILE}: "extra_folders" must be a list.`);
+    }
+    const severity = config.severity ?? {};
+    if (!isRecord(severity)) {
+        throw new UserError(`${PROFILE_FILE}: "severity" must be a mapping of rule to ${SEVERITIES.join(', ')}.`);
+    }
+    for (const [rule, level] of Object.entries(severity)) {
+        if (!SEVERITIES.includes(level)) {
+            throw new UserError(`${PROFILE_FILE}: severity of "${rule}" is "${String(level)}"; use ${SEVERITIES.join(', ')}.`);
+        }
+    }
+    const extra = (config.extra_folders ?? []).map((entry) => {
+        const f = isRecord(entry) ? entry : {};
+        if (!f.name || !f.type) {
+            throw new UserError(`${PROFILE_FILE}: every extra_folders entry needs "name" and "type".`);
+        }
+        if (typeof f.name !== 'string' || !KEBAB.test(f.name)) {
+            throw new UserError(`${PROFILE_FILE}: extra_folders name "${String(f.name)}" must be kebab-case (lowercase letters, digits and hyphens).`);
+        }
+        const type = String(f.type);
+        const sections = (Array.isArray(f.sections) ? f.sections : []).map((s) => String(s).replace(/^#+\s*/, ''));
+        return {
+            name: f.name,
+            type,
+            title: f.title ? String(f.title) : type,
+            description: f.description ? String(f.description) : '',
+            sections,
+            core: false,
+            extra: true,
+        };
+    });
+    return {
+        config,
+        severity: severity,
+        folders: [...CORE_FOLDERS, ...OPTIONAL_FOLDERS, ...extra],
+    };
+}
+export const folderByName = (profile, name) => profile.folders.find((f) => f.name === name);
+/** One of the base profile folders; they always exist. */
+export function coreFolder(name) {
+    const folder = CORE_FOLDERS.find((f) => f.name === name);
+    if (!folder)
+        throw new Error(`Unknown core folder: ${name}`);
+    return folder;
+}
+export function findFolderByType(profile, alias) {
+    return profile.folders.find((f) => typeAlias(f.type) === alias.toLowerCase());
+}

package/dist/src/core/trust.d.ts

@@ -0,0 +1,10 @@
+import type { Frontmatter, TrustTier, Verification } from './types.js';
+export declare function verifiedList(data: Frontmatter | null): Verification[];
+export declare function contentHash(data: Frontmatter | null, body: string): string;
+export declare function validVerifications(data: Frontmatter | null, body: string): Verification[];
+export declare function trustState(data: Frontmatter | null, body: string): {
+    tier: TrustTier;
+    outdated: boolean;
+    last: Verification | undefined;
+};
+export declare const countTodos: (body: string) => number;

package/dist/src/core/trust.js

@@ -0,0 +1,42 @@
+import { createHash } from 'node:crypto';
+// Trust signals of a page, derived from its frontmatter (OKF v0.2, section 5).
+// `verified` may be a list or, as OKF allows, a single { by, at } mapping.
+export function verifiedList(data) {
+    const v = data?.verified;
+    if (!v)
+        return [];
+    return (Array.isArray(v) ? v : [v]).filter((e) => !!e && typeof e === 'object');
+}
+const canonical = (value) => {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value && typeof value === 'object') {
+        const obj = value;
+        return Object.fromEntries(Object.keys(obj).sort().map((k) => [k, canonical(obj[k])]));
+    }
+    return value;
+};
+// Hash of what a reviewer read: the frontmatter (except verified and status,
+// which do not change the content) and the body.
+export function contentHash(data, body) {
+    const { verified: _verified, status: _status, ...rest } = data ?? {};
+    const text = `${JSON.stringify(canonical(rest))}\n${body.replace(/\r\n/g, '\n').trim()}`;
+    return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+// A verification still counts when it has no hash (written by hand) or its
+// hash matches the current content.
+export function validVerifications(data, body) {
+    const current = contentHash(data, body);
+    return verifiedList(data).filter((e) => !e.hash || String(e.hash) === current);
+}
+// tier: unverified | machine-confirmed | human-reviewed
+// outdated: the page was verified, but its content changed afterwards.
+export function trustState(data, body) {
+    const all = verifiedList(data);
+    const valid = validVerifications(data, body);
+    if (!valid.length)
+        return { tier: 'unverified', outdated: all.length > 0, last: all[all.length - 1] };
+    const human = valid.some((e) => String(e.by ?? '').startsWith('human:'));
+    return { tier: human ? 'human-reviewed' : 'machine-confirmed', outdated: false, last: valid[valid.length - 1] };
+}
+export const countTodos = (body) => (body.match(/<!--\s*TODO/g) ?? []).length;

package/dist/src/core/types.d.ts

@@ -0,0 +1,61 @@
+import type { WriteStatus } from './util.js';
+export type Severity = 'error' | 'warning' | 'off';
+/** A folder of the wiki: the base profile ones plus `extra_folders` from the profile. */
+export interface Folder {
+    name: string;
+    type: string;
+    title: string;
+    description: string;
+    sections: string[];
+    core: boolean;
+    extra?: boolean;
+}
+export interface Profile {
+    config: Record<string, unknown>;
+    severity: Record<string, Severity>;
+    folders: Folder[];
+}
+/** Parsed YAML frontmatter. Its values come from user files, so they are `unknown`. */
+export type Frontmatter = Record<string, unknown>;
+export interface Page {
+    /** Path relative to the wiki root, with "/" separators. */
+    rel: string;
+    text: string;
+    /** null when the page has no parseable frontmatter. */
+    data: Frontmatter | null;
+    body: string;
+    /** First path segment, or null for a page at the wiki root. */
+    folder: string | null;
+}
+/** One entry of the `verified` list. Hand-written entries may omit `hash`. */
+export interface Verification {
+    by?: unknown;
+    at?: unknown;
+    hash?: unknown;
+}
+export type TrustTier = 'unverified' | 'machine-confirmed' | 'human-reviewed';
+export interface Issue {
+    rule: string;
+    severity: 'error' | 'warning';
+    file: string;
+    message: string;
+    fix: string;
+}
+export interface ReviewSummary {
+    pages: number;
+    deprecated: number;
+    'human-reviewed': number;
+    'machine-confirmed': number;
+    unverified: number;
+    outdated: number;
+}
+/** What every command returns: `text` for people, the rest for `--json`. */
+export interface CommandResult {
+    text: string;
+    ok?: boolean;
+    [key: string]: unknown;
+}
+export interface AgentFileResult {
+    path: string;
+    status: WriteStatus;
+}

package/dist/src/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/core/util.d.ts

@@ -0,0 +1,17 @@
+/** Expected error: the message is printed and the process exits with code 1, no stack trace. */
+export declare class UserError extends Error {
+}
+export declare const RESERVED: Set<string>;
+export declare const KEBAB: RegExp;
+export declare const toPosix: (p: string) => string;
+export declare function writeText(file: string, text: string): void;
+export declare function createText(file: string, text: string): void;
+export declare function readIfExists(file: string): string | null;
+export type WriteStatus = 'created' | 'updated' | 'unchanged';
+export declare function writeWithStatus(file: string, text: string): WriteStatus;
+export declare function humanize(slug: string): string;
+export declare function isoNow(now?: Date): string;
+export declare const yamlScalar: (value: unknown) => string;
+export declare function assertKebabPath(rel: string): void;
+/** Reads the `code` of a Node error without assuming the thrown value is an Error. */
+export declare const errorCode: (e: unknown) => string | undefined;

package/dist/src/core/util.js

@@ -0,0 +1,67 @@
+import { mkdirSync, writeFileSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { stringify } from 'yaml';
+/** Expected error: the message is printed and the process exits with code 1, no stack trace. */
+export class UserError extends Error {
+}
+// Files the CLI owns inside every wiki folder; they are never pages.
+export const RESERVED = new Set(['index.md', 'log.md']);
+export const KEBAB = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+// Wiki paths always use "/", on Windows too.
+export const toPosix = (p) => p.split('\\').join('/');
+// Writes through a temp file and a rename, so a crash never leaves a truncated page.
+export function writeText(file, text) {
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, text);
+        renameSync(tmp, file);
+    }
+    catch (err) {
+        rmSync(tmp, { force: true });
+        throw err;
+    }
+}
+// Creates a new file; fails with EEXIST instead of overwriting (no check-then-write race).
+export function createText(file, text) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, text, { flag: 'wx' });
+}
+// Reads a text file, or null when it does not exist (or is a directory).
+export function readIfExists(file) {
+    try {
+        return readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        const code = errorCode(e);
+        if (code === 'ENOENT' || code === 'EISDIR')
+            return null;
+        throw e;
+    }
+}
+// Writes the file only when its content changes, and says what happened.
+export function writeWithStatus(file, text) {
+    const current = readIfExists(file);
+    if (current === text)
+        return 'unchanged';
+    writeText(file, text);
+    return current === null ? 'created' : 'updated';
+}
+export function humanize(slug) {
+    const words = slug.replace(/-/g, ' ');
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+export function isoNow(now = new Date()) {
+    return now.toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+// Single-line YAML scalar (quoted only when needed).
+export const yamlScalar = (value) => stringify(value, { lineWidth: 0 }).trim();
+export function assertKebabPath(rel) {
+    for (const s of rel.split('/')) {
+        if (!KEBAB.test(s)) {
+            throw new UserError(`"${s}" is not kebab-case (lowercase letters, digits and hyphens). Example: "state-management".`);
+        }
+    }
+}
+/** Reads the `code` of a Node error without assuming the thrown value is an Error. */
+export const errorCode = (e) => typeof e === 'object' && e !== null && 'code' in e && typeof e.code === 'string' ? e.code : undefined;

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

@@ -0,0 +1,24 @@
+import { type AgentName } from './targets.js';
+import type { AgentFileResult, Profile } from '../core/types.js';
+export declare const BLOCK_START = "<!-- okfcli:start -->";
+export declare const BLOCK_END = "<!-- okfcli:end -->";
+export declare function pointerBlock(wiki: string): string;
+export declare function skillFiles({ wiki, profile, version }: {
+    wiki: string;
+    profile: Profile;
+    version: string;
+}): {
+    path: string;
+    text: string;
+}[];
+export declare function upsertBlock(current: string | null, block: string, file: string): string;
+export declare function pointerFile(projectRoot: string, candidates: readonly [string, ...string[]]): string;
+interface WriteAgentFilesOptions {
+    projectRoot: string;
+    wiki: string;
+    profile: Profile;
+    version: string;
+    agents: AgentName[];
+}
+export declare function writeAgentFiles({ projectRoot, wiki, profile, version, agents }: WriteAgentFilesOptions): AgentFileResult[];
+export {};