@bussolabs/closeyourit-cli 0.15.0 → 0.16.0

package/README.md

@@ -105,6 +105,9 @@ CLOSEYOURIT_TOKEN=cyi_u_… CLOSEYOURIT_API_URL=https://www.closeyour.it \
 | `tickets watch\|unwatch <id> --project <id\|key>` | Watch / stop watching a ticket (its notifications). |
 | `tickets branch <id\|code> --project <id\|key>` | Create a GitHub branch from a ticket (name prefixed with the ticket code). |
 | `tickets pr <id\|code> --project <id\|key>` | Open a GitHub pull request from a ticket (head = the ticket branch). |
+| `tickets lease claim <id\|code> --project <id\|key> [--ttl <seconds>] [--run-id <id>]` | Claim the working lease on a ticket (server default TTL: 8h). Exits non-zero on a 409, naming the current holder and its expiry. |
+| `tickets lease renew <id\|code> --project <id\|key> [--ttl <seconds>] [--run-id <id>]` | Extend your own lease before it expires. |
+| `tickets lease release <id\|code> --project <id\|key> [--run-id <id>]` | Release your own lease so someone else can claim the ticket. |
 | `ideas delete <id> --project <id\|key> --confirm` | Delete an idea (author always allowed; others need ideas.delete). |
 | `ideas archive\|unarchive <id> --project <id\|key>` | Archive an idea (open → archived) / reopen it. |
 | `ideas case-update <idea-id> <case-id> --project <id\|key> [--title] [--description]` | Update a case (example) of an idea. |

package/dist/commands/tickets/lease/claim.d.ts

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../../base';
+export default class TicketsLeaseClaim extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        ttl: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'run-id': 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/tickets/lease/claim.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../../base");
+const lease_1 = require("../../../lib/lease");
+const output_1 = require("../../../lib/output");
+class TicketsLeaseClaim extends base_1.BaseCommand {
+    static description = 'Claim the working lease on a ticket, so nobody else (person or agent) starts it at the same time';
+    static examples = [
+        '<%= config.bin %> tickets lease claim <ticket-id> --project acme-api',
+        '<%= config.bin %> tickets lease claim DRFL-3 -p driverone-flutter --ttl 3600 --run-id run-42',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Ticket id or code (e.g. DRFL-3)', required: true }),
+    };
+    static flags = {
+        ...base_1.projectFlag,
+        ttl: core_1.Flags.integer({ description: 'Lease duration in seconds (server default: 8h; range 1s..30 days)' }),
+        'run-id': core_1.Flags.string({ description: 'Automation run id, for tokens that juggle several concurrent runs' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(TicketsLeaseClaim);
+        const projectId = await this.resolveProjectId(flags.project);
+        const path = `/cli/v1/projects/${encodeURIComponent(projectId)}/tickets/${encodeURIComponent(args.id)}/lease`;
+        const body = {};
+        if (flags.ttl !== undefined)
+            body.ttl_seconds = flags.ttl;
+        if (flags['run-id'] !== undefined)
+            body.run_id = flags['run-id'];
+        let res;
+        try {
+            res = await this.api.post(path, body);
+        }
+        catch (error) {
+            // 409 = somebody else already holds it. --json prints the full backend envelope (details
+            // included) itself and returns, so BaseCommand.catch never trims it down to {code,message};
+            // human mode gets the holder spelled out in the message instead (requisito CYCL-14).
+            if (this.jsonEnabled()) {
+                const envelope = (0, lease_1.leaseErrorEnvelope)(error);
+                if (!envelope)
+                    throw error;
+                this.logJson(envelope);
+                process.exitCode = 1;
+                return;
+            }
+            throw (0, lease_1.describeLeaseConflict)(error);
+        }
+        if (!this.jsonEnabled()) {
+            const lease = res.data ?? {};
+            this.log(`Ticket ${args.id} leased until ${lease.expires_at ?? '?'}:`);
+            this.log((0, output_1.renderRecord)(leaseSummary(lease)));
+        }
+        return res;
+    }
+}
+exports.default = TicketsLeaseClaim;
+/** Flatten the lease payload for `renderRecord`: `held_by` is a nested object, so print it as one line. */
+function leaseSummary(lease) {
+    const heldBy = lease.held_by;
+    return {
+        ticket: lease.ticket,
+        run_id: lease.run_id,
+        held_by: heldBy ? `${heldBy.kind} ${heldBy.name ?? heldBy.id}` : null,
+        expires_at: lease.expires_at,
+        host_id: lease.host_id,
+        account_id: lease.account_id,
+        agent: lease.agent,
+        execution_phase: lease.execution_phase,
+        profile_digest: lease.profile_digest,
+    };
+}

package/dist/commands/tickets/lease/release.d.ts

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

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../../base");
+const lease_1 = require("../../../lib/lease");
+const output_1 = require("../../../lib/output");
+class TicketsLeaseRelease extends base_1.BaseCommand {
+    static description = 'Release your own working lease on a ticket, so someone else can claim it';
+    static examples = [
+        '<%= config.bin %> tickets lease release <ticket-id> --project acme-api',
+        '<%= config.bin %> tickets lease release DRFL-3 -p driverone-flutter --run-id run-42',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Ticket id or code (e.g. DRFL-3)', required: true }),
+    };
+    static flags = {
+        ...base_1.projectFlag,
+        'run-id': core_1.Flags.string({ description: 'Automation run id, for tokens that juggle several concurrent runs' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(TicketsLeaseRelease);
+        const projectId = await this.resolveProjectId(flags.project);
+        const path = `/cli/v1/projects/${encodeURIComponent(projectId)}/tickets/${encodeURIComponent(args.id)}/lease`;
+        const body = {};
+        if (flags['run-id'] !== undefined)
+            body.run_id = flags['run-id'];
+        let res;
+        try {
+            res = await this.api.delete(path, { body });
+        }
+        catch (error) {
+            // 409 = somebody else already holds it, 404 = no lease to release. --json prints the full
+            // backend envelope (details included) itself and returns, so BaseCommand.catch never trims
+            // it down to {code,message}; human mode gets the holder spelled out instead (CYCL-14).
+            if (this.jsonEnabled()) {
+                const envelope = (0, lease_1.leaseErrorEnvelope)(error);
+                if (!envelope)
+                    throw error;
+                this.logJson(envelope);
+                process.exitCode = 1;
+                return;
+            }
+            throw (0, lease_1.describeLeaseConflict)(error);
+        }
+        if (!this.jsonEnabled()) {
+            this.log(`Ticket ${args.id} lease released:`);
+            this.log((0, output_1.renderRecord)(res.data ?? {}));
+        }
+        return res;
+    }
+}
+exports.default = TicketsLeaseRelease;

package/dist/commands/tickets/lease/renew.d.ts

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../../base';
+export default class TicketsLeaseRenew extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        ttl: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'run-id': 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/tickets/lease/renew.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../../base");
+const lease_1 = require("../../../lib/lease");
+const output_1 = require("../../../lib/output");
+class TicketsLeaseRenew extends base_1.BaseCommand {
+    static description = 'Extend your own working lease on a ticket before it expires';
+    static examples = [
+        '<%= config.bin %> tickets lease renew <ticket-id> --project acme-api',
+        '<%= config.bin %> tickets lease renew DRFL-3 -p driverone-flutter --ttl 3600 --run-id run-42',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Ticket id or code (e.g. DRFL-3)', required: true }),
+    };
+    static flags = {
+        ...base_1.projectFlag,
+        ttl: core_1.Flags.integer({ description: 'New lease duration in seconds (server default: 8h; range 1s..30 days)' }),
+        'run-id': core_1.Flags.string({ description: 'Automation run id, for tokens that juggle several concurrent runs' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(TicketsLeaseRenew);
+        const projectId = await this.resolveProjectId(flags.project);
+        const path = `/cli/v1/projects/${encodeURIComponent(projectId)}/tickets/${encodeURIComponent(args.id)}/lease`;
+        const body = {};
+        if (flags.ttl !== undefined)
+            body.ttl_seconds = flags.ttl;
+        if (flags['run-id'] !== undefined)
+            body.run_id = flags['run-id'];
+        let res;
+        try {
+            res = await this.api.put(path, body);
+        }
+        catch (error) {
+            // 409 = somebody else already holds it, 404 = no lease to renew. --json prints the full
+            // backend envelope (details included) itself and returns, so BaseCommand.catch never trims
+            // it down to {code,message}; human mode gets the holder spelled out instead (CYCL-14).
+            if (this.jsonEnabled()) {
+                const envelope = (0, lease_1.leaseErrorEnvelope)(error);
+                if (!envelope)
+                    throw error;
+                this.logJson(envelope);
+                process.exitCode = 1;
+                return;
+            }
+            throw (0, lease_1.describeLeaseConflict)(error);
+        }
+        if (!this.jsonEnabled()) {
+            const lease = res.data ?? {};
+            this.log(`Ticket ${args.id} lease renewed until ${lease.expires_at ?? '?'}:`);
+            this.log((0, output_1.renderRecord)(leaseSummary(lease)));
+        }
+        return res;
+    }
+}
+exports.default = TicketsLeaseRenew;
+/** Flatten the lease payload for `renderRecord`: `held_by` is a nested object, so print it as one line. */
+function leaseSummary(lease) {
+    const heldBy = lease.held_by;
+    return {
+        ticket: lease.ticket,
+        run_id: lease.run_id,
+        held_by: heldBy ? `${heldBy.kind} ${heldBy.name ?? heldBy.id}` : null,
+        expires_at: lease.expires_at,
+        host_id: lease.host_id,
+        account_id: lease.account_id,
+        agent: lease.agent,
+        execution_phase: lease.execution_phase,
+        profile_digest: lease.profile_digest,
+    };
+}

package/dist/lib/lease.d.ts

@@ -0,0 +1,44 @@
+/**
+ * On a 409 lease conflict, rewrite the error message to name who holds the ticket and until when.
+ * An automation reading "R409-LEASE-001: Ticket is already leased" alone cannot decide whether to
+ * skip to the next ticket — it needs the holder. Every other status/code (and a 409 without the
+ * expected `details.holder` shape) passes through untouched, so unrelated errors keep the server's
+ * own wording. Human-mode only: `--json` prints its own full envelope instead (see
+ * `leaseErrorEnvelope`), so it never goes through this rewrite.
+ */
+export declare function describeLeaseConflict(error: unknown): unknown;
+/** Allow-listed `details` for the --json envelope: only the fields a lease conflict is documented to carry. */
+interface LeaseErrorDetails {
+    holder: {
+        held_by: {
+            kind: string;
+            id: string;
+            name?: string;
+        };
+        expires_at?: string;
+    };
+}
+/**
+ * Full `{error:{code,message,details}}` envelope for a lease command failure in `--json` mode.
+ * `BaseCommand.catch` — shared by every command in the CLI — only ever emits `{code,message}`; a
+ * script reading `--json` on a 409 needs `details.holder` too (who holds the ticket, until when),
+ * so lease commands print this themselves and return before the error reaches `catch()`, instead of
+ * changing that shared, cross-cutting behaviour (out of scope for CYCL-14).
+ *
+ * `details` is rebuilt field-by-field from an explicit allow-list (`holder.held_by.{kind,id,name}`,
+ * `holder.expires_at`) instead of forwarding `error.details` verbatim — same reasoning as
+ * `BaseCommand.catch`'s own allow-listed envelope (see `base.ts`): never serialize a server-shaped
+ * object of arbitrary provenance straight into `--json` output. Any other field the backend happens
+ * to send inside `details` (e.g. a stray `holder.ticket`) is dropped, not forwarded.
+ *
+ * Returns undefined for anything that isn't an `ApiRequestError`: callers should let those propagate
+ * to `catch()` as usual.
+ */
+export declare function leaseErrorEnvelope(error: unknown): {
+    error: {
+        code: string;
+        message: string;
+        details?: LeaseErrorDetails;
+    };
+} | undefined;
+export {};

package/dist/lib/lease.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeLeaseConflict = describeLeaseConflict;
+exports.leaseErrorEnvelope = leaseErrorEnvelope;
+const api_1 = require("./api");
+/** Extract `{kind,id,name?,expiresAt?}` from a 409's `details`, or undefined if the shape doesn't match. */
+function parseLeaseHolder(details) {
+    const holder = details?.holder;
+    const heldBy = holder?.held_by;
+    if (!heldBy?.kind || !heldBy.id)
+        return undefined;
+    return { kind: heldBy.kind, id: heldBy.id, name: heldBy.name, expiresAt: holder?.expires_at };
+}
+/**
+ * On a 409 lease conflict, rewrite the error message to name who holds the ticket and until when.
+ * An automation reading "R409-LEASE-001: Ticket is already leased" alone cannot decide whether to
+ * skip to the next ticket — it needs the holder. Every other status/code (and a 409 without the
+ * expected `details.holder` shape) passes through untouched, so unrelated errors keep the server's
+ * own wording. Human-mode only: `--json` prints its own full envelope instead (see
+ * `leaseErrorEnvelope`), so it never goes through this rewrite.
+ */
+function describeLeaseConflict(error) {
+    if (!(error instanceof api_1.ApiRequestError) || error.status !== 409)
+        return error;
+    const holder = parseLeaseHolder(error.details);
+    if (!holder)
+        return error;
+    const who = holder.name ? `${holder.kind} "${holder.name}"` : `${holder.kind} ${holder.id}`;
+    const until = holder.expiresAt ? ` until ${holder.expiresAt}` : '';
+    return new api_1.ApiRequestError(error.status, error.code, `Ticket already leased by ${who}${until}.`, error.details);
+}
+/**
+ * Full `{error:{code,message,details}}` envelope for a lease command failure in `--json` mode.
+ * `BaseCommand.catch` — shared by every command in the CLI — only ever emits `{code,message}`; a
+ * script reading `--json` on a 409 needs `details.holder` too (who holds the ticket, until when),
+ * so lease commands print this themselves and return before the error reaches `catch()`, instead of
+ * changing that shared, cross-cutting behaviour (out of scope for CYCL-14).
+ *
+ * `details` is rebuilt field-by-field from an explicit allow-list (`holder.held_by.{kind,id,name}`,
+ * `holder.expires_at`) instead of forwarding `error.details` verbatim — same reasoning as
+ * `BaseCommand.catch`'s own allow-listed envelope (see `base.ts`): never serialize a server-shaped
+ * object of arbitrary provenance straight into `--json` output. Any other field the backend happens
+ * to send inside `details` (e.g. a stray `holder.ticket`) is dropped, not forwarded.
+ *
+ * Returns undefined for anything that isn't an `ApiRequestError`: callers should let those propagate
+ * to `catch()` as usual.
+ */
+function leaseErrorEnvelope(error) {
+    if (!(error instanceof api_1.ApiRequestError))
+        return undefined;
+    const holder = parseLeaseHolder(error.details);
+    const details = holder
+        ? {
+            holder: {
+                held_by: holder.name ? { kind: holder.kind, id: holder.id, name: holder.name } : { kind: holder.kind, id: holder.id },
+                ...(holder.expiresAt ? { expires_at: holder.expiresAt } : {}),
+            },
+        }
+        : undefined;
+    return { error: { code: error.code, message: error.message, details } };
+}