@knpkv/jira-cli 0.1.1 → 0.3.0

package/dist/commands/version.js

@@ -0,0 +1,179 @@
+/**
+ * `jira version` command — list / view Jira project versions (releases) with
+ * Driver, Contributors and Approver fields resolved to display names, plus
+ * mutations: edit the description and manage "Related work" links (the
+ * Confluence pages surfaced on a release report).
+ *
+ * @internal
+ */
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { Argument as Args, Command, Flag as Options } from "effect/unstable/cli";
+import { JiraApiError } from "../JiraCliError.js";
+import { VersionService } from "../VersionService.js";
+/**
+ * Return a copy of `version` with every resolved {@link Person.emailAddress}
+ * (PII) set to null — covering driver, contributors, approvers[].person and
+ * tickets[].assignee. Used to keep emails out of `--json` output unless the
+ * caller opts in with `--emails`.
+ */
+export const stripEmails = (version) => {
+    const stripPerson = (person) => ({ ...person, emailAddress: null });
+    return {
+        ...version,
+        driver: version.driver ? stripPerson(version.driver) : null,
+        contributors: version.contributors.map(stripPerson),
+        approvers: version.approvers.map((a) => ({ ...a, person: stripPerson(a.person) })),
+        tickets: version.tickets.map((t) => ({
+            ...t,
+            assignee: t.assignee ? stripPerson(t.assignee) : null
+        }))
+    };
+};
+/**
+ * Jira version ids are numeric (e.g. `10042`). Passing a name/key 404s with an
+ * opaque error, so validate early and emit a hint pointing at `version list`.
+ */
+const ensureNumericId = (id) => /^\d+$/.test(id)
+    ? Effect.void
+    : Effect.fail(new JiraApiError({
+        message: `Invalid version id "${id}". The version id is numeric (e.g. 10042); ` +
+            `use 'jira version list --project <KEY>' to find it.`
+    }));
+const projectOption = Options.string("project").pipe(Options.withAlias("p"), Options.withDescription("Jira project key (e.g. RPS)"));
+const releasedOption = Options.boolean("released").pipe(Options.withDescription("Only list released versions"), Options.withDefault(false));
+const unreleasedOption = Options.boolean("unreleased").pipe(Options.withDescription("Only list unreleased versions"), Options.withDefault(false));
+const jsonOption = Options.boolean("json").pipe(Options.withDescription("Output as JSON"), Options.withDefault(false));
+const emailsOption = Options.boolean("emails").pipe(Options.withDescription("Include resolved user email addresses in --json output"), Options.withDefault(false));
+const customFieldOption = Options.string("custom-field").pipe(Options.withDescription("Custom field display name to include on each ticket (repeatable, e.g. " +
+    "--custom-field \"Security & Compliance Impact\"). Values are exposed in " +
+    "ticket.customFields[<name>]."), Options.atLeast(0));
+const maxOption = Options.integer("max").pipe(Options.withAlias("m"), Options.withDescription("Maximum number of versions to fetch (default: all)"), Options.optional);
+const idArg = Args.string("id").pipe(Args.withDescription("Version id (numeric)"));
+const listCommand = Command.make("list", {
+    project: projectOption,
+    released: releasedOption,
+    unreleased: unreleasedOption,
+    customFields: customFieldOption,
+    max: maxOption,
+    json: jsonOption,
+    emails: emailsOption
+}, ({ customFields, emails, json, max, project, released, unreleased }) => Effect.gen(function* () {
+    if (released && unreleased) {
+        return yield* Effect.fail(new JiraApiError({
+            message: "--released and --unreleased are mutually exclusive; pass at most one (omit both to list all)."
+        }));
+    }
+    const service = yield* VersionService;
+    const versions = yield* service.listProjectVersions(project, {
+        released,
+        unreleased,
+        ...(Option.isSome(max) ? { maxResults: max.value } : {}),
+        customFieldNames: customFields
+    });
+    if (json) {
+        const output = emails ? versions : versions.map(stripEmails);
+        yield* Console.log(JSON.stringify(output, null, 2));
+        return;
+    }
+    const sep = "  ";
+    yield* Console.log(["id", "name", "released", "releaseDate", "driver", "contributors", "approvers"].join(sep));
+    for (const v of versions) {
+        yield* Console.log([
+            v.id,
+            v.name,
+            String(v.released),
+            v.releaseDate ?? "-",
+            v.driver?.displayName ?? "-",
+            v.contributors.map((c) => c.displayName).join("|") || "-",
+            v.approvers.map((a) => `${a.person.displayName}:${a.status}`).join("|") || "-"
+        ].join(sep));
+    }
+})).pipe(Command.withDescription("List versions for a Jira project"));
+/** Cap on the number of ticket keys listed in the human `view` output. */
+const TICKET_KEYS_LIMIT = 20;
+const viewCommand = Command.make("view", { id: idArg, json: jsonOption, emails: emailsOption }, ({ emails, id, json }) => Effect.gen(function* () {
+    yield* ensureNumericId(id);
+    const service = yield* VersionService;
+    const version = yield* service.getVersion(id);
+    if (json) {
+        const output = emails ? version : stripEmails(version);
+        yield* Console.log(JSON.stringify(output, null, 2));
+        return;
+    }
+    yield* Console.log(`# ${version.name} (${version.id})`);
+    yield* Console.log(`released: ${version.released}`);
+    yield* Console.log(`releaseDate: ${version.releaseDate ?? "-"}`);
+    yield* Console.log(`driver: ${version.driver?.displayName ?? "-"}`);
+    yield* Console.log(`contributors: ${version.contributors.map((c) => c.displayName).join(", ") || "-"}`);
+    yield* Console.log(`approvers: ${version.approvers.map((a) => `${a.person.displayName}:${a.status}`).join(", ") || "-"}`);
+    yield* Console.log(`tickets (${version.tickets.length}): ${formatTicketKeys(version.tickets)}`);
+})).pipe(Command.withDescription("Show a single Jira version"));
+/**
+ * Render a version's ticket keys for the human `view`: the first
+ * {@link TICKET_KEYS_LIMIT} keys, with a `(+M more)` suffix when truncated, or
+ * `-` when there are none.
+ */
+const formatTicketKeys = (tickets) => {
+    if (tickets.length === 0)
+        return "-";
+    const keys = tickets.map((t) => t.key);
+    const shown = keys.slice(0, TICKET_KEYS_LIMIT).join(", ");
+    const remaining = keys.length - TICKET_KEYS_LIMIT;
+    return remaining > 0 ? `${shown} (+${remaining} more)` : shown;
+};
+const descriptionOption = Options.string("description").pipe(Options.withAlias("d"), Options.withDescription("New version description"));
+const setCommand = Command.make("set", { id: idArg, description: descriptionOption, json: jsonOption }, ({ description, id, json }) => Effect.gen(function* () {
+    yield* ensureNumericId(id);
+    const service = yield* VersionService;
+    const version = yield* service.updateVersion(id, { description });
+    if (json) {
+        yield* Console.log(JSON.stringify(version, null, 2));
+        return;
+    }
+    yield* Console.log(`Updated version ${version.name} (${version.id})`);
+    yield* Console.log(`description: ${version.description ?? "-"}`);
+})).pipe(Command.withDescription("Update a version's description (requires manage:jira-project scope)"));
+// === relatedwork ===
+const titleOption = Options.string("title").pipe(Options.withAlias("t"), Options.withDescription("Related-work link title (e.g. \"Release notes\")"));
+const urlOption = Options.string("url").pipe(Options.withAlias("u"), Options.withDescription("Related-work link URL (e.g. a Confluence page)"));
+const categoryOption = Options.string("category").pipe(Options.withAlias("c"), Options.withDescription("Related-work category (Jira groups by this; e.g. Communication, Testing, Design)"), Options.withDefault("Communication"));
+const relatedWorkListCommand = Command.make("list", { id: idArg, json: jsonOption }, ({ id, json }) => Effect.gen(function* () {
+    yield* ensureNumericId(id);
+    const service = yield* VersionService;
+    const items = yield* service.listRelatedWork(id);
+    if (json) {
+        yield* Console.log(JSON.stringify(items, null, 2));
+        return;
+    }
+    if (items.length === 0) {
+        yield* Console.log("(no related work)");
+        return;
+    }
+    const sep = "  ";
+    yield* Console.log(["category", "title", "url"].join(sep));
+    for (const w of items) {
+        yield* Console.log([w.category || "-", w.title ?? "-", w.url ?? "-"].join(sep));
+    }
+})).pipe(Command.withDescription("List a version's related-work links"));
+const relatedWorkAddCommand = Command.make("add", {
+    id: idArg,
+    title: titleOption,
+    url: urlOption,
+    category: categoryOption,
+    json: jsonOption
+}, ({ category, id, json, title, url }) => Effect.gen(function* () {
+    yield* ensureNumericId(id);
+    const service = yield* VersionService;
+    const created = yield* service.addRelatedWork(id, { title, category, url });
+    if (json) {
+        yield* Console.log(JSON.stringify(created, null, 2));
+        return;
+    }
+    yield* Console.log(`Attached "${created.title ?? title}" (${created.category}) to version ${id}`);
+    yield* Console.log(`url: ${created.url ?? url}`);
+})).pipe(Command.withDescription("Attach a related-work link (e.g. a Confluence page) to a version (requires manage:jira-project scope)"));
+const relatedWorkCommand = Command.make("relatedwork").pipe(Command.withDescription("List or attach version related-work links (Confluence pages on the release report)"), Command.withSubcommands([relatedWorkListCommand, relatedWorkAddCommand]));
+export const versionCommand = Command.make("version").pipe(Command.withDescription("List, view, or edit Jira project versions (releases)"), Command.withSubcommands([listCommand, viewCommand, setCommand, relatedWorkCommand]));
+//# sourceMappingURL=version.js.map

package/dist/commands/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/commands/version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,QAAQ,IAAI,IAAI,EAAE,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAChF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAErD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAgB,EAAW,EAAE;IACvD,MAAM,WAAW,GAAG,CAAmB,MAAS,EAAK,EAAE,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAA;IAC3F,OAAO;QACL,GAAG,OAAO;QACV,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI;QAC3D,YAAY,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,CAAC;QACnD,SAAS,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAClF,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACnC,GAAG,CAAC;YACJ,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI;SACtD,CAAC,CAAC;KACJ,CAAA;AACH,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,eAAe,GAAG,CAAC,EAAU,EAAqC,EAAE,CACxE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;IACd,CAAC,CAAC,MAAM,CAAC,IAAI;IACb,CAAC,CAAC,MAAM,CAAC,IAAI,CACX,IAAI,YAAY,CAAC;QACf,OAAO,EAAE,uBAAuB,EAAE,6CAA6C;YAC7E,qDAAqD;KACxD,CAAC,CACH,CAAA;AAEL,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAClD,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,EACtB,OAAO,CAAC,eAAe,CAAC,6BAA6B,CAAC,CACvD,CAAA;AACD,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,IAAI,CACrD,OAAO,CAAC,eAAe,CAAC,6BAA6B,CAAC,EACtD,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAC3B,CAAA;AACD,MAAM,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,IAAI,CACzD,OAAO,CAAC,eAAe,CAAC,+BAA+B,CAAC,EACxD,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAC3B,CAAA;AACD,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAC7C,OAAO,CAAC,eAAe,CAAC,gBAAgB,CAAC,EACzC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAC3B,CAAA;AACD,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,IAAI,CACjD,OAAO,CAAC,eAAe,CAAC,wDAAwD,CAAC,EACjF,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAC3B,CAAA;AACD,MAAM,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,IAAI,CAC3D,OAAO,CAAC,eAAe,CACrB,wEAAwE;IACtE,0EAA0E;IAC1E,8BAA8B,CACjC,EACD,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CACnB,CAAA;AACD,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAC3C,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,EACtB,OAAO,CAAC,eAAe,CAAC,oDAAoD,CAAC,EAC7E,OAAO,CAAC,QAAQ,CACjB,CAAA;AAED,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,sBAAsB,CAAC,CAAC,CAAA;AAElF,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE;IACvC,OAAO,EAAE,aAAa;IACtB,QAAQ,EAAE,cAAc;IACxB,UAAU,EAAE,gBAAgB;IAC5B,YAAY,EAAE,iBAAiB;IAC/B,GAAG,EAAE,SAAS;IACd,IAAI,EAAE,UAAU;IAChB,MAAM,EAAE,YAAY;CACrB,EAAE,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE,CACxE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,IAAI,QAAQ,IAAI,UAAU,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CACvB,IAAI,YAAY,CAAC;YACf,OAAO,EAAE,+FAA+F;SACzG,CAAC,CACH,CAAA;IACH,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,cAAc,CAAA;IACrC,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC,OAAO,EAAE;QAC3D,QAAQ;QACR,UAAU;QACV,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,gBAAgB,EAAE,YAAY;KAC/B,CAAC,CAAA;IACF,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;QAC5D,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAA;QACnD,OAAM;IACR,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAA;IAChB,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,QAAQ,EAAE,cAAc,EAAE,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;IAC9G,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;YACjB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,IAAI;YACN,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;YAClB,CAAC,CAAC,WAAW,IAAI,GAAG;YACpB,CAAC,CAAC,MAAM,EAAE,WAAW,IAAI,GAAG;YAC5B,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG;YACzD,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,WAAW,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG;SAC/E,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;IACd,CAAC;AACH,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,kCAAkC,CAAC,CAAC,CAAA;AAEvE,0EAA0E;AAC1E,MAAM,iBAAiB,GAAG,EAAE,CAAA;AAE5B,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAC9B,MAAM,EACN,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,EACrD,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CACvB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,KAAK,CAAC,CAAC,eAAe,CAAC,EAAE,CAAC,CAAA;IAC1B,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,cAAc,CAAA;IACrC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAA;IAC7C,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;QACtD,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAA;QACnD,OAAM;IACR,CAAC;IACD,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,EAAE,GAAG,CAAC,CAAA;IACvD,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;IACnD,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,OAAO,CAAC,WAAW,IAAI,GAAG,EAAE,CAAC,CAAA;IAChE,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,OAAO,CAAC,MAAM,EAAE,WAAW,IAAI,GAAG,EAAE,CAAC,CAAA;IACnE,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC,CAAA;IACvG,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAChB,cAAc,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,WAAW,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,EAAE,CACtG,CAAA;IACD,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,OAAO,CAAC,OAAO,CAAC,MAAM,MAAM,gBAAgB,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;AACjG,CAAC,CAAC,CACL,CAAC,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,4BAA4B,CAAC,CAAC,CAAA;AAE7D;;;;GAIG;AACH,MAAM,gBAAgB,GAAG,CAAC,OAA2B,EAAU,EAAE;IAC/D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,CAAA;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACtC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACzD,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,GAAG,iBAAiB,CAAA;IACjD,OAAO,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,MAAM,SAAS,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAA;AAChE,CAAC,CAAA;AAED,MAAM,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,IAAI,CAC1D,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,EACtB,OAAO,CAAC,eAAe,CAAC,yBAAyB,CAAC,CACnD,CAAA;AAED,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,CAAC,EACvG,WAAW,EACX,EAAE,EACF,IAAI,EACL,EAAE,EAAE,CACH,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,KAAK,CAAC,CAAC,eAAe,CAAC,EAAE,CAAC,CAAA;IAC1B,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,cAAc,CAAA;IACrC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,CAAA;IACjE,IAAI,IAAI,EAAE,CAAC;QACT,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAA;QACpD,OAAM;IACR,CAAC;IACD,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,EAAE,GAAG,CAAC,CAAA;IACrE,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,OAAO,CAAC,WAAW,IAAI,GAAG,EAAE,CAAC,CAAA;AAClE,CAAC,CAAC,CAAC,CAAC,IAAI,CACN,OAAO,CAAC,eAAe,CAAC,qEAAqE,CAAC,CAC/F,CAAA;AAEH,sBAAsB;AAEtB,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAC9C,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,EACtB,OAAO,CAAC,eAAe,CAAC,kDAAkD,CAAC,CAC5E,CAAA;AACD,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAC1C,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,EACtB,OAAO,CAAC,eAAe,CAAC,gDAAgD,CAAC,CAC1E,CAAA;AACD,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CACpD,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,EACtB,OAAO,CAAC,eAAe,CAAC,kFAAkF,CAAC,EAC3G,OAAO,CAAC,WAAW,CAAC,eAAe,CAAC,CACrC,CAAA;AAED,MAAM,sBAAsB,GAAG,OAAO,CAAC,IAAI,CACzC,MAAM,EACN,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,EAC/B,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CACf,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,KAAK,CAAC,CAAC,eAAe,CAAC,EAAE,CAAC,CAAA;IAC1B,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,cAAc,CAAA;IACrC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC,CAAA;IAChD,IAAI,IAAI,EAAE,CAAC;QACT,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAA;QAClD,OAAM;IACR,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAA;QACvC,OAAM;IACR,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAA;IAChB,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;IAC1D,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,GAAG,EAAE,CAAC,CAAC,KAAK,IAAI,GAAG,EAAE,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;IACjF,CAAC;AACH,CAAC,CAAC,CACL,CAAC,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,qCAAqC,CAAC,CAAC,CAAA;AAEtE,MAAM,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE;IAChD,EAAE,EAAE,KAAK;IACT,KAAK,EAAE,WAAW;IAClB,GAAG,EAAE,SAAS;IACd,QAAQ,EAAE,cAAc;IACxB,IAAI,EAAE,UAAU;CACjB,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,CACxC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,KAAK,CAAC,CAAC,eAAe,CAAC,EAAE,CAAC,CAAA;IAC1B,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,cAAc,CAAA;IACrC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAA;IAC3E,IAAI,IAAI,EAAE,CAAC;QACT,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAA;QACpD,OAAM;IACR,CAAC;IACD,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,OAAO,CAAC,KAAK,IAAI,KAAK,MAAM,OAAO,CAAC,QAAQ,gBAAgB,EAAE,EAAE,CAAC,CAAA;IACjG,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,OAAO,CAAC,GAAG,IAAI,GAAG,EAAE,CAAC,CAAA;AAClD,CAAC,CAAC,CAAC,CAAC,IAAI,CACN,OAAO,CAAC,eAAe,CACrB,uGAAuG,CACxG,CACF,CAAA;AAEH,MAAM,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,CACzD,OAAO,CAAC,eAAe,CAAC,oFAAoF,CAAC,EAC7G,OAAO,CAAC,eAAe,CAAC,CAAC,sBAAsB,EAAE,qBAAqB,CAAC,CAAC,CACzE,CAAA;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CACxD,OAAO,CAAC,eAAe,CAAC,sDAAsD,CAAC,EAC/E,OAAO,CAAC,eAAe,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,kBAAkB,CAAC,CAAC,CACpF,CAAA"}

package/dist/internal/oauthServer.d.ts

@@ -1,9 +1,21 @@
-import * as HttpServer from "@effect/platform/HttpServer";
-import type { ServeError } from "@effect/platform/HttpServerError";
+/**
+ * Local HTTP callback server for OAuth2 authorization code capture.
+ *
+ * **Mental model**
+ *
+ * - **Deferred-coordinated lifecycle**: {@link startCallbackServer} returns a `codePromise`
+ *   (Deferred) and a `shutdown` effect. The server validates the CSRF `state` parameter
+ *   and resolves the Deferred with the authorization code.
+ * - **Port auto-discovery**: Tries default port 8585, increments on conflict.
+ *
+ * @internal
+ */
 import { OAuthError } from "@knpkv/atlassian-common/auth";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import { HttpServer } from "effect/unstable/http";
+import type * as HttpServerError from "effect/unstable/http/HttpServerError";
 /**
  * Factory service for creating HTTP servers.
  * This allows mocking the server creation in tests.
@@ -11,9 +23,9 @@ import * as Layer from "effect/Layer";
  * @category Services
  */
 export interface HttpServerFactory {
-    readonly createServerLayer: (port: number) => Layer.Layer<HttpServer.HttpServer, ServeError, never>;
+    readonly createServerLayer: (port: number) => Layer.Layer<HttpServer.HttpServer, HttpServerError.ServeError, never>;
 }
-declare const HttpServerFactoryTag_base: Context.TagClass<HttpServerFactoryTag, "@knpkv/jira-cli/HttpServerFactory", HttpServerFactory>;
+declare const HttpServerFactoryTag_base: Context.ServiceClass<HttpServerFactoryTag, "@knpkv/jira-cli/HttpServerFactory", HttpServerFactory>;
 /**
  * Tag for the HttpServerFactory service.
  *
@@ -30,7 +42,7 @@ export declare class HttpServerFactoryTag extends HttpServerFactoryTag_base {
  *
  * @category Layers
  */
-export declare const makeHttpServerFactory: (createLayerFn: (port: number) => Layer.Layer<HttpServer.HttpServer, ServeError, never>) => Layer.Layer<HttpServerFactoryTag>;
+export declare const makeHttpServerFactory: (createLayerFn: (port: number) => Layer.Layer<HttpServer.HttpServer, HttpServerError.ServeError, never>) => Layer.Layer<HttpServerFactoryTag>;
 /**
  * Result from the OAuth callback server.
  */

package/dist/internal/oauthServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauthServer.d.ts","sourceRoot":"","sources":["../../src/internal/oauthServer.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,UAAU,MAAM,6BAA6B,CAAA;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAA;AAGlE,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAA;AACzD,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAEzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAKrC;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC,KAAK,CACvD,UAAU,CAAC,UAAU,EACrB,UAAU,EACV,KAAK,CACN,CAAA;CACF;;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,yBAGvC;CAAG;AAEN;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,GAChC,eAAe,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,CAAC,KACrF,KAAK,CAAC,KAAK,CAAC,oBAAoB,CAG/B,CAAA;AAwCJ;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IACvD,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;IAC7C,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAC9B,eAAe,MAAM,KACpB,MAAM,CAAC,MAAM,CAAC,oBAAoB,EAAE,UAAU,EAAE,oBAAoB,CA2EnE,CAAA"}
+{"version":3,"file":"oauthServer.d.ts","sourceRoot":"","sources":["../../src/internal/oauthServer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAA;AACzD,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAEzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAErC,OAAO,EAAc,UAAU,EAAsB,MAAM,sBAAsB,CAAA;AACjF,OAAO,KAAK,KAAK,eAAe,MAAM,sCAAsC,CAAA;AAK5E;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC,KAAK,CACvD,UAAU,CAAC,UAAU,EACrB,eAAe,CAAC,UAAU,EAC1B,KAAK,CACN,CAAA;CACF;;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,yBAGF;CAAG;AAE3C;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,GAChC,eAAe,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,EAAE,eAAe,CAAC,UAAU,EAAE,KAAK,CAAC,KACrG,KAAK,CAAC,KAAK,CAAC,oBAAoB,CAG/B,CAAA;AAEJ;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IACvD,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;IAC7C,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAC9B,eAAe,MAAM,KACpB,MAAM,CAAC,MAAM,CAAC,oBAAoB,EAAE,UAAU,EAAE,oBAAoB,CAuFnE,CAAA"}

package/dist/internal/oauthServer.js

@@ -10,24 +10,23 @@
  *
  * @internal
  */
-import * as HttpRouter from "@effect/platform/HttpRouter";
-import * as HttpServer from "@effect/platform/HttpServer";
-import * as HttpServerRequest from "@effect/platform/HttpServerRequest";
-import * as HttpServerResponse from "@effect/platform/HttpServerResponse";
 import { OAuthError } from "@knpkv/atlassian-common/auth";
 import * as Context from "effect/Context";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
 import * as Fiber from "effect/Fiber";
 import * as Layer from "effect/Layer";
+import * as Scope from "effect/Scope";
+import { HttpRouter, HttpServer, HttpServerResponse } from "effect/unstable/http";
 const DEFAULT_PORT = 8585;
-const MAX_PORT_ATTEMPTS = 10;
+const MAX_PORT = 8594;
 /**
  * Tag for the HttpServerFactory service.
  *
  * @category Services
  */
-export class HttpServerFactoryTag extends Context.Tag("@knpkv/jira-cli/HttpServerFactory")() {
+export class HttpServerFactoryTag extends Context.Service()("@knpkv/jira-cli/HttpServerFactory") {
 }
 /**
  * Create a HttpServerFactory layer from a layer factory function.
@@ -41,31 +40,6 @@ export class HttpServerFactoryTag extends Context.Tag("@knpkv/jira-cli/HttpServe
 export const makeHttpServerFactory = (createLayerFn) => Layer.succeed(HttpServerFactoryTag, {
     createServerLayer: createLayerFn
 });
-/**
- * Check if a port is available by attempting to start a server.
- */
-const isPortAvailable = (port) => Effect.gen(function* () {
-    const factory = yield* HttpServerFactoryTag;
-    const serverLayer = factory.createServerLayer(port);
-    const result = yield* Layer.build(serverLayer).pipe(Effect.scoped, Effect.as(true), Effect.catchAll(() => Effect.succeed(false)));
-    return result;
-});
-/**
- * Find an available port starting from the default.
- */
-const findAvailablePort = () => Effect.gen(function* () {
-    for (let attempt = 0; attempt < MAX_PORT_ATTEMPTS; attempt++) {
-        const port = DEFAULT_PORT + attempt;
-        const available = yield* isPortAvailable(port);
-        if (available) {
-            return port;
-        }
-    }
-    return yield* Effect.fail(new OAuthError({
-        step: "authorize",
-        cause: `Could not find available port (tried ${DEFAULT_PORT}-${DEFAULT_PORT + MAX_PORT_ATTEMPTS - 1}). Close other applications using these ports.`
-    }));
-});
 /**
  * Start a local HTTP server to receive OAuth callback.
  *
@@ -76,11 +50,18 @@ const findAvailablePort = () => Effect.gen(function* () {
  */
 export const startCallbackServer = (expectedState) => Effect.gen(function* () {
     const factory = yield* HttpServerFactoryTag;
-    const port = yield* findAvailablePort();
     const deferred = yield* Deferred.make();
-    const readyDeferred = yield* Deferred.make();
-    const app = HttpRouter.empty.pipe(HttpRouter.get("/callback", Effect.gen(function* () {
-        const req = yield* HttpServerRequest.HttpServerRequest;
+    const serverScope = yield* Scope.make();
+    const buildServerContext = (port) => Layer.buildWithScope(factory.createServerLayer(port), serverScope).pipe(Effect.map((context) => ({ context, port })), Effect.catchCause((cause) => port < MAX_PORT
+        ? buildServerContext(port + 1)
+        : Effect.fail(new OAuthError({ step: "authorize", cause }))));
+    const { context: serverContext } = yield* buildServerContext(DEFAULT_PORT);
+    const server = Context.get(serverContext, HttpServer.HttpServer);
+    const port = yield* (server.address._tag === "TcpAddress"
+        ? Effect.succeed(server.address.port)
+        : Effect.fail(new OAuthError({ step: "authorize", cause: "OAuth callback server must listen on a TCP port" })));
+    const router = yield* HttpRouter.make;
+    yield* router.add("GET", "/callback", (req) => Effect.gen(function* () {
         const url = new URL(req.url, `http://localhost:${port}`);
         const code = url.searchParams.get("code");
         const state = url.searchParams.get("state");
@@ -100,13 +81,15 @@ export const startCallbackServer = (expectedState) => Effect.gen(function* () {
         }
         yield* Deferred.succeed(deferred, code);
         return HttpServerResponse.html("<html><body><h1>Success!</h1><p>You can close this window and return to the terminal.</p></body></html>");
-    })));
-    const serverLayer = factory.createServerLayer(port);
-    const serverFiber = yield* HttpServer.serve(app).pipe(Layer.provide(serverLayer), Layer.build, Effect.tap(() => Deferred.succeed(readyDeferred, undefined)), Effect.tapError((err) => Deferred.fail(readyDeferred, new OAuthError({ step: "authorize", cause: err }))), Effect.flatMap(() => Effect.never), Effect.scoped, Effect.fork);
-    yield* Deferred.await(readyDeferred);
+    }));
+    const app = router.asHttpEffect();
+    const serverFiber = yield* HttpServer.serveEffect(app).pipe(Effect.provide(serverContext), Effect.provideService(Scope.Scope, serverScope), Effect.forkIn(serverScope));
     return {
         codePromise: Deferred.await(deferred),
-        shutdown: Fiber.interrupt(serverFiber).pipe(Effect.asVoid),
+        shutdown: Effect.gen(function* () {
+            yield* Fiber.interrupt(serverFiber);
+            yield* Scope.close(serverScope, Exit.void);
+        }),
         port
     };
 });

package/dist/internal/oauthServer.js.map

@@ -1 +1 @@
-{"version":3,"file":"oauthServer.js","sourceRoot":"","sources":["../../src/internal/oauthServer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"oauthServer.js","sourceRoot":"","sources":["../../src/internal/oauthServer.ts"],"names":[],"mappings":"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"}

package/dist/internal/openBrowser.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Cross-platform browser launcher backed by Effect v4 child process services.
+ *
+ * @internal
+ */
+import * as Effect from "effect/Effect";
+import type * as PlatformError from "effect/PlatformError";
+import { ChildProcessSpawner } from "effect/unstable/process";
+export declare const openBrowser: (url: string) => Effect.Effect<void, PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner>;
+//# sourceMappingURL=openBrowser.d.ts.map

package/dist/internal/openBrowser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openBrowser.d.ts","sourceRoot":"","sources":["../../src/internal/openBrowser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,aAAa,MAAM,sBAAsB,CAAA;AAC1D,OAAO,EAAgB,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAiB3E,eAAO,MAAM,WAAW,GACtB,KAAK,MAAM,KACV,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,aAAa,EAAE,mBAAmB,CAAC,mBAAmB,CAIxF,CAAA"}

package/dist/internal/openBrowser.js

@@ -0,0 +1,17 @@
+/**
+ * Cross-platform browser launcher backed by Effect v4 child process services.
+ *
+ * @internal
+ */
+import * as Effect from "effect/Effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+const run = (command, args) => Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    yield* spawner.exitCode(ChildProcess.make(command, args, {
+        stdin: "ignore",
+        stdout: "ignore",
+        stderr: "ignore"
+    }));
+});
+export const openBrowser = (url) => run("open", [url]).pipe(Effect.catch(() => run("xdg-open", [url])), Effect.catch(() => run("rundll32.exe", ["url.dll,FileProtocolHandler", url])));
+//# sourceMappingURL=openBrowser.js.map

package/dist/internal/openBrowser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openBrowser.js","sourceRoot":"","sources":["../../src/internal/openBrowser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAE3E,MAAM,GAAG,GAAG,CACV,OAAe,EACf,IAA2B,EACgE,EAAE,CAC7F,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,mBAAmB,CAAC,mBAAmB,CAAA;IAC9D,KAAK,CAAC,CAAC,OAAO,CAAC,QAAQ,CACrB,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE;QAC/B,KAAK,EAAE,QAAQ;QACf,MAAM,EAAE,QAAQ;QAChB,MAAM,EAAE,QAAQ;KACjB,CAAC,CACH,CAAA;AACH,CAAC,CAAC,CAAA;AAEJ,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,GAAW,EACgF,EAAE,CAC7F,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CACrB,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAC1C,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC,6BAA6B,EAAE,GAAG,CAAC,CAAC,CAAC,CAC9E,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knpkv/jira-cli",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "CLI tool to fetch Jira tickets and export to markdown",
   "license": "MIT",
   "author": "knpkv",
@@ -46,23 +46,21 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@effect/platform": ">=0.93.0 <0.96.0",
-    "effect": ">=3.19.3"
+    "effect": "4.0.0-beta.87"
   },
   "dependencies": {
-    "@effect/cli": "latest",
-    "@effect/platform-node": "latest",
+    "@effect/platform-node": "4.0.0-beta.87",
     "gray-matter": "^4.0.3",
-    "@knpkv/atlassian-common": "0.2.0",
-    "@knpkv/jira-api-client": "0.2.0"
+    "@knpkv/agent-skills": "^0.2.0",
+    "@knpkv/atlassian-common": "0.3.0",
+    "@knpkv/jira-api-client": "0.3.0"
   },
   "devDependencies": {
-    "@effect/platform": "latest",
-    "@effect/vitest": "latest",
+    "@effect/vitest": "4.0.0-beta.87",
     "@types/node": "latest",
-    "effect": "latest",
-    "typescript": "~5.9.0",
-    "vitest": "^4.0.13"
+    "effect": "4.0.0-beta.87",
+    "typescript": "~6.0.3",
+    "vitest": "^4.1.9"
   },
   "keywords": [
     "effect",

package/skills/jira/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: jira
+description: Use the @knpkv/jira-cli command line tool to authenticate with Jira Cloud, fetch Jira issues, export issues to markdown, search by JQL or fixVersion, and inspect or update Jira project versions and related work links. Trigger when the user asks an agent to query Jira, collect tickets for release notes, write ticket markdown, inspect release metadata, or attach Confluence release-report links to a Jira version.
+---
+
+# Jira
+
+Use the `jira` binary for Jira Cloud issue export and release-version workflows.
+
+## Preconditions
+
+- Authenticate first with `jira auth status`, `jira auth create`, `jira auth configure`, and `jira auth login`.
+- Use `--json` on version commands when the agent needs structured data.
+- Use numeric version ids for `jira version view`, `jira version set`, and `jira version relatedwork`.
+- Confirm before commands that mutate Jira: `jira version set` and `jira version relatedwork add`.
+
+## Authentication
+
+```bash
+jira auth status
+jira auth create
+jira auth configure --client-id <id> --client-secret <secret>
+jira auth login
+jira auth login --site https://example.atlassian.net
+```
+
+OAuth scopes used by release workflows include `read:jira-work`, `write:jira-work`, `manage:jira-project`, `read:jira-user`, `read:me`, and `offline_access`.
+
+## Issue Export
+
+Fetch one issue as markdown:
+
+```bash
+jira get PROJ-123 --output-dir ./jira-tickets
+```
+
+Search with JQL:
+
+```bash
+jira search 'project = PROJ AND status = Done' --output-dir ./jira-tickets
+jira search 'fixVersion = "1.0.0"' --format single --max-results 200
+```
+
+Search by fix version:
+
+```bash
+jira search --by-version "1.0.0" --project PROJ
+jira search --by-version "1.0.0" --project PROJ --format single
+```
+
+Output formats:
+
+- `--format multi` writes one markdown file per issue.
+- `--format single` writes `jira-export.md`.
+
+## Version Workflows
+
+List versions:
+
+```bash
+jira version list --project PROJ --json
+jira version list --project PROJ --unreleased --max 10 --json
+jira version list --project PROJ --custom-field "Security & Compliance Impact" --json
+```
+
+View a version:
+
+```bash
+jira version view 10042 --json
+```
+
+Update a version description:
+
+```bash
+jira version set 10042 --description "Q3 release"
+```
+
+Manage related work links:
+
+```bash
+jira version relatedwork list 10042 --json
+jira version relatedwork add 10042 --title "Release notes" --url "https://example.atlassian.net/wiki/spaces/PROJ/pages/123" --category Communication
+```
+
+## Agent Workflow
+
+1. Use read-only commands first to find issue keys, version ids, and current release metadata.
+2. Prefer `--json` for release metadata and parse the resulting JSON instead of scraping tables.
+3. Avoid printing tokens or OAuth secrets. Let interactive commands prompt for secrets when needed.
+4. Confirm exact version id, title, URL, category, or description before mutating Jira.

package/skills/jira/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Jira CLI"
+  short_description: "Search Jira and manage releases"
+  default_prompt: "Use $jira to search Jira issues, export markdown, or update release metadata."