@enbox/gitd 0.0.1

package/src/github-shim/pulls.ts

@@ -0,0 +1,500 @@
+/**
+ * GitHub API shim — `/repos/:did/:repo/pulls` endpoints.
+ *
+ * Maps DWN patch records to GitHub REST API v3 pull request responses.
+ *
+ * Endpoints:
+ *   GET   /repos/:did/:repo/pulls                    List pull requests
+ *   GET   /repos/:did/:repo/pulls/:number            Pull request detail
+ *   GET   /repos/:did/:repo/pulls/:number/reviews    Pull request reviews
+ *   POST  /repos/:did/:repo/pulls                    Create pull request
+ *   PATCH /repos/:did/:repo/pulls/:number            Update pull request
+ *   PUT   /repos/:did/:repo/pulls/:number/merge      Merge pull request
+ *   POST  /repos/:did/:repo/pulls/:number/reviews    Create review
+ *
+ * Status mapping:
+ *   - `open`   -> state: "open"
+ *   - `closed` -> state: "closed", merged: false
+ *   - `merged` -> state: "closed", merged: true
+ *
+ * @module
+ */
+
+import type { AgentContext } from '../cli/agent.js';
+import type { JsonResponse } from './helpers.js';
+
+import { DateSort } from '@enbox/dwn-sdk-js';
+
+import {
+  buildApiUrl,
+  buildLinkHeader,
+  buildOwner,
+  fromOpt,
+  getNextPatchNumber,
+  getRepoRecord,
+  jsonCreated,
+  jsonMethodNotAllowed,
+  jsonNotFound,
+  jsonOk,
+  jsonValidationError,
+  numericId,
+  paginate,
+  parsePagination,
+  toISODate,
+} from './helpers.js';
+
+// ---------------------------------------------------------------------------
+// Verdict -> GitHub review state mapping
+// ---------------------------------------------------------------------------
+
+const VERDICT_MAP: Record<string, string> = {
+  approve : 'APPROVED',
+  reject  : 'CHANGES_REQUESTED',
+  comment : 'COMMENTED',
+};
+
+// ---------------------------------------------------------------------------
+// Pull request object builder
+// ---------------------------------------------------------------------------
+
+function buildPullResponse(
+  rec: any, data: any, tags: Record<string, string>,
+  targetDid: string, repoName: string, baseUrl: string,
+): Record<string, unknown> {
+  const owner = buildOwner(targetDid, baseUrl);
+  const number = parseInt(tags.number ?? data.number ?? '0', 10);
+  const dwnStatus = tags.status ?? 'open';
+  const merged = dwnStatus === 'merged';
+  const state = dwnStatus === 'open' ? 'open' : 'closed';
+  const baseBranch = tags.baseBranch ?? 'main';
+  const headBranch = tags.headBranch ?? '';
+
+  return {
+    id                  : numericId(rec.id ?? ''),
+    node_id             : rec.id ?? '',
+    url                 : `${baseUrl}/repos/${targetDid}/${repoName}/pulls/${number}`,
+    html_url            : `${baseUrl}/repos/${targetDid}/${repoName}/pulls/${number}`,
+    diff_url            : `${baseUrl}/repos/${targetDid}/${repoName}/pulls/${number}.diff`,
+    patch_url           : `${baseUrl}/repos/${targetDid}/${repoName}/pulls/${number}.patch`,
+    issue_url           : `${baseUrl}/repos/${targetDid}/${repoName}/issues/${number}`,
+    commits_url         : `${baseUrl}/repos/${targetDid}/${repoName}/pulls/${number}/commits`,
+    review_comments_url : `${baseUrl}/repos/${targetDid}/${repoName}/pulls/${number}/comments`,
+    comments_url        : `${baseUrl}/repos/${targetDid}/${repoName}/issues/${number}/comments`,
+    number,
+    title               : data.title ?? '',
+    body                : data.body ?? null,
+    state,
+    locked              : false,
+    merged,
+    mergeable           : state === 'open' ? true : null,
+    merge_commit_sha    : merged ? '0000000000000000000000000000000000000000' : null,
+    merged_at           : merged ? toISODate(rec.timestamp) : null,
+    merged_by           : merged ? owner : null,
+    created_at          : toISODate(rec.dateCreated),
+    updated_at          : toISODate(rec.timestamp),
+    closed_at           : state === 'closed' ? toISODate(rec.timestamp) : null,
+    user                : owner,
+    author_association  : 'OWNER',
+    draft               : false,
+    head                : {
+      label : `${targetDid}:${headBranch}`,
+      ref   : headBranch,
+      sha   : '',
+    },
+    base: {
+      label : `${targetDid}:${baseBranch}`,
+      ref   : baseBranch,
+      sha   : '',
+    },
+    labels              : [],
+    assignees           : [],
+    milestone           : null,
+    requested_reviewers : [],
+    commits             : 0,
+    additions           : 0,
+    deletions           : 0,
+    changed_files       : 0,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// GET /repos/:did/:repo/pulls
+// ---------------------------------------------------------------------------
+
+export async function handleListPulls(
+  ctx: AgentContext, targetDid: string, repoName: string, url: URL,
+): Promise<JsonResponse> {
+  const repo = await getRepoRecord(ctx, targetDid);
+  if (!repo) {
+    return jsonNotFound(`Repository '${repoName}' not found for DID '${targetDid}'.`);
+  }
+
+  const from = fromOpt(ctx, targetDid);
+  const baseUrl = buildApiUrl(url);
+
+  const stateFilter = url.searchParams.get('state') ?? 'open';
+  const direction = url.searchParams.get('direction') ?? 'desc';
+  const pagination = parsePagination(url);
+
+  const dateSort = direction === 'asc'
+    ? DateSort.CreatedAscending
+    : DateSort.CreatedDescending;
+
+  const { records } = await ctx.patches.records.query('repo/patch', {
+    from,
+    filter: { contextId: repo.contextId },
+    dateSort,
+  });
+
+  // Filter by state — GitHub treats `closed` as "closed or merged".
+  let filtered = records;
+  if (stateFilter !== 'all') {
+    filtered = records.filter((r) => {
+      const t = r.tags as Record<string, string> | undefined;
+      const s = t?.status ?? 'open';
+      if (stateFilter === 'open') { return s === 'open'; }
+      // 'closed' includes both closed and merged.
+      return s === 'closed' || s === 'merged';
+    });
+  }
+
+  const page = paginate(filtered, pagination);
+
+  const items: Record<string, unknown>[] = [];
+  for (const rec of page) {
+    const data = await rec.data.json();
+    const tags = (rec.tags as Record<string, string> | undefined) ?? {};
+    items.push(buildPullResponse(rec, data, tags, targetDid, repoName, baseUrl));
+  }
+
+  const linkHeader = buildLinkHeader(
+    baseUrl, `/repos/${targetDid}/${repoName}/pulls`,
+    pagination.page, pagination.perPage, filtered.length,
+  );
+  const extraHeaders: Record<string, string> = {};
+  if (linkHeader) { extraHeaders['Link'] = linkHeader; }
+
+  return jsonOk(items, extraHeaders);
+}
+
+// ---------------------------------------------------------------------------
+// GET /repos/:did/:repo/pulls/:number
+// ---------------------------------------------------------------------------
+
+export async function handleGetPull(
+  ctx: AgentContext, targetDid: string, repoName: string, number: string, url: URL,
+): Promise<JsonResponse> {
+  const repo = await getRepoRecord(ctx, targetDid);
+  if (!repo) {
+    return jsonNotFound(`Repository '${repoName}' not found for DID '${targetDid}'.`);
+  }
+
+  const from = fromOpt(ctx, targetDid);
+  const baseUrl = buildApiUrl(url);
+
+  const { records } = await ctx.patches.records.query('repo/patch', {
+    from,
+    filter: { contextId: repo.contextId, tags: { number } },
+  });
+
+  if (records.length === 0) {
+    return jsonNotFound(`Pull request #${number} not found.`);
+  }
+
+  const rec = records[0];
+  const data = await rec.data.json();
+  const tags = (rec.tags as Record<string, string> | undefined) ?? {};
+
+  return jsonOk(buildPullResponse(rec, data, tags, targetDid, repoName, baseUrl));
+}
+
+// ---------------------------------------------------------------------------
+// GET /repos/:did/:repo/pulls/:number/reviews
+// ---------------------------------------------------------------------------
+
+export async function handleListPullReviews(
+  ctx: AgentContext, targetDid: string, repoName: string, number: string, url: URL,
+): Promise<JsonResponse> {
+  const repo = await getRepoRecord(ctx, targetDid);
+  if (!repo) {
+    return jsonNotFound(`Repository '${repoName}' not found for DID '${targetDid}'.`);
+  }
+
+  const from = fromOpt(ctx, targetDid);
+  const baseUrl = buildApiUrl(url);
+  const pagination = parsePagination(url);
+
+  // Find the patch first.
+  const { records: patches } = await ctx.patches.records.query('repo/patch', {
+    from,
+    filter: { contextId: repo.contextId, tags: { number } },
+  });
+
+  if (patches.length === 0) {
+    return jsonNotFound(`Pull request #${number} not found.`);
+  }
+
+  const patchRec = patches[0];
+  const owner = buildOwner(targetDid, baseUrl);
+
+  // Fetch reviews.
+  const { records: reviews } = await ctx.patches.records.query('repo/patch/review' as any, {
+    from,
+    filter   : { contextId: patchRec.contextId },
+    dateSort : DateSort.CreatedAscending,
+  });
+
+  const paged = paginate(reviews, pagination);
+
+  const items: Record<string, unknown>[] = [];
+  for (const review of paged) {
+    const rData = await review.data.json();
+    const rTags = (review.tags as Record<string, string> | undefined) ?? {};
+    const verdict = rTags.verdict ?? 'comment';
+
+    items.push({
+      id                 : numericId(review.id ?? ''),
+      node_id            : review.id ?? '',
+      user               : owner,
+      body               : rData.body ?? '',
+      state              : VERDICT_MAP[verdict] ?? 'COMMENTED',
+      html_url           : `${baseUrl}/repos/${targetDid}/${repoName}/pulls/${number}#pullrequestreview-${numericId(review.id ?? '')}`,
+      pull_request_url   : `${baseUrl}/repos/${targetDid}/${repoName}/pulls/${number}`,
+      submitted_at       : toISODate(review.dateCreated),
+      commit_id          : '',
+      author_association : 'OWNER',
+    });
+  }
+
+  const linkHeader = buildLinkHeader(
+    baseUrl, `/repos/${targetDid}/${repoName}/pulls/${number}/reviews`,
+    pagination.page, pagination.perPage, reviews.length,
+  );
+  const extraHeaders: Record<string, string> = {};
+  if (linkHeader) { extraHeaders['Link'] = linkHeader; }
+
+  return jsonOk(items, extraHeaders);
+}
+
+// ---------------------------------------------------------------------------
+// POST /repos/:did/:repo/pulls — create pull request
+// ---------------------------------------------------------------------------
+
+export async function handleCreatePull(
+  ctx: AgentContext, targetDid: string, repoName: string,
+  reqBody: Record<string, unknown>, url: URL,
+): Promise<JsonResponse> {
+  const repo = await getRepoRecord(ctx, targetDid);
+  if (!repo) {
+    return jsonNotFound(`Repository '${repoName}' not found for DID '${targetDid}'.`);
+  }
+
+  const title = reqBody.title as string | undefined;
+  if (!title) {
+    return jsonValidationError('Validation Failed: title is required.');
+  }
+
+  const body = (reqBody.body as string) ?? '';
+  const baseBranch = (reqBody.base as string) ?? 'main';
+  const headBranch = (reqBody.head as string) ?? '';
+  const baseUrl = buildApiUrl(url);
+  const number = await getNextPatchNumber(ctx, repo.contextId);
+
+  const tags: Record<string, string> = {
+    status : 'open',
+    baseBranch,
+    number : String(number),
+  };
+  if (headBranch) { tags.headBranch = headBranch; }
+
+  const { status, record } = await ctx.patches.records.create('repo/patch', {
+    data            : { title, body, number },
+    tags,
+    parentContextId : repo.contextId,
+  });
+
+  if (status.code >= 300) {
+    return jsonValidationError(`Failed to create pull request: ${status.detail}`);
+  }
+
+  const recTags = (record.tags as Record<string, string> | undefined) ?? {};
+  const data = await record.data.json();
+  const pr = buildPullResponse(record, data, recTags, targetDid, repoName, baseUrl);
+
+  return jsonCreated(pr);
+}
+
+// ---------------------------------------------------------------------------
+// PATCH /repos/:did/:repo/pulls/:number — update pull request
+// ---------------------------------------------------------------------------
+
+export async function handleUpdatePull(
+  ctx: AgentContext, targetDid: string, repoName: string,
+  number: string, reqBody: Record<string, unknown>, url: URL,
+): Promise<JsonResponse> {
+  const repo = await getRepoRecord(ctx, targetDid);
+  if (!repo) {
+    return jsonNotFound(`Repository '${repoName}' not found for DID '${targetDid}'.`);
+  }
+
+  const baseUrl = buildApiUrl(url);
+
+  const { records } = await ctx.patches.records.query('repo/patch', {
+    filter: { contextId: repo.contextId, tags: { number } },
+  });
+
+  if (records.length === 0) {
+    return jsonNotFound(`Pull request #${number} not found.`);
+  }
+
+  const rec = records[0];
+  const data = await rec.data.json();
+  const tags = (rec.tags as Record<string, string> | undefined) ?? {};
+
+  // Apply updates.
+  const newTitle = (reqBody.title as string | undefined) ?? data.title;
+  const newBody = (reqBody.body as string | undefined) ?? data.body;
+  const newBase = (reqBody.base as string | undefined) ?? tags.baseBranch;
+
+  // GitHub API uses "state" (open/closed), DWN uses "status" tag.
+  let newStatus = tags.status ?? 'open';
+  if (reqBody.state === 'closed') { newStatus = 'closed'; }
+  if (reqBody.state === 'open') { newStatus = 'open'; }
+
+  const newTags: Record<string, string> = { ...tags, status: newStatus };
+  if (newBase) { newTags.baseBranch = newBase; }
+
+  const { status } = await rec.update({
+    data : { title: newTitle, body: newBody, number: data.number },
+    tags : newTags,
+  });
+
+  if (status.code >= 300) {
+    return jsonValidationError(`Failed to update pull request: ${status.detail}`);
+  }
+
+  const updatedData = { title: newTitle, body: newBody, number: data.number };
+  const pr = buildPullResponse(rec, updatedData, newTags, targetDid, repoName, baseUrl);
+
+  return jsonOk(pr);
+}
+
+// ---------------------------------------------------------------------------
+// PUT /repos/:did/:repo/pulls/:number/merge — merge pull request
+// ---------------------------------------------------------------------------
+
+export async function handleMergePull(
+  ctx: AgentContext, targetDid: string, repoName: string,
+  number: string, reqBody: Record<string, unknown>, _url: URL,
+): Promise<JsonResponse> {
+  const repo = await getRepoRecord(ctx, targetDid);
+  if (!repo) {
+    return jsonNotFound(`Repository '${repoName}' not found for DID '${targetDid}'.`);
+  }
+
+  const { records } = await ctx.patches.records.query('repo/patch', {
+    filter: { contextId: repo.contextId, tags: { number } },
+  });
+
+  if (records.length === 0) {
+    return jsonNotFound(`Pull request #${number} not found.`);
+  }
+
+  const rec = records[0];
+  const data = await rec.data.json();
+  const tags = (rec.tags as Record<string, string> | undefined) ?? {};
+
+  if (tags.status === 'merged') {
+    return jsonMethodNotAllowed(`Pull request #${number} is already merged.`);
+  }
+
+  if (tags.status === 'closed') {
+    return jsonMethodNotAllowed(`Pull request #${number} is closed. Reopen it before merging.`);
+  }
+
+  // Update the patch status to merged.
+  const mergeStrategy = (reqBody.merge_method as string) ?? 'merge';
+
+  const { status } = await rec.update({
+    data : data,
+    tags : { ...tags, status: 'merged' },
+  });
+
+  if (status.code >= 300) {
+    return jsonValidationError(`Failed to merge pull request: ${status.detail}`);
+  }
+
+  // Create a merge result record.
+  await ctx.patches.records.create('repo/patch/mergeResult' as any, {
+    data            : { mergedBy: ctx.did },
+    tags            : { mergeCommit: 'pending', strategy: mergeStrategy },
+    parentContextId : rec.contextId,
+  } as any);
+
+  // GitHub returns a merge result object.
+  return jsonOk({
+    sha     : '0000000000000000000000000000000000000000',
+    merged  : true,
+    message : `Pull request #${number} merged successfully.`,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// POST /repos/:did/:repo/pulls/:number/reviews — create review
+// ---------------------------------------------------------------------------
+
+export async function handleCreatePullReview(
+  ctx: AgentContext, targetDid: string, repoName: string,
+  number: string, reqBody: Record<string, unknown>, url: URL,
+): Promise<JsonResponse> {
+  const repo = await getRepoRecord(ctx, targetDid);
+  if (!repo) {
+    return jsonNotFound(`Repository '${repoName}' not found for DID '${targetDid}'.`);
+  }
+
+  const baseUrl = buildApiUrl(url);
+
+  // Find the patch.
+  const { records: patches } = await ctx.patches.records.query('repo/patch', {
+    filter: { contextId: repo.contextId, tags: { number } },
+  });
+
+  if (patches.length === 0) {
+    return jsonNotFound(`Pull request #${number} not found.`);
+  }
+
+  const patchRec = patches[0];
+  const reviewBody = (reqBody.body as string) ?? '';
+
+  // GitHub API uses "event" field: APPROVE, REQUEST_CHANGES, COMMENT.
+  // Map to DWN verdict tags.
+  const event = (reqBody.event as string | undefined)?.toUpperCase() ?? 'COMMENT';
+  let verdict = 'comment';
+  if (event === 'APPROVE') { verdict = 'approve'; }
+  if (event === 'REQUEST_CHANGES') { verdict = 'reject'; }
+
+  const { status, record: reviewRec } = await ctx.patches.records.create('repo/patch/review' as any, {
+    data            : { body: reviewBody },
+    tags            : { verdict },
+    parentContextId : patchRec.contextId,
+  } as any);
+
+  if (status.code >= 300) {
+    return jsonValidationError(`Failed to create review: ${status.detail}`);
+  }
+
+  const owner = buildOwner(targetDid, baseUrl);
+
+  return jsonCreated({
+    id                 : numericId(reviewRec.id ?? ''),
+    node_id            : reviewRec.id ?? '',
+    user               : owner,
+    body               : reviewBody,
+    state              : VERDICT_MAP[verdict] ?? 'COMMENTED',
+    html_url           : `${baseUrl}/repos/${targetDid}/${repoName}/pulls/${number}#pullrequestreview-${numericId(reviewRec.id ?? '')}`,
+    pull_request_url   : `${baseUrl}/repos/${targetDid}/${repoName}/pulls/${number}`,
+    submitted_at       : toISODate(reviewRec.dateCreated),
+    commit_id          : '',
+    author_association : 'OWNER',
+  });
+}

package/src/github-shim/releases.ts

@@ -0,0 +1,185 @@
+/**
+ * GitHub API shim — `/repos/:did/:repo/releases` endpoints.
+ *
+ * Maps DWN release records to GitHub REST API v3 release responses.
+ *
+ * Endpoints:
+ *   GET  /repos/:did/:repo/releases            List releases
+ *   GET  /repos/:did/:repo/releases/tags/:tag  Release by tag name
+ *   POST /repos/:did/:repo/releases            Create release
+ *
+ * @module
+ */
+
+import type { AgentContext } from '../cli/agent.js';
+import type { JsonResponse } from './helpers.js';
+
+import { DateSort } from '@enbox/dwn-sdk-js';
+
+import {
+  buildApiUrl,
+  buildLinkHeader,
+  buildOwner,
+  fromOpt,
+  getRepoRecord,
+  jsonCreated,
+  jsonNotFound,
+  jsonOk,
+  jsonValidationError,
+  numericId,
+  paginate,
+  parsePagination,
+  toISODate,
+} from './helpers.js';
+
+// ---------------------------------------------------------------------------
+// Release object builder
+// ---------------------------------------------------------------------------
+
+function buildReleaseResponse(
+  rec: any, data: any, tags: Record<string, unknown>,
+  targetDid: string, repoName: string, baseUrl: string,
+): Record<string, unknown> {
+  const owner = buildOwner(targetDid, baseUrl);
+  const tagName = (tags.tagName as string) ?? '';
+  const prerelease = tags.prerelease === true;
+  const draft = tags.draft === true;
+  const id = numericId(rec.id ?? '');
+
+  return {
+    id,
+    node_id          : rec.id ?? '',
+    url              : `${baseUrl}/repos/${targetDid}/${repoName}/releases/${id}`,
+    html_url         : `${baseUrl}/repos/${targetDid}/${repoName}/releases/tags/${tagName}`,
+    assets_url       : `${baseUrl}/repos/${targetDid}/${repoName}/releases/${id}/assets`,
+    upload_url       : `${baseUrl}/repos/${targetDid}/${repoName}/releases/${id}/assets{?name,label}`,
+    tarball_url      : `${baseUrl}/repos/${targetDid}/${repoName}/tarball/${tagName}`,
+    zipball_url      : `${baseUrl}/repos/${targetDid}/${repoName}/zipball/${tagName}`,
+    tag_name         : tagName,
+    target_commitish : 'main',
+    name             : data.name ?? tagName,
+    body             : data.body ?? '',
+    draft,
+    prerelease,
+    created_at       : toISODate(rec.dateCreated),
+    published_at     : toISODate(rec.dateCreated),
+    author           : owner,
+    assets           : [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// GET /repos/:did/:repo/releases
+// ---------------------------------------------------------------------------
+
+export async function handleListReleases(
+  ctx: AgentContext, targetDid: string, repoName: string, url: URL,
+): Promise<JsonResponse> {
+  const repo = await getRepoRecord(ctx, targetDid);
+  if (!repo) {
+    return jsonNotFound(`Repository '${repoName}' not found for DID '${targetDid}'.`);
+  }
+
+  const from = fromOpt(ctx, targetDid);
+  const baseUrl = buildApiUrl(url);
+  const pagination = parsePagination(url);
+
+  const { records } = await ctx.releases.records.query('repo/release' as any, {
+    from,
+    filter   : { contextId: repo.contextId },
+    dateSort : DateSort.CreatedDescending,
+  });
+
+  const paged = paginate(records, pagination);
+
+  const items: Record<string, unknown>[] = [];
+  for (const rec of paged) {
+    const data = await rec.data.json();
+    const tags = (rec.tags as Record<string, unknown> | undefined) ?? {};
+    items.push(buildReleaseResponse(rec, data, tags, targetDid, repoName, baseUrl));
+  }
+
+  const linkHeader = buildLinkHeader(
+    baseUrl, `/repos/${targetDid}/${repoName}/releases`,
+    pagination.page, pagination.perPage, records.length,
+  );
+  const extraHeaders: Record<string, string> = {};
+  if (linkHeader) { extraHeaders['Link'] = linkHeader; }
+
+  return jsonOk(items, extraHeaders);
+}
+
+// ---------------------------------------------------------------------------
+// GET /repos/:did/:repo/releases/tags/:tag
+// ---------------------------------------------------------------------------
+
+export async function handleGetReleaseByTag(
+  ctx: AgentContext, targetDid: string, repoName: string, tag: string, url: URL,
+): Promise<JsonResponse> {
+  const repo = await getRepoRecord(ctx, targetDid);
+  if (!repo) {
+    return jsonNotFound(`Repository '${repoName}' not found for DID '${targetDid}'.`);
+  }
+
+  const from = fromOpt(ctx, targetDid);
+  const baseUrl = buildApiUrl(url);
+
+  const { records } = await ctx.releases.records.query('repo/release' as any, {
+    from,
+    filter: { contextId: repo.contextId, tags: { tagName: tag } },
+  });
+
+  if (records.length === 0) {
+    return jsonNotFound(`Release with tag '${tag}' not found.`);
+  }
+
+  const rec = records[0];
+  const data = await rec.data.json();
+  const tags = (rec.tags as Record<string, unknown> | undefined) ?? {};
+
+  return jsonOk(buildReleaseResponse(rec, data, tags, targetDid, repoName, baseUrl));
+}
+
+// ---------------------------------------------------------------------------
+// POST /repos/:did/:repo/releases — create release
+// ---------------------------------------------------------------------------
+
+export async function handleCreateRelease(
+  ctx: AgentContext, targetDid: string, repoName: string,
+  reqBody: Record<string, unknown>, url: URL,
+): Promise<JsonResponse> {
+  const repo = await getRepoRecord(ctx, targetDid);
+  if (!repo) {
+    return jsonNotFound(`Repository '${repoName}' not found for DID '${targetDid}'.`);
+  }
+
+  const tagName = reqBody.tag_name as string | undefined;
+  if (!tagName) {
+    return jsonValidationError('Validation Failed: tag_name is required.');
+  }
+
+  const name = (reqBody.name as string) ?? tagName;
+  const body = (reqBody.body as string) ?? '';
+  const baseUrl = buildApiUrl(url);
+
+  const tags: Record<string, unknown> = { tagName };
+  if (reqBody.target_commitish) { tags.commitSha = reqBody.target_commitish; }
+  if (reqBody.prerelease === true) { tags.prerelease = true; }
+  if (reqBody.draft === true) { tags.draft = true; }
+
+  const { status, record } = await ctx.releases.records.create('repo/release' as any, {
+    data            : { name, body },
+    tags,
+    parentContextId : repo.contextId,
+  } as any);
+
+  if (status.code >= 300) {
+    return jsonValidationError(`Failed to create release: ${status.detail}`);
+  }
+
+  const recTags = (record.tags as Record<string, unknown> | undefined) ?? {};
+  const data = await record.data.json();
+  const release = buildReleaseResponse(record, data, recTags, targetDid, repoName, baseUrl);
+
+  return jsonCreated(release);
+}