@bussolabs/closeyourit-cli 0.17.0 → 0.18.0

package/README.md

@@ -79,6 +79,12 @@ CLOSEYOURIT_TOKEN=cyi_u_… CLOSEYOURIT_API_URL=https://www.closeyour.it \
 | `errors list --project <id\|key> [--status] [--page]` | List error groups. |
 | `errors show <id> --project <id\|key>` | Show one error group. |
 | `errors resolve\|reopen\|mute\|unmute <id> --project <id\|key>` | Triage an error group. |
+| `vulnerabilities list [--project <id\|key>] [--severity] [--status] [--package] [--page]` | List known dependency vulnerabilities across every visible project, worst first. |
+| `vulnerabilities show <id>` | Show one: advisory, package, manifest, fixing version. |
+| `vulnerabilities ignore <id> [--note]` / `reopen <id>` | Accept living with the risk, or change your mind (requires vulnerabilities.triage). |
+| `vulnerabilities promote <id>` | Open a ticket from it — automatic promotion only fires on high/critical. |
+| `vulnerabilities rescan --project <id\|key>` | Rescan now, without waiting for the nightly run. |
+| `vulnerabilities runtimes [--project <id\|key>] [--page]` | Support state of the declared runtimes (Ruby, Node, Flutter…). |
 | `tokens list --project <id\|key>` | List ingest tokens. |
 | `tokens create --project <id\|key> --name <name> --environment-id <id>` | Create a token (secret shown once). |
 | `tokens provision --project <id\|key> --name <name> --environment-id <code\|id> --to-project <id\|key> --to-environment-id <code\|id> --secret-name <NAME>` | Generate and deliver a token without revealing its value. GitHub sync is enabled by default; use `--no-sync-github` for vault-only delivery. |

package/dist/commands/login.js

@@ -14,12 +14,17 @@ class Login extends base_1.BaseCommand {
     };
     async run() {
         const { flags } = await this.parse(Login);
-        if (flags['api-url']) {
-            this.cfg.apiUrl = flags['api-url'];
-            (0, config_1.saveConfig)(this.cfg);
-        }
+        // Persist from the on-disk config so a temporary CLOSEYOURIT_API_URL override is never written to
+        // config.json. Only an explicit --api-url is persisted (that is its documented purpose).
+        const stored = (0, config_1.loadStoredConfig)();
+        if (flags['api-url'])
+            stored.apiUrl = flags['api-url'];
+        // Runtime URL to authenticate against: --api-url wins, otherwise the resolved config (env override included).
+        const apiUrl = flags['api-url'] ?? this.cfg.apiUrl;
+        if (flags['api-url'])
+            (0, config_1.saveConfig)(stored);
         const clientName = `closeyourit-cli/${this.config.version} (${process.platform} ${process.arch})`;
-        const authorization = await (0, device_flow_1.startDeviceFlow)(this.cfg.apiUrl, clientName);
+        const authorization = await (0, device_flow_1.startDeviceFlow)(apiUrl, clientName);
         if (!this.jsonEnabled()) {
             this.log('');
             this.log('To authorize this CLI, open:');
@@ -32,7 +37,7 @@ class Login extends base_1.BaseCommand {
             this.log('Opening your browser…');
         }
         (0, browser_1.openUrl)(authorization.verification_uri_complete);
-        const result = await (0, device_flow_1.pollDeviceToken)(this.cfg.apiUrl, authorization.device_code, {
+        const result = await (0, device_flow_1.pollDeviceToken)(apiUrl, authorization.device_code, {
             interval: authorization.interval,
             expiresIn: authorization.expires_in,
             onPending: () => {
@@ -40,24 +45,24 @@ class Login extends base_1.BaseCommand {
                     process.stderr.write('.');
             },
         });
-        this.cfg.token = result.access_token;
-        (0, config_1.saveConfig)(this.cfg);
-        // Enrich the local config with identity (account + organization).
-        this.api = new api_1.CliApi(this.cfg);
+        stored.token = result.access_token;
+        (0, config_1.saveConfig)(stored);
+        // Enrich the local config with identity (account + organization). Use the runtime apiUrl for the call.
+        this.api = new api_1.CliApi({ ...stored, apiUrl });
         const who = await this.api.get('/cli/v1/whoami');
         const account = who.data.account;
         const organization = who.data.organization;
         if (account)
-            this.cfg.account = { id: account.id, name: account.name, email: account.email };
+            stored.account = { id: account.id, name: account.name, email: account.email };
         if (organization) {
-            this.cfg.organization = { id: organization.id, name: organization.name, slug: organization.slug };
+            stored.organization = { id: organization.id, name: organization.name, slug: organization.slug };
         }
-        (0, config_1.saveConfig)(this.cfg);
+        (0, config_1.saveConfig)(stored);
         if (!this.jsonEnabled()) {
             this.log('');
-            this.log(`Logged in as ${this.cfg.account?.email ?? 'unknown'} · ${this.cfg.organization?.name ?? 'no organization'}`);
+            this.log(`Logged in as ${stored.account?.email ?? 'unknown'} · ${stored.organization?.name ?? 'no organization'}`);
         }
-        return { account: this.cfg.account, organization: this.cfg.organization, token: result.token };
+        return { account: stored.account, organization: stored.organization, token: result.token };
     }
 }
 exports.default = Login;

package/dist/commands/vulnerabilities/ignore.d.ts

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

package/dist/commands/vulnerabilities/ignore.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../base");
+class VulnerabilitiesIgnore extends base_1.BaseCommand {
+    static aliases = ['vulns:ignore'];
+    static description = 'Ignore a vulnerability: you accept living with the risk';
+    static examples = [
+        '<%= config.bin %> vulnerabilities ignore <finding-id>',
+        '<%= config.bin %> vulnerabilities ignore <finding-id> --note "Not reachable from our code."',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Vulnerability finding id', required: true }),
+    };
+    static flags = {
+        note: core_1.Flags.string({ description: 'Why you are keeping it (shown alongside the ignored row)' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(VulnerabilitiesIgnore);
+        const res = await this.api.put(`/cli/v1/vulnerabilities/${args.id}/ignore`, { triage_note: flags.note });
+        if (!this.jsonEnabled()) {
+            // An ignored row never reopens on its own: the next scan won't undo a decision already taken.
+            this.log(`Vulnerability ${args.id} ignored.`);
+        }
+        return res;
+    }
+}
+exports.default = VulnerabilitiesIgnore;

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

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../base';
+export default class VulnerabilitiesList extends BaseCommand {
+    static aliases: string[];
+    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>;
+        severity: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        status: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        package: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/vulnerabilities/list.js

@@ -0,0 +1,54 @@
+"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 VulnerabilitiesList extends base_1.BaseCommand {
+    static aliases = ['vulns:list'];
+    static description = 'List known vulnerabilities of the project dependencies (cross-project)';
+    static examples = [
+        '<%= config.bin %> vulnerabilities list',
+        '<%= config.bin %> vulnerabilities list --severity critical',
+        '<%= config.bin %> vulnerabilities list --project acme-api --status open',
+        '<%= config.bin %> vulnerabilities list --package nokogiri --json',
+    ];
+    static flags = {
+        // Optional here (the endpoint is cross-project): without it, the list spans every visible project.
+        project: core_1.Flags.string({ char: 'p', description: 'Filter by project id (UUID) or key' }),
+        severity: core_1.Flags.string({ description: 'Filter by severity (critical, high, moderate, low, unknown)' }),
+        status: core_1.Flags.string({ description: 'Filter by status (open, resolved, ignored)' }),
+        package: core_1.Flags.string({ description: 'Filter by package name (partial match)' }),
+        ...base_1.pageFlag,
+    };
+    async run() {
+        const { flags } = await this.parse(VulnerabilitiesList);
+        const query = new URLSearchParams({ page: String(flags.page) });
+        if (flags.project)
+            query.set('project_id', await this.resolveProjectId(flags.project));
+        if (flags.severity)
+            query.set('severity', flags.severity);
+        if (flags.status)
+            query.set('status', flags.status);
+        if (flags.package)
+            query.set('package', flags.package);
+        const res = await this.api.get(`/cli/v1/vulnerabilities?${query.toString()}`);
+        const findings = res.data ?? [];
+        if (!this.jsonEnabled()) {
+            this.log((0, output_1.renderTable)(
+            // ID first, like `errors list`: every other subcommand takes it as its argument, so a table
+            // without it forces `--json` just to triage what you are already looking at.
+            ['ID', 'PROJECT', 'PACKAGE', 'SEVERITY', 'STATUS', 'FIXED IN', 'ADVISORY'], findings.map((finding) => [
+                String(finding.id ?? ''),
+                String(finding.project?.key ?? ''),
+                String(finding.package?.coordinates ?? ''),
+                (0, output_1.statusCell)(finding.advisory?.severity),
+                (0, output_1.statusCell)(finding.status),
+                // No fixed version means OSV declares none: the only move is dropping or replacing the dep.
+                String(finding.fixed_version ?? '—'),
+                String(finding.advisory?.display_id ?? ''),
+            ])));
+        }
+        return res;
+    }
+}
+exports.default = VulnerabilitiesList;

package/dist/commands/vulnerabilities/promote.d.ts

@@ -0,0 +1,10 @@
+import { BaseCommand } from '../../base';
+export default class VulnerabilitiesPromote extends BaseCommand {
+    static aliases: string[];
+    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/vulnerabilities/promote.js

@@ -0,0 +1,23 @@
+"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 VulnerabilitiesPromote extends base_1.BaseCommand {
+    static aliases = ['vulns:promote'];
+    static description = 'Open a ticket from a vulnerability (automatic promotion only fires on high/critical)';
+    static examples = ['<%= config.bin %> vulnerabilities promote <finding-id>'];
+    static args = {
+        id: core_1.Args.string({ description: 'Vulnerability finding id', required: true }),
+    };
+    async run() {
+        const { args } = await this.parse(VulnerabilitiesPromote);
+        // Idempotent server-side: promoting twice returns R422-VULN-001, never a second ticket.
+        const res = await this.api.put(`/cli/v1/vulnerabilities/${args.id}/promotion`);
+        if (!this.jsonEnabled()) {
+            this.log((0, output_1.renderRecord)(res.data ?? {}));
+        }
+        return res;
+    }
+}
+exports.default = VulnerabilitiesPromote;

package/dist/commands/vulnerabilities/reopen.d.ts

@@ -0,0 +1,10 @@
+import { BaseCommand } from '../../base';
+export default class VulnerabilitiesReopen extends BaseCommand {
+    static aliases: string[];
+    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/vulnerabilities/reopen.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../base");
+class VulnerabilitiesReopen extends base_1.BaseCommand {
+    static aliases = ['vulns:reopen'];
+    static description = 'Reopen an ignored vulnerability: you changed your mind';
+    static examples = ['<%= config.bin %> vulnerabilities reopen <finding-id>'];
+    static args = {
+        id: core_1.Args.string({ description: 'Vulnerability finding id', required: true }),
+    };
+    async run() {
+        const { args } = await this.parse(VulnerabilitiesReopen);
+        // Reopening is deleting the ignore, not a verb of its own — hence DELETE on the same resource.
+        const res = await this.api.delete(`/cli/v1/vulnerabilities/${args.id}/ignore`);
+        if (!this.jsonEnabled()) {
+            this.log(`Vulnerability ${args.id} reopened.`);
+        }
+        return res;
+    }
+}
+exports.default = VulnerabilitiesReopen;

package/dist/commands/vulnerabilities/rescan.d.ts

@@ -0,0 +1,10 @@
+import { BaseCommand } from '../../base';
+export default class VulnerabilitiesRescan extends BaseCommand {
+    static aliases: string[];
+    static description: string;
+    static examples: string[];
+    static flags: {
+        project: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/vulnerabilities/rescan.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const base_1 = require("../../base");
+class VulnerabilitiesRescan extends base_1.BaseCommand {
+    static aliases = ['vulns:rescan'];
+    static description = 'Rescan a project now, without waiting for the nightly run';
+    static examples = ['<%= config.bin %> vulnerabilities rescan --project acme-api'];
+    // Required here, unlike the other subcommands: a scan always targets one project.
+    static flags = { ...base_1.projectFlag };
+    async run() {
+        const { flags } = await this.parse(VulnerabilitiesRescan);
+        const projectId = await this.resolveProjectId(flags.project);
+        const res = await this.api.post('/cli/v1/vulnerabilities/rescan', { project_id: projectId });
+        if (!this.jsonEnabled()) {
+            this.log(`Scan queued for project ${flags.project}.`);
+        }
+        return res;
+    }
+}
+exports.default = VulnerabilitiesRescan;

package/dist/commands/vulnerabilities/runtimes.d.ts

@@ -0,0 +1,11 @@
+import { BaseCommand } from '../../base';
+export default class VulnerabilitiesRuntimes extends BaseCommand {
+    static aliases: string[];
+    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>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/vulnerabilities/runtimes.js

@@ -0,0 +1,38 @@
+"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 VulnerabilitiesRuntimes extends base_1.BaseCommand {
+    static aliases = ['vulns:runtimes'];
+    static description = 'List the support state of the declared runtimes (Ruby, Node, Flutter…)';
+    static examples = [
+        '<%= config.bin %> vulnerabilities runtimes',
+        '<%= config.bin %> vulnerabilities runtimes --project acme-api --json',
+    ];
+    static flags = {
+        project: core_1.Flags.string({ char: 'p', description: 'Filter by project id (UUID) or key' }),
+        ...base_1.pageFlag,
+    };
+    async run() {
+        const { flags } = await this.parse(VulnerabilitiesRuntimes);
+        const query = new URLSearchParams({ page: String(flags.page) });
+        if (flags.project)
+            query.set('project_id', await this.resolveProjectId(flags.project));
+        const res = await this.api.get(`/cli/v1/vulnerabilities/runtimes?${query.toString()}`);
+        const runtimes = res.data ?? [];
+        if (!this.jsonEnabled()) {
+            this.log((0, output_1.renderTable)(['PROJECT', 'RUNTIME', 'VERSION', 'STATE', 'EOL', 'LATEST'], runtimes.map((runtime) => [
+                String(runtime.project?.key ?? ''),
+                String(runtime.name ?? ''),
+                String(runtime.version ?? ''),
+                (0, output_1.statusCell)(runtime.state),
+                // No EOL date means endoflife.date doesn't know the product: no alarm is possible.
+                String(runtime.eol_on ?? '—'),
+                String(runtime.latest ?? '—'),
+            ])));
+        }
+        return res;
+    }
+}
+exports.default = VulnerabilitiesRuntimes;

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

@@ -0,0 +1,10 @@
+import { BaseCommand } from '../../base';
+export default class VulnerabilitiesShow extends BaseCommand {
+    static aliases: string[];
+    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/vulnerabilities/show.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 output_1 = require("../../lib/output");
+/** A nested object of the payload, or `{}` when the field is absent. */
+function nested(data, key) {
+    const value = data[key];
+    return value && typeof value === 'object' ? value : {};
+}
+class VulnerabilitiesShow extends base_1.BaseCommand {
+    static aliases = ['vulns:show'];
+    static description = 'Show a single vulnerability: advisory, package, manifest and the fixing version';
+    static examples = ['<%= config.bin %> vulnerabilities show <finding-id>'];
+    static args = {
+        id: core_1.Args.string({ description: 'Vulnerability finding id', required: true }),
+    };
+    async run() {
+        const { args } = await this.parse(VulnerabilitiesShow);
+        const res = await this.api.get(`/cli/v1/vulnerabilities/${args.id}`);
+        if (!this.jsonEnabled()) {
+            const data = res.data ?? {};
+            // Same blocks the promoted ticket carries: whoever reads either one decides with the same facts.
+            this.log((0, output_1.renderRecord)(data));
+            this.log((0, output_1.section)('Project', '📦'));
+            this.log((0, output_1.renderRecord)(nested(data, 'project')));
+            this.log((0, output_1.section)('Package', '🧩'));
+            this.log((0, output_1.renderRecord)({ ...nested(data, 'package'), manifest: nested(data, 'manifest').path ?? null }));
+            this.log((0, output_1.section)('Advisory', '🔒'));
+            this.log((0, output_1.renderRecord)(nested(data, 'advisory')));
+        }
+        return res;
+    }
+}
+exports.default = VulnerabilitiesShow;

package/dist/lib/config.d.ts

@@ -14,7 +14,14 @@ export interface CliConfig {
 }
 export declare function configPath(): string;
 export declare function defaultApiUrl(): string;
+/**
+ * Config exactly as stored on disk, ignoring env overrides. This is the base for mutations that get
+ * re-saved (login, clearToken): a temporary CLOSEYOURIT_API_URL / CLOSEYOURIT_TOKEN must never be
+ * written back to config.json, otherwise a one-off override would silently become permanent.
+ */
+export declare function loadStoredConfig(): CliConfig;
+/** Runtime config: env overrides win over the stored values, symmetrically for apiUrl and token. */
 export declare function loadConfig(): CliConfig;
 export declare function saveConfig(cfg: CliConfig): void;
-/** Remove token + identity, keep apiUrl. */
+/** Remove token + identity, keep the on-disk apiUrl (never a temporary env override). */
 export declare function clearToken(): void;

package/dist/lib/config.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.configPath = configPath;
 exports.defaultApiUrl = defaultApiUrl;
+exports.loadStoredConfig = loadStoredConfig;
 exports.loadConfig = loadConfig;
 exports.saveConfig = saveConfig;
 exports.clearToken = clearToken;
@@ -52,9 +53,16 @@ function configDir() {
 function configPath() {
     return path.join(configDir(), 'config.json');
 }
-function defaultApiUrl() {
+/**
+ * API URL from CLOSEYOURIT_API_URL env (overrides the stored config apiUrl), for pointing the CLI
+ * at another server on the fly — symmetric with envToken(), so URL and token behave the same way.
+ */
+function envApiUrl() {
     const fromEnv = process.env.CLOSEYOURIT_API_URL;
-    return fromEnv && fromEnv.trim() !== '' ? fromEnv : DEFAULT_API_URL;
+    return fromEnv && fromEnv.trim() !== '' ? fromEnv.trim() : undefined;
+}
+function defaultApiUrl() {
+    return envApiUrl() ?? DEFAULT_API_URL;
 }
 /**
  * Token from CLOSEYOURIT_TOKEN env, for headless/CI/agent use (overrides the stored config token).
@@ -65,7 +73,12 @@ function envToken() {
     const fromEnv = process.env.CLOSEYOURIT_TOKEN;
     return fromEnv && fromEnv.trim() !== '' ? fromEnv.trim() : undefined;
 }
-function loadConfig() {
+/**
+ * Config exactly as stored on disk, ignoring env overrides. This is the base for mutations that get
+ * re-saved (login, clearToken): a temporary CLOSEYOURIT_API_URL / CLOSEYOURIT_TOKEN must never be
+ * written back to config.json, otherwise a one-off override would silently become permanent.
+ */
+function loadStoredConfig() {
     const file = configPath();
     let parsed = {};
     try {
@@ -78,12 +91,21 @@ function loadConfig() {
         parsed = {};
     }
     return {
-        apiUrl: parsed.apiUrl && parsed.apiUrl.trim() !== '' ? parsed.apiUrl : defaultApiUrl(),
-        token: envToken() ?? parsed.token,
+        apiUrl: parsed.apiUrl && parsed.apiUrl.trim() !== '' ? parsed.apiUrl : DEFAULT_API_URL,
+        token: parsed.token,
         account: parsed.account,
         organization: parsed.organization,
     };
 }
+/** Runtime config: env overrides win over the stored values, symmetrically for apiUrl and token. */
+function loadConfig() {
+    const stored = loadStoredConfig();
+    return {
+        ...stored,
+        apiUrl: envApiUrl() ?? stored.apiUrl,
+        token: envToken() ?? stored.token,
+    };
+}
 function saveConfig(cfg) {
     const dir = configDir();
     fs.mkdirSync(dir, { recursive: true });
@@ -92,9 +114,9 @@ function saveConfig(cfg) {
     // Ensure perms even if the file pre-existed with a looser mode.
     fs.chmodSync(file, 0o600);
 }
-/** Remove token + identity, keep apiUrl. */
+/** Remove token + identity, keep the on-disk apiUrl (never a temporary env override). */
 function clearToken() {
-    const cfg = loadConfig();
+    const cfg = loadStoredConfig();
     delete cfg.token;
     delete cfg.account;
     delete cfg.organization;

package/dist/lib/opencli.d.ts

@@ -0,0 +1,107 @@
+/** Flag di un comando, così come lo espone `oclif.manifest.json`. */
+export interface OclifFlag {
+    name: string;
+    type: 'boolean' | 'option';
+    char?: string;
+    description?: string;
+    required?: boolean;
+    options?: string[];
+    hidden?: boolean;
+    helpGroup?: string;
+}
+/** Argomento posizionale di un comando, dal manifest oclif. */
+export interface OclifArg {
+    name: string;
+    description?: string;
+    required?: boolean;
+    options?: string[];
+    hidden?: boolean;
+}
+/** Comando risolto dal manifest oclif. */
+export interface OclifCommand {
+    id: string;
+    description?: string;
+    summary?: string;
+    aliases?: string[];
+    hidden?: boolean;
+    flags?: Record<string, OclifFlag>;
+    args?: Record<string, OclifArg>;
+    examples?: Array<string | {
+        command: string;
+        description?: string;
+    }>;
+}
+/** Il manifest oclif (`oclif.manifest.json`). */
+export interface OclifManifest {
+    version: string;
+    commands: Record<string, OclifCommand>;
+}
+export interface OpenCliArgument {
+    name: string;
+    required?: boolean;
+    description?: string;
+    acceptedValues?: string[];
+    hidden?: boolean;
+}
+export interface OpenCliOption {
+    name: string;
+    aliases?: string[];
+    description?: string;
+    required?: boolean;
+    recursive?: boolean;
+    hidden?: boolean;
+    arguments?: OpenCliArgument[];
+}
+export interface OpenCliExitCode {
+    code: number;
+    description?: string;
+}
+export interface OpenCliCommand {
+    name: string;
+    description?: string;
+    aliases?: string[];
+    hidden?: boolean;
+    options?: OpenCliOption[];
+    arguments?: OpenCliArgument[];
+    exitCodes?: OpenCliExitCode[];
+    examples?: string[];
+    commands?: OpenCliCommand[];
+}
+export interface OpenCliInfo {
+    title: string;
+    version: string;
+    summary?: string;
+    description?: string;
+    license?: {
+        name?: string;
+        identifier?: string;
+        url?: string;
+    };
+}
+export interface OpenCliDocument {
+    $schema: string;
+    opencli: string;
+    info: OpenCliInfo;
+    conventions: {
+        groupOptions: boolean;
+        optionSeparator: string;
+    };
+    command: OpenCliCommand;
+}
+export interface BuildOpenCliInput {
+    manifest: OclifManifest;
+    bin: string;
+    description?: string;
+    summary?: string;
+    license?: {
+        name?: string;
+        identifier?: string;
+        url?: string;
+    };
+    /** Descrizioni dei topic (contenitori senza comando proprio), indicizzate per id oclif. */
+    topics?: Record<string, {
+        description?: string;
+    }>;
+}
+/** Costruisce il documento OpenCLI completo dal manifest oclif e dai metadati di package.json. */
+export declare function buildOpenCliDocument(input: BuildOpenCliInput): OpenCliDocument;