@jam-mcp/server 1.2.0 → 1.3.1

package/dist/policy/custom-field-policy.js

@@ -0,0 +1,230 @@
+import { JamError } from "../domain/errors.js";
+/**
+ * Which configured field this selector names.
+ *
+ * The id is the identity; the name is an alias for people. Resolution is exact
+ * on either - no substring, no fuzz - because the alternative is an agent's
+ * approximate word choosing which field on somebody's board gets rewritten.
+ *
+ * Only `writable: true` entries are candidates, including for the refusal
+ * message: naming a read-only field as an alternative would suggest it is one
+ * selector away from being written.
+ */
+export function resolveWritableField(config, requested) {
+    const wanted = requested.trim();
+    if (wanted.length === 0) {
+        throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "custom-field.update needs a non-empty `input.field`.", { operation: "custom-field.update" });
+    }
+    const writable = config.customFields.filter((f) => f.writable);
+    const match = writable.find((f) => f.id.toLowerCase() === wanted.toLowerCase()) ??
+        writable.find((f) => f.name.trim().toLowerCase() === wanted.toLowerCase());
+    if (!match) {
+        throw new JamError("JAM_WRITE_FIELD_NOT_ALLOWED", writable.length === 0
+            ? `No custom field in this project is writable. A team opts one in by adding \`writable: true\` to its entry in .jira-agent/project.yaml; being readable does not make a field writable.`
+            : `"${requested}" is not a writable custom field in this project. JAM writes only the exact ids a team has opted in.`, {
+            requested,
+            writableCustomFields: writable.map((f) => ({ id: f.id, name: f.name })),
+        });
+    }
+    return { id: match.id, name: match.name };
+}
+/**
+ * The field as Jira currently offers it on this issue, or a refusal.
+ *
+ * Absent from the edit metadata and present-but-not-settable are different
+ * situations with the same answer for the caller, so they share a code and
+ * differ in the detail: one means the field is not on this screen, the other
+ * that Jira will not let this account set it.
+ */
+export function assertEditable(issueKey, field, metadata) {
+    const found = metadata.find((f) => f.id === field.id);
+    if (!found) {
+        throw new JamError("JAM_WRITE_CUSTOM_FIELD_NOT_EDITABLE", `Jira does not offer ${field.name} (${field.id}) on ${issueKey}'s edit screen for this account. The field may not apply to this project or issue type, or this account may not be able to edit it.`, { issueKey, fieldId: field.id, fieldName: field.name, reason: "NOT_ON_EDIT_SCREEN" });
+    }
+    if (!found.operations.includes("set")) {
+        throw new JamError("JAM_WRITE_CUSTOM_FIELD_NOT_EDITABLE", `Jira lists ${field.name} (${field.id}) on ${issueKey} but does not offer "set" for it${found.operations.length > 0 ? ` - only ${found.operations.join(", ")}` : ""}. JAM only sets a value; it does not add to or remove from one.`, {
+            issueKey,
+            fieldId: field.id,
+            fieldName: field.name,
+            operations: found.operations,
+            reason: "SET_NOT_OFFERED",
+        });
+    }
+    return found;
+}
+/**
+ * Which of the four families this field belongs to, if any.
+ *
+ * Classified from Jira's own `schema`, which is the vocabulary Jira answers
+ * in. The implementation key (`schema.custom`) deliberately does not decide
+ * it: there are hundreds of them, they are app-specific, and a field's wire
+ * shape follows its type rather than its plugin.
+ *
+ * Anything unclassified is refused. Posting an unknown type to see what
+ * happens would use a Jira 400 as schema discovery, and on the occasions it
+ * did not 400 it would write something nobody described.
+ */
+export function classifyKind(field) {
+    const { type, items } = field.schema;
+    if (type === "string" && !items)
+        return "text";
+    if (type === "number" && !items)
+        return "number";
+    if (type === "option" && !items)
+        return "single-option";
+    if (type === "array" && items === "option")
+        return "multi-option";
+    throw new JamError("JAM_WRITE_CUSTOM_FIELD_TYPE_UNSUPPORTED", `${field.name} (${field.id}) is a ${describeType(field)} field, and JAM does not know how to write one safely yet. Supported: single-line text, number, single-select and multi-select.`, {
+        fieldId: field.id,
+        fieldName: field.name,
+        schema: field.schema,
+        supported: ["text", "number", "single-option", "multi-option"],
+    });
+}
+function describeType(field) {
+    const { type, items } = field.schema;
+    return items ? `${type} of ${items}` : type;
+}
+/**
+ * The value, checked against the family and turned into what Jira expects.
+ *
+ * Types are never coerced. `"5"` is not `5`: a caller that meant a number can
+ * say so, and silently converting would make JAM's idea of the value differ
+ * from the caller's in exactly the cases where it matters.
+ *
+ * Nothing here clears a field. Empty strings, empty arrays and null are
+ * refused rather than treated as "unset" - removing a value is a different
+ * intent from setting one, and it is not in this version.
+ */
+export function resolveCustomFieldValue(field, kind, input) {
+    const { value } = input;
+    const named = { id: field.id, name: field.name };
+    switch (kind) {
+        case "text": {
+            if (typeof value !== "string")
+                throw wrongType(field, kind, value);
+            const text = value.trim();
+            if (text.length === 0)
+                throw refuseClear(field);
+            return { jiraValue: text, view: { ...named, value: text } };
+        }
+        case "number": {
+            if (typeof value !== "number" || !Number.isFinite(value))
+                throw wrongType(field, kind, value);
+            return { jiraValue: value, view: { ...named, value } };
+        }
+        case "single-option": {
+            if (typeof value !== "string")
+                throw wrongType(field, kind, value);
+            const option = resolveOption(field, value);
+            // Jira takes the option by id. The label is what a person reads, and two
+            // options could carry the same one.
+            return {
+                jiraValue: { id: option.id },
+                view: { ...named, value: option },
+                resolvedOptions: [option],
+            };
+        }
+        case "multi-option": {
+            if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+                throw wrongType(field, kind, value);
+            }
+            if (value.length === 0)
+                throw refuseClear(field);
+            const seen = new Set();
+            for (const raw of value) {
+                const key = raw.trim().toLowerCase();
+                if (seen.has(key)) {
+                    throw new JamError("JAM_WRITE_VALUE_NOT_ALLOWED", `"${raw}" appears more than once in the value for ${field.name}. JAM does not quietly drop the repeat - say each option once.`, { fieldId: field.id, repeated: raw });
+                }
+                seen.add(key);
+            }
+            // Every option resolves, or none is written. A partly-applied selection
+            // is a selection nobody asked for.
+            const options = value.map((raw) => resolveOption(field, raw));
+            return {
+                jiraValue: options.map((o) => ({ id: o.id })),
+                view: { ...named, value: options },
+                resolvedOptions: options,
+            };
+        }
+    }
+}
+/**
+ * Which option Jira offers under this name, if exactly one does.
+ *
+ * An option id wins outright, then an exact label ignoring case and space.
+ * Nothing partial: Jira's option lists are short and a caller can name one
+ * exactly, so a near miss is a question rather than a guess.
+ */
+function resolveOption(field, requested) {
+    const allowed = field.allowedValues;
+    if (!allowed) {
+        throw new JamError("JAM_WRITE_CUSTOM_FIELD_TYPE_UNSUPPORTED", `${field.name} (${field.id}) is a select field, but Jira did not say which options it offers, so JAM cannot resolve "${requested}" to one.`, { fieldId: field.id, fieldName: field.name, schema: field.schema });
+    }
+    const wanted = requested.trim();
+    const byId = allowed.filter((o) => o.id === wanted);
+    const matches = byId.length > 0
+        ? byId
+        : allowed.filter((o) => o.label.trim().toLowerCase() === wanted.toLowerCase());
+    if (matches.length === 0) {
+        throw new JamError("JAM_WRITE_VALUE_NOT_ALLOWED", allowed.length === 0
+            ? `Jira offers no options for ${field.name} on this issue, so "${requested}" cannot be set.`
+            : `"${requested}" is not an option Jira offers for ${field.name}. Allowed: ${allowed.map((o) => o.label).join(", ")}.`, { fieldId: field.id, requested, allowed });
+    }
+    if (matches.length > 1) {
+        throw new JamError("JAM_WRITE_VALUE_NOT_ALLOWED", `"${requested}" matches ${matches.length} options for ${field.name}. Pass the option id of the one you mean.`, { fieldId: field.id, requested, candidates: matches });
+    }
+    return matches[0];
+}
+/**
+ * Do this plan's premises still hold?
+ *
+ * Semantic, like the create schema check and for the same reason: comparing
+ * whole metadata documents would invalidate every outstanding plan whenever an
+ * unrelated field appeared on the screen. What is compared is what the plan
+ * actually rested on - the field is still settable, still the same family,
+ * still the same schema, and every option it chose is still offered under the
+ * same label.
+ *
+ * A renamed option is treated as a changed one. The id is the identity, but a
+ * label is what the plan showed a human before they agreed to it, and "Backend"
+ * becoming "Platform" is a different statement about the issue.
+ */
+export function assertCustomFieldUnchanged(issueKey, requirements, metadata) {
+    const field = metadata.find((f) => f.id === requirements.fieldId);
+    if (!field) {
+        throw schemaChanged(`${requirements.fieldName} (${requirements.fieldId}) is no longer on ${issueKey}'s edit screen for this account.`, { issueKey, fieldId: requirements.fieldId });
+    }
+    if (!field.operations.includes("set")) {
+        throw schemaChanged(`Jira no longer offers "set" for ${requirements.fieldName} on ${issueKey}.`, { issueKey, fieldId: field.id, operations: field.operations });
+    }
+    if (field.schema.type !== requirements.schema.type ||
+        field.schema.items !== requirements.schema.items) {
+        throw schemaChanged(`${requirements.fieldName} is no longer a ${requirements.kind} field.`, { issueKey, fieldId: field.id, planned: requirements.schema, current: field.schema });
+    }
+    for (const planned of requirements.resolvedOptions ?? []) {
+        const current = field.allowedValues?.find((o) => o.id === planned.id);
+        if (!current) {
+            throw schemaChanged(`Option "${planned.label}" is no longer offered for ${requirements.fieldName}.`, { issueKey, fieldId: field.id, option: planned });
+        }
+        if (current.label !== planned.label) {
+            throw schemaChanged(`Option "${planned.label}" has been renamed to "${current.label}", so this plan no longer describes the change it showed.`, { issueKey, fieldId: field.id, planned, current });
+        }
+    }
+}
+function schemaChanged(what, details) {
+    return new JamError("JAM_WRITE_SCHEMA_CHANGED", `${what} This plan was built on the field's configuration as it was, so it no longer describes a change JAM can make. Nothing was written - plan again.`, details);
+}
+function wrongType(field, kind, value) {
+    const wanted = {
+        text: "a string",
+        number: "a number",
+        "single-option": "a string naming one option",
+        "multi-option": "an array of strings naming options",
+    }[kind];
+    return new JamError("JAM_WRITE_VALUE_NOT_ALLOWED", `${field.name} (${field.id}) is a ${kind} field and needs ${wanted}. JAM does not convert between types - "5" and 5 are different values, and guessing which was meant is not JAM's to do.`, { fieldId: field.id, kind, received: typeof value });
+}
+function refuseClear(field) {
+    return new JamError("JAM_WRITE_VALUE_NOT_ALLOWED", `custom-field.update sets a value; it does not clear one. ${field.name} cannot be set to an empty value in this version.`, { fieldId: field.id, reason: "CLEAR_NOT_SUPPORTED" });
+}

package/dist/ports/jira-assignee-resolution.port.d.ts

@@ -0,0 +1,51 @@
+import type { AssigneeCandidate } from "../domain/write.js";
+/**
+ * Who Jira thinks a name refers to, and whether they can hold this issue.
+ *
+ * A third read-shaped port, for the same reason `JiraCreateMetadataPort` is
+ * one: nothing here mutates, so it does not belong behind the write port's
+ * no-retry contract, and it answers a question about a directory rather than
+ * about an issue, so the read port's completeness semantics would mean nothing
+ * for it.
+ *
+ * The two calls are deliberately separate questions. Searching answers "who
+ * did the caller mean", and it is allowed to be fuzzy - Jira matches on
+ * substrings, and a partial match is a suggestion to show a human. Checking
+ * assignability answers "may this exact person hold this exact issue", and it
+ * is not fuzzy at all: it takes an accountId that resolution has already
+ * settled on. Collapsing them would let a substring match decide a mutation.
+ *
+ * Neither call retries. Their answers decide a mutation, and a retried answer
+ * is a possibly-stale one - the same argument that keeps `getTransitions` and
+ * the create metadata calls on the non-retrying side.
+ */
+export interface JiraAssigneeResolutionPort {
+    /**
+     * Users matching a query, as Jira's own directory reports them.
+     *
+     * Fuzzy by nature. What comes back is candidates, never a decision - see
+     * `resolveAssignee` for what JAM will and will not do with them.
+     */
+    searchUsers(query: string): Promise<AssigneeCandidate[]>;
+    /**
+     * One user, looked up by identity rather than found by searching.
+     *
+     * JAM's contract says `assignee` may be an accountId, and a contract about
+     * identity has to be met by an identity lookup. Jira's user search does
+     * currently return a user when the query happens to be their accountId, but
+     * that is a property of a substring search, not a promise - relying on it
+     * means the accountId half of the contract holds by coincidence.
+     *
+     * Absent means Jira has no such account, or this token cannot see it. Both
+     * are "you cannot assign this", which is the caller's answer either way.
+     */
+    getUserByAccountId(accountId: string): Promise<AssigneeCandidate | undefined>;
+    /**
+     * Whether this exact account may be assigned this exact issue, right now.
+     *
+     * Asked by accountId, so it is an identity question rather than a name one.
+     * Asked again immediately before the write, because a permission that held
+     * when the plan was made is not the same as one that still holds.
+     */
+    isAssignable(issueKey: string, accountId: string): Promise<boolean>;
+}

package/dist/ports/jira-assignee-resolution.port.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/jira-edit-metadata.port.d.ts

@@ -0,0 +1,22 @@
+import type { EditFieldMetadata } from "../domain/write.js";
+/**
+ * What Jira will let this account change on one issue, right now.
+ *
+ * `GET /rest/api/3/issue/{key}/editmeta` is the authority, and it is asked
+ * rather than reconstructed. A custom field's applicability depends on the
+ * project, the issue type, the field's contexts, the screen it is on and the
+ * permissions of whoever is asking - JAM does not carry a copy of that model,
+ * and the field-context APIs that would let it try need administrator rights
+ * most tokens do not have. So the question is put to Jira in the form it can
+ * answer exactly: on this issue, for this account, what is editable and how.
+ *
+ * The same shape as the other read-shaped ports, for the same reasons: it
+ * mutates nothing, so it does not belong behind the write port's no-retry
+ * contract, and it answers a question about a configuration rather than about
+ * an issue, so the read port's completeness semantics would mean nothing here.
+ *
+ * It does not retry. Its answer decides a mutation.
+ */
+export interface JiraEditMetadataPort {
+    getEditableFields(issueKey: string): Promise<EditFieldMetadata[]>;
+}

package/dist/ports/jira-edit-metadata.port.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/jira-read.port.d.ts

@@ -27,6 +27,27 @@ export type GetIssueRequest = {
 export type GetIssueResult = {
     /** Absent when Jira has no such issue, or this account cannot see it. */
     issue?: FullIssueContext;
+    /**
+     * Who the issue is assigned to, by identity rather than by name.
+     *
+     * Here rather than on the issue because only the write plane needs it. Two
+     * people can share a display name, so `assignee` cannot settle whether an
+     * assignment landed on the right person - and the read tools have no use for
+     * an accountId, so their payload does not grow one.
+     *
+     * Absent when the issue is unassigned, or when the field was not requested.
+     */
+    assigneeAccountId?: string;
+    /**
+     * Raw custom field values, keyed by field id, exactly as Jira returned them.
+     *
+     * Here rather than on the issue for the same reason as the accountId: only
+     * the write plane needs it. `FullIssueContext.customFields` is the mapped,
+     * whitelisted view the read tools show; verifying a write needs the value in
+     * the form Jira stores it, option ids included, before anything shortens it
+     * to something a person reads.
+     */
+    customFieldValues?: Record<string, unknown>;
     responseBytes: number;
 };
 export type GetIssuesResult = {

package/dist/ports/jira-write.port.d.ts

@@ -32,4 +32,12 @@ export interface JiraWritePort {
     /** Transitions Jira offers for this issue right now, for this account. */
     getTransitions(key: string): Promise<JiraTransition[]>;
     transitionIssue(key: string, transitionId: string): Promise<void>;
+    /**
+     * Assign an issue to one account.
+     *
+     * By accountId, never by name: Jira Cloud identifies users by account, and a
+     * display name is a label two people can share. Which account it is was
+     * settled during planning.
+     */
+    assignIssue(key: string, accountId: string): Promise<void>;
 }

package/package.json

@@ -1,69 +1,69 @@
-{
-  "name": "@jam-mcp/server",
-  "version": "1.2.0",
-  "description": "JAM (Jira Agent MCP) - agent-facing Jira access layer: MCP server, setup core, and CLI",
-  "keywords": [
-    "jira",
-    "mcp",
-    "model-context-protocol",
-    "claude-code",
-    "codex",
-    "jira-api"
-  ],
-  "homepage": "https://github.com/colosair/jam#readme",
-  "bugs": {
-    "url": "https://github.com/colosair/jam/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/colosair/jam.git",
-    "directory": "packages/server"
-  },
-  "author": "colosair (https://github.com/colosair)",
-  "type": "module",
-  "bin": {
-    "jam-server": "dist/index.js"
-  },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "engines": {
-    "node": ">=20"
-  },
-  "files": [
-    "dist",
-    "!dist/**/*.js.map",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
-  "dependencies": {
-    "@jam-mcp/launcher": "1.2.0",
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "yaml": "^2.9.0",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.0",
-    "typescript": "^5.9.0",
-    "vitest": "^4.1.11"
-  },
-  "license": "MIT",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./cli-entry": {
-      "types": "./dist/cli-entry.d.ts",
-      "default": "./dist/cli-entry.js"
-    }
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  }
-}
+{
+  "name": "@jam-mcp/server",
+  "version": "1.3.1",
+  "description": "JAM (Jira Agent MCP) - agent-facing Jira access layer: MCP server, setup core, and CLI",
+  "keywords": [
+    "jira",
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "codex",
+    "jira-api"
+  ],
+  "homepage": "https://github.com/colosair/jam#readme",
+  "bugs": {
+    "url": "https://github.com/colosair/jam/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/colosair/jam.git",
+    "directory": "packages/server"
+  },
+  "author": "colosair (https://github.com/colosair)",
+  "type": "module",
+  "bin": {
+    "jam-server": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.js.map",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@jam-mcp/launcher": "1.3.1",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.11"
+  },
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cli-entry": {
+      "types": "./dist/cli-entry.d.ts",
+      "default": "./dist/cli-entry.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}