@bussolabs/closeyourit-cli 0.22.0 → 0.24.1

package/dist/commands/workload/promote.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../base");
+const limits_1 = require("../../lib/limits");
+const output_1 = require("../../lib/output");
+const ticket_lookup_1 = require("../../lib/ticket-lookup");
+const workload_1 = require("../../lib/workload");
+class WorkloadPromote extends base_1.BaseCommand {
+    static args = {
+        action: core_1.Args.string({ description: 'Workload action id', required: true }),
+    };
+    static description = 'Generate a ticket from a workload action and link it back (the action keeps existing; an already linked action is refused)';
+    static examples = [
+        '<%= config.bin %> workload promote <action-id> --project acme-api',
+        '<%= config.bin %> workload promote <action-id> -p acme-api --title "Implement the partner API" --description "Agreed in the meeting" --kind story --priority High',
+    ];
+    static flags = {
+        ...base_1.projectFlag,
+        title: core_1.Flags.string({
+            description: `Ticket title (default: the action title, max ${limits_1.LENGTH_LIMITS.title} characters)`,
+        }),
+        description: core_1.Flags.string({ description: `Ticket description (max ${limits_1.LENGTH_LIMITS.description} characters)` }),
+        kind: core_1.Flags.string({ description: 'Ticket kind (default: task)', options: ['bug', 'story', 'task', 'epic'] }),
+        ...ticket_lookup_1.newTicketLookupFlags,
+    };
+    async run() {
+        const { args, flags } = await this.parse(WorkloadPromote);
+        // Il ticket nasce qui: valgono i tetti di `tickets create`, e si leggono tutti in un rifiuto
+        // solo, prima di qualunque chiamata (CYCL-32).
+        const tooLong = (0, limits_1.tooLongMessage)([
+            { flag: '--title', value: flags.title, max: limits_1.LENGTH_LIMITS.title, orthography: true },
+            { flag: '--description', value: flags.description, max: limits_1.LENGTH_LIMITS.description, orthography: true },
+        ]);
+        if (tooLong)
+            this.error(tooLong, { exit: 2 });
+        const projectId = await this.resolveProjectId(flags.project);
+        const body = { project_id: projectId };
+        if (flags.title !== undefined)
+            body.title = flags.title;
+        if (flags.description !== undefined)
+            body.description = flags.description;
+        if (flags.kind !== undefined)
+            body.kind = flags.kind;
+        if (flags.status !== undefined)
+            body.status_id = await this.resolveTicketLookupId(ticket_lookup_1.TICKET_STATUS, flags.status);
+        if (flags.priority !== undefined) {
+            body.priority_id = await this.resolveTicketLookupId(ticket_lookup_1.TICKET_PRIORITY, flags.priority);
+        }
+        const res = await this.api.post(`${workload_1.WORKLOAD_ACTIONS_PATH}/${encodeURIComponent(args.action)}/promotion`, body);
+        if (!this.jsonEnabled()) {
+            this.log('Ticket created from the workload action:');
+            this.log((0, output_1.renderRecord)(res.data ?? {}));
+        }
+        return res;
+    }
+}
+exports.default = WorkloadPromote;

package/dist/commands/workload/show.d.ts

@@ -0,0 +1,9 @@
+import { BaseCommand } from '../../base';
+export default class WorkloadShow extends BaseCommand {
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    run(): Promise<unknown>;
+}

package/dist/commands/workload/show.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../base");
+const output_1 = require("../../lib/output");
+const workload_1 = require("../../lib/workload");
+class WorkloadShow extends base_1.BaseCommand {
+    static args = {
+        id: core_1.Args.string({ description: 'Workload action id', required: true }),
+    };
+    static description = 'Show one workload action (an action of another team answers 404, never 403)';
+    static examples = ['<%= config.bin %> workload show <action-id>'];
+    async run() {
+        const { args } = await this.parse(WorkloadShow);
+        const res = await this.api.get(`${workload_1.WORKLOAD_ACTIONS_PATH}/${encodeURIComponent(args.id)}`);
+        if (!this.jsonEnabled()) {
+            const data = res.data ?? {};
+            this.log((0, output_1.renderRecord)(data));
+            this.log((0, workload_1.participantsLine)(data));
+        }
+        return res;
+    }
+}
+exports.default = WorkloadShow;

package/dist/commands/workload/update.d.ts

@@ -0,0 +1,17 @@
+import { BaseCommand } from '../../base';
+export default class WorkloadUpdate extends BaseCommand {
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        description: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        status: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'scheduled-at': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'due-at': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        ticket: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        title: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/workload/update.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../base");
+const output_1 = require("../../lib/output");
+const workload_1 = require("../../lib/workload");
+class WorkloadUpdate extends base_1.BaseCommand {
+    static args = {
+        id: core_1.Args.string({ description: 'Workload action id', required: true }),
+    };
+    static description = 'Update a workload action (only the passed fields change). The team never changes: moving an action would change who can see it.';
+    static examples = [
+        '<%= config.bin %> workload update <action-id> --status done',
+        '<%= config.bin %> workload update <action-id> --title "Fiera 2027" --due-at 2027-09-10T18:00:00Z',
+        '<%= config.bin %> workload update <action-id> --ticket ""',
+    ];
+    static flags = {
+        title: core_1.Flags.string({ description: 'New title' }),
+        ...workload_1.actionFieldFlags,
+    };
+    async run() {
+        const { args, flags } = await this.parse(WorkloadUpdate);
+        const body = {};
+        if (flags.title !== undefined)
+            body.title = flags.title;
+        (0, workload_1.applyActionBody)(body, flags);
+        const ticketId = flags.ticket ? await this.resolveTicketId(flags.ticket) : undefined;
+        if (flags.ticket !== undefined)
+            body.ticket_id = ticketId ?? null;
+        const res = await this.api.put(`${workload_1.WORKLOAD_ACTIONS_PATH}/${encodeURIComponent(args.id)}`, body);
+        const data = res.data ?? {};
+        // Su una modifica il rifiuto silenzioso del server non lascia le cose come stavano: azzera il
+        // campo, quindi porta via anche il ticket che era collegato prima. Dirlo per intero.
+        if ((0, workload_1.ticketLinkMissing)(flags.ticket, ticketId, data)) {
+            this.warn(`Ticket ${flags.ticket} is not visible to you: the action now has no linked ticket at all, not even the one it had before.`);
+        }
+        if (!this.jsonEnabled()) {
+            this.log('Workload action updated:');
+            this.log((0, output_1.renderRecord)(data));
+            this.log((0, workload_1.participantsLine)(data));
+        }
+        return res;
+    }
+}
+exports.default = WorkloadUpdate;

package/dist/errors/error-codes.d.ts

@@ -22,9 +22,22 @@ export declare const ErrorCodes: {
     readonly Team: {
         readonly notFound: "C404-TEM-001";
     };
+    readonly ErrorGroup: {
+        readonly notFound: "C404-ERG-001";
+    };
+    readonly MetricGroup: {
+        readonly notFound: "C404-MTG-001";
+    };
     readonly Member: {
         readonly notFound: "C404-MBR-001";
     };
+    readonly ServiceAccount: {
+        readonly boundaryMismatch: "C404-SVA-001";
+        readonly restrictionNotApplied: "C500-SVA-002";
+    };
+    readonly Ticket: {
+        readonly notFound: "C404-TKT-001";
+    };
     readonly Knowledge: {
         readonly publishUnavailable: "C404-KNW-001";
     };
@@ -38,6 +51,10 @@ export declare const ErrorCodes: {
         readonly expired: "C408-DEV-001";
         readonly failed: "C400-DEV-002";
     };
+    readonly Ask: {
+        readonly timeout: "C408-ASK-001";
+        readonly failed: "C502-ASK-002";
+    };
     readonly Input: {
         readonly invalid: "C400-INP-001";
     };

package/dist/errors/error-codes.js

@@ -27,9 +27,37 @@ exports.ErrorCodes = {
     Team: {
         notFound: 'C404-TEM-001',
     },
+    // Gruppi di monitoring chiesti a un'operazione in massa e non ritrovati nella risposta. Il server
+    // filtra la selezione sul progetto e risponde 200 su ciò che resta (`scope.where(id:)`), quindi
+    // un id di un altro progetto — o di un dato ormai vecchio — sparisce senza una parola: chi ha
+    // chiesto di chiudere trenta gruppi ne vedrebbe chiusi ventotto e nessuno glielo direbbe (CYCL-44).
+    ErrorGroup: {
+        notFound: 'C404-ERG-001',
+    },
+    MetricGroup: {
+        notFound: 'C404-MTG-001',
+    },
     Member: {
         notFound: 'C404-MBR-001',
     },
+    // Il confine ambienti di un account di servizio, chiesto e non applicato (CYCL-46). Il server
+    // interseca i code ricevuti con quelli dell'organizzazione e risponde 200 su ciò che resta: un
+    // refuso non restringe niente, CANCELLA il confine — e una allow-list vuota vuol dire «ogni
+    // ambiente», cioè l'opposto di quello che si stava chiedendo, senza una parola. Il comando
+    // controlla i code prima di scrivere, ma leggere gli ambienti chiede un permesso che può mancare:
+    // il confronto fra chiesto e applicato resta la rete sotto, e vale in entrambi i versi (un code
+    // sparito, o uno comparso che nessuno aveva chiesto).
+    ServiceAccount: {
+        boundaryMismatch: 'C404-SVA-001',
+        restrictionNotApplied: 'C500-SVA-002',
+    },
+    // Un ticket indicato per collegarlo altrove (una attività del carico di lavoro) e non trovato: il
+    // riferimento non è né un id né un code leggibile ("DRFL-3"), oppure quel code non esiste tra i
+    // ticket visibili. Il server, ricevendo un id che non si può vedere, salverebbe «nessun ticket»
+    // senza dire niente (CYCL-42).
+    Ticket: {
+        notFound: 'C404-TKT-001',
+    },
     // Il backend risponde 404 senza codice applicativo sulla route della pubblicazione atomica:
     // non è il progetto a mancare, è il server a essere più vecchio del comando (CYCL-8).
     Knowledge: {
@@ -47,6 +75,14 @@ exports.ErrorCodes = {
         expired: 'C408-DEV-001',
         failed: 'C400-DEV-002',
     },
+    // Attesa di una risposta preparata altrove (l'assistente, «chiedi ai ticket»). `timeout` non è un
+    // guasto del server: la domanda è partita e la risposta sta ancora arrivando, è il comando che ha
+    // smesso di aspettare — il messaggio dice dove ritrovarla. `failed` copre il caso in cui il
+    // server dichiara fallita la risposta senza allegare un codice proprio (CYCL-43).
+    Ask: {
+        timeout: 'C408-ASK-001',
+        failed: 'C502-ASK-002',
+    },
     // The command line itself was rejected (missing/unknown flag or arg, value outside the allowed
     // options, a `this.error(...)` guard): the message says what to fix, and it never reached the
     // server — the opposite of System.unexpected, which stays for real failures (CYCL-33).

package/dist/lib/api.d.ts

@@ -22,7 +22,7 @@ export interface UploadFile {
     filename: string;
     data: Blob;
 }
-type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 export declare class CliApi {
     private readonly config;
     /**
@@ -47,6 +47,12 @@ export declare class CliApi {
     get<T = unknown>(path: string, opts?: RequestOptions): Promise<Envelope<T>>;
     post<T = unknown>(path: string, body?: unknown, opts?: RequestOptions): Promise<Envelope<T>>;
     put<T = unknown>(path: string, body?: unknown, opts?: RequestOptions): Promise<Envelope<T>>;
+    /**
+     * PATCH. Rails routes a resourceful `update` under both PUT and PATCH, so most commands here use
+     * `put`; a custom member route declared with `patch` (error group assignment, CYCL-44) answers to
+     * PATCH alone, and sending PUT to it is a plain 404.
+     */
+    patch<T = unknown>(path: string, body?: unknown, opts?: RequestOptions): Promise<Envelope<T>>;
     delete<T = unknown>(path: string, opts?: RequestOptions): Promise<Envelope<T>>;
     /**
      * Download a binary payload (e.g. a ticket attachment). The endpoint redirects to a signed

package/dist/lib/api.js

@@ -117,6 +117,14 @@ class CliApi {
     put(path, body, opts) {
         return this.request('PUT', path, { ...opts, body });
     }
+    /**
+     * PATCH. Rails routes a resourceful `update` under both PUT and PATCH, so most commands here use
+     * `put`; a custom member route declared with `patch` (error group assignment, CYCL-44) answers to
+     * PATCH alone, and sending PUT to it is a plain 404.
+     */
+    patch(path, body, opts) {
+        return this.request('PATCH', path, { ...opts, body });
+    }
     delete(path, opts) {
         return this.request('DELETE', path, opts);
     }

package/dist/lib/assistant.d.ts

@@ -0,0 +1,29 @@
+/** A message of an assistant conversation, as the backend serializes it (AssistantMessageSerializer). */
+export interface AssistantMessage extends Record<string, unknown> {
+    id?: string;
+    role?: string;
+    /** `streaming` = still being written; `complete`/`failed` = final. */
+    status?: string;
+    content?: string | null;
+    tools_used?: unknown;
+    error_code?: string | null;
+    created_at?: string;
+}
+/** `{code, message}` for a failed reply: the server code when there is one, ours when there is not. */
+export declare function assistantFailure(errorCode?: string | null): {
+    code: string;
+    message: string;
+};
+/**
+ * The `🧰 Tools used:` line, or '' when the reply used none. What the assistant read is what makes
+ * the answer checkable, so it is printed next to the answer and not hidden behind `--json`.
+ */
+export declare function renderToolsUsed(tools: unknown, prefix?: string): string;
+/** Every message of a conversation, oldest first (the order the backend serializes them in). */
+export declare function renderMessages(messages: unknown): string;
+/**
+ * The conversation list. ID first: it is the argument of `assistant conversations show|delete` and
+ * the value of `assistant ask --conversation`, so a table without it would force `--json` just to
+ * carry on the conversation you are looking at.
+ */
+export declare function renderConversationsTable(rows: Array<Record<string, unknown>>): string;

package/dist/lib/assistant.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assistantFailure = assistantFailure;
+exports.renderToolsUsed = renderToolsUsed;
+exports.renderMessages = renderMessages;
+exports.renderConversationsTable = renderConversationsTable;
+const error_codes_1 = require("../errors/error-codes");
+const output_1 = require("./output");
+/**
+ * Why a reply failed, said in a way that tells the reader what to do next.
+ *
+ * The backend ships only the code (`Assistant::Message#error_kind` does the same reading on the web
+ * side), and the three cases ask for three different reactions: nothing will change until someone
+ * connects the AI service, or the question itself must be rewritten, or it is worth trying again in
+ * a minute. Collapsing them into one "the assistant failed" would send people to retry forever
+ * something that cannot succeed.
+ */
+const FAILURE_MESSAGES = {
+    // Integrations::Providers::NOT_CONNECTED_CODE
+    'R503-INTEGRATION-006': 'The AI service is not connected for your organization: connect it from the web app, then ask again.',
+    // Assistant::Message::NO_ANSWER_ERROR_CODES
+    'R502-GEMINI-004': 'The assistant did not produce an answer for this question — try rephrasing it.',
+};
+const FAILURE_FALLBACK = 'The assistant could not answer (temporary problem upstream); try again in a moment.';
+/** `{code, message}` for a failed reply: the server code when there is one, ours when there is not. */
+function assistantFailure(errorCode) {
+    const code = errorCode ?? undefined;
+    return {
+        code: code ?? error_codes_1.ErrorCodes.Ask.failed,
+        message: (code ? FAILURE_MESSAGES[code] : undefined) ?? FAILURE_FALLBACK,
+    };
+}
+/**
+ * The `🧰 Tools used:` line, or '' when the reply used none. What the assistant read is what makes
+ * the answer checkable, so it is printed next to the answer and not hidden behind `--json`.
+ */
+function renderToolsUsed(tools, prefix = '') {
+    const names = Array.isArray(tools) ? tools.map((tool) => (0, output_1.sanitize)(tool)).filter((tool) => tool.trim() !== '') : [];
+    return names.length === 0 ? '' : `${prefix}🧰 Tools used: ${names.join(', ')}`;
+}
+/** One message: who spoke and when, the text, the reason when it failed, the tools it used. */
+function renderMessage(message) {
+    const when = (0, output_1.sanitize)(message.created_at ?? '');
+    const lines = [`${(0, output_1.statusDot)(message.status)} [${(0, output_1.sanitize)(message.role ?? '-')}] ${when}`.trimEnd()];
+    const content = String(message.content ?? '').trim();
+    if (content !== '')
+        lines.push((0, output_1.sanitizeMultiline)(message.content));
+    // A failed reply carries no text at all: without this line the conversation would show an empty
+    // bubble and no hint of what went wrong.
+    if (message.status === 'failed') {
+        const failure = assistantFailure(message.error_code);
+        lines.push(`⚠️  ${failure.code} — ${failure.message}`);
+    }
+    const tools = renderToolsUsed(message.tools_used);
+    if (tools !== '')
+        lines.push(tools);
+    return lines.join('\n');
+}
+/** Every message of a conversation, oldest first (the order the backend serializes them in). */
+function renderMessages(messages) {
+    const rows = Array.isArray(messages) ? messages : [];
+    return rows.length === 0 ? '(no messages)' : rows.map((message) => renderMessage(message)).join('\n\n');
+}
+/**
+ * The conversation list. ID first: it is the argument of `assistant conversations show|delete` and
+ * the value of `assistant ask --conversation`, so a table without it would force `--json` just to
+ * carry on the conversation you are looking at.
+ */
+function renderConversationsTable(rows) {
+    return (0, output_1.renderTable)(['ID', 'TITLE', 'LAST MESSAGE', 'CREATED'], rows.map((row) => [
+        String(row.id ?? ''),
+        String(row.title ?? ''),
+        String(row.last_message_at ?? ''),
+        String(row.created_at ?? ''),
+    ]));
+}

package/dist/lib/bulk-triage.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Bulk triage of monitoring groups (errors, metrics) — CYCL-44.
+ *
+ * The two endpoints are the same shape (`POST .../bulk_triage` with `ids[]` + `bulk_action`) and
+ * share the same blind spot, so the guard lives here once instead of in both commands.
+ */
+/** The three actions the backend accepts, for errors and metrics alike (`Observability::Triage::ACTIONS`). */
+export declare const TRIAGE_ACTIONS: readonly ["resolve", "ignore", "reopen"];
+/**
+ * The ids to send: the order they were written in, each one once.
+ *
+ * The server matches with `where(id: ids)`, which never returns the same row twice — so a repeated
+ * `--group` would come back as one row and the check below would read it as "one went missing".
+ * Deduplicating is safe here precisely because this endpoint is not all-or-nothing: unlike merge,
+ * where the raw list is the evidence the server needs to refuse the whole operation.
+ */
+export declare function uniqueIds(values: string[]): string[];
+/**
+ * Refuse a partial triage the caller cannot see.
+ *
+ * `bulk_triage` scopes the selection to the project and answers 200 on whatever is left, so an id
+ * belonging to another project (or to a page refreshed on stale data) is dropped without a word.
+ * A script would go on believing it closed thirty groups after closing twenty-eight. Everything the
+ * server did touch stays done — the triage is reversible, and undoing the good part would be worse
+ * — but the command says so and exits non-zero.
+ */
+export declare function assertNothingDropped(opts: {
+    action: string;
+    code: string;
+    noun: string;
+    requested: string[];
+    rows: Array<Record<string, unknown>>;
+}): void;
+/** `1 error group` / `3 error groups` — the count line both commands print. */
+export declare function triagedLine(count: number, noun: string, action: string): string;

package/dist/lib/bulk-triage.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRIAGE_ACTIONS = void 0;
+exports.uniqueIds = uniqueIds;
+exports.assertNothingDropped = assertNothingDropped;
+exports.triagedLine = triagedLine;
+const api_1 = require("./api");
+/**
+ * Bulk triage of monitoring groups (errors, metrics) — CYCL-44.
+ *
+ * The two endpoints are the same shape (`POST .../bulk_triage` with `ids[]` + `bulk_action`) and
+ * share the same blind spot, so the guard lives here once instead of in both commands.
+ */
+/** The three actions the backend accepts, for errors and metrics alike (`Observability::Triage::ACTIONS`). */
+exports.TRIAGE_ACTIONS = ['resolve', 'ignore', 'reopen'];
+/**
+ * The ids to send: the order they were written in, each one once.
+ *
+ * The server matches with `where(id: ids)`, which never returns the same row twice — so a repeated
+ * `--group` would come back as one row and the check below would read it as "one went missing".
+ * Deduplicating is safe here precisely because this endpoint is not all-or-nothing: unlike merge,
+ * where the raw list is the evidence the server needs to refuse the whole operation.
+ */
+function uniqueIds(values) {
+    const seen = new Set();
+    return values.filter((value) => {
+        const key = value.toLowerCase();
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/**
+ * Refuse a partial triage the caller cannot see.
+ *
+ * `bulk_triage` scopes the selection to the project and answers 200 on whatever is left, so an id
+ * belonging to another project (or to a page refreshed on stale data) is dropped without a word.
+ * A script would go on believing it closed thirty groups after closing twenty-eight. Everything the
+ * server did touch stays done — the triage is reversible, and undoing the good part would be worse
+ * — but the command says so and exits non-zero.
+ */
+function assertNothingDropped(opts) {
+    const returned = new Set(opts.rows.map((row) => String(row.id ?? '').toLowerCase()));
+    const missing = opts.requested.filter((id) => !returned.has(id.toLowerCase()));
+    if (missing.length === 0)
+        return;
+    throw new api_1.ApiRequestError(404, opts.code, `Triaged ${opts.rows.length} of ${opts.requested.length} ${opts.noun}s (${opts.action}). ` +
+        `Not found in this project: ${missing.join(', ')} — those were left untouched, ` +
+        `the other ${opts.rows.length} were changed.`);
+}
+/** `1 error group` / `3 error groups` — the count line both commands print. */
+function triagedLine(count, noun, action) {
+    return `Triaged ${count} ${noun}${count === 1 ? '' : 's'} (${action}).`;
+}

package/dist/lib/grouping-rules.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Custom error grouping rules (CYCL-44, server side CYRA-153).
+ *
+ * At ingest time the first active rule, in `position` order, whose match succeeds rewrites the
+ * occurrence's fingerprint: everything hitting rules with the same `fingerprint_key` lands in one
+ * group. This is how a team bends the automatic grouping.
+ */
+/** Occurrence field a rule looks at (`Errors::GroupingRule.fields`). */
+export declare const GROUPING_RULE_FIELDS: readonly ["exception_type", "message", "culprit", "transaction"];
+/**
+ * How the field is compared (`Errors::GroupingRule.operators`). Always case-insensitive and never a
+ * regular expression: on the ingest hot path a user-supplied pattern would be an open door to ReDoS.
+ */
+export declare const GROUPING_RULE_OPERATORS: readonly ["contains", "equals", "starts_with"];
+export interface GroupingRuleFlags {
+    active?: boolean;
+    field?: string;
+    'fingerprint-key'?: string;
+    operator?: string;
+    position?: number;
+    value?: string;
+}
+/**
+ * The rule attributes to send, skipping every flag left out. `create` fills the required ones by
+ * declaring them required; `update` sends only what it was told to change, so an omitted flag keeps
+ * the value the rule already has instead of blanking it.
+ */
+export declare function groupingRuleBody(flags: GroupingRuleFlags): Record<string, unknown>;

package/dist/lib/grouping-rules.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Custom error grouping rules (CYCL-44, server side CYRA-153).
+ *
+ * At ingest time the first active rule, in `position` order, whose match succeeds rewrites the
+ * occurrence's fingerprint: everything hitting rules with the same `fingerprint_key` lands in one
+ * group. This is how a team bends the automatic grouping.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GROUPING_RULE_OPERATORS = exports.GROUPING_RULE_FIELDS = void 0;
+exports.groupingRuleBody = groupingRuleBody;
+/** Occurrence field a rule looks at (`Errors::GroupingRule.fields`). */
+exports.GROUPING_RULE_FIELDS = ['exception_type', 'message', 'culprit', 'transaction'];
+/**
+ * How the field is compared (`Errors::GroupingRule.operators`). Always case-insensitive and never a
+ * regular expression: on the ingest hot path a user-supplied pattern would be an open door to ReDoS.
+ */
+exports.GROUPING_RULE_OPERATORS = ['contains', 'equals', 'starts_with'];
+/**
+ * The rule attributes to send, skipping every flag left out. `create` fills the required ones by
+ * declaring them required; `update` sends only what it was told to change, so an omitted flag keeps
+ * the value the rule already has instead of blanking it.
+ */
+function groupingRuleBody(flags) {
+    const body = {};
+    if (flags.field !== undefined)
+        body.field = flags.field;
+    if (flags.operator !== undefined)
+        body.operator = flags.operator;
+    if (flags.value !== undefined)
+        body.value = flags.value;
+    if (flags['fingerprint-key'] !== undefined)
+        body.fingerprint_key = flags['fingerprint-key'];
+    if (flags.position !== undefined)
+        body.position = flags.position;
+    if (flags.active !== undefined)
+        body.active = flags.active;
+    return body;
+}

package/dist/lib/knowledge.d.ts

@@ -5,6 +5,11 @@ export declare const KNOWLEDGE_KINDS: readonly ["note", "decision", "guide"];
  * `--kind note --kind decision,guide` → ['note', 'decision', 'guide'].
  */
 export declare function normalizeKinds(values?: string[]): string[];
+/**
+ * Clean a repeatable flag into a list: trimmed, empties dropped, order preserved.
+ * `--tag ""` therefore means "leave nothing" — the deliberate way to clear tags on update.
+ */
+export declare function cleanList(values?: string[]): string[];
 /** Collapse whitespace and truncate a cell so the list table stays single-line. */
 export declare function truncate(value: string, max?: number): string;
 /**
@@ -59,6 +64,16 @@ export declare function buildBooksQuery(opts: {
     project?: string;
     q?: string;
 }): string;
+/**
+ * The scope lines of a page — every project it belongs to, its groups, its tags — as readable
+ * `key: a, b` rows. `renderRecord` drops arrays, so without these a page connected to five projects
+ * read as if it had one, and its tags were invisible from the terminal (CYCL-45).
+ *
+ * `projects` shows up only past the first one: with a single project the `project` line above
+ * already says it, and repeating it would be noise on the pages that have always had just one.
+ * Groups and tags appear whenever there are any.
+ */
+export declare function pageScopeLines(page: Record<string, unknown>): Record<string, string>;
 /**
  * Render the `kb book list` table. ID first: it is the argument of `kb book show` and of
  * `kb book add-page`, so a table without it would force `--json` just to act on what you are

package/dist/lib/knowledge.js

@@ -2,11 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KNOWLEDGE_STATUSES = exports.KNOWLEDGE_KINDS = void 0;
 exports.normalizeKinds = normalizeKinds;
+exports.cleanList = cleanList;
 exports.truncate = truncate;
 exports.buildPagesQuery = buildPagesQuery;
 exports.renderRelated = renderRelated;
 exports.renderRelatedGroups = renderRelatedGroups;
 exports.buildBooksQuery = buildBooksQuery;
+exports.pageScopeLines = pageScopeLines;
 exports.renderBooksTable = renderBooksTable;
 exports.renderBook = renderBook;
 exports.renderPagesTable = renderPagesTable;
@@ -25,6 +27,15 @@ function normalizeKinds(values) {
         .map((value) => value.trim())
         .filter((value) => value.length > 0);
 }
+/**
+ * Clean a repeatable flag into a list: trimmed, empties dropped, order preserved.
+ * `--tag ""` therefore means "leave nothing" — the deliberate way to clear tags on update.
+ */
+function cleanList(values) {
+    if (!values)
+        return [];
+    return values.map((value) => value.trim()).filter((value) => value.length > 0);
+}
 /** Collapse whitespace and truncate a cell so the list table stays single-line. */
 function truncate(value, max = 60) {
     const flat = value.replace(/\s+/g, ' ').trim();
@@ -107,6 +118,31 @@ function joinList(value) {
         return undefined;
     return value.map((entry) => String(entry)).join(', ');
 }
+/**
+ * The scope lines of a page — every project it belongs to, its groups, its tags — as readable
+ * `key: a, b` rows. `renderRecord` drops arrays, so without these a page connected to five projects
+ * read as if it had one, and its tags were invisible from the terminal (CYCL-45).
+ *
+ * `projects` shows up only past the first one: with a single project the `project` line above
+ * already says it, and repeating it would be noise on the pages that have always had just one.
+ * Groups and tags appear whenever there are any.
+ */
+function pageScopeLines(page) {
+    const lines = {};
+    const projects = Array.isArray(page.projects) ? page.projects : [];
+    if (projects.length > 1) {
+        const keys = projects.map((project) => String(project.key ?? '')).filter(Boolean);
+        if (keys.length > 0)
+            lines.projects = keys.join(', ');
+    }
+    const groups = joinList(page.groups);
+    if (groups)
+        lines.groups = groups;
+    const tags = joinList(page.tags);
+    if (tags)
+        lines.tags = tags;
+    return lines;
+}
 /**
  * Render the `kb book list` table. ID first: it is the argument of `kb book show` and of
  * `kb book add-page`, so a table without it would force `--json` just to act on what you are