@bussolabs/closeyourit-cli 0.25.1 → 0.27.0

package/dist/lib/api.d.ts

@@ -10,6 +10,13 @@ export interface RequestOptions {
     body?: unknown;
     /** Defaults to true; set false for unauthenticated endpoints. */
     auth?: boolean;
+    /**
+     * Abort the request when the caller cannot afford to wait (CYCL-55): `kb context` runs at the
+     * start of every session, where a stalled connection would be paid on each one. Without it fetch
+     * waits as long as the OS lets it. An aborted call surfaces as a network ApiRequestError, like
+     * any other unreachable server.
+     */
+    signal?: AbortSignal;
 }
 export interface Envelope<T = unknown> {
     data: T;
@@ -42,6 +49,15 @@ export declare class CliApi {
      * without a body is covered too. Reads never carry it: looking is not executing.
      */
     confirm: boolean;
+    /**
+     * Interrompe ogni richiesta che parte da questo client, quando è ora di chiudere (CYCL-56).
+     *
+     * Vive sull'istanza per la stessa ragione di `confirm`: il server MCP deve poter mollare TUTTE le
+     * chiamate in volo — quelle degli strumenti e quelle delle ricerche per nome che si portano
+     * dietro — senza infilare un parametro in ogni firma che sta in mezzo. Una `signal` passata alla
+     * singola richiesta (`RequestOptions`) resta più specifica e vince su questa.
+     */
+    signal?: AbortSignal;
     constructor(config: CliConfig);
     request<T = unknown>(method: HttpMethod, path: string, opts?: RequestOptions): Promise<Envelope<T>>;
     /**

package/dist/lib/api.js

@@ -36,6 +36,15 @@ class CliApi {
      * without a body is covered too. Reads never carry it: looking is not executing.
      */
     confirm = false;
+    /**
+     * Interrompe ogni richiesta che parte da questo client, quando è ora di chiudere (CYCL-56).
+     *
+     * Vive sull'istanza per la stessa ragione di `confirm`: il server MCP deve poter mollare TUTTE le
+     * chiamate in volo — quelle degli strumenti e quelle delle ricerche per nome che si portano
+     * dietro — senza infilare un parametro in ogni firma che sta in mezzo. Una `signal` passata alla
+     * singola richiesta (`RequestOptions`) resta più specifica e vince su questa.
+     */
+    signal;
     constructor(config) {
         this.config = config;
     }
@@ -49,6 +58,7 @@ class CliApi {
                 method,
                 headers,
                 body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+                signal: opts.signal ?? this.signal,
             });
         }
         catch (err) {
@@ -103,7 +113,17 @@ class CliApi {
     }
     /** Parse the response body and map the error envelope to an ApiRequestError. Shared by request() and upload(). */
     async handleResponse(res) {
-        const text = await res.text();
+        // The body can fail after the headers arrived: an abort that fires mid-read (RequestOptions.signal),
+        // a connection that drops. That is the same network failure as one on the first byte, so it must
+        // come out as an ApiRequestError — raw, it would escape every caller that maps failures by that
+        // type, and a command counting on a quiet failure would crash instead.
+        let text;
+        try {
+            text = await res.text();
+        }
+        catch (err) {
+            throw new ApiRequestError(0, error_codes_1.ErrorCodes.Network.requestFailed, `Reading the response failed: ${err.message}`);
+        }
         let json = {};
         if (text.length > 0) {
             try {

package/dist/lib/git.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `owner/name` out of a git remote URL, in both shapes git writes them:
+ *   git@github.com:bussolabs/closeyourit-cli.git
+ *   https://github.com/bussolabs/closeyourit-cli
+ *
+ * Only the last two path segments are kept, so a nested group (gitlab) still yields the pair the
+ * project→repository map is keyed by. Anything that is not a pair — a local path, an empty remote —
+ * returns undefined: the caller then simply has no project, which is a legitimate state (CYCL-55,
+ * scenario 2), not an error.
+ */
+export declare function parseRepoSlug(url: string): string | undefined;
+/**
+ * The `origin` remote of `cwd` as `owner/name`, or undefined when there is none to read: outside a
+ * repository, without an `origin`, or without git installed. Never throws and never waits long —
+ * this runs at the start of a session, where a hang would be felt on every single start.
+ */
+export declare function repoSlug(cwd: string, timeoutMs?: number): Promise<string | undefined>;

package/dist/lib/git.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRepoSlug = parseRepoSlug;
+exports.repoSlug = repoSlug;
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const run = (0, node_util_1.promisify)(node_child_process_1.execFile);
+/**
+ * `owner/name` out of a git remote URL, in both shapes git writes them:
+ *   git@github.com:bussolabs/closeyourit-cli.git
+ *   https://github.com/bussolabs/closeyourit-cli
+ *
+ * Only the last two path segments are kept, so a nested group (gitlab) still yields the pair the
+ * project→repository map is keyed by. Anything that is not a pair — a local path, an empty remote —
+ * returns undefined: the caller then simply has no project, which is a legitimate state (CYCL-55,
+ * scenario 2), not an error.
+ */
+function parseRepoSlug(url) {
+    const trimmed = url.trim();
+    if (trimmed === '')
+        return undefined;
+    // A repository cloned from disk (`file:///srv/git/acme/api.git`) has no owner: keeping its last
+    // two directories would invent a slug that could collide with a real `owner/name`.
+    if (/^file:\/\//i.test(trimmed))
+        return undefined;
+    // With a scheme the path starts after the host; the scp-like form has everything past the colon.
+    const marker = trimmed.indexOf('://');
+    const path = marker === -1
+        ? trimmed.slice(trimmed.indexOf(':') + 1)
+        : trimmed
+            .slice(marker + 3)
+            .split('/')
+            .slice(1)
+            .join('/');
+    if (marker === -1 && !trimmed.includes(':'))
+        return undefined;
+    const parts = path
+        .replace(/\.git$/i, '')
+        .split('/')
+        .filter((part) => part !== '');
+    return parts.length < 2 ? undefined : parts.slice(-2).join('/');
+}
+/**
+ * The `origin` remote of `cwd` as `owner/name`, or undefined when there is none to read: outside a
+ * repository, without an `origin`, or without git installed. Never throws and never waits long —
+ * this runs at the start of a session, where a hang would be felt on every single start.
+ */
+async function repoSlug(cwd, timeoutMs = 2000) {
+    try {
+        const { stdout } = await run('git', ['remote', 'get-url', 'origin'], { cwd, timeout: timeoutMs });
+        return parseRepoSlug(stdout);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/lib/knowledge-context.d.ts

@@ -0,0 +1,27 @@
+import { ApiRequestError, type CliApi, type Envelope, type RequestOptions } from './api';
+/**
+ * Does this failure mean the server has no such route? A 404 says so outright; a 500 only when the
+ * body was not an error envelope the backend wrote, which is how a missing route surfaces here.
+ */
+export declare function isMissingRoute(error: ApiRequestError): boolean;
+/**
+ * Ask for the project's knowledge context, falling back to its plain page list on a server that
+ * does not expose the context route yet (CYRA-767): the same short list, one call later, instead
+ * of a session start that reports a failure the reader can do nothing about.
+ *
+ * A 500 counts as "route missing" alongside 404, but only when the body was not a backend error
+ * envelope: the CLI asks for `Accept: application/json`, a server without the route renders its
+ * not-found page, has no JSON template for it, and fails — which arrives here as a plain
+ * `Network.requestFailed`. A 500 the backend narrated itself (`R500-…`) is a real fault of a route
+ * that exists, and retrying elsewhere would only replace its message with a more confusing one.
+ */
+export declare function fetchKnowledgeContext(api: CliApi, project: string, limit: number, opts?: RequestOptions): Promise<Envelope<unknown>>;
+/**
+ * The project of `cwd`, matched on its `origin` remote through the project → repository map the
+ * backend already publishes (`projects github-map`).
+ *
+ * The remote was preferred over a local configuration file: it is already written in every
+ * repository, so nothing new has to be created, kept in sync, or forgotten in a fresh clone.
+ * No remote, no match, no repository at all → undefined, and the caller shows nothing.
+ */
+export declare function projectFromGitRemote(api: CliApi, cwd: string, timeoutMs: number, opts?: RequestOptions): Promise<string | undefined>;

package/dist/lib/knowledge-context.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMissingRoute = isMissingRoute;
+exports.fetchKnowledgeContext = fetchKnowledgeContext;
+exports.projectFromGitRemote = projectFromGitRemote;
+const api_1 = require("./api");
+const error_codes_1 = require("../errors/error-codes");
+const git_1 = require("./git");
+const knowledge_1 = require("./knowledge");
+/**
+ * Does this failure mean the server has no such route? A 404 says so outright; a 500 only when the
+ * body was not an error envelope the backend wrote, which is how a missing route surfaces here.
+ */
+function isMissingRoute(error) {
+    if (error.status === 404)
+        return true;
+    return error.status === 500 && error.code === error_codes_1.ErrorCodes.Network.requestFailed;
+}
+/**
+ * Ask for the project's knowledge context, falling back to its plain page list on a server that
+ * does not expose the context route yet (CYRA-767): the same short list, one call later, instead
+ * of a session start that reports a failure the reader can do nothing about.
+ *
+ * A 500 counts as "route missing" alongside 404, but only when the body was not a backend error
+ * envelope: the CLI asks for `Accept: application/json`, a server without the route renders its
+ * not-found page, has no JSON template for it, and fails — which arrives here as a plain
+ * `Network.requestFailed`. A 500 the backend narrated itself (`R500-…`) is a real fault of a route
+ * that exists, and retrying elsewhere would only replace its message with a more confusing one.
+ */
+async function fetchKnowledgeContext(api, project, limit, opts = {}) {
+    const query = new URLSearchParams({ project, per: String(limit) });
+    try {
+        return await api.get(`/cli/v1/knowledge/context?${query.toString()}`, opts);
+    }
+    catch (error) {
+        if (!(error instanceof api_1.ApiRequestError) || !isMissingRoute(error))
+            throw error;
+        const pages = (0, knowledge_1.buildPagesQuery)({ kinds: [], page: 1, per: limit, project });
+        return api.get(`/cli/v1/knowledge/pages?${pages}`, opts);
+    }
+}
+/**
+ * The project of `cwd`, matched on its `origin` remote through the project → repository map the
+ * backend already publishes (`projects github-map`).
+ *
+ * The remote was preferred over a local configuration file: it is already written in every
+ * repository, so nothing new has to be created, kept in sync, or forgotten in a fresh clone.
+ * No remote, no match, no repository at all → undefined, and the caller shows nothing.
+ */
+async function projectFromGitRemote(api, cwd, timeoutMs, opts = {}) {
+    const slug = await (0, git_1.repoSlug)(cwd, timeoutMs);
+    if (slug === undefined)
+        return undefined;
+    const wanted = slug.toLowerCase();
+    let page = 1;
+    let totalPages = 1;
+    do {
+        const query = new URLSearchParams({ page: String(page), per: '100', connected_only: 'true' });
+        // eslint-disable-next-line no-await-in-loop
+        const res = await api.get(`/cli/v1/projects/github-map?${query.toString()}`, opts);
+        const match = (res.data ?? []).find((row) => (row.repository?.full_name ?? '').toLowerCase() === wanted);
+        if (match)
+            return match.project_key ?? match.project_id;
+        totalPages = Number(res.meta?.total_pages ?? 1);
+        page += 1;
+    } while (page <= totalPages);
+    return undefined;
+}

package/dist/lib/knowledge-doctor.d.ts

@@ -0,0 +1,127 @@
+import type { CliApi } from './api';
+/**
+ * Il controllo di salute della conoscenza (`cyi kb doctor`, CYCL-57).
+ *
+ * Le verifiche girano QUI, sul client, sopra l'elenco delle pagine che il servizio già espone: è
+ * lo stesso canale su cui gira oggi lo script di audit tenuto fuori dal prodotto
+ * (`knowledge-base/scripts/audit_closeyourit_kb.rb`, che chiama `cyi kb list --status all --json`),
+ * e portarlo dentro il comando è tutto il punto del ticket — un controllo che nessuno lancia non
+ * accorge nessuno di niente. Il controllo del file versionato, poi, può girare solo da questa
+ * parte: il repo dei documenti sta sul disco di chi lavora, il servizio non lo vede.
+ *
+ * Nessuna verifica scrive: il modulo legge pagine e restituisce un referto. La riparazione resta
+ * un gesto esplicito di chi legge, ed è per questo che ogni verifica porta con sé il comando da
+ * dare — non lo esegue.
+ */
+/** Esito di una verifica. Le stringhe sono quelle che `statusDot` sa già colorare. */
+export type DoctorCheckStatus = 'fail' | 'ok' | 'skipped' | 'warning';
+/** Una pagina segnalata da una verifica: id e titolo per ritrovarla, `detail` per il perché. */
+export interface DoctorFinding {
+    id: string;
+    title: string;
+    detail?: string;
+}
+/** Il referto di una singola verifica: cosa guarda, com'è andata, cosa fare adesso. */
+export interface DoctorCheck {
+    code: string;
+    status: DoctorCheckStatus;
+    count: number;
+    summary: string;
+    next_step: string;
+    pages: DoctorFinding[];
+}
+/** Una pagina come la serializza il servizio (KnowledgePageSerializer), per quel che serve qui. */
+export interface DoctorPage extends Record<string, unknown> {
+    id?: unknown;
+    title?: unknown;
+    body?: unknown;
+    status?: unknown;
+    projects?: unknown;
+    groups?: unknown;
+    source_path?: unknown;
+    consolidated_at?: unknown;
+    updated_at?: unknown;
+    created_at?: unknown;
+}
+/** Il referto completo, nella forma che finisce sia a schermo sia in `--json`. */
+export interface DoctorReport {
+    scanned: number;
+    truncated: boolean;
+    stale_days: number;
+    checks: DoctorCheck[];
+}
+/**
+ * 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.
+ */
+export declare const DOCTOR_CHECK_CODES: readonly ["empty-body", "orphan-scope", "duplicate-title", "dangling-link", "stale-review", "stale-consolidation", "inconsistent-consolidation", "missing-source-file"];
+/**
+ * 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.
+ */
+export declare function titleKey(value: unknown): string;
+/**
+ * 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).
+ */
+export declare function stripCode(markdown: string): string;
+/**
+ * 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.
+ */
+export declare function wikilinkTitles(body: unknown): string[];
+export interface DoctorInput {
+    /** Le pagine visibili, in ogni stato. */
+    pages: DoctorPage[];
+    /** Le accettate non ancora archiviate, come le elenca il servizio (scope `awaiting_consolidation`). */
+    awaitingConsolidation: DoctorPage[];
+    /** Da quanti giorni una coda ferma va segnalata. */
+    staleDays: number;
+    now: Date;
+    /** La radice del repo dei documenti versionati; assente → il controllo del file non si fa. */
+    docsRoot?: string;
+    /** Come si guarda se un file c'è. Iniettabile perché le verifiche restino pure e testabili. */
+    fileExists?: (path: string) => boolean;
+    /**
+     * L'elenco letto è quello di UN progetto. Il servizio però risolve i wikilink e l'unicità dei
+     * titoli su TUTTA l'organizzazione (Knowledge::Links::Sync), quindi da un elenco ristretto quelle
+     * due verifiche direbbero il falso in entrambi i versi: collegamenti sani segnalati come appesi
+     * perché la destinazione sta in un altro progetto, e doppioni cross-progetto mai visti.
+     */
+    scopedToProject?: boolean;
+}
+/**
+ * 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.
+ */
+export declare function runDoctorChecks(input: DoctorInput): DoctorCheck[];
+/** Quante verifiche sono fallite e quante hanno solo avvisato. */
+export declare function doctorTotals(checks: DoctorCheck[]): {
+    failures: number;
+    warnings: number;
+};
+/**
+ * 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.
+ */
+export declare function renderDoctorReport(report: DoctorReport): string;
+/**
+ * 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.
+ */
+export declare function fetchDoctorPages(api: CliApi, opts: {
+    limit: number;
+    project?: string;
+    awaitingConsolidation?: boolean;
+}): Promise<{
+    pages: DoctorPage[];
+    truncated: boolean;
+}>;