@anyday/sanity-workspace-manager 0.1.0 → 0.2.0

package/README.md

@@ -1,51 +1,169 @@
 # @anyday/sanity-workspace-manager
 
-Drafts a site repo's `workspace-manager.json`, the manifest that tells the workspace manager how
-to set up sites for that project type. See [docs/project-config.md](https://github.com/anydayagency/anyday-workspace-manager-sanity/blob/main/docs/project-config.md).
+The command-line tool for Anyday's Sanity workspace manager. The workspace manager creates a new
+Sanity workspace for a site in a few clicks: the project, its dataset, starter or copied content,
+the brand, the central Studio entry and the Vercel site. It holds no code for any one project.
+Each kind of site (a **project type**) is described instead by a `workspace-manager.json` manifest
+that lives in that site's repo.
+
+This tool writes and saves that manifest:
+
+- **`init`** drafts `workspace-manager.json` from the site repo, its Sanity schema and, optionally,
+  the live Sanity project, then lists what it guessed so you can review it.
+- **`register`** checks the manifest and saves it to the workspace manager, which then offers the
+  project type in the Workspaces app.
+
+## Requirements
+
+- Node.js 20 or later.
+- A Sanity login: run `npx sanity login` once, or set `SANITY_AUTH_TOKEN`.
+- For `register`, the **Administrator** role in the manifest's Sanity organisation.
+
+## Quick start
+
+From the root of the site repo:
+
+```bash
+# 1. Export the Studio's schema (writes sanity.schema.json)
+cd studio && npx sanity schema extract && cd ..
+
+# 2. Draft the manifest from the repo and the live project; it lists the site's pages to pick
+#    starter content from
+npx @anyday/sanity-workspace-manager init --live
+
+# 3. Review workspace-manager.json, then commit it next to the schema
+
+# 4. Save it to the workspace manager
+npx @anyday/sanity-workspace-manager register --api https://anyday-workspace-manager-sanity-api.vercel.app
+```
 
 ## init
 
 ```bash
-# in the site repo's Studio: writes sanity.schema.json
-npx sanity schema extract
+npx @anyday/sanity-workspace-manager init [dir] [options]
+```
+
+`dir` is the site repo, and defaults to the current folder. `init` asks four questions, each with a
+suggestion you can accept with Enter:
+
+| Question                                    | Suggested from                                                     |
+| ------------------------------------------- | ------------------------------------------------------------------ |
+| Project type id, short and lowercase        | The repo name in the git remote, e.g. `acme-site`                  |
+| Name shown in the app                       | The same repo name, capitalised                                    |
+| Sanity project to copy schemas from         | A `projectId: '…'` written in the Studio's config, if there is one |
+| Sanity organisation to create workspaces in | Looked up from that project with your login                        |
+
+The id is permanent: jobs store it and it prefixes each site's Vercel project. Registering a
+different id later creates a second project type instead of updating this one.
 
-# in the site repo: asks for the id, title and schema project
-npx @anyday/sanity-workspace-manager init
-npx @anyday/sanity-workspace-manager init --live --starter home,about,contact
+### What it reads
+
+| Source                          | Used for                                                                                             |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| git remote and default branch   | `site.repo`, `site.branch`, the suggested id and name                                                |
+| `.env.example`, names only      | `siteEnv`, the variables each new site needs                                                         |
+| `sanity.schema.json`            | copy sections, singletons, home page, language documents, settings fields, colour and font templates |
+| the live project, with `--live` | theme defaults, colour defaults and starter pages                                                    |
+
+`sanity.schema.json` is looked for in the repo root, `frontend`, `web`, `site`, `studio`, `apps`
+and each folder in `apps`.
+
+### Options
+
+| Option              | Does                                                                                            |
+| ------------------- | ----------------------------------------------------------------------------------------------- |
+| `--yes`             | Accepts the suggested id, name and project without asking                                       |
+| `--project <id>`    | The Sanity project new workspaces copy their schema from                                        |
+| `--org <id>`        | The Sanity organisation new workspaces are created in (found with `--live`)                     |
+| `--live`            | Reads the current theme, settings and starter pages from that project                           |
+| `--dataset <name>`  | The dataset `--live` reads (default `production`)                                               |
+| `--starter <pages>` | Starter pages without the list: `home`, slugs or document ids, comma-separated (needs `--live`) |
+| `--force`           | Replaces an existing `workspace-manager.json`                                                   |
+| `--print`           | Prints the draft instead of writing it                                                          |
+
+### Starter pages
+
+Starter pages are what a new workspace starts with when it doesn't copy another workspace. With
+`--live`, `init` lists the live site's pages in the home page's language, home first:
+
+```text
+Pages of the live site:
+  1. Home (/home)  ← home
+  2. About Olive (/about-olive)
+  3. Accessibility (/accessibility)
+Starter pages, by number (e.g. 1,3; Enter for one empty home page):
 ```
 
-From a clone of this repo, without npm: `npm run cli -- init ../my-site`.
+Pick by number, or press Enter for one empty home page. To skip the list, name the pages with
+`--starter`: `home` means whichever page the settings mark as the home page, and any other entry
+is a page's slug or document id, e.g. `--starter home,about-olive`. When translations share a
+slug, the home page's language wins. With `--yes` and no `--starter`, the starter is one empty
+home page.
 
-| Reads                         | For                                                                                                  |
-| ----------------------------- | ---------------------------------------------------------------------------------------------------- |
-| git remote and default branch | `site.repo`, `site.branch`, the suggested id and title                                               |
-| `.env.example` (names only)   | `siteEnv`                                                                                            |
-| `sanity.schema.json`          | copy sections, singletons, home page, language documents, settings fields, colour and font templates |
-| the live project (`--live`)   | theme defaults, colour defaults, starter pages (`--starter <ids>`)                                   |
+Starter pages get `{{siteName}}` and `{{language}}` where the source site's name and language
+were. Font files are never copied into theme defaults, since fonts are often licensed per brand.
 
-`--live` signs in with `SANITY_AUTH_TOKEN`, or the token `npx sanity login` saved. Starter pages
-get `{{siteName}}` and `{{language}}` where the source site's own name and language were.
+### Review before registering
 
-The draft is checked against the manifest schema before it is written. Every guess is listed
-afterwards: review them, in particular the copy sections, which start as every content type.
-`--print` shows the draft without writing it.
+The draft is checked against the manifest's JSON Schema before it is written, and every guess is
+listed afterwards. Check these in particular:
+
+- **Copy sections** start as every content type. Keep only the ones editors should be able to copy
+  between workspaces.
+- **Starter pages** must not link to documents outside the starter: a new workspace won't have
+  them, and saving the page fails. `init` names any such links.
+- **Colour roles** come with empty descriptions. Add a short one each, saying where the colour is
+  used, so whoever sets up a brand knows what they are picking.
+- **Language documents and singletons** are guessed from type names (`…Settings`, `l10n.locale`).
 
 ## register
 
 ```bash
-# in the site repo, once its workspace-manager.json is reviewed and committed
-npx @anyday/sanity-workspace-manager register --api https://anyday-workspace-manager-sanity-api.vercel.app
+npx @anyday/sanity-workspace-manager register [dir] --api <url>
 ```
 
-Checks the manifest, then saves it through the API signed in as you (`SANITY_AUTH_TOKEN` or
-`npx sanity login`). You must be an Administrator of the manifest's `organizationId`.
-Registering again replaces the saved copy for that `id`; a different `id` adds a new project type.
-Set `WORKSPACE_MANAGER_API_URL` to skip `--api`; locally, `npm run dev:api` serves it on
-`http://localhost:3100`.
+Checks `workspace-manager.json` in `dir` (default: the current folder) and saves it to the
+workspace manager. The live API is `https://anyday-workspace-manager-sanity-api.vercel.app`; set
+`WORKSPACE_MANAGER_API_URL` to skip `--api`.
+
+- You must be an **Administrator** of the manifest's `organizationId`.
+- Registering again replaces the saved copy for that `id`, so a changed manifest needs no delete
+  first.
+- It prints `Registered <name> (<id>)` when saved.
+
+## Signing in
+
+Both commands use `SANITY_AUTH_TOKEN` when it is set, and otherwise the token `npx sanity login`
+saved. Use your own login: the workspace manager refuses robot tokens for `register`, so that
+every project type traces back to a person. If a robot token is exported in your shell (for
+example for a Studio deploy), `unset SANITY_AUTH_TOKEN` before registering.
+
+## Troubleshooting
+
+| Message                                               | Fix                                                                |
+| ----------------------------------------------------- | ------------------------------------------------------------------ |
+| `No sanity.schema.json`                               | Run `npx sanity schema extract` in the Studio folder               |
+| `workspace-manager.json exists: pass --force`         | Add `--force` to replace it, or `--print` to compare               |
+| `--starter needs --live`                              | Add `--live`; starter pages are read from the live project         |
+| `Pass --api <url> or set WORKSPACE_MANAGER_API_URL`   | Add `--api https://anyday-workspace-manager-sanity-api.vercel.app` |
+| `Use your own Sanity login, not a robot token`        | `unset SANITY_AUTH_TOKEN` and use `npx sanity login`               |
+| `Register only as an Administrator of organisation …` | Ask an Administrator of that organisation to run `register`        |
+
+## How it fits together
+
+The full design, including every manifest field, is in
+[docs/project-config.md](https://github.com/anydayagency/anyday-workspace-manager-sanity/blob/main/docs/project-config.md),
+and an overview in
+[docs/how-it-works.md](https://github.com/anydayagency/anyday-workspace-manager-sanity/blob/main/docs/how-it-works.md)
+(Anyday's GitHub organisation only).
+
+## Developing and publishing
 
-## Publishing
+From a clone of the workspace manager repo, run the CLI without npm:
+`npm run cli -- init ../my-site`. `npm run build` bundles `src/cli.ts`, with the manifest code it
+borrows from the API, into `dist/cli.mjs`; only `@sanity/client` and `ajv` stay dependencies.
 
-`npm run build` bundles `src/cli.ts` and the manifest code it borrows from the API into
-`dist/cli.mjs`; only `@sanity/client` and `ajv` stay dependencies. Bump `version`, then from
-this folder run `npm publish --access public --auth-type=web` (it builds and tests first; the
-web sign-in covers npm's two-factor check).
+Publish from `main`: bump `version`, then run
+`npm publish --workspace=@anyday/sanity-workspace-manager --access public --auth-type=web` from the
+repo root. It builds and tests first; the web sign-in covers npm's two-factor check, and the
+release then waits for approval on npmjs.com.

package/dist/cli.mjs

@@ -642,7 +642,7 @@ function draftStarter(schema, home, live, note) {
   const page = { _id: "starter-home", _type: type };
   if ("title" in fields) page.title = "{{siteName}}";
   if ("language" in fields) page.language = "{{language}}";
-  note("Starter is one empty home page: pass --starter <ids> with --live to copy real pages");
+  note("Starter is one empty home page: run with --live to pick real pages instead");
   return { homeId: "starter-home", documents: [page] };
 }
 function draftBrand(schema, home, live, note) {
@@ -792,15 +792,27 @@ async function organizationOf(projectId, token) {
   if (!response.ok) throw new Error(`Couldn't read project ${projectId}: ${response.status}`);
   return (await response.json()).organizationId ?? "";
 }
+var liveClient = ({ projectId, dataset, token }) => createClient({
+  projectId,
+  dataset,
+  token,
+  apiVersion: "2026-08-15",
+  useCdn: false,
+  perspective: "published"
+});
+async function listPages(options) {
+  const { settings, pages } = await liveClient(options).fetch(
+    `{
+      "settings": *[_id == $settingsId][0],
+      "pages": *[_type == $type && defined(slug.current)]{_id, title, "slug": slug.current, language}
+    }`,
+    { settingsId: options.home.documentId, type: options.pageType }
+  );
+  const homeId = settings?.[options.home.field]?._ref ?? null;
+  return { pages, homeId };
+}
 async function readLive(options) {
-  const client = createClient({
-    projectId: options.projectId,
-    dataset: options.dataset,
-    token: options.token,
-    apiVersion: "2026-08-15",
-    useCdn: false,
-    perspective: "published"
-  });
+  const client = liveClient(options);
   const docs = await client.fetch("*[_id in $ids]", {
     ids: [options.settingsId, options.themeId, ...options.starterIds]
   });
@@ -861,6 +873,39 @@ function readRepo(root) {
   };
 }
 
+// src/init/starter.ts
+function resolveStarter(entries, pages, homeId) {
+  const home = pages.find((page) => page._id === homeId);
+  return entries.map((entry) => {
+    if (entry === "home") {
+      if (!homeId) throw new Error("The live settings name no home page: pass its slug instead");
+      return homeId;
+    }
+    if (pages.some((page) => page._id === entry)) return entry;
+    let matches = pages.filter((page) => page.slug === entry);
+    if (matches.length > 1 && home?.language)
+      matches = matches.filter((page) => page.language === home.language);
+    if (matches.length === 1) return matches[0]._id;
+    if (!matches.length) throw new Error(`No page with the slug or id "${entry}"`);
+    throw new Error(
+      `Several pages have the slug "${entry}": pass one of ${matches.map((page) => page._id).join(", ")}`
+    );
+  });
+}
+function pickable(pages, homeId) {
+  const home = pages.find((page) => page._id === homeId);
+  const shown = home?.language ? pages.filter((page) => page.language === home.language) : pages;
+  return [...shown].sort(
+    (a, b) => a._id === homeId ? -1 : b._id === homeId ? 1 : (a.title ?? "").localeCompare(b.title ?? "")
+  );
+}
+function parsePick(answer, count) {
+  const picked = answer.split(/[\s,]+/).filter(Boolean).map((part) => Number(part));
+  const wrong = picked.filter((n) => !Number.isInteger(n) || n < 1 || n > count);
+  if (wrong.length) throw new Error(`Pick numbers from 1 to ${count}`);
+  return [...new Set(picked)].map((n) => n - 1);
+}
+
 // src/register.ts
 import { readFileSync as readFileSync3 } from "node:fs";
 import { join as join3 } from "node:path";
@@ -896,7 +941,8 @@ Options:
   --org <id>         The Sanity organisation new workspaces are created in (found with --live)
   --live             Read the current theme, settings and starter pages from that project
   --dataset <name>   Dataset to read with --live (default: production)
-  --starter <ids>    Comma-separated document ids to use as starter content (needs --live)
+  --starter <pages>  Comma-separated pages to copy as starter content: \`home\`, slugs or
+                     document ids (needs --live; without it, --live offers a list to pick from)
   --force            Overwrite an existing workspace-manager.json
   --print            Print the draft instead of writing it
 
@@ -957,13 +1003,22 @@ async function init(argv) {
   };
   let draft = draftManifest(repo, base);
   if (token) {
+    const project = { projectId: answers.project, dataset: values.dataset, token };
+    const { pages, homeId } = await listPages({
+      ...project,
+      pageType: draft.manifest.content.starter.documents[0]._type,
+      home: draft.manifest.content.homePage
+    });
+    const starterIds = values.starter ? resolveStarter(
+      values.starter.split(",").map((entry) => entry.trim()).filter(Boolean),
+      pages,
+      homeId
+    ) : values.yes ? [] : await pickStarter(pickable(pages, homeId), homeId);
     const live = await readLive({
-      projectId: answers.project,
-      dataset: values.dataset,
-      token,
+      ...project,
       settingsId: draft.manifest.brand.settings.documentId,
       themeId: draft.manifest.brand.theme.documentId,
-      starterIds: values.starter?.split(",").map((id) => id.trim()).filter(Boolean) ?? []
+      starterIds
     });
     draft = draftManifest(repo, base, live);
   }
@@ -978,7 +1033,7 @@ Check before registering:`);
   for (const note of draft.notes) console.error(`  - ${note}`);
 }
 async function ask(suggested, orgFor) {
-  const prompt = createInterface({ input: process.stdin, output: process.stdout });
+  const prompt = createInterface({ input: process.stdin, output: process.stderr });
   const question = async (label, fallback) => (await prompt.question(`${label}${fallback ? ` (${fallback})` : ""}: `)).trim() || fallback;
   try {
     const id = await question("Project type id, short and lowercase", suggested.id);
@@ -990,6 +1045,23 @@ async function ask(suggested, orgFor) {
     prompt.close();
   }
 }
+async function pickStarter(pages, homeId) {
+  if (!pages.length) return [];
+  console.error("\nPages of the live site:");
+  pages.forEach((page, index) => {
+    const label = `${page.title ?? page._id} (/${page.slug})`;
+    console.error(`  ${index + 1}. ${label}${page._id === homeId ? "  \u2190 home" : ""}`);
+  });
+  const prompt = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = await prompt.question(
+      "Starter pages, by number (e.g. 1,3; Enter for one empty home page): "
+    );
+    return parsePick(answer, pages.length).map((index) => pages[index]._id);
+  } finally {
+    prompt.close();
+  }
+}
 var commands = {
   init,
   register: registerCommand

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anyday/sanity-workspace-manager",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Drafts a site repo's workspace-manager.json for the Anyday workspace manager",
   "repository": {
     "type": "git",