@bussolabs/closeyourit-cli 0.25.1 → 0.27.0

package/dist/lib/knowledge-doctor.js

@@ -0,0 +1,310 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOCTOR_CHECK_CODES = void 0;
+exports.titleKey = titleKey;
+exports.stripCode = stripCode;
+exports.wikilinkTitles = wikilinkTitles;
+exports.runDoctorChecks = runDoctorChecks;
+exports.doctorTotals = doctorTotals;
+exports.renderDoctorReport = renderDoctorReport;
+exports.fetchDoctorPages = fetchDoctorPages;
+const node_path_1 = require("node:path");
+const knowledge_1 = require("./knowledge");
+const output_1 = require("./output");
+/**
+ * I codici delle verifiche, nell'ordine in cui vengono mostrate: prima ciò che rende una pagina
+ * introvabile, poi ciò che spezza i collegamenti, infine le code ferme e il repo dei documenti.
+ * Codici stabili: chi ne legge l'esito da un programma può filtrare per codice senza inseguire
+ * il testo, che è per le persone.
+ */
+exports.DOCTOR_CHECK_CODES = [
+    'empty-body',
+    'orphan-scope',
+    'duplicate-title',
+    'dangling-link',
+    'stale-review',
+    'stale-consolidation',
+    'inconsistent-consolidation',
+    'missing-source-file',
+];
+/** Quante pagine elenca il referto a schermo per ciascuna verifica, prima di riassumere il resto. */
+const LISTED_PER_CHECK = 10;
+/** Wikilink `[[Titolo]]` / `[[Titolo|etichetta]]`, com'è scritto lato servizio (Knowledge::Links::Parse). */
+const WIKILINK = /\[\[([^\n[\]|]{1,255})(?:\|[^\n[\]]{1,255})?]]/g;
+/** Il tetto ai riferimenti letti per pagina, come lato servizio: una pagina è un documento, non un grafo. */
+const MAX_LINKS_PER_PAGE = 50;
+function text(value) {
+    return typeof value === 'string' ? value : '';
+}
+/**
+ * La chiave con cui il servizio risolve un wikilink verso una pagina: titolo senza spazi ai bordi,
+ * minuscolo (`LOWER(BTRIM(title))` in Knowledge::Links::Sync). Deliberatamente NON normalizza gli
+ * spazi interni né gli accenti: due titoli che il servizio considera diversi devono restare diversi
+ * anche qui, o il referto segnalerebbe collegamenti rotti che rotti non sono.
+ */
+function titleKey(value) {
+    return text(value).trim().toLowerCase();
+}
+/**
+ * Il markdown senza le parti di codice: blocchi recintati (``` / ~~~) e code span inline.
+ * Una guida che documenta la sintassi scrivendo `[[Titolo]]` fra i backtick non sta collegando
+ * niente, e il servizio infatti non la collega (Knowledge::Links::Segments).
+ */
+function stripCode(markdown) {
+    const lines = markdown.split('\n');
+    const prose = [];
+    let fence;
+    for (const line of lines) {
+        if (fence === undefined) {
+            const opening = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+            if (opening) {
+                fence = opening[1];
+                continue;
+            }
+            prose.push(line);
+        }
+        else {
+            const stripped = line.trim();
+            // Chiude solo una riga fatta dello stesso carattere della recinzione, lunga almeno quanto
+            // l'apertura: `~~~` non chiude un blocco aperto con ```.
+            if (stripped.length >= fence.length && new Set(stripped).size === 1 && stripped.startsWith(fence[0])) {
+                fence = undefined;
+            }
+        }
+    }
+    // Code span inline: N backtick, contenuto, gli stessi N backtick.
+    return prose.join('\n').replaceAll(/(`+)[^]*?\1/g, ' ');
+}
+/**
+ * I titoli citati come wikilink nel corpo, deduplicati senza distinzione di maiuscole e nell'ordine
+ * di apparizione — la stessa lettura che fa il servizio quando costruisce il grafo dei collegamenti.
+ */
+function wikilinkTitles(body) {
+    const seen = new Set();
+    const titles = [];
+    for (const match of stripCode(text(body)).matchAll(WIKILINK)) {
+        const title = match[1].trim();
+        if (title === '' || seen.has(title.toLowerCase()))
+            continue;
+        seen.add(title.toLowerCase());
+        titles.push(title);
+        if (titles.length >= MAX_LINKS_PER_PAGE)
+            break;
+    }
+    return titles;
+}
+/** Quanti giorni sono passati da `value`, o undefined se il servizio non ha mandato una data leggibile. */
+function daysSince(value, now) {
+    const raw = text(value).trim();
+    if (raw === '')
+        return undefined;
+    const when = Date.parse(raw);
+    if (Number.isNaN(when))
+        return undefined;
+    return (now.getTime() - when) / 86_400_000;
+}
+/** L'ultima data nota della pagina: quando è stata toccata, o quando è nata. */
+function ageInDays(page, now) {
+    return daysSince(page.updated_at, now) ?? daysSince(page.created_at, now);
+}
+function finding(page, detail) {
+    return { id: String(page.id ?? ''), title: text(page.title), ...(detail === undefined ? {} : { detail }) };
+}
+/** Una verifica il cui esito è dato dalle pagine trovate: nessuna → superata. */
+function check(code, summary, nextStep, pages, failing) {
+    return {
+        code,
+        status: pages.length === 0 ? 'ok' : failing ? 'fail' : 'warning',
+        count: pages.length,
+        summary,
+        next_step: nextStep,
+        pages,
+    };
+}
+/** Una verifica che non è stato possibile fare: esito neutro, e come renderla possibile. */
+function skipped(code, summary, nextStep) {
+    return { code, status: 'skipped', count: 0, summary, next_step: nextStep, pages: [] };
+}
+function listLength(value) {
+    return Array.isArray(value) ? value.length : 0;
+}
+/** La pagina non ha corpo: non c'è niente da indicizzare, nessuna ricerca la troverà mai. */
+function emptyBodyCheck(pages) {
+    return check('empty-body', 'Pages whose body is empty. There is nothing to index, so no search will ever return them.', 'Read it with `cyi kb show <id>`, then write the body with `cyi kb update <id> --body ...`.', pages.filter((page) => text(page.body).trim() === '').map((page) => finding(page)), true);
+}
+/**
+ * Nessun progetto e nessun gruppo. La visibilità si concede per progetto o per gruppo
+ * (Knowledge::Page.visible_to), quindi una pagina senza né l'uno né l'altro la vede SOLO chi ha
+ * accesso pieno all'organizzazione: per tutti gli altri è come se non ci fosse.
+ *
+ * Avviso e non guasto: il dominio la consente deliberatamente — Knowledge::CreatePage rifiuta lo
+ * scope vuoto a chiunque tranne a chi ha accesso pieno — e da fuori non si può sapere se questa
+ * pagina è una dimenticanza o una scelta. Segnalarla come rottura farebbe uscire il comando in
+ * errore su una conoscenza sana.
+ */
+function orphanScopeCheck(pages) {
+    return check('orphan-scope', 'Pages attached to no project and no group. Only someone with full access to the organization can see them; for everybody else they are not there at all.', 'Give it a scope with `cyi kb update <id> --project <key>` (or a group). Leave it as it is if the page really is meant for the whole organization.', pages.filter((page) => listLength(page.projects) === 0 && listLength(page.groups) === 0).map((page) => finding(page)), false);
+}
+/**
+ * Due pagine con lo stesso titolo: il servizio collega un `[[Titolo]]` solo quando UNA pagina lo
+ * porta, quindi ogni citazione a un titolo doppio resta testo semplice.
+ */
+function duplicateTitleCheck(pages) {
+    const byTitle = new Map();
+    for (const page of pages) {
+        const key = titleKey(page.title);
+        if (key === '')
+            continue;
+        byTitle.set(key, [...(byTitle.get(key) ?? []), page]);
+    }
+    const found = [...byTitle.values()]
+        .filter((group) => group.length > 1)
+        .flatMap((group) => group.map((page) => finding(page, `same title as ${group.filter((other) => other !== page).map((other) => String(other.id ?? '')).join(', ')}`)));
+    return check('duplicate-title', 'Two or more pages carry the same title. A `[[Title]]` pointing there stays plain text, because the link cannot tell which one is meant.', 'Rename one of them with `cyi kb update <id> --title ...`, or merge them by hand and delete the leftover.', found, false);
+}
+/**
+ * Wikilink verso un titolo che nessuna pagina porta. Il confronto usa le pagine VISIBILI a questo
+ * accesso: il servizio risolve su tutta l'organizzazione, quindi un collegamento verso una pagina
+ * fuori dal proprio scope compare qui pur essendo sano — ed è detto nel referto, non nascosto.
+ */
+function danglingLinkCheck(pages) {
+    const known = new Set(pages.map((page) => titleKey(page.title)).filter((key) => key !== ''));
+    const found = pages.flatMap((page) => {
+        const missing = wikilinkTitles(page.body).filter((title) => !known.has(title.trim().toLowerCase()));
+        return missing.length === 0 ? [] : [finding(page, missing.join(', '))];
+    });
+    return check('dangling-link', 'Pages linking to `[[Title]]` when no visible page carries that title. Read from the titles as they are now, over the pages this access can see: a link into a project you cannot read shows up here, and so does one whose target was renamed after the link was made (the service kept that one attached).', 'Fix the quoted title, or write the missing page — the link attaches itself as soon as the title exists.', found, false);
+}
+/** Proposte mai decise: restano fuori da ricerca, risposte e pannelli finché qualcuno non sceglie. */
+function staleReviewCheck(pages, staleDays, now) {
+    const found = pages
+        .filter((page) => page.status === 'in_review')
+        .flatMap((page) => {
+        const age = ageInDays(page, now);
+        return age === undefined || age <= staleDays ? [] : [finding(page, `waiting ${Math.floor(age)} days`)];
+    });
+    return check('stale-review', `Proposals nobody decided for more than ${staleDays} days. Until someone does, they stay out of search, answers and related panels.`, 'Accept it with `cyi kb approve <id>` or discard it with `cyi kb reject <id>`.', found, false);
+}
+/** Accettate ma mai scritte fra i documenti versionati: la conoscenza vive in un posto solo. */
+function staleConsolidationCheck(awaiting, staleDays, now) {
+    const found = awaiting.flatMap((page) => {
+        const age = ageInDays(page, now);
+        return age === undefined || age <= staleDays ? [] : [finding(page, `accepted ${Math.floor(age)} days ago`)];
+    });
+    return check('stale-consolidation', `Accepted pages not yet written to the versioned docs for more than ${staleDays} days.`, 'Write the document in the knowledge-base repo, then record it with `cyi kb consolidate <id> --path <path>`.', found, false);
+}
+/** Percorso e data di archiviazione devono dire la stessa cosa: o entrambi ci sono, o nessuno dei due. */
+function inconsistentConsolidationCheck(pages) {
+    const found = pages.flatMap((page) => {
+        const hasPath = text(page.source_path).trim() !== '';
+        const hasDate = text(page.consolidated_at).trim() !== '';
+        if (hasPath === hasDate)
+            return [];
+        return [finding(page, hasPath ? 'path without a filing date' : 'filed without a path')];
+    });
+    return check('inconsistent-consolidation', 'Pages whose document path and filing date disagree: one is set and the other is not, so the filing queue cannot be trusted.', 'Re-record the filing with `cyi kb consolidate <id> --path <path>`.', found, true);
+}
+/**
+ * Il documento versionato dichiarato dalla pagina esiste davvero sul disco? Senza `--docs-root`
+ * la verifica non si fa e lo dice: inventare un esito su una radice indovinata segnalerebbe come
+ * mancante ogni documento del parco.
+ */
+function missingSourceFileCheck(pages, docsRoot, fileExists) {
+    const summary = 'Pages that name a versioned document. The file has to be there, or the page points at knowledge that no longer exists.';
+    if (docsRoot === undefined || fileExists === undefined) {
+        return skipped('missing-source-file', `${summary} Not checked: the docs repository lives on this machine, not on the service.`, 'Run it again with `--docs-root <path to the knowledge-base repo>`.');
+    }
+    const root = (0, node_path_1.resolve)(docsRoot);
+    const found = pages.flatMap((page) => {
+        const path = text(page.source_path).trim();
+        if (path === '')
+            return [];
+        const target = (0, node_path_1.isAbsolute)(path) ? (0, node_path_1.resolve)(path) : (0, node_path_1.resolve)(root, path);
+        if (target !== root && !target.startsWith(root + node_path_1.sep))
+            return [finding(page, `${path} — outside the docs root`)];
+        return fileExists(target) ? [] : [finding(page, path)];
+    });
+    return check('missing-source-file', summary, 'Write the missing document, or point the page at the right one with `cyi kb consolidate <id> --path <path>`.', found, true);
+}
+/**
+ * Tutte le verifiche, sempre tutte e sempre nello stesso ordine: un referto che tace sulle prove
+ * superate non si distingue da un referto che non le ha fatte.
+ */
+function runDoctorChecks(input) {
+    const { awaitingConsolidation, docsRoot, fileExists, now, pages, scopedToProject, staleDays } = input;
+    return [
+        emptyBodyCheck(pages),
+        orphanScopeCheck(pages),
+        scopedToProject
+            ? skipped('duplicate-title', 'Two or more pages carrying the same title. Not checked: titles are unique across the whole organization, and this run only read one project.', 'Run it again without `--project` to compare every visible page.')
+            : duplicateTitleCheck(pages),
+        scopedToProject
+            ? skipped('dangling-link', 'Pages linking to `[[Title]]` when no page carries that title. Not checked: the service resolves those links across the whole organization, and this run only read one project — every link pointing outside it would look broken.', 'Run it again without `--project` to compare every visible page.')
+            : danglingLinkCheck(pages),
+        staleReviewCheck(pages, staleDays, now),
+        staleConsolidationCheck(awaitingConsolidation, staleDays, now),
+        inconsistentConsolidationCheck(pages),
+        missingSourceFileCheck(pages, docsRoot, fileExists),
+    ];
+}
+/** Quante verifiche sono fallite e quante hanno solo avvisato. */
+function doctorTotals(checks) {
+    return {
+        failures: checks.filter((entry) => entry.status === 'fail').length,
+        warnings: checks.filter((entry) => entry.status === 'warning').length,
+    };
+}
+/**
+ * Il referto a schermo: prima la tabella di tutte le verifiche con il loro esito, poi un blocco per
+ * ciascuna di quelle che hanno qualcosa da dire — la spiegazione, il passo da fare e le pagine.
+ */
+function renderDoctorReport(report) {
+    const scanned = report.truncated
+        ? `${report.scanned} pages examined (the collection is larger — raise --limit to cover it)`
+        : `${report.scanned} pages examined`;
+    const table = (0, output_1.renderTable)(['STATUS', 'CHECK', 'FOUND'], report.checks.map((entry) => [`${(0, output_1.statusDot)(entry.status)} ${entry.status}`, entry.code, String(entry.count)]));
+    const blocks = report.checks
+        .filter((entry) => entry.status !== 'ok')
+        .map((entry) => {
+        const heading = `${(0, output_1.statusDot)(entry.status)} ${(0, output_1.sanitize)(entry.code)} (${entry.count})`;
+        const lines = [`\n${heading}`, `  ${(0, output_1.sanitize)(entry.summary)}`, `  Next step: ${(0, output_1.sanitize)(entry.next_step)}`];
+        for (const page of entry.pages.slice(0, LISTED_PER_CHECK)) {
+            const detail = page.detail ? ` — ${(0, output_1.sanitize)((0, knowledge_1.truncate)(page.detail, 80))}` : '';
+            lines.push(`  [${(0, output_1.sanitize)(page.id)}] ${(0, output_1.sanitize)((0, knowledge_1.truncate)(page.title))}${detail}`);
+        }
+        if (entry.pages.length > LISTED_PER_CHECK)
+            lines.push(`  … and ${entry.pages.length - LISTED_PER_CHECK} more`);
+        return lines.join('\n');
+    });
+    return [`🩺 Knowledge doctor · ${scanned}`, '', table, ...blocks].join('\n');
+}
+/**
+ * Legge le pagine da esaminare, fermandosi a `limit` righe.
+ *
+ * Il tetto c'è perché un controllo che scandisce tutto il parco non deve poter diventare una
+ * scansione infinita lanciata in linea: quando si ferma prima della fine lo DICE (`truncated`), così
+ * il referto non fa passare per "tutto a posto" ciò che semplicemente non ha guardato.
+ */
+async function fetchDoctorPages(api, opts) {
+    const per = Math.min(100, opts.limit);
+    const pages = [];
+    let page = 1;
+    let totalPages = 1;
+    do {
+        const query = (0, knowledge_1.buildPagesQuery)({
+            awaitingConsolidation: opts.awaitingConsolidation,
+            kinds: [],
+            page,
+            per,
+            project: opts.project,
+            status: opts.awaitingConsolidation ? undefined : 'all',
+        });
+        // eslint-disable-next-line no-await-in-loop
+        const res = await api.get(`/cli/v1/knowledge/pages?${query}`);
+        pages.push(...(Array.isArray(res.data) ? res.data : []));
+        totalPages = Number(res.meta?.total_pages ?? 1);
+        page += 1;
+    } while (page <= totalPages && pages.length < opts.limit);
+    const truncated = pages.length > opts.limit || page <= totalPages;
+    return { pages: pages.slice(0, opts.limit), truncated };
+}

package/dist/lib/knowledge.d.ts

@@ -95,3 +95,33 @@ export declare function renderBook(book: Record<string, unknown>): string;
  * state is the whole point, gets it automatically.
  */
 export declare function renderPagesTable(pages: Array<Record<string, unknown>>): string;
+/** One page of the knowledge context printed when a working session starts (CYCL-55). */
+export interface ContextPage extends Record<string, unknown> {
+    id?: string;
+    title?: string;
+    kind?: string;
+}
+/**
+ * The pages out of a knowledge-context payload, in either shape the endpoint may answer with: an
+ * object carrying `pages`, or the bare list. Anything else reads as "no pages" rather than as a
+ * failure — at session start an unexpected payload must not be louder than an empty one.
+ */
+export declare function contextPages(data: unknown): ContextPage[];
+/**
+ * How to name the project in the heading: the key the server sent back when it names one, otherwise
+ * the reference the caller asked with — which for a git-resolved project is already its key.
+ */
+export declare function contextProjectLabel(data: unknown, fallback: string): string;
+/**
+ * Render the knowledge context: one heading plus one line per page, id included so the reader can
+ * go straight to `kb show <id>`. Deliberately a short list and not a table — it is printed at the
+ * start of every session, where anything taller would be scrolled past instead of read.
+ */
+export declare function renderKnowledgeContext(pages: ContextPage[], project: string): string;
+/**
+ * The same payload with at most `limit` pages, whichever shape it came in. The cap the caller asked
+ * for has to hold on the JSON envelope too: the server is told `per`, but nothing guarantees the
+ * context route honours it, and a machine consumer that asked for five pages must not silently get
+ * ten. Everything else in the payload is preserved.
+ */
+export declare function capContextPages<T>(data: T, limit: number): T;

package/dist/lib/knowledge.js

@@ -12,6 +12,10 @@ exports.pageScopeLines = pageScopeLines;
 exports.renderBooksTable = renderBooksTable;
 exports.renderBook = renderBook;
 exports.renderPagesTable = renderPagesTable;
+exports.contextPages = contextPages;
+exports.contextProjectLabel = contextProjectLabel;
+exports.renderKnowledgeContext = renderKnowledgeContext;
+exports.capContextPages = capContextPages;
 const output_1 = require("./output");
 /** Knowledge page kinds accepted by the backend (Knowledge::Page). */
 exports.KNOWLEDGE_KINDS = ['note', 'decision', 'guide'];
@@ -206,3 +210,63 @@ function renderPagesTable(pages) {
         return row;
     }));
 }
+/**
+ * The pages out of a knowledge-context payload, in either shape the endpoint may answer with: an
+ * object carrying `pages`, or the bare list. Anything else reads as "no pages" rather than as a
+ * failure — at session start an unexpected payload must not be louder than an empty one.
+ */
+function contextPages(data) {
+    if (Array.isArray(data))
+        return data;
+    if (data && typeof data === 'object') {
+        const { pages } = data;
+        if (Array.isArray(pages))
+            return pages;
+    }
+    return [];
+}
+/**
+ * How to name the project in the heading: the key the server sent back when it names one, otherwise
+ * the reference the caller asked with — which for a git-resolved project is already its key.
+ */
+function contextProjectLabel(data, fallback) {
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+        const { project } = data;
+        if (typeof project === 'string' && project.trim() !== '')
+            return project;
+        if (project && typeof project === 'object') {
+            const { key, name } = project;
+            if (typeof key === 'string' && key.trim() !== '')
+                return key;
+            if (typeof name === 'string' && name.trim() !== '')
+                return name;
+        }
+    }
+    return fallback;
+}
+/**
+ * Render the knowledge context: one heading plus one line per page, id included so the reader can
+ * go straight to `kb show <id>`. Deliberately a short list and not a table — it is printed at the
+ * start of every session, where anything taller would be scrolled past instead of read.
+ */
+function renderKnowledgeContext(pages, project) {
+    const heading = `📚 Knowledge · ${(0, output_1.sanitize)(project)} (${pages.length})`;
+    const lines = pages.map((page) => `  [${(0, output_1.sanitize)(page.kind)}] ${(0, output_1.sanitize)(truncate(String(page.title ?? '')))} · ${(0, output_1.sanitize)(page.id)}`);
+    return [heading, ...lines].join('\n');
+}
+/**
+ * The same payload with at most `limit` pages, whichever shape it came in. The cap the caller asked
+ * for has to hold on the JSON envelope too: the server is told `per`, but nothing guarantees the
+ * context route honours it, and a machine consumer that asked for five pages must not silently get
+ * ten. Everything else in the payload is preserved.
+ */
+function capContextPages(data, limit) {
+    if (Array.isArray(data))
+        return (data.length <= limit ? data : data.slice(0, limit));
+    if (data && typeof data === 'object') {
+        const { pages } = data;
+        if (Array.isArray(pages) && pages.length > limit)
+            return { ...data, pages: pages.slice(0, limit) };
+    }
+    return data;
+}

package/dist/lib/lookup.d.ts

@@ -0,0 +1,30 @@
+import { type CliApi } from './api';
+export declare const UUID_RE: RegExp;
+/**
+ * Risoluzione di un riferimento leggibile (chiave di progetto, nome di gruppo) nel suo id.
+ *
+ * Vive qui e non più dentro `BaseCommand` perché non è più solo roba da comando: il server MCP
+ * (CYCL-56) accetta gli stessi riferimenti che accetta la riga di comando, e una seconda copia di
+ * questa ricerca vorrebbe dire due comportamenti che divergono al primo cambio.
+ */
+/**
+ * Resolve a project reference (UUID passes through; otherwise matched by key, case-insensitive).
+ * Walks every page of `/cli/v1/projects`: a key can live past the first page, so a single-page
+ * lookup would 404 keys like legalbloom LBRA/LBWB while their UUID (and first-page keys) worked (CYCL-1).
+ */
+export declare function resolveProjectId(api: CliApi, value: string): Promise<string>;
+/** Resolve an `{id, name}` reference by name (UUID passes through). */
+export declare function resolveNamedId(api: CliApi, path: string, value: string, code: string, label: string): Promise<string>;
+/**
+ * Every row of an organization lookup (teams, roles, groups, members) — all its pages.
+ *
+ * The server serves ten per page: stopping at the first made the eleventh team or the eleventh
+ * person invisible, and a perfectly good name or email came back as "not found" (CYCL-42, the
+ * lesson `resolveProjectId` already learned on project keys in CYCL-1).
+ *
+ * A 403 here is not about the command being run: listing teams needs `permissions.manage` and
+ * listing members `members.view`, permissions that a team workload board never asks for. Left
+ * alone it would read as "Permesso negato" on an operation the caller is entitled to, so the
+ * refusal carries the way out instead — name the id, skip the lookup.
+ */
+export declare function fetchLookupRows<T>(api: CliApi, path: string, hint: string): Promise<T[]>;

package/dist/lib/lookup.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UUID_RE = void 0;
+exports.resolveProjectId = resolveProjectId;
+exports.resolveNamedId = resolveNamedId;
+exports.fetchLookupRows = fetchLookupRows;
+const api_1 = require("./api");
+const error_codes_1 = require("../errors/error-codes");
+exports.UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Risoluzione di un riferimento leggibile (chiave di progetto, nome di gruppo) nel suo id.
+ *
+ * Vive qui e non più dentro `BaseCommand` perché non è più solo roba da comando: il server MCP
+ * (CYCL-56) accetta gli stessi riferimenti che accetta la riga di comando, e una seconda copia di
+ * questa ricerca vorrebbe dire due comportamenti che divergono al primo cambio.
+ */
+/**
+ * Resolve a project reference (UUID passes through; otherwise matched by key, case-insensitive).
+ * Walks every page of `/cli/v1/projects`: a key can live past the first page, so a single-page
+ * lookup would 404 keys like legalbloom LBRA/LBWB while their UUID (and first-page keys) worked (CYCL-1).
+ */
+async function resolveProjectId(api, value) {
+    if (exports.UUID_RE.test(value))
+        return value;
+    let page = 1;
+    let totalPages = 1;
+    do {
+        // eslint-disable-next-line no-await-in-loop
+        const res = await api.get(`/cli/v1/projects?page=${page}&per=100`);
+        const match = (res.data ?? []).find((project) => (project.key ?? '').toLowerCase() === value.toLowerCase());
+        if (match)
+            return match.id;
+        totalPages = Number(res.meta?.total_pages ?? 1);
+        page += 1;
+    } while (page <= totalPages);
+    throw new api_1.ApiRequestError(404, error_codes_1.ErrorCodes.Project.notFound, `Project not found: ${value}`);
+}
+/** Resolve an `{id, name}` reference by name (UUID passes through). */
+async function resolveNamedId(api, path, value, code, label) {
+    if (exports.UUID_RE.test(value))
+        return value;
+    const noun = label.toLowerCase();
+    const rows = await fetchLookupRows(api, path, `Listing the ${noun}s needs the permissions.manage permission — pass the ${noun} id instead of its name.`);
+    const match = rows.find((row) => (row.name ?? '').toLowerCase() === value.toLowerCase());
+    if (!match) {
+        throw new api_1.ApiRequestError(404, code, `${label} not found: ${value}`);
+    }
+    return match.id;
+}
+/**
+ * Every row of an organization lookup (teams, roles, groups, members) — all its pages.
+ *
+ * The server serves ten per page: stopping at the first made the eleventh team or the eleventh
+ * person invisible, and a perfectly good name or email came back as "not found" (CYCL-42, the
+ * lesson `resolveProjectId` already learned on project keys in CYCL-1).
+ *
+ * A 403 here is not about the command being run: listing teams needs `permissions.manage` and
+ * listing members `members.view`, permissions that a team workload board never asks for. Left
+ * alone it would read as "Permesso negato" on an operation the caller is entitled to, so the
+ * refusal carries the way out instead — name the id, skip the lookup.
+ */
+async function fetchLookupRows(api, path, hint) {
+    const rows = [];
+    let page = 1;
+    let totalPages = 1;
+    try {
+        do {
+            // eslint-disable-next-line no-await-in-loop
+            const res = await api.get(`${path}?page=${page}&per=100`);
+            rows.push(...(res.data ?? []));
+            totalPages = Number(res.meta?.total_pages ?? 1);
+            page += 1;
+        } while (page <= totalPages);
+    }
+    catch (error) {
+        if (error instanceof api_1.ApiRequestError && error.status === 403) {
+            throw new api_1.ApiRequestError(error.status, error.code, `${error.message}. ${hint}`);
+        }
+        throw error;
+    }
+    return rows;
+}

package/dist/lib/mcp/protocol.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Il livello JSON-RPC 2.0 del server MCP (CYCL-56).
+ *
+ * Sul trasporto stdio il Model Context Protocol non incapsula niente: un messaggio JSON per riga,
+ * senza a capo dentro, e nient'altro su standard output. Quello che entra arriva da un processo
+ * estraneo, quindi ogni forma sbagliata ha qui una risposta prevista: un server che cade sulla
+ * prima riga storta lascerebbe l'assistente senza conoscenza e senza spiegazione.
+ */
+export declare const JSONRPC_VERSION = "2.0";
+export type JsonRpcId = string | number;
+/** Una richiesta già ripulita: `id` assente vuol dire notifica, cioè nessuna risposta attesa. */
+export interface JsonRpcRequest {
+    id?: JsonRpcId;
+    method: string;
+    params: Record<string, unknown>;
+}
+export interface JsonRpcErrorBody {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export interface JsonRpcResponse {
+    jsonrpc: string;
+    id: JsonRpcId | null;
+    result?: unknown;
+    error?: JsonRpcErrorBody;
+}
+/** I codici standard di JSON-RPC 2.0, gli unici che il protocollo di base assegna. */
+export declare const RPC_ERROR: {
+    readonly parse: -32700;
+    readonly invalidRequest: -32600;
+    readonly methodNotFound: -32601;
+    readonly invalidParams: -32602;
+    readonly internal: -32603;
+};
+export declare function rpcResult(id: JsonRpcId | null, result: unknown): JsonRpcResponse;
+export declare function rpcFailure(id: JsonRpcId | null, code: number, message: string, data?: unknown): JsonRpcResponse;
+/**
+ * Cosa fare di una riga letta: servirla, rispedire un errore già pronto, o tacere.
+ * Il terzo caso non è un ripiego: a una riga vuota e a una risposta del client non si replica.
+ */
+export type ParsedLine = {
+    kind: 'request';
+    request: JsonRpcRequest;
+} | {
+    kind: 'response';
+    response: JsonRpcResponse;
+} | {
+    kind: 'ignore';
+};
+export declare function parseLine(line: string): ParsedLine;

package/dist/lib/mcp/protocol.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Il livello JSON-RPC 2.0 del server MCP (CYCL-56).
+ *
+ * Sul trasporto stdio il Model Context Protocol non incapsula niente: un messaggio JSON per riga,
+ * senza a capo dentro, e nient'altro su standard output. Quello che entra arriva da un processo
+ * estraneo, quindi ogni forma sbagliata ha qui una risposta prevista: un server che cade sulla
+ * prima riga storta lascerebbe l'assistente senza conoscenza e senza spiegazione.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RPC_ERROR = exports.JSONRPC_VERSION = void 0;
+exports.rpcResult = rpcResult;
+exports.rpcFailure = rpcFailure;
+exports.parseLine = parseLine;
+exports.JSONRPC_VERSION = '2.0';
+/** I codici standard di JSON-RPC 2.0, gli unici che il protocollo di base assegna. */
+exports.RPC_ERROR = {
+    parse: -32_700,
+    invalidRequest: -32_600,
+    methodNotFound: -32_601,
+    invalidParams: -32_602,
+    internal: -32_603,
+};
+function rpcResult(id, result) {
+    return { jsonrpc: exports.JSONRPC_VERSION, id, result };
+}
+function rpcFailure(id, code, message, data) {
+    return { jsonrpc: exports.JSONRPC_VERSION, id, error: { code, message, ...(data === undefined ? {} : { data }) } };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** L'id solo nella forma che JSON-RPC gli riconosce; `null` (come l'assenza) significa notifica. */
+function readId(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number')
+        return value;
+    return undefined;
+}
+function parseLine(line) {
+    const trimmed = line.trim();
+    if (trimmed === '')
+        return { kind: 'ignore' };
+    let message;
+    try {
+        message = JSON.parse(trimmed);
+    }
+    catch {
+        // Senza un messaggio leggibile non c'è nemmeno un id da citare: JSON-RPC prescrive `null`.
+        return { kind: 'response', response: rpcFailure(null, exports.RPC_ERROR.parse, 'Invalid JSON message') };
+    }
+    if (!isRecord(message)) {
+        return { kind: 'response', response: rpcFailure(null, exports.RPC_ERROR.invalidRequest, 'Expected a JSON-RPC object') };
+    }
+    // Una busta con `result`/`error` è la risposta del client a una nostra richiesta. Non ne mandiamo,
+    // ma se ne arrivasse una non va replicata: rispondere a una risposta è come si aprono i cicli.
+    if (message.method === undefined && ('result' in message || 'error' in message))
+        return { kind: 'ignore' };
+    const id = readId(message.id);
+    if (typeof message.method !== 'string' || message.method === '') {
+        return { kind: 'response', response: rpcFailure(id ?? null, exports.RPC_ERROR.invalidRequest, 'Missing method name') };
+    }
+    // I metodi MCP prendono solo parametri per nome: una lista posizionale non avrebbe dove finire.
+    const params = isRecord(message.params) ? message.params : {};
+    return { kind: 'request', request: { id, method: message.method, params } };
+}