engineering-memory 1.11.30 → 1.11.31

package/runtime/dist/src/mcp/tool-annotations.js

@@ -140,6 +140,12 @@ export const toolAnnotations = {
     'live_status.list': read,
     'live_status.notice_presented': repeatableWrite,
     'live_status.set_sharing': write,
+    'jira.status': read,
+    'jira.connect': outward, // the user approves access on Atlassian through the link it returns
+    'jira.disconnect': destructive, // the stored access is deleted; only a new approval restores it
+    'jira.link_project': write,
+    'jira.unlink_project': write,
+    'jira.map_people': write,
     'auth.status': read,
     'auth.signin_browser': outward,
     'auth.logout': destructive,

package/runtime/dist/src/mcp/tool-definitions.js

@@ -1,6 +1,7 @@
 import { registerDeliveryTools } from './delivery-tools.js';
 import { registerReviewTools } from './review-tools.js';
 import { registerLiveStatusTools } from './live-status-tools.js';
+import { registerJiraTools } from './jira-tools.js';
 import { registerStatusMeaningTools } from './status-meaning-tools.js';
 import { registerStatusRemapTools } from './status-remap-tools.js';
 import { registerWorkflowTools } from './workflow-tools.js';
@@ -180,6 +181,12 @@ export const engineeringMemoryToolNames = [
     'live_status.list',
     'live_status.notice_presented',
     'live_status.set_sharing',
+    'jira.status',
+    'jira.connect',
+    'jira.disconnect',
+    'jira.link_project',
+    'jira.unlink_project',
+    'jira.map_people',
     'auth.status',
     'auth.signin_browser',
     'auth.logout',
@@ -1252,6 +1259,7 @@ export function registerEngineeringMemoryTools(server, service) {
         inputSchema: z.object({ projectId: z.string().min(1) }),
     }, async (input) => toolResult(await service.projectLinks(input)));
     registerLiveStatusTools(server, service);
+    registerJiraTools(server, service);
     server.registerTool('auth.status', {
         description: 'Check whether OS credential storage contains an active local Engineering Memory session.',
         inputSchema: z.object({}),

package/runtime/dist/src/providers/jira-connect.js

@@ -0,0 +1,182 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import * as z from 'zod/v4';
+import { endpoints } from '../config.js';
+import { ApiResponseError } from '../runtime/api-client.js';
+import { copies, escapeHtml, format, textDirection } from '../runtime/texts.js';
+const text = z.string().min(1);
+const pageWording = z.strictObject({
+    title: text,
+    connected: text,
+    chooseSite: text,
+    cancelled: text,
+    failed: text,
+    invalid: text,
+});
+const started = z.object({
+    requestId: z.uuid(),
+    connectUrl: z.url(),
+    expiresAt: z.iso.datetime({ offset: true }),
+});
+export class JiraConnectCoordinator {
+    client;
+    language;
+    flows = new Map();
+    constructor(client, language = async () => undefined) {
+        this.client = client;
+        this.language = language;
+    }
+    state(organizationId) {
+        return this.flows.get(organizationId)?.state ?? null;
+    }
+    async start(organizationId, projectId) {
+        await this.forget(organizationId);
+        const codeVerifier = randomBytes(32).toString('base64url');
+        const server = createServer((request, response) => {
+            void this.callback(organizationId, request, response);
+        });
+        await new Promise((resolvePromise, reject) => {
+            server.once('error', reject);
+            server.listen(0, '127.0.0.1', resolvePromise);
+        });
+        server.unref();
+        const port = server.address().port;
+        try {
+            const envelope = await this.client.request(endpoints.jiraConnect(organizationId), {
+                method: 'POST',
+                body: {
+                    codeChallenge: createHash('sha256').update(codeVerifier).digest('base64url'),
+                    callbackUrl: `http://127.0.0.1:${port}/callback`,
+                    ...(projectId ? { projectId } : {}),
+                },
+            });
+            const request = started.parse(envelope.data);
+            const state = {
+                phase: 'waiting',
+                connectUrl: request.connectUrl,
+                expiresAt: request.expiresAt,
+            };
+            const timer = setTimeout(() => void this.expire(organizationId, request.requestId), Math.max(0, Date.parse(request.expiresAt) - Date.now()));
+            timer.unref();
+            this.flows.set(organizationId, {
+                requestId: request.requestId,
+                codeVerifier,
+                port,
+                server,
+                timer,
+                state,
+            });
+            return state;
+        }
+        catch (error) {
+            await close(server);
+            throw error;
+        }
+    }
+    async forget(organizationId) {
+        const flow = this.flows.get(organizationId);
+        if (!flow)
+            return;
+        this.flows.delete(organizationId);
+        clearTimeout(flow.timer);
+        await close(flow.server);
+    }
+    async dispose() {
+        for (const organizationId of [...this.flows.keys()])
+            await this.forget(organizationId);
+    }
+    async expire(organizationId, requestId) {
+        const flow = this.flows.get(organizationId);
+        if (flow?.requestId !== requestId || flow.state.phase === 'finishing')
+            return;
+        if (flow.state.phase === 'waiting')
+            flow.state = { phase: 'expired' };
+        await close(flow.server);
+    }
+    async callback(organizationId, request, response) {
+        const flow = this.flows.get(organizationId);
+        try {
+            const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+            if (!flow ||
+                request.method !== 'GET' ||
+                request.headers.host !== `127.0.0.1:${flow.port}` ||
+                url.pathname !== '/callback' ||
+                url.searchParams.get('requestId') !== flow.requestId ||
+                flow.state.phase !== 'waiting' ||
+                Date.parse(flow.state.expiresAt) <= Date.now())
+                return this.send(response, 400, await this.page('invalid'));
+            const code = url.searchParams.get('code');
+            if (!code) {
+                const cancelled = url.searchParams.get('error') === 'cancelled';
+                flow.state = cancelled
+                    ? { phase: 'cancelled' }
+                    : {
+                        phase: 'failed',
+                        message: 'Atlassian did not finish the authorization. Start jira.connect again.',
+                        recovery: 'jira.connect',
+                    };
+                return this.finish(flow, response, await this.page(cancelled ? 'cancelled' : 'failed'));
+            }
+            flow.state = { phase: 'finishing' };
+            try {
+                const envelope = await this.client.request(endpoints.jiraConnectComplete(organizationId), {
+                    method: 'POST',
+                    body: { requestId: flow.requestId, code, codeVerifier: flow.codeVerifier },
+                });
+                const result = envelope.data ?? {};
+                flow.state = { phase: 'answered', result };
+                const connection = result.connection;
+                return this.finish(flow, response, result.outcome === 'connected'
+                    ? await this.page('connected', String(connection?.siteName ?? ''))
+                    : await this.page('chooseSite'));
+            }
+            catch (error) {
+                flow.state = {
+                    phase: 'failed',
+                    message: error instanceof Error ? error.message : 'The Jira connection failed.',
+                    recovery: error instanceof ApiResponseError ? error.recovery : null,
+                };
+                return this.finish(flow, response, await this.page('failed'), 502);
+            }
+        }
+        catch {
+            return this.send(response, 500, await this.page('failed'));
+        }
+    }
+    finish(flow, response, html, status = 200) {
+        clearTimeout(flow.timer);
+        response.once('finish', () => void close(flow.server));
+        this.send(response, status, html);
+    }
+    send(response, status, html) {
+        response.writeHead(status, {
+            'Content-Type': 'text/html; charset=utf-8',
+            'Cache-Control': 'no-store',
+            'Referrer-Policy': 'no-referrer',
+            'X-Content-Type-Options': 'nosniff',
+            'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'",
+        });
+        response.end(html);
+    }
+    async page(notice, site = '') {
+        const told = await this.language().catch(() => undefined);
+        const { language, copy } = copies(pageWording, 'jiraConnect', told)[0];
+        const message = format(copy[notice], language, { site });
+        return (`<!doctype html><html lang="${escapeHtml(language)}" dir="${textDirection(language)}"><head>` +
+            '<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">' +
+            `<title>${escapeHtml(copy.title)}</title><style>` +
+            'body{font:16px/1.5 system-ui,sans-serif;margin:0;padding:24px 16px;background:#f6f7f9;color:#1d2330}' +
+            'main{max-width:560px;margin:0 auto}h1{font-size:22px;line-height:1.3}' +
+            '@media (prefers-color-scheme:dark){body{background:#14171c;color:#e6e9ef}}' +
+            `</style></head><body><main><h1>${escapeHtml(copy.title)}</h1><p>${escapeHtml(message)}</p></main></body></html>`);
+    }
+}
+async function close(server) {
+    if (!server.listening)
+        return;
+    await new Promise((resolvePromise) => {
+        server.close(() => resolvePromise());
+        server.closeAllConnections();
+    });
+}
+//# sourceMappingURL=jira-connect.js.map

package/runtime/dist/src/runtime/api-client.js

@@ -9,6 +9,7 @@ export const backendRecoveryOperationNames = [
     'auth.web_signin',
     'audit.list',
     'live_status.list',
+    'jira.status',
     'organization.member_list',
     'organization.member_upsert',
     'project.setup',

package/runtime/dist/src/runtime/bridge-service.js

@@ -4361,6 +4361,89 @@ export class BridgeService {
             return asJsonValue(response.data);
         });
     }
+    async jiraProjectState(input) {
+        return await this.execute(async () => {
+            const projectId = input.projectId ?? (await this.jiraBoundProject(input.repoRoot));
+            const response = await this.dependencies.client.request(endpoints.projectJira(projectId));
+            return asJsonValue(response.data);
+        });
+    }
+    async jiraOrganizationStatus(organizationId) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.jiraStatus(organizationId));
+            return asJsonValue(response.data);
+        });
+    }
+    async jiraConnectStart(input) {
+        return await this.execute(async () => {
+            const connector = this.dependencies.jiraConnect;
+            if (!connector)
+                throw refuse('This bridge was started without Jira support. Update Engineering Memory and run jira.connect again.', 'jira.status');
+            const current = connector.state(input.organizationId);
+            if (current && !input.restart && current.phase !== 'expired')
+                return asJsonValue(current);
+            return asJsonValue(await connector.start(input.organizationId, input.projectId));
+        });
+    }
+    async jiraConnectForget(organizationId) {
+        await this.dependencies.jiraConnect?.forget(organizationId);
+    }
+    async jiraChooseSite(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.jiraConnectSite(input.organizationId), { method: 'POST', body: { requestId: input.requestId, cloudId: input.cloudId } });
+            return asJsonValue(response.data);
+        });
+    }
+    async jiraDisconnect(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.jiraDisconnect(input.organizationId, input.connectionId), { method: 'POST' });
+            return asJsonValue(response.data);
+        });
+    }
+    async jiraProjects(input) {
+        return await this.execute(async () => {
+            const query = input.key ? `?${new URLSearchParams({ key: input.key })}` : '';
+            const response = await this.dependencies.client.request(endpoints.projectJiraProjects(input.projectId, input.connectionId) + query);
+            return asJsonValue(response.data);
+        });
+    }
+    async jiraLink(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.projectJiraLink(input.projectId), {
+                method: 'PUT',
+                body: {
+                    connectionId: input.connectionId,
+                    jiraProjectId: input.jiraProjectId,
+                    ...(input.replace ? { replace: true } : {}),
+                },
+            });
+            return asJsonValue(response.data);
+        });
+    }
+    async jiraUnlink(projectId) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.projectJiraUnlink(projectId), { method: 'POST' });
+            return asJsonValue(response.data);
+        });
+    }
+    async jiraPeople(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.jiraPeople(input.organizationId, input.connectionId));
+            return asJsonValue(response.data);
+        });
+    }
+    async jiraDecidePeople(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.jiraPeopleDecisions(input.organizationId, input.connectionId), { method: 'POST', body: { decisions: input.decisions } });
+            return asJsonValue(response.data);
+        });
+    }
+    async jiraBoundProject(repoRoot) {
+        const repository = await this.dependencies.repositories.resolveIdentity(repoRoot ?? process.cwd());
+        if (!repository.projectId)
+            throw refuse('This repository has no selected project. Name the projectId, or the organizationId for the organization-wide Jira tools.', 'session.entry');
+        return repository.projectId;
+    }
     async boundProject(repoRoot) {
         const repository = await this.dependencies.repositories.resolveIdentity(repoRoot ?? process.cwd());
         if (!repository.projectId)
@@ -4604,6 +4687,7 @@ export class BridgeService {
                 await this.dependencies.credentials.clear();
             }
             await this.dependencies.browserAuth.dispose();
+            await this.dependencies.jiraConnect?.dispose();
             return asJsonValue({ loggedOut: true, remoteRevoked, remoteStatus });
         }, true);
     }

package/runtime/dist/src/runtime/create-bridge-service.js

@@ -22,6 +22,7 @@ import { PrincipalStateGuard, principalFingerprint } from './principal-state.js'
 import { MergeRequests } from './merge-request-sync.js';
 import { GitLabClient, GitLabTokens } from '../providers/gitlab.js';
 import { GitLabTokenPage } from '../providers/gitlab-token-page.js';
+import { JiraConnectCoordinator } from '../providers/jira-connect.js';
 import { OnboardingStore } from './onboarding-store.js';
 import { QuestionnaireStore } from './questionnaire-store.js';
 import { sha256 } from '../utilities/hash.js';
@@ -115,6 +116,7 @@ export function createBridgeService(options = {}) {
             page: new GitLabTokenPage(gitlabTokens, gitlab, signedInLanguage),
             requests: new MergeRequests(client, gitlabTokens, gitlab, git, signedInLanguage),
         },
+        jiraConnect: new JiraConnectCoordinator(client, signedInLanguage),
     }));
 }
 //# sourceMappingURL=create-bridge-service.js.map

package/skill/references/lifecycle.md

@@ -456,3 +456,24 @@ roles stay as they are; change an aimed role separately with work_item.setup_wor
 bound to the counts it showed: when they change, the question is asked again, and a change at the
 moment of writing moves nothing. It is critical under the task mode. An empty source needs no
 question. Keep the same requestKey to resume and honor deferral as in the flows above.
+
+## Jira connection
+
+When the user asks to connect Jira, to link the project to a Jira project or to match people, start
+with `jira.status`: it reads the bound project's link and the organization's connections and names
+the next step. `jira.connect` returns a one-time link: give it to the user as it is and never open it
+yourself; they open it on this computer and approve access in Atlassian. Call `jira.connect` again
+without `restart` to learn how it ended, and while it still waits, wait for the user; `restart: true`
+only discards a link the user no longer wants. When Jira is not configured on the server, say that
+the person who runs the server must add its settings, and do not retry. A connection that needs
+reconnecting is renewed with `jira.connect`.
+
+`jira.link_project`, `jira.unlink_project`, `jira.disconnect` and `jira.map_people` take a
+`requestKey`: reuse it to retry or continue the same request, and use a new one when the user asks
+again later. Every choice here (the site, the Jira project, replacing or pausing a link,
+disconnecting, who each person is) is asked of the user natively in every task mode; never answer it
+yourself. Pass a Jira project key the user names as `jiraProjectKey`. Match a person only from the
+user's answer and never guess a handle; a typed e-mail address is refused, so ask for the part before
+`@`. The access only reads Jira and Jira issues are not brought in yet, so do not promise writing to
+Jira or importing issues. After a disconnect the user can also remove the app on Atlassian's side, at
+id.atlassian.com → Connected apps, as the tool says.