@jam-mcp/server 1.1.0 → 1.3.0

package/dist/application/plan-write.js

@@ -1,5 +1,7 @@
 import { JamError } from "../domain/errors.js";
-import { assertFieldsAllowed, assertOperationAllowed, assertWriteScope, PLAN_TTL_MS, resolveTransition, } from "../policy/write-policy.js";
+import { assertExistingIssueOperation, assertFieldsAllowed, assertOperationAllowed, assertWriteScope, PLAN_TTL_MS, resolveTransition, } from "../policy/write-policy.js";
+import { assertAssignable, assertNotAlreadyAssigned, exactMatches, resolveAssignee, } from "../policy/assignee-policy.js";
+import { planCreateIssue } from "./plan-create-issue.js";
 /**
  * Work out whether a requested change is currently possible, and describe it.
  *
@@ -14,18 +16,27 @@ import { assertFieldsAllowed, assertOperationAllowed, assertWriteScope, PLAN_TTL
  * it right now, never from what the caller asserted about it.
  */
 export async function planWrite(deps, request) {
-    const issueKey = request.key.trim().toUpperCase();
+    // Creation branches before anything else touches `key`, because it has none.
+    // Routing on the operation rather than on whether a key happened to be
+    // supplied keeps the two request shapes genuinely separate instead of one
+    // shape with holes in it.
+    if (assertOperationAllowed(request.operation) === "issue.create") {
+        return planCreateIssue(deps, { input: request.input });
+    }
+    const issueKey = requireIssueKey(request);
     const projectKey = assertWriteScope(issueKey, deps.config.project.key);
-    const operation = assertOperationAllowed(request.operation);
+    const operation = assertExistingIssueOperation(request.operation);
     // Everything that can be refused from the request alone is refused here,
     // before a Jira call is spent on it. An agent asking to write a field JAM
     // does not write should get that answer, not a round trip and then that
     // answer.
     const input = validateInput(operation, request.input);
-    const issue = await readIssue(deps, issueKey);
-    const { before, intendedAfter, mutation, transition } = await describe(deps, operation, issueKey, issue, input);
+    const snapshot = await readIssue(deps, issueKey);
+    const issue = snapshot.issue;
+    const { before, intendedAfter, mutation, transition, baseAssigneeAccountId } = await describe(deps, operation, issueKey, snapshot, input);
     const createdAt = new Date();
     const plan = deps.writePlans.create({
+        kind: "existing-issue",
         issueKey,
         projectKey,
         operation,
@@ -35,6 +46,7 @@ export async function planWrite(deps, request) {
         createdAt: createdAt.toISOString(),
         expiresAt: new Date(createdAt.getTime() + PLAN_TTL_MS).toISOString(),
         ...(transition ? { transition } : {}),
+        ...(baseAssigneeAccountId ? { baseAssigneeAccountId } : {}),
         mutation,
     });
     return {
@@ -51,22 +63,45 @@ export async function planWrite(deps, request) {
         },
     };
 }
-/**
- * The issue as Jira has it, read directly by key.
- *
- * A direct read, never a search: ConsistencyPolicy requires it for anything
- * that decides a write, and a JQL result can lag behind the issue it describes.
- */
 export async function readIssue(deps, issueKey) {
-    const { issues } = await deps.jira.getIssues({
-        keys: [issueKey],
-        fields: ["summary", "status", "priority", "labels", "components", "updated"],
+    const { issue: found, assigneeAccountId } = await deps.jira.getIssue({
+        key: issueKey,
+        // `issuetype` and `description` are here for creation's verification step,
+        // which has to confirm the issue Jira made is the one that was asked for.
+        // A field a plan promises to check has to be a field this read returns -
+        // otherwise the check silently passes on `undefined`. They cost nothing on
+        // the other operations, which do not compare them.
+        fields: [
+            "summary",
+            "status",
+            "issuetype",
+            "description",
+            "assignee",
+            "priority",
+            "labels",
+            "components",
+            "updated",
+        ],
     });
-    const issue = issues[0];
-    if (!issue) {
+    if (!found) {
         throw new JamError("ISSUE_NOT_FOUND", `Jira has no issue ${issueKey}, or it is not visible to this account.`, { issueKey });
     }
-    return issue;
+    return { issue: found, ...(assigneeAccountId ? { assigneeAccountId } : {}) };
+}
+/**
+ * The issue an existing-issue operation names, or a refusal that says why.
+ *
+ * `key` is optional on the request only because `issue.create` has no issue.
+ * Reaching here means the operation does have one, so its absence is the
+ * caller using the wrong shape - which is worth saying, rather than reading as
+ * an empty key and failing further in.
+ */
+function requireIssueKey(request) {
+    const key = request.key?.trim();
+    if (!key) {
+        throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", `${request.operation} changes an issue that already exists, so it needs \`key\`.`, { operation: request.operation });
+    }
+    return key.toUpperCase();
 }
 /**
  * Check the request against the contract, and normalize it.
@@ -93,9 +128,17 @@ function validateInput(operation, raw) {
             }
             return { status: status.trim() };
         }
+        case "assignee.update": {
+            const assignee = raw.assignee;
+            if (typeof assignee !== "string" || assignee.trim().length === 0) {
+                throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "assignee.update needs non-empty `input.assignee` - a display name, or an accountId.", { operation });
+            }
+            return { assignee: assignee.trim() };
+        }
     }
 }
-async function describe(deps, operation, issueKey, issue, input) {
+async function describe(deps, operation, issueKey, snapshot, input) {
+    const issue = snapshot.issue;
     switch (operation) {
         case "comment.add": {
             const { text } = input;
@@ -135,8 +178,54 @@ async function describe(deps, operation, issueKey, issue, input) {
                 transition,
             };
         }
+        case "assignee.update": {
+            const { assignee: requested } = input;
+            // Ask Jira who this is, and decide from what it says. The requested
+            // string never reaches a mutation: what gets written is the accountId
+            // that resolution settled on, and resolution refuses rather than picks
+            // when the answer is not one person.
+            const target = resolveAssignee(requested, await findCandidates(deps, requested));
+            // Two independent refusals, in the order that costs least. Already-set
+            // needs no Jira call; assignability does.
+            assertNotAlreadyAssigned(issueKey, snapshot.assigneeAccountId, target);
+            assertAssignable(issueKey, target, await deps.jiraAssignees.isAssignable(issueKey, target.accountId));
+            return {
+                before: {
+                    assignee: snapshot.assigneeAccountId
+                        ? { accountId: snapshot.assigneeAccountId, displayName: issue.assignee ?? "" }
+                        : null,
+                },
+                intendedAfter: { assignee: target },
+                mutation: { kind: "assignee", accountId: target.accountId },
+                ...(snapshot.assigneeAccountId
+                    ? { baseAssigneeAccountId: snapshot.assigneeAccountId }
+                    : {}),
+            };
+        }
     }
 }
+/**
+ * Who Jira thinks this string could be.
+ *
+ * The search first, because it answers both halves of the contract most of the
+ * time - Jira's user search currently matches an accountId as readily as a
+ * name. "Currently" is the problem: that is a property of a substring search
+ * rather than a promise, and the contract says an accountId identifies a
+ * person. So when the search settles nothing, the exact lookup is asked before
+ * giving up.
+ *
+ * Ordered this way because it costs nothing on the paths that work. The extra
+ * request happens only where resolution was about to fail anyway, and the
+ * string is never inspected to guess whether it looks like an accountId - Jira
+ * is asked, and Jira answers.
+ */
+async function findCandidates(deps, requested) {
+    const candidates = await deps.jiraAssignees.searchUsers(requested);
+    if (exactMatches(requested, candidates).length > 0)
+        return candidates;
+    const byId = await deps.jiraAssignees.getUserByAccountId(requested);
+    return byId ? [byId] : candidates;
+}
 function currentValue(issue, field) {
     switch (field) {
         case "summary":

package/dist/application/write-plan-store.d.ts

@@ -1,4 +1,4 @@
-import type { WritePlan } from "../domain/write.js";
+import type { NewWritePlan, WritePlan } from "../domain/write.js";
 /**
  * Where a plan lives between `jira_write_plan` and `jira_write_apply`.
  *
@@ -21,7 +21,7 @@ export declare class WritePlanStore {
     private readonly plans;
     /** Injected by tests so expiry does not depend on wall-clock timing. */
     constructor(now?: () => Date);
-    create(plan: Omit<WritePlan, "planId">): WritePlan;
+    create(plan: NewWritePlan): WritePlan;
     /**
      * Resolve a plan for applying.
      *

package/dist/application/write-plan-store.js

@@ -45,7 +45,19 @@ export class WritePlanStore {
         }
         if (planExpired(plan.expiresAt, this.now())) {
             this.plans.delete(planId);
-            throw new JamError("JAM_WRITE_PLAN_EXPIRED", `This write plan expired at ${plan.expiresAt}. Re-plan against the current state of ${plan.issueKey}.`, { planId, issueKey: plan.issueKey, expiresAt: plan.expiresAt });
+            // What to re-plan against differs by plan: an existing issue has a
+            // current state, a create has only the project's current create schema.
+            // Naming an issue key here for a create would name an issue that has
+            // never existed.
+            throw new JamError("JAM_WRITE_PLAN_EXPIRED", plan.kind === "create-issue"
+                ? `This write plan expired at ${plan.expiresAt}. Nothing was created - re-plan against the current create schema for project ${plan.projectKey}.`
+                : `This write plan expired at ${plan.expiresAt}. Re-plan against the current state of ${plan.issueKey}.`, {
+                planId,
+                expiresAt: plan.expiresAt,
+                ...(plan.kind === "create-issue"
+                    ? { project: plan.projectKey }
+                    : { issueKey: plan.issueKey }),
+            });
         }
         return plan;
     }

package/dist/bootstrap/mcp-config-merger.d.ts

@@ -13,7 +13,7 @@ import { LAUNCHER_PACKAGE_SPEC } from "@jam-mcp/launcher";
 export { LAUNCHER_PACKAGE_SPEC };
 export declare const JAM_MCP_ENTRY: {
     readonly command: "npx";
-    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.1.0", "serve"];
+    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.3.0", "serve"];
 };
 /**
  * Recognise wiring from before the launcher existed: a hard-coded path to one

package/dist/cli/auth.d.ts

@@ -24,6 +24,12 @@ export type AuthOptions = {
      * it) is about the ordering, not about the network.
      */
     verify?: (values: StoredCredentials) => Promise<string | undefined>;
+    /**
+     * Injected by tests. The suite runs with JAM_DISABLE_SECRET_STORE set so it
+     * cannot reach a real keychain, which would otherwise make every "no store
+     * on this system" case report the disabled one instead.
+     */
+    env?: NodeJS.ProcessEnv;
 };
 export declare function authLoginCommand(options?: AuthOptions): Promise<number>;
 export declare function authLogoutCommand(options?: AuthOptions): number;

package/dist/cli/auth.js

@@ -48,11 +48,12 @@ export async function authLoginCommand(options = {}) {
     const ui = options.ui ?? new Ui();
     const store = "store" in options ? options.store : resolveSecretStore();
     const readBack = options.readBack ?? freshPort;
+    const env = options.env ?? process.env;
     ui.section("Authentication");
     if (!store) {
         // Disabled and absent are different problems with different fixes, and
         // saying "no store" when one was switched off sends the user hunting.
-        if (secretStoreDisabled()) {
+        if (secretStoreDisabled(env)) {
             ui.failure("Secret store disabled by JAM_DISABLE_SECRET_STORE");
             ui.line("  That variable is for isolated test sandboxes. Unset it and run this again.");
             ui.next(ENV_HINT);

package/dist/deps.d.ts

@@ -4,6 +4,8 @@ import type { ProjectConfig } from "./config/schema.js";
 import type { CachePort } from "./ports/cache.port.js";
 import type { CredentialPort } from "./ports/credentials.port.js";
 import type { JiraReadPort } from "./ports/jira-read.port.js";
+import type { JiraAssigneeResolutionPort } from "./ports/jira-assignee-resolution.port.js";
+import type { JiraCreateMetadataPort } from "./ports/jira-create-metadata.port.js";
 import type { JiraWritePort } from "./ports/jira-write.port.js";
 import { WritePlanStore } from "./application/write-plan-store.js";
 import type { TelemetryPort } from "./ports/telemetry.port.js";
@@ -20,6 +22,20 @@ export type JamDeps = {
      * that did both would blur them.
      */
     jiraWrite: JiraWritePort;
+    /**
+     * What Jira will accept when creating an issue here. A third port rather
+     * than a method on either of the others: it mutates nothing, so it does not
+     * belong behind the write port's no-retry contract, and it answers a
+     * question about a project rather than about an issue, so the read port's
+     * completeness semantics would mean nothing for it.
+     */
+    jiraCreateMetadata: JiraCreateMetadataPort;
+    /**
+     * Who a name refers to, and who may hold an issue. A fourth port for the
+     * same reason as the third: it reads a directory rather than an issue, and
+     * it mutates nothing.
+     */
+    jiraAssignees: JiraAssigneeResolutionPort;
     /**
      * Plans awaiting apply. Lives for the life of this server process - see
      * WritePlanStore for why it is not persisted.
@@ -35,6 +51,10 @@ export type BuildDepsOptions = {
     jira?: JiraReadPort;
     /** Injected by tests so no test can reach a real Jira write endpoint. */
     jiraWrite?: JiraWritePort;
+    /** Injected by tests so create metadata comes from a fixture, not a site. */
+    jiraCreateMetadata?: JiraCreateMetadataPort;
+    /** Injected by tests so user resolution never reaches a real directory. */
+    jiraAssignees?: JiraAssigneeResolutionPort;
     /** Injected by tests to bypass the real process/registry credential lookup. */
     credentials?: CredentialPort;
     /**

package/dist/deps.js

@@ -33,12 +33,24 @@ export async function buildDeps(options = {}) {
         const { JiraCloudWriteAdapter } = await import("./adapters/jira-cloud/jira-write.adapter.js");
         jiraWrite = new JiraCloudWriteAdapter(credentials);
     }
+    let jiraCreateMetadata = options.jiraCreateMetadata;
+    if (!jiraCreateMetadata) {
+        const { JiraCloudCreateMetadataAdapter } = await import("./adapters/jira-cloud/jira-create-metadata.adapter.js");
+        jiraCreateMetadata = new JiraCloudCreateMetadataAdapter(credentials);
+    }
+    let jiraAssignees = options.jiraAssignees;
+    if (!jiraAssignees) {
+        const { JiraCloudAssigneeResolutionAdapter } = await import("./adapters/jira-cloud/jira-assignee-resolution.adapter.js");
+        jiraAssignees = new JiraCloudAssigneeResolutionAdapter(credentials);
+    }
     return {
         config: resolved.config,
         configPath: resolved.configPath,
         keySource: resolved.keySource,
         jira,
         jiraWrite,
+        jiraCreateMetadata,
+        jiraAssignees,
         writePlans: new WritePlanStore(),
         cache: new NoopCache(),
         telemetry,

package/dist/domain/adf.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Plain text to the narrowest Atlassian Document Format that represents it.
+ *
+ * Jira's rich-text fields - a comment body, an issue description - are document
+ * trees. Accepting one from a caller would mean accepting arbitrary structure
+ * through a field that reads like "text": panels, mentions, embedded content,
+ * links to anywhere. So JAM's contract is plain text in both places, and this
+ * is the single conversion that produces the document.
+ *
+ * Shared rather than duplicated per field on purpose. Two copies of this would
+ * be two answers to "what can an agent put in a Jira document", and the second
+ * one would drift.
+ *
+ * Blank lines separate paragraphs; everything else is literal. No markdown is
+ * interpreted, so text containing `*` or `#` says what it says.
+ */
+export declare function textToAdf(text: string): unknown;
+/**
+ * The text as it will exist once Jira has it.
+ *
+ * A write is only verified if what a direct read shows can be compared to what
+ * was asked for - and for a rich-text field those two are never byte-identical.
+ * The caller's string becomes a document, Jira stores the document, and reading
+ * it back renders a document into text again. Blank-line runs collapse, block
+ * edges lose their whitespace, a trailing newline disappears.
+ *
+ * None of that changes what the description says, so comparing raw strings
+ * would fail every time. Comparing canonical forms fails only when the text
+ * actually differs.
+ *
+ * Deliberately the same normalization `textToAdf` performs, from the same
+ * place: "what JAM sends" and "what JAM will accept as proof it arrived" must
+ * not be able to drift into two answers.
+ */
+export declare function canonicalizePlainText(text: string): string;

package/dist/domain/adf.js

@@ -0,0 +1,65 @@
+/**
+ * Plain text to the narrowest Atlassian Document Format that represents it.
+ *
+ * Jira's rich-text fields - a comment body, an issue description - are document
+ * trees. Accepting one from a caller would mean accepting arbitrary structure
+ * through a field that reads like "text": panels, mentions, embedded content,
+ * links to anywhere. So JAM's contract is plain text in both places, and this
+ * is the single conversion that produces the document.
+ *
+ * Shared rather than duplicated per field on purpose. Two copies of this would
+ * be two answers to "what can an agent put in a Jira document", and the second
+ * one would drift.
+ *
+ * Blank lines separate paragraphs; everything else is literal. No markdown is
+ * interpreted, so text containing `*` or `#` says what it says.
+ */
+export function textToAdf(text) {
+    const paragraphs = toParagraphs(text);
+    return {
+        type: "doc",
+        version: 1,
+        content: (paragraphs.length > 0 ? paragraphs : [text]).map((block) => ({
+            type: "paragraph",
+            content: [{ type: "text", text: block }],
+        })),
+    };
+}
+/**
+ * The text as it will exist once Jira has it.
+ *
+ * A write is only verified if what a direct read shows can be compared to what
+ * was asked for - and for a rich-text field those two are never byte-identical.
+ * The caller's string becomes a document, Jira stores the document, and reading
+ * it back renders a document into text again. Blank-line runs collapse, block
+ * edges lose their whitespace, a trailing newline disappears.
+ *
+ * None of that changes what the description says, so comparing raw strings
+ * would fail every time. Comparing canonical forms fails only when the text
+ * actually differs.
+ *
+ * Deliberately the same normalization `textToAdf` performs, from the same
+ * place: "what JAM sends" and "what JAM will accept as proof it arrived" must
+ * not be able to drift into two answers.
+ */
+export function canonicalizePlainText(text) {
+    return toParagraphs(text).join("\n\n");
+}
+/**
+ * Blank lines separate paragraphs; everything else is literal.
+ *
+ * A single newline inside a block survives - it is a line break the author
+ * wrote, and ADF round-trips it - so only the edges of each block are trimmed.
+ */
+function toParagraphs(text) {
+    return (text
+        // Line endings first. A CRLF document would otherwise carry a stray \r
+        // at the end of every block into ADF, and Jira renders it back as LF -
+        // so a create that was correct would fail verification, on nothing more
+        // than which editor the caller used. Worse, `\r\n\r\n` and `\n\n` would
+        // split into paragraphs differently.
+        .replace(/\r\n?/g, "\n")
+        .split(/\n{2,}/)
+        .map((block) => block.trim())
+        .filter(Boolean));
+}

package/dist/domain/errors.d.ts

@@ -5,7 +5,7 @@
  * is mapped onto one of these codes so the agent (and `jam doctor`) can reason
  * about failures without parsing vendor-specific payloads.
  */
-export declare const JAM_ERROR_CODES: readonly ["JIRA_AUTH_FAILED", "JIRA_PERMISSION_DENIED", "JQL_INVALID", "ISSUE_NOT_FOUND", "RATE_LIMITED", "CONTEXT_TOO_LARGE", "PARTIAL_RESULT", "CONFIG_INVALID", "JIRA_UNAVAILABLE", "JAM_SETUP_REQUIRED", "JAM_BINDINGS_UNREADABLE", "JAM_WRITE_SCOPE_VIOLATION", "JAM_WRITE_OPERATION_NOT_ALLOWED", "JAM_WRITE_FIELD_NOT_ALLOWED", "JAM_WRITE_TRANSITION_NOT_AVAILABLE", "JAM_WRITE_PLAN_NOT_FOUND", "JAM_WRITE_PLAN_EXPIRED", "JAM_WRITE_CONFLICT", "JAM_WRITE_VERIFICATION_FAILED", "JAM_WRITE_UNCERTAIN"];
+export declare const JAM_ERROR_CODES: readonly ["JIRA_AUTH_FAILED", "JIRA_PERMISSION_DENIED", "JQL_INVALID", "ISSUE_NOT_FOUND", "RATE_LIMITED", "CONTEXT_TOO_LARGE", "PARTIAL_RESULT", "CONFIG_INVALID", "JIRA_UNAVAILABLE", "JAM_SETUP_REQUIRED", "JAM_BINDINGS_UNREADABLE", "JAM_WRITE_SCOPE_VIOLATION", "JAM_WRITE_OPERATION_NOT_ALLOWED", "JAM_WRITE_FIELD_NOT_ALLOWED", "JAM_WRITE_TRANSITION_NOT_AVAILABLE", "JAM_WRITE_ISSUE_TYPE_NOT_AVAILABLE", "JAM_WRITE_REQUIRED_FIELD_UNSUPPORTED", "JAM_WRITE_VALUE_NOT_ALLOWED", "JAM_WRITE_SCHEMA_CHANGED", "JAM_WRITE_ASSIGNEE_NOT_FOUND", "JAM_WRITE_ASSIGNEE_AMBIGUOUS", "JAM_WRITE_ASSIGNEE_NOT_ASSIGNABLE", "JAM_WRITE_ASSIGNEE_ALREADY_SET", "JAM_WRITE_PLAN_NOT_FOUND", "JAM_WRITE_PLAN_EXPIRED", "JAM_WRITE_CONFLICT", "JAM_WRITE_VERIFICATION_FAILED", "JAM_WRITE_UNCERTAIN"];
 export type JamErrorCode = (typeof JAM_ERROR_CODES)[number];
 export type JamErrorPayload = {
     error: {

package/dist/domain/errors.js

@@ -25,6 +25,23 @@ export const JAM_ERROR_CODES = [
     "JAM_WRITE_OPERATION_NOT_ALLOWED",
     "JAM_WRITE_FIELD_NOT_ALLOWED",
     "JAM_WRITE_TRANSITION_NOT_AVAILABLE",
+    // Creation. Each is a refusal JAM makes before Jira is asked to act, or a
+    // premise that stopped holding between planning and applying - never a raw
+    // Jira 400 passed along. "That type is not on offer", "this project needs a
+    // field JAM cannot fill" and "the schema moved under the plan" are three
+    // different next steps for whoever is holding the agent.
+    "JAM_WRITE_ISSUE_TYPE_NOT_AVAILABLE",
+    "JAM_WRITE_REQUIRED_FIELD_UNSUPPORTED",
+    "JAM_WRITE_VALUE_NOT_ALLOWED",
+    "JAM_WRITE_SCHEMA_CHANGED",
+    // Assignment. A name is not an identity, and Jira decides who may hold an
+    // issue - so "nobody by that name", "several people by that name", "that
+    // person may not hold this issue" and "they already do" are four different
+    // things for a caller to do next, and none of them is "try again".
+    "JAM_WRITE_ASSIGNEE_NOT_FOUND",
+    "JAM_WRITE_ASSIGNEE_AMBIGUOUS",
+    "JAM_WRITE_ASSIGNEE_NOT_ASSIGNABLE",
+    "JAM_WRITE_ASSIGNEE_ALREADY_SET",
     "JAM_WRITE_PLAN_NOT_FOUND",
     "JAM_WRITE_PLAN_EXPIRED",
     "JAM_WRITE_CONFLICT",