@sanity/runtime-cli 17.8.0 → 17.9.0-blueprinit.g14aaebd

package/skills/init.md

@@ -0,0 +1,199 @@
+# init
+
+Use `init` to scaffold a Blueprint around an existing Sanity project. The command is
+experimental, hidden from root help, and available from the `blueprinit` npm dist-tag.
+
+Use it for demos and evaluation, not as a stable project initializer. Its flags, generated files,
+and resource model may change.
+
+## Know what it does
+
+`init` uses an existing Sanity organization. It uses a project that exists, or creates one with
+`--create-project`. It writes local Blueprint files, then creates an empty organization-scoped
+Stack. The generated Blueprint attaches the project and declares resources for a later deployment.
+
+The dataset works one of two ways:
+
+- **Existing project:** the user picks one of its datasets, and the Blueprint attaches it.
+- **New project:** a new project has no datasets, so the Blueprint creates one. Its name comes from
+  `--dataset` and defaults to `production`. It does not exist until `blueprints deploy` runs.
+
+It does not create an organization. It does not deploy the attached resources, CORS origin, Studio,
+or Function. Those changes happen only if `blueprints deploy` is run later.
+
+## Inspect the target directory
+
+Pass the directory as an argument, or run the command from the directory that should contain the
+Blueprint. Without an argument an interactive run asks where the files go; an unattended run keeps
+the current directory.
+
+Before running:
+
+1. Check the working tree and existing files. Do not discard unrelated user changes.
+2. Look for a root `sanity.blueprint.*` file. If one exists, use the existing Blueprint instead of
+   initializing again.
+3. Look for a root `sanity.config.*` file. Its presence selects the Studio adoption flow.
+4. Confirm the user asked to initialize this directory. The command writes files and creates a
+   remote Stack.
+5. Confirm the user is signed in. If needed, have them run:
+
+```sh
+npx sanity login
+```
+
+The account must have at least one organization. A run against an existing project also needs one
+project in the selected organization and one dataset in that project. A run with `--create-project`
+needs neither.
+
+Interactive runs show the Blueprint resources, hosted Studio URL, local changes, and remote actions
+before the confirmation prompt. Everything the Blueprint declares stays pending until a later
+deployment.
+
+A run that creates a project makes two remote changes rather than one: the project, then the Stack.
+Both happen after the confirmation, so a cancelled run creates nothing. The project is created
+before any file is written, because the generated Studio config needs its ID.
+
+## Choose the flow
+
+- **Existing Blueprint with a configured Stack:** Exit without changes and use
+  `blueprints config --edit` or `blueprints doctor`.
+- **Existing Blueprint without a configured Stack:** Finish setup with `blueprints init`; it can
+  connect the existing manifest without rewriting it.
+- **Root Studio config:** Adopt the Studio in place. Read literal `projectId` and `dataset` strings
+  from `sanity.config.*`, falling back to `sanity.cli.*`. Do not move the Studio.
+- **Fresh workspace:** Create a Blueprint, an npm-workspace Studio, and a starter `set-slug`
+  document function.
+
+Do not rewrite a Studio config merely to make adoption work unless the user asks. Dynamic
+`projectId` or `dataset` values built from environment variables or imports cannot be detected.
+
+For an existing Blueprint, inspect it with:
+
+```sh
+npx @sanity/runtime-cli@blueprinit blueprints doctor
+```
+
+## Run unattended
+
+When the organization and project IDs are known, run this from the target directory:
+
+```sh
+npx @sanity/runtime-cli@blueprinit init --yes \
+  --organization-id <organization-id> \
+  --project-id <project-id> \
+  --dataset <dataset-name>
+```
+
+To create the project instead, replace `--project-id` with `--create-project`:
+
+```sh
+npx @sanity/runtime-cli@blueprinit init --yes \
+  --organization-id <organization-id> \
+  --create-project "<project display name>" \
+  --dataset <dataset-name>
+```
+
+`--create-project` and `--project-id` cannot both be passed. With `--create-project`, `--dataset`
+names a dataset to create and defaults to `production`.
+
+Replace all placeholders with real values. The project must belong to the organization, and the
+dataset must belong to the project. Do not guess any value.
+
+`--yes` skips confirmation. Without explicit values, an unattended run stops when the account has
+several organizations, projects, or datasets. Ask the user for the missing value or have them run
+the command interactively.
+
+Use `--stack-name <name>` and `--studio-name <name>` when those generated names need to be stable.
+The command normalizes both names to lowercase kebab case.
+
+The Stack name defaults to `<project>-<dataset>` and is also the hosted Studio slug, so it must be
+available across every Sanity organization. No API reports whether a slug is free, so a taken one
+fails during `blueprints deploy`.
+
+The Studio name is a Blueprint-local resource name and its directory under `studios/`. It defaults
+to `studio`. Every other generated name carries its resource type, so the defaults cannot collide.
+A dataset named `studio`, or `--studio-name production` against a `production` dataset, does
+collide; the command names the repeated value and writes nothing.
+
+When `SANITY_INTERNAL_ENV=staging`, the generated Studio URL and CORS origin use
+`https://<stack-name>.studio.sanity.work`. Other environments use
+`https://<stack-name>.sanity.studio`.
+
+For interactive organization, project, dataset, Stack-name, and confirmation prompts, have the
+user run:
+
+```sh
+npx @sanity/runtime-cli@blueprinit init
+```
+
+When the project has several datasets, the interactive command prompts for one and lists
+`production` first. Report the selected dataset from the command output.
+
+## Review the result
+
+A successful fresh run creates or updates:
+
+```text
+.
+├── .sanity/blueprint.config.json
+├── sanity.blueprint.ts
+├── package.json
+├── functions/
+│   └── set-slug/
+└── studios/
+    └── studio/
+```
+
+The command also creates or updates `.gitignore`. It preserves existing package metadata and adds
+the required npm workspaces and `@sanity/blueprints` dependency.
+
+The generated Studio matches `sanity init`: the same `sanity`, `@sanity/vision`, `react`,
+`react-dom`, `styled-components`, `@types/react`, and `typescript` versions, the same
+`tsconfig.json`, and `visionTool()` beside `structureTool()`. `sanity` and `@sanity/vision` are
+resolved from the registry at scaffold time, so no version is written into this repository.
+The Studio has no `deploy` script, because the Blueprint deploys it.
+
+An adopted Studio stays at the repository root. The command adds the Blueprint, Blueprint config,
+dependency, and `.gitignore` entry, but does not generate the starter Function.
+
+After the command exits:
+
+1. Confirm the output names the expected organization, project, and dataset.
+2. Confirm `.sanity/blueprint.config.json` exists. Its presence means Stack creation completed.
+3. Review `sanity.blueprint.ts`, including the Studio slug and credentialed CORS origin, plus
+   `package.json`, `.gitignore`, and the working-tree diff.
+4. Report the Stack ID and every created or modified path.
+
+Do not deploy as part of initialization unless the user separately asks for deployment. To continue
+after reviewing the scaffold, install dependencies and preview the deployment:
+
+```sh
+npm install
+npx @sanity/runtime-cli@blueprinit blueprints plan
+```
+
+Treat dependency installation and planning as separate follow-up actions when they were not part of
+the user's request.
+
+## Handle failures
+
+- **`No Sanity session found.`** Stop and ask the user to run `npx sanity login`. Authentication
+  fails before files are written.
+- **Multiple organizations or projects found.** Rerun with the matching `--organization-id` and
+  `--project-id`. Selection fails before files are written.
+- **No datasets found.** Ask the user to choose a project with a dataset, or to create a project
+  with `--create-project`, which makes the Blueprint create the dataset too.
+- **No projects found in an organization.** In an unattended run, pass `--create-project <name>`.
+- **Dataset name is not valid.** The projects API allows 2 to 64 characters from `a-z`, `0-9`, `-`,
+  and `_`, starting with a letter or a digit. Report the rule and ask for another name. Do not
+  rewrite the name the user gave.
+- **Could not create project.** Nothing was written. Report the API message. A quota error needs a
+  plan change or another organization.
+- **Could not read `projectId` and `dataset`.** The detected Studio config does not contain both
+  values as string literals. Pass explicit `--project-id` and `--dataset` values or report the config
+  file and let the user decide whether to change it.
+- **Refusing to overwrite an existing path.** Inspect the reported Studio or Function directory.
+  Do not delete or replace it without the user's direction.
+- **Stack quota or duplicate-name error.** Local scaffold files may already exist while
+  `.sanity/blueprint.config.json` does not. Resolve the Stack error, then run the recovery command
+  printed by `init`, which is `blueprints init`. It connects the existing manifest without rewriting it.