Skip to content

feat(app-sdk): issue list components (useIssues, IssueList, IssueCard) - #34732

Merged
bolichen97 merged 2 commits into
mainfrom
feat/app-sdk-issue-components
Nov 13, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
feat/app-sdk-issue-components

Conversation

@kyleseaman

@kyleseaman kyleseaman commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Let any Kiro Crew app list, search and show issues from GitHub, GitLab, Jira and Linear with one SDK hook and two ready-made components.

An app builder who wants an issue list today has to write the request, paging, loading and error states, provider badges and the permission check themselves. The dashboard has issue UI (IssuePanel, Issue Radar's list), but none of it is exported through @kirocrew/app-sdk.

Why it matters

Issue lists are one of the most common things a crew app shows. Without shared components, each app rebuilds them, and each copy can get the security details wrong: rendering provider text as HTML, opening a javascript: link, or calling the gateway without a declared permission.

Not a goal

  • The gateway route POST /api/source/issues. A separate PR builds it against the same contract; until it lands, the components are tested against a mocked transport.
  • Editing issues (comment, close, assign). The components are read-only.
  • Changing the existing dashboard issue UI (IssuePanel, Issue Radar).

What changed (motivation → approach → change)

Apps get useIssues(query), <IssueList> and <IssueCard> from @kirocrew/app-sdk. The list draws GitHub, GitLab, Jira and Linear issues from one IssueSummary shape, in a one-row condensed view or a card expanded view. It has loading, empty, error and "Load more" states and an optional filter bar for state, assignee ("Assigned to me"), labels and search text.

The approach copies PullRequestPanel. The host's identity picks the transport: an external app's scoped client only when its manifest declares /api/source/issues, the dashboard client for builtin pages, and a refusal with zero requests otherwise. The singular /api/source/issue does not enable it. Provider text renders as text. Links and avatars load only from http(s) URLs.

The code lives in website/src/app-sdk/issues/ (useIssues.ts, IssueList.tsx, IssueCard.tsx, and the lazy boundary in index.tsx), exported from website/src/app-sdk/index.ts. Builtin pages call the new fetchIssues in website/src/api/client/sourceControl.ts. The components use the request and response types the merged route (#34742) defined in website/src/types/index.sources.ts (IssueSearchRequest, IssueSearchResponse, IssueSummary); this PR adds no types of its own. The route serves all four providers (GitHub, GitLab, Jira and Linear), and the docs say so. Both SDK level mirrors (website/src/app-sdk/sdkLevel.ts, src/kiro_crew/apps/app_sdk_level.py) move from 5 to 6 (main's #35533 took level 5 for ctx.app_token()), so an app can tell a host with the issue list from one without it, and the vendor stub lists the new exports. Strings go through the i18n catalog in every locale under website/src/i18n/locales/, with the plural keys registered in website/src/i18n/pluralKeys.json. Docs add a short guide, an api-reference entry, the full-app example and the spec and feature-map rows. website/capture/ gains a stubbed harness for the screenshots.

Backwards compatibility

Compatible: only new exports, types and an API-client method; nothing existing changes shape.

Removes nothing: the diff only adds exports, components, catalog keys and docs.

Tests

website/src/test/AppSdkIssues.test.tsx (20 tests):

  • Fails closed: refusal and zero requests when only /api/source/issue is declared, and with no identity or SDK provider; the hook reports an AppApiPermissionError; builtin pages keep the dashboard client.
  • Paging follows nextCursor and hides "Load more" on the last page; a filter change starts again from the first page; typed filters debounce; "Assigned to me" sends assignee: "me".
  • Empty state (default and app text), provider error with retry, loading skeleton; a failed "Load more" keeps the loaded issues and offers the agent hand-off.
  • All four providers in both views; sparse issues (null priority and author, no labels, long title) and RTL text in both views.
  • Hostile text renders as text; javascript: issue and avatar URLs are neither linked nor fetched; keyboard-reachable rows with accessible names; the condensed row caps label chips at two.
  • A list reopened after the route's 30 s cache reads again (the app's query client otherwise keeps data forever), and the filter bar hides while query.raw replaces the structured filters. A Jira or Linear card leaves out the comment count, which their searches never report. An issue the next page repeats after a re-sort (the route pages by offset) is shown once. Each of these tests fails with its fix reverted.

Determinism: the file passed 25/25 in 3 shuffled orders (--sequence.shuffle, seeds 1-3) on the final head, and 21/21 on 5 repeats and 5 shuffled orders before the last two tests were added.

Local frontend gate for this push: tsc, i18n:check, the theme and restyle lints, and 107 scoped test files (the app-sdk, API-client and issue tests plus all of src/i18n). The full vitest related step was not run locally. Because this diff touches types/index.ts and the locale catalogs, it selects most of the frontend suite, and on the shared host (load about 25 on 16 cores) it covered 251 files in 45 minutes while main moved 79 commits. CI's Frontend Tests is the full gate. Two AppSdkSharedModulesCov80 tests timed out locally at 15 s on a cold import under that load; they pass with --testTimeout=60000.

Manual verification

Rendered the real components in the stubbed harness (node capture/shoot-app-sdk-issues.mjs) in dark and light themes at 760px and 320px: both views, "Assigned to me" on, the empty, loading and error states, and the refusal.

Screenshots / video

Condensed, dark, with "Assigned to me" on (the toggle is a pill with a person icon, so it does not read as a text box):

Condensed issue list, dark theme, Assigned to me on

Expanded, light:

Expanded issue cards, light theme

Error with retry and the agent hand-off, light:

Provider error with Retry and Ask the agent, light theme

More: other theme and width variants, empty, loading, refusal

Condensed issue list, dark theme

Condensed issue list, light theme

Expanded issue cards, dark theme

Condensed list at 320px, dark

Expanded cards at 320px, light

Empty state, light theme

Loading skeleton, dark theme

Refusal when /api/source/issues is not declared

Related Issues

N/A — no tracking issue for this work.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@kyleseaman
kyleseaman requested review from a team and KiroCrewCaptain as code owners November 10, 2026 18:39
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 10, 2026
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS (a BLOCK with no Trigger and no Outcome does not block)

Design-level review of ce129e9ad4b434896e1ec60a1086d8cfc3fe5d2e — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

cannot evaluate: missing screenshot or recording of the <IssueList>/<IssueCard> views. This PR adds a new user-visible surface, and the workflow's evidence list contains no image of it.

Blockers

No rendered evidence of this revision for the new issue-list surface
Trigger: the diff adds website/src/app-sdk/issues/IssueList.tsx and IssueCard.tsx, which render condensed and expanded views, a filter bar ("Assigned to me" toggle, state, labels, search), and loading, empty, error and "Load more" states. Every image the description offers appears as "[image removed]".
Outcome: design-evidence.txt records "attachments downloaded and typed as images: 0", "committed images … 0" and "failed for a transport reason: 0". No artifact was confirmed, so the shape of the control set (does the toggle read as a pill, does the condensed row stay dense, how the error and hand-off look) cannot be judged, and this design lane cannot pass the surface.
Fix: re-attach the screenshots from node capture/shoot-app-sdk-issues.mjs as github.com/user-attachments images in the description, or commit them under temp-screenshots/.
Clears when: design-evidence.txt lists at least one downloaded or committed image showing IssueList (condensed and expanded) at this head SHA.

Notes

  • The ## Backwards compatibility section has both a Compatible: line and a Removes nothing: line. Keep only the Removes nothing: line.

[DESIGN-REVIEWED] ce129e9

Description read

[DESCRIPTION-READ] 5da3f3731df045f27ce9128a513267ec9ee4c7be5846c703d532417827917c27

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of ce129e9ad4b434896e1ec60a1086d8cfc3fe5d2e — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

This only adds things: a new SDK hook and two components beside the existing ones, with no default changed. The issue route already exists (#34742), and nothing in the repo already provides an exportable issue list.

Notes

  • Item 6 — inherited: the builtin branch (builtinTransport → new api.fetchIssues) copies "the way PullRequestPanel decides it". 0 built-in pages render IssueList/useIssues (grepped website/src/apps, website/src/pages), and AGENTS.md accepts no new built-in apps. Subtraction: delete builtinTransport and fetchIssues from sourceControl.ts, so the builtin case falls through to the refusal until a built-in page actually needs it.
  • Item 7 — symptom-level: uniqueIssues fixes duplicate rows on the client because "the route pages by offset". The cause is offset paging in issue_search.py. That is outside this PR's Goal, so it stays a note.

What this change ships

Inventory (9 items) — 7 justified

Intent: let an app builder show a paged, filterable issue list from GitHub, GitLab, Jira or Linear without writing the fetching, the states or the safety rules themselves. ADDITION.

  1. Apps can import useIssues, IssueList and IssueCard from @kirocrew/app-sdk — justified
  2. The list shows a refusal and sends no request unless the manifest declares /api/source/issues — justified
  3. A condensed one-row view and an expanded card view for all four providers — justified
  4. An optional filter bar (state, assignee, "Assigned to me", labels, text) with debounced typing — justified
  5. "Load more" paging, plus loading, empty and error states with retry and agent hand-off — justified
  6. Built-in pages fetch through the dashboard client via the new api.fetchIssues — one consumer, generalized; mirrors PullRequestPanel
  7. An issue repeated across pages is shown once — symptom-level; the cause is offset paging in the route
  8. APP_SDK_LEVEL goes from 5 to 6 in both mirrors, and the vendor stub lists the new exports — justified
  9. Docs, guide, full-app example permission, locale strings and a capture harness — justified

[FIRST-PRINCIPLES-REVIEWED] ce129e9

Description read

[DESCRIPTION-READ] a8915fb387f5f202b021c4e6956fdc1e12c944e22630ed3aefb96d6a0be7eb62

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS (a BLOCK with no Trigger and no Outcome does not block)

UX-level review of ce129e9ad4b434896e1ec60a1086d8cfc3fe5d2e — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

cannot evaluate: missing screenshots of the new IssueList / IssueCard surfaces. The blind read was not performed because no image this lane could admit was supplied.

Evidence gaps

  • Missing images for every new state: the condensed and expanded views, the filter bar (state, assignee, labels, search, and the "Assigned to me" pill), the loading skeleton, the empty state, the error state with retry and agent hand-off, and the refusal. All of these come from website/src/app-sdk/issues/IssueList.tsx and IssueCard.tsx.
  • Why the description's images don't count: they arrived as [image removed], and the screenshot list is empty, so nothing was admitted for this revision.
  • What closes the gap: attach the images node capture/shoot-app-sdk-issues.mjs produces as github.com/user-attachments images in the PR description, or commit them under temp-screenshots/. Then re-run this workflow.

[UX-REVIEWED] ce129e9

Description read

[DESCRIPTION-READ] 2c3bf62820f11ad146d09b16a2079536ded216a695d7ac946ced6b9c1b073222

That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed ce129e9ad4b434896e1ec60a1086d8cfc3fe5d2e — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] ce129e9

Verdict parsed from the review's SHA-scoped output markers for commit ce129e9ad4b434896e1ec60a1086d8cfc3fe5d2e.

False positive or not applicable? A repository writer can comment:
/ai-review override fable ce129e9ad4b434896e1ec60a1086d8cfc3fe5d2e false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of ce129e9ad4b434896e1ec60a1086d8cfc3fe5d2e and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ce129e9

False positive or not applicable? A repository writer can comment:
/ai-review override gpt ce129e9ad4b434896e1ec60a1086d8cfc3fe5d2e false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 10, 2026
@KiroCrewCaptain

KiroCrewCaptain commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider estimates a 12% chance that this change introduces a defect, within the 12% limit for approving on its own, but it changes 1849 lines, more than the 400 it may approve on its own.

Additive SDK feature: useIssues, IssueList and IssueCard over the existing POST /api/source/issues route. The fetch choice copies PullRequestPanel: an external app gets its scoped client only when apiPathAllowed covers /api/source/issues, builtin pages use the dashboard client, and otherwise the hook refuses with an AppApiPermissionError and sends no request. The slash-boundary matcher excludes the singular /api/source/issue, and the builtin origin cannot be forged by an external app. The backend accepts cursor null and serves all four providers. Jira and Linear search really do send commentCount 0, so hiding it is correct. Provider text renders as text, links and avatars pass safeHttpUrl, and labelChipStyle validates hex colours. The SDK level moves 5→6 in both mirrors (pinned equal by test_app_sdk_level_mirror). The vendor stub and barrel stay in exact agreement, as appSharedModuleBoundary requires. The API-client order test, plural keys and locales are updated. The new tests cover each added behaviour. No regression, fail-open or data-loss path found. Caveat: the frontend ratchets/i18n, lint and CodeQL checks were still pending at review time, and the full frontend suite was not

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit ce129e9ad4 · 1849 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@kyleseaman
kyleseaman force-pushed the feat/app-sdk-issue-components branch from 20d1e5c to 70c75c6 Compare November 11, 2026 01:02
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 11, 2026
@kyleseaman
kyleseaman force-pushed the feat/app-sdk-issue-components branch from 70c75c6 to 315c4a2 Compare November 11, 2026 23:02
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 11, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 12, 2026
@kyleseaman
kyleseaman force-pushed the feat/app-sdk-issue-components branch from 315c4a2 to e2309e2 Compare November 12, 2026 11:02
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 12, 2026
@kyleseaman
kyleseaman force-pushed the feat/app-sdk-issue-components branch from e2309e2 to bda7573 Compare November 12, 2026 12:50
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Nov 12, 2026
bolichen97
bolichen97 previously approved these changes Nov 12, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. I read every product file in the diff (useIssues.ts, IssueList.tsx, IssueCard.tsx, issues/index.tsx, the app-sdk/index.ts and vendor-stub exports, sourceControl.ts, both SDK level files) and skimmed the docs, capture harness, locales and tests.

  • One endpoint only. The hook's only request is POST /api/source/issues: through the app's scoped client (scopedIssuesTransport) for an external app, or api.fetchIssues for a builtin page. Nothing else is called, and the route itself is unchanged.
  • Fails closed. An external app gets a transport only when apiPathAllowed(permissions.api, '/api/source/issues') holds, and the singular /api/source/issue doesn't satisfy it. With no SDK context the hook sends nothing and returns an AppApiPermissionError. The builtin path keys off the host-published identity, never the app. This mirrors PullRequestPanel.
  • Provider text is inert. Every title, label, excerpt and name renders as a React text child (no dangerouslySetInnerHTML). Links and avatars go through safeHttpUrl, with rel="noopener noreferrer" and referrerPolicy="no-referrer".
  • No regex in product code. splitLabels is a plain split(','). The only regex in the diff is a trailing-slash trim in the dev capture script.
  • The capture harness serves Vite on 127.0.0.1 only and fabricates every response.
  • Hiding the comment count for Jira and Linear (whose list APIs report 0) and hiding the filter bar while raw is set are both good calls.

@bolichen97
bolichen97 enabled auto-merge (squash) November 12, 2026 17:07
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 12, 2026
@kyleseaman
kyleseaman force-pushed the feat/app-sdk-issue-components branch from 7d3bf71 to fe14091 Compare November 12, 2026 19:31
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 12, 2026
@kyleseaman
kyleseaman force-pushed the feat/app-sdk-issue-components branch from fe14091 to ce129e9 Compare November 12, 2026 22:51
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 12, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-approving at ce129e9. The new push dismissed my approval on 7d3bf71. I compared the two saved diffs, and only two things changed:

  • Docs. The guide, the README row and the feature-map rows now say the route serves Linear too, instead of naming its provider_not_supported error. A Linear commentCount is documented as 0 because its list API reports none.
  • uniqueIssues. IssueList now merges pages through uniqueIssues, which keeps the first copy of each issue, keyed by url or provider:key. The route pages by offset over a list sorted by update time, so an issue updated after page 1 loaded could show twice. The new test pins one copy.

The rest of the diff is the same as at 7d3bf71. No regex is added, and nothing is live red (the cancelled runs are superseded by newer passes).

@bolichen97
bolichen97 merged commit ab9144b into main Nov 13, 2026
112 of 116 checks passed
@bolichen97
bolichen97 deleted the feat/app-sdk-issue-components branch November 13, 2026 01:08
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 13, 2026
KiroCrewCaptain added a commit to KiroCrewCaptain/kirocrew-app-spec-builder that referenced this pull request Nov 13, 2026
Kiro Crew gave App Kit level 6 to the SDK's issue list
(kirodotdev/KiroCrew#34732), so the agentReadOnlyDirs seam
(kirodotdev/KiroCrew#33589) lands at level 7. Gating on 6 would move
the decision record into a data/trust/ that a level-6 host does not
fence. Raise READONLY_DIRS_SDK_LEVEL to 7, update the docs and tests
that named level 6, and pin that a level-6 host keeps the record where
it gates it.
kyleseaman pushed a commit that referenced this pull request Nov 13, 2026
Main's #34732 took App Kit seam level 6 (issue list) and #33589 took level 7
(agentReadOnlyDirs, backend SDK), so permissions.bots moves to level 8 in both
mirrors (app_sdk_level.py, sdkLevel.ts), api-reference.md and app-kit-platform.md
§32c. Other conflicts were additive: manager_uninstall.py keeps both imports, and
the feature-map rows and the api-reference level list keep both sides' entries.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants