filestate backend currently operates exclusively with stack names.
All its internal pass around just the stack name, and nothing else.
This makes it a bit difficult to add project support to the backend.

This is a refactor in advance of adding project support,
changing the internals of filestate to pass a stack reference around.
It inspects the reference directly for all its operations.

Note: This contains no behavioral changes.
Name and FullyQualifiedName currently both return just the stack name.
In a future change, once project name is incorporated into the object,
FullyQualifiedName will be able to return `organization/$project/$name`.

Extracted from #12134

Co-authored-by: Abhinav Gupta <abhinav@pulumi.com>

This re-adds project support back to the filestate backend.

For backwards compatibility, and to plan for the future,
this requires versioning the storage state.
To do that, we introduce a .pulumi/Pulumi.yaml file
where we hold metadata like the version of the filestate storage
format.
Version 1 is the initial version that introduces project support.

    # .pulumi/Pulumi.yaml
    version: 1

If we ever need to make breaking changes to the storage protocol
we can bump the format version.

Newly initialized states will use the new project-mode format.
Existing states will continue to run in the old, non-project mode.
State can be migrated to the new format with `pulumi state upgrade`,
at which point they will become incompatible with older CLIs.

For more graceful degradation, if an old CLI writes to an upgraded state
the CLI will warn about these files, and recommend re-running upgrade.

Testing:
Some tests inside filestate/backend were duplicated
for legacy and project variants.

Moves pulumiState extraction from a bucket
into a separate independent ensurePulumiMeta function,
reanming the type to pulumiMeta,
and adds unit tests for success and failure cases of this function.

Add a test that validates the warnings we print in project mode
when there are legacy files in the bucket.

The cobra command for 'state upgrade' specifies that
it has one required positional argument.
This isn't true--it takes no arguments, and it does nothing with 'args'.

Switch to NoArgs and add a test.

Refactors the 'state upgrade' command to use
the pattern from #12400 and #11951
and adds unit tests for its core functionality.

Instead of branching different code paths on
whether we're in project mode or not,
define an interface for those specific behaviors
and extract code for those pieces into two separate implementations.

This way, instead of:

    if projectMode { aProject() } else { aLegacy() }
    // ...
    if projectMode { bProject() } else { bLegacy() }
    // ...
    if projectMode { cProject() } else { cLegacy() }

We do:

    var x X
    if projectMode { x = &projectX{} } else { x = &legacyX{} }
    x.a()
    x.b()
    x.c()

Instead of duplciating the logic to read legacy stack files from the
bucket, use the legacyReferenceStore to re-read the old references
and upgrade them to project-level references.

Instead of looking for leftover legacy files in project mode manually,
re-use the legacyReferenceStore logic to find them.

localBackendReference keeps track of the backend
so that it can determine the current project
and shorten the String representation of the reference.

As far as I can tell,
this doesn't need to be "current project at the time of calling String"
and can be "current project when the reference was constructed."
This switch allows us to turn localBackendReference
back into a data-only object.

Let referenceStore decide paths of different files and directories
rather than having the backend decide them
based on whether localBackendReference.project is empty or not.

To make renames from legacy to project-based stacks possible,
we need localBackendReference to track the store that created it,
and use that to determine old and new paths.

We actually need to track the localBackend
because the current project for a localBackend
does change after a reference is parsed.

Includes a test for this change.

These paths are calculated on-demand repeatedly,
but they never change.
There's no reason for these to be bound to the backend implemntation.

Turn them into top-level variables.
(They're not constants because the output of filepath.Join cannot be a
const.)

SetCurrentProject and localBackendReference.String have a data race
in accessing the currentProject field.
Turn it into an atomic.Pointer to address this data race.

Adds a ListProjects methods to the projectReferenceStore
which we re-use in DoesProjectExist and ListReferences
rather than re-implementing that logic.

These don't need to pollute the primary file.
Otherwise, future tests may feel compelled to duplicate for legacy and
project variants.