@bussolabs/closeyourit-cli 0.19.0 → 0.21.0

package/dist/commands/tickets/update.js

@@ -2,40 +2,175 @@
 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_body_1 = require("../../lib/ticket-body");
+const ticket_lookup_1 = require("../../lib/ticket-lookup");
+/** Campi che la GET del ticket restituisce già con la chiave e il valore attesi dalla PUT. */
+const PRESERVED_KEYS = ['title', 'kind', 'description', 'technical_analysis', 'weight', 'due_at', 'parent_id'];
 class TicketsUpdate extends base_1.BaseCommand {
-    // PUT /cli/v1/projects/:p/tickets/:id maps to Ticketing::UpdateTicket, a full replace:
-    // fields you omit are cleared server-side. Pass the complete desired state, not a partial patch.
-    static description = 'Update a ticket (full replace — fields you omit are cleared server-side)';
+    // PUT /cli/v1/projects/:p/tickets/:id maps to Ticketing::UpdateTicket, a full replace built for the
+    // web form, which always posts every field: whatever the body omits is cleared server-side, and
+    // status/priority are mandatory, so `--title` alone did not even go through ("Priority must exist")
+    // while a body carrying them silently emptied description, technical analysis, weight, due date,
+    // assignee, milestone and platforms (CYCL-30).
+    //
+    // The command now reads the ticket first and re-sends its current state under the flags you passed:
+    // what you do not name stays as it was. Emptying is a separate, explicit request (`--clear <field>`),
+    // and `--replace` keeps the raw full replace for callers that really do send the whole desired state.
+    //
+    // Scenarios and conditions stay out of the merge: the backend replaces them when the body carries
+    // new ones and leaves them untouched otherwise, so re-sending them would only risk duplicates.
+    //
+    // Known limit — the read and the write are not one atomic operation, and this endpoint offers no
+    // optimistic locking (no lock_version, no If-Match/ETag: the GET exposes nothing to send back),
+    // so an edit landing between them is overwritten by the state this command read. It cannot be
+    // fixed from the client alone, and it is strictly narrower than what it replaces: the full replace
+    // wiped those fields on EVERY call, concurrency or not, while here the exposure is the round trip.
+    // Closing it for good needs a server-side merge (or a version token to send back) — the fix the
+    // ticket calls the "server remedy".
+    static description = 'Update a ticket, changing only the fields you pass (the others keep their current value; use --clear to empty one, --replace for the raw full replace)';
     static examples = [
         '<%= config.bin %> tickets update <ticket-id> --project acme-api --title "New title"',
+        '<%= config.bin %> tickets update <ticket-id> -p acme-api --clear assignee --clear due-at',
         '<%= config.bin %> tickets update <ticket-id> -p acme-api --title "Login bug" --scenarios \'[{"step_given":"logged out","step_when":"I submit","step_then":"it 500s","step_expected":"dashboard loads"}]\' --condition "login works"',
+        '<%= config.bin %> tickets update <ticket-id> -p acme-api --status in_review --priority High',
+        '<%= config.bin %> tickets update <ticket-id> -p acme-api --replace --title "Only this" --status open --priority medium',
     ];
     static args = {
         id: core_1.Args.string({ description: 'Ticket id', required: true }),
     };
     static flags = {
         ...base_1.projectFlag,
-        title: core_1.Flags.string({ description: 'Ticket title' }),
+        title: core_1.Flags.string({ description: `Ticket title (max ${limits_1.LENGTH_LIMITS.title} characters)` }),
         kind: core_1.Flags.string({ description: 'Ticket kind (bug, story, task, epic)', options: ['bug', 'story', 'task', 'epic'] }),
         ...ticket_body_1.ticketBodyFlags,
+        ...ticket_body_1.clearFlag,
+        replace: core_1.Flags.boolean({
+            description: 'Send only the flags you passed (full replace — every field you omit is cleared server-side)',
+            default: false,
+        }),
     };
     async run() {
         const { args, flags } = await this.parse(TicketsUpdate);
         const projectId = await this.resolveProjectId(flags.project);
-        const body = {};
+        const path = `/cli/v1/projects/${encodeURIComponent(projectId)}/tickets/${encodeURIComponent(args.id)}`;
+        const requested = {};
         if (flags.title !== undefined)
-            body.title = flags.title;
+            requested.title = flags.title;
         if (flags.kind !== undefined)
-            body.kind = flags.kind;
-        (0, ticket_body_1.applyTicketBody)(body, flags);
-        const res = await this.api.put(`/cli/v1/projects/${projectId}/tickets/${args.id}`, body);
+            requested.kind = flags.kind;
+        (0, ticket_body_1.applyTicketBody)(requested, flags);
+        // Cambiare stato o priorità non costringe più a cercarne prima l'id: il code o l'etichetta
+        // bastano, e un id passa così com'è (CYCL-34).
+        if (flags.status !== undefined) {
+            requested.status_id = await this.resolveTicketLookupId(ticket_lookup_1.TICKET_STATUS, flags.status);
+        }
+        if (flags.priority !== undefined) {
+            requested.priority_id = await this.resolveTicketLookupId(ticket_lookup_1.TICKET_PRIORITY, flags.priority);
+        }
+        this.refuseClearConflicts(requested, flags.clear);
+        (0, ticket_body_1.applyTicketClears)(requested, flags.clear);
+        let body = requested;
+        if (!flags.replace) {
+            const ticket = (await this.api.get(path)).data ?? {};
+            // I campi troppo lunghi si scoprono qui, tutti insieme, invece che uno per rifiuto (CYCL-32).
+            // Il valore attuale fa da salvaguardia: un testo scritto prima che il tetto esistesse resta
+            // correggibile finché non si allunga, com'è dal server. Con `--replace` lo stato attuale non
+            // si legge, quindi la salvaguardia non è calcolabile e la misura resta al server.
+            const tooLong = (0, limits_1.tooLongMessage)((0, ticket_body_1.ticketLengthChecks)(flags, ticket));
+            if (tooLong)
+                this.error(tooLong, { exit: 2 });
+            body = { ...(await this.currentState(projectId, ticket, requested)), ...requested };
+        }
+        const res = await this.api.put(path, body);
         if (!this.jsonEnabled()) {
             this.log('Ticket updated:');
             this.log((0, output_1.renderRecord)(res.data ?? {}));
         }
         return res;
     }
+    /**
+     * Lo stato attuale del ticket, nella forma che la PUT si aspetta, per i soli campi che chi ha
+     * scritto il comando non ha già deciso. I campi vuoti restano fuori dal corpo: ometterli o
+     * mandarli a null è la stessa cosa, e il corpo resta leggibile.
+     */
+    async currentState(projectId, ticket, requested) {
+        const current = {};
+        for (const key of PRESERVED_KEYS) {
+            const value = ticket[key];
+            if (key in requested || value === null || value === undefined || value === '')
+                continue;
+            current[key] = value;
+        }
+        // Status e priorità sono obbligatorie per il backend: senza di loro l'update non passa. La GET
+        // espone l'id dello status, mentre della priorità dà solo l'etichetta, da rileggere nella lookup.
+        if (!('status_id' in requested)) {
+            const statusId = ticket.status_ref?.id;
+            if (typeof statusId !== 'string' || statusId === '') {
+                this.error('Cannot read the current status of this ticket: pass --status <code|label|id> or use --replace.', {
+                    exit: 2,
+                });
+            }
+            current.status_id = statusId;
+        }
+        if (!('priority_id' in requested)) {
+            current.priority_id = await this.lookupId(ticket_lookup_1.TICKET_PRIORITY.path, ticket.priority, 'priority', '--priority');
+        }
+        if (!('assignee_id' in requested) && ticket.assignee) {
+            current.assignee_id = await this.lookupId('/cli/v1/members', ticket.assignee, 'assignee', '--assignee-id', 'account_id');
+        }
+        if (!('milestone_id' in requested) && ticket.milestone) {
+            const milestones = `/cli/v1/projects/${encodeURIComponent(projectId)}/milestones`;
+            current.milestone_id = await this.lookupId(milestones, ticket.milestone, 'milestone', '--milestone-id');
+        }
+        const platforms = Array.isArray(ticket.platforms) ? ticket.platforms : [];
+        if (!('platform_ids' in requested) && platforms.length > 0) {
+            const rows = await this.lookupRows('/cli/v1/platforms');
+            current.platform_ids = platforms.map((platform) => this.matchId(rows, platform, 'platform', '--platform-id'));
+        }
+        return current;
+    }
+    /** Rifiuta `--clear x` insieme a `--x`: impostare e svuotare lo stesso campo è una richiesta ambigua. */
+    refuseClearConflicts(requested, fields) {
+        for (const field of fields ?? []) {
+            if (ticket_body_1.CLEARABLE_FIELDS[field] in requested) {
+                this.error(`--clear ${field} conflicts with the value passed for the same field: pick one.`, { exit: 2 });
+            }
+        }
+    }
+    /** Id della voce di lookup che corrisponde all'etichetta mostrata dalla GET del ticket. */
+    async lookupId(path, label, field, flag, idKey = 'id') {
+        const rows = await this.lookupRows(path);
+        return this.matchId(rows, label, field, flag, idKey);
+    }
+    /**
+     * Una lookup non trovata o ambigua ferma il comando: proseguire manderebbe una PUT senza quel
+     * campo, cioè lo cancellerebbe in silenzio — il difetto che questo comando esiste per evitare.
+     */
+    matchId(rows, label, field, flag, idKey = 'id') {
+        const wanted = String(label ?? '').toLowerCase();
+        const matches = rows.filter((row) => [row.label, row.code, row.name].some((value) => typeof value === 'string' && value.toLowerCase() === wanted));
+        if (matches.length !== 1 || typeof matches[0][idKey] !== 'string') {
+            const reason = matches.length > 1 ? `${matches.length} entries match it` : 'no entry matches it';
+            this.error(`Cannot keep the current ${field} "${String(label ?? '')}": ${reason}. Pass ${flag} <id> or use --replace.`, { exit: 2 });
+        }
+        return matches[0][idKey];
+    }
+    /** Ogni pagina di un endpoint di lookup: la voce cercata può stare oltre la prima. */
+    async lookupRows(path) {
+        const rows = [];
+        const separator = path.includes('?') ? '&' : '?';
+        let page = 1;
+        let totalPages = 1;
+        do {
+            // eslint-disable-next-line no-await-in-loop
+            const res = await this.api.get(`${path}${separator}page=${page}&per=100`);
+            rows.push(...(Array.isArray(res.data) ? res.data : []));
+            totalPages = Number(res.meta?.total_pages ?? 1);
+            page += 1;
+        } while (page <= totalPages);
+        return rows;
+    }
 }
 exports.default = TicketsUpdate;

package/dist/commands/whoami.js

@@ -5,6 +5,9 @@ class Whoami extends base_1.BaseCommand {
     static description = 'Show the authenticated account, organization, token prefix and permissions';
     static examples = ['<%= config.bin %> whoami', '<%= config.bin %> whoami --json'];
     async run() {
+        // Nothing to read from the parser, but oclif validates the command line only here: without this
+        // call a mistyped flag is silently ignored and the command answers as if it were right (CYCL-33).
+        await this.parse(Whoami);
         const res = await this.api.get('/cli/v1/whoami');
         // Rebuild from an allow-list. If a future backend accidentally includes a token secret or other
         // authentication internals, `--json` must not proxy them to stdout.

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

@@ -25,10 +25,22 @@ export declare const ErrorCodes: {
     readonly Member: {
         readonly notFound: "C404-MBR-001";
     };
+    readonly Knowledge: {
+        readonly publishUnavailable: "C404-KNW-001";
+    };
+    readonly TicketStatus: {
+        readonly notFound: "C404-STA-001";
+    };
+    readonly TicketPriority: {
+        readonly notFound: "C404-PRI-001";
+    };
     readonly Device: {
         readonly expired: "C408-DEV-001";
         readonly failed: "C400-DEV-002";
     };
+    readonly Input: {
+        readonly invalid: "C400-INP-001";
+    };
     readonly System: {
         readonly unexpected: "C500-SYS-001";
     };

package/dist/errors/error-codes.js

@@ -30,10 +30,29 @@ exports.ErrorCodes = {
     Member: {
         notFound: 'C404-MBR-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: {
+        publishUnavailable: 'C404-KNW-001',
+    },
+    // Stato e priorità di un ticket, indicati per code o etichetta e non trovati nelle lookup
+    // dell'organizzazione (o corrispondenti a più di una voce) — CYCL-34.
+    TicketStatus: {
+        notFound: 'C404-STA-001',
+    },
+    TicketPriority: {
+        notFound: 'C404-PRI-001',
+    },
     Device: {
         expired: 'C408-DEV-001',
         failed: 'C400-DEV-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).
+    Input: {
+        invalid: 'C400-INP-001',
+    },
     System: {
         unexpected: 'C500-SYS-001',
     },

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

@@ -0,0 +1,16 @@
+/**
+ * True for the failures oclif has already worded for whoever typed the command: a parse/validation
+ * error (missing required flag or arg, nonexistent flag, value outside the allowed options) and the
+ * `this.error(...)` guards inside a command (`--confirm` missing, nothing to update, file unreadable).
+ *
+ * Deliberately NOT input errors, although both extend `CLIError`:
+ *  - `ExitError`, thrown by `this.exit(code)` — `cyi run` uses it to propagate the child exit code;
+ *  - `ModuleLoadError`, which is a real internal failure and keeps the generic system code.
+ */
+export declare function isInputError(error: unknown): error is Error;
+/**
+ * Flatten oclif's multi-line, ANSI-decorated message into the single line a JSON consumer reads:
+ * `The following error occurred:\n  Missing required flag project\nSee more help with --help`
+ * becomes `Missing required flag project` (CYCL-33).
+ */
+export declare function inputErrorMessage(error: Error): string;

package/dist/errors/input-error.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInputError = isInputError;
+exports.inputErrorMessage = inputErrorMessage;
+const core_1 = require("@oclif/core");
+/** oclif dims parts of a parse error with ANSI when the terminal has colors; machine output must not. */
+const ANSI = /\x1B\[[\d;]*m/g;
+/** Every parse error ends with this hint, and multi-reason ones open with a header line. */
+const HELP_HINT = 'See more help with --help';
+const HEADER = /^The following errors? occurred:$/;
+/**
+ * True for the failures oclif has already worded for whoever typed the command: a parse/validation
+ * error (missing required flag or arg, nonexistent flag, value outside the allowed options) and the
+ * `this.error(...)` guards inside a command (`--confirm` missing, nothing to update, file unreadable).
+ *
+ * Deliberately NOT input errors, although both extend `CLIError`:
+ *  - `ExitError`, thrown by `this.exit(code)` — `cyi run` uses it to propagate the child exit code;
+ *  - `ModuleLoadError`, which is a real internal failure and keeps the generic system code.
+ */
+function isInputError(error) {
+    if (!(error instanceof core_1.Errors.CLIError))
+        return false;
+    return !(error instanceof core_1.Errors.ExitError) && !(error instanceof core_1.Errors.ModuleLoadError);
+}
+/**
+ * Flatten oclif's multi-line, ANSI-decorated message into the single line a JSON consumer reads:
+ * `The following error occurred:\n  Missing required flag project\nSee more help with --help`
+ * becomes `Missing required flag project` (CYCL-33).
+ */
+function inputErrorMessage(error) {
+    const plain = error.message.replace(ANSI, '');
+    const lines = plain
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line !== '' && line !== HELP_HINT && !HEADER.test(line));
+    // Only noise (a bare hint, or an empty message): keep whatever the error carried rather than nothing.
+    if (lines.length === 0)
+        return plain.trim();
+    // A line ending in `:` introduces the next one ("Missing 1 required arg:" + the arg itself);
+    // anything else is a reason of its own ("Missing required flag environment" + "…flag project").
+    return lines.reduce((acc, line) => (acc.endsWith(':') ? `${acc} ${line}` : `${acc}; ${line}`));
+}

package/dist/lib/alert-events.js

@@ -53,4 +53,5 @@ exports.ALERT_EVENT_TYPES = [
     'server_replication_up',
     'server_container_restart_loop',
     'server_container_stable',
+    'seo_issue_new',
 ];

package/dist/lib/knowledge.d.ts

@@ -48,6 +48,30 @@ export declare function renderRelated(rows: RelatedRow[], heading?: string, inde
  * order as the table above it. Results without related pages are simply left out.
  */
 export declare function renderRelatedGroups(pages: Array<Record<string, unknown>>, grouped: Record<string, RelatedRow[]>): string;
+/**
+ * Build the query string for `kb book list`. `project` goes out as the raw reference: the books
+ * endpoint resolves a key or a UUID by itself (and 404s outside the scope), exactly like the pages
+ * endpoint — so no extra lookup call here.
+ */
+export declare function buildBooksQuery(opts: {
+    page: number;
+    per?: number;
+    project?: string;
+    q?: 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
+ * already looking at.
+ */
+export declare function renderBooksTable(books: Array<Record<string, unknown>>): string;
+/**
+ * Render a book with its summary: the metadata header, then the table of contents — the response
+ * both `kb book show` and `kb book add-page` get back, so the reader sees the resulting order in
+ * the same shape either way. `#` is the 0-based position, the very number `--position` takes.
+ * Page bodies are not here on purpose: the TOC is for orientation, `kb show <page>` for reading.
+ */
+export declare function renderBook(book: Record<string, unknown>): string;
 /**
  * Render the shared list/search table: TITLE, KIND, PROJECT, AUTHOR, UPDATED.
  *

package/dist/lib/knowledge.js

@@ -6,6 +6,9 @@ exports.truncate = truncate;
 exports.buildPagesQuery = buildPagesQuery;
 exports.renderRelated = renderRelated;
 exports.renderRelatedGroups = renderRelatedGroups;
+exports.buildBooksQuery = buildBooksQuery;
+exports.renderBooksTable = renderBooksTable;
+exports.renderBook = renderBook;
 exports.renderPagesTable = renderPagesTable;
 const output_1 = require("./output");
 /** Knowledge page kinds accepted by the backend (Knowledge::Page). */
@@ -82,6 +85,71 @@ function renderRelatedGroups(pages, grouped) {
         .map(({ rows, title }) => renderRelated(rows, `  ${(0, output_1.sanitize)(title)}`, '    '));
     return blocks.length === 0 ? '' : ['\n🔗 Related:', ...blocks].join('\n');
 }
+/**
+ * Build the query string for `kb book list`. `project` goes out as the raw reference: the books
+ * endpoint resolves a key or a UUID by itself (and 404s outside the scope), exactly like the pages
+ * endpoint — so no extra lookup call here.
+ */
+function buildBooksQuery(opts) {
+    const query = new URLSearchParams();
+    query.set('page', String(opts.page));
+    if (opts.per !== undefined)
+        query.set('per', String(opts.per));
+    if (opts.project)
+        query.set('project', opts.project);
+    if (opts.q)
+        query.set('q', opts.q);
+    return query.toString();
+}
+/** A list of names (project keys, group names) as one cell, or undefined when there is nothing. */
+function joinList(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return undefined;
+    return value.map((entry) => String(entry)).join(', ');
+}
+/**
+ * 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
+ * already looking at.
+ */
+function renderBooksTable(books) {
+    return (0, output_1.renderTable)(['ID', 'TITLE', 'PAGES', 'PROJECTS', 'AUTHOR', 'UPDATED'], books.map((book) => [
+        String(book.id ?? ''),
+        truncate(String(book.title ?? '')),
+        String(book.pages_count ?? ''),
+        joinList(book.projects) ?? '',
+        String(book.author ?? ''),
+        String(book.updated_at ?? ''),
+    ]));
+}
+/**
+ * Render a book with its summary: the metadata header, then the table of contents — the response
+ * both `kb book show` and `kb book add-page` get back, so the reader sees the resulting order in
+ * the same shape either way. `#` is the 0-based position, the very number `--position` takes.
+ * Page bodies are not here on purpose: the TOC is for orientation, `kb show <page>` for reading.
+ */
+function renderBook(book) {
+    const pages = Array.isArray(book.pages) ? book.pages : [];
+    const header = (0, output_1.renderRecord)({
+        id: book.id,
+        title: book.title,
+        description: book.description,
+        projects: joinList(book.projects),
+        groups: joinList(book.groups),
+        author: book.author,
+        pages_count: book.pages_count,
+        created_at: book.created_at,
+        updated_at: book.updated_at,
+    });
+    const toc = (0, output_1.renderTable)(['#', 'TITLE', 'KIND', 'PROJECT', 'ID'], pages.map((page) => [
+        String(page.position ?? ''),
+        truncate(String(page.title ?? '')),
+        String(page.kind ?? ''),
+        String(page.project ?? ''),
+        String(page.id ?? ''),
+    ]));
+    return [header, (0, output_1.section)('Contents', '📖'), toc].join('\n');
+}
 /**
  * Render the shared list/search table: TITLE, KIND, PROJECT, AUTHOR, UPDATED.
  *

package/dist/lib/limits.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Tetti di lunghezza dei campi di testo, come li applica il server (CYCL-32).
+ *
+ * Prima erano scoperti solo sbagliando: l'aiuto non li nominava e il rifiuto arrivava dopo aver
+ * scritto tutto. Qui vivono i numeri — copia dichiarata di `Knowledge::Constants`,
+ * `Ticketing::Constants` e `App::Constants::COMMENT_MAX_CHARS` — che le descrizioni dei flag
+ * mostrano e che i comandi verificano prima di spedire, così i campi troppo lunghi si scoprono
+ * tutti insieme e senza chiamare il server.
+ */
+export declare const LENGTH_LIMITS: {
+    /** Titolo di un ticket e di una pagina di conoscenza. */
+    readonly title: 255;
+    readonly description: 4000;
+    readonly technicalAnalysis: 1500;
+    readonly comment: 240;
+    readonly report: 20000;
+    readonly pageBody: 4000;
+    readonly techSpec: 1500;
+    readonly reviewNote: 240;
+};
+/** Un campo da misurare: il flag come lo scrive chi usa il comando, il valore e il suo tetto. */
+export interface LengthCheck {
+    flag: string;
+    value: unknown;
+    max: number;
+    /** Valore attualmente sul server, quando il comando lo ha letto (vedi `tooLongMessage`). */
+    previous?: unknown;
+    /** Campo che il server corregge in ortografia italiana prima di misurarlo (vedi `exceeds`). */
+    orthography?: boolean;
+}
+/**
+ * Caratteri di un testo contati come li conta il server (Ruby `String#length`, cioè per code point).
+ * La `.length` di JS conta unità UTF-16: un'emoji o qualunque carattere fuori dal BMP ne vale due, e
+ * la lunghezza mostrata divergerebbe da quella su cui il server misura il suo limite.
+ */
+export declare function charCount(value: unknown): number;
+/**
+ * Lunghezza sulla quale il server decide: il testo passa dalle sue normalizzazioni prima di essere
+ * misurato — CRLF ridotti a un solo a capo (`LengthBudget.normalize_newlines`) e spazi ai bordi via
+ * (`strip`). Senza questo un file con 100 righe scritto su Windows "peserebbe" 100 caratteri in più
+ * qui che là, e il comando rifiuterebbe un testo che il server accetta.
+ *
+ * `trim()` non è `String#strip`: toglie anche gli spazi Unicode che Ruby lascia (lo spazio unificatore
+ * in testa a una riga, per dire). Va nella direzione innocua — misura al più quanto il server, mai di
+ * più — quindi al massimo lascia partire una chiamata che il server rifiuterà, mai il contrario.
+ */
+export declare function serverLength(value: unknown): number;
+/**
+ * Il messaggio che elenca TUTTI i campi oltre il tetto, in un colpo solo — il punto della
+ * lavorazione: sistemarne uno e scoprire il successivo al tentativo dopo è esattamente ciò che
+ * questa funzione toglie di mezzo. `undefined` quando è tutto in regola.
+ *
+ * `previous` porta la clausola di salvaguardia del server (`LengthBudget`): un testo già oltre il
+ * tetto resta salvabile finché non si allunga, così chi ha in archivio una pagina o un ticket
+ * scritti prima del limite può ancora correggerli e accorciarli per gradi. I comandi che leggono lo
+ * stato attuale prima di scrivere lo passano; chi non lo conosce (una creazione, o `--replace`) lo
+ * lascia fuori e il tetto vale pieno.
+ */
+export declare function tooLongMessage(checks: LengthCheck[]): string | undefined;

package/dist/lib/limits.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LENGTH_LIMITS = void 0;
+exports.charCount = charCount;
+exports.serverLength = serverLength;
+exports.tooLongMessage = tooLongMessage;
+/**
+ * Tetti di lunghezza dei campi di testo, come li applica il server (CYCL-32).
+ *
+ * Prima erano scoperti solo sbagliando: l'aiuto non li nominava e il rifiuto arrivava dopo aver
+ * scritto tutto. Qui vivono i numeri — copia dichiarata di `Knowledge::Constants`,
+ * `Ticketing::Constants` e `App::Constants::COMMENT_MAX_CHARS` — che le descrizioni dei flag
+ * mostrano e che i comandi verificano prima di spedire, così i campi troppo lunghi si scoprono
+ * tutti insieme e senza chiamare il server.
+ */
+exports.LENGTH_LIMITS = {
+    /** Titolo di un ticket e di una pagina di conoscenza. */
+    title: 255,
+    description: 4_000,
+    technicalAnalysis: 1_500,
+    comment: 240,
+    report: 20_000,
+    pageBody: 4_000,
+    techSpec: 1_500,
+    reviewNote: 240,
+};
+/**
+ * Caratteri di un testo contati come li conta il server (Ruby `String#length`, cioè per code point).
+ * La `.length` di JS conta unità UTF-16: un'emoji o qualunque carattere fuori dal BMP ne vale due, e
+ * la lunghezza mostrata divergerebbe da quella su cui il server misura il suo limite.
+ */
+function charCount(value) {
+    return [...String(value ?? '')].length;
+}
+/**
+ * Lunghezza sulla quale il server decide: il testo passa dalle sue normalizzazioni prima di essere
+ * misurato — CRLF ridotti a un solo a capo (`LengthBudget.normalize_newlines`) e spazi ai bordi via
+ * (`strip`). Senza questo un file con 100 righe scritto su Windows "peserebbe" 100 caratteri in più
+ * qui che là, e il comando rifiuterebbe un testo che il server accetta.
+ *
+ * `trim()` non è `String#strip`: toglie anche gli spazi Unicode che Ruby lascia (lo spazio unificatore
+ * in testa a una riga, per dire). Va nella direzione innocua — misura al più quanto il server, mai di
+ * più — quindi al massimo lascia partire una chiamata che il server rifiuterà, mai il contrario.
+ */
+function serverLength(value) {
+    return charCount(String(value ?? '').replaceAll('\r\n', '\n').trim());
+}
+/**
+ * Quanto la correzione ortografica italiana del server può ancora accorciare il testo (CYCL-32).
+ *
+ * `Text::ItalianOrthography.correct` gira sui campi dei ticket e sul resoconto prima della misura, e
+ * sostituisce forme note con la loro versione accentata: «gia» → «già» non cambia la lunghezza,
+ * «perche'» → «perché» ne toglie una, perché assorbe l'apostrofo. Il dizionario non vive qui e non
+ * deve: il taglio massimo possibile è comunque UN carattere per apostrofo presente nel testo.
+ *
+ * Serve a non rifiutare in locale ciò che il server accetterebbe — un testo appena sopra il tetto e
+ * pieno di apostrofi da correggere ci rientra da solo. Sotto quel margine la misura resta al server.
+ */
+function orthographyMargin(value) {
+    return (value.match(/['’]/g) ?? []).length;
+}
+/**
+ * Il messaggio che elenca TUTTI i campi oltre il tetto, in un colpo solo — il punto della
+ * lavorazione: sistemarne uno e scoprire il successivo al tentativo dopo è esattamente ciò che
+ * questa funzione toglie di mezzo. `undefined` quando è tutto in regola.
+ *
+ * `previous` porta la clausola di salvaguardia del server (`LengthBudget`): un testo già oltre il
+ * tetto resta salvabile finché non si allunga, così chi ha in archivio una pagina o un ticket
+ * scritti prima del limite può ancora correggerli e accorciarli per gradi. I comandi che leggono lo
+ * stato attuale prima di scrivere lo passano; chi non lo conosce (una creazione, o `--replace`) lo
+ * lascia fuori e il tetto vale pieno.
+ */
+function tooLongMessage(checks) {
+    const over = checks.filter((check) => exceeds(check));
+    if (over.length === 0)
+        return undefined;
+    const list = over.map((check) => `${check.flag} is ${serverLength(check.value)} characters (max ${check.max})`);
+    return `Too long for the server: ${list.join('; ')}. Shorten ${over.length === 1 ? 'it' : 'them'} and run the command again.`;
+}
+/**
+ * Vero solo quando il rifiuto è CERTO: si misura la lunghezza più corta che il testo può avere una
+ * volta arrivato al server (correzione ortografica inclusa, dove il server la applica) e si tiene
+ * conto della salvaguardia sul valore attuale. Nel dubbio si tace e decide il server.
+ */
+function exceeds(check) {
+    const length = serverLength(check.value);
+    const shortest = check.orthography ? length - orthographyMargin(String(check.value ?? '')) : length;
+    if (shortest <= check.max)
+        return false;
+    const previous = serverLength(check.previous);
+    return !(previous > check.max && length <= previous);
+}

package/dist/lib/stdin.d.ts

@@ -1,3 +1,2 @@
-/** Read a whole stream (default: process.stdin) into a UTF-8 string. Used by `secrets import` to accept
- * piped input, e.g. `doppler secrets download --format json | cyi secrets import --format json`. */
+/** Read a whole stream (default: process.stdin) into a UTF-8 string for `secrets import`. */
 export declare function readStream(stream?: AsyncIterable<Buffer | string>): Promise<string>;

package/dist/lib/stdin.js

@@ -1,8 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readStream = readStream;
-/** Read a whole stream (default: process.stdin) into a UTF-8 string. Used by `secrets import` to accept
- * piped input, e.g. `doppler secrets download --format json | cyi secrets import --format json`. */
+/** Read a whole stream (default: process.stdin) into a UTF-8 string for `secrets import`. */
 async function readStream(stream = process.stdin) {
     const chunks = [];
     for await (const chunk of stream)

package/dist/lib/subprocess.d.ts

@@ -1,6 +1,6 @@
 /**
  * Run a child process inheriting stdio, resolving with its exit code. Unlike `openUrl` (browser.ts)
  * this is NOT detached/unref'd: `cyi run` must stay attached and propagate the child's exit code
- * (like `doppler run`). A terminating signal maps to a non-zero code.
+ * and propagate the child's exit code. A terminating signal maps to a non-zero code.
  */
 export declare function runCommand(command: string, args: string[], env: NodeJS.ProcessEnv): Promise<number>;

package/dist/lib/subprocess.js

@@ -5,7 +5,7 @@ const node_child_process_1 = require("node:child_process");
 /**
  * Run a child process inheriting stdio, resolving with its exit code. Unlike `openUrl` (browser.ts)
  * this is NOT detached/unref'd: `cyi run` must stay attached and propagate the child's exit code
- * (like `doppler run`). A terminating signal maps to a non-zero code.
+ * and propagate the child's exit code. A terminating signal maps to a non-zero code.
  */
 function runCommand(command, args, env) {
     return new Promise((resolve, reject) => {