@orboto/mcp 0.178.0

package/dist/tools/primer-facts.js

@@ -0,0 +1,346 @@
+/**
+ * ORB-510 / ORB-513 - primer-fact tools.
+ *
+ * Six tools that wrap the `/projects/:id/primer-facts` and
+ * `/primer-facts/:id` REST surface from ORB-511. Agents call these to
+ * record structured project facts - tech-stack details, conventions,
+ * deployment quirks - that the AI primer (ORB-512) renders at the top
+ * of every session. The skill rule (ORB-514) tells agents *when* to
+ * record; these tools are the *how*.
+ *
+ * All tool descriptions and parameter `.describe()` strings are in
+ * English so the international LLM tool-selection path is reliable.
+ *
+ * Wire order in server.ts:
+ *   - orboto_primer_fact_list
+ *   - orboto_primer_fact_add
+ *   - orboto_primer_fact_update
+ *   - orboto_primer_fact_supersede
+ *   - orboto_primer_fact_verify
+ *   - orboto_primer_fact_delete
+ */
+import { z } from 'zod';
+import { OrbotoApiError } from '../orboto-client.js';
+import { resolveProjectByKey, sizeBlockResult } from './shared.js';
+// ORB-1819 - the writing contract, verbatim in every write-tool
+// description so the writing agent sees it at the moment of writing.
+const FACT_WRITING_CONTRACT = ' Fact: <= 300 chars, one fact per key, the value is the fact - long material goes into a doc, the fact holds the doc key.';
+// ---------------------------------------------------------------------------
+// Shared types + helpers
+// ---------------------------------------------------------------------------
+const PRIMER_FACT_CATEGORIES = [
+    'tech_stack',
+    'conventions',
+    'deployment',
+    'architecture',
+    'integrations',
+    'gotchas',
+    'commands',
+    // ORB-1403 - explicit non-functional requirements (performance, security,
+    // DSGVO, operations, i18n, ...) for the Pflichtenheft NFR chapter.
+    'non_functional',
+    // ORB-1413 - glossary/terminology facts for the Pflichtenheft glossary
+    // chapter (chapter 11) only, so they no longer double-render via `other`.
+    'glossary',
+    'other',
+];
+const PRIMER_FACT_SOURCES = ['manual', 'agent_observed', 'imported'];
+const PrimerFactCategoryEnum = z.enum(PRIMER_FACT_CATEGORIES);
+const PrimerFactSourceEnum = z.enum(PRIMER_FACT_SOURCES);
+function rewritePermissionError(action) {
+    return (err) => {
+        if (err instanceof OrbotoApiError && err.status === 403) {
+            throw new Error(`${action} requires project:edit on the target project, or admin:ai:write for workspace-wide facts.`);
+        }
+        if (err instanceof OrbotoApiError && err.status === 404) {
+            throw new Error(`${action}: target not found (or not visible to your account).`);
+        }
+        if (err instanceof OrbotoApiError && err.status === 409) {
+            throw new Error(`${action}: a fact with that category + key already exists in this scope. Use orboto_primer_fact_supersede or orboto_primer_fact_update instead.`);
+        }
+        throw err;
+    };
+}
+function summariseFact(f) {
+    const markers = [];
+    if (f.source === 'agent_observed' && !f.verified)
+        markers.push('observed');
+    if (f.source === 'imported')
+        markers.push('imported');
+    if (f.supersededById)
+        markers.push('superseded');
+    const tag = markers.length > 0 ? ` _(${markers.join(', ')})_` : '';
+    // Single-line preview of the value - multi-line bodies get truncated
+    // so the list output stays scannable.
+    const valuePreview = f.value.length > 120 || f.value.includes('\n')
+        ? `${f.value.replace(/\n/g, ' ').slice(0, 120)}…`
+        : f.value;
+    const scope = f.projectId === null ? '[workspace]' : '[project]';
+    return `- ${scope} **${f.category}/${f.key}**: ${valuePreview}${tag}`;
+}
+// ---------------------------------------------------------------------------
+// orboto_primer_fact_list
+// ---------------------------------------------------------------------------
+export const primerFactListToolConfig = {
+    title: 'List structured project primer facts',
+    description: 'List structured project facts that feed the AI primer (tech stack, conventions, deployment, architecture, integrations, gotchas, commands). Use this to discover what the project has already documented before adding a new observation. Workspace-wide facts (applying to every project) are merged in by default; pass includeWorkspace=false to see only project-scoped rows.',
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key, e.g. "ORB". Case-insensitive.'),
+        category: PrimerFactCategoryEnum.optional().describe('Filter by category. Omit for all categories.'),
+        source: PrimerFactSourceEnum.optional().describe('Filter by provenance: manual (operator), agent_observed (bot, awaiting verification), imported.'),
+        verified: z.boolean().optional().describe('Filter by verification flag. true = verified facts only, false = unverified only.'),
+        includeWorkspace: z.boolean().default(true).describe('When true (default), workspace-wide facts that apply to every project are merged into the result.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makePrimerFactListHandler(client) {
+    return async ({ projectKey, category, source, verified, includeWorkspace, }) => {
+        const project = await resolveProjectByKey(client, projectKey);
+        const qs = new URLSearchParams();
+        if (category)
+            qs.set('category', category);
+        if (source)
+            qs.set('source', source);
+        if (verified !== undefined)
+            qs.set('verified', String(verified));
+        qs.set('includeWorkspace', String(includeWorkspace ?? true));
+        const path = `/projects/${project.id}/primer-facts${qs.toString() ? `?${qs}` : ''}`;
+        const rows = await client.get(path).catch(rewritePermissionError('list primer facts'));
+        const text = rows.length === 0
+            ? 'No primer facts in scope.'
+            : rows.map(summariseFact).join('\n');
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: {
+                count: rows.length,
+                facts: rows.map((f) => ({
+                    id: f.id,
+                    scope: f.projectId === null ? 'workspace' : 'project',
+                    category: f.category,
+                    key: f.key,
+                    value: f.value,
+                    source: f.source,
+                    verified: f.verified,
+                    lastVerifiedAt: f.lastVerifiedAt,
+                })),
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_primer_fact_add
+// ---------------------------------------------------------------------------
+export const primerFactAddToolConfig = {
+    title: 'Record a new project primer fact',
+    description: 'Record a new structured fact about the project that future AI agents should see at session start. Use when you learn something during work that is missing from the primer (a library version, a convention, a deployment quirk, an architecture decision). Note: the auto-generated primer does NOT automatically include CLAUDE.md / AGENTS.md content unless the operator configured repo briefings and the API host can read those files from disk - most deployments cannot. Treat key conventions documented in CLAUDE.md / AGENTS.md as fair game to record here so they survive cross-deployment. Set observed=true when you are recording from a bot/agent context - the fact will land as agent_observed and require operator verification before losing the (observed) marker.'
+        + FACT_WRITING_CONTRACT,
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key, e.g. "ORB". Case-insensitive.'),
+        category: PrimerFactCategoryEnum.describe('Category bucket. Pick the closest fit; categories are fixed. Use "non_functional" to capture an explicit non-functional requirement (performance / security / DSGVO / operations / i18n) - the key names the sub-area, the value is the requirement; these render verbatim in the requirements-spec NFR chapter. Use "glossary" for a term/definition pair - these render only in the requirements-spec glossary chapter.'),
+        key: z.string().min(1).max(120).describe('Short machine-readable identifier, e.g. "package-manager", "node-version", "css-framework". Lowercase + dashes preferred.'),
+        value: z.string().min(1).max(8000).describe('Human-readable Markdown body, 1-3 sentences typically. Include a version number, a path, or a command where relevant.'),
+        observed: z.boolean().default(false).describe('True = source is agent_observed (needs operator verification). False = manual entry by operator. Bots without project:edit get coerced to agent_observed server-side regardless.'),
+        allowOversize: z.boolean().optional().describe('Override the hard size-cap block (300*2 chars). Only after a call was blocked.'),
+        oversizeReason: z.string().min(10).max(500).optional().describe('Required with allowOversize=true - why this value genuinely needs the length. Audit-logged.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makePrimerFactAddHandler(client) {
+    return async ({ projectKey, category, key, value, observed, allowOversize, oversizeReason, }) => {
+        const project = await resolveProjectByKey(client, projectKey);
+        const body = {
+            category,
+            key,
+            value,
+            source: observed ? 'agent_observed' : 'manual',
+            allowOversize,
+            oversizeReason,
+        };
+        let row;
+        try {
+            row = await client.post(`/projects/${project.id}/primer-facts`, body);
+        }
+        catch (err) {
+            const blocked = sizeBlockResult(err, 'Primer fact add');
+            if (blocked)
+                return blocked;
+            return rewritePermissionError('add primer fact')(err);
+        }
+        const warn = row.sizeWarning ? `\n⚠ ${row.value.length} chars, over the ${row.sizeWarning.limit}-char soft limit. ${row.sizeWarning.hint}` : '';
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Recorded ${project.key} primer fact: ${row.category}/${row.key} (source: ${row.source}, id ${row.id.slice(0, 8)}).${warn}`,
+                }],
+            structuredContent: {
+                id: row.id,
+                category: row.category,
+                key: row.key,
+                source: row.source,
+                verified: row.verified,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_primer_fact_update
+// ---------------------------------------------------------------------------
+export const primerFactUpdateToolConfig = {
+    title: 'Update an existing primer fact',
+    description: 'Update an existing fact. Use this when the value has changed (e.g. version bumped) or you are renaming the key. Bumps last_verified_at automatically when the value changes; pure renames leave it untouched. To replace a fact while preserving history, use orboto_primer_fact_supersede instead.'
+        + FACT_WRITING_CONTRACT,
+    inputSchema: z.object({
+        factId: z.string().min(1).describe('UUID of the fact to update. Read it from orboto_primer_fact_list output.'),
+        value: z.string().min(1).max(8000).optional().describe('New Markdown body.'),
+        category: PrimerFactCategoryEnum.optional().describe('New category.'),
+        key: z.string().min(1).max(120).optional().describe('New key.'),
+        allowOversize: z.boolean().optional().describe('Override the hard size-cap block (300*2 chars). Only after a call was blocked.'),
+        oversizeReason: z.string().min(10).max(500).optional().describe('Required with allowOversize=true - why this value genuinely needs the length. Audit-logged.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makePrimerFactUpdateHandler(client) {
+    return async ({ factId, value, category, key, allowOversize, oversizeReason, }) => {
+        const body = {};
+        if (value !== undefined)
+            body.value = value;
+        if (category !== undefined)
+            body.category = category;
+        if (key !== undefined)
+            body.key = key;
+        if (Object.keys(body).length === 0) {
+            throw new Error('orboto_primer_fact_update needs at least one of value, category, key.');
+        }
+        if (allowOversize !== undefined)
+            body.allowOversize = allowOversize;
+        if (oversizeReason !== undefined)
+            body.oversizeReason = oversizeReason;
+        let row;
+        try {
+            row = await client.patch(`/primer-facts/${factId}`, body);
+        }
+        catch (err) {
+            const blocked = sizeBlockResult(err, 'Primer fact update');
+            if (blocked)
+                return blocked;
+            return rewritePermissionError('update primer fact')(err);
+        }
+        const warn = row.sizeWarning ? `\n⚠ ${row.value.length} chars, over the ${row.sizeWarning.limit}-char soft limit. ${row.sizeWarning.hint}` : '';
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Updated primer fact ${row.category}/${row.key} (id ${row.id.slice(0, 8)}).${warn}`,
+                }],
+            structuredContent: {
+                id: row.id,
+                category: row.category,
+                key: row.key,
+                lastVerifiedAt: row.lastVerifiedAt,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_primer_fact_supersede
+// ---------------------------------------------------------------------------
+export const primerFactSupersedeToolConfig = {
+    title: 'Replace a primer fact while preserving history',
+    description: 'Replace a fact with a corrected version, preserving the old one in history (linked via superseded_by_id). Use when you discover a previously recorded fact was wrong; do not just delete it. The old row gets a tombstoned key suffix so the partial unique index does not collide; the new row starts unverified and needs operator verification before losing the (observed) marker.'
+        + FACT_WRITING_CONTRACT,
+    inputSchema: z.object({
+        oldFactId: z.string().min(1).describe('UUID of the fact being replaced.'),
+        category: PrimerFactCategoryEnum.describe('Category of the new fact (usually unchanged).'),
+        key: z.string().min(1).max(120).describe('Key of the new fact (usually unchanged).'),
+        value: z.string().min(1).max(8000).describe('Corrected Markdown body.'),
+        allowOversize: z.boolean().optional().describe('Override the hard size-cap block (300*2 chars). Only after a call was blocked.'),
+        oversizeReason: z.string().min(10).max(500).optional().describe('Required with allowOversize=true - why this value genuinely needs the length. Audit-logged.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makePrimerFactSupersedeHandler(client) {
+    return async ({ oldFactId, category, key, value, allowOversize, oversizeReason, }) => {
+        let row;
+        try {
+            row = await client.post(`/primer-facts/${oldFactId}/supersede`, { category, key, value, allowOversize, oversizeReason });
+        }
+        catch (err) {
+            const blocked = sizeBlockResult(err, 'Primer fact supersede');
+            if (blocked)
+                return blocked;
+            return rewritePermissionError('supersede primer fact')(err);
+        }
+        const warn = row.sizeWarning ? `\n⚠ ${row.value.length} chars, over the ${row.sizeWarning.limit}-char soft limit. ${row.sizeWarning.hint}` : '';
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Superseded primer fact: new id ${row.id.slice(0, 8)}, category ${row.category}, key ${row.key}.${warn}`,
+                }],
+            structuredContent: {
+                newId: row.id,
+                category: row.category,
+                key: row.key,
+                verified: row.verified,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_primer_fact_verify
+// ---------------------------------------------------------------------------
+export const primerFactVerifyToolConfig = {
+    title: 'Verify an agent-observed primer fact',
+    description: 'Promote an agent-observed fact to verified. Operator-only action; bots without project:edit cannot self-verify. Removes the (observed) marker from the rendered primer and stamps verifiedBy / verifiedAt.',
+    inputSchema: z.object({
+        factId: z.string().min(1).describe('UUID of the fact to verify.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makePrimerFactVerifyHandler(client) {
+    return async ({ factId }) => {
+        const row = await client
+            .post(`/primer-facts/${factId}/verify`, {})
+            .catch(rewritePermissionError('verify primer fact'));
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Verified primer fact ${row.category}/${row.key} (id ${row.id.slice(0, 8)}).`,
+                }],
+            structuredContent: {
+                id: row.id,
+                verified: row.verified,
+                verifiedBy: row.verifiedBy,
+                verifiedAt: row.verifiedAt,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_primer_fact_delete
+// ---------------------------------------------------------------------------
+export const primerFactDeleteToolConfig = {
+    title: 'Delete a primer fact',
+    description: 'Hard-delete a fact. Prefer orboto_primer_fact_supersede when the fact is being replaced; only delete when the fact was wrong from the start or no longer relevant. Writes an audit-log entry; the row itself is gone (no soft-delete).',
+    inputSchema: z.object({
+        factId: z.string().min(1).describe('UUID of the fact to delete.'),
+        reason: z.string().max(500).optional().describe('Optional human-readable reason; recorded in the audit log details for future operators.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makePrimerFactDeleteHandler(client) {
+    return async ({ factId, reason }) => {
+        // ORB-516 - pass the reason through so the audit-log entry
+        // captures it. Old API versions silently ignore the querystring
+        // so there's no compat risk.
+        const path = reason
+            ? `/primer-facts/${factId}?reason=${encodeURIComponent(reason)}`
+            : `/primer-facts/${factId}`;
+        await client.delete(path).catch(rewritePermissionError('delete primer fact'));
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Deleted primer fact ${factId.slice(0, 8)}${reason ? ` (reason: ${reason})` : ''}.`,
+                }],
+            structuredContent: { id: factId, deleted: true, reason: reason ?? null },
+        };
+    };
+}