Refuse to convert a 1.x project under an APC context, and give the same advice everywhere

[schnie]

What

There is one project format, and astro init converts a 1.x project to it the same way on every platform. This PR adds the one exception, for now: Astro Private Cloud. APC deploys the 1.x layout (a Dockerfile and .astro/config.yaml, with Astro CLI 1.x) and not yet pyproject.toml projects. The PR also makes every hint about a 1.x project agree with that exception.

The refusal, in pkg/scaffold

scaffold.Plan and scaffold.Run refuse when scaffold.Options.DeploysToAPC is set and the target directory is a 1.x project or lies inside one. They refuse before anything is read or written. The reason for covering directories inside: a project scaffolded inside one (for example astro init dags) would be deployed with it by Astro CLI 1.x.

How the target is matched:

• The walk. scaffold.Find1xProject goes up from the cleaned absolute target to the filesystem root. It stops at any directory that has a manifest, whether it loads or not, and checks that before the 1.x layout, so each step loads the manifest once. Plan then reports that manifest as it always has.
• What counts as a 1.x project. scaffold.Is1xProject, the one definition (the CLI's discovery uses it too), follows what Astro CLI 1.x itself takes for a project. 1.x's config.IsProjectDir (origin/main config/config.go:322) requires .astro/config.yaml, and its deploy requires that through utils.EnsureProjectDir (cmd/utils/utils.go:25). The rule here is:
  • a Dockerfile and a .astro/config.yaml, with no manifest (scaffold.HasManifest);
  • unless that config.yaml is the CLI's own settings file. That means a YAML mapping with no top-level project key, and at least one of context, contexts or telemetry (keys from v2's config.CFG). A 1.x project's always has project (cmd/airflow.go:677 and :680).
  • 1.x tells its home directory apart by path; this tells the settings file apart by content, so a stray ~/Dockerfile beside the settings does not make home a 1.x project, while a home directory that is one (HOME=/usr/local/airflow in a 1.x image) is refused.
  • An empty or unparseable config.yaml counts, as it does for 1.x (fail closed). A missing one does not.
  • A tools-only pyproject.toml does not rule a project out, so a monorepo root does not hide it.

API (additions only; Plan and Run keep their by-value signatures)

• scaffold.Options.DeploysToAPC bool. A caller whose context or platform is APC sets it. The default, false, is today's behaviour.
• scaffold.ErrConvert1xUnderAPC, the sentinel for errors.Is.
• *scaffold.Convert1xUnderAPCError{Dir}, the error value. Dir is the 1.x project's directory, and the message is scaffold.Project1xUnderAPCMessage(Dir).
• scaffold.Is1xProject(dir). internal/project.Is1xProject delegates to it, and project.Project1xUnderAPC delegates to the message function, so there is one check and one message.
• scaffold.Find1xProject(dir), the walk.
• scaffold.Project1xUnderAPCReason(dir), the shared why-it-stays part of the message.
• scaffold.SwitchToAstro, the one "switch to Astro" text: astro context switch astronomer.io, or astro login astronomer.io. A bare astro login logs back in to the current context, which is APC's.
• scaffold.HasManifest(dir). internal/project.HasManifest uses it.

The message

Plain text, naming the 1.x project's directory:

APC deploys that layout and not yet pyproject.toml projects. Leave the project as it is for now: Astro CLI 1.x keeps deploying it to Astro Private Cloud, and converting it will be available once Astro Private Cloud deploys pyproject.toml projects. To convert it anyway, for Astro or for local development only, switch to an Astro context first (astro context switch astronomer.io, or astro login) and run astro init in

.

This holds with or without #2295.

One decision for every hint

project.Convert1xBlocked(dir) returns why init refuses (BlockedUnderAPC, BlockedUnresolved, or NotBlocked) and the 1.x project's root. It checks the context first, so under Astro it walks nothing: init walks nothing there. A hint that names the root under Astro walks for itself. The dev stub calls scaffold.Find1xProject, and Discover tracks the root in its own walk, since no pyproject.toml lies on that path.

NoAstroSectionError works the same way:

• Where init refuses, it says what init says.
• Elsewhere it looks for a 1.x project only between the start and the pyproject's directory. A monorepo root's error names the 1.x project between them, while a plain package's pyproject.toml inside a 1.x tree gets the add-[tool.astro] hint, as on v2. It is built on scaffold.Find1xProject and the one project.SetContext that cmd.Execute records. Every hint asks it, and discovery's errors keep the answer when they are made, so Error() only formats:
• astro init;
• discovery's NotFoundError and NoAstroSectionError, so astro local start and the rest, astro local check and Otto;
• the astro dev stub.

So no hint suggests astro init where init refuses. Every message (project.Blocked1xMessage, and the Astro hints) names the 1.x root and ends "then run astro init in ":

• under an unresolved context it says to fix or switch the context;
• where ASTRO_DOMAIN chose the context, it says to change or unset ASTRO_DOMAIN instead. The table test TestTheDevStubAndInitAgree covers five contexts (APC, APC via ASTRO_DOMAIN, Astro, unresolved, unresolved via ASTRO_DOMAIN), each at a 1.x root, a subdirectory, and a fresh directory. It checks that the stub and init agree, that the stub's note is init's own message, and that v1_dir is the root.

The CLI

Kind and exit code. The refusal is not a mistake in the command line, so it is not usage. It publishes a new documented kind, unsupported_on_platform (exit 1), listed in docs/architecture.md. Execute's unknown-command tracking runs only for usage errors, so it does not run here.

Platform detection (contextPlatform in cmd). cmd.Execute sets it once, on the real CLI path only, through project.SetUnderAPC and project.SetContextUnresolved. The cases:

Situation	Result
ASTRO_DOMAIN names an Astro domain	Astro, before anything else, even with an unreadable config
No context named, by the home config or ASTRO_DOMAIN (a fresh machine)	Astro: converts as today
A context that resolves	APC unless its domain is Astro's
A home config that cannot be read (new config.HomeConfigUnreadable)	unresolved; the message names the file and says to fix or move it, never to change the context
A named context the config does not hold, for a domain that is not Astro's	unresolved

contextPlatform reads only the current domain and whether a context for it is saved (config.Context.ContextExists), never a login, so startup never reaches the keyring; a test pins that. Where ASTRO_DOMAIN chose an APC context, the advice is to set it to an Astro domain (astronomer.io). It adds "or unset it" only when the saved current context is Astro, or there is none (Context.UnsetIsAstro).

When the context is unresolved, astro init refuses the same directories, with the same kind. The message names the 1.x project as the reason, and says to fix the context or switch to one (astro context list, then astro context switch), then rerun astro init in the directory given. Desktop's API stays the one bool.

Notice. A successful init under APC, or under an unresolved context, prints one line on stderr, in text mode only (project.NewProjectNotice). It is worded for that context, and for whether ASTRO_DOMAIN chose it. A successful init always means it wrote a new manifest (created, or [tool.astro] adopted into a pyproject.toml). The notice is not in Result.Notes and not in json.

No double walk. On the CLI path, init has already refused by the time scaffold runs, so it does not set opts.DeploysToAPC; that field is for Desktop.

The astro dev stub. It finds the nearest enclosing 1.x root in every context. v1_project now means inside a 1.x project, and the new v1_dir names its root. The golden gains v1_dir and context_unresolved.

• Under Astro, the convert advice names the root. From below it, the convert command is astro init <root>, in convert and in the text alike. The path is quoted by scaffold.ShellQuote, which astro config's suggestions now share: POSIX single quotes where quoting is needed, with backslashes safe on Windows, so an ordinary path such as C:\proj prints bare. astro dev init's replacement stays plain astro init, and the text offers both, naming the convert command once: "Use astro init to make a new project here, or astro init <root> to convert the 1.x project at in place."
• astro local init, astro af init and astro airflow init redirect to astro init. Where init refuses, they give its refusal instead.
• Where init refuses, it names no replacement and its text lists no astro local commands; the notes, which are init's message, are the whole answer.
• Its json then has under_apc or context_unresolved set, the same notes, and an empty mapping.

Scope

cmd/root.go, cmd/local/root.go and cmd/local/deps.go are as on v2.

Possible follow-up: the parser fixes as their own PR. Two fixes were reverted here: floating /runtime tags read as Airflow 3, and a pin-only Dockerfile's Python flavor carried into requires-python. Review found points such a PR would need to address:

• write requires-python from the tag only when the Dockerfile is retired;
• handle bare runtime: / astro-runtime: names;
• decide how mirrors are treated, since Docker mode accepts only Astronomer's registries;
• never read a non-3 /runtime tag as Airflow 2.

Known and inherited

• The context snapshot. cmd.Execute records the context once, before the tree runs. The one pre-run that changes the context afterwards is followProjectPreRun (cmd/astro/project_scope.go), which sets ASTRO_DOMAIN to a project's Astro host. It runs only on Astro-tree commands, and it switches from Astro to Astro, so the platform never changes. astro init, the dev stub and the local commands skip the pre-runs entirely. So the snapshot cannot go stale for any decision made here.
• Deploy only pyproject.toml projects in v2 #2295 alignment. Deploy only pyproject.toml projects in v2 #2295's utils.Locate has its own 1.x rule (cmd/utils/utils.go:126: has1xLayout(d) && !isHome(d)). scaffold.Is1xProject is exported, so a follow-up changes that line to if scaffold.Is1xProject(d) { and can drop homeMatcher and its own has1xLayout. Is1xProject loads the manifest once more, which is harmless.
• Fix the project-directory advice #2283 added (core fixes) #2290 conflict. Fix the project-directory advice #2283 added (core fixes) #2290 rewrites internal/project.HasManifest (manifestPresent), and this PR's delegation to scaffold.HasManifest touches the same body. Whichever merges second keeps Fix the project-directory advice #2283 added (core fixes) #2290's validation-error handling inside scaffold.HasManifest, or keeps manifestPresent.
• A localhost context without local.platform set is read as context.IsCloudDomain reads it.
• astro init's refusal is unsupported_on_platform (exit 1). Discovery errors carrying the same advice keep no_project (exit 1).
• Desktop is covered only when it sets scaffold.Options.DeploysToAPC from its platform or context. Plan and Run then refuse a 1.x project, or a directory inside one, under APC with scaffold.ErrConvert1xUnderAPC (the value is a *scaffold.Convert1xUnderAPCError; message: scaffold.Project1xUnderAPCMessage). The message's last step names astro init, a CLI command. An unresolved context is the CLI's own handling; Desktop decides its own.

Follow-ups (not in this PR)

• A tools-only pyproject.toml below a 1.x root: discovery stops there, while the stub's advice walks past it.
• The kind of blocked discovery errors: no_project, versus unsupported_on_platform for init's refusal.
• The isCLISettings content heuristic for the home settings file.
• One shared loop for find1xBetween and scaffold.Find1xProject.
• cmd.exe and PowerShell quoting of printed paths with spaces or quotes (ShellQuote writes POSIX single quotes; ordinary Windows paths print bare).
• astro local init and astro af init under APC now give init's refusal: they are no longer counted by the unknown-command tracking (which counts usage errors only), and they exit 1, not 2.
• test-windows's "Run unit tests" step appears to test only the root package (one coverage line, about 30s), so the cmd and cmd/local suites, TestConfigSuggestionQuotesAValueWithSpaces among them, do not run on Windows.
• Deploy only pyproject.toml projects in v2 #2295's utils.Locate switching to scaffold.Is1xProject.

Docs

docs/install.md, Step 4, covers the rule, directories inside a 1.x project, the unresolved-context refusal, and the settings-file case. docs/architecture.md lists the new kind.

Tests

• pkg/scaffold/apc_test.go:
  • Plan and Run refuse a 1.x root: the error type, sentinel, message and Dir are checked, and nothing is written.
  • Existing, nested and new subdirectories are refused, naming the root. An Astro project in between stops the walk. Without the flag, the root converts.
  • The CLI settings file in a home directory with a stray Dockerfile is not a 1.x project, while a home directory that is a 1.x project is refused from below.
  • Is1xProject cases: a settings file with contexts only, one with telemetry only, a project key beside contexts, a config with no project key, a .astro/ with no config.yaml, an unparseable config.yaml, a tools-only pyproject, a manifest, and the partial layouts.
• cmd/local:
  • The root is refused in text and json, with unsupported_on_platform and exit 1, nothing written, and not usage.
  • astro init from dags/ and astro init fresh inside are refused.
  • The monorepo case and the home-as-project case are refused.
  • An unresolved context refuses a 1.x project and allows a fresh directory.
  • Astro still converts, and a new project under APC has no APC note.
  • TestTheAPCAdviceOn1xProjectsIsOne resets stdout and asserts the json error is the APC advice under APC.
  • The dev stub under APC: no replacement, an empty mapping, and text that is the notes.
  • The kind table and its order are pinned.
• cmd/contextplatform_test.go: no context, Astro, APC, ASTRO_DOMAIN naming an unsaved APC domain or Astro, and an unreadable home config.
• e2e/convert_test.go (tier 0): under a real APC context, init and init dags are refused with exit 1 and one unsupported_on_platform object, and nothing is written. A fresh directory succeeds, with no APC note.

Checks run

• Builds: go build ./..., GOOS=windows go build ./....
• Vet: GOOS=windows go vet on ./cmd/..., internal/project, pkg/scaffold and e2e with -tags e2e.
• Tests: make test, make test-submodules, make test-e2e (tier 0), and go test -race -shuffle=on -count=3 ./cmd/... ./internal/project/....
• Lint: make lint, make lint-submodules, make lint-e2e, make lint-goos, make deadcode.
• git merge-tree is clean against v2, Guard removed 1.x commands in CI, and give bundle create/update/delete -o json #2291 and Deploy only pyproject.toml projects in v2 #2295. Each combination builds, vets and passes the cmd, cmd/local and internal/project tests (plus pkg/scaffold with v2, and cmd/apc with Deploy only pyproject.toml projects in v2 #2295).

Not verified

• No real APC deploy.

[coveralls-official]

Coverage Report for CI Build 38066810338

Warning

Build has drifted: This PR's base is out of sync with its target branch, so coverage data may include unrelated changes.
Quick fix: rebase this PR. Learn more →

Coverage increased (+0.3%) to 57.741%

Details

• Coverage increased (+0.3%) from the base build.
• Patch coverage: 34 uncovered changes across 5 files (197 of 231 lines covered, 85.28%).
• 271 coverage regressions across 14 files.

Uncovered Changes

File	Changed	Covered	%
internal/project/apc.go	75	54	72.0%
cmd/problemkind.go	5	0	0.0%
cmd/local/dev.go	60	57	95.0%
config/config.go	3	0	0.0%
cmd/local/initcmd.go	25	23	92.0%
Total (10 files)	231	197	85.28%

Coverage Regressions

271 previously-covered lines in 14 files lost coverage.

Top 10 Files by Coverage Loss	Lines Losing Coverage	Coverage
cmd/astro/deployment.go	61	93.01%
internal/platform/apc/deploy/deploy.go	46	90.54%
pkg/fileutil/files.go	42	84.13%
cmd/apc/deployment.go	30	94.69%
cmd/otto.go	27	36.11%
cmd/cliout/format.go	26	83.75%
cmd/astro/organization.go	10	96.79%
cmd/auth.go	9	94.12%
cmd/apc/deploy.go	4	97.47%
cmd/api/api.go	4	88.37%

---

Coverage Stats

Relevant Lines:	69644
Covered Lines:	40213
Line Coverage:	57.74%
Coverage Strength:	240.91 hits per line

---

💛 - Coveralls