Integrate Project model into loader and decompose into composable stages

[ryancbahan]

WHY are these changes introduced?

PR #7022 introduced the Project and ActiveConfig domain models, but nothing consumed them (the loader still ran its own filesystem discovery, constructed AppConfigurationState as an intermediate, and threaded the entire previous AppInterface through reloads). This PR wires the new models into the loading pipeline and uses that as leverage to decompose the monolithic loadApp into composable stages with narrow interfaces.

WHAT is this pull request doing?

Decomposes the loader into three explicit stages:

• getAppConfigurationContext(dir, configName) → {project, activeConfig} — discovery only, no parsing or state construction
• loadAppFromContext({project, activeConfig, specifications, …}) → AppInterface — validation and assembly, for callers that already hold a Project
• loadApp({directory, configName, …}) — thin wrapper composing the two above

[Interim state] Replaces previousApp with narrow ReloadState:

Instead of threading the entire AppLinkedInterface through reloads (just to read 2 fields), reloadApp now constructs a ReloadState with only extensionDevUUIDs: Map<string, string> and previousDevURLs. This is a step change away from broad state passing/mutation, but needs more consideration on "permanent home" as we continue to decompose functionality.

Updates all consumers:

• linkedAppContext uses activeConfig.isLinked and activeConfig.file.content directly instead of going through AppConfigurationState
• link() returns {remoteApp, configFileName, configuration} — drops state from its return type
• use() reads activeConfig.file.content instead of calling loadAppConfiguration
• loadConfigForAppCreation uses activeConfig and project.directory directly

Removes dead code (-400 lines):

AppConfigurationState, AppConfigurationStateBasics, toAppConfigurationState, loadAppConfigurationFromState, loadAppUsingConfigurationState, loadAppConfiguration, getAppConfigurationState, getAppDirectory, loadDotEnv, loadHiddenConfig, findWebConfigPaths, loadWebsForAppCreation, getConfigurationPath (de-exported)

How to test your changes?

npx vitest run packages/app/src/cli/models/app/loader.test.ts
npx vitest run packages/app/src/cli/services/app-context.test.ts
npx vitest run packages/app/src/cli/services/app/config/link.test.ts
npx vitest run packages/app/src/cli/services/app/config/use.test.ts
npx vitest run packages/app/src/cli/services/context.test.ts
npx vitest run packages/app/src/cli/models/project/

Measuring impact

• n/a

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes

🤖 Generated with Claude Code

[ryancbahan]

• Remove packageManager, nodeDependencies, usesWorkspaces from App #7035
• Integrate Project model into loader and decompose into composable stages #7023 👈 (View in Graphite)
• Add Project domain model for filesystem abstraction #7022
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟢	Statements	82.2%	14884/18106
🟡	Branches	74.52%	7353/9867
🟢	Functions	81.38%	3762/4623
🟢	Lines	82.6%	14073/17037

Test suite run success

3916 tests passing in 1504 suites.

Report generated by 🧪jest coverage report action from c5eef3c

[github-actions]

We detected some changes at packages/*/src and there are no updates in the .changeset.
If the changes are user-facing, run pnpm changeset add to track your changes and include them in the next release CHANGELOG.

Caution

DO NOT create changesets for features which you do not wish to be included in the public changelog of the next CLI release.

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

We found no new type declarations in this PR

Existing type declarations

packages/cli-kit/dist/public/node/themes/api.d.ts

@@ -5,7 +5,6 @@ export type ThemeParams = Partial<Pick<Theme, 'name' | 'role' | 'processing' | '
 export type AssetParams = Pick<ThemeAsset, 'key'> & Partial<Pick<ThemeAsset, 'value' | 'attachment'>>;
 export declare function fetchTheme(id: number, session: AdminSession): Promise<Theme | undefined>;
 export declare function fetchThemes(session: AdminSession): Promise<Theme[]>;
-export declare function findDevelopmentThemeByName(name: string, session: AdminSession): Promise<Theme | undefined>;
 export declare function themeCreate(params: ThemeParams, session: AdminSession): Promise<Theme | undefined>;
 export declare function fetchThemeAssets(id: number, filenames: Key[], session: AdminSession): Promise<ThemeAsset[]>;
 export declare function deleteThemeAssets(id: number, filenames: Key[], session: AdminSession): Promise<Result[]>;

packages/cli-kit/dist/public/node/themes/theme-manager.d.ts

@@ -8,8 +8,8 @@ export declare abstract class ThemeManager {
     protected abstract removeTheme(): void;
     protected abstract context: string;
     constructor(adminSession: AdminSession);
-    findOrCreate(name?: string, role?: Role): Promise<Theme>;
-    fetch(name?: string, role?: Role): Promise<Theme | undefined>;
+    findOrCreate(): Promise<Theme>;
+    fetch(): Promise<Theme | undefined>;
     generateThemeName(context: string): string;
     create(themeRole?: Role, themeName?: string): Promise<Theme>;
 }
\ No newline at end of file

[isaacroldan]

---

Review assisted by pair-review

[isaacroldan]

💡 Improvement: createExtensionInstances takes _extensionDirectories (underscore-prefixed to suppress unused-var linting) but completely ignores it. Extension discovery comes from this.activeConfigFile and extensionFilesForConfig, which reads extension_directories from activeConfig.content internally. The parameter is passed from the call site at line 641 as appConfiguration.extension_directories, but it's never consumed.

Suggestion: Remove the _extensionDirectories parameter from the method signature and the corresponding argument from the call site at line 641.

[ryancbahan]

This is implemented in the next pr in stack 03-17-remove-project-fields-from-app

[isaacroldan]

📐 Design: active-config.ts imports getAppConfigurationFileName from loader.js (line 4), and loader.ts imports selectActiveConfig from active-config.js. Additionally, active-config.ts imports use.js (line 6) which imports getAppConfigurationContext from loader.js, creating a deeper cycle: loader → active-config → use → loader. Node ESM handles this without crashing at startup thanks to live bindings, but it's fragile — reordering imports or adding a top-level side effect in any of these files can produce undefined at import time. It also makes isolated testing harder.

Suggestion: Extract getAppConfigurationFileName into a small, leaf-level utility module (e.g., config-naming.ts) that both loader.ts and active-config.ts can import without forming a cycle. This function is a pure string utility with no dependencies on loader internals.

[ryancbahan]

will extract.

[isaacroldan]

Human comment: Are we planning to validate the active config content using the modules schemas?
AI:
🐛 Bug: The old code called loadAppConfiguration which parsed and validated the config against AppSchema before passing it to setCurrentConfigPreference. The new code reads raw TOML via getAppConfigurationContext and casts it with as AppConfiguration, bypassing all schema validation. A malformed config file (invalid field types, missing nested structure, wrong shapes) will now be silently accepted as the current preference. Previously, such files would produce a validation error. This is a behavioral regression — the app config use command no longer validates configs before adopting them.

Suggestion: Either validate the content against AppSchema before setting the preference, or narrow the type to only what setCurrentConfigPreference actually needs. If full validation isn't feasible here, at minimum validate the fields that setCurrentConfigPreference relies on (like client_id).

[ryancbahan]

I believe this is the correct behavior. "Use" is just switching active TOML -- it should only validate whether the toml is syntactically correct (which it does). It's not running anything, and therefore should not concern itself with schema validation. Other commands handle that.

[isaacroldan]

So the validation would happen on the next command run?
The casting is weird though, because you can't be sure that content conforms to AppConfiguration :/

[ryancbahan]

That's fair, though I'm not sure it's rewriting at the moment since it's just passthrough and any "real" command will catch the errors.

[isaacroldan]

Let's add tests for this file :)

[isaacroldan]

Umm, during dev you might add a new extension, that forces an app reload. But this project won't have the new files for the new extension right? :thinking_face:

[isaacroldan]

Yeah I confirmed this:
app dev appears to work when generating an extension mid-dev, because the watcher detects the changes. And it triggers the reloadApp so that the in-memory App representation is updated. But Since this reload is not re-scanning the file-system is not loading the new extensions and they are not included in the deployed manifest.

We need to re-scan when reloading the app :)

[ryancbahan]

Context from Slack -- this is a pre-existing issue on main branch. Will make sure it's fixed here though.

[ryancbahan]

The reload is called as expected in this pr. I added a test to demonstrate this

[isaacroldan]

The reload behaviour has changed, let's fix that first 🙏

I think some extensive tophat of app dev is necessary before merging, even it appears to work, we need to check the manifest.json and the bundle uploaded to ensure it includes everything

[ryancbahan]

Pulling context from Slack -- we discovered the reload issue with manifest writes is already on main, not introduced in this pr. I've added more tests here and will tophat thoroughly + document.

[ryancbahan]

this was hogging up memory now that tests are sharded

[ryancbahan]

Added a bunch more tests around hot reload, file watching, and config switching. Doing a bunch of local tophatting and good so far.