Skip to content

refactor: make core independent of the file-explorer app - #28032

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
refactor/decouple-core-from-file-explorer
Nov 2, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
refactor/decouple-core-from-file-explorer

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Kiro Crew core stops importing or naming the Files (file-explorer) app, so that app can move out of this repository whole without core changing.

Core reaches into the Files app in four places today. The file viewer's ⋯ menu imports the app's deep-link module to build "Open in Files". Two core components borrow the app's parentDir and useDebouncedValue helpers. DefaultAppsLoader.bundled_app_names() names file_explorer by package name. A core test imports the app's server to pin its binary-extension list. While those links exist, the app cannot leave as #26967 plans.

Why it matters

Every built-in app is moving to its own repository (#26967). Without this change, removing the Files app would break the chat side panel's file viewer and the Files rail at build time, and nothing would stop a new core import of the app from creeping back in.

Not a goal

  • Moving the Files app out of the repository. This PR only makes that possible.
  • Changing what "Open in Files", the Files rail or orphan detection does while the app is installed.
  • The string-keyed rows that still name the app in core data: the ui-prefs sync allowlist key kc:file-explorer:state:v2 (users' open tabs), the App Store copy in appManifest.ts, the apps.fileExplorer.* catalog keys, the registry row, and the core tests that use the app as their shipped-builtin fixture. Each goes when the app leaves.
  • Switching the app's module-style entryPoint to a file entry point; that changes how the backend is launched and trusted.

What changed (motivation → approach → change)

Core now asks for what it needs instead of importing the app.

  • "Open in " is a generic seam. A BuiltinAppEntry may declare opensPathParam, the query parameter its page reads a path from. The new website/src/apps/pathOpener.ts picks the first such entry whose app is enabled and routed natively, and builds the link. The Files row declares path, so the row, its gates and its URL are unchanged; MarkdownPanel.test.tsx's "Open in Files" cases pass untouched.
  • Shared helpers move into core. useDebouncedValue becomes hooks/useDebouncedValue.ts and parentDir becomes utils/parentDir.ts; the app imports them from there.
  • bundled_app_names() returns [] (platform/defaults.py, with the AppsLoader docstring in platform/interfaces_structural.py). The two package names it returned never matched an installed app directory, which is hyphenated, so orphan detection reads the same set.
  • App tests live with the app. test_file_explorer_app.py and the app's frontend tests move into the app's directories, as do the app's cases from three cross-app frontend tests, its _is_within prefix case, and its parity pin of BINARY_EXTS against dashboard/handlers/files.py; test_server.py defines its own requires_symlinks marker instead of importing core's test/conftest.py. Two files.py comments stop naming the app's path. cssClassParity.test.ts now skips *.test.ts(x) files wherever they live, as it already skipped src/test/: a moved test's querySelector('.mc-fe-tab-folder') read as a stylesheet rule.
  • Two gates keep it that way. test/test_core_file_explorer_decoupling.py fails on any core module or script that imports the app or names it in a string. fileExplorerBoundary.test.ts fails on any dashboard module except builtinRegistry.ts that imports from the app directory.
  • One backend scanner serves every app gate. test/core_app_independence.py takes an app's package, its names and the reasoned string rows a gate allows. The Files gate and test_core_aws_control_decoupling.py both call it, so the next app to leave adds a short gate, not another scanner.

Specs updated: app-kit-platform.md, platform-context.md, website/docs/extension-seams.md, website/docs/frontend-conventions.md.

Backwards compatibility

Compatible: the Files app still ships in this tree and its registry row declares the path parameter, so the menu offers the same row with the same link; bundled_app_names() dropped only names no installed app can carry.

Reader: src/kiro_crew/apps/manager_builtins.py:_edition_bundled_app_names -- app -- feeds get_orphaned_builtins, whose discover_builtin_apps() already yields file-explorer and auto-research; test_cpp_wiring_enterprise_wave2.py
Reader: website/src/components/MarkdownPanelHeader.tsx:OverflowMenu -- chat -- reads pathOpenerTarget; MarkdownPanel.test.tsx "OverflowMenu — Open in Files"
Reader: website/src/components/FilePathMenu.tsx:FilePathMenu -- chat -- imports parentDir from utils/parentDir; parentDir.test.ts
Reader: website/src/pages/chat/FileBrowserRail.tsx:FileBrowserRail -- chat -- imports useDebouncedValue from hooks/useDebouncedValue; useDebouncedValue.test.ts

Tests

  • test/test_core_file_explorer_decoupling.py: the no-import gate, the no-name-string gate, and probes that every import form and both spellings are caught, run through the shared test/core_app_independence.py.
  • test/test_core_aws_control_decoupling.py: the same tests and pinned list as on main, run through the shared scanner.
  • website/src/apps/file-explorer/fileExplorerBoundary.test.ts: only builtinRegistry.ts imports into the app directory, and the row's path opener builds the link the page reads.
  • website/src/test/pathOpener.test.ts: the opener rule on synthetic registry rows (none declared, order, disabled / orphaned / AppHost-routed skipped, a parameter needing encoding skipped).
  • parentDir.test.ts, useDebouncedValue.test.ts: the cases moved out of the app's tests.
  • Moved, unchanged in substance: the app's backend and frontend tests, test_core_parity.py, test_windows_extended_prefix.py, api.typedErrors.test.ts, PathBar.imeGuard.test.tsx, windowsPaths.test.ts.

Determinism: the two backend gates (30 tests) passed 3 repeats at -n0, once in reverse file order, and once at -n 2 --dist loadgroup; they read only the source tree. The 146 backend tests in the Files gate and the app's tests/ passed 20 repeats at -n0, each in a different shuffled order (seeds 1-20), and 10 runs at -n 4; the frontend files under src/apps/file-explorer/ and the three new core test files passed 10 shuffled repeats (--sequence.shuffle, seeds 1-10). None of them sleeps or reads a clock.

Manual verification

N/A — unit coverage sufficient: the change moves code and inverts one import, and the unchanged menu tests pin the row's gates, label, order and link.

Screenshots / video

Why no screenshot: the file viewer's ⋯ menu renders the same rows with the same labels and order; only where its "Open in" target is looked up changed.

Related Issues

Part of #26967

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

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 2, 2026 10:07
@bolichen97
bolichen97 enabled auto-merge (squash) November 2, 2026 10:07
@bolichen97

Copy link
Copy Markdown
Contributor Author

Driver notes for #26967 (the campaign's driver decides and reports; nothing here asks for a ruling).

Decisions

  • "Open in Files" goes through a generic opensPathParam on BuiltinAppEntry plus apps/pathOpener.ts, not through the existing contributes.fileMenuItems. That seam POSTs the path to an app endpoint and adds an attributed row in a separate group. Moving the row onto it would change the row's placement and wording and what clicking it does. The new field keeps the behaviour byte-for-byte. The MarkdownPanel.test.tsx "Open in Files" cases are untouched and still pass.
  • useDebouncedValue and parentDir move into core, and the app imports them there. This follows refactor: make core independent of the dev-fleet and pptx-maker apps #27435's soffice_discovery precedent: something both sides use lives in core.
  • bundled_app_names() returns []. The auto_research / file_explorer package names never matched an installed app directory, which is hyphenated, so orphan detection is unchanged. Dropping auto_research is part of the same no-op.
  • The core tests that use the Files app as their shipped-builtin fixture stay where they are: test_app_execution, test_app_backend's module-style entryPoint, test_builtin_backend_address_reuse, test_host_isolation_floor, test_dashboard_snapshot, and the string-only governance / token / ui-prefs tests. They exercise core paths, and they get re-pointed when the app leaves.

Local gate on this host. Two backend reds and 13 frontend files also fail on a clean origin/main worktree with the same setup, so none of them comes from this diff:

  • test_find_ui_auto.py::...[continue with github...]
  • test_workspace_crud_cli.py: the cli_commands facade-family drift
  • 13 vitest files: the Pierre diff worker, ArtifactDetailPage, ChatInput.approval, SchedulePage.secrets and others. They fail on Denied ID .../node_modules/@pierre/diffs/...?worker&url because node_modules was symlinked from another worktree.
  • check-bundle-size.mjs: SettingsPage is 1.7 KB over budget on main as well.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 2, 2026
@bolichen97
bolichen97 force-pushed the refactor/decouple-core-from-file-explorer branch from d0efe15 to 4d27180 Compare November 2, 2026 11:33
@bolichen97

Copy link
Copy Markdown
Contributor Author

CI triage for d0efe15 (14 red checks). The new head is 4d27180, rebased on main 90773d1.

  • Backend Lint & Type Check (3.12), and the Coverage Gate that depends on it. Fixed in 4d27180. src/kiro_crew/apps/builtins/file_explorer/tests/test_server.py did from conftest import requires_symlinks. Under mypy src/kiro_crew/ that bare import resolves to the rootdir conftest.py, which has no such marker. That gave 7 errors, 6 of them inside the rootdir conftest. The app's test now defines the marker itself, using the same symlink probe as test/conftest.py. That also keeps the app's tests free of imports from core's test tree. I reproduced it locally (mypy src/kiro_crew/: 7 errors before, clean after).
  • macOS Tests (on demand) shard 6. test/test_process_tree_kill.py::TestSigkillSessionProcessTree::test_sigkill_fallback_on_killpg_failure is not caused by this diff, which does not touch subagent/acp/platform_compat. The same node id fails the macOS lane on five other branches' heads and passes on Linux here. It is recorded in the flake ledger as Flaky: test_sigkill_fallback_on_killpg_failure reds the macOS lane on every sampled head #28095. Shard 2 was cancelled, not red.
  • Dependency License Gate, Design / First Principles / UX / GPT 6.1 / Opus 5.5 Review, Sensitive Change Review, PR Policy (Screenshot Evidence), Publish readiness signal. All of these failed on the shared installation token's primary rate limit (API rate limit exceeded for installation; readiness logged 0/15000 remaining). None of them is a finding. They run again on the new head.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 2, 2026
@bolichen97
bolichen97 force-pushed the refactor/decouple-core-from-file-explorer branch from 4d27180 to b3474d6 Compare November 2, 2026 11:39
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased again, because main's #27995 changed website/src/apps/file-explorer/deepLink.ts and the branch conflicted with main. The new head is b3474d6 on main ea24427.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the core-to-app links are inverted into core-owned helpers and a declarative seam, and gates stop new imports.

Notes

  • opensPathParam lives on BuiltinAppEntry in builtinRegistry.ts, which is one of the built-in tables Move every built-in app out to KiroCrewApps and forbid built-in apps #26967 is emptying. Once Files ships from its own repo, that row goes and "Open in Files" goes with it. An installed app will need the same field in its manifest (an App Kit seam) for the menu row to survive the move, so plan that in the follow-up.

[DESIGN-REVIEWED] dfa45e8

Description read

[DESCRIPTION-READ] bd629a5a3e16c6d1840175a4e344ea779efc54fb0a065d7f06621a9355ce5bf0

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 2, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

Nothing to check. The "Open in Files" row keeps the same label, the same rules for when it appears and the same link; the rest of the diff moves code and tests, so no screenshot is needed.

[UX-REVIEWED] dfa45e8

Description read

[DESCRIPTION-READ] e4a636b5f27bf10831827f9ebb996d4657a8f012dca836f4cf35f5235c35495c

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 2, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of dfa45e89db9e3b4f6a1ac3b008d2620f7eea94e3 — 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

Nothing blocks: every item enforces the AGENTS.md rule that core never imports or names a specific app. One note: the new path-opener seam has exactly one user.

Notes

  • Item 1 — one consumer, generalized: opensPathParam is declared by exactly one registry row (grep opensPathParam outside tests: 1 declaring row, builtinRegistry.ts:63). Yet pathOpenerTarget loops over the registry and resolves "first match in registration order". BuiltinAppEntry is the table being emptied under Move every built-in app out to KiroCrewApps and forbid built-in apps #26967, so when Files leaves, the field has zero consumers. No external app can declare it either, because it is not a manifest key. Subtraction: when the Files row leaves, delete opensPathParam, pathOpener.ts and the ⋯-menu row together, rather than leaving a seam nobody can reach.

What this change ships

Inventory (8 items) — 7 justified

Intent: let the Files app leave the repo whole, without core changing (ADDITION/refactor, no behaviour change).

  1. The ⋯ menu's "Open in Files" row now finds its target through a generic registry field instead of an app import — one consumer, generalized
  2. The debounce hook and the parent-directory helper now live in core; the app imports them from there — justified
  3. The default apps loader declares no bundled app names — justified
  4. The app's backend and frontend tests moved into the app's own directory — justified
  5. Two gates fail on any core import of the Files app or any string naming it — justified
  6. One shared backend scanner serves both the Files gate and the aws-control gate — justified
  7. The CSS-parity test skips test files wherever they live — justified
  8. Comments in files.py stop naming the app's path — justified

[FIRST-PRINCIPLES-REVIEWED] dfa45e8

Description read

[DESCRIPTION-READ] 03b76fe824ada3ee26b0c416ab637b0b90dc8b20c3d85727323186e1ee46b2c6

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 2, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] dfa45e8

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

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

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] dfa45e8

False positive or not applicable? A repository writer can comment:
/ai-review override gpt dfa45e89db9e3b4f6a1ac3b008d2620f7eea94e3 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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 2, 2026
The Files app is to leave this repository whole, so nothing outside its
own directories may import it or name it.

- The dashboard's "Open in Files" row now asks a generic seam: a
  builtinRegistry entry declares `opensPathParam`, and
  apps/pathOpener.ts picks the first enabled, natively routed page
  that declares one. The Files row declares `path`, so the row, its
  gates and its link are unchanged.
- useDebouncedValue and parentDir, which core components borrowed from
  the app, move into core (hooks/, utils/); the app imports them.
- DefaultAppsLoader.bundled_app_names() returns [] instead of naming
  two builtins by package name. The names never matched an installed
  app directory (those are hyphenated), so orphan detection is
  unchanged.
- The app's tests, and the parity pin of its BINARY_EXTS against the
  core file-read endpoint, move into the app's own directories.
- test/test_core_file_explorer_decoupling.py and
  fileExplorerBoundary.test.ts keep core from importing or naming the
  app again. The backend gate and the aws-control one call one shared,
  app-agnostic scanner, test/core_app_independence.py, so the next app
  to leave adds a gate, not another copy of the scanner.

Part of #26967
@bolichen97
bolichen97 force-pushed the refactor/decouple-core-from-file-explorer branch from b3474d6 to dfa45e8 Compare November 2, 2026 13:01
@bolichen97

bolichen97 commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: one app-agnostic scanner, test/core_app_independence.py, behind every backend app-independence gate

  • span=61c65f7f3412 Second copy of the decoupling scanner

fixed in dfa45e8: the scanner moved out of both gates into test/core_app_independence.py (app_imports, name_strings, core_trees, core_app_imports, core_name_strings), keyed on an app package, its names and an allowlist of reasoned string rows.
test_core_aws_control_decoupling.py and test_core_file_explorer_decoupling.py keep their test names and pinned data (KNOWN_NAME_REFERENCES, APP_NAMES) and only call the helper; neither holds a copied helper.
app-kit-platform.md names the shared scanner, and states that the next app to leave adds a gate that calls it, never another scanner.
Verified: both gates, 30 tests, green at -n0 (both file orders) and -n 2 --dist loadgroup; a synthetic core import and string are still caught.

@bolichen97

Copy link
Copy Markdown
Contributor Author

The red macOS Tests / Backend Tests (macOS) (6) on b3474d6 is test/test_process_tree_kill.py::TestSigkillSessionProcessTree::test_sigkill_fallback_on_killpg_failure, the macOS-only red tracked in #28095 (same node id red on six unrelated heads; fix in #28108). This PR touches no process/kill code. Recorded on the ledger: #28095 (comment)

@github-actions github-actions Bot added readiness: checking Automated validation is still running 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 2, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approved on behalf of the watch holder (bolichen). Lanes pass on dfa45e8, no conflict, no open change request.

@KiroCrewCaptain
KiroCrewCaptain merged commit 9c5869f into main Nov 2, 2026
95 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the refactor/decouple-core-from-file-explorer branch November 2, 2026 15:59
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 2, 2026
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.

2 participants