@infinisys/is-devops 0.0.0-stage → 0.1.0

package/index.js

@@ -0,0 +1,948 @@
+/**
+ * Host half of the Infinity DevOps bundle.
+ *
+ * Two surfaces share one GitFox client:
+ *
+ * - an authenticated same-origin proxy (`/infinity/devops/api/v1/...`) for the
+ *   Client panel — the browser never sees the access token;
+ * - one compact agent tool, `infinity_devops`, for the Fabric AI team and any
+ *   other agent that needs to read or change issues, merge requests, commits,
+ *   branches, and projects.
+ *
+ * The `infinityDevOps` Host service exposes the same client to sibling Host
+ * plugins, which keeps future Fabric automation on one integration seam.
+ */
+import { botNameFor, defaultActorRecord, normalizeActorRecord } from './lib/bot-identity.js';
+import { createGitRepository } from './lib/git-repository.js';
+import { createGitTool } from './lib/git-tool.js';
+import { projectFromCloneUrl, undiscovered } from './lib/project-discovery.js';
+import {
+  GitFoxError,
+  createGitFoxClient,
+  readRequestBody,
+  withQuery,
+} from './lib/gitfox-api.js';
+
+const PROXY_PREFIX = '/infinity/devops';
+const MAX_PROXY_BODY_BYTES = 5 * 1024 * 1024;
+const PROXY_TIMEOUT_MS = 30_000;
+/** Custom header required on every browser call (CSRF / cross-origin guard). */
+const REQUEST_HEADER = 'x-infinity-request';
+const PROXY_METHODS = ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'];
+const ISSUE_WRITABLE_FIELDS = ['title', 'description', 'state', 'labels'];
+/** Fields `update_merge_request` may rewrite; the rest of the record stays as written. */
+const MERGE_REQUEST_WRITABLE_FIELDS = ['title', 'description'];
+
+const TOOL_DESCRIPTION =
+  'Read and manage GitFox DevOps resources for the Infinity System: projects, issues, merge requests, their comments, commits and branches. Connect GitFox once in Settings → Infinity System. Project references use "namespace/name"; issue and merge-request ids are project-scoped iids. Agent-created issues and merge requests are attributed to the infinsys-* bot identity; comments are written as the connected account because GitFox notes have no bot field. A remark about an existing issue or merge request belongs in its thread ("create_issue_note" / "create_merge_request_note"), not in a new issue.';
+
+const TOOL_PARAMETERS = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    action: {
+      type: 'string',
+      enum: [
+        'status',
+        'projects',
+        'issues',
+        'issue',
+        'create_issue',
+        'update_issue',
+        'issue_notes',
+        'create_issue_note',
+        'merge_requests',
+        'create_merge_request',
+        'merge_merge_request',
+        'update_merge_request',
+        'close_merge_request',
+        'merge_request_notes',
+        'create_merge_request_note',
+        'branches',
+        'create_branch',
+        'delete_branch',
+        'commits',
+        'commit',
+      ],
+      description:
+        'Operation to perform. "status" checks the connection; "projects" lists visible projects; list actions accept page/per_page. "*_notes" read the comments of one issue or merge request; "create_*_note" posts a comment instead of editing the record.',
+    },
+    project: {
+      type: 'string',
+      description: 'Project reference in "namespace/name" form.',
+    },
+    iid: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Project-scoped issue or merge-request id.',
+    },
+    sha: { type: 'string', description: 'Commit SHA for action "commit".' },
+    branch: { type: 'string', description: 'Branch name for "delete_branch".' },
+    ref: {
+      type: 'string',
+      description: 'Source revision for "create_branch" or commit filter for "commits".',
+    },
+    name: { type: 'string', description: 'New branch name for "create_branch".' },
+    title: { type: 'string', description: 'Issue or merge-request title.' },
+    description: { type: 'string', description: 'Issue or merge-request description.' },
+    body: {
+      type: 'string',
+      description: 'Comment text for "create_issue_note" and "create_merge_request_note".',
+    },
+    state: {
+      type: 'string',
+      enum: ['open', 'closed', 'all'],
+      description: 'Issue filter or new state for "update_issue".',
+    },
+    status: {
+      type: 'string',
+      enum: ['open', 'merged', 'closed', 'draft'],
+      description: 'Merge-request status filter.',
+    },
+    labels: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'Issue labels.',
+    },
+    source_branch: { type: 'string', description: 'Merge-request source branch.' },
+    target_branch: { type: 'string', description: 'Merge-request target branch.' },
+    is_draft: { type: 'boolean', description: 'Create the merge request as a draft.' },
+    squash: { type: 'boolean', description: 'Squash commits while merging.' },
+    delete_source_branch: {
+      type: 'boolean',
+      description: 'Delete the source branch after a merge.',
+    },
+    page: { type: 'integer', minimum: 1, description: 'Page number, starting at 1.' },
+    per_page: {
+      type: 'integer',
+      minimum: 1,
+      maximum: 100,
+      description: 'Page size, 1–100.',
+    },
+  },
+  required: ['action'],
+};
+
+/**
+ * Whether one socket address is a loopback address.
+ *
+ * @param {string} address - `remoteAddress` or `localAddress` text.
+ * @returns {boolean} loopback status.
+ */
+function isLoopbackAddress(address) {
+  const text = address.startsWith('[') ? address.slice(1, address.indexOf(']')) : address;
+  const bare = text.split('%')[0];
+  if (bare === '::1') return true;
+  const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(bare);
+  return /^127\./.test(mapped === null ? bare : mapped[1]);
+}
+
+/**
+ * Whether the request may use the Fabric HTTP surface.
+ *
+ * Two things make a request local: it comes from loopback, or it arrives on the
+ * address the Harness listener itself is bound to. The second case is the
+ * operator's own choice — a listener bound to a network address serves that
+ * network — so following the listener keeps the panel working exactly where the
+ * GUI URL points instead of failing behind a loopback-only guard.
+ * `INFINITY_ALLOW_NON_LOOPBACK=1` stays as the explicit override for
+ * deployments that terminate authentication in front of the Harness.
+ *
+ * @param {import('node:http').IncomingMessage} req - incoming request.
+ * @returns {boolean} whether the peer may use the route.
+ */
+function isLocalRequest(req) {
+  if (process.env.INFINITY_ALLOW_NON_LOOPBACK === '1') return true;
+  const socket = req.socket;
+  if (socket === undefined) return true;
+  if (socket.remoteAddress === undefined) return true;
+  if (isLoopbackAddress(socket.remoteAddress)) return true;
+  // The connection's local address is the listener's bind address, so it names
+  // the interface this request actually reached. Loopback there means the
+  // Harness never offered the port to the network.
+  return socket.localAddress !== undefined && !isLoopbackAddress(socket.localAddress);
+}
+
+/**
+ * Limit the proxy to the DevOps resources the panel actually uses.
+ *
+ * @param {string} method - HTTP method.
+ * @param {string} pathname - decoded URL pathname.
+ * @returns {boolean} whether the proxy may forward the request.
+ */
+function isAllowedProxyRequest(method, pathname) {
+  if (pathname === '/api/v1/projects') return method === 'GET' || method === 'HEAD';
+  const project = /^\/api\/v1\/projects\/[^/]+\/[^/]+\/(issues|merge_requests)(?:\/\d+)?(?:\/merge)?$/;
+  const match = project.exec(pathname);
+  if (match !== null) return ['GET', 'HEAD', 'POST', 'PUT', 'DELETE'].includes(method);
+  if (/^\/api\/v1\/projects\/[^/]+\/[^/]+\/repository\/branches(?:\/.*)?$/.test(pathname)) {
+    return ['GET', 'HEAD', 'POST', 'DELETE'].includes(method);
+  }
+  if (/^\/api\/v1\/projects\/[^/]+\/[^/]+\/repository\/commits(?:\/[^/]+)?$/.test(pathname)) {
+    return method === 'GET' || method === 'HEAD';
+  }
+  return false;
+}
+
+/**
+ * Write one JSON error response.
+ *
+ * @param {import('node:http').ServerResponse} res - response to own.
+ * @param {number} status - HTTP status code.
+ * @param {string} code - stable machine code.
+ * @param {string} message - human-readable detail.
+ * @returns {void}
+ */
+function sendError(res, status, code, message) {
+  const body = JSON.stringify({ error: { code, message } });
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(body),
+  });
+  res.end(body);
+}
+
+/**
+ * Throw when one required tool argument is absent.
+ *
+ * @param {Record<string, unknown>} args - tool arguments.
+ * @param {string} key - required field.
+ * @returns {void}
+ */
+function requireArg(args, key) {
+  if (args[key] === undefined || args[key] === null || args[key] === '') {
+    throw new GitFoxError(`action "${args.action}" requires "${key}"`, { code: 'invalid-arguments' });
+  }
+}
+
+/**
+ * Require an integer tool argument.
+ *
+ * @param {Record<string, unknown>} args - tool arguments.
+ * @param {string} key - required field.
+ * @returns {number} integer value.
+ */
+function requireInt(args, key) {
+  requireArg(args, key);
+  const value = Number(args[key]);
+  if (!Number.isInteger(value) || value < 1) {
+    throw new GitFoxError(`"${key}" must be a positive integer`, { code: 'invalid-arguments' });
+  }
+  return value;
+}
+
+/**
+ * Require and return the `project` argument.
+ *
+ * @param {Record<string, unknown>} args - tool arguments.
+ * @returns {string} project reference.
+ */
+function requireProject(args) {
+  requireArg(args, 'project');
+  return /** @type {string} */ (args.project);
+}
+
+/**
+ * Format a tool value without letting one huge API response dominate context.
+ *
+ * @param {unknown} value - canonical tool value.
+ * @returns {string} model-facing text.
+ */
+function formatValue(value) {
+  const text = JSON.stringify(value, null, 2) ?? 'null';
+  return text.length <= 24_000 ? text : `${text.slice(0, 24_000)}\n… (truncated)`;
+}
+
+/**
+ * Resolve the GitFox connection through settings on every request.
+ *
+ * @param {{ infinitySettings: { resolveGitFox: () => Promise<{ baseUrl: string, token: string }> } }} ctx - Host context.
+ * @returns {Promise<{ baseUrl: string, token: string }>} connection.
+ */
+async function resolveGitFoxConfig(ctx) {
+  const connection = await ctx.infinitySettings.resolveGitFox();
+  return { baseUrl: connection.baseUrl, token: connection.token };
+}
+
+/**
+ * Validate one proxy request and derive its upstream target.
+ *
+ * @param {import('node:http').IncomingMessage} req - incoming request.
+ * @param {import('node:http').ServerResponse} res - response to own.
+ * @returns {{ method: string, rest: string } | null} target, or null after an error was sent.
+ */
+function proxyTarget(req, res) {
+  if (!isLocalRequest(req)) {
+    sendError(
+      res,
+      403,
+      'loopback-only',
+      'The DevOps proxy serves this computer only. Restart the Harness on one network address to serve that network.',
+    );
+    return null;
+  }
+  const method = req.method ?? 'GET';
+  if (req.headers[REQUEST_HEADER] !== '1') {
+    sendError(res, 403, 'csrf-guard', 'Missing request marker.');
+    return null;
+  }
+  if (!PROXY_METHODS.includes(method)) {
+    sendError(res, 405, 'method-not-allowed', `${method} is not supported`);
+    return null;
+  }
+
+  const url = new URL(req.url ?? '/', 'http://localhost');
+  const apiPath = url.pathname.slice(PROXY_PREFIX.length);
+  if (!apiPath.startsWith('/api/v1/')) {
+    sendError(res, 404, 'not-an-api-path', 'Only /infinity/devops/api/v1/* is proxied');
+    return null;
+  }
+  if (apiPath.includes('..') || apiPath.includes('\\')) {
+    sendError(res, 400, 'invalid-path', 'Path traversal is not allowed');
+    return null;
+  }
+  if (!isAllowedProxyRequest(method, apiPath)) {
+    sendError(res, 403, 'proxy-path-not-allowed', 'This DevOps resource is not exposed by the panel proxy.');
+    return null;
+  }
+  return { method, rest: `${apiPath}${url.search}` };
+}
+
+/**
+ * Build the upstream headers of one proxy call.
+ *
+ * @param {import('node:http').IncomingMessage} req - incoming request.
+ * @param {string} token - GitFox access token.
+ * @returns {Record<string, string>} headers.
+ */
+function proxyHeaders(req, token) {
+  return {
+    accept: typeof req.headers.accept === 'string' ? req.headers.accept : 'application/json',
+    authorization: `Bearer ${token}`,
+  };
+}
+
+/**
+ * Read the proxy request body for mutating methods.
+ *
+ * @param {import('node:http').IncomingMessage} req - incoming request.
+ * @param {string} method - HTTP method.
+ * @returns {Promise<Buffer | undefined>} body bytes, or undefined for GET/HEAD.
+ */
+async function proxyBody(req, method) {
+  if (method === 'GET' || method === 'HEAD') return undefined;
+  return readRequestBody(req, MAX_PROXY_BODY_BYTES);
+}
+
+/**
+ * Forward one validated request to GitFox and stream its answer back.
+ *
+ * @param {object} ctx - Host context.
+ * @param {import('node:http').IncomingMessage} req - incoming request.
+ * @param {import('node:http').ServerResponse} res - response to own.
+ * @param {{ method: string, rest: string }} target - validated upstream target.
+ * @returns {Promise<void>}
+ */
+async function forwardProxyRequest(ctx, req, res, target) {
+  const connection = await ctx.infinitySettings.resolveGitFox();
+  if (connection.token === '') {
+    sendError(
+      res,
+      503,
+      'not-configured',
+      'GitFox is not connected. Open Settings → Infinity System and add an access token.',
+    );
+    return;
+  }
+
+  const headers = proxyHeaders(req, connection.token);
+  const body = await proxyBody(req, target.method);
+  if (body !== undefined && body.length > 0) {
+    headers['content-type'] =
+      typeof req.headers['content-type'] === 'string'
+        ? req.headers['content-type']
+        : 'application/json';
+  }
+
+  const upstream = await fetch(`${connection.baseUrl.replace(/\/+$/, '')}${target.rest}`, {
+    method: target.method,
+    headers,
+    body,
+    signal: AbortSignal.timeout(PROXY_TIMEOUT_MS),
+  });
+  const bytes = Buffer.from(await upstream.arrayBuffer());
+  const total = upstream.headers.get('x-total');
+  res.writeHead(upstream.status, {
+    'content-type': upstream.headers.get('content-type') ?? 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': bytes.length,
+    ...(total === null ? {} : { 'x-total': total }),
+  });
+  res.end(bytes);
+}
+
+/**
+ * Map a proxy failure onto a JSON error response.
+ *
+ * @param {import('node:http').ServerResponse} res - response to own.
+ * @param {any} error - thrown value.
+ * @returns {void}
+ */
+function proxyErrorResponse(res, error) {
+  if (error instanceof GitFoxError) {
+    sendError(res, error.status === 0 ? 502 : error.status, error.code, error.message);
+    return;
+  }
+  if (typeof error?.statusCode === 'number' && error.statusCode > 0) {
+    sendError(
+      res,
+      error.statusCode,
+      typeof error.code === 'string' ? error.code : 'auth-failed',
+      error instanceof Error ? error.message : String(error),
+    );
+    return;
+  }
+  if (error instanceof Error && error.name === 'TimeoutError') {
+    sendError(res, 504, 'timeout', 'GitFox did not answer within 30 seconds.');
+    return;
+  }
+  sendError(
+    res,
+    502,
+    'unreachable',
+    `Cannot reach GitFox: ${error instanceof Error ? error.message : String(error)}`,
+  );
+}
+
+/**
+ * Handle one authenticated proxy request.
+ *
+ * @param {object} ctx - Host context.
+ * @param {import('node:http').IncomingMessage} req - incoming request.
+ * @param {import('node:http').ServerResponse} res - response to own.
+ * @returns {Promise<void>}
+ */
+async function handleProxy(ctx, req, res) {
+  const target = proxyTarget(req, res);
+  if (target === null) return;
+  try {
+    await forwardProxyRequest(ctx, req, res, target);
+  } catch (error) {
+    proxyErrorResponse(res, error);
+  }
+}
+
+/**
+ * Register the same-origin proxy route.
+ *
+ * @param {object} ctx - Host context.
+ * @returns {void}
+ */
+function registerProxyRoutes(ctx) {
+  ctx.effect(
+    () =>
+      ctx.webServer.register({
+        kind: 'prefix',
+        path: PROXY_PREFIX,
+        handler: (req, res) => handleProxy(ctx, req, res),
+      }),
+    'is-devops: authenticated GitFox API proxy',
+  );
+}
+
+/**
+ * @param {Record<string, unknown>} args - tool arguments.
+ * @returns {{ page: number, per_page: number }} paging query.
+ */
+function pageQuery(args) {
+  return { page: args.page ?? 1, per_page: args.per_page ?? 50 };
+}
+
+/**
+ * @param {object} api - GitFox client.
+ * @returns {Promise<unknown>} the authenticated user, or null when unconfigured.
+ */
+async function currentUser(api) {
+  try {
+    return await api.me();
+  } catch (error) {
+    if (!(error instanceof GitFoxError) || error.code !== 'not-configured') throw error;
+    return null;
+  }
+}
+
+/**
+ * @param {{ ctx: object, api: object }} deps - action dependencies.
+ * @returns {Promise<{ result: unknown }>} status result.
+ */
+async function handleStatus({ ctx, api }) {
+  const connection = await ctx.infinitySettings.getGitFoxStatus();
+  const user = await currentUser(api);
+  return { result: { connection, user: user ?? null } };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ result: unknown }>} projects result.
+ */
+async function handleProjects({ api, args }) {
+  return { result: await api.listProjects(pageQuery(args)) };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ project: string, result: unknown }>} issue list result.
+ */
+async function handleIssues({ api, args }) {
+  const project = requireProject(args);
+  const result = await api.listIssues(project, {
+    state: args.state ?? 'open',
+    ...pageQuery(args),
+  });
+  return { project, result };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ project: string, result: unknown }>} issue detail.
+ */
+async function handleIssue({ api, args }) {
+  const project = requireProject(args);
+  return { project, result: await api.getIssue(project, requireInt(args, 'iid')) };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ project: string, result: unknown }>} created issue.
+ */
+async function handleCreateIssue({ api, args, actor }) {
+  const project = requireProject(args);
+  requireArg(args, 'title');
+  const body = { title: args.title };
+  if (args.description !== undefined) body.description = args.description;
+  if (Array.isArray(args.labels)) body.labels = args.labels;
+  return { project, result: await api.createIssue(project, body, { botName: actor.botName }) };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ project: string, result: unknown }>} updated issue.
+ */
+async function handleUpdateIssue({ api, args }) {
+  const project = requireProject(args);
+  const iid = requireInt(args, 'iid');
+  const body = {};
+  for (const field of ISSUE_WRITABLE_FIELDS) {
+    if (args[field] !== undefined) body[field] = args[field];
+  }
+  return { project, result: await api.updateIssue(project, iid, body) };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ project: string, result: unknown }>} issue comments.
+ */
+async function handleIssueNotes({ api, args }) {
+  const project = requireProject(args);
+  return { project, result: await api.listIssueNotes(project, requireInt(args, 'iid')) };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ project: string, result: unknown }>} created comment.
+ */
+async function handleCreateIssueNote({ api, args }) {
+  const project = requireProject(args);
+  const iid = requireInt(args, 'iid');
+  requireArg(args, 'body');
+  return { project, result: await api.addIssueNote(project, iid, { body: args.body }) };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ project: string, result: unknown }>} merge request list.
+ */
+async function handleMergeRequests({ api, args }) {
+  const project = requireProject(args);
+  const query = {};
+  if (args.status !== undefined) query.status = args.status;
+  Object.assign(query, pageQuery(args));
+  return { project, result: await api.listMergeRequests(project, query) };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ project: string, result: unknown }>} created merge request.
+ */
+async function handleCreateMergeRequest({ api, args, actor }) {
+  const project = requireProject(args);
+  requireArg(args, 'title');
+  requireArg(args, 'source_branch');
+  requireArg(args, 'target_branch');
+  const body = {
+    title: args.title,
+    source_branch: args.source_branch,
+    target_branch: args.target_branch,
+  };
+  if (args.description !== undefined) body.description = args.description;
+  if (args.is_draft !== undefined) body.is_draft = args.is_draft;
+  return {
+    project,
+    result: await api.createMergeRequest(project, body, { botName: actor.botName }),
+  };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ project: string, result: unknown }>} merge result.
+ */
+async function handleMergeMergeRequest({ api, args }) {
+  const project = requireProject(args);
+  const iid = requireInt(args, 'iid');
+  const body = {};
+  if (args.squash !== undefined) body.squash = args.squash;
+  if (args.delete_source_branch !== undefined) {
+    body.delete_source_branch = args.delete_source_branch;
+  }
+  return { project, result: await api.mergeMergeRequest(project, iid, body) };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ project: string, result: unknown }>} updated merge request.
+ */
+async function handleUpdateMergeRequest({ api, args }) {
+  const project = requireProject(args);
+  const iid = requireInt(args, 'iid');
+  const body = {};
+  for (const field of MERGE_REQUEST_WRITABLE_FIELDS) {
+    if (args[field] !== undefined) body[field] = args[field];
+  }
+  if (Object.keys(body).length === 0) {
+    throw new GitFoxError(
+      `action "update_merge_request" requires "title" or "description"`,
+      { code: 'invalid-arguments' },
+    );
+  }
+  return { project, result: await api.updateMergeRequest(project, iid, body) };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ project: string, result: unknown }>} closed merge request.
+ */
+async function handleCloseMergeRequest({ api, args }) {
+  const project = requireProject(args);
+  const iid = requireInt(args, 'iid');
+  const result = await api.updateMergeRequest(project, iid, { state: 'closed' });
+  // A server that predates merge-request state support ignores the field and
+  // answers 200, so read the record back instead of trusting the status code.
+  const status = result?.status ?? result?.merge_request?.status;
+  if (status !== 'closed') {
+    throw new GitFoxError(
+      `the server accepted the request but merge request ${iid} is "${status ?? 'unknown'}", not closed; this GitFox build has no merge-request state update`,
+      { code: 'close-not-applied' },
+    );
+  }
+  return { project, result };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ project: string, result: unknown }>} merge-request comments.
+ */
+async function handleMergeRequestNotes({ api, args }) {
+  const project = requireProject(args);
+  return { project, result: await api.listMergeRequestNotes(project, requireInt(args, 'iid')) };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ project: string, result: unknown }>} created comment.
+ */
+async function handleCreateMergeRequestNote({ api, args }) {
+  const project = requireProject(args);
+  const iid = requireInt(args, 'iid');
+  requireArg(args, 'body');
+  return { project, result: await api.addMergeRequestNote(project, iid, { body: args.body }) };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ project: string, result: unknown }>} branch list.
+ */
+async function handleBranches({ api, args }) {
+  const project = requireProject(args);
+  return { project, result: await api.listBranches(project) };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ project: string, result: unknown }>} created branch.
+ */
+async function handleCreateBranch({ api, args }) {
+  const project = requireProject(args);
+  requireArg(args, 'name');
+  requireArg(args, 'ref');
+  return { project, result: await api.createBranch(project, { name: args.name, ref: args.ref }) };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ project: string, result: unknown }>} deletion result.
+ */
+async function handleDeleteBranch({ api, args }) {
+  const project = requireProject(args);
+  requireArg(args, 'branch');
+  return { project, result: await api.deleteBranch(project, args.branch) };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ project: string, result: unknown }>} commit list.
+ */
+async function handleCommits({ api, args }) {
+  const project = requireProject(args);
+  const result = await api.listCommits(project, {
+    ref: args.ref,
+    ...pageQuery(args),
+  });
+  return { project, result };
+}
+
+/**
+ * @param {{ api: object, args: Record<string, unknown> }} deps - action dependencies.
+ * @returns {Promise<{ project: string, result: unknown }>} commit detail.
+ */
+async function handleCommit({ api, args }) {
+  const project = requireProject(args);
+  requireArg(args, 'sha');
+  return { project, result: await api.getCommit(project, args.sha) };
+}
+
+/** One handler per supported tool action. */
+const ACTION_HANDLERS = {
+  status: handleStatus,
+  projects: handleProjects,
+  issues: handleIssues,
+  issue: handleIssue,
+  create_issue: handleCreateIssue,
+  update_issue: handleUpdateIssue,
+  issue_notes: handleIssueNotes,
+  create_issue_note: handleCreateIssueNote,
+  merge_requests: handleMergeRequests,
+  create_merge_request: handleCreateMergeRequest,
+  merge_merge_request: handleMergeMergeRequest,
+  update_merge_request: handleUpdateMergeRequest,
+  close_merge_request: handleCloseMergeRequest,
+  merge_request_notes: handleMergeRequestNotes,
+  create_merge_request_note: handleCreateMergeRequestNote,
+  branches: handleBranches,
+  create_branch: handleCreateBranch,
+  delete_branch: handleDeleteBranch,
+  commits: handleCommits,
+  commit: handleCommit,
+};
+
+/**
+ * Normalize one handler outcome into the canonical tool result.
+ *
+ * @param {string} action - executed action.
+ * @param {{ project?: string, result: unknown }} outcome - handler outcome.
+ * @returns {{ action: string, project?: string, result: unknown }} canonical result.
+ */
+function finalizeAction(action, outcome) {
+  const result = outcome.result ?? null;
+  if (outcome.project === undefined) return { action, result };
+  return { action, project: outcome.project, result };
+}
+
+/**
+ * Execute one DevOps action by name.
+ *
+ * @param {object} ctx - Host context.
+ * @param {object} api - GitFox client.
+ * @param {Record<string, any>} args - validated arguments.
+ * @returns {Promise<object>} canonical result.
+ */
+async function executeAction(ctx, api, args, actor) {
+  const handler = ACTION_HANDLERS[args.action];
+  if (handler === undefined) {
+    throw new GitFoxError(`unknown action "${args.action}"`, { code: 'invalid-arguments' });
+  }
+  return finalizeAction(args.action, await handler({ ctx, api, args, actor }));
+}
+
+/**
+ * Execute one action, normalizing GitFox errors into tool errors.
+ *
+ * @param {object} ctx - Host context.
+ * @param {object} api - GitFox client.
+ * @param {Record<string, any>} args - validated arguments.
+ * @returns {Promise<object>} canonical result.
+ */
+async function runAction(ctx, api, args, actor) {
+  try {
+    return await executeAction(ctx, api, args, actor);
+  } catch (error) {
+    if (error instanceof GitFoxError) {
+      throw new Error(`${error.code}: ${error.message}`, { cause: error });
+    }
+    throw error;
+  }
+}
+
+/**
+ * Build the `infinity_devops` tool definition.
+ *
+ * @param {object} ctx - Host context.
+ * @param {object} api - GitFox client.
+ * @returns {object} tool definition.
+ */
+function createTool(ctx, api) {
+  return {
+    name: 'infinity_devops',
+    description: TOOL_DESCRIPTION,
+    parameters: TOOL_PARAMETERS,
+    output: {
+      schema: { type: 'object', additionalProperties: true },
+      /**
+       * @param {unknown} _args - validated arguments.
+       * @param {unknown} value - canonical value.
+       * @returns {Array<{ type: 'text', text: string }>} model-facing content.
+       */
+      render(_args, value) {
+        return [{ type: 'text', text: formatValue(value) }];
+      },
+    },
+    /**
+     * Execute one DevOps action.
+     *
+     * @param {Record<string, any>} args - validated arguments.
+     * @param {{ signal?: AbortSignal }} exec - execution context.
+     * @returns {Promise<object>} canonical result.
+     */
+    async execute(args, exec) {
+      exec.signal?.throwIfAborted();
+      const actor = await api.resolveActor(exec.agent);
+      const result = await runAction(ctx, api, args, actor);
+      exec.signal?.throwIfAborted();
+      return result;
+    },
+  };
+}
+
+/**
+ * Add sibling-plugin actor resolution to the GitFox client.
+ *
+ * `is-fabric-team` registers a resolver that maps a live session to its team
+ * role. Without it, an ordinary Agent session gets the unrestricted
+ * `infinsys-agent` actor, which preserves pre-existing behaviour outside Team
+ * Collaboration Mode.
+ *
+ * @param {object} api - GitFox client.
+ * @returns {object} Host DevOps service.
+ */
+function createDevOpsService(api, git) {
+  const resolvers = new Set();
+  return {
+    ...api,
+    botNameFor,
+    /**
+     * Discover the GitFox project named by the workspace's origin remote.
+     *
+     * @param {string} workspaceRoot - canonical session workspace.
+     * @param {{ signal?: AbortSignal }} [options] - cancellation.
+     * @returns {Promise<{ project: string | null, remoteUrl: string | null, reason?: string }>} discovery result.
+     */
+    async discoverProject(workspaceRoot, options = {}) {
+      let remoteUrl;
+      try {
+        const remote = await git.remoteUrl(undefined, {
+          workspaceRoot,
+          signal: options.signal,
+        });
+        remoteUrl = remote.remote;
+      } catch {
+        return undiscovered('no-remote');
+      }
+      if (remoteUrl === null) return undiscovered('no-remote');
+      let config;
+      try {
+        config = await api.getConfig(options.signal === undefined ? {} : { signal: options.signal });
+      } catch {
+        return undiscovered('config-unavailable', remoteUrl);
+      }
+      const project = projectFromCloneUrl(remoteUrl, config);
+      return project === null ? undiscovered('unknown-remote', remoteUrl) : { project, remoteUrl };
+    },
+    /**
+     * Read the staged entries of one workspace's index.
+     *
+     * Sibling plugins need the index as data, not just as a commit step: the
+     * work-record gate has to know which paths a commit would put in the tree,
+     * and whether each one is an addition or a deletion.
+     *
+     * @param {string} workspaceRoot - canonical session workspace.
+     * @param {{ signal?: AbortSignal, actor?: object }} [options] - cancellation and identity.
+     * @returns {Promise<{ path: string, status: string }[]>} staged entries.
+     */
+    async stagedFiles(workspaceRoot, options = {}) {
+      if (typeof workspaceRoot !== 'string' || workspaceRoot === '') return [];
+      return git.stagedFiles(options.actor, {
+        workspaceRoot,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+      });
+    },
+    /**
+     * @param {object} [agent] - live Agent.
+     * @returns {Promise<object>} resolved actor record.
+     */
+    async resolveActor(agent) {
+      for (const resolver of [...resolvers].reverse()) {
+        const actor = await resolver(agent);
+        if (actor !== undefined && actor !== null) return normalizeActorRecord(actor);
+      }
+      return defaultActorRecord();
+    },
+    /**
+     * @param {(agent?: object) => object | undefined | Promise<object | undefined>} resolver - actor resolver.
+     * @returns {() => void} disposer.
+     */
+    registerActorResolver(resolver) {
+      if (typeof resolver !== 'function') {
+        throw new TypeError('actor resolver must be a function');
+      }
+      resolvers.add(resolver);
+      return () => resolvers.delete(resolver);
+    },
+  };
+}
+
+/**
+ * Host plugin body.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx - Host context.
+ * @returns {void}
+ */
+export function apply(ctx) {
+  const git = createGitRepository({ resolveConfig: () => resolveGitFoxConfig(ctx) });
+  const api = createDevOpsService(
+    createGitFoxClient({ resolveConfig: () => resolveGitFoxConfig(ctx) }),
+    git,
+  );
+  ctx.provide('infinityDevOps', api);
+  registerProxyRoutes(ctx);
+  ctx.effect(() => ctx.tools.register(createTool(ctx, api)), 'is-devops: infinity_devops tool');
+  ctx.effect(
+    () => ctx.tools.register(createGitTool({ git, resolveActor: api.resolveActor })),
+    'is-devops: infinity_git tool',
+  );
+}
+
+/** Services required by the Host half. */
+export const inject = ['infinitySettings', 'webServer', 'tools'];
+
+/** Re-exported for tests and sibling packages that resolve this module directly. */
+export { withQuery };