@bussolabs/closeyourit-cli 0.0.13 → 0.0.15

package/README.md

@@ -64,6 +64,13 @@ organization are stored locally.
 | `metrics list --project <id\|key> [--kind] [--page]` | List metric groups. |
 | `metrics show <id> --project <id\|key>` | Show one metric group. |
 | `logs list [--project <id\|key>] [--level] [--trace-id] [--environment] [--page]` | List structured log entries. Cross-app: omit `--project` for the full visible stream. |
+| `kb list [--project <id\|key>] [--kind] [--per] [--page]` | List knowledge pages. Cross-project: omit `--project` for every visible project. |
+| `kb search <query…> [--project <id\|key>] [--kind] [--per] [--page]` | Search knowledge pages (semantic when available, title ILIKE fallback). |
+| `kb show <id>` | Show one knowledge page: metadata header + raw markdown body. |
+| `kb create --project <id\|key> --title <t> [--kind note\|decision\|guide] (--body <md> \| --body-file <path>)` | Create a knowledge page. |
+| `kb update <id> [--title] [--kind] [--body \| --body-file]` | Update a page (unpassed fields keep their current value). |
+| `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. |
 | `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). |

package/dist/commands/ideas/create.d.ts

@@ -4,7 +4,9 @@ export default class IdeasCreate extends BaseCommand {
     static examples: string[];
     static flags: {
         title: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
-        body: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        problem: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        solution: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        stakeholders: 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/ideas/create.js

@@ -6,17 +6,24 @@ const output_1 = require("../../lib/output");
 class IdeasCreate extends base_1.BaseCommand {
     static description = 'Propose an idea for a project';
     static examples = [
-        '<%= config.bin %> ideas create --project acme-api --title "Dark mode" --body "Dark theme for the dashboard"',
+        '<%= config.bin %> ideas create --project acme-api --title "Dark mode" --problem "The dashboard blinds users at night" --solution "System dark theme" --stakeholders "Mobile team" --stakeholders "Enterprise customers"',
     ];
     static flags = {
         ...base_1.projectFlag,
         title: core_1.Flags.string({ description: 'Idea title', required: true }),
-        body: core_1.Flags.string({ description: 'Idea proposal body', required: true }),
+        problem: core_1.Flags.string({ description: 'Problem or need the idea solves', required: true }),
+        solution: core_1.Flags.string({ description: 'Proposed solution (optional)' }),
+        stakeholders: core_1.Flags.string({ description: 'Who it helps — repeatable (optional)', multiple: true }),
     };
     async run() {
         const { flags } = await this.parse(IdeasCreate);
         const projectId = await this.resolveProjectId(flags.project);
-        const res = await this.api.post(`/cli/v1/projects/${projectId}/ideas`, { title: flags.title, body: flags.body });
+        const res = await this.api.post(`/cli/v1/projects/${projectId}/ideas`, {
+            title: flags.title,
+            problem: flags.problem,
+            solution: flags.solution,
+            stakeholders: flags.stakeholders ?? [],
+        });
         if (!this.jsonEnabled()) {
             this.log('Idea created:');
             this.log((0, output_1.renderRecord)(res.data ?? {}));

package/dist/commands/ideas/show.js

@@ -7,7 +7,7 @@ class IdeasShow extends base_1.BaseCommand {
     static args = {
         id: core_1.Args.string({ description: 'Idea id', required: true }),
     };
-    static description = 'Show an idea (fields + full proposal body)';
+    static description = 'Show an idea (fields + problem, solution, stakeholders)';
     static examples = ['<%= config.bin %> ideas show <idea-id> --project acme-api'];
     static flags = { ...base_1.projectFlag };
     async run() {
@@ -15,11 +15,18 @@ class IdeasShow extends base_1.BaseCommand {
         const projectId = await this.resolveProjectId(flags.project);
         const res = await this.api.get(`/cli/v1/projects/${projectId}/ideas/${args.id}`);
         if (!this.jsonEnabled()) {
-            const { body, ...fields } = res.data ?? {};
+            const { problem, solution, stakeholders, ...fields } = res.data ?? {};
             this.log((0, output_1.renderRecord)(fields));
-            if (body) {
-                this.log('\nProposal:');
-                this.log((0, output_1.sanitizeMultiline)(body));
+            if (Array.isArray(stakeholders) && stakeholders.length > 0) {
+                this.log(`\nStakeholders: ${stakeholders.join(', ')}`);
+            }
+            if (problem) {
+                this.log('\nProblem:');
+                this.log((0, output_1.sanitizeMultiline)(String(problem)));
+            }
+            if (solution) {
+                this.log('\nSolution:');
+                this.log((0, output_1.sanitizeMultiline)(String(solution)));
             }
         }
         return res;

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

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

package/dist/commands/kb/ask.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");
+class KbAsk extends base_1.BaseCommand {
+    // Variadic question: every positional word is joined into a single natural-language question.
+    static strict = false;
+    static description = 'Ask a natural-language question; the server AI answers from the knowledge base and cites the pages it used (may take a few seconds)';
+    static examples = [
+        '<%= config.bin %> kb ask how do we roll back a kamal deploy',
+        '<%= config.bin %> kb ask "what is our retry/backoff policy?" --json',
+    ];
+    // Non-required: with strict = false the arg validation is off, so we guard the empty case ourselves.
+    static args = {
+        question: core_1.Args.string({ description: 'The question (all positional words are joined)' }),
+    };
+    async run() {
+        const { argv } = await this.parse(KbAsk);
+        const question = argv.join(' ').trim();
+        if (question === '')
+            this.error('Provide a question (e.g. "kb ask how do we roll back a deploy").', { exit: 2 });
+        if (!this.jsonEnabled())
+            this.log('Asking the knowledge base (AI), this may take a few seconds…');
+        const res = await this.api.post('/cli/v1/knowledge/ask', { question });
+        const data = res.data ?? {};
+        if (!this.jsonEnabled()) {
+            if (data.insufficient) {
+                this.log('The knowledge base does not have enough to answer this confidently.');
+            }
+            const answer = String(data.answer ?? '').trim();
+            if (answer !== '')
+                this.log((0, output_1.sanitizeMultiline)(data.answer));
+            const pages = Array.isArray(data.pages) ? data.pages : [];
+            if (pages.length > 0) {
+                this.log('\nSources:');
+                for (const page of pages) {
+                    this.log(`  [${(0, output_1.sanitize)(page.kind)}] ${(0, output_1.sanitize)(page.title)} · ${(0, output_1.sanitize)(page.id)}`);
+                }
+            }
+        }
+        return res;
+    }
+}
+exports.default = KbAsk;

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

@@ -0,0 +1,13 @@
+import { BaseCommand } from '../../base';
+export default class KbCreate extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        title: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        kind: import("@oclif/core/lib/interfaces").OptionFlag<string, 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/create.js

@@ -0,0 +1,48 @@
+"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 output_1 = require("../../lib/output");
+class KbCreate extends base_1.BaseCommand {
+    static description = 'Create a knowledge page in a project';
+    static examples = [
+        '<%= config.bin %> kb create --project acme-api --title "Kamal rollback" --body "Steps…"',
+        '<%= config.bin %> kb create -p acme-api --title "ADR: queue backend" --kind decision --body-file ./adr.md',
+    ];
+    static flags = {
+        // Required — passed straight to the server as `project` (key or UUID), resolved there.
+        ...base_1.projectFlag,
+        title: core_1.Flags.string({ description: 'Page title', required: true }),
+        kind: core_1.Flags.string({ description: 'Page kind: note|decision|guide', default: 'note' }),
+        body: core_1.Flags.string({ description: 'Page body (markdown)' }),
+        'body-file': core_1.Flags.string({ description: 'Read the body (markdown) from a local file' }),
+    };
+    async run() {
+        const { flags } = await this.parse(KbCreate);
+        let body = flags.body;
+        if (body === undefined && flags['body-file'] !== undefined) {
+            try {
+                body = await (0, promises_1.readFile)(flags['body-file'], 'utf8');
+            }
+            catch {
+                this.error(`File not found or unreadable: ${flags['body-file']}`, { exit: 2 });
+            }
+        }
+        if (body === undefined) {
+            this.error('Provide the page body via --body or --body-file.', { exit: 2 });
+        }
+        const res = await this.api.post('/cli/v1/knowledge/pages', {
+            project: flags.project,
+            title: flags.title,
+            kind: flags.kind,
+            body,
+        });
+        if (!this.jsonEnabled()) {
+            this.log('Knowledge page created:');
+            this.log((0, output_1.renderRecord)(res.data ?? {}));
+        }
+        return res;
+    }
+}
+exports.default = KbCreate;

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

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

package/dist/commands/kb/delete.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../base");
+class KbDelete extends base_1.BaseCommand {
+    static description = 'Delete a knowledge page (irreversible)';
+    static examples = ['<%= config.bin %> kb delete <page-id> --confirm'];
+    static args = {
+        id: core_1.Args.string({ description: 'Knowledge page id', required: true }),
+    };
+    static flags = {
+        confirm: core_1.Flags.boolean({ description: 'Required: confirm the irreversible deletion' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(KbDelete);
+        if (!flags.confirm) {
+            this.error('Refusing to delete without --confirm (the action is irreversible).', { exit: 2 });
+        }
+        await this.api.delete(`/cli/v1/knowledge/pages/${encodeURIComponent(args.id)}`);
+        if (!this.jsonEnabled())
+            this.log(`Deleted knowledge page ${args.id}`);
+        return { deleted: args.id };
+    }
+}
+exports.default = KbDelete;

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

@@ -0,0 +1,12 @@
+import { BaseCommand } from '../../base';
+export default class KbList 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>;
+        kind: 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/list.js

@@ -0,0 +1,35 @@
+"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 KbList extends base_1.BaseCommand {
+    static description = 'List knowledge pages across the projects you can see';
+    static examples = [
+        '<%= config.bin %> kb list',
+        '<%= config.bin %> kb list --project acme-api --kind decision',
+        '<%= config.bin %> kb list --kind note,guide --per 50 --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)' }),
+        kind: core_1.Flags.string({ description: 'Filter by kind: note|decision|guide (repeatable or comma-separated)', multiple: true }),
+        per: core_1.Flags.integer({ description: 'Page size' }),
+        ...base_1.pageFlag,
+    };
+    async run() {
+        const { flags } = await this.parse(KbList);
+        const query = (0, knowledge_1.buildPagesQuery)({
+            kinds: (0, knowledge_1.normalizeKinds)(flags.kind),
+            page: flags.page,
+            per: flags.per,
+            project: flags.project,
+        });
+        const res = await this.api.get(`/cli/v1/knowledge/pages?${query}`);
+        if (!this.jsonEnabled()) {
+            this.log((0, knowledge_1.renderPagesTable)(res.data ?? []));
+        }
+        return res;
+    }
+}
+exports.default = KbList;

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

@@ -0,0 +1,16 @@
+import { BaseCommand } from '../../base';
+export default class KbSearch extends BaseCommand {
+    static strict: boolean;
+    static description: string;
+    static examples: string[];
+    static args: {
+        query: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    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>;
+        kind: 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/search.js

@@ -0,0 +1,48 @@
+"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 KbSearch extends base_1.BaseCommand {
+    // Variadic query: every positional word is joined into a single search string.
+    static strict = false;
+    static description = 'Search knowledge pages (semantic when available, ILIKE fallback on the title otherwise)';
+    static examples = [
+        '<%= config.bin %> kb search kamal deploy rollback',
+        '<%= config.bin %> kb search "connection pool timeout" --project acme-api',
+        '<%= config.bin %> kb search retry backoff --kind decision --json',
+    ];
+    // Non-required: with strict = false the arg validation is off, so we guard the empty case ourselves.
+    static args = {
+        query: core_1.Args.string({ description: 'Search query (all positional words are joined)' }),
+    };
+    static flags = {
+        project: core_1.Flags.string({ char: 'p', description: 'Filter by project (key or UUID)' }),
+        kind: core_1.Flags.string({ description: 'Filter by kind: note|decision|guide (repeatable or comma-separated)', multiple: true }),
+        per: core_1.Flags.integer({ description: 'Page size' }),
+        ...base_1.pageFlag,
+    };
+    async run() {
+        const { argv, flags } = await this.parse(KbSearch);
+        const q = argv.join(' ').trim();
+        if (q === '')
+            this.error('Provide a search query (e.g. "kb search kamal rollback").', { exit: 2 });
+        const query = (0, knowledge_1.buildPagesQuery)({
+            kinds: (0, knowledge_1.normalizeKinds)(flags.kind),
+            page: flags.page,
+            per: flags.per,
+            project: flags.project,
+            q,
+        });
+        const res = await this.api.get(`/cli/v1/knowledge/pages?${query}`);
+        if (!this.jsonEnabled()) {
+            // meta.search tells us whether the server ran a semantic query or fell back to a title ILIKE.
+            if (res.meta?.search === 'like') {
+                this.log('(semantic search unavailable — showing title matches)');
+            }
+            this.log((0, knowledge_1.renderPagesTable)(res.data ?? []));
+        }
+        return res;
+    }
+}
+exports.default = KbSearch;

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

@@ -0,0 +1,9 @@
+import { BaseCommand } from '../../base';
+export default class KbShow 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/show.js

@@ -0,0 +1,40 @@
+"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");
+class KbShow extends base_1.BaseCommand {
+    static description = 'Show a single knowledge page: metadata header then the raw markdown body';
+    static examples = [
+        '<%= config.bin %> kb show <page-id>',
+        '<%= config.bin %> kb show <page-id> --json',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Knowledge page id', required: true }),
+    };
+    async run() {
+        const { args } = await this.parse(KbShow);
+        const res = await this.api.get(`/cli/v1/knowledge/pages/${encodeURIComponent(args.id)}`);
+        const page = res.data ?? {};
+        if (!this.jsonEnabled()) {
+            // Header first (scalar fields only), then the body on its own so the markdown stays intact.
+            this.log((0, output_1.renderRecord)({
+                id: page.id,
+                title: page.title,
+                kind: page.kind,
+                project: page.project,
+                project_name: page.project_name,
+                author: page.author,
+                created_at: page.created_at,
+                updated_at: page.updated_at,
+            }));
+            const body = page.body;
+            if (body !== null && body !== undefined && String(body).trim() !== '') {
+                this.log('');
+                this.log((0, output_1.sanitizeMultiline)(body));
+            }
+        }
+        return res;
+    }
+}
+exports.default = KbShow;

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

@@ -0,0 +1,15 @@
+import { BaseCommand } from '../../base';
+export default class KbUpdate extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        title: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, 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>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/kb/update.js

@@ -0,0 +1,53 @@
+"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 output_1 = require("../../lib/output");
+class KbUpdate extends base_1.BaseCommand {
+    static description = 'Update a knowledge page (only the fields you pass; the others keep their current value)';
+    static examples = [
+        '<%= config.bin %> kb update <page-id> --title "New title"',
+        '<%= config.bin %> kb update <page-id> --kind decision --body-file ./adr.md',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Knowledge page id', required: true }),
+    };
+    static flags = {
+        title: core_1.Flags.string({ description: 'New title' }),
+        kind: core_1.Flags.string({ description: 'New kind: note|decision|guide' }),
+        body: core_1.Flags.string({ description: 'New body (markdown)' }),
+        'body-file': core_1.Flags.string({ description: 'Read the new body (markdown) from a local file' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(KbUpdate);
+        let body = flags.body;
+        if (body === undefined && flags['body-file'] !== undefined) {
+            try {
+                body = await (0, promises_1.readFile)(flags['body-file'], 'utf8');
+            }
+            catch {
+                this.error(`File not found or unreadable: ${flags['body-file']}`, { exit: 2 });
+            }
+        }
+        if (flags.title === undefined && flags.kind === undefined && body === undefined) {
+            this.error('Provide at least one of --title, --kind, --body or --body-file.', { exit: 2 });
+        }
+        // The backend expects the full title/body/kind on update → read the current page and merge,
+        // so a partial edit (e.g. only --title) doesn't blank out the other fields.
+        const base = `/cli/v1/knowledge/pages/${encodeURIComponent(args.id)}`;
+        const current = await this.api.get(base);
+        const page = current.data ?? {};
+        const res = await this.api.put(base, {
+            title: flags.title ?? page.title,
+            kind: flags.kind ?? page.kind,
+            body: body ?? page.body,
+        });
+        if (!this.jsonEnabled()) {
+            this.log('Knowledge page updated:');
+            this.log((0, output_1.renderRecord)(res.data ?? {}));
+        }
+        return res;
+    }
+}
+exports.default = KbUpdate;

package/dist/lib/knowledge.d.ts

@@ -0,0 +1,22 @@
+/** Knowledge page kinds accepted by the backend (Knowledge::Page). */
+export declare const KNOWLEDGE_KINDS: readonly ["note", "decision", "guide"];
+/**
+ * Flatten a repeatable + comma-separated `--kind` flag into a clean list.
+ * `--kind note --kind decision,guide` → ['note', 'decision', 'guide'].
+ */
+export declare function normalizeKinds(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;
+/**
+ * Build the shared query string for `kb list` / `kb search`. Kinds go out as the
+ * `kind[]` array param; `page` is always sent, `per`/`project`/`q` only when set.
+ */
+export declare function buildPagesQuery(opts: {
+    kinds: string[];
+    page: number;
+    per?: number;
+    project?: string;
+    q?: string;
+}): string;
+/** Render the shared list/search table: TITLE, KIND, PROJECT, AUTHOR, UPDATED. */
+export declare function renderPagesTable(pages: Array<Record<string, unknown>>): string;

package/dist/lib/knowledge.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWLEDGE_KINDS = void 0;
+exports.normalizeKinds = normalizeKinds;
+exports.truncate = truncate;
+exports.buildPagesQuery = buildPagesQuery;
+exports.renderPagesTable = renderPagesTable;
+const output_1 = require("./output");
+/** Knowledge page kinds accepted by the backend (Knowledge::Page). */
+exports.KNOWLEDGE_KINDS = ['note', 'decision', 'guide'];
+/**
+ * Flatten a repeatable + comma-separated `--kind` flag into a clean list.
+ * `--kind note --kind decision,guide` → ['note', 'decision', 'guide'].
+ */
+function normalizeKinds(values) {
+    if (!values)
+        return [];
+    return values
+        .flatMap((value) => value.split(','))
+        .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();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+/**
+ * Build the shared query string for `kb list` / `kb search`. Kinds go out as the
+ * `kind[]` array param; `page` is always sent, `per`/`project`/`q` only when set.
+ */
+function buildPagesQuery(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);
+    for (const kind of opts.kinds)
+        query.append('kind[]', kind);
+    if (opts.q)
+        query.set('q', opts.q);
+    return query.toString();
+}
+/** Render the shared list/search table: TITLE, KIND, PROJECT, AUTHOR, UPDATED. */
+function renderPagesTable(pages) {
+    return (0, output_1.renderTable)(['TITLE', 'KIND', 'PROJECT', 'AUTHOR', 'UPDATED'], pages.map((page) => [
+        truncate(String(page.title ?? '')),
+        String(page.kind ?? ''),
+        String(page.project ?? ''),
+        String(page.author ?? ''),
+        String(page.updated_at ?? ''),
+    ]));
+}