@jam-mcp/server 1.1.0 → 1.3.0

package/README.md

@@ -70,10 +70,10 @@ auth login   Store Jira credentials in this user's OS secret store
 runtime      Show or change which JAM build this machine runs
 ```
 
-Written out, that is `npx --yes @jam-mcp/launcher@1.1.0 doctor`, or just `jam
+Written out, that is `npx --yes @jam-mcp/launcher@1.3.0 doctor`, or just `jam
 doctor` if you took the launcher's optional global install. Starting from
 nothing — no install, no runtime chosen yet — use
-`npx --yes @jam-mcp/bootstrap@1.1.0 init` instead.
+`npx --yes @jam-mcp/bootstrap@1.3.0 init` instead.
 
 Credentials come from the process environment or this user's OS secret store —
 never from a repository file — and never appear in logs, telemetry, or tool

package/dist/adapters/credentials/windows-user-env.d.ts

@@ -15,6 +15,8 @@ export type RegQueryFn = (name: string) => string | undefined;
  */
 export declare class WindowsUserEnvCredentialSource implements CredentialValueSource {
     private readonly queryFn;
-    constructor(queryFn?: RegQueryFn);
+    private readonly env;
+    constructor(queryFn?: RegQueryFn, env?: NodeJS.ProcessEnv);
     read(): RawCredentialValues;
 }
+export declare function userEnvDisabled(env?: NodeJS.ProcessEnv): boolean;

package/dist/adapters/credentials/windows-user-env.js

@@ -15,12 +15,16 @@ import { CREDENTIAL_ENV_KEYS } from "./process-env.js";
  */
 export class WindowsUserEnvCredentialSource {
     queryFn;
-    constructor(queryFn = defaultRegQuery) {
+    env;
+    constructor(queryFn = defaultRegQuery, env = process.env) {
         this.queryFn = queryFn;
+        this.env = env;
     }
     read() {
         if (process.platform !== "win32")
             return {};
+        if (userEnvDisabled(this.env))
+            return {};
         const out = {};
         for (const key of CREDENTIAL_ENV_KEYS) {
             const value = this.queryFn(key)?.trim();
@@ -30,6 +34,21 @@ export class WindowsUserEnvCredentialSource {
         return out;
     }
 }
+/**
+ * Escape hatch for isolated test sandboxes, matching JAM_DISABLE_SECRET_STORE.
+ *
+ * HKCU\Environment is per-user, not per-HOME, so repointing HOME does not make
+ * a sandbox credential-free on Windows: a developer who ran `setx JIRA_API_TOKEN`
+ * once has credentials that every process of theirs can see. Without this, a
+ * hermetic test would pass or fail depending on whose machine ran it, and
+ * "zero HOME" would be mistaken for "zero credentials".
+ *
+ * Not a user-facing feature. Production never sets it.
+ */
+const DISABLE_ENV = "JAM_DISABLE_USER_ENV";
+export function userEnvDisabled(env = process.env) {
+    return Boolean(env[DISABLE_ENV]);
+}
 const VALUE_LINE = /^\s*\S+\s+REG_(?:SZ|EXPAND_SZ)\s+(.*)$/;
 // Built from a char code rather than a literal backslash escape - a lone
 // backslash before a letter isn't a recognized JS escape and silently

package/dist/adapters/jira-cloud/jira-assignee-resolution.adapter.d.ts

@@ -0,0 +1,39 @@
+import type { AssigneeCandidate } from "../../domain/write.js";
+import type { CredentialPort } from "../../ports/credentials.port.js";
+import type { JiraAssigneeResolutionPort } from "../../ports/jira-assignee-resolution.port.js";
+/**
+ * Jira Cloud REST v3 user directory, read-only.
+ *
+ * Two endpoints, two questions:
+ *
+ *  - `GET /rest/api/3/user/search?query=` - who might this name mean. Jira
+ *    matches display name and, where privacy settings allow it, email. The
+ *    answers are candidates.
+ *  - `GET /rest/api/3/user/assignable/search?issueKey=&accountId=` - may this
+ *    exact account hold this exact issue. Jira answers with the account when
+ *    it may and with nothing when it may not, which is the assignability check
+ *    without JAM having to interpret a permission model it does not own.
+ *
+ * `retry: false` on both. Their answers decide a mutation, so a
+ * retried-and-stale answer is worse than a failure.
+ *
+ * Email is deliberately not part of the identity JAM works with. Jira's
+ * privacy settings routinely blank it - most users on a real site come back
+ * with `emailAddress: ""` - so resolving on it would work for some people and
+ * silently fail for others on the same site.
+ */
+export declare class JiraCloudAssigneeResolutionAdapter implements JiraAssigneeResolutionPort {
+    private readonly client;
+    constructor(credentials: CredentialPort, fetchImpl?: typeof fetch);
+    searchUsers(query: string): Promise<AssigneeCandidate[]>;
+    /**
+     * `GET /rest/api/3/user?accountId=` - the exact lookup, not a search.
+     *
+     * Jira answers 404 when no such account exists or this token cannot see it.
+     * Both mean the same thing to a caller who wanted to assign it, so both
+     * become `undefined` rather than an error: "there is nobody to assign" is an
+     * answer, and the policy layer is where it turns into a refusal.
+     */
+    getUserByAccountId(accountId: string): Promise<AssigneeCandidate | undefined>;
+    isAssignable(issueKey: string, accountId: string): Promise<boolean>;
+}

package/dist/adapters/jira-cloud/jira-assignee-resolution.adapter.js

@@ -0,0 +1,94 @@
+import { JamError } from "../../domain/errors.js";
+import { JiraClient } from "./jira-client.js";
+/** How many candidates are worth reporting back to a human. */
+const SEARCH_LIMIT = 20;
+/**
+ * Jira Cloud REST v3 user directory, read-only.
+ *
+ * Two endpoints, two questions:
+ *
+ *  - `GET /rest/api/3/user/search?query=` - who might this name mean. Jira
+ *    matches display name and, where privacy settings allow it, email. The
+ *    answers are candidates.
+ *  - `GET /rest/api/3/user/assignable/search?issueKey=&accountId=` - may this
+ *    exact account hold this exact issue. Jira answers with the account when
+ *    it may and with nothing when it may not, which is the assignability check
+ *    without JAM having to interpret a permission model it does not own.
+ *
+ * `retry: false` on both. Their answers decide a mutation, so a
+ * retried-and-stale answer is worse than a failure.
+ *
+ * Email is deliberately not part of the identity JAM works with. Jira's
+ * privacy settings routinely blank it - most users on a real site come back
+ * with `emailAddress: ""` - so resolving on it would work for some people and
+ * silently fail for others on the same site.
+ */
+export class JiraCloudAssigneeResolutionAdapter {
+    client;
+    constructor(credentials, fetchImpl) {
+        this.client = fetchImpl ? new JiraClient(credentials, fetchImpl) : new JiraClient(credentials);
+    }
+    async searchUsers(query) {
+        const { data } = await this.client.request({
+            path: "rest/api/3/user/search",
+            query: { query, maxResults: SEARCH_LIMIT },
+            retry: false,
+        });
+        return toCandidates(data);
+    }
+    /**
+     * `GET /rest/api/3/user?accountId=` - the exact lookup, not a search.
+     *
+     * Jira answers 404 when no such account exists or this token cannot see it.
+     * Both mean the same thing to a caller who wanted to assign it, so both
+     * become `undefined` rather than an error: "there is nobody to assign" is an
+     * answer, and the policy layer is where it turns into a refusal.
+     */
+    async getUserByAccountId(accountId) {
+        try {
+            const { data } = await this.client.request({
+                path: "rest/api/3/user",
+                query: { accountId },
+                retry: false,
+            });
+            return toCandidates([data])[0];
+        }
+        catch (err) {
+            if (err instanceof JamError && err.code === "ISSUE_NOT_FOUND")
+                return undefined;
+            throw err;
+        }
+    }
+    async isAssignable(issueKey, accountId) {
+        const { data } = await this.client.request({
+            path: "rest/api/3/user/assignable/search",
+            query: { issueKey, accountId, maxResults: 1 },
+            retry: false,
+        });
+        // Jira answers with the account when it is assignable and with an empty
+        // list when it is not. Matching the id back is belt and braces: an answer
+        // about somebody else is not an answer to the question that was asked.
+        return toCandidates(data).some((u) => u.accountId === accountId);
+    }
+}
+/**
+ * Users JAM can work with, from whatever Jira sent.
+ *
+ * An entry with no accountId is dropped: accountId is the identity, and an
+ * entry without one cannot be assigned, verified, or told apart from another.
+ * App and customer accounts are dropped too - they are not people a human
+ * meant to name, and offering one as a candidate invites assigning an issue to
+ * an integration.
+ */
+function toCandidates(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((u) => typeof u?.accountId === "string" &&
+        (u.accountType === undefined || u.accountType === "atlassian"))
+        .map((u) => ({
+        accountId: u.accountId,
+        displayName: typeof u.displayName === "string" ? u.displayName : u.accountId,
+        active: u.active !== false,
+    }));
+}

package/dist/adapters/jira-cloud/jira-create-metadata.adapter.d.ts

@@ -0,0 +1,27 @@
+import type { CreateFieldMetadata, CreateIssueType } from "../../domain/write.js";
+import type { CredentialPort } from "../../ports/credentials.port.js";
+import type { JiraCreateMetadataPort } from "../../ports/jira-create-metadata.port.js";
+/**
+ * Jira Cloud REST v3 create metadata, per project and per issue type.
+ *
+ * The two-endpoint form, not the aggregate `createmeta?expand=` one: the
+ * aggregate endpoint is deprecated on Jira Cloud and returns every issue type's
+ * every field in one document, which is both larger and less precise than the
+ * question being asked. Planning wants one project's issue types, and then one
+ * issue type's fields.
+ *
+ * `retry: false` throughout. These answers decide whether a create is possible
+ * and what it will contain, so a retried-and-stale answer is worse than a
+ * failure - the same reason `getTransitions` does not retry.
+ *
+ * Both mappers are defensive about shape. Jira omits fields it considers
+ * irrelevant and different deployments populate different ones, so anything
+ * unrecognised is dropped rather than guessed at: an entry JAM cannot read is
+ * an entry JAM must not claim to have understood.
+ */
+export declare class JiraCloudCreateMetadataAdapter implements JiraCreateMetadataPort {
+    private readonly client;
+    constructor(credentials: CredentialPort, fetchImpl?: typeof fetch);
+    getIssueTypes(projectKey: string): Promise<CreateIssueType[]>;
+    getCreateFields(projectKey: string, issueTypeId: string): Promise<CreateFieldMetadata[]>;
+}

package/dist/adapters/jira-cloud/jira-create-metadata.adapter.js

@@ -0,0 +1,81 @@
+import { JiraClient } from "./jira-client.js";
+/**
+ * Jira Cloud REST v3 create metadata, per project and per issue type.
+ *
+ * The two-endpoint form, not the aggregate `createmeta?expand=` one: the
+ * aggregate endpoint is deprecated on Jira Cloud and returns every issue type's
+ * every field in one document, which is both larger and less precise than the
+ * question being asked. Planning wants one project's issue types, and then one
+ * issue type's fields.
+ *
+ * `retry: false` throughout. These answers decide whether a create is possible
+ * and what it will contain, so a retried-and-stale answer is worse than a
+ * failure - the same reason `getTransitions` does not retry.
+ *
+ * Both mappers are defensive about shape. Jira omits fields it considers
+ * irrelevant and different deployments populate different ones, so anything
+ * unrecognised is dropped rather than guessed at: an entry JAM cannot read is
+ * an entry JAM must not claim to have understood.
+ */
+export class JiraCloudCreateMetadataAdapter {
+    client;
+    constructor(credentials, fetchImpl) {
+        this.client = fetchImpl ? new JiraClient(credentials, fetchImpl) : new JiraClient(credentials);
+    }
+    async getIssueTypes(projectKey) {
+        const { data } = await this.client.request({
+            path: `rest/api/3/issue/createmeta/${encodeURIComponent(projectKey)}/issuetypes`,
+            retry: false,
+        });
+        return (data.issueTypes ?? [])
+            .filter((t) => typeof t.id === "string" && typeof t.name === "string")
+            .map((t) => ({ id: t.id, name: t.name, subtask: t.subtask === true }));
+    }
+    async getCreateFields(projectKey, issueTypeId) {
+        const { data } = await this.client.request({
+            path: `rest/api/3/issue/createmeta/${encodeURIComponent(projectKey)}/issuetypes/${encodeURIComponent(issueTypeId)}`,
+            retry: false,
+        });
+        return (data.fields ?? [])
+            .map(toFieldMetadata)
+            .filter((f) => f !== undefined);
+    }
+}
+function toFieldMetadata(raw) {
+    // Jira has called this `fieldId` and `key` in different responses. Without
+    // one of them the entry cannot be matched to anything, so it is dropped -
+    // and if it was required, the required-field gate will refuse the plan
+    // because JAM cannot show it was supplied.
+    const id = typeof raw.fieldId === "string" ? raw.fieldId : typeof raw.key === "string" ? raw.key : undefined;
+    if (!id)
+        return undefined;
+    const allowed = mapAllowedValues(raw.allowedValues);
+    return {
+        id,
+        name: typeof raw.name === "string" ? raw.name : id,
+        required: raw.required === true,
+        hasDefaultValue: raw.hasDefaultValue === true,
+        ...(allowed ? { allowedValues: allowed } : {}),
+    };
+}
+/**
+ * Allowed values, when Jira constrains the field at all.
+ *
+ * Undefined and empty mean different things and are kept apart: undefined is
+ * "Jira did not constrain this", empty is "Jira constrains it and offers
+ * nothing". The first permits a free value, the second permits none.
+ */
+function mapAllowedValues(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    return raw.map((entry) => {
+        const id = typeof entry?.id === "string" ? entry.id : undefined;
+        // Components and priorities use `name`; some option fields use `value`.
+        const name = typeof entry?.name === "string"
+            ? entry.name
+            : typeof entry?.value === "string"
+                ? entry.value
+                : undefined;
+        return { ...(id ? { id } : {}), ...(name ? { name } : {}) };
+    });
+}

package/dist/adapters/jira-cloud/jira-read.adapter.d.ts

@@ -1,11 +1,20 @@
 import type { ProjectConfig } from "../../config/schema.js";
 import type { CredentialPort } from "../../ports/credentials.port.js";
-import type { CurrentUser, GetCommentsRequest, GetCommentsResult, GetIssuesRequest, GetIssuesResult, JiraReadPort, ListProjectsResult, SearchPageRequest, SearchPageResult } from "../../ports/jira-read.port.js";
+import type { CurrentUser, GetCommentsRequest, GetCommentsResult, GetIssueRequest, GetIssueResult, GetIssuesRequest, GetIssuesResult, JiraReadPort, ListProjectsResult, SearchPageRequest, SearchPageResult } from "../../ports/jira-read.port.js";
 export declare class JiraCloudReadAdapter implements JiraReadPort {
     private readonly config;
     private readonly client;
     constructor(credentials: CredentialPort, config: ProjectConfig, fetchImpl?: typeof fetch);
     searchPage(req: SearchPageRequest): Promise<SearchPageResult>;
+    /**
+     * `GET /rest/api/3/issue/{key}` - the single-issue endpoint, not bulkfetch.
+     *
+     * This is what ConsistencyPolicy means by a direct issue read, and the write
+     * plane is the only caller. A 404 is an answer, not a failure: the issue is
+     * not there, or not visible to this account, and the caller decides which of
+     * those matters.
+     */
+    getIssue(req: GetIssueRequest): Promise<GetIssueResult>;
     getIssues(req: GetIssuesRequest): Promise<GetIssuesResult>;
     getComments(req: GetCommentsRequest): Promise<GetCommentsResult>;
     listProjects(): Promise<ListProjectsResult>;

package/dist/adapters/jira-cloud/jira-read.adapter.js

@@ -27,6 +27,32 @@ export class JiraCloudReadAdapter {
             result.nextPageToken = data.nextPageToken;
         return result;
     }
+    /**
+     * `GET /rest/api/3/issue/{key}` - the single-issue endpoint, not bulkfetch.
+     *
+     * This is what ConsistencyPolicy means by a direct issue read, and the write
+     * plane is the only caller. A 404 is an answer, not a failure: the issue is
+     * not there, or not visible to this account, and the caller decides which of
+     * those matters.
+     */
+    async getIssue(req) {
+        const { data, bytes } = await this.client.request({
+            path: `rest/api/3/issue/${encodeURIComponent(req.key)}`,
+            query: { fields: req.fields.join(",") },
+        });
+        if (!data?.key)
+            return { responseBytes: bytes };
+        // Read straight off the raw payload rather than through the mapper: the
+        // mapper's job is the shape the read tools see, and this identity is only
+        // for the write plane. Raw DTOs still stop here.
+        const assignee = data.fields?.assignee;
+        const accountId = typeof assignee?.accountId === "string" ? assignee.accountId : undefined;
+        return {
+            issue: mapIssueWithMeta(data, this.config).issue,
+            ...(accountId ? { assigneeAccountId: accountId } : {}),
+            responseBytes: bytes,
+        };
+    }
     async getIssues(req) {
         const issues = [];
         const commentTotals = {};

package/dist/adapters/jira-cloud/jira-write.adapter.d.ts

@@ -17,6 +17,19 @@ import type { JiraWritePort } from "../../ports/jira-write.port.js";
 export declare class JiraCloudWriteAdapter implements JiraWritePort {
     private readonly client;
     constructor(credentials: CredentialPort, fetchImpl?: typeof fetch);
+    /**
+     * Create one issue, once.
+     *
+     * `retry: false` matters more here than anywhere else behind this port. A
+     * retried update converges; a retried create leaves two issues, and the
+     * second one has a different key nobody is holding. An ambiguous failure is
+     * handed to the application layer as JAM_WRITE_UNCERTAIN and resolved by
+     * looking, never by sending it again.
+     */
+    createIssue(fields: Record<string, unknown>): Promise<{
+        id: string;
+        key: string;
+    }>;
     updateIssue(key: string, fields: Record<string, unknown>): Promise<void>;
     /**
      * Add a comment, converting plain text to ADF here rather than accepting ADF.
@@ -30,12 +43,14 @@ export declare class JiraCloudWriteAdapter implements JiraWritePort {
         id: string;
     }>;
     getTransitions(key: string): Promise<JiraTransition[]>;
+    /**
+     * `PUT /rest/api/3/issue/{key}/assignee` with an accountId.
+     *
+     * The dedicated assignment endpoint rather than a field update: assignment
+     * has its own permission and its own Jira semantics, and routing it through
+     * the generic field PUT would put it behind the field whitelist, where it
+     * does not belong.
+     */
+    assignIssue(key: string, accountId: string): Promise<void>;
     transitionIssue(key: string, transitionId: string): Promise<void>;
 }
-/**
- * Plain text to the narrowest ADF that represents it.
- *
- * Blank lines separate paragraphs; everything else is literal. No markdown is
- * interpreted, so a comment containing `*` or `#` says what it says.
- */
-export declare function textToAdf(text: string): unknown;

package/dist/adapters/jira-cloud/jira-write.adapter.js

@@ -1,3 +1,4 @@
+import { textToAdf } from "../../domain/adf.js";
 import { JamError } from "../../domain/errors.js";
 import { JiraClient } from "./jira-client.js";
 /**
@@ -20,6 +21,30 @@ export class JiraCloudWriteAdapter {
             ? new JiraClient(credentials, fetchImpl)
             : new JiraClient(credentials);
     }
+    /**
+     * Create one issue, once.
+     *
+     * `retry: false` matters more here than anywhere else behind this port. A
+     * retried update converges; a retried create leaves two issues, and the
+     * second one has a different key nobody is holding. An ambiguous failure is
+     * handed to the application layer as JAM_WRITE_UNCERTAIN and resolved by
+     * looking, never by sending it again.
+     */
+    async createIssue(fields) {
+        const { data } = await this.client.request({
+            path: "rest/api/3/issue",
+            method: "POST",
+            body: { fields },
+            retry: false,
+        });
+        if (!data?.key || !data.id) {
+            // Jira took the request and told us nothing identifying, so an issue may
+            // now exist that JAM cannot name. That is exactly the uncertain case:
+            // report it, do not retry, and let a person look.
+            throw new JamError("JAM_WRITE_UNCERTAIN", "Jira accepted a create but returned no issue key, so JAM cannot tell which issue it made - or whether it made one. Look in the project before trying again: retrying could create a second issue.", { project: fields["project"]?.key });
+        }
+        return { id: data.id, key: data.key };
+    }
     async updateIssue(key, fields) {
         await this.client.request({
             path: `rest/api/3/issue/${encodeURIComponent(key)}`,
@@ -66,6 +91,22 @@ export class JiraCloudWriteAdapter {
             to: t.to?.name ?? t.name ?? "",
         }));
     }
+    /**
+     * `PUT /rest/api/3/issue/{key}/assignee` with an accountId.
+     *
+     * The dedicated assignment endpoint rather than a field update: assignment
+     * has its own permission and its own Jira semantics, and routing it through
+     * the generic field PUT would put it behind the field whitelist, where it
+     * does not belong.
+     */
+    async assignIssue(key, accountId) {
+        await this.client.request({
+            path: `rest/api/3/issue/${encodeURIComponent(key)}/assignee`,
+            method: "PUT",
+            body: { accountId },
+            retry: false,
+        });
+    }
     async transitionIssue(key, transitionId) {
         await this.client.request({
             path: `rest/api/3/issue/${encodeURIComponent(key)}/transitions`,
@@ -75,23 +116,3 @@ export class JiraCloudWriteAdapter {
         });
     }
 }
-/**
- * Plain text to the narrowest ADF that represents it.
- *
- * Blank lines separate paragraphs; everything else is literal. No markdown is
- * interpreted, so a comment containing `*` or `#` says what it says.
- */
-export function textToAdf(text) {
-    const paragraphs = text
-        .split(/\n{2,}/)
-        .map((block) => block.trim())
-        .filter(Boolean);
-    return {
-        type: "doc",
-        version: 1,
-        content: (paragraphs.length > 0 ? paragraphs : [text]).map((block) => ({
-            type: "paragraph",
-            content: [{ type: "text", text: block }],
-        })),
-    };
-}

package/dist/application/apply-create-issue.d.ts

@@ -0,0 +1,20 @@
+import type { JamDeps } from "../deps.js";
+import type { CreateIssueWritePlan, WriteApplyReceipt } from "../domain/write.js";
+/**
+ * Create the issue a plan describes, then go and look at what was created.
+ *
+ * The same three-step shape as every other apply, with one substitution.
+ * Updating an existing issue re-reads that issue and compares its revision;
+ * there is no issue to re-read here, so what gets checked instead is the
+ * premise the plan was built on - the project's create schema. That is
+ * creation's concurrency boundary.
+ *
+ *  1. Re-derive the schema and check the plan's premises still hold. If the
+ *     issue type went away, or a required field JAM cannot fill appeared, or a
+ *     resolved value is no longer offered, nothing is sent.
+ *  2. POST the create exactly once. No retry, ever - see below.
+ *  3. Read the new issue by the key Jira returned, and check it says what the
+ *     plan intended. A 201 with a key is Jira accepting a request, not
+ *     evidence that the issue exists as described.
+ */
+export declare function applyCreateIssue(deps: JamDeps, plan: CreateIssueWritePlan): Promise<WriteApplyReceipt>;