@ferrule-io/ok-fine 0.0.0-stage → 0.3.7

package/dist/okf/paths.js

@@ -0,0 +1,99 @@
+import { createHash } from "node:crypto";
+import { posix } from "node:path";
+import { OkfError } from "../errors.js";
+export const PROJECT_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+export const SEGMENT_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export function normalizeConceptIdForWrite(raw) {
+    let s = raw;
+    if (s.startsWith("/")) {
+        s = s.slice(1);
+    }
+    if (s.endsWith(".md")) {
+        s = s.slice(0, -3);
+    }
+    if (s.length === 0) {
+        throw new OkfError("invalid_id", 400, "concept ID cannot be empty");
+    }
+    if (s.length > 512) {
+        throw new OkfError("invalid_id", 400, "concept ID cannot exceed 512 characters");
+    }
+    const segments = s.split("/");
+    if (segments.length > 12) {
+        throw new OkfError("invalid_id", 400, "concept ID cannot exceed 12 path segments");
+    }
+    for (const seg of segments) {
+        if (!SEGMENT_RE.test(seg)) {
+            throw new OkfError("invalid_id", 400, `invalid path segment "${seg}" in concept ID`);
+        }
+    }
+    const lastSeg = segments[segments.length - 1];
+    if (!lastSeg) {
+        throw new OkfError("invalid_id", 400, "concept ID cannot have empty trailing segment");
+    }
+    const lastLower = lastSeg.toLowerCase();
+    if (lastLower === "index" || lastLower === "log") {
+        throw new OkfError("invalid_id", 400, `last segment of concept ID cannot be "${lastLower}"`);
+    }
+    return segments.join("/");
+}
+export function normalizeFilePathForWrite(raw) {
+    if (raw.toLowerCase().endsWith(".md")) {
+        throw new OkfError("use_write_concept", 400, "markdown files are concepts; use write_concept");
+    }
+    let s = raw;
+    if (s.startsWith("/")) {
+        s = s.slice(1);
+    }
+    if (s.length === 0) {
+        throw new OkfError("invalid_path", 400, "file path cannot be empty");
+    }
+    if (s.length > 512) {
+        throw new OkfError("invalid_path", 400, "file path cannot exceed 512 characters");
+    }
+    const segments = s.split("/");
+    if (segments.length > 12) {
+        throw new OkfError("invalid_path", 400, "file path cannot exceed 12 path segments");
+    }
+    for (const seg of segments) {
+        if (!SEGMENT_RE.test(seg)) {
+            throw new OkfError("invalid_path", 400, `invalid path segment "${seg}" in file path`);
+        }
+    }
+    return segments.join("/");
+}
+export function resolveReadPath(raw) {
+    if (raw.includes("\\")) {
+        throw new OkfError("invalid_path", 400, "path cannot contain backslashes");
+    }
+    let s = raw;
+    if (s.startsWith("/")) {
+        s = s.slice(1);
+    }
+    const rawSegments = s.split("/");
+    for (const seg of rawSegments) {
+        if (seg === ".." || seg.startsWith(".")) {
+            throw new OkfError("invalid_path", 400, "path cannot traverse or contain dot segments");
+        }
+    }
+    const normalized = posix.normalize(s);
+    if (!normalized || normalized === "." || normalized === "") {
+        throw new OkfError("invalid_path", 400, "path cannot be empty");
+    }
+    const segments = normalized.split("/");
+    for (const seg of segments) {
+        if (seg === ".." || seg.startsWith(".")) {
+            throw new OkfError("invalid_path", 400, "path cannot traverse or contain dot segments");
+        }
+    }
+    return normalized;
+}
+export function isReservedName(basename) {
+    return basename === "index.md" || basename === "log.md";
+}
+export function blobRevision(buf) {
+    return createHash("sha1")
+        .update(Buffer.from(`blob ${buf.length}\0`))
+        .update(buf)
+        .digest("hex");
+}
+//# sourceMappingURL=paths.js.map

package/dist/okf/repository.js

@@ -0,0 +1,53 @@
+/**
+ * Normalize a git remote URL to `host/path` (lowercase, no scheme, userinfo, port, or `.git`), so the same
+ * repository compares equal across `git@host:org/repo.git`, `https://host/org/repo`, and `ssh://git@host:22/org/repo`.
+ * Returns null for local paths and anything that is not a recognizable remote.
+ */
+export function normalizeRepository(raw) {
+    const input = raw.trim();
+    if (input === "")
+        return null;
+    let host;
+    let path;
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(input)) {
+        let url;
+        try {
+            url = new URL(input);
+        }
+        catch {
+            return null;
+        }
+        if (url.protocol === "file:")
+            return null;
+        host = url.hostname;
+        path = url.pathname;
+    }
+    else {
+        const scp = /^[^\s/@]+@([^\s/:]+):(.+)$/.exec(input);
+        if (scp) {
+            host = scp[1] ?? "";
+            path = scp[2] ?? "";
+        }
+        else {
+            if (/^[/.~]/.test(input) || input.includes("\\"))
+                return null;
+            const slash = input.indexOf("/");
+            if (slash < 0)
+                return null;
+            host = input.slice(0, slash);
+            path = input.slice(slash + 1);
+            if (!host.includes(".") && host.toLowerCase() !== "localhost")
+                return null;
+        }
+    }
+    host = host.toLowerCase();
+    path = path
+        .toLowerCase()
+        .replace(/\/{2,}/g, "/")
+        .replace(/^\/+|\/+$/g, "")
+        .replace(/\.git$/, "")
+        .replace(/\/+$/, "");
+    const result = `${host}/${path}`;
+    return /^[a-z0-9][a-z0-9.-]*(\/[^/\s]+)+$/.test(result) ? result : null;
+}
+//# sourceMappingURL=repository.js.map

package/dist/okf/semantics.js

@@ -0,0 +1,121 @@
+export const ISO_DATETIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
+export function normalizeVerified(v) {
+    if (v == null) {
+        return [];
+    }
+    const rawList = Array.isArray(v) ? v : [v];
+    const result = [];
+    for (const item of rawList) {
+        if (item && typeof item === "object" && "by" in item && typeof item.by === "string" && item.by.length > 0) {
+            const at = "at" in item && typeof item.at === "string" ? item.at : undefined;
+            result.push({ by: item.by, at });
+        }
+    }
+    return result;
+}
+export function trustTier(fm) {
+    const verified = normalizeVerified(fm?.verified);
+    if (verified.length === 0) {
+        return "unverified";
+    }
+    for (const entry of verified) {
+        if (entry.by.startsWith("human:")) {
+            return "human-reviewed";
+        }
+    }
+    return "machine-confirmed";
+}
+export function effectiveStatus(fm) {
+    const s = fm?.status;
+    if (s === "draft" || s === "stable" || s === "deprecated") {
+        return s;
+    }
+    return "stable";
+}
+export function staleAfter(fm) {
+    const raw = fm?.stale_after;
+    if (typeof raw === "string") {
+        const parsed = Date.parse(raw);
+        if (!Number.isNaN(parsed)) {
+            return raw;
+        }
+    }
+    return null;
+}
+export function isStale(fm, now) {
+    const sa = staleAfter(fm);
+    if (!sa) {
+        return false;
+    }
+    const time = Date.parse(sa);
+    if (Number.isNaN(time)) {
+        return false;
+    }
+    return now.getTime() >= time;
+}
+export function generatedAt(fm) {
+    if (fm?.generated &&
+        typeof fm.generated === "object" &&
+        "at" in fm.generated &&
+        typeof fm.generated.at === "string") {
+        return fm.generated.at;
+    }
+    const legacy = fm?.timestamp;
+    if (typeof legacy === "string") {
+        return legacy;
+    }
+    if (legacy instanceof Date) {
+        return legacy.toISOString().replace(/\.\d{3}Z$/, "Z");
+    }
+    return null;
+}
+export function generatedBy(fm) {
+    if (fm?.generated &&
+        typeof fm.generated === "object" &&
+        "by" in fm.generated &&
+        typeof fm.generated.by === "string") {
+        return fm.generated.by;
+    }
+    return null;
+}
+export function lastVerifiedAt(fm) {
+    const verified = normalizeVerified(fm?.verified);
+    let latest = null;
+    for (const entry of verified) {
+        if (entry.at) {
+            const parsed = Date.parse(entry.at);
+            if (!Number.isNaN(parsed)) {
+                if (!latest || parsed > latest.timestamp) {
+                    latest = { atStr: entry.at, timestamp: parsed };
+                }
+            }
+        }
+    }
+    return latest?.atStr ?? null;
+}
+const HUMAN_ACTOR_RE = /^human:([A-Za-z0-9._@+-]+)$/;
+const PROCESS_ACTOR_RE = /^process:([A-Za-z0-9._@+-]+)$/;
+const AGENT_ACTOR_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._:+-]+$/;
+export function parseActor(s) {
+    const humanMatch = HUMAN_ACTOR_RE.exec(s);
+    if (humanMatch?.[1]) {
+        return { kind: "human", id: humanMatch[1] };
+    }
+    const processMatch = PROCESS_ACTOR_RE.exec(s);
+    if (processMatch?.[1]) {
+        return { kind: "process", id: processMatch[1] };
+    }
+    if (AGENT_ACTOR_RE.test(s)) {
+        return { kind: "agent", id: s };
+    }
+    return null;
+}
+export function displayTitle(fm, conceptId) {
+    if (typeof fm?.title === "string" && fm.title.length > 0) {
+        return fm.title;
+    }
+    const segments = conceptId.split("/");
+    const last = segments[segments.length - 1];
+    return last && last.length > 0 ? last : conceptId;
+}
+//# sourceMappingURL=semantics.js.map

package/dist/server.js

@@ -0,0 +1,343 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { buildOAuthProtectedResourceMetadata, createMcpHandler, getOAuthProtectedResourceMetadataUrl, } from "@modelcontextprotocol/server";
+import { StdioServerTransport, serveStdio } from "@modelcontextprotocol/server/stdio";
+import Fastify, {} from "fastify";
+import { ZodError } from "zod";
+import { discoverAuthorizationServer } from "./auth/discovery.js";
+import { createAuthenticator } from "./auth/http-auth.js";
+import { JwtTokenVerifier, principalFromAuthInfo } from "./auth/verifier.js";
+import { OkfError } from "./errors.js";
+import { registerMcpRoute } from "./http/mcp-route.js";
+import { registerRestRoutes } from "./http/rest.js";
+import { DEFAULT_UI_DIR, endpointOrigins, registerUiRoutes } from "./http/ui.js";
+import { createMcpServer } from "./mcp/server.js";
+import { KnowledgeService } from "./service/knowledge-service.js";
+import { Catalog } from "./store/catalog.js";
+import { GitBackend } from "./store/git-backend.js";
+import { VERSION } from "./version.js";
+const DISCOVERY_ATTEMPTS = 5;
+const DISCOVERY_RETRY_MS = 2000;
+function parseHostHeader(hostHeader) {
+    if (!hostHeader || typeof hostHeader !== "string")
+        return null;
+    const trimmed = hostHeader.trim();
+    if (trimmed.length === 0 || /[/\s\\@]/.test(trimmed))
+        return null;
+    if (trimmed.startsWith("[")) {
+        const closeBracket = trimmed.indexOf("]");
+        if (closeBracket === -1)
+            return null;
+        const rest = trimmed.slice(closeBracket + 1);
+        if (rest.length > 0 && !/^:\d+$/.test(rest))
+            return null;
+        return trimmed.slice(0, closeBracket + 1).toLowerCase();
+    }
+    const colonIndex = trimmed.indexOf(":");
+    if (colonIndex !== -1) {
+        const port = trimmed.slice(colonIndex + 1);
+        if (!/^\d+$/.test(port))
+            return null;
+        return trimmed.slice(0, colonIndex).toLowerCase();
+    }
+    return trimmed.toLowerCase();
+}
+export async function startServer(config, options = {}) {
+    const tp = config.trustProxy;
+    const trustProxy = typeof tp === "number"
+        ? (_addr, hop) => hop < tp
+        : typeof tp === "string"
+            ? tp
+                .split(",")
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0)
+            : tp;
+    const app = Fastify({
+        logger: { level: config.logLevel, redact: ["req.headers.authorization"] },
+        trustProxy,
+        requestTimeout: 120_000,
+        connectionTimeout: 120_000,
+        bodyLimit: 4 * 1024 * 1024,
+    });
+    app.removeContentTypeParser("text/plain");
+    app.addContentTypeParser(/^text\//, { parseAs: "string", bodyLimit: config.maxFileBytes + 65536 }, (_req, body, done) => done(null, body));
+    app.addContentTypeParser(["application/gzip", "application/x-gzip", "application/octet-stream"], { parseAs: "buffer", bodyLimit: config.maxArchiveBytes }, (_req, body, done) => done(null, body));
+    let authHandler;
+    let uiConnectSrc = [];
+    if (config.auth.mode === "oidc") {
+        let discovered;
+        for (let attempt = 1; !discovered; attempt++) {
+            try {
+                discovered = await discoverAuthorizationServer(config.auth.issuer, {
+                    timeoutMs: 5000,
+                    allowInsecureIssuer: config.auth.allowInsecureIssuer,
+                    ...(config.auth.jwksUri === undefined ? {} : { jwksUri: config.auth.jwksUri }),
+                });
+            }
+            catch (err) {
+                if (attempt >= DISCOVERY_ATTEMPTS)
+                    throw err;
+                app.log.warn({ err, attempt }, "authorization server discovery failed; retrying");
+                await sleep(DISCOVERY_RETRY_MS);
+            }
+        }
+        const { metadata, jwksUri } = discovered;
+        // The web UI fetches these cross-origin; it reaches authorization_endpoint by navigation, which CSP does not cover.
+        uiConnectSrc = endpointOrigins(metadata.token_endpoint, metadata.registration_endpoint);
+        const resourceServerUrl = new URL(`${config.publicBaseUrl}/mcp`);
+        const prm = buildOAuthProtectedResourceMetadata({
+            // Discovery checked `issuer`; buildOAuthProtectedResourceMetadata validates the rest and throws on misconfiguration.
+            oauthMetadata: metadata,
+            resourceServerUrl,
+            scopesSupported: [config.scopeNames.read, config.scopeNames.write, config.scopeNames.admin],
+            resourceName: "ok-fine",
+            dangerouslyAllowInsecureIssuerUrl: config.auth.allowInsecureIssuer,
+        });
+        for (const path of ["/.well-known/oauth-protected-resource", "/.well-known/oauth-protected-resource/mcp"]) {
+            app.get(path, async (_req, reply) => reply.header("access-control-allow-origin", "*").send(prm));
+        }
+        app.get("/.well-known/oauth-authorization-server", async (_req, reply) => reply.header("access-control-allow-origin", "*").send(metadata));
+        const { access } = config.auth;
+        if (access.allowedSubjects.length === 0 &&
+            access.allowedEmails.length === 0 &&
+            access.requiredGroups.length === 0 &&
+            access.allowedClientIds.length === 0) {
+            app.log.warn(`no OAUTH_ALLOWED_* / OAUTH_REQUIRED_GROUPS policy set: every token from ${config.auth.issuer} with an ok-fine scope can read all projects`);
+        }
+        const verifier = new JwtTokenVerifier({
+            issuer: config.auth.issuer,
+            audiences: config.auth.audiences,
+            jwksUri,
+            identityClaims: config.auth.identityClaims,
+            access: config.auth.access,
+        });
+        const authenticator = createAuthenticator({
+            verifier,
+            resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(resourceServerUrl),
+            scopeNames: config.scopeNames,
+        });
+        authHandler = {
+            mode: "oidc",
+            authenticate: async (req) => {
+                const result = await authenticator.authenticate(req.headers.authorization);
+                if (!result.ok)
+                    return result.response;
+                req.principal = result.principal;
+                req.authInfo = result.authInfo;
+                return null;
+            },
+            insufficientScope: (scopeName) => authenticator.insufficientScope(scopeName),
+        };
+    }
+    else {
+        app.log.warn("authentication disabled, every request has admin access; never expose this beyond localhost");
+        const allowedHosts = {
+            localhost: true,
+            "127.0.0.1": true,
+            "[::1]": true,
+            "::1": true,
+        };
+        const publicHost = new URL(config.publicBaseUrl).hostname.toLowerCase();
+        allowedHosts[publicHost] = true;
+        if (publicHost.startsWith("[") && publicHost.endsWith("]")) {
+            allowedHosts[publicHost.slice(1, -1)] = true;
+        }
+        app.addHook("onRequest", async (req, reply) => {
+            if (req.method === "GET" && (req.url === "/healthz" || req.url.startsWith("/healthz?"))) {
+                return;
+            }
+            const host = parseHostHeader(req.headers.host);
+            if (!host || !allowedHosts[host]) {
+                return reply.code(403).send({
+                    error: {
+                        code: "forbidden",
+                        message: `Host header '${req.headers.host ?? ""}' is not allowed in AUTH_MODE=none`,
+                    },
+                });
+            }
+            if (req.headers.origin !== undefined) {
+                const rawOrigin = Array.isArray(req.headers.origin) ? req.headers.origin[0] : req.headers.origin;
+                let originAllowed = false;
+                if (typeof rawOrigin === "string") {
+                    try {
+                        const parsed = new URL(rawOrigin);
+                        if ((parsed.protocol === "http:" || parsed.protocol === "https:") &&
+                            allowedHosts[parsed.hostname.toLowerCase()]) {
+                            originAllowed = true;
+                        }
+                    }
+                    catch {
+                        // invalid origin URL
+                    }
+                }
+                if (!originAllowed) {
+                    return reply.code(403).send({
+                        error: {
+                            code: "forbidden",
+                            message: `Origin '${rawOrigin ?? ""}' is not allowed in AUTH_MODE=none`,
+                        },
+                    });
+                }
+            }
+        });
+        const allScopes = [config.scopeNames.read, config.scopeNames.write, config.scopeNames.admin];
+        const anonymousAuthInfo = {
+            token: "",
+            clientId: "anonymous",
+            scopes: allScopes,
+            extra: { sub: "anonymous", identity: null },
+        };
+        const anonymousPrincipal = principalFromAuthInfo(anonymousAuthInfo, config.scopeNames);
+        authHandler = {
+            mode: "none",
+            authenticate: async (req) => {
+                req.principal = anonymousPrincipal;
+                req.authInfo = anonymousAuthInfo;
+                return null;
+            },
+        };
+    }
+    const storage = await GitBackend.open(config, app.log);
+    const catalog = new Catalog();
+    const service = new KnowledgeService({ config, storage, catalog, log: app.log });
+    await service.initialize();
+    const mcpHandler = createMcpHandler(({ authInfo }) => {
+        if (!authInfo)
+            throw new Error("MCP request reached the handler without authInfo");
+        return createMcpServer(service, principalFromAuthInfo(authInfo, config.scopeNames), app.log);
+    }, { legacy: "stateless", responseMode: "json" });
+    app.setErrorHandler((error, req, reply) => {
+        if (error instanceof OkfError) {
+            return reply
+                .code(error.status)
+                .send({ error: { code: error.code, message: error.message, details: error.details } });
+        }
+        if (error instanceof ZodError) {
+            return reply
+                .code(400)
+                .send({ error: { code: "bad_request", message: "invalid request", details: error.issues } });
+        }
+        const fastifyError = error;
+        if (fastifyError.code === "FST_ERR_CTP_BODY_TOO_LARGE") {
+            return reply.code(413).send({ error: { code: "payload_too_large", message: "request body too large" } });
+        }
+        if (fastifyError.code === "FST_ERR_CTP_INVALID_MEDIA_TYPE") {
+            return reply.code(415).send({ error: { code: "unsupported_media", message: "unsupported content type" } });
+        }
+        const status = fastifyError.statusCode;
+        if (typeof status === "number" && status >= 400 && status < 500) {
+            return reply
+                .code(status)
+                .send({ error: { code: "bad_request", message: fastifyError.message ?? "bad request" } });
+        }
+        req.log.error({ err: error }, "unhandled error");
+        return reply.code(500).send({ error: { code: "internal", message: "internal error" } });
+    });
+    app.get("/healthz", async () => ({ status: "ok" }));
+    await registerUiRoutes(app, {
+        dir: options.uiDir ?? DEFAULT_UI_DIR,
+        publicBaseUrl: config.publicBaseUrl,
+        clientConfig: {
+            authMode: config.auth.mode,
+            oauthClientId: config.auth.mode === "oidc" ? (config.auth.uiClientId ?? null) : null,
+            scope: config.scopeNames.read,
+            version: VERSION,
+        },
+        connectSrc: uiConnectSrc,
+    });
+    app.decorateRequest("principal", null);
+    app.decorateRequest("authInfo", null);
+    await app.register(async (secured) => {
+        secured.addHook("onRequest", async (req, reply) => {
+            const challenge = await authHandler.authenticate(req);
+            if (challenge)
+                return reply.send(challenge);
+            if (authHandler.mode === "oidc") {
+                const need = req.routeOptions?.config?.permission ?? "read";
+                const p = req.principal;
+                const permitted = p !== null && (need === "admin" ? p.canAdmin : need === "write" ? p.canWrite : p.canRead);
+                if (!permitted)
+                    return reply.send(authHandler.insufficientScope(config.scopeNames[need]));
+            }
+        });
+        registerMcpRoute(secured, (request, options) => mcpHandler.fetch(request, options), config.publicBaseUrl);
+        registerRestRoutes(secured, service);
+    });
+    const address = await app.listen({ port: config.port, host: config.host });
+    const stopSync = startPeriodicSync(config, service, app.log);
+    return {
+        app,
+        url: address,
+        close: async () => {
+            stopSync();
+            await app.close();
+            await storage.close();
+            await mcpHandler.close();
+        },
+    };
+}
+/** Runs `service.syncNow()` every GIT_SYNC_INTERVAL_SECONDS when a remote is configured; returns a stop function. */
+function startPeriodicSync(config, service, log) {
+    if (!config.gitRemoteUrl || config.gitSyncIntervalSeconds <= 0)
+        return () => undefined;
+    let syncTimer;
+    let stopped = false;
+    const scheduleSync = () => {
+        syncTimer = setTimeout(async () => {
+            try {
+                await service.syncNow();
+            }
+            catch (err) {
+                log.error({ err }, "periodic sync failed");
+            }
+            if (!stopped)
+                scheduleSync();
+        }, config.gitSyncIntervalSeconds * 1000);
+    };
+    scheduleSync();
+    return () => {
+        stopped = true;
+        clearTimeout(syncTimer);
+    };
+}
+/** Serves MCP over stdio to one local client with full permissions. Only the transport writes to stdout. */
+export async function startStdioServer(config, options) {
+    const { log } = options;
+    const stdin = options.stdin ?? process.stdin;
+    const stdout = options.stdout ?? process.stdout;
+    const storage = await GitBackend.open(config, log);
+    const catalog = new Catalog();
+    const service = new KnowledgeService({ config, storage, catalog, log });
+    await service.initialize();
+    const principal = {
+        subject: "local",
+        clientId: "stdio",
+        identity: options.identity,
+        scopes: [],
+        canRead: true,
+        canWrite: true,
+        canAdmin: true,
+    };
+    const stopSync = startPeriodicSync(config, service, log);
+    // serveStdio owns transport.onclose, so watch stdin directly.
+    const { promise: done, resolve } = Promise.withResolvers();
+    stdin.once("end", resolve);
+    stdin.once("close", resolve);
+    const handle = serveStdio(() => createMcpServer(service, principal, log), {
+        transport: new StdioServerTransport(stdin, stdout),
+        onerror: (err) => log.error({ err }, "stdio transport error"),
+    });
+    let closing;
+    return {
+        done,
+        close: () => {
+            closing ??= (async () => {
+                stopSync();
+                await handle.close();
+                // Waits for the storage mutex, so an in-flight write still commits.
+                await storage.close();
+            })();
+            return closing;
+        },
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/service/feedback.js

@@ -0,0 +1,40 @@
+import { OkfError } from "../errors.js";
+import { VERSION } from "../version.js";
+export const FEEDBACK_REPOSITORY = "https://github.com/ferrule-io/ok-fine";
+// github.com answers 500 for logged-out users above ~6900 characters and 414 URI Too Long above ~8200.
+export const MAX_FEEDBACK_URL_LENGTH = 6000;
+export const FEEDBACK_TYPES = ["bug", "feature", "general"];
+const MESSAGE = "Not submitted yet. Show this URL to the user: it opens a prefilled public GitHub issue on ferrule-io/ok-fine that they review, edit, and submit with their own GitHub account.";
+function present(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+/**
+ * Build a prefilled GitHub new-issue URL. Only `title` and `body` are passed: GitHub 404s permissioned
+ * parameters such as `labels` for users without triage access.
+ */
+export function feedbackLink(input) {
+    const title = `[${input.type}] ${input.title.trim()}`;
+    const lines = [input.body.trim()];
+    for (const [heading, value] of [
+        ["Expected", input.expected],
+        ["Actual", input.actual],
+        ["Reproduction", input.reproduction],
+    ]) {
+        const text = present(value);
+        if (text)
+            lines.push("", `### ${heading}`, "", text);
+    }
+    lines.push("", "---", "", `- Type: ${input.type}`, `- ok-fine version: ${VERSION}`);
+    const tool = present(input.tool);
+    if (tool)
+        lines.push(`- Tool: \`${tool}\``);
+    lines.push("", "_Drafted by an AI agent with the ok-fine `submit_feedback` MCP tool._");
+    const body = `${lines.join("\n")}\n`;
+    const url = `${FEEDBACK_REPOSITORY}/issues/new?${new URLSearchParams({ title, body })}`;
+    if (url.length > MAX_FEEDBACK_URL_LENGTH) {
+        throw new OkfError("bad_request", 400, `feedback is too long for a GitHub issue link (${url.length} > ${MAX_FEEDBACK_URL_LENGTH} characters); shorten body, expected, actual, or reproduction`, { length: url.length, max: MAX_FEEDBACK_URL_LENGTH });
+    }
+    return { url, title, submitted: false, message: MESSAGE };
+}
+//# sourceMappingURL=feedback.js.map