@jam-mcp/server 1.0.1 → 1.2.0

package/dist/application/plan-write.js

@@ -0,0 +1,210 @@
+import { JamError } from "../domain/errors.js";
+import { assertExistingIssueOperation, assertFieldsAllowed, assertOperationAllowed, assertWriteScope, PLAN_TTL_MS, resolveTransition, } from "../policy/write-policy.js";
+import { planCreateIssue } from "./plan-create-issue.js";
+/**
+ * Work out whether a requested change is currently possible, and describe it.
+ *
+ * Reads only. Nothing here mutates Jira, and that is the whole point of the
+ * step: the agent gets to see what the issue looks like now, what JAM would
+ * do to it, and what a direct read will have to show before JAM will call it
+ * done - all before anything has happened.
+ *
+ * The order matters. Scope and operation are checked before any Jira call, so
+ * an out-of-scope key costs nothing and comes back as a JAM refusal rather
+ * than a 404. Everything after that is derived from the issue as Jira reports
+ * it right now, never from what the caller asserted about it.
+ */
+export async function planWrite(deps, request) {
+    // 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 = 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 createdAt = new Date();
+    const plan = deps.writePlans.create({
+        kind: "existing-issue",
+        issueKey,
+        projectKey,
+        operation,
+        before,
+        intendedAfter,
+        baseUpdated: issue.updated,
+        createdAt: createdAt.toISOString(),
+        expiresAt: new Date(createdAt.getTime() + PLAN_TTL_MS).toISOString(),
+        ...(transition ? { transition } : {}),
+        mutation,
+    });
+    return {
+        plan,
+        receipt: {
+            status: "planned",
+            planId: plan.planId,
+            issue: plan.issueKey,
+            operation: plan.operation,
+            before: plan.before,
+            intendedAfter: plan.intendedAfter,
+            expiresAt: plan.expiresAt,
+            verification: { method: "direct-issue-read", expects: plan.intendedAfter },
+        },
+    };
+}
+/**
+ * The issue as Jira has it, read directly by key.
+ *
+ * `getIssue`, not `getIssues`: ConsistencyPolicy requires a direct issue GET
+ * for anything that decides or confirms a write, and the bulk endpoint is not
+ * one. A JQL result can lag behind the issue it describes; a bulk fetch is
+ * free to answer from a different path than the single-issue endpoint. Neither
+ * difference matters for ordinary reads, and both matter here.
+ *
+ * The one read every write goes through - the pre-write conflict check, the
+ * post-write confirmation, and the post-create confirmation.
+ */
+export async function readIssue(deps, issueKey) {
+    const { issue: found } = 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",
+            "priority",
+            "labels",
+            "components",
+            "updated",
+        ],
+    });
+    if (!found) {
+        throw new JamError("ISSUE_NOT_FOUND", `Jira has no issue ${issueKey}, or it is not visible to this account.`, { issueKey });
+    }
+    return found;
+}
+/**
+ * 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.
+ *
+ * Pure: no Jira, no state. Whether an operation is supported, whether a field
+ * is writable and whether the input is even the right shape are all knowable
+ * without asking Jira anything, so they are answered first.
+ */
+function validateInput(operation, raw) {
+    switch (operation) {
+        case "comment.add": {
+            const text = raw.text;
+            if (typeof text !== "string" || text.trim().length === 0) {
+                throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "comment.add needs non-empty `input.text`.", { operation });
+            }
+            return { text: text.trim() };
+        }
+        case "field.update":
+            return assertFieldsAllowed(raw);
+        case "status.transition": {
+            const status = raw.status;
+            if (typeof status !== "string" || status.trim().length === 0) {
+                throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "status.transition needs non-empty `input.status`.", { operation });
+            }
+            return { status: status.trim() };
+        }
+    }
+}
+async function describe(deps, operation, issueKey, issue, input) {
+    switch (operation) {
+        case "comment.add": {
+            const { text } = input;
+            // Comments accumulate rather than replace, so `before` says what is
+            // there now by count - the plan is not claiming to know the thread.
+            return {
+                before: { comments: issue.comments.length },
+                intendedAfter: { commentAdded: text },
+                mutation: { kind: "comment", text },
+            };
+        }
+        case "field.update": {
+            const fields = input;
+            const before = {};
+            const after = {};
+            for (const [field, value] of Object.entries(fields)) {
+                before[field] = currentValue(issue, field);
+                after[field] = value;
+            }
+            return {
+                before,
+                intendedAfter: after,
+                mutation: { kind: "fields", fields: toJiraFields(fields) },
+            };
+        }
+        case "status.transition": {
+            const { status: target } = input;
+            // Ask Jira what is reachable rather than deriving an id from a name:
+            // transition ids are per-workflow, and a guessed one either fails or
+            // moves the issue somewhere nobody asked for.
+            const available = await deps.jiraWrite.getTransitions(issueKey);
+            const transition = resolveTransition(target, available);
+            return {
+                before: { status: issue.status },
+                intendedAfter: { status: transition.to },
+                mutation: { kind: "transition", transitionId: transition.id },
+                transition,
+            };
+        }
+    }
+}
+function currentValue(issue, field) {
+    switch (field) {
+        case "summary":
+            return issue.summary;
+        case "priority":
+            return issue.priority;
+        case "labels":
+            return issue.labels;
+        case "components":
+            return issue.components;
+        default:
+            return undefined;
+    }
+}
+/** Whitelisted values to the shapes Jira's field API expects. */
+function toJiraFields(input) {
+    const fields = {};
+    if (input.summary !== undefined)
+        fields["summary"] = input.summary;
+    if (input.priority !== undefined)
+        fields["priority"] = { name: input.priority };
+    if (input.labels !== undefined)
+        fields["labels"] = input.labels;
+    if (input.components !== undefined) {
+        fields["components"] = input.components.map((name) => ({ name }));
+    }
+    return fields;
+}

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

@@ -0,0 +1,42 @@
+import type { NewWritePlan, WritePlan } from "../domain/write.js";
+/**
+ * Where a plan lives between `jira_write_plan` and `jira_write_apply`.
+ *
+ * In this process, and nowhere else. The alternative considered was a signed
+ * self-contained token, and it is worse here on both counts that matter: the
+ * signing key would have to come from somewhere (a new secret on disk, or a
+ * per-process key that gives the token exactly this lifetime anyway), and the
+ * mutation would have to travel through the agent to come back. Keeping the
+ * mutation in memory makes forgery impossible rather than merely hard - a
+ * `planId` is an opaque handle, and what it names never leaves this process.
+ *
+ * The cost is that plans do not survive a restart. That is acceptable: a plan
+ * is only valid while the issue has not moved, so a stale one was going to be
+ * rejected on its own terms, and re-planning is a single read.
+ *
+ * See docs/decisions/adr-jira-write-plane.md.
+ */
+export declare class WritePlanStore {
+    private readonly now;
+    private readonly plans;
+    /** Injected by tests so expiry does not depend on wall-clock timing. */
+    constructor(now?: () => Date);
+    create(plan: NewWritePlan): WritePlan;
+    /**
+     * Resolve a plan for applying.
+     *
+     * An expired plan is reported as expired rather than as missing: those are
+     * different situations, and telling them apart is the difference between
+     * "re-plan" and "you are calling this wrong".
+     */
+    take(planId: string): WritePlan;
+    /**
+     * Retire a plan once it has been applied.
+     *
+     * Single use, so a receipt cannot be turned into a second mutation by
+     * calling apply again with the same id - which for `comment.add` would mean
+     * two comments.
+     */
+    consume(planId: string): void;
+    private evictExpired;
+}

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

@@ -0,0 +1,81 @@
+import { randomUUID } from "node:crypto";
+import { JamError } from "../domain/errors.js";
+import { planExpired } from "../policy/write-policy.js";
+/**
+ * Where a plan lives between `jira_write_plan` and `jira_write_apply`.
+ *
+ * In this process, and nowhere else. The alternative considered was a signed
+ * self-contained token, and it is worse here on both counts that matter: the
+ * signing key would have to come from somewhere (a new secret on disk, or a
+ * per-process key that gives the token exactly this lifetime anyway), and the
+ * mutation would have to travel through the agent to come back. Keeping the
+ * mutation in memory makes forgery impossible rather than merely hard - a
+ * `planId` is an opaque handle, and what it names never leaves this process.
+ *
+ * The cost is that plans do not survive a restart. That is acceptable: a plan
+ * is only valid while the issue has not moved, so a stale one was going to be
+ * rejected on its own terms, and re-planning is a single read.
+ *
+ * See docs/decisions/adr-jira-write-plane.md.
+ */
+export class WritePlanStore {
+    now;
+    plans = new Map();
+    /** Injected by tests so expiry does not depend on wall-clock timing. */
+    constructor(now = () => new Date()) {
+        this.now = now;
+    }
+    create(plan) {
+        this.evictExpired();
+        const stored = { ...plan, planId: randomUUID() };
+        this.plans.set(stored.planId, stored);
+        return stored;
+    }
+    /**
+     * Resolve a plan for applying.
+     *
+     * An expired plan is reported as expired rather than as missing: those are
+     * different situations, and telling them apart is the difference between
+     * "re-plan" and "you are calling this wrong".
+     */
+    take(planId) {
+        const plan = this.plans.get(planId);
+        if (!plan) {
+            throw new JamError("JAM_WRITE_PLAN_NOT_FOUND", "No such write plan. Plans live in the running JAM server and do not survive a restart - call jira_write_plan again.", { planId });
+        }
+        if (planExpired(plan.expiresAt, this.now())) {
+            this.plans.delete(planId);
+            // 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;
+    }
+    /**
+     * Retire a plan once it has been applied.
+     *
+     * Single use, so a receipt cannot be turned into a second mutation by
+     * calling apply again with the same id - which for `comment.add` would mean
+     * two comments.
+     */
+    consume(planId) {
+        this.plans.delete(planId);
+    }
+    evictExpired() {
+        const now = this.now();
+        for (const [id, plan] of this.plans) {
+            if (planExpired(plan.expiresAt, now))
+                this.plans.delete(id);
+        }
+    }
+}

package/dist/bootstrap/boot-health-gate.js

@@ -1,5 +1,5 @@
 import { toJamError } from "../domain/errors.js";
-import { createServer } from "../mcp/create-server.js";
+import { createServer, TOOL_COUNT } from "../mcp/create-server.js";
 /**
  * One health-check core shared by `jam doctor`, `jam setup` and `jam serve`.
  *
@@ -60,7 +60,7 @@ export async function runHealthGate(deps, mode) {
     });
     try {
         createServer(deps);
-        add({ name: "MCP server startup", ok: true, fatal: true, detail: "3 tools registered" });
+        add({ name: "MCP server startup", ok: true, fatal: true, detail: `${TOOL_COUNT} tools registered` });
     }
     catch (err) {
         add({ name: "MCP server startup", ok: false, fatal: true, detail: toJamError(err).message });

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.0.1", "serve"];
+    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.2.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/cli-entry.js

@@ -11,39 +11,39 @@ import { authStatusCommand, doctorJsonCommand, setupAgentCommand, setupApplyComm
  * points (notably @jam-mcp/bootstrap) can forward to exactly these commands
  * instead of reimplementing them.
  */
-export const USAGE = `jam - Jira Agent MCP
-
-Usage:
-  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)
-  jam doctor              Diagnose config, credentials and Jira connectivity
-  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]
-                          Wire up this project and run doctor. Binds it to you
-                          alone, writing nothing to the repository; --shared
-                          adopts JAM for the team (project.yaml, .mcp.json)
-  jam runtime             Show which JAM build this machine runs
-  jam runtime use package | development <path>
-                          Change it (writes ~/.jam/config.yaml only, never a project)
-  jam auth login          Store Jira credentials in this user's OS secret store
-  jam auth logout         Remove them again
-
-For coding agents and scripts (stdout is JSON only, never prompts):
-  jam setup --agent       One shot: detect, plan, apply what is safe, verify
-  jam setup plan --json   Report what setup would change, changing nothing
-  jam setup apply --non-interactive --json
-                          Execute the plan
-  jam doctor --json       Health check as structured output
-  jam auth status --json  Whether Jira credentials are configured (never their value)
-
-Environment:
-  JIRA_BASE_URL     https://your-site.atlassian.net
-  JIRA_EMAIL        Atlassian account email
-  JIRA_API_TOKEN    Atlassian API token
-  JAM_PROJECT_KEY   Jira project key, used by \`jam setup\`/\`jam serve\` when no
-                     .jira-agent/project.yaml exists yet
-
-Credentials and JAM_PROJECT_KEY are read from the current shell's environment
-first, then (on Windows) from the User environment - so a value set with
-\`setx\` works without opening a new terminal.
+export const USAGE = `jam - Jira Agent MCP
+
+Usage:
+  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)
+  jam doctor              Diagnose config, credentials and Jira connectivity
+  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]
+                          Wire up this project and run doctor. Binds it to you
+                          alone, writing nothing to the repository; --shared
+                          adopts JAM for the team (project.yaml, .mcp.json)
+  jam runtime             Show which JAM build this machine runs
+  jam runtime use package | development <path>
+                          Change it (writes ~/.jam/config.yaml only, never a project)
+  jam auth login          Store Jira credentials in this user's OS secret store
+  jam auth logout         Remove them again
+
+For coding agents and scripts (stdout is JSON only, never prompts):
+  jam setup --agent       One shot: detect, plan, apply what is safe, verify
+  jam setup plan --json   Report what setup would change, changing nothing
+  jam setup apply --non-interactive --json
+                          Execute the plan
+  jam doctor --json       Health check as structured output
+  jam auth status --json  Whether Jira credentials are configured (never their value)
+
+Environment:
+  JIRA_BASE_URL     https://your-site.atlassian.net
+  JIRA_EMAIL        Atlassian account email
+  JIRA_API_TOKEN    Atlassian API token
+  JAM_PROJECT_KEY   Jira project key, used by \`jam setup\`/\`jam serve\` when no
+                     .jira-agent/project.yaml exists yet
+
+Credentials and JAM_PROJECT_KEY are read from the current shell's environment
+first, then (on Windows) from the User environment - so a value set with
+\`setx\` works without opening a new terminal.
 `;
 function findFlagValue(argv, flag) {
     const index = argv.indexOf(flag);

package/dist/deps.d.ts

@@ -4,6 +4,9 @@ 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 { 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";
 /** Everything the application layer is allowed to reach for. */
 export type JamDeps = {
@@ -12,6 +15,25 @@ export type JamDeps = {
     /** Where the project key came from when no config file supplied one. */
     keySource?: BootstrapSource;
     jira: JiraReadPort;
+    /**
+     * The mutating half. Separate from `jira` on purpose: reading and writing
+     * have different retry rules and different confirmation rules, and one port
+     * 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;
+    /**
+     * Plans awaiting apply. Lives for the life of this server process - see
+     * WritePlanStore for why it is not persisted.
+     */
+    writePlans: WritePlanStore;
     cache: CachePort;
     telemetry: TelemetryPort;
     credentials: CredentialPort;
@@ -20,6 +42,10 @@ export type BuildDepsOptions = {
     cwd?: string;
     /** Injected by tests to bypass the real REST adapter. */
     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 to bypass the real process/registry credential lookup. */
     credentials?: CredentialPort;
     /**

package/dist/deps.js

@@ -2,6 +2,7 @@ import { NoopCache } from "./adapters/cache/noop-cache.js";
 import { CompositeCredentialProvider } from "./adapters/credentials/composite.js";
 import { ConsoleTelemetry } from "./adapters/telemetry/console-telemetry.js";
 import { resolveProjectConfig } from "./bootstrap/project-config-resolver.js";
+import { WritePlanStore } from "./application/write-plan-store.js";
 /**
  * Single composition root. `jam serve`, `jam doctor` and `jam setup` all wire
  * through here, so a doctor pass actually proves the server's configuration.
@@ -27,11 +28,24 @@ export async function buildDeps(options = {}) {
         const { JiraCloudReadAdapter } = await import("./adapters/jira-cloud/jira-read.adapter.js");
         jira = new JiraCloudReadAdapter(credentials, resolved.config);
     }
+    let jiraWrite = options.jiraWrite;
+    if (!jiraWrite) {
+        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);
+    }
     return {
         config: resolved.config,
         configPath: resolved.configPath,
         keySource: resolved.keySource,
         jira,
+        jiraWrite,
+        jiraCreateMetadata,
+        writePlans: new WritePlanStore(),
         cache: new NoopCache(),
         telemetry,
         credentials,

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"];
+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_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: {