Add Project domain model with ActiveConfig and config-selection

Introduces a new Project domain model that abstracts the filesystem
for Shopify app projects. Project discovers all config files, extension
files, web files, dotenv files, hidden config, and project metadata
in a single scan.

- Project: discovers and holds all filesystem state without
  interpreting it. Supports multi-config projects (shopify.app.*.toml).
- ActiveConfig: represents the selected app configuration, derived
  from Project. Resolves config-specific dotenv and hidden config.
- Config selection functions: resolveDotEnv, resolveHiddenConfig,
  extensionFilesForConfig, webFilesForConfig — pure functions that
  derive config-specific state from Project.

48 tests covering project discovery, config selection, file filtering,
dotenv resolution, hidden config lookup, multi-config scenarios, and
integration parity with the existing loader.

All new code — zero changes to existing files.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ryancbahan

packages/app/src/cli/models/project/active-config.test.ts

@@ -0,0 +1,167 @@
+import {selectActiveConfig} from './active-config.js'
+import {Project} from './project.js'
+import {describe, expect, test, vi, beforeEach} from 'vitest'
+import {inTemporaryDirectory, writeFile, mkdir} from '@shopify/cli-kit/node/fs'
+import {joinPath} from '@shopify/cli-kit/node/path'
+
+vi.mock('../../services/local-storage.js', () => ({
+  getCachedAppInfo: vi.fn().mockReturnValue(undefined),
+  setCachedAppInfo: vi.fn(),
+  clearCachedAppInfo: vi.fn(),
+}))
+
+vi.mock('../../services/app/config/use.js', () => ({
+  default: vi.fn(),
+}))
+
+const {getCachedAppInfo} = await import('../../services/local-storage.js')
+const useModule = await import('../../services/app/config/use.js')
+
+beforeEach(() => {
+  vi.mocked(getCachedAppInfo).mockReturnValue(undefined)
+})
+
+describe('selectActiveConfig', () => {
+  test('selects config by user-provided name (flag)', async () => {
+    await inTemporaryDirectory(async (dir) => {
+      await writeFile(joinPath(dir, 'shopify.app.toml'), 'client_id = "default"')
+      await writeFile(joinPath(dir, 'shopify.app.staging.toml'), 'client_id = "staging"')
+      const project = await Project.load(dir)
+
+      const config = await selectActiveConfig(project, 'staging')
+
+      expect(config.fileName).toBe('shopify.app.staging.toml')
+      expect(config.file.content.client_id).toBe('staging')
+      expect(config.source).toBe('flag')
+      expect(config.isLinked).toBe(true)
+    })
+  })
+
+  test('selects config from cache', async () => {
+    await inTemporaryDirectory(async (dir) => {
+      await writeFile(joinPath(dir, 'shopify.app.toml'), 'client_id = "default"')
+      await writeFile(joinPath(dir, 'shopify.app.production.toml'), 'client_id = "production"')
+      const project = await Project.load(dir)
+
+      vi.mocked(getCachedAppInfo).mockReturnValue({
+        directory: dir,
+        configFile: 'shopify.app.production.toml',
+      })
+
+      const config = await selectActiveConfig(project)
+
+      expect(config.fileName).toBe('shopify.app.production.toml')
+      expect(config.file.content.client_id).toBe('production')
+      expect(config.source).toBe('cached')
+    })
+  })
+
+  test('falls back to default shopify.app.toml when no flag or cache', async () => {
+    await inTemporaryDirectory(async (dir) => {
+      await writeFile(joinPath(dir, 'shopify.app.toml'), 'client_id = "default-id"')
+      const project = await Project.load(dir)
+
+      const config = await selectActiveConfig(project)
+
+      expect(config.fileName).toBe('shopify.app.toml')
+      expect(config.file.content.client_id).toBe('default-id')
+    })
+  })
+
+  test('detects isLinked from client_id', async () => {
+    await inTemporaryDirectory(async (dir) => {
+      await writeFile(joinPath(dir, 'shopify.app.toml'), 'client_id = ""')
+      const project = await Project.load(dir)
+
+      const config = await selectActiveConfig(project)
+
+      expect(config.isLinked).toBe(false)
+    })
+  })
+
+  test('detects isLinked when client_id is present', async () => {
+    await inTemporaryDirectory(async (dir) => {
+      await writeFile(joinPath(dir, 'shopify.app.toml'), 'client_id = "abc123"')
+      const project = await Project.load(dir)
+
+      const config = await selectActiveConfig(project)
+
+      expect(config.isLinked).toBe(true)
+    })
+  })
+
+  test('resolves config-specific dotenv', async () => {
+    await inTemporaryDirectory(async (dir) => {
+      await writeFile(joinPath(dir, 'shopify.app.staging.toml'), 'client_id = "staging"')
+      await writeFile(joinPath(dir, 'shopify.app.toml'), 'client_id = "default"')
+      await writeFile(joinPath(dir, '.env'), 'KEY=default')
+      await writeFile(joinPath(dir, '.env.staging'), 'KEY=staging')
+      const project = await Project.load(dir)
+
+      const config = await selectActiveConfig(project, 'staging')
+
+      expect(config.dotenv).toBeDefined()
+      expect(config.dotenv!.variables.KEY).toBe('staging')
+    })
+  })
+
+  test('resolves hidden config for client_id', async () => {
+    await inTemporaryDirectory(async (dir) => {
+      await writeFile(joinPath(dir, 'shopify.app.toml'), 'client_id = "abc123"')
+      await mkdir(joinPath(dir, '.shopify'))
+      await writeFile(
+        joinPath(dir, '.shopify', 'project.json'),
+        JSON.stringify({abc123: {dev_store_url: 'test.myshopify.com'}}),
+      )
+      const project = await Project.load(dir)
+
+      const config = await selectActiveConfig(project)
+
+      expect(config.hiddenConfig).toStrictEqual({dev_store_url: 'test.myshopify.com'})
+    })
+  })
+
+  test('returns empty hidden config when no entry for client_id', async () => {
+    await inTemporaryDirectory(async (dir) => {
+      await writeFile(joinPath(dir, 'shopify.app.toml'), 'client_id = "abc123"')
+      const project = await Project.load(dir)
+
+      const config = await selectActiveConfig(project)
+
+      expect(config.hiddenConfig).toStrictEqual({})
+    })
+  })
+
+  test('path is absolute', async () => {
+    await inTemporaryDirectory(async (dir) => {
+      await writeFile(joinPath(dir, 'shopify.app.toml'), 'client_id = "abc"')
+      const project = await Project.load(dir)
+
+      const config = await selectActiveConfig(project)
+
+      expect(config.path).toBe(joinPath(dir, 'shopify.app.toml'))
+    })
+  })
+
+  test('accepts full filename as config name', async () => {
+    await inTemporaryDirectory(async (dir) => {
+      await writeFile(joinPath(dir, 'shopify.app.toml'), 'client_id = "default"')
+      await writeFile(joinPath(dir, 'shopify.app.staging.toml'), 'client_id = "staging"')
+      const project = await Project.load(dir)
+
+      const config = await selectActiveConfig(project, 'shopify.app.staging.toml')
+
+      expect(config.fileName).toBe('shopify.app.staging.toml')
+      expect(config.file.content.client_id).toBe('staging')
+    })
+  })
+
+  test('throws when requested config does not exist', async () => {
+    await inTemporaryDirectory(async (dir) => {
+      await writeFile(joinPath(dir, 'shopify.app.toml'), 'client_id = "default"')
+      const project = await Project.load(dir)
+
+      await expect(selectActiveConfig(project, 'nonexistent')).rejects.toThrow()
+    })
+  })
+})

packages/app/src/cli/models/project/active-config.ts

@@ -0,0 +1,133 @@
+import {Project} from './project.js'
+import {resolveDotEnv, resolveHiddenConfig} from './config-selection.js'
+import {AppHiddenConfig, BasicAppConfigurationWithoutModules} from '../app/app.js'
+import {AppConfigurationFileName, AppConfigurationState, getConfigurationPath} from '../app/loader.js'
+import {getCachedAppInfo} from '../../services/local-storage.js'
+import use from '../../services/app/config/use.js'
+import {TomlFile} from '@shopify/cli-kit/node/toml/toml-file'
+import {DotEnvFile} from '@shopify/cli-kit/node/dot-env'
+import {fileExistsSync} from '@shopify/cli-kit/node/fs'
+import {joinPath} from '@shopify/cli-kit/node/path'
+
+/** @public */
+export type ConfigSource = 'flag' | 'cached'
+
+/**
+ * The selected app configuration — one specific TOML from the project's
+ * potentially many app config files, plus config-specific derived state.
+ *
+ * A sibling to Project, not a child. Project is the environment;
+ * ActiveConfig is a selection decision applied to that environment.
+ * @public
+ */
+export interface ActiveConfig {
+  /** The selected app TOML file (from project.appConfigFiles) */
+  file: TomlFile
+  /** Absolute path to the config file */
+  path: string
+  /** Filename, e.g., 'shopify.app.staging.toml' */
+  fileName: string
+  /** How the selection was made */
+  source: ConfigSource
+  /** Whether the config has a non-empty client_id */
+  isLinked: boolean
+  /** Config-specific dotenv (.env.staging or .env) */
+  dotenv?: DotEnvFile
+  /** Hidden config entry for this config's client_id */
+  hiddenConfig: AppHiddenConfig
+}
+
+/**
+ * Select the active app configuration from a project.
+ *
+ * Resolution priority:
+ * 1. userProvidedConfigName (from --config flag)
+ * 2. Cached selection (from `app config use`)
+ * 3. Default (shopify.app.toml)
+ *
+ * If the cached config file no longer exists on disk, prompts the user
+ * to select a new one via `app config use`.
+ *
+ * Derives config-specific state: dotenv and hidden config for the selected
+ * config's client_id.
+ * @public
+ */
+export async function selectActiveConfig(project: Project, userProvidedConfigName?: string): Promise<ActiveConfig> {
+  let configName = userProvidedConfigName
+  const source: ConfigSource = configName ? 'flag' : 'cached'
+
+  // Check cache for previously selected config
+  const cachedConfigName = getCachedAppInfo(project.directory)?.configFile
+  const cachedConfigPath = cachedConfigName ? joinPath(project.directory, cachedConfigName) : null
+
+  // Handle stale cache: cached config file no longer exists
+  if (!configName && cachedConfigPath && !fileExistsSync(cachedConfigPath)) {
+    const warningContent = {
+      headline: `Couldn't find ${cachedConfigName}`,
+      body: [
+        "If you have multiple config files, select a new one. If you only have one config file, it's been selected as your default.",
+      ],
+    }
+    configName = await use({directory: project.directory, warningContent, shouldRenderSuccess: false})
+  }
+
+  configName = configName ?? cachedConfigName
+
+  // Resolve the config file name and verify it exists
+  const {configurationPath, configurationFileName} = await getConfigurationPath(project.directory, configName)
+
+  // Look up the TomlFile from the project's pre-loaded files
+  const file = project.appConfigByName(configurationFileName)
+  if (!file) {
+    // Fallback: the project didn't discover this file (shouldn't happen, but be safe)
+    const fallbackFile = await TomlFile.read(configurationPath)
+    return buildActiveConfig(project, fallbackFile, configurationPath, configurationFileName, source)
+  }
+
+  return buildActiveConfig(project, file, configurationPath, configurationFileName, source)
+}
+
+/**
+ * Bridge from the new Project/ActiveConfig model to the legacy AppConfigurationState.
+ *
+ * This allows callers that still consume AppConfigurationState to work with
+ * the new selection logic without changes.
+ * @public
+ */
+export function toAppConfigurationState(
+  project: Project,
+  activeConfig: ActiveConfig,
+  basicConfiguration: BasicAppConfigurationWithoutModules,
+): AppConfigurationState {
+  return {
+    appDirectory: project.directory,
+    configurationPath: activeConfig.path,
+    basicConfiguration,
+    configSource: activeConfig.source,
+    configurationFileName: activeConfig.fileName as AppConfigurationFileName,
+    isLinked: activeConfig.isLinked,
+  }
+}
+
+async function buildActiveConfig(
+  project: Project,
+  file: TomlFile,
+  configPath: string,
+  fileName: string,
+  source: ConfigSource,
+): Promise<ActiveConfig> {
+  const clientId = typeof file.content.client_id === 'string' ? file.content.client_id : undefined
+  const isLinked = Boolean(clientId) && clientId !== ''
+  const dotenv = resolveDotEnv(project, configPath)
+  const hiddenConfig = await resolveHiddenConfig(project, clientId)
+
+  return {
+    file,
+    path: configPath,
+    fileName,
+    source,
+    isLinked,
+    dotenv,
+    hiddenConfig,
+  }
+}