@bussolabs/closeyourit-cli 0.24.1 → 0.25.0

package/README.md

@@ -162,6 +162,8 @@ CLOSEYOURIT_TOKEN=cyi_u_… CLOSEYOURIT_API_URL=https://www.closeyour.it \
 | `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>…] [--group <id\|name>…] [--tag <tag>…] --title <t> [--kind note\|decision\|guide] (--body <md> \| --body-file <path>) [--tech-spec <md> \| --tech-spec-file <path>] [--in-review] [--review-note <line>] [--author-origin <name>]` | Create a knowledge page (optional technical section, kept separate from the body). `--project`, `--group` and `--tag` are repeatable — a page can belong to several projects and groups at once, and to groups alone; at least one project or group is required. 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. `--author-origin` declares the assistant or skill that wrote the text, which is not the owner of the token. |
 | `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 approve <id>` | Accept a page waiting for review: it enters search, answers and related panels. A human decision: a service token is refused, and a page the automatic reviewer rejected must be fixed and saved first. |
+| `kb reject <id>` | Discard a page waiting for review: it stays archived as rejected, out of search and answers, so it is not proposed again. Nothing is deleted. |
 | `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] [--project <id\|key>…] [--group <id\|name>…] [--tag <tag>…] [--author-origin <name>]` | Update a page (unpassed fields keep their current value — including projects, groups, tags and attachments). Passing `--project`, `--group` or `--tag` **replaces** that list with what you name; `--tag ""` clears the tags. Changing only scope or tags never rewrites the text, so a concurrent edit is not overwritten. 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). |
@@ -272,6 +274,9 @@ CLOSEYOURIT_TOKEN=cyi_u_… CLOSEYOURIT_API_URL=https://www.closeyour.it \
 | `workload promote <action-id> --project <id\|key> [--title] [--description] [--kind] [--status] [--priority]` | Generate a ticket from the action and link it back. |
 
 Every command accepts `--json` for machine-readable output and `--help` for usage details.
+Every command also accepts `--yes`: the server refuses a write that goes through a dangerous
+permission (deleting a project, importing or deleting secrets, …) with `R422-CONFIRM-001` until you
+confirm it, and `--yes` is that confirmation. Reads never need it.
 `--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

package/dist/base.d.ts

@@ -1,4 +1,5 @@
 import { Command, type Interfaces } from '@oclif/core';
+import type { ArgOutput, FlagOutput, Input, ParserOutput } from '@oclif/core/lib/interfaces/parser';
 import { type CliConfig } from './lib/config';
 import { CliApi } from './lib/api';
 import { type TicketLookup } from './lib/ticket-lookup';
@@ -28,9 +29,20 @@ export declare function paginationError(opts: {
 }): string | undefined;
 export declare abstract class BaseCommand extends Command {
     static enableJsonFlag: boolean;
+    /**
+     * `--yes` on every command (CYCL-53): the server asks an explicit confirmation for writes that pass
+     * through a dangerous permission key (`R422-CONFIRM-001`, CYRA-728). Which keys are dangerous is
+     * the server's catalogue, not ours, so the flag is global instead of being sprinkled on the
+     * commands we believe are risky today. Harmless elsewhere: the parameter is simply ignored.
+     */
+    static baseFlags: {
+        yes: Interfaces.BooleanFlag<boolean>;
+    };
     protected cfg: CliConfig;
     protected api: CliApi;
     init(): Promise<void>;
+    /** Parse as oclif does, then hand `--yes` to the api client before any request leaves. */
+    protected parse<F extends FlagOutput, B extends FlagOutput, A extends ArgOutput>(options?: Input<F, B, A>, argv?: string[]): Promise<ParserOutput<F, B, A>>;
     /**
      * Resolve a project reference (UUID passes through; otherwise matched by key, case-insensitive).
      * Walks every page of `/cli/v1/projects`: a key can live past the first page, so a single-page

package/dist/base.js

@@ -38,6 +38,15 @@ function paginationError(opts) {
 }
 class BaseCommand extends core_1.Command {
     static enableJsonFlag = true;
+    /**
+     * `--yes` on every command (CYCL-53): the server asks an explicit confirmation for writes that pass
+     * through a dangerous permission key (`R422-CONFIRM-001`, CYRA-728). Which keys are dangerous is
+     * the server's catalogue, not ours, so the flag is global instead of being sprinkled on the
+     * commands we believe are risky today. Harmless elsewhere: the parameter is simply ignored.
+     */
+    static baseFlags = {
+        yes: core_1.Flags.boolean({ description: 'Confirm a dangerous action the server would otherwise refuse (R422-CONFIRM-001)', default: false }),
+    };
     cfg;
     api;
     async init() {
@@ -45,6 +54,13 @@ class BaseCommand extends core_1.Command {
         this.cfg = (0, config_1.loadConfig)();
         this.api = new api_1.CliApi(this.cfg);
     }
+    /** Parse as oclif does, then hand `--yes` to the api client before any request leaves. */
+    async parse(options, argv) {
+        const parsed = await super.parse(options, argv);
+        if (this.api)
+            this.api.confirm = parsed.flags.yes === true;
+        return parsed;
+    }
     /**
      * Resolve a project reference (UUID passes through; otherwise matched by key, case-insensitive).
      * Walks every page of `/cli/v1/projects`: a key can live past the first page, so a single-page
@@ -191,10 +207,12 @@ class BaseCommand extends core_1.Command {
     async catch(error) {
         if (error instanceof api_1.ApiRequestError) {
             if (this.jsonEnabled()) {
-                this.logJson({ error: { code: error.code, message: error.message } });
+                this.logJson({ error: { code: error.code, message: error.message, ...(error.details === undefined ? {} : { details: error.details }) } });
             }
             else {
                 this.logToStderr(`${error.code}: ${error.message}`);
+                for (const line of reviewVerdictLines(error))
+                    this.logToStderr(line);
             }
             return this.exit(1);
         }
@@ -237,3 +255,31 @@ class BaseCommand extends core_1.Command {
     }
 }
 exports.BaseCommand = BaseCommand;
+/**
+ * The automatic reviewer of knowledge pages (R422-KNOWLEDGE-013, CYRA-764) answers with the whole
+ * verdict in `details`: every rule violated, the format it recognised, a suggested title, the page it
+ * looks like a duplicate of. The message carries only the first three rules, so a human reading the
+ * terminal would otherwise have to open the site to learn what to fix.
+ */
+function reviewVerdictLines(error) {
+    if (error.code !== 'R422-KNOWLEDGE-013' || typeof error.details !== 'object' || error.details === null)
+        return [];
+    const details = error.details;
+    const lines = [];
+    const violations = Array.isArray(details.violations) ? details.violations : [];
+    if (violations.length > 0) {
+        lines.push('Rules violated:');
+        for (const v of violations)
+            lines.push(`  ${v.code ?? '?'}${v.blocking === false ? ' (warning)' : ''}: ${v.message ?? ''}`);
+    }
+    if (details.format && details.format !== 'unknown')
+        lines.push(`Format recognised: ${details.format}`);
+    if (details.suggested_title)
+        lines.push(`Suggested title: ${details.suggested_title}`);
+    if (details.duplicate_of)
+        lines.push(`Looks like a duplicate of: ${details.duplicate_of}`);
+    if (Array.isArray(details.split_suggestion) && details.split_suggestion.length > 0) {
+        lines.push(`Split into: ${details.split_suggestion.join(' · ')}`);
+    }
+    return lines;
+}

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

@@ -0,0 +1,15 @@
+import { BaseCommand } from '../../base';
+/**
+ * First step of the review flow: a page proposed with `kb create --in-review` enters the knowledge
+ * (search, answers, related panels). The server insists the decision comes from a person: a service
+ * token gets R403-KNOWLEDGE-005, and a page the automatic reviewer rejected must be fixed and saved
+ * first (R422-KNOWLEDGE-009).
+ */
+export default class KbApprove extends BaseCommand {
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    run(): Promise<unknown>;
+}

package/dist/commands/kb/approve.js

@@ -0,0 +1,28 @@
+"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");
+/**
+ * First step of the review flow: a page proposed with `kb create --in-review` enters the knowledge
+ * (search, answers, related panels). The server insists the decision comes from a person: a service
+ * token gets R403-KNOWLEDGE-005, and a page the automatic reviewer rejected must be fixed and saved
+ * first (R422-KNOWLEDGE-009).
+ */
+class KbApprove extends base_1.BaseCommand {
+    static args = {
+        id: core_1.Args.string({ description: 'Knowledge page id', required: true }),
+    };
+    static description = 'Accept a page waiting for review: it enters search, answers and related panels';
+    static examples = ['<%= config.bin %> kb approve <page-id>', '<%= config.bin %> kb approve <page-id> --json'];
+    async run() {
+        const { args } = await this.parse(KbApprove);
+        const res = await this.api.post(`/cli/v1/knowledge/pages/${args.id}/approve`);
+        if (!this.jsonEnabled()) {
+            this.log('Knowledge page accepted:');
+            this.log((0, output_1.renderRecord)(res.data ?? {}));
+        }
+        return res;
+    }
+}
+exports.default = KbApprove;

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

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../base';
+/**
+ * Mirror of `kb approve`: the proposal stays archived as rejected — out of search, answers, related
+ * panels and lists — so whoever proposes can see it when hunting duplicates and not propose it again.
+ * Nothing is deleted (that is `kb delete`). A human decision, like approve.
+ */
+export default class KbReject extends BaseCommand {
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    run(): Promise<unknown>;
+}

package/dist/commands/kb/reject.js

@@ -0,0 +1,27 @@
+"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");
+/**
+ * Mirror of `kb approve`: the proposal stays archived as rejected — out of search, answers, related
+ * panels and lists — so whoever proposes can see it when hunting duplicates and not propose it again.
+ * Nothing is deleted (that is `kb delete`). A human decision, like approve.
+ */
+class KbReject extends base_1.BaseCommand {
+    static args = {
+        id: core_1.Args.string({ description: 'Knowledge page id', required: true }),
+    };
+    static description = 'Discard a page waiting for review: it stays archived as rejected, out of search and answers';
+    static examples = ['<%= config.bin %> kb reject <page-id>', '<%= config.bin %> kb reject <page-id> --json'];
+    async run() {
+        const { args } = await this.parse(KbReject);
+        const res = await this.api.post(`/cli/v1/knowledge/pages/${args.id}/reject`);
+        if (!this.jsonEnabled()) {
+            this.log('Knowledge page rejected:');
+            this.log((0, output_1.renderRecord)(res.data ?? {}));
+        }
+        return res;
+    }
+}
+exports.default = KbReject;

package/dist/lib/api.d.ts

@@ -23,6 +23,8 @@ export interface UploadFile {
     data: Blob;
 }
 type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/** Error code the server answers when a dangerous write arrives without the confirm gesture (CYRA-728). */
+export declare const CONFIRMATION_REQUIRED_CODE = "R422-CONFIRM-001";
 export declare class CliApi {
     private readonly config;
     /**
@@ -32,6 +34,14 @@ export declare class CliApi {
      * commands (CYCL-11). The instance is per-command, so this is that command's last response.
      */
     lastMeta?: Record<string, unknown>;
+    /**
+     * The user confirmed dangerous actions (`--yes`, CYCL-53). The server (CYRA-728) refuses any
+     * write through a `dangerous` permission key without the `confirm` parameter and answers
+     * `R422-CONFIRM-001`: not a permission problem, a missing gesture. `BaseCommand.parse` sets it;
+     * `request()` then adds `confirm=1` to every writing call — in the query string, so DELETE
+     * without a body is covered too. Reads never carry it: looking is not executing.
+     */
+    confirm: boolean;
     constructor(config: CliConfig);
     request<T = unknown>(method: HttpMethod, path: string, opts?: RequestOptions): Promise<Envelope<T>>;
     /**
@@ -39,6 +49,8 @@ export declare class CliApi {
      * The boundary Content-Type is derived by fetch from the FormData body — never set it by hand.
      */
     upload<T = unknown>(method: 'POST' | 'PUT', path: string, files: UploadFile[], opts?: RequestOptions): Promise<Envelope<T>>;
+    /** Add `confirm=1` to a writing request when the user passed `--yes`; reads are left alone. */
+    private withConfirmation;
     private resolveUrl;
     /** Build the shared Accept + Authorization headers; throws (before any fetch) if an authed call has no token. */
     private authHeaders;

package/dist/lib/api.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CliApi = exports.ApiRequestError = void 0;
+exports.CliApi = exports.CONFIRMATION_REQUIRED_CODE = exports.ApiRequestError = void 0;
 const error_codes_1 = require("../errors/error-codes");
 /** Error carrying the HTTP status and the structured code from the backend envelope (R/G prefix) or a local C-prefix fallback. */
 class ApiRequestError extends Error {
@@ -16,6 +16,9 @@ class ApiRequestError extends Error {
     }
 }
 exports.ApiRequestError = ApiRequestError;
+/** Error code the server answers when a dangerous write arrives without the confirm gesture (CYRA-728). */
+exports.CONFIRMATION_REQUIRED_CODE = 'R422-CONFIRM-001';
+const READ_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
 class CliApi {
     config;
     /**
@@ -25,13 +28,21 @@ class CliApi {
      * commands (CYCL-11). The instance is per-command, so this is that command's last response.
      */
     lastMeta;
+    /**
+     * The user confirmed dangerous actions (`--yes`, CYCL-53). The server (CYRA-728) refuses any
+     * write through a `dangerous` permission key without the `confirm` parameter and answers
+     * `R422-CONFIRM-001`: not a permission problem, a missing gesture. `BaseCommand.parse` sets it;
+     * `request()` then adds `confirm=1` to every writing call — in the query string, so DELETE
+     * without a body is covered too. Reads never carry it: looking is not executing.
+     */
+    confirm = false;
     constructor(config) {
         this.config = config;
     }
     async request(method, path, opts = {}) {
         const headers = this.authHeaders(opts.auth !== false);
         headers['Content-Type'] = 'application/json';
-        const url = this.resolveUrl(path);
+        const url = this.resolveUrl(this.withConfirmation(method, path));
         let res;
         try {
             res = await fetch(url, {
@@ -70,6 +81,12 @@ class CliApi {
         }
         return this.handleResponse(res);
     }
+    /** Add `confirm=1` to a writing request when the user passed `--yes`; reads are left alone. */
+    withConfirmation(method, path) {
+        if (!this.confirm || READ_METHODS.has(method))
+            return path;
+        return `${path}${path.includes('?') ? '&' : '?'}confirm=1`;
+    }
     resolveUrl(path) {
         return this.config.apiUrl.replace(/\/+$/, '') + path;
     }
@@ -102,7 +119,12 @@ class CliApi {
         if (!res.ok) {
             const envelope = (json ?? {});
             const error = envelope.error ?? {};
-            throw new ApiRequestError(res.status, error.code ?? `C${res.status}-API-000`, error.message ?? res.statusText ?? `Request failed (${res.status})`, error.details);
+            let message = error.message ?? res.statusText ?? `Request failed (${res.status})`;
+            // The server names the gesture it wants but not the flag that makes it: say it here, once.
+            if (error.code === exports.CONFIRMATION_REQUIRED_CODE && !message.includes('--yes')) {
+                message = `${message} Re-run with --yes to confirm this dangerous action.`;
+            }
+            throw new ApiRequestError(res.status, error.code ?? `C${res.status}-API-000`, message, error.details);
         }
         const envelope = (json ?? {});
         this.lastMeta = envelope.meta;