feat(ui): forge user lookup — assignee combobox, @-mentions, repo-scoped user search

Repo-scoped assignable-user search for GitHub, GitLab, and Gitea, surfaced as
an assignee combobox in the metadata editor and @-mention autocomplete in
forge comment/reply/review surfaces.

- server: GET /api/{provider}/users/search (assignees / project members),
  query + directory/override repo resolution, 429 -> 503, connected:false
  degradation; GitLab assignee writes resolve login -> ID server-side
- wire: searchUsers (+ searchLabels/milestones/branches/tags) on the three
  API clients with tests
- facade: userSearch capability (all three), searchUsers adapters,
  mapGithubAssignee/mapGitlabMember/mapGiteaAssignee -> ForgeUser
- ui: ForgeLookupCombobox (keyboard nav, debounced 30s-TTL cache,
  connected-only caching), ForgeMentionTextarea (@ token parsing, caret
  restore), free-text fallback when lookup is unavailable; i18n in 12 locales
- extras sharing the same infrastructure: GitLab create-issue dialog and
  label/milestone/branch/tag lookups in the metadata editor

packages/web/server/lib/gitea/DOCUMENTATION.md

@@ -107,6 +107,7 @@
 | PATCH | `/api/gitea/pr/update` | body `{ directory, number, title?, description?, state? }` -> `{ connected, repo?, pr }`; `404` when the PR does not exist |
 | POST | `/api/gitea/pr/merge` | body `{ directory, number, method? }` -> `{ connected, merged: true }` on success; non-mergeable PRs -> the Gitea status (`405`/`409`/`422`) with `{ connected, merged: false, message }` |
 | POST | `/api/gitea/issues/comment` | body `{ directory, number, body, owner?, repo? }` -> `{ connected, repo?, comment }` |
+| POST | `/api/gitea/issues/create` | body `{ directory, title, body?, labels?, owner?, repo? }` -> `{ connected, repo?, issue }` |
 | PATCH | `/api/gitea/issues/update` | body `{ directory, number, title?, body?, state?, labels?, assignees?, milestone?, owner?, repo? }` -> `{ connected, repo?, issue }`; `400 'Milestone not found'` when a milestone title does not match |
 | POST | `/api/gitea/prs/comment` | body `{ directory, number, body, owner?, repo? }` -> `{ connected, repo?, comment }` (PRs are issues at the API level, so the PR number is the issue index) |
 | POST | `/api/gitea/prs/review` | body `{ directory, number, event, body?, owner?, repo? }` -> `{ connected, repo?, review }`; `400` when `event` is not `APPROVED`/`REQUEST_CHANGES`/`COMMENT` |

packages/web/server/lib/gitea/client.js

@@ -265,6 +265,8 @@ export function createGiteaClient({ token, baseUrl }) {
       request(`/repos/${owner}/${repo}/issues/${number}/comments`, { query: params }),
     createIssueComment: (owner, repo, number, body) =>
       request(`/repos/${owner}/${repo}/issues/${number}/comments`, { method: 'POST', body: { body } }),
+    createIssue: (owner, repo, params) =>
+      request(`/repos/${owner}/${repo}/issues`, { method: 'POST', body: params }),
     updateIssue: (owner, repo, number, params) =>
       request(`/repos/${owner}/${repo}/issues/${number}`, { method: 'PATCH', body: params }),
     milestones: (owner, repo, params = {}) =>
@@ -295,6 +297,12 @@ export function createGiteaClient({ token, baseUrl }) {
       request(`/repos/${owner}/${repo}/pulls/${number}/merge`, { method: 'POST', body }),
     branches: (owner, repo, params = {}) =>
       request(`/repos/${owner}/${repo}/branches`, { query: params }),
+    // Assignable users (collaborators with role access + org members) are the
+    // mention/assign candidate set; Gitea mirrors the GitHub assignees route.
+    assignees: (owner, repo, params = {}) =>
+      request(`/repos/${owner}/${repo}/assignees`, { query: params }),
+    tags: (owner, repo, params = {}) =>
+      request(`/repos/${owner}/${repo}/tags`, { query: params }),
   };
 }
 

packages/web/server/lib/gitea/routes.js

@@ -569,6 +569,60 @@ export function registerGiteaRoutes(app, options = {}) {
     }
   });
 
+  app.post('/api/gitea/issues/create', async (req, res) => {
+    try {
+      const directory = asString(req.body?.directory);
+      const title = typeof req.body?.title === 'string' ? req.body.title.trim() : '';
+      if (!directory || !title) {
+        return res.status(400).json({ error: 'directory and title are required' });
+      }
+      const body = typeof req.body?.body === 'string' ? req.body.body.trim() : undefined;
+      const labels = Array.isArray(req.body?.labels)
+        ? req.body.labels.filter((label) => typeof label === 'string' && label.length > 0)
+        : undefined;
+
+      const client = await getClient();
+      if (!client) {
+        return res.json({ connected: false });
+      }
+
+      const requestedRepo = getRequestedRepo(req);
+      const { owner, repo, repoRef } = await resolveRepoForRequest(directory, requestedRepo);
+      if (!owner || !repo) {
+        return res.status(400).json({ error: 'Unable to resolve Gitea repo from directory' });
+      }
+
+      const params = {
+        title,
+        ...(body !== undefined ? { body } : {}),
+        ...(labels !== undefined ? { labels } : {}),
+      };
+      const resp = await client.createIssue(owner, repo, params);
+      if (resp.status === 429) {
+        return res.status(503).json({ error: 'Gitea rate limited' });
+      }
+      if (resp.status === 403) {
+        return res.status(400).json({ error: 'Your Gitea token needs write:repository scope to create issues' });
+      }
+      if (resp.status !== 200 && resp.status !== 201) {
+        const status = resp.status >= 500 ? 500 : 400;
+        return res.status(status).json({ error: giteaErrorMessage(resp.data) || 'Gitea returned an error while creating the issue' });
+      }
+      if (!resp.data) {
+        return res.status(500).json({ error: 'Gitea returned an empty response while creating the issue' });
+      }
+
+      return res.json({
+        connected: true,
+        repo: repoRef || repoRefFromOwnerRepo(owner, repo, client.baseUrl),
+        issue: mapGiteaIssue(resp.data),
+      });
+    } catch (error) {
+      console.error('Failed to create Gitea issue:', error);
+      return res.status(500).json({ error: error.message || 'Failed to create Gitea issue' });
+    }
+  });
+
   app.patch('/api/gitea/issues/update', async (req, res) => {
     try {
       const directory = asString(req.body?.directory);
@@ -1418,4 +1472,217 @@ export function registerGiteaRoutes(app, options = {}) {
       return res.status(500).json({ error: error.message || 'Failed to fetch Gitea repo labels' });
     }
   });
+
+  // ================= Gitea Rich Lookup APIs =================
+
+  // Repo-scoped lookups for pickers/mentions. Each resolves the target repo
+  // (directory remote + owner/repo override) and hits a Gitea endpoint that
+  // does not support server-side search, then filters client-side
+  // (case-insensitive substring on the primary field). `connected: false`
+  // means the lookup could not be performed — never an authoritative empty list.
+
+  const lookupRepo = async (req) => {
+    const directory = asString(req.query?.directory);
+    const requestedRepo = getRequestedRepo(req);
+    if (!directory && !requestedRepo) {
+      return { error: 'directory or owner/repo is required' };
+    }
+    const client = await getClient();
+    if (!client) {
+      return { client: null };
+    }
+    const { owner, repo, repoRef } = await resolveRepoForRequest(directory, requestedRepo);
+    return { client, owner, repo, repoRef };
+  };
+
+  app.get('/api/gitea/users/search', async (req, res) => {
+    try {
+      const query = asString(req.query?.query);
+      const resolved = await lookupRepo(req);
+      if (resolved.error) {
+        return res.status(400).json({ error: resolved.error });
+      }
+      if (!resolved.client) {
+        return res.json({ connected: false, users: [] });
+      }
+      const { client, owner, repo, repoRef } = resolved;
+      if (!owner || !repo) {
+        return res.json({ connected: true, repo: null, users: [] });
+      }
+
+      const resp = await withTimeout(client.assignees(owner, repo, { limit: 100 }), ROUTE_TIMEOUT_MS, 'gitea users search');
+      if (resp.status === 429) {
+        return res.status(503).json({ error: 'Gitea rate limited' });
+      }
+      if (resp.status !== 200) {
+        return res.status(502).json({ error: 'Gitea returned an error while searching users' });
+      }
+      const needle = query.toLowerCase();
+      const users = (Array.isArray(resp.data) ? resp.data : [])
+        .map(mapGiteaUser)
+        .filter((user) => user && user.username)
+        .filter((user) => !needle || user.username.toLowerCase().includes(needle) || (user.name || '').toLowerCase().includes(needle));
+
+      return res.json({ connected: true, repo: repoRef || repoRefFromOwnerRepo(owner, repo, client.baseUrl), users });
+    } catch (error) {
+      console.error('Failed to search Gitea users:', error);
+      return res.status(500).json({ error: error.message || 'Failed to search Gitea users' });
+    }
+  });
+
+  app.get('/api/gitea/labels/search', async (req, res) => {
+    try {
+      const query = asString(req.query?.query);
+      const resolved = await lookupRepo(req);
+      if (resolved.error) {
+        return res.status(400).json({ error: resolved.error });
+      }
+      if (!resolved.client) {
+        return res.json({ connected: false, labels: [] });
+      }
+      const { client, owner, repo, repoRef } = resolved;
+      if (!owner || !repo) {
+        return res.json({ connected: true, repo: null, labels: [] });
+      }
+
+      const resp = await withTimeout(client.repoLabels(owner, repo, { limit: 100 }), ROUTE_TIMEOUT_MS, 'gitea labels search');
+      if (resp.status === 429) {
+        return res.status(503).json({ error: 'Gitea rate limited' });
+      }
+      if (resp.status !== 200) {
+        return res.status(502).json({ error: 'Gitea returned an error while searching labels' });
+      }
+      const needle = query.toLowerCase();
+      const labels = (Array.isArray(resp.data) ? resp.data : [])
+        .map((label) => ({
+          ...(typeof label.id === 'number' ? { id: label.id } : {}),
+          name: typeof label.name === 'string' ? label.name : '',
+          ...(typeof label.color === 'string' ? { color: label.color } : {}),
+          ...(typeof label.description === 'string' ? { description: label.description } : {}),
+        }))
+        .filter((label) => label.name && (!needle || label.name.toLowerCase().includes(needle)));
+
+      return res.json({ connected: true, repo: repoRef || repoRefFromOwnerRepo(owner, repo, client.baseUrl), labels });
+    } catch (error) {
+      console.error('Failed to search Gitea labels:', error);
+      return res.status(500).json({ error: error.message || 'Failed to search Gitea labels' });
+    }
+  });
+
+  app.get('/api/gitea/milestones/search', async (req, res) => {
+    try {
+      const query = asString(req.query?.query);
+      const resolved = await lookupRepo(req);
+      if (resolved.error) {
+        return res.status(400).json({ error: resolved.error });
+      }
+      if (!resolved.client) {
+        return res.json({ connected: false, milestones: [] });
+      }
+      const { client, owner, repo, repoRef } = resolved;
+      if (!owner || !repo) {
+        return res.json({ connected: true, repo: null, milestones: [] });
+      }
+
+      const resp = await withTimeout(client.milestones(owner, repo, { state: 'all', limit: 100 }), ROUTE_TIMEOUT_MS, 'gitea milestones search');
+      if (resp.status === 429) {
+        return res.status(503).json({ error: 'Gitea rate limited' });
+      }
+      if (resp.status !== 200) {
+        return res.status(502).json({ error: 'Gitea returned an error while searching milestones' });
+      }
+      const needle = query.toLowerCase();
+      const milestones = (Array.isArray(resp.data) ? resp.data : [])
+        .map((item) => ({
+          title: typeof item?.title === 'string' ? item.title : '',
+          ...(typeof item?.state === 'string' ? { state: item.state } : {}),
+        }))
+        .filter((item) => item.title && (!needle || item.title.toLowerCase().includes(needle)));
+
+      return res.json({ connected: true, repo: repoRef || repoRefFromOwnerRepo(owner, repo, client.baseUrl), milestones });
+    } catch (error) {
+      console.error('Failed to search Gitea milestones:', error);
+      return res.status(500).json({ error: error.message || 'Failed to search Gitea milestones' });
+    }
+  });
+
+  app.get('/api/gitea/branches/search', async (req, res) => {
+    try {
+      const query = asString(req.query?.query);
+      const resolved = await lookupRepo(req);
+      if (resolved.error) {
+        return res.status(400).json({ error: resolved.error });
+      }
+      if (!resolved.client) {
+        return res.json({ connected: false, branches: [] });
+      }
+      const { client, owner, repo, repoRef } = resolved;
+      if (!owner || !repo) {
+        return res.json({ connected: true, repo: null, branches: [] });
+      }
+
+      const branches = [];
+      const needle = query.toLowerCase();
+      let page = 1;
+      while (page <= 10) {
+        const resp = await withTimeout(client.branches(owner, repo, { limit: 50, page }), ROUTE_TIMEOUT_MS, 'gitea branches search');
+        if (resp.status === 429) {
+          return res.status(503).json({ error: 'Gitea rate limited' });
+        }
+        if (resp.status !== 200 || !Array.isArray(resp.data)) {
+          break;
+        }
+        const chunk = resp.data;
+        for (const branch of chunk) {
+          const name = typeof branch?.name === 'string' ? branch.name : '';
+          if (!name) continue;
+          if (!needle || name.toLowerCase().includes(needle)) branches.push(name);
+        }
+        if (chunk.length < 50 || !resp.page?.hasMore) {
+          break;
+        }
+        page += 1;
+      }
+
+      return res.json({ connected: true, repo: repoRef || repoRefFromOwnerRepo(owner, repo, client.baseUrl), branches });
+    } catch (error) {
+      console.error('Failed to search Gitea branches:', error);
+      return res.status(500).json({ error: error.message || 'Failed to search Gitea branches' });
+    }
+  });
+
+  app.get('/api/gitea/tags/search', async (req, res) => {
+    try {
+      const query = asString(req.query?.query);
+      const resolved = await lookupRepo(req);
+      if (resolved.error) {
+        return res.status(400).json({ error: resolved.error });
+      }
+      if (!resolved.client) {
+        return res.json({ connected: false, tags: [] });
+      }
+      const { client, owner, repo, repoRef } = resolved;
+      if (!owner || !repo) {
+        return res.json({ connected: true, repo: null, tags: [] });
+      }
+
+      const resp = await withTimeout(client.tags(owner, repo, { limit: 100 }), ROUTE_TIMEOUT_MS, 'gitea tags search');
+      if (resp.status === 429) {
+        return res.status(503).json({ error: 'Gitea rate limited' });
+      }
+      if (resp.status !== 200) {
+        return res.status(502).json({ error: 'Gitea returned an error while searching tags' });
+      }
+      const needle = query.toLowerCase();
+      const tags = (Array.isArray(resp.data) ? resp.data : [])
+        .map((tag) => (typeof tag?.name === 'string' ? tag.name : ''))
+        .filter(Boolean)
+        .filter((name) => !needle || name.toLowerCase().includes(needle));
+
+      return res.json({ connected: true, repo: repoRef || repoRefFromOwnerRepo(owner, repo, client.baseUrl), tags });
+    } catch (error) {
+      console.error('Failed to search Gitea tags:', error);
+      return res.status(500).json({ error: error.message || 'Failed to search Gitea tags' });
+    }
+  });
 }

packages/web/server/lib/gitea/routes.test.js

@@ -1339,6 +1339,174 @@ describe('Gitea data routes', () => {
     expect(JSON.parse(options.body)).toEqual({ state: 'closed' });
   });
 
+  test('issues/create POSTs an issue and maps it', async () => {
+    const fetchMock = scriptedFetch([
+      (url, options) => {
+        if (matches(/\/issues$/)(url) && options.method === 'POST') {
+          return jsonResponse({
+            number: 9,
+            title: 'New issue',
+            html_url: 'https://gitea.example.com/owner/repo/issues/9',
+            state: 'open',
+            body: 'The body',
+            labels: [{ id: 1, name: 'bug', color: 'd73a4a' }],
+            user: { id: 42, login: 'alice', full_name: 'Alice Example' },
+            created_at: '2026-01-02T11:00:00Z',
+            updated_at: '2026-01-02T11:00:00Z',
+          }, { status: 201 });
+        }
+        return null;
+      },
+    ]);
+
+    const app = createApp();
+    const response = await request(app)
+      .post('/api/gitea/issues/create')
+      .send({ directory: '/tmp/work', title: 'New issue', body: 'The body', labels: ['bug'] });
+
+    expect(response.status).toBe(200);
+    expect(response.body).toMatchObject({
+      connected: true,
+      repo: { owner: 'owner', repo: 'repo', host: 'gitea.example.com' },
+      issue: {
+        number: 9,
+        title: 'New issue',
+        url: 'https://gitea.example.com/owner/repo/issues/9',
+        state: 'open',
+        body: 'The body',
+        labels: ['bug'],
+        author: { username: 'alice', id: 42 },
+      },
+    });
+    const [, options] = fetchMock.mock.calls[0];
+    expect(options.method).toBe('POST');
+    expect(JSON.parse(options.body)).toEqual({ title: 'New issue', body: 'The body', labels: ['bug'] });
+  });
+
+  test('issues/create requires directory and title', async () => {
+    const app = createApp();
+    const response = await request(app)
+      .post('/api/gitea/issues/create')
+      .send({ directory: '/tmp/work' });
+
+    expect(response.status).toBe(400);
+    expect(response.body).toEqual({ error: 'directory and title are required' });
+  });
+
+  test('issues/create reports connected:false when not authenticated', async () => {
+    clearGiteaAuth();
+    const app = createApp();
+    const response = await request(app)
+      .post('/api/gitea/issues/create')
+      .send({ directory: '/tmp/work', title: 'Hi' });
+
+    expect(response.status).toBe(200);
+    expect(response.body).toEqual({ connected: false });
+  });
+
+  describe('Gitea rich lookup routes', () => {
+    beforeEach(() => {
+      setGiteaAuth({ accessToken: 'gitea-secret', baseUrl: 'https://gitea.example.com', user: aliceUser });
+    });
+
+    test('users/search maps repo assignees and filters by query', async () => {
+      scriptedFetch([
+        (url) => (matches(/\/repos\/owner\/repo\/assignees\?/)(url)
+          ? jsonResponse([
+            { id: 42, login: 'alice', full_name: 'Alice Example', avatar_url: 'https://gitea.example.com/alice.png', html_url: 'https://gitea.example.com/alice' },
+            { id: 43, login: 'bob', full_name: 'Bob', avatar_url: 'https://gitea.example.com/bob.png', html_url: 'https://gitea.example.com/bob' },
+          ])
+          : null),
+      ]);
+
+      const app = createApp();
+      const response = await request(app).get('/api/gitea/users/search?directory=%2Ftmp%2Fwork&query=ali');
+
+      expect(response.status).toBe(200);
+      expect(response.body).toMatchObject({
+        connected: true,
+        repo: { owner: 'owner', repo: 'repo' },
+        users: [{ username: 'alice', id: 42, name: 'Alice Example', avatarUrl: 'https://gitea.example.com/alice.png' }],
+      });
+    });
+
+    test('users/search reports connected:false when not authenticated', async () => {
+      clearGiteaAuth();
+      const app = createApp();
+      const response = await request(app).get('/api/gitea/users/search?directory=%2Ftmp%2Fwork&query=ali');
+      expect(response.status).toBe(200);
+      expect(response.body).toEqual({ connected: false, users: [] });
+    });
+
+    test('labels/search returns labeled objects filtered by name', async () => {
+      scriptedFetch([
+        (url) => (matches(/\/repos\/owner\/repo\/labels\?/)(url)
+          ? jsonResponse([
+            { id: 1, name: 'bug', color: 'd73a4a', description: 'a bug' },
+            { id: 2, name: 'feature', color: '0e8a16' },
+          ])
+          : null),
+      ]);
+
+      const app = createApp();
+      const response = await request(app).get('/api/gitea/labels/search?directory=%2Ftmp%2Fwork&query=bug');
+
+      expect(response.status).toBe(200);
+      expect(response.body).toMatchObject({
+        connected: true,
+        labels: [{ name: 'bug', color: 'd73a4a', description: 'a bug' }],
+      });
+    });
+
+    test('milestones/search maps milestone titles and states', async () => {
+      scriptedFetch([
+        (url) => (matches(/\/repos\/owner\/repo\/milestones\?/)(url)
+          ? jsonResponse([
+            { id: 1, title: 'v1.0', state: 'open' },
+            { id: 2, title: 'v2.0', state: 'closed' },
+          ])
+          : null),
+      ]);
+
+      const app = createApp();
+      const response = await request(app).get('/api/gitea/milestones/search?directory=%2Ftmp%2Fwork&query=v1');
+
+      expect(response.status).toBe(200);
+      expect(response.body).toMatchObject({
+        connected: true,
+        milestones: [{ title: 'v1.0', state: 'open' }],
+      });
+    });
+
+    test('branches/search returns branch names', async () => {
+      scriptedFetch([
+        (url) => (matches(/\/repos\/owner\/repo\/branches\?/)(url)
+          ? jsonResponse([{ name: 'main' }, { name: 'feat/x' }])
+          : null),
+      ]);
+
+      const app = createApp();
+      const response = await request(app).get('/api/gitea/branches/search?directory=%2Ftmp%2Fwork&query=main');
+
+      expect(response.status).toBe(200);
+      expect(response.body).toMatchObject({ connected: true, branches: ['main'] });
+    });
+
+    test('tags/search returns tag names', async () => {
+      scriptedFetch([
+        (url) => (matches(/\/repos\/owner\/repo\/tags\?/)(url)
+          ? jsonResponse([{ name: 'v1.0.0' }, { name: 'v1.1.0' }])
+          : null),
+      ]);
+
+      const app = createApp();
+      const response = await request(app).get('/api/gitea/tags/search?directory=%2Ftmp%2Fwork&query=v1.0');
+
+      expect(response.status).toBe(200);
+      expect(response.body).toMatchObject({ connected: true, tags: ['v1.0.0'] });
+    });
+  });
+
   // NOTE: keep this test last in the file. The rate-limit cooldown is
   // module-level and has no reset export, so tests after it would short-circuit.
   test('data routes surface a 503 when Gitea rate limits', async () => {