@bussolabs/closeyourit-cli 0.20.0 → 0.21.0

package/README.md

@@ -142,10 +142,14 @@ CLOSEYOURIT_TOKEN=cyi_u_… CLOSEYOURIT_API_URL=https://www.closeyour.it \
 | `kb show <id> [--related] [--question <q>]` | Show one knowledge page: metadata header, raw markdown body, then the technical section. |
 | `kb related <id> [--question <q>] [--links-only]` | Pages to read next: linked with `[[wiki links]]` plus close matches by meaning. |
 | `kb create --project <id\|key> --title <t> [--kind note\|decision\|guide] (--body <md> \| --body-file <path>) [--tech-spec <md> \| --tech-spec-file <path>] [--in-review] [--review-note <line>]` | Create a knowledge page (optional technical section, kept separate from the body). Length caps: title 255, body 4000, technical section 1500, review note 240 characters — every field over the cap is listed at once, before the call. With `--in-review` the page waits for a human and stays out of search, answers and related panels. |
+| `kb publish --project <id\|key> --publication-key <key> --title <t> [--kind note\|decision\|guide] (--body <md> \| --body-file <path>)` | Create or update a knowledge page in one atomic call, keyed by a stable `--publication-key` (1-255 URL-safe characters). Safe to repeat: the same key always lands on the same page, and the output says whether it was `created` or `updated`. Exactly one body source is required. Omitting `--kind` keeps the kind the page already has (a new page is a `note`). Same title/body caps as `kb create`. |
 | `kb consolidate <id> --path <doc-path>` | Mark an accepted page as written to the versioned docs, recording where the document lives. |
 | `kb update <id> [--title] [--kind] [--body \| --body-file] [--tech-spec \| --tech-spec-file]` | Update a page (unpassed fields keep their current value). Same length caps as `kb create`; text already over the cap is refused only if it grows. |
 | `kb delete <id> --confirm` | Delete a knowledge page (irreversible). |
 | `kb ask <question…>` | Ask a question; the AI answers from the knowledge base and cites the pages it used. |
+| `kb book list [--project <id\|key>] [--q <text>] [--per] [--page]` | List knowledge books (ordered collections of pages). Cross-project: omit `--project` for every visible project. |
+| `kb book show <id>` | Show a book: metadata, then the summary of the pages it collects (`#` is the 0-based position). |
+| `kb book add-page <id> --page <page-id> [--position <n>]` | Add a page to a book's summary. `--page` takes a page **id** (alias: `--page-id`), not a page number; `--position` is 0-based (`0` = top, omitted = last), like the position the summary shows back. Idempotent: repeating it never lists the page twice. |
 | `servers list [--status] [--page]` | List the monitored servers (fleet snapshot: status, cpu/mem/disk, last seen). |
 | `servers show <id>` | Show a monitored server (latest snapshot + machine details). |
 | `servers rename <id> --name <name>` | Rename a server (display name only). |
@@ -232,6 +236,12 @@ CLOSEYOURIT_TOKEN=cyi_u_… CLOSEYOURIT_API_URL=https://www.closeyour.it \
 Every command accepts `--json` for machine-readable output and `--help` for usage details.
 `--project` accepts either a project UUID or its key (matched case-insensitively).
 
+`kb publish` needs a backend exposing the atomic Knowledge publication route; an older one fails with
+`C404-KNW-001` and says to upgrade. An unknown project key fails locally with `C404-PRJ-001`; the
+backend `R404-KNOWLEDGE-001` is reserved for a project UUID that is missing or not visible to the
+caller. `R403-KNOWLEDGE-003` means the key already belongs to a page you cannot manage, and
+`R409-KNOWLEDGE-001` that two untagged pages share the title the key would adopt.
+
 When a command fails in `--json` mode it exits non-zero and prints an error envelope on stdout —
 never a silent success:
 

package/dist/base.d.ts

@@ -15,6 +15,17 @@ export declare const environmentFlag: {
 export declare const pageFlag: {
     page: Interfaces.OptionFlag<number, Interfaces.CustomOptions>;
 };
+/**
+ * Message for a `--page`/`--per` outside the sensible range, or undefined when both are fine.
+ *
+ * The backend silently clamps them (`Pagination`): `--per 0` quietly returns the default page size
+ * and `--page 0` returns page 1, so a script that computed the wrong number gets plausible data
+ * back instead of an error. Say it before the call, and exit 2 like any other rejected command line.
+ */
+export declare function paginationError(opts: {
+    page?: number;
+    per?: number;
+}): string | undefined;
 export declare abstract class BaseCommand extends Command {
     static enableJsonFlag: boolean;
     protected cfg: CliConfig;

package/dist/base.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseCommand = exports.pageFlag = exports.environmentFlag = exports.projectFlag = exports.UUID_RE = void 0;
+exports.paginationError = paginationError;
 const core_1 = require("@oclif/core");
 const config_1 = require("./lib/config");
 const api_1 = require("./lib/api");
@@ -21,6 +22,20 @@ exports.environmentFlag = {
 exports.pageFlag = {
     page: core_1.Flags.integer({ description: 'Page number', default: 1 }),
 };
+/**
+ * Message for a `--page`/`--per` outside the sensible range, or undefined when both are fine.
+ *
+ * The backend silently clamps them (`Pagination`): `--per 0` quietly returns the default page size
+ * and `--page 0` returns page 1, so a script that computed the wrong number gets plausible data
+ * back instead of an error. Say it before the call, and exit 2 like any other rejected command line.
+ */
+function paginationError(opts) {
+    if (opts.page !== undefined && opts.page < 1)
+        return `Invalid --page ${opts.page}: the first page is 1.`;
+    if (opts.per !== undefined && opts.per < 1)
+        return `Invalid --per ${opts.per}: ask for at least 1 row.`;
+    return undefined;
+}
 class BaseCommand extends core_1.Command {
     static enableJsonFlag = true;
     cfg;

package/dist/commands/kb/book/add-page.d.ts

@@ -0,0 +1,18 @@
+import { BaseCommand } from '../../../base';
+/**
+ * Put one page in a book's summary. Idempotent server-side: repeating the same call leaves the
+ * summary as it is (the page is moved, never added twice), which is what makes it safe for an
+ * automation that cannot know whether the previous run got through.
+ */
+export default class KbBookAddPage extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        page: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        position: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/kb/book/add-page.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../../base");
+const knowledge_1 = require("../../../lib/knowledge");
+/**
+ * Put one page in a book's summary. Idempotent server-side: repeating the same call leaves the
+ * summary as it is (the page is moved, never added twice), which is what makes it safe for an
+ * automation that cannot know whether the previous run got through.
+ */
+class KbBookAddPage extends base_1.BaseCommand {
+    static description = 'Add a knowledge page to a book, optionally at a given position in the summary';
+    static examples = [
+        '<%= config.bin %> kb book add-page <book-id> --page <page-id>',
+        '<%= config.bin %> kb book add-page <book-id> --page <page-id> --position 0',
+        '<%= config.bin %> kb book add-page <book-id> --page <page-id> --json',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Knowledge book id', required: true }),
+    };
+    static flags = {
+        // `--page` is the name the Automator already calls (closeyourit-automator, lib/book.ts
+        // `assignPage`), and this command has no pagination, so there is nothing to collide with. It
+        // still takes a page *id*, unlike the `--page` of every list command: `--page-id` is accepted
+        // as an alias so a human can be explicit about that.
+        page: core_1.Flags.string({
+            aliases: ['page-id'],
+            description: 'Id of the knowledge page to add (an id, not a page number; alias: --page-id)',
+            required: true,
+        }),
+        // 0-based, like the server (Knowledge::Books::AddPage) and like the `position` the summary
+        // shows back. A caller counting from 1 must subtract one: passing its own number would put the
+        // page one slot too low, and the backend clamps instead of refusing.
+        position: core_1.Flags.integer({ description: 'Where to put it in the summary (0 = top; omit to append at the end)' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(KbBookAddPage);
+        if (flags.position !== undefined && flags.position < 0) {
+            this.error(`Invalid --position ${flags.position}: the summary starts at 0 (the top).`, { exit: 2 });
+        }
+        // `!== undefined`, not a truthiness test: position 0 is the top of the summary, not "unset".
+        const body = { page_id: flags.page };
+        if (flags.position !== undefined)
+            body.position = flags.position;
+        const res = await this.api.post(`/cli/v1/knowledge/books/${encodeURIComponent(args.id)}/pages`, body);
+        if (!this.jsonEnabled()) {
+            // "updated", not "added": the call is idempotent, so on a repeat nothing was inserted — what
+            // is worth showing either way is the resulting order.
+            this.log('Book summary updated:');
+            this.log((0, knowledge_1.renderBook)(res.data ?? {}));
+        }
+        return res;
+    }
+}
+exports.default = KbBookAddPage;

package/dist/commands/kb/book/list.d.ts

@@ -0,0 +1,12 @@
+import { BaseCommand } from '../../../base';
+export default class KbBookList extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        page: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+        project: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        q: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        per: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/kb/book/list.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../../base");
+const knowledge_1 = require("../../../lib/knowledge");
+class KbBookList extends base_1.BaseCommand {
+    static description = 'List knowledge books (ordered collections of pages) across the projects you can see';
+    static examples = [
+        '<%= config.bin %> kb book list',
+        '<%= config.bin %> kb book list --project acme-api',
+        '<%= config.bin %> kb book list --q deploy --per 50',
+        '<%= config.bin %> kb book list --json',
+    ];
+    static flags = {
+        // Optional (the endpoint is cross-project): omit it to span every visible project.
+        project: core_1.Flags.string({ char: 'p', description: 'Filter by project (key or UUID)' }),
+        q: core_1.Flags.string({ description: 'Filter by title (substring, case-insensitive)' }),
+        per: core_1.Flags.integer({ description: 'Page size' }),
+        ...base_1.pageFlag,
+    };
+    async run() {
+        const { flags } = await this.parse(KbBookList);
+        const invalid = (0, base_1.paginationError)(flags);
+        if (invalid)
+            this.error(invalid, { exit: 2 });
+        const res = await this.api.get(`/cli/v1/knowledge/books?${(0, knowledge_1.buildBooksQuery)(flags)}`);
+        if (!this.jsonEnabled()) {
+            this.log((0, knowledge_1.renderBooksTable)(res.data ?? []));
+        }
+        return res;
+    }
+}
+exports.default = KbBookList;

package/dist/commands/kb/book/show.d.ts

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

package/dist/commands/kb/book/show.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../../base");
+const knowledge_1 = require("../../../lib/knowledge");
+class KbBookShow extends base_1.BaseCommand {
+    static description = 'Show a knowledge book: its metadata, then the summary of the pages it collects';
+    static examples = ['<%= config.bin %> kb book show <book-id>', '<%= config.bin %> kb book show <book-id> --json'];
+    static args = {
+        id: core_1.Args.string({ description: 'Knowledge book id', required: true }),
+    };
+    async run() {
+        const { args } = await this.parse(KbBookShow);
+        const res = await this.api.get(`/cli/v1/knowledge/books/${encodeURIComponent(args.id)}`);
+        // The summary only lists the pages of the projects the reader can see, so a multi-project book
+        // never shows titles from a project this account has no access to.
+        if (!this.jsonEnabled())
+            this.log((0, knowledge_1.renderBook)(res.data ?? {}));
+        return res;
+    }
+}
+exports.default = KbBookShow;

package/dist/commands/kb/publish.d.ts

@@ -0,0 +1,15 @@
+import { BaseCommand } from '../../base';
+export default class KbPublish extends BaseCommand {
+    static description: string;
+    static usage: string;
+    static examples: string[];
+    static flags: {
+        'publication-key': import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        title: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        kind: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        body: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'body-file': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        project: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/kb/publish.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const promises_1 = require("node:fs/promises");
+const core_1 = require("@oclif/core");
+const base_1 = require("../../base");
+const error_codes_1 = require("../../errors/error-codes");
+const api_1 = require("../../lib/api");
+const limits_1 = require("../../lib/limits");
+const output_1 = require("../../lib/output");
+// Copia dichiarata di `Knowledge::Page::PUBLICATION_KEY_FORMAT`: una chiave malformata è l'unico
+// errore che si può riconoscere senza chiamare il server, e riconoscerlo qui evita di scoprire a
+// metà di un ciclo di retry che tutte le chiamate erano destinate a un 422.
+const PUBLICATION_KEY_RE = /^[A-Za-z0-9][A-Za-z0-9._~:-]{0,254}$/;
+// Un errore che il backend ha davvero formulato: `error-codes.ts` riserva le iniziali R/G ai codici
+// applicativi e li propaga intatti, mentre tutto ciò che inizia per C lo ha coniato la CLI davanti a
+// una risposta che non parlava — corpo non JSON (`C000-NET-001`) o envelope senza codice
+// (`C404-API-000`), che è la forma in cui si presenta una route inesistente.
+const BACKEND_CODE_RE = /^[RG]/;
+class KbPublish extends base_1.BaseCommand {
+    static description = `Idempotently create or update a Knowledge page by publication key.
+
+Exactly one of --body or --body-file is required.`;
+    static usage = '-p <project> --publication-key <key> --title <title> [--kind <kind>] (--body <markdown> | --body-file <path>)';
+    static examples = [
+        '<%= config.bin %> kb publish --project CYCL --publication-key docs:release --title "Release guide" --body "Steps…"',
+        '<%= config.bin %> kb publish -p CYCL --publication-key docs:release --title "Release guide" --kind guide --body-file ./release.md',
+    ];
+    static flags = {
+        ...base_1.projectFlag,
+        'publication-key': core_1.Flags.string({
+            description: 'Stable publication key (1-255 URL-safe characters)',
+            required: true,
+        }),
+        title: core_1.Flags.string({ description: `Page title (max ${limits_1.LENGTH_LIMITS.title} characters)`, required: true }),
+        // Nessun default qui: il server mette `note` solo quando la pagina nasce e altrimenti tiene il
+        // kind che ha già. Spedire `note` a ogni chiamata declasserebbe una guida a nota al primo
+        // publish ripetuto senza `--kind`, che è esattamente ciò che una fonte idempotente non deve fare.
+        kind: core_1.Flags.string({ description: 'Page kind: note|decision|guide (new page: note; existing: unchanged)' }),
+        body: core_1.Flags.string({
+            description: `Page body (markdown, max ${limits_1.LENGTH_LIMITS.pageBody} characters); exactly one of --body or --body-file is required`,
+            exactlyOne: ['body', 'body-file'],
+        }),
+        'body-file': core_1.Flags.string({
+            description: `Read the page body (markdown, max ${limits_1.LENGTH_LIMITS.pageBody} characters) from a local file; exactly one of --body or --body-file is required`,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(KbPublish);
+        const publicationKey = flags['publication-key'];
+        if (!PUBLICATION_KEY_RE.test(publicationKey)) {
+            this.error('Invalid --publication-key: use 1-255 characters, start with a letter or number, then only letters, numbers, . _ ~ : -.', { exit: 2 });
+        }
+        let body;
+        let bodyFlag = '--body';
+        if (flags.body === undefined) {
+            bodyFlag = '--body-file';
+            try {
+                body = await (0, promises_1.readFile)(flags['body-file'], 'utf8');
+            }
+            catch {
+                this.error(`File not found or unreadable: ${flags['body-file']}`, { exit: 2 });
+            }
+        }
+        else {
+            body = flags.body;
+        }
+        // Il publish è un upsert atomico e non rilegge la pagina prima di scrivere: senza un valore
+        // attuale da usare come salvaguardia il tetto vale pieno, come su `kb create` (CYCL-32).
+        const tooLong = (0, limits_1.tooLongMessage)([
+            { flag: '--title', value: flags.title, max: limits_1.LENGTH_LIMITS.title },
+            { flag: bodyFlag, value: body, max: limits_1.LENGTH_LIMITS.pageBody },
+        ]);
+        if (tooLong)
+            this.error(tooLong, { exit: 2 });
+        const projectId = await this.resolveProjectId(flags.project);
+        const path = `/cli/v1/projects/${projectId}/knowledge/publications/${encodeURIComponent(publicationKey)}`;
+        // `kind` esce dal payload quando non è stato passato: il server distingue "non me l'hai detto"
+        // (tiene quello che ha) da un valore esplicito, e una chiave presente ma vuota non è la stessa cosa.
+        const payload = { title: flags.title, ...(flags.kind === undefined ? {} : { kind: flags.kind }), body };
+        let res;
+        try {
+            res = await this.api.put(path, payload);
+        }
+        catch (error) {
+            // Un 404 che il backend non ha formulato è la route che non c'è: su un server più vecchio
+            // della pubblicazione atomica il messaggio dice cosa aggiornare, invece di far sembrare
+            // sparito il progetto. Ogni 404 applicativo passa intatto — R404-KNOWLEDGE-001 per il progetto
+            // invisibile e chiunque altro il backend aggiunga dopo, che qui non va mascherato.
+            if (error instanceof api_1.ApiRequestError && error.status === 404 && !BACKEND_CODE_RE.test(error.code)) {
+                throw new api_1.ApiRequestError(404, error_codes_1.ErrorCodes.Knowledge.publishUnavailable, 'Knowledge publish is not supported by this backend. Upgrade CloseYourIt and retry.');
+            }
+            throw error;
+        }
+        if (!this.jsonEnabled()) {
+            const meta = (res.meta ?? {});
+            const operation = meta.operation === 'created' ? 'created' : 'updated';
+            // Il corpo è appena stato scritto da chi ha lanciato il comando: ristamparlo per intero
+            // seppellirebbe l'unica cosa nuova, cioè se la pagina è nata ora o è stata aggiornata.
+            const { body: _body, ...page } = res.data ?? {};
+            this.log(`Knowledge publication ${operation}:`);
+            this.log((0, output_1.renderRecord)({ ...page, operation: meta.operation, adopted_legacy: meta.adopted_legacy }));
+        }
+        return res;
+    }
+}
+exports.default = KbPublish;

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

@@ -25,6 +25,9 @@ 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";
     };

package/dist/errors/error-codes.js

@@ -30,6 +30,11 @@ 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: {

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.
  *