fix: parity round 4 (override-config, worktree mounts, logs, local Features, upgrade)

docs/migration.md

@@ -86,6 +86,36 @@ runs the official CLI is unaffected:
   matching container.
 - Features are staged under `<tmp>/devcontainercli-<user>/container-features/`,
   one folder per build, and that folder is kept as the official CLI keeps it.
+- When the workspace is a Git worktree and the configuration sets both
+  `workspaceMount` and `workspaceFolder`, `up` no longer mounts the main
+  repository's Git common directory, and `read-configuration` no longer reports
+  `additionalMountString`, as in the official CLI v0.89.0. With only
+  `workspaceMount` set, the common directory is mounted under
+  `/workspaces/<main repository>/.git` rather than under the custom mount's
+  target. Earlier releases carried an unreleased upstream change (#1261) instead.
+  A configuration that needs Git inside the container this way should add the
+  common directory to `mounts` itself.
+- A `${containerEnv}` reference without a variable name fails `up`, `set-up`,
+  `run-user-commands`, `exec` and `read-configuration` with exit 1 and
+  `'${containerEnv}' in <file> can not be resolved because no environment
+  variable name is given.`, as the official CLI does. Earlier releases reported
+  success for most of them. Name the variable, as in `${containerEnv:PATH}`.
+- `exec` reads the configuration `--config` or `--override-config` names, also
+  with `--container-id` and no `--workspace-folder`, and exits 1 when it is
+  missing (`Dev container config (<path>) not found.`) or cannot be loaded.
+  Earlier releases ignored those flags without a workspace folder and ran the
+  command despite a configuration error.
+- `read-configuration` looks up the workspace's container (or the one
+  `--id-label` names) as the official CLI does, and exits 1 with nothing on
+  stdout when that lookup fails, including when no Docker engine is reachable.
+  Earlier releases ignored the failure and printed the configuration. Run it
+  where the Docker engine answers.
+- A local Feature (`./x`) must live inside the workspace's `.devcontainer/`
+  folder, as in the official CLI. `build`, `up`, `read-configuration` and
+  `upgrade` now exit 1 with `ERR: Feature './x' could not be processed. ...` for
+  `../x`, an absolute path, or `./x` next to a `.devcontainer.json` at the
+  workspace root, where earlier releases resolved the folder next to the
+  configuration. Move the Feature's folder under `.devcontainer/`.
 - `build` on a Docker Compose configuration without `--image-name` reports
   `"imageName"` as the image's name, a string, as the official CLI does. Earlier
   releases wrapped it in an array. With `--image-name`, and for image and
@@ -110,6 +140,39 @@ runs the official CLI is unaffected:
   `--frozen-lockfile` instead.
 - `upgrade` always rewrites the lockfile in its canonical form, even when the
   existing one differs only in formatting.
+- `upgrade --log-level` accepts only `error`, `info`, `debug`, and `trace`. Any
+  other value exits 1 with `Invalid value "<value>" for --log-level` instead of
+  running at the default level.
+- `upgrade --config` naming a file that does not exist reports
+  `Dev container config (<path>) not found.` instead of the operating system's
+  read error. The exit code stays 1.
+- `upgrade` no longer logs `Lockfile updated.` on stderr after writing the
+  lockfile, and starts its log with the version header once the configuration
+  loads, as the official CLI does. Check the exit code to tell whether the
+  lockfile was written.
+- `upgrade` on a configuration without Features exits 1 with
+  `Failed to update lockfile` and writes no lockfile, with or without
+  `--dry-run`. Earlier releases wrote or printed `{"features":{}}` and exited 0.
+  Skip `upgrade` for configurations that use no Features.
+- `upgrade` resolves Features the way `build` does. A Feature whose manifest or
+  content cannot be fetched fails the command (exit 1,
+  `ERR: Feature '<id>' could not be processed. ...`) instead of being left out
+  of the lockfile. The lockfile also lists the Features that other Features
+  depend on, with each entry's `dependsOn`, so it matches the one `build` and the
+  official CLI write. Make every Feature reachable, with registry credentials
+  where needed, before running `upgrade`.
+- `upgrade --feature <id> --target-version <version>` rewrites the Feature's
+  key in `devcontainer.json` to `<id without version>:<version>`, even with
+  `--dry-run`, before generating the lockfile. Earlier releases validated the
+  two flags but otherwise ignored them. Run it on a clean working tree, or
+  without the flags, when the configuration must stay unchanged.
+- `outdated --output-format json` indents its result only when stdout is a
+  terminal. Redirected or piped, as in a script, it is one unindented line
+  (`{"features":{...}}`) followed by a newline; earlier releases always indented it
+  with two spaces. A script that parses the JSON is unaffected; one that matches
+  lines or greps the indented text should parse the JSON instead (with `jq`, say).
+- `outdated` on a configuration without Features prints its table header alone
+  (`Feature  Current  Wanted  Latest`) instead of `No features configured.`.
 - Only a registry whose host is `localhost` is reached over plain HTTP. Earlier
   releases also used plain HTTP for `127.0.0.1`, which is now addressed over HTTPS
   like any other host. Refer to a local plain-HTTP registry as `localhost:<port>`.