@vascend/talos 0.1.0

package/dist/tools/ramification-tools.js

@@ -0,0 +1,528 @@
+import { resolveKingdomBus } from "../vascend/kingdom-channel.js";
+import { RamificationStore } from "../vascend/ramification-store.js";
+import { teamForSession } from "../vascend/team-session.js";
+import { addBranch, addNode, consultOnNode, crosstalkFor, frontier, judgeNode, postAcrossNodes, progress, proposeMutation, renderCrosstalk, resolveProposal, startNode, submitNode, } from "../vascend/ramification.js";
+// I tool della ramificazione: come un team fa un piano lungo e lo porta avanti
+// nodo per nodo, dove ogni nodo e' una sessione intera di lavoro.
+//
+// Il piano vive nella CONVERSAZIONE, non nella sessione: e' l'unico modo perche'
+// il nodo 40 sappia cosa e' stato deciso al nodo 3, in una sessione che allora
+// non esisteva.
+function conversationScope(ctx) {
+    // In una sessione delegata il piano resta quello della conversazione madre:
+    // altrimenti ogni collaboratore aprirebbe un piano suo e la ramificazione si
+    // sfarinerebbe in tanti alberi scollegati.
+    return String(ctx.planStoreId || ctx.roomStoreId || ctx.sessionId || "default");
+}
+function openStore(ctx) {
+    if (!ctx.sessionDir)
+        return null;
+    return RamificationStore.open(ctx.sessionDir, conversationScope(ctx));
+}
+// Chi sta parlando. Dentro una sessione delegata e' lo slug del collaboratore,
+// altrimenti e' l'agente principale.
+function speaker(ctx) {
+    return String(ctx.kingdom?.self || "orchestratore");
+}
+function text(input, key) {
+    const value = input[key];
+    return typeof value === "string" ? value.trim() : "";
+}
+function strings(input, key) {
+    const value = input[key];
+    if (!Array.isArray(value))
+        return [];
+    return value.map((item) => String(item ?? "").trim()).filter(Boolean);
+}
+function noStore() {
+    return "piano a rami non disponibile: manca una sessione persistente";
+}
+/* Riga di stato del nodo, in coda alla risposta. La legge l'utente in chat, e
+   la legge l'host per aggiornare la board: senza il RAMO un aggiornamento non
+   si puo' agganciare a niente, perche' i passaggi vivono dentro il loro ramo. */
+function segnaleNodo(node, stato, extra) {
+    return `[nodo] ${node.id} · ramo ${node.branch} · ${stato}${extra ? ` · ${extra}` : ""}`;
+}
+function renderStatus(roadmap) {
+    const righe = [`obiettivo: ${roadmap.goal}`];
+    if (roadmap.acceptance.length)
+        righe.push(`accettazione: ${roadmap.acceptance.join(" · ")}`);
+    for (const riga of progress(roadmap)) {
+        righe.push(`ramo ${riga.branch} (${riga.owner}): ${riga.committed}/${riga.total} approvati`
+            + (riga.current ? `, ora ${riga.current}` : "")
+            + (riga.blocked.length ? `, bloccati ${riga.blocked.join(", ")}` : ""));
+    }
+    const prendibili = frontier(roadmap);
+    // I nodi prendibili sono INDIPENDENTI fra loro: possono partire tutti adesso,
+    // ognuno nella sua sessione. Metterli in fila e' lavoro perso.
+    righe.push(prendibili.length
+        ? `prendibili adesso (indipendenti, possono partire in contemporanea): ${prendibili.map((n) => n.id).join(", ")}`
+        : "niente di prendibile: o e' tutto in corso, o aspetta un giudizio");
+    const inAttesa = roadmap.proposals.filter((p) => p.state === "pending");
+    if (inAttesa.length) {
+        righe.push(`proposte in attesa: ${inAttesa.map((p) => `${p.id} (${p.by}) ${p.reason}`).join(" | ")}`);
+    }
+    return righe.join("\n");
+}
+/* Il percorso si disegna INSIEME. Se hai una squadra ingaggiata e non le hai
+   ancora rivolto la parola, un piano scritto da solo non e' il piano del team:
+   e' un compito consegnato. Chi lavora su un pezzo sa cose che tu non sai —
+   e' il motivo per cui l'hai ingaggiato — e quelle cose cambiano il percorso,
+   non il modo di eseguirlo. Quindi qui si controlla che ci si sia parlati:
+   almeno una tua parola e almeno una loro risposta. */
+function teamNonSentita(ctx) {
+    const team = teamForSession(String(ctx.sessionId || ""));
+    if (!team || !team.members.length)
+        return "";
+    const io = String(ctx.kingdom?.self || "orchestratore");
+    const storia = resolveKingdomBus(process.env, ctx.sessionDir).history(team.id);
+    const hoParlato = storia.some((m) => m.from === io);
+    const hannoRisposto = storia.some((m) => m.from !== io);
+    if (hoParlato && hannoRisposto)
+        return "";
+    const chi = team.members.map((m) => m.slug).join(", ");
+    return `hai ingaggiato ${chi} ma `
+        + (!hoParlato
+            ? "non gli hai ancora detto niente. "
+            : "non hai ancora sentito cosa ne pensano. ")
+        + "Il percorso lo disegnate insieme: raccontagli la situazione con team_say, "
+        + "senti il loro parere (team_wait), e solo dopo scrivi i rami. Chi lavorera' su un pezzo "
+        + "sa cose che tu non sai — e' il motivo per cui l'hai chiamato.";
+}
+// ram_plan: il team stila il percorso. Rami e nodi in una chiamata sola, perche'
+// e' cosi' che si progetta — guardando l'insieme, non un nodo per volta.
+export const ramPlanTool = {
+    name: "ram_plan",
+    description: "Il PERCORSO di un lavoro che non si chiude in una conversazione: rami e nodi, un livello SOPRA i "
+        + "passaggi. Ogni ramo ha un titolare e una visione (il metro con cui giudichera' i suoi nodi); ogni "
+        + "nodo e' una sessione intera di lavoro, e un nodo si sblocca solo quando i suoi prerequisiti sono "
+        + "stati APPROVATI, non quando sono finiti. Qui NON si scrivono i passaggi: dentro un nodo li pianifica "
+        + "con vascend_plan la sessione che lo esegue, che e' l'unica a sapere come farlo. Un mandato dice cosa "
+        + "deve essere vero alla fine, non come arrivarci.",
+    schema: {
+        type: "object",
+        properties: {
+            goal: { type: "string", description: "l'obiettivo lungo, in una frase" },
+            acceptance: { type: "array", items: { type: "string" }, description: "criteri di accettazione finali, verificabili" },
+            founders: { type: "array", items: { type: "string" }, description: "chi puo' riscrivere il futuro dei rami (default: chi chiama)" },
+            branches: {
+                type: "array",
+                description: "i rami del piano",
+                items: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string", description: "id breve del ramo, es. prodotto" },
+                        owner: { type: "string", description: "chi lo porta avanti e ne giudica i nodi" },
+                        vision: { type: "string", description: "cosa deve essere vero perche' il ramo sia riuscito" },
+                    },
+                    required: ["id", "vision"],
+                },
+            },
+            nodes: {
+                type: "array",
+                description: "i nodi, in ordine; ognuno e' una sessione di lavoro",
+                items: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string", description: "id del nodo, es. N01" },
+                        branch: { type: "string", description: "ramo di appartenenza" },
+                        title: { type: "string" },
+                        mandate: { type: "string", description: "cosa deve essere VERO alla fine del nodo; non i passaggi per arrivarci" },
+                        acceptance: { type: "array", items: { type: "string" }, description: "criteri verificabili del nodo" },
+                        after: { type: "array", items: { type: "string" }, description: "nodi che devono essere approvati prima" },
+                    },
+                    required: ["id", "branch", "mandate"],
+                },
+            },
+        },
+        required: ["goal"],
+    },
+    handler: async (input, ctx) => {
+        const store = openStore(ctx);
+        if (!store)
+            return noStore();
+        const now = Date.now();
+        const chi = speaker(ctx);
+        if (!store.has()) {
+            // Solo alla CREAZIONE: aggiungere un ramo a un percorso gia' aperto e'
+            // un'altra cosa, e passa comunque dalle proposte.
+            const muti = teamNonSentita(ctx);
+            if (muti)
+                return muti;
+            const founders = strings(input, "founders");
+            const creato = store.create({
+                goal: text(input, "goal"),
+                acceptance: strings(input, "acceptance"),
+                founders: founders.length ? founders : [chi],
+                at: now,
+            });
+            if (!creato.ok)
+                return creato.reason;
+        }
+        const rami = Array.isArray(input["branches"]) ? input["branches"] : [];
+        for (const ramo of rami) {
+            const esito = store.apply((roadmap) => addBranch(roadmap, {
+                id: String(ramo["id"] ?? ""),
+                owner: String(ramo["owner"] ?? chi),
+                vision: String(ramo["vision"] ?? ""),
+                at: now,
+            }));
+            if (!esito.ok)
+                return `ramo ${String(ramo["id"] ?? "")}: ${esito.reason}`;
+        }
+        const nodi = Array.isArray(input["nodes"]) ? input["nodes"] : [];
+        for (const nodo of nodi) {
+            const esito = store.apply((roadmap) => addNode(roadmap, {
+                id: String(nodo["id"] ?? ""),
+                branch: String(nodo["branch"] ?? ""),
+                title: String(nodo["title"] ?? ""),
+                mandate: String(nodo["mandate"] ?? ""),
+                acceptance: Array.isArray(nodo["acceptance"]) ? nodo["acceptance"].map(String) : [],
+                after: Array.isArray(nodo["after"]) ? nodo["after"].map(String) : [],
+                by: chi,
+                at: now,
+            }));
+            if (!esito.ok)
+                return `nodo ${String(nodo["id"] ?? "")}: ${esito.reason}`;
+        }
+        const roadmap = store.current();
+        return roadmap ? renderStatus(roadmap) : noStore();
+    },
+};
+// ram_status: dove siamo. E' la prima cosa che una sessione nuova deve chiedere.
+export const ramStatusTool = {
+    name: "ram_status",
+    description: "Dove e' arrivato il piano a rami: cosa e' approvato, cosa e' in corso, cosa e' bloccato e da cosa, "
+        + "quali nodi sono PRENDIBILI adesso. Chiamalo all'inizio di una sessione che continua un lavoro lungo: "
+        + "si riparte dalla frontiera, non dal principio.",
+    schema: { type: "object", properties: {} },
+    handler: async (_input, ctx) => {
+        const store = openStore(ctx);
+        if (!store)
+            return noStore();
+        const roadmap = store.current();
+        if (!roadmap)
+            return "nessun piano a rami per questa conversazione";
+        return renderStatus(roadmap);
+    },
+};
+// ram_take: questa sessione prende un nodo. Un nodo e' una sessione: qui si
+// dichiara quale.
+export const ramTakeTool = {
+    name: "ram_take",
+    description: "Prendi un nodo prendibile: da qui in avanti questa sessione E' quel nodo. Ritorna il mandato e i "
+        + "criteri di accettazione. Un nodo bloccato viene rifiutato dicendo cosa manca.",
+    schema: {
+        type: "object",
+        properties: { node: { type: "string", description: "id del nodo" } },
+        required: ["node"],
+    },
+    handler: async (input, ctx) => {
+        const store = openStore(ctx);
+        if (!store)
+            return noStore();
+        const id = text(input, "node");
+        const esito = store.apply((roadmap) => startNode(roadmap, {
+            id,
+            sessionId: String(ctx.sessionId || ""),
+            by: speaker(ctx),
+            at: Date.now(),
+        }));
+        if (!esito.ok)
+            return esito.reason;
+        const node = esito.roadmap?.nodes[id];
+        const branch = esito.roadmap?.branches.find((b) => b.id === node?.branch);
+        if (!node)
+            return esito.reason || "nodo preso";
+        return [
+            `preso ${node.id} (${node.branch})`,
+            `mandato: ${node.mandate}`,
+            branch ? `visione del ramo: ${branch.vision}` : "",
+            node.acceptance.length ? `accettazione: ${node.acceptance.join(" · ")}` : "",
+            "Adesso pianifica i TUOI passaggi con vascend_plan (compaiono sulla board) e lavora: il percorso a "
+                + "rami non si tocca da qui. Quando hai finito consegna con ram_submit — senza artefatto e senza "
+                + "prove non e' una consegna.",
+            segnaleNodo(node, "in corso", `sessione ${String(ctx.sessionId || "")}`),
+        ].filter(Boolean).join("\n");
+    },
+};
+export const ramSubmitTool = {
+    name: "ram_submit",
+    description: "Consegna il nodo che questa sessione sta eseguendo: cosa hai prodotto, cosa hai verificato e come, "
+        + "e il commit che lo fissa. La consegna NON sblocca i nodi successivi: li sblocca il giudizio di chi "
+        + "possiede il ramo.",
+    schema: {
+        type: "object",
+        properties: {
+            node: { type: "string", description: "id del nodo" },
+            artifact: { type: "string", description: "cosa hai prodotto (percorso, componente, documento)" },
+            tests: { type: "array", items: { type: "string" }, description: "prove eseguite" },
+            evidence: { type: "array", items: { type: "string" }, description: "cosa hai osservato che lo dimostra" },
+            commit: { type: "string", description: "commit o marcatore che fissa il lavoro" },
+        },
+        required: ["node", "artifact", "evidence"],
+    },
+    handler: async (input, ctx) => {
+        const store = openStore(ctx);
+        if (!store)
+            return noStore();
+        const now = Date.now();
+        const esito = store.apply((roadmap) => submitNode(roadmap, {
+            id: text(input, "node"),
+            transaction: {
+                artifact: text(input, "artifact"),
+                tests: strings(input, "tests"),
+                evidence: strings(input, "evidence"),
+                commit: text(input, "commit"),
+                at: now,
+            },
+            by: speaker(ctx),
+            at: now,
+        }));
+        if (!esito.ok)
+            return esito.reason;
+        const consegnato = esito.roadmap?.nodes[text(input, "node")];
+        return [
+            `${text(input, "node")} consegnato, in attesa di giudizio`,
+            consegnato ? segnaleNodo(consegnato, "consegnato") : "",
+        ].filter(Boolean).join(String.fromCharCode(10));
+    },
+};
+// ram_ask: si chiede prima di giudicare. La risposta arriva parlando.
+export const ramAskTool = {
+    name: "ram_ask",
+    description: "Chiedi a qualcuno un parere su un nodo consegnato, prima di giudicarlo: a chi lo ha fatto, o a chi "
+        + "conosce il pezzo che tocca. Resta la traccia della domanda; la risposta arriva parlando.",
+    schema: {
+        type: "object",
+        properties: {
+            node: { type: "string", description: "id del nodo" },
+            who: { type: "string", description: "a chi lo chiedi" },
+            question: { type: "string", description: "la domanda" },
+        },
+        required: ["node", "who", "question"],
+    },
+    handler: async (input, ctx) => {
+        const store = openStore(ctx);
+        if (!store)
+            return noStore();
+        const esito = store.apply((roadmap) => consultOnNode(roadmap, {
+            id: text(input, "node"),
+            who: text(input, "who"),
+            question: text(input, "question"),
+            by: speaker(ctx),
+            at: Date.now(),
+        }));
+        return esito.ok ? `chiesto a ${text(input, "who")} su ${text(input, "node")}` : esito.reason;
+    },
+};
+export const ramJudgeTool = {
+    name: "ram_judge",
+    description: "Il cancello: giudica un nodo consegnato rispetto alla visione del ramo e ai criteri del nodo. "
+        + "`pass` sblocca i nodi che dipendevano da lui; `return` lo rimanda indietro con le ragioni; "
+        + "`replan` dice che il lavoro ha scoperto qualcosa che rende sbagliato il seguito — allora si propone "
+        + "una riscrittura con ram_propose. Giudica chi possiede il ramo.",
+    schema: {
+        type: "object",
+        properties: {
+            node: { type: "string", description: "id del nodo" },
+            decision: { type: "string", enum: ["pass", "return", "replan"], description: "l'esito" },
+            reason: { type: "string", description: "il perche' (obbligatorio se non e' pass)" },
+            consulted: { type: "array", items: { type: "string" }, description: "con chi ne hai parlato" },
+        },
+        required: ["node", "decision"],
+    },
+    handler: async (input, ctx) => {
+        const store = openStore(ctx);
+        if (!store)
+            return noStore();
+        const decision = text(input, "decision");
+        if (!["pass", "return", "replan"].includes(decision))
+            return "decisione non valida: pass, return o replan";
+        const esito = store.apply((roadmap) => judgeNode(roadmap, {
+            id: text(input, "node"),
+            decision,
+            reason: text(input, "reason"),
+            consulted: strings(input, "consulted"),
+            by: speaker(ctx),
+            at: Date.now(),
+        }));
+        if (!esito.ok)
+            return esito.reason;
+        if (!esito.roadmap)
+            return "giudicato";
+        const giudicato = esito.roadmap.nodes[text(input, "node")];
+        const stato = decision === "pass" ? "approvato" : decision === "return" ? "rimandato indietro" : "da ripianificare";
+        return [
+            renderStatus(esito.roadmap),
+            giudicato ? segnaleNodo(giudicato, stato, text(input, "reason")) : "",
+        ].filter(Boolean).join(String.fromCharCode(10));
+    },
+};
+export const ramProposeTool = {
+    name: "ram_propose",
+    description: "Proponi di riscrivere il FUTURO di un ramo, quando il lavoro ha scoperto un limite che il seguito "
+        + "del piano dava per risolto. Non lo applichi: lo proponi, con il motivo, e decide il team che ha "
+        + "aperto la ramificazione. I nodi gia' approvati non si toccano.",
+    schema: {
+        type: "object",
+        properties: {
+            id: { type: "string", description: "id della proposta, es. P1" },
+            branch: { type: "string", description: "ramo interessato" },
+            reason: { type: "string", description: "il limite che l'ha causata" },
+            add: {
+                type: "array",
+                description: "nodi da aggiungere",
+                items: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string" },
+                        branch: { type: "string" },
+                        title: { type: "string" },
+                        mandate: { type: "string" },
+                        acceptance: { type: "array", items: { type: "string" } },
+                        after: { type: "array", items: { type: "string" } },
+                    },
+                    required: ["id", "branch", "mandate"],
+                },
+            },
+            drop: { type: "array", items: { type: "string" }, description: "nodi non ancora consegnati da togliere" },
+            retarget: {
+                type: "array",
+                description: "nodi da riscrivere (mandato, criteri, prerequisiti)",
+                items: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string" },
+                        mandate: { type: "string" },
+                        acceptance: { type: "array", items: { type: "string" } },
+                        after: { type: "array", items: { type: "string" } },
+                    },
+                    required: ["id"],
+                },
+            },
+        },
+        required: ["id", "reason"],
+    },
+    handler: async (input, ctx) => {
+        const store = openStore(ctx);
+        if (!store)
+            return noStore();
+        const mutation = {
+            ...(Array.isArray(input["add"]) ? { add: input["add"] } : {}),
+            ...(Array.isArray(input["drop"]) ? { drop: strings(input, "drop") } : {}),
+            ...(Array.isArray(input["retarget"]) ? { retarget: input["retarget"] } : {}),
+        };
+        const esito = store.apply((roadmap) => proposeMutation(roadmap, {
+            id: text(input, "id"),
+            branch: text(input, "branch"),
+            mutation,
+            reason: text(input, "reason"),
+            by: speaker(ctx),
+            at: Date.now(),
+        }));
+        return esito.ok
+            ? `proposta ${text(input, "id")} in attesa: decide il team che ha aperto la ramificazione`
+            : esito.reason;
+    },
+};
+export const ramDecideTool = {
+    name: "ram_decide",
+    description: "Decidi su una proposta di riscrittura: accettata, il futuro del ramo cambia adesso; rifiutata, "
+        + "servono le ragioni. Decide solo il team che ha aperto la ramificazione.",
+    schema: {
+        type: "object",
+        properties: {
+            id: { type: "string", description: "id della proposta" },
+            accept: { type: "boolean", description: "true accetta, false rifiuta" },
+            reason: { type: "string", description: "il perche'" },
+        },
+        required: ["id", "accept"],
+    },
+    handler: async (input, ctx) => {
+        const store = openStore(ctx);
+        if (!store)
+            return noStore();
+        const esito = store.apply((roadmap) => resolveProposal(roadmap, {
+            id: text(input, "id"),
+            accept: input["accept"] === true,
+            reason: text(input, "reason"),
+            by: speaker(ctx),
+            at: Date.now(),
+        }));
+        if (!esito.ok)
+            return esito.reason;
+        return esito.roadmap ? renderStatus(esito.roadmap) : "deciso";
+    },
+};
+// ram_tell / ram_hear: il canale fra NODI, cioe' fra sessioni diverse. Distinto
+// dai messaggi fra agenti della stessa stanza, e marcato come tale.
+export const ramTellTool = {
+    name: "ram_tell",
+    description: "Scrivi a un altro nodo del piano, cioe' a un'ALTRA sessione. Usalo quando scopri qualcosa che "
+        + "riguarda il lavoro di un altro ramo. Chi legge vedra' che arriva da un'altra sessione, con nodo, "
+        + "ramo e sessione di provenienza: non e' un collega della sua attivita. Ometti `to` per dirlo a tutti.",
+    schema: {
+        type: "object",
+        properties: {
+            from: { type: "string", description: "il nodo da cui scrivi (quello che questa sessione sta eseguendo)" },
+            to: { type: "string", description: "nodo o ramo destinatario; ometti per tutti" },
+            text: { type: "string", description: "il messaggio" },
+        },
+        required: ["from", "text"],
+    },
+    handler: async (input, ctx) => {
+        const store = openStore(ctx);
+        if (!store)
+            return noStore();
+        const esito = store.apply((roadmap) => postAcrossNodes(roadmap, {
+            fromNode: text(input, "from"),
+            who: speaker(ctx),
+            to: text(input, "to"),
+            text: text(input, "text"),
+            at: Date.now(),
+        }));
+        return esito.ok ? "inviato" : esito.reason;
+    },
+};
+export const ramHearTool = {
+    name: "ram_hear",
+    description: "Leggi cosa ti hanno scritto le ALTRE sessioni del piano. Ogni riga dice da quale nodo, ramo e "
+        + "sessione arriva. Controllalo prima di dare per buono qualcosa che un altro ramo potrebbe aver "
+        + "smentito.",
+    schema: {
+        type: "object",
+        properties: {
+            node: { type: "string", description: "il nodo che questa sessione sta eseguendo" },
+            since: { type: "number", description: "leggi solo dopo questo numero di sequenza" },
+        },
+        required: ["node"],
+    },
+    handler: async (input, ctx) => {
+        const store = openStore(ctx);
+        if (!store)
+            return noStore();
+        const roadmap = store.current();
+        if (!roadmap)
+            return "nessun piano a rami per questa conversazione";
+        const messaggi = crosstalkFor(roadmap, {
+            node: text(input, "node"),
+            since: Number(input["since"]) || 0,
+        });
+        if (!messaggi.length)
+            return "niente dalle altre sessioni";
+        return messaggi.map((m) => `${m.seq}. ${renderCrosstalk(m)}`).join("\n");
+    },
+};
+export const ramificationTools = [
+    ramPlanTool,
+    ramStatusTool,
+    ramTakeTool,
+    ramSubmitTool,
+    ramAskTool,
+    ramJudgeTool,
+    ramProposeTool,
+    ramDecideTool,
+    ramTellTool,
+    ramHearTool,
+];

package/dist/tools/regex-compat.d.ts

@@ -0,0 +1,9 @@
+export interface CompiledPattern {
+    readonly regex: RegExp;
+    readonly notes: readonly string[];
+}
+export declare class PatternError extends Error {
+}
+export declare function compileSearchPattern(pattern: string, opts?: {
+    readonly ignoreCase?: boolean;
+}): CompiledPattern;

package/dist/tools/regex-compat.js

@@ -0,0 +1,96 @@
+// Compatibilita' fra le regex che i modelli SCRIVONO e quelle che JavaScript
+// ESEGUE.
+//
+// I modelli producono pattern in stile ripgrep/Rust/Python, perche' e' quello
+// che vedono ovunque: `(?i)password`, `(?P<name>...)`, `\A...\z`. Il motore di
+// JavaScript non conosce nessuna di queste forme e solleva
+// "Invalid regular expression: unrecognized character after (?", quindi la
+// ricerca falliva del tutto e l'agente perdeva un giro a indovinare perche'.
+//
+// Qui traduciamo le forme equivalenti e lasciamo fallire solo cio' che davvero
+// non ha corrispondenza. Modulo PURO, nessuna dipendenza.
+export class PatternError extends Error {
+}
+// Flag inline supportate (stessa lettera in JS). `x` (extended) e `U`
+// (ungreedy) non hanno equivalente e vengono dichiarate non supportate.
+const INLINE_FLAGS = new Set(["i", "m", "s"]);
+// Legge i gruppi di flag inline in TESTA al pattern: (?i), (?im), (?i-s), uno
+// dopo l'altro. Ritorna le flag attive e il resto del pattern.
+function takeLeadingFlags(pattern) {
+    const flags = new Set();
+    const unsupported = new Set();
+    let rest = pattern;
+    for (;;) {
+        const match = /^\(\?([a-zA-Z]*)(?:-([a-zA-Z]+))?\)/.exec(rest);
+        if (!match)
+            break;
+        const on = match[1] ?? "";
+        const off = match[2] ?? "";
+        // `(?)` non e' un gruppo di flag valido: lascialo al motore.
+        if (!on && !off)
+            break;
+        for (const flag of on) {
+            if (INLINE_FLAGS.has(flag))
+                flags.add(flag);
+            else
+                unsupported.add(flag);
+        }
+        for (const flag of off)
+            flags.delete(flag);
+        rest = rest.slice(match[0].length);
+    }
+    return { flags, rest, unsupported };
+}
+// Traduzioni testuali sicure verso la sintassi JavaScript.
+function translateBody(pattern) {
+    const notes = [];
+    let body = pattern;
+    // Gruppi con nome in stile Python/Rust: (?P<x>...) -> (?<x>...)
+    if (/\(\?P</.test(body)) {
+        body = body.replace(/\(\?P</g, "(?<");
+        notes.push("gruppi (?P<nome>) tradotti in (?<nome>)");
+    }
+    // Ancore Rust: \A inizio testo, \z / \Z fine testo.
+    if (/\\A/.test(body)) {
+        body = body.replace(/\\A/g, "^");
+        notes.push("\\A tradotto in ^");
+    }
+    if (/\\[zZ]/.test(body)) {
+        body = body.replace(/\\[zZ]/g, "$");
+        notes.push("\\z tradotto in $");
+    }
+    return { body, notes };
+}
+// Compila un pattern di ricerca. `ignoreCase` e' la richiesta esplicita del
+// chiamante (parametro del tool); le flag inline si sommano a quella.
+export function compileSearchPattern(pattern, opts = {}) {
+    if (!pattern)
+        throw new PatternError("pattern vuoto");
+    const notes = [];
+    const leading = takeLeadingFlags(pattern);
+    if (leading.unsupported.size) {
+        throw new PatternError(`flag inline non supportate in JavaScript: (?${[...leading.unsupported].join("")}). `
+            + "Usa i parametri del tool (ignore_case) o riscrivi il pattern.");
+    }
+    const flags = new Set(leading.flags);
+    if (opts.ignoreCase)
+        flags.add("i");
+    if (leading.flags.size) {
+        notes.push(`flag inline (?${[...leading.flags].join("")}) applicate come flag del motore`);
+    }
+    const translated = translateBody(leading.rest);
+    notes.push(...translated.notes);
+    // Flag inline rimaste in mezzo al pattern: JavaScript non le supporta e
+    // spostarle cambierebbe il significato. Meglio dirlo che indovinare.
+    const midPattern = /\(\?[a-zA-Z]*(?:-[a-zA-Z]+)?\)/.exec(translated.body);
+    if (midPattern) {
+        throw new PatternError(`flag inline ${midPattern[0]} in mezzo al pattern: JavaScript le accetta solo come flag globali. `
+            + "Spostale all'inizio del pattern o usa ignore_case.");
+    }
+    try {
+        return { regex: new RegExp(translated.body, [...flags].sort().join("")), notes };
+    }
+    catch (err) {
+        throw new PatternError(err.message);
+    }
+}