[RFC] (Re)create consistent GAS project for codebase: remote create (multi-developer workflow)

[HoldYourWaffle]

Depends on #989. For simplicity this proposal assumes it has been implemented.

To prevent ambiguity the term "project" in this proposal always refers to a Google Apps Script (GAS) project and "codebase" is used for a local project code folder/repository.

In most multi-developer workflows each developer has their own personal testing environment based on a shared codebase structure.
Unfortunately such a multi-developer workflow is currently not well-supported by clasp, as demonstrated by the discussion in #921.

Private remotes as proposed in #989 would solve a significant portion of the hassle, but the resulting workflow still has a couple of flaws and limitations:

• create implicitly drags some default files into the codebase (Workflow for creating project and pushing existing code #758).
• create with git clone (Workflow for creating project and pushing existing code #758) is unnatural when the codebase is already on your machine.
• Some information for create such as --title and --type are not stored anywhere, so they can't be shared and tracked by version control to create consistent testing environments.
• A combination of create, remote add, push and some juggling with files works, but is unnecessarily complicated and prone to mistakes.

The running theme here is that there's no easy way to reliably and consistently (re)create a GAS project based on the shared structure of a codebase, similar to something like Docker or "Infrastructure as Code".

You could turn to scripting, but that's a treacherous path of system differences and shoddy error handling.
This workflow is so common that I strongly believe it deserves first-party support. Scripting should only be necessary for truly custom scenarios.

Usecases

• Multi-developer workflow (Workflow for multiple devs working in one project #921).
• Push existing codebase to GAS (Workflow for creating project and pushing existing code #758).
• clasp's own testing infrastructure (Tests are broken (access denied to "communal testing project") #987).
• Ephemeral GAS projects for CI testing.
• (Automated) PR staging.

Prior art

• gcloud deployment-manager deployments create.
• terraform apply.
• docker compose up.
  • Note that [RFC] Multiple (private) GAS targets: remotes #989 already covers compose down with remote remove --delete.
• gh codespace create.

Configuration

To consistently (re)create GAS projects some extra information needs to be added to .clasp.json:

• type: store after create/clone.
• title:
  • Ask during create if not specified, suggest name of package.json or the name of the directory of .clasp.json.
  • Use title of cloned project during clone.

New subcommand: remote create

The existing create command is intended to create a new codebase with accompanying GAS project, like you would do on scripts.google.com.
We need a command that creates only a GAS project based on an existing codebase. I propose the following new subcommand:

clasp remote create <name>

This command should handle this workflow in three steps:

1. Add a new remote called <name> to the codebase (private by default).
2. Create a new (empty) GAS project based on .clasp.json.
3. Push the codebase to this new remote.

Options

• All options for remote add should be propagated, except:
  • <scriptId> (newly created)
  • --pull (can't pull from a new project)
• All options for create should be propagated, except:
  • --remote-name (covered by <name>)
  • --remote-default (covered by remote add's --default)
  • --type (read from .clasp.json)
  • --rootDir (using existing codebase)
• --recycle or -r to reuse an existing GAS project with the same title
• --title-suffix to add to the base title, e.g. "MyScript-dev". Defaults to the provided remote <name>, or an empty string if --title is explicitly specified.

Implementation notes

• The title in .clasp.json can be overidden with --title(-suffix), this is not important for the consistency of the testing environment.
• If --title is not explicitly specified the base title of the new GAS project should default to:
  1. title in .clasp.json.
  2. name in package.json.
  3. The dirname of the folder that contains .clasp.json.
• If --title-suffix is set to an empty string no dash should be added.
• Error if a GAS project with the resolved full title already exists, unless --recycle is specified. This avoids accidental data loss.
• --recycle should adjust the existing GAS project to the structure defined in .clasp.json, but preserve existing versions and deployments.
• If --parentId is specified check if the inferred --type matches .clasp.json.

remote create felt more natural than create --empty as proposed in #758, since it explicitly signals creating only a new remote rather than a whole new codebase. Having create behave significantly differently in a folder with a .clasp.json seems undesirable and would probably be a breaking change.

Other considerations

1. Is sharing a codebase across projects with varying type-s a thing? If so, type could be moved/added to the remotes object with some form of shared default setting.