@bussolabs/closeyourit-cli 0.7.3 → 0.8.0

package/README.md

@@ -116,8 +116,9 @@ CLOSEYOURIT_TOKEN=cyi_u_… CLOSEYOURIT_API_URL=https://www.closeyour.it \
 | `logs link <id> --to <Errors::Group:uuid\|Ticketing::Ticket:uuid>` | Manually link a log entry to an error group or ticket. |
 | `logs unlink <id> <link-id> --confirm` | Remove a manual log link. |
 | `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 search <query…> [--project <id\|key>] [--kind] [--per] [--page] [--with-related]` | Search knowledge pages (semantic when available, title ILIKE fallback). |
+| `kb show <id> [--related] [--question <q>]` | Show one knowledge page: metadata header + raw markdown body. |
+| `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>)` | 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). |

package/dist/commands/kb/ask.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
 const base_1 = require("../../base");
+const knowledge_1 = require("../../lib/knowledge");
 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.
@@ -38,6 +39,10 @@ class KbAsk extends base_1.BaseCommand {
                     this.log(`  [${(0, output_1.sanitize)(page.kind)}] ${(0, output_1.sanitize)(page.title)} · ${(0, output_1.sanitize)(page.id)}`);
                 }
             }
+            // Second hop: what the cited pages point to, kept only when it matches the question.
+            const related = Array.isArray(data.related) ? data.related : [];
+            if (related.length > 0)
+                this.log((0, knowledge_1.renderRelated)(related));
         }
         return res;
     }

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

@@ -0,0 +1,13 @@
+import { BaseCommand } from '../../base';
+export default class KbRelated extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        question: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'links-only': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/kb/related.js

@@ -0,0 +1,37 @@
+"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 KbRelated extends base_1.BaseCommand {
+    static description = 'List the pages to read next: the ones this page links to (and that link to it), plus close matches by meaning';
+    static examples = [
+        '<%= config.bin %> kb related <page-id>',
+        '<%= config.bin %> kb related <page-id> --question "how do we roll back a deploy?"',
+        '<%= config.bin %> kb related <page-id> --links-only --json',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Knowledge page id', required: true }),
+    };
+    static flags = {
+        // With a question the server scores every candidate against it and drops what does not match.
+        question: core_1.Flags.string({ description: 'Keep only the pages relevant to this question' }),
+        'links-only': core_1.Flags.boolean({ description: 'Only pages linked with [[wiki links]], no close matches' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(KbRelated);
+        const query = new URLSearchParams();
+        if (flags.question)
+            query.set('question', flags.question);
+        if (flags['links-only'])
+            query.set('links_only', '1');
+        const suffix = query.toString() === '' ? '' : `?${query.toString()}`;
+        const res = await this.api.get(`/cli/v1/knowledge/pages/${encodeURIComponent(args.id)}/related${suffix}`);
+        const rows = res.data ?? [];
+        if (!this.jsonEnabled()) {
+            this.log(rows.length === 0 ? 'No related pages.' : (0, knowledge_1.renderRelated)(rows, '🔗 Related:'));
+        }
+        return res;
+    }
+}
+exports.default = KbRelated;

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

@@ -11,6 +11,7 @@ export default class KbSearch extends BaseCommand {
         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>;
+        'with-related': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<unknown>;
 }

package/dist/commands/kb/search.js

@@ -10,6 +10,7 @@ class KbSearch extends base_1.BaseCommand {
     static examples = [
         '<%= config.bin %> kb search kamal deploy rollback',
         '<%= config.bin %> kb search "connection pool timeout" --project acme-api',
+        '<%= config.bin %> kb search kamal rollback --with-related',
         '<%= 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.
@@ -20,6 +21,8 @@ class KbSearch extends base_1.BaseCommand {
         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' }),
+        // Opt-in: the server only computes this when asked, for the first few results.
+        'with-related': core_1.Flags.boolean({ description: 'Also show the pages each result links to' }),
         ...base_1.pageFlag,
     };
     async run() {
@@ -33,14 +36,20 @@ class KbSearch extends base_1.BaseCommand {
             per: flags.per,
             project: flags.project,
             q,
+            related: flags['with-related'],
         });
         const res = await this.api.get(`/cli/v1/knowledge/pages?${query}`);
+        const pages = res.data ?? [];
         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 ?? []));
+            this.log((0, knowledge_1.renderPagesTable)(pages));
+            const grouped = (res.meta?.related ?? {});
+            const block = (0, knowledge_1.renderRelatedGroups)(pages, grouped);
+            if (block !== '')
+                this.log(block);
         }
         return res;
     }

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

@@ -5,5 +5,9 @@ export default class KbShow extends BaseCommand {
     static args: {
         id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
     };
+    static flags: {
+        related: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        question: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
     run(): Promise<unknown>;
 }

package/dist/commands/kb/show.js

@@ -2,19 +2,32 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
 const base_1 = require("../../base");
+const knowledge_1 = require("../../lib/knowledge");
 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> --question "how do we roll back a deploy?"',
         '<%= config.bin %> kb show <page-id> --json',
     ];
     static args = {
         id: core_1.Args.string({ description: 'Knowledge page id', required: true }),
     };
+    static flags = {
+        // Opt-in: without these flags the request is exactly what it has always been.
+        related: core_1.Flags.boolean({ description: 'Also list the pages to read next' }),
+        question: core_1.Flags.string({ description: 'Keep only the related pages relevant to this question (implies --related)' }),
+    };
     async run() {
-        const { args } = await this.parse(KbShow);
-        const res = await this.api.get(`/cli/v1/knowledge/pages/${encodeURIComponent(args.id)}`);
+        const { args, flags } = await this.parse(KbShow);
+        const query = new URLSearchParams();
+        if (flags.question)
+            query.set('question', flags.question);
+        else if (flags.related)
+            query.set('related', '1');
+        const suffix = query.toString() === '' ? '' : `?${query.toString()}`;
+        const res = await this.api.get(`/cli/v1/knowledge/pages/${encodeURIComponent(args.id)}${suffix}`);
         const page = res.data ?? {};
         if (!this.jsonEnabled()) {
             // Header first (scalar fields only), then the body on its own so the markdown stays intact.
@@ -33,6 +46,9 @@ class KbShow extends base_1.BaseCommand {
                 this.log('');
                 this.log((0, output_1.sanitizeMultiline)(body));
             }
+            const related = (res.meta?.related ?? []);
+            if (related.length > 0)
+                this.log((0, knowledge_1.renderRelated)(related));
         }
         return res;
     }

package/dist/lib/knowledge.d.ts

@@ -17,6 +17,28 @@ export declare function buildPagesQuery(opts: {
     per?: number;
     project?: string;
     q?: string;
+    related?: boolean;
 }): string;
+/** A related-page row as returned by the server (KnowledgeRelatedPageSerializer). */
+export interface RelatedRow extends Record<string, unknown> {
+    id?: string;
+    title?: string;
+    kind?: string;
+    project?: string;
+    via?: string;
+    relevance?: number | null;
+}
+/**
+ * Render the "🔗 Related" block shared by `kb show`, `kb ask` and `kb related`.
+ * `via` says why the page is here (link = someone wrote it, semantic = close in meaning) and
+ * `relevance` how well it matches the question, when one was asked. Empty list → empty string,
+ * so callers can print it unconditionally.
+ */
+export declare function renderRelated(rows: RelatedRow[], heading?: string, indent?: string): string;
+/**
+ * Render `kb search --with-related`: one block per result that has related pages, in the same
+ * 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;
 /** 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

@@ -4,6 +4,8 @@ exports.KNOWLEDGE_KINDS = void 0;
 exports.normalizeKinds = normalizeKinds;
 exports.truncate = truncate;
 exports.buildPagesQuery = buildPagesQuery;
+exports.renderRelated = renderRelated;
+exports.renderRelatedGroups = renderRelatedGroups;
 exports.renderPagesTable = renderPagesTable;
 const output_1 = require("./output");
 /** Knowledge page kinds accepted by the backend (Knowledge::Page). */
@@ -40,8 +42,36 @@ function buildPagesQuery(opts) {
         query.append('kind[]', kind);
     if (opts.q)
         query.set('q', opts.q);
+    if (opts.related)
+        query.set('related', '1');
     return query.toString();
 }
+/**
+ * Render the "🔗 Related" block shared by `kb show`, `kb ask` and `kb related`.
+ * `via` says why the page is here (link = someone wrote it, semantic = close in meaning) and
+ * `relevance` how well it matches the question, when one was asked. Empty list → empty string,
+ * so callers can print it unconditionally.
+ */
+function renderRelated(rows, heading = '\n🔗 Related:', indent = '  ') {
+    if (rows.length === 0)
+        return '';
+    const lines = rows.map((row) => {
+        const score = typeof row.relevance === 'number' ? ` · ${row.relevance.toFixed(2)}` : '';
+        return `${indent}[${(0, output_1.sanitize)(row.kind)}] ${(0, output_1.sanitize)(row.title)} · ${(0, output_1.sanitize)(row.id)} (${(0, output_1.sanitize)(row.via)}${score})`;
+    });
+    return [heading, ...lines].join('\n');
+}
+/**
+ * Render `kb search --with-related`: one block per result that has related pages, in the same
+ * order as the table above it. Results without related pages are simply left out.
+ */
+function renderRelatedGroups(pages, grouped) {
+    const blocks = pages
+        .map((page) => ({ rows: grouped[String(page.id ?? '')] ?? [], title: String(page.title ?? '') }))
+        .filter(({ rows }) => rows.length > 0)
+        .map(({ rows, title }) => renderRelated(rows, `  ${(0, output_1.sanitize)(title)}`, '    '));
+    return blocks.length === 0 ? '' : ['\n🔗 Related:', ...blocks].join('\n');
+}
 /** 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) => [