refactor(config): rename config document type ProjectConfig to CliConfig (CLI-2235)

[Coly010]

Summary

Repo-wide vocabulary rename settling @supabase/config's core naming before first npm publish (CLI-2235).

One prefix rule across the package: Cli* = the local checkout side; bare Project* = the hosted Supabase project. After this PR no exported name uses a bare "project" to mean the local checkout, and ProjectConfig is freed for the hosted-project subset type the API-mapping work (CLI-2230 / CLI-2156) will introduce. Renames are only free while the package is private: true, which is why this blocks CLI-2169 (first publish).

No functional behavior changes: the config-file surface (project_id, section names), the generated schema.json, and the schema URL value are unchanged. Four renamed error tags are user-visible and change deliberately with this release: the stderr and --output-format json error code changes (ProjectConfigParseError→CliConfigParseError, ProjectEnvParseError→CliProjectEnvParseError, MissingProjectConfigValueError→MissingCliConfigValueError on malformed-config/env failures, and ProjectHomeNotDirectoryError→CliProjectHomeNotDirectoryError when .supabase/ is blocked by a file or symlink loop), and the telemetry error_fingerprint series fork accordingly (tag:<old> goes flat, tag:<new> starts) — annotate dashboards/alerts keyed on the old values at release. A normalize-error unit test now pins the user-facing codes so the next such rename is a visible review event. Service tag strings were renamed with their services (app-internal identity keys) and moved out of the package's namespace: supabase/config/* → supabase/cli/* for all apps/cli-owned services.

ADRs 0009/0018/0019 keep their pre-rename symbol names as historical records — the tables below are the mapping.

Step 0 — free the CliConfig name (apps/cli)

Old	New
CliConfig (service, tag supabase/config/CliConfig)	CliSettings (tag supabase/cli/CliSettings)
LegacyCliConfig (tag supabase/legacy/CliConfig)	LegacyCliSettings (tag supabase/legacy/CliSettings)
cliConfigLayer, mockCliConfig, cliConfig vars, …	cliSettingsLayer, mockCliSettings, cliSettings, …
cli-config.service.ts / cli-config.layer.ts / legacy-cli-config.*	cli-settings.* / legacy-cli-settings.*

Config-document family (ProjectConfig* → CliConfig*)

Old	New
ProjectConfig, ProjectConfigSchema, ProjectConfigJson, toProjectConfigJsonSchema	CliConfig, CliConfigSchema, CliConfigJson, toCliConfigJsonSchema
loadProjectConfig, loadProjectConfigFile, saveProjectConfig, LoadedProjectConfig, Load/SaveProjectConfigOptions	loadCliConfig, loadCliConfigFile, saveCliConfig, LoadedCliConfig, Load/SaveCliConfigOptions
encodeProjectConfigToJson/Toml, projectConfigValueSourceAt, ProjectConfigValueOrigin/Source	encodeCliConfigToJson/Toml, cliConfigValueSourceAt, CliConfigValueOrigin/Source
ProjectConfigParseError, MissingProjectConfigValueError	CliConfigParseError, MissingCliConfigValueError
ProjectConfigStore, projectConfigStoreLayer (+ file renames)	CliConfigStore, cliConfigStoreLayer (cli-config.service.ts / cli-config.layer.ts)
PROJECT_CONFIG_SCHEMA_URL (value unchanged)	CLI_CONFIG_SCHEMA_URL
getDefaultProjectConfig, subtractProjectConfig	getDefaultCliConfig, subtractCliConfig
compounds re-grepped post-CLI-2231: writeProjectConfig, decodeProjectConfig, ProjectConfigIo, loadFunctionsProjectConfig, renderProjectConfigTemplate, BaseProjectConfig, SparseProjectConfig, …	same names with CliConfig substituted

Local-checkout family (Project* → CliProject*)

Old	New
ProjectEnvironment, loadProjectEnvironment(For), LoadProjectEnvironmentOptions, LiveProjectEnvironment	CliProjectEnvironment, loadCliProjectEnvironment(For), …
ProjectPaths, findProjectPaths(For), FindProjectPathsOptions, findProjectRoot(For/FromRepoState)	CliProjectPaths, findCliProjectPaths(For), …, findCliProjectRoot(…)
ProjectEnvParseError	CliProjectEnvParseError
resolveProjectValue(AtPath), resolveProjectSubtree, ResolvedProjectValue, ResolveProjectOptions — config family: they resolve env() refs in config values	resolveCliConfigValue(AtPath), resolveCliConfigSubtree, ResolvedCliConfigValue, ResolveCliConfigOptions
ProjectContext (apps/cli, tag supabase/config/ProjectContext) + projectContextLayer(For), mockProjectContext, … + file renames	CliProjectContext (tag supabase/cli/CliProjectContext) + cliProjectContextLayer(For), mockCliProjectContext, … (cli-project-context.*)
ProjectHome (apps/cli) + projectHomeLayer(For), ProjectHomeNotDirectoryError, … + file renames	CliProjectHome (tag supabase/cli/CliProjectHome) + cliProjectHomeLayer(For), … (cli-project-home.*)
ProjectLocalServiceVersions (apps/cli) + layer/mocks + file renames	CliProjectLocalServiceVersions (tag supabase/cli/CliProjectLocalServiceVersions) (cli-project-local-service-versions.*)
projectCommandBaseLayer, provideProjectCommandRuntime (apps/cli)	cliProjectCommandBaseLayer, provideCliProjectCommandRuntime
LoadCliConfigOptions.projectEnv (published options field) + the resolveCliConfig* resolvers' projectEnv param	cliProjectEnv (apps/cli-internal CliProjectContext.projectEnv deliberately keeps its name — filed on CLI-2234)

Deliberately unchanged

• DuplicateRemoteProjectIdError / InvalidRemoteProjectIdError — "project id" there genuinely means the hosted project ref (the new meaning of "project"). (remoteProjectConfig, initially kept under the same carve-out, was renamed to remoteCliConfigBlock per review — it binds the reserved ProjectConfig spelling for what is a CliConfig sub-document.)
• packages/api generated names (v2GetProjectConfig, …) — hosted-project endpoint operations.
• Legacy-internal Legacy* / legacy*ProjectEnv* / LegacyLocalProjectContext symbols — already namespaced by their Legacy prefix and pending deletion with the legacy shell.
• Go-source provenance comments (getProjectRoot, internal/utils/misc.go) and apps/cli-go/**.

Docs

packages/config/docs/project-config-loading.md — the doc that defined the old vocabulary — is rewritten as cli-config-loading.md around the final naming, with stale behavioral claims corrected against current source along the way:

• missing env(NAME) resolution does not fail with MissingProjectEnvVarError (that class doesn't exist); the resolvers leave unresolved literals as plain strings
• loadCliConfig substitutes most env(NAME) refs eagerly at load; only functions.<name>.env.* stays literal for on-demand resolution
• supabase init writes a commented config.toml template, not a $schema-only config.json
• managed-stack state lives under global SUPABASE_HOME, not repo-local .supabase/

Review round 1 (2026-08-25)

Addressed from the multi-pass review:

• Truthful user-visible statement (above) + normalize-error unit test pinning the error codes.
• Finished the vocabulary in apps/cli/src/next/config/: CliProjectHome, CliProjectLocalServiceVersions, cliProjectCommandBaseLayer/provideCliProjectCommandRuntime. Remaining bare Project* there (ProjectLinkRemote, ProjectLinkState, ProjectRefResolver) describe the hosted project or the link to it — now stated in the vocabulary doc.
• Retagged all apps/cli services out of the package's namespace: supabase/config/* → supabase/cli/* (each tag literal verified single-occurrence).
• remoteProjectConfig → remoteCliConfigBlock; LoadCliConfigOptions.projectEnv → cliProjectEnv (+ resolver params).
• ADR 0009/0018: dated rename addenda (old→new tables + pointer to the vocabulary doc); ADR bodies untouched.
• Docs: README vocabulary blockquote; vocabulary doc gains the /io facade section, LegacyCliSettings bullet, project_id dual-meaning note, corrected SUPABASE_HOME keying + identity.json inventory; CLI-2110 plan doc symbols updated; packages/stack/README.mdcliSettings.supabaseHome; stale comment fixes (paths.ts, project.unit.test.ts, push.handler.ts, run.ts defect strings).

Filed as explicit pre-publish decisions rather than rushed here: /io facade naming convention → CLI-2234; BaseCliConfig as the hosted-diff operand type → CLI-2230.

Linked issue

CLI-2235

• I'm a Supabase maintainer working from a Linear ticket.
• The PR title follows Conventional Commits.

[Coly010]

Multi-pass review of the CLI-2235 rename (engineer / architect / DX lenses), run against head b5c88da72.

Verdict

The mechanical rename is verifiably clean — mergeable as-is on the code. The asks are: make the PR body truthful about the three user-visible error tags (see errors.ts comment), reconcile the docs/ADRs that now contradict the tree, and settle four pre-publish naming judgment calls while they're still free.

What was verified (all passing)

• Reverse-rename proof: replayed all 99 symbol mappings + 12 file renames in reverse over HEAD and diffed against the merge base — only 5 files had residual content (all intentional or flagged inline), and exactly one non-symbol string literal changed in the entire 403-file diff (a test temp-dir prefix, cli-settings.layer.unit.test.ts:15 — flagging only so it's a conscious choice). The reflow commit is genuinely formatting-only.
• Identifier census balances exactly (e.g. loadProjectConfig 167→0 / loadCliConfig 0→167; mockLegacyCliConfig 313→0 / mockLegacyCliSettings 0→313). Zero stragglers of old names outside the declared carve-outs; carve-outs (apps/cli-go, generated packages/api, RemotesSchema, Legacy*) respected. The stringly-typed Effect.catchTag("CliProjectEnvParseError", …) in secrets/set.handler.ts:262 was correctly updated.
• ProjectConfig is genuinely free: no exported binding on any entrypoint (., /io node+bun+browser, /effect); export-surface snapshots are set-equal to the base after reverse-rename — nothing added, removed, or mixed; reordering is the correct consequence of .sort().
• Generated schema.json is byte-identical between merge base and HEAD (built both, diffed: 5,975 lines identical); $schema URL value unchanged; zero changes to any .toml/.json/.snap fixture; supabase init template untouched.
• Checks: types:check across config/cli/e2e/test-helpers/stack, lint, fmt, knip all green; 198/198 config unit, 5,059 CLI unit, 3,251 integration tests pass.
• Doc fact-check: all four corrected behavioral claims in cli-config-loading.md verified true against source — unresolved env() stays literal (project.ts:341-343), eager-vs-deferred interpolation (io.ts:531 / lib/env.ts:29, only functions.<name>.env.* deferred), init writes a commented config.toml (project-init.ts:308), managed state under global SUPABASE_HOME. Also confirmed MissingCliConfigValueError is constructed nowhere, as the doc now says.

Findings not anchorable inline (files outside the diff)

• packages/stack/README.md:48 — cliConfig.supabaseHome missed by the sweep (supabaseHome is a CliSettings field → cliSettings.supabaseHome).
• docs/adr/0009-configuration-schema-and-validation.md:25-30 + docs/adr/0018-sparse-config-subtraction.md — need dated rename notes; details on the AGENTS.md comment.
• docs/superpowers/plans/2026-08-16-cli-2110-managed-port-allocation.md:78,113-134 — live plan (0/44 steps checked) still instructs an implementer to create ProjectConfigValueSource / projectConfigValueSourceAt and extend LoadedProjectConfig — all renamed by this PR. Rename the symbols or mark it superseded.
• apps/cli/src/shared/cli/run.ts:712-714 — the CliConfigStore fallback stub's defect strings still say "unexpected root project config access / file access / write"; these can surface in a crash report naming the freed concept.
• packages/config/src/base.ts:43 — internal const remoteProjectConfig binds the reserved identifier for what is a CliConfig sub-document (leaks into a comment at io.ts:319). Not exported, so low cost — but it's the one name the PR reserves. Suggest remoteCliConfigBlock.

Severity summary

• Should-fix (in this PR): errors.ts claim/telemetry statement · vocabulary-rule exceptions (ProjectHome, ProjectLocalServiceVersions) · ADR 0009/0018 rename notes · cliConfig.workdir comments (×2) · README vocabulary note · CliSettings/CliProjectContext tag namespace.
• Pre-publish judgment calls (decide before first publish, not necessarily here): LoadCliConfigOptions.projectEnv field name · /io facade naming convention · BaseCliConfig as the hosted-diff operand type (the one that's expensive to reverse).
• Nits: everything else inline + the unanchorable list above.

[Coly010]

Review round 1 addressed in 9bebebc + 7f5f92c (replies on every thread). The findings without inline anchors:

• packages/stack/README.md:48 — cliConfig.supabaseHome → cliSettings.supabaseHome. Fixed.
• ADR 0009 / 0018 — dated rename addenda appended (see the AGENTS.md thread).
• CLI-2110 plan doc (docs/superpowers/plans/2026-08-16-…) — agreed it's live, not historical: its symbol references updated to the post-rename names (CliConfigValueSource, cliConfigValueSourceAt, LoadedCliConfig, …).
• run.ts fallback stub defect strings — reworded to unexpected root cli-config access/file access/write so a crash report can't surface the freed concept.
• remoteProjectConfig — accepted your reasoning over the issue's blanket "RemotesSchema internals keep-as-is" carve-out: renamed to remoteCliConfigBlock (+ the io.ts comment). It was the one binding of the reserved spelling left in the tree.
• Temp-dir prefix (cli-settings.layer.unit.test.ts) — conscious choice, kept: it's a filesystem prefix for test isolation, not vocabulary.

Two pre-publish judgment calls filed as explicit decisions rather than rushed here: /io facade naming convention → CLI-2234; BaseCliConfig as the hosted-diff operand type → CLI-2230.

One bonus find from your LoadCliConfigOptions.projectEnv ask: serve.ts passed the option through a conditional spread that bypasses TS excess-property checking, so the field rename silently dropped serve's pre-resolved env — caught by the serve integration suite (the .env.development numeric-env() case), fixed in 9bebebc.

Validation after the round: types:check ×5 projects, config 198 tests, CLI test:core (unit + integration incl. the new normalize-error pins), oxlint, oxfmt, knip — all green with verified exit codes.

[github-actions]

Supabase CLI preview

npx --yes https://pkg.pr.new/supabase/cli/supabase@03ec58fe6994e447031c99d541c9500ced4654f9

Preview package for commit 03ec58f.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:7f5f92c1f9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[avallete]

Before it get cold.