@anyday/sanity-workspace-manager 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,150 @@
-# Temporary Holding Version
+# @anyday/sanity-workspace-manager
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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, reading theme defaults and three starter pages from the live project
+npx @anyday/sanity-workspace-manager init --live --starter home,about,contact
+
+# 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
+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.
+
+### 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 (`--starter <ids>`)                                |
+
+`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 <ids>`  | Comma-separated document ids to use as starter content (needs `--live`)     |
+| `--force`          | Replaces an existing `workspace-manager.json`                               |
+| `--print`          | Prints the draft instead of writing it                                      |
+
+Without `--starter`, new workspaces start from one empty home page. 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.
+
+### Review before registering
+
+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
+npx @anyday/sanity-workspace-manager register [dir] --api <url>
+```
+
+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
+
+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.
+
+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

@@ -0,0 +1,1006 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { existsSync as existsSync3, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "node:util";
+
+// ../api/src/projects/manifest.ts
+import { Ajv } from "ajv";
+
+// ../api/src/content/color.ts
+function colorValue(hex) {
+  const r = parseInt(hex.slice(1, 3), 16);
+  const g = parseInt(hex.slice(3, 5), 16);
+  const b = parseInt(hex.slice(5, 7), 16);
+  const rn = r / 255;
+  const gn = g / 255;
+  const bn = b / 255;
+  const max = Math.max(rn, gn, bn);
+  const min = Math.min(rn, gn, bn);
+  const d = max - min;
+  const l = (max + min) / 2;
+  let h = 0;
+  if (d !== 0) {
+    if (max === rn) h = (gn - bn) / d % 6;
+    else if (max === gn) h = (bn - rn) / d + 2;
+    else h = (rn - gn) / d + 4;
+    h *= 60;
+    if (h < 0) h += 360;
+  }
+  return {
+    _type: "color",
+    hex,
+    alpha: 1,
+    hsl: { _type: "hslaColor", h, s: d === 0 ? 0 : d / (1 - Math.abs(2 * l - 1)), l, a: 1 },
+    hsv: { _type: "hsvaColor", h, s: max === 0 ? 0 : d / max, v: max, a: 1 },
+    rgb: { _type: "rgbaColor", r, g, b, a: 1 }
+  };
+}
+
+// ../api/src/content/template.ts
+var WHOLE = /^\{\{(\w+)\}\}$/;
+var PLACEHOLDER = /\{\{(\w+)\}\}/g;
+var MissingValue = class extends Error {
+};
+function valueOf(name, values) {
+  const value = values[name];
+  if (value === void 0) throw new MissingValue(`No value for {{${name}}}`);
+  return value;
+}
+function fill(template, values) {
+  if (typeof template === "string") {
+    const whole = template.match(WHOLE);
+    if (whole) return valueOf(whole[1], values);
+    return template.replace(PLACEHOLDER, (_, name) => String(valueOf(name, values)));
+  }
+  if (Array.isArray(template)) return template.map((item) => fill(item, values));
+  if (template && typeof template === "object") {
+    if ("$color" in template) return colorValue(String(fill(template.$color, values)).toLowerCase());
+    return Object.fromEntries(
+      Object.entries(template).map(([key, value]) => [key, fill(value, values)])
+    );
+  }
+  return template;
+}
+
+// ../api/src/content/brand.ts
+var HEX = /^#[0-9a-f]{6}$/i;
+function brandDocuments(spec, brand, homePageId) {
+  const values = {
+    siteName: brand.siteName,
+    language: brand.language,
+    homePageId,
+    domain: brand.domain || void 0,
+    logoAssetId: brand.logoAssetId || void 0,
+    faviconAssetId: brand.faviconAssetId || void 0
+  };
+  const { documentId: settingsId, fields } = spec.settings;
+  const settings = { _id: settingsId, _type: settingsId };
+  for (const [field, template] of Object.entries(fields)) {
+    try {
+      settings[field] = fill(template, values);
+    } catch (error) {
+      if (!(error instanceof MissingValue)) throw error;
+    }
+  }
+  const { documentId: themeId, colorDefault, color, font, fontFace, defaults } = spec.theme;
+  const theme = {
+    _id: themeId,
+    _type: themeId,
+    ...Object.fromEntries(
+      spec.colorRoles.map((role) => [
+        role.role,
+        fill(colorDefault, { hex: role.default, label: role.label })
+      ])
+    ),
+    ...fill(defaults, {})
+  };
+  for (const [role, hex] of Object.entries(brand.colors ?? {})) {
+    if (!HEX.test(hex)) throw new Error(`${role} must be a #rrggbb colour, got "${hex}"`);
+    theme[role] = fill(color, { hex });
+  }
+  for (const [role, faces] of Object.entries(brand.fonts ?? {})) {
+    if (!font || !fontFace) throw new Error("This project type takes no fonts");
+    theme[role] = fill(font, {
+      faces: faces.map((face, index) => fill(fontFace, { ...face, role, index }))
+    });
+  }
+  return { settings, theme };
+}
+
+// ../api/src/provision/language-names.ts
+var tagOf = (code) => {
+  try {
+    return Intl.getCanonicalLocales(code)[0] ?? code;
+  } catch {
+    return code;
+  }
+};
+function englishNameOf(code) {
+  return new Intl.DisplayNames(["en"], { type: "language" }).of(tagOf(code)) ?? code;
+}
+function nativeNameOf(code) {
+  const tag = tagOf(code);
+  try {
+    return new Intl.DisplayNames([tag], { type: "language" }).of(tag) ?? englishNameOf(code);
+  } catch {
+    return englishNameOf(code);
+  }
+}
+
+// ../api/src/projects/workspace-manager.schema.json
+var workspace_manager_schema_default = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://github.com/anydayagency/anyday-workspace-manager-sanity/workspace-manager.schema.json",
+  title: "Workspace manager project type",
+  description: "How the workspace manager sets up sites for one project type. Templates are JSON with {{name}} placeholders; see docs/project-config.md.",
+  type: "object",
+  required: [
+    "id",
+    "title",
+    "organizationId",
+    "site",
+    "siteEnv",
+    "schemaSourceProjectId",
+    "content",
+    "brand"
+  ],
+  additionalProperties: false,
+  definitions: {
+    name: {
+      type: "string",
+      minLength: 1
+    },
+    document: {
+      type: "object",
+      required: ["_id", "_type"],
+      properties: {
+        _id: {
+          type: "string"
+        },
+        _type: {
+          type: "string"
+        }
+      }
+    },
+    hex: {
+      type: "string",
+      pattern: "^#[0-9a-fA-F]{6}$"
+    }
+  },
+  properties: {
+    $schema: {
+      type: "string"
+    },
+    id: {
+      description: "Stable id stored on jobs and used as the Vercel project prefix.",
+      type: "string",
+      pattern: "^[a-z0-9][a-z0-9-]{0,31}$"
+    },
+    title: {
+      $ref: "#/definitions/name"
+    },
+    organizationId: {
+      description: "The Sanity organisation new workspaces are created in.",
+      $ref: "#/definitions/name"
+    },
+    vercelTeamId: {
+      description: "The Vercel team new sites are created in; leave out for the API's default team.",
+      $ref: "#/definitions/name"
+    },
+    site: {
+      type: "object",
+      required: ["repo", "branch", "revalidatePath"],
+      additionalProperties: false,
+      properties: {
+        repo: {
+          description: "owner/name on GitHub",
+          type: "string",
+          pattern: "^[\\w.-]+/[\\w.-]+$"
+        },
+        branch: {
+          $ref: "#/definitions/name"
+        },
+        revalidatePath: {
+          type: "string",
+          pattern: "^/"
+        }
+      }
+    },
+    siteEnv: {
+      description: "Names of the env vars the site reads.",
+      type: "object",
+      required: ["projectId", "dataset", "defaultLocale", "studioWorkspace", "baseUrl"],
+      additionalProperties: false,
+      properties: {
+        projectId: {
+          $ref: "#/definitions/name"
+        },
+        dataset: {
+          $ref: "#/definitions/name"
+        },
+        defaultLocale: {
+          $ref: "#/definitions/name"
+        },
+        studioWorkspace: {
+          $ref: "#/definitions/name"
+        },
+        baseUrl: {
+          $ref: "#/definitions/name"
+        }
+      }
+    },
+    schemaSourceProjectId: {
+      description: "The Sanity project whose latest deployed Studio schema each workspace gets.",
+      $ref: "#/definitions/name"
+    },
+    languages: {
+      type: "object",
+      required: ["document", "setupTypes"],
+      additionalProperties: false,
+      properties: {
+        document: {
+          description: "One language's document. Values: code, codeUpper, englishName, nativeName.",
+          $ref: "#/definitions/document"
+        },
+        setupTypes: {
+          type: "array",
+          items: {
+            $ref: "#/definitions/name"
+          }
+        }
+      }
+    },
+    content: {
+      type: "object",
+      required: ["sections", "singletons", "homePage", "starter"],
+      additionalProperties: false,
+      properties: {
+        sections: {
+          description: "[type, title] pairs the copy picker lists, in order.",
+          type: "array",
+          items: {
+            type: "array",
+            items: [
+              {
+                $ref: "#/definitions/name"
+              },
+              {
+                $ref: "#/definitions/name"
+              }
+            ],
+            minItems: 2,
+            maxItems: 2
+          }
+        },
+        singletons: {
+          type: "array",
+          items: {
+            $ref: "#/definitions/name"
+          }
+        },
+        homePage: {
+          type: "object",
+          required: ["documentId", "field"],
+          additionalProperties: false,
+          properties: {
+            documentId: {
+              $ref: "#/definitions/name"
+            },
+            field: {
+              $ref: "#/definitions/name"
+            }
+          }
+        },
+        starter: {
+          description: "Values: siteName, language.",
+          type: "object",
+          required: ["homeId", "documents"],
+          additionalProperties: false,
+          properties: {
+            homeId: {
+              $ref: "#/definitions/name"
+            },
+            documents: {
+              type: "array",
+              items: {
+                $ref: "#/definitions/document"
+              }
+            }
+          }
+        }
+      }
+    },
+    brand: {
+      type: "object",
+      required: ["colorRoles", "settings", "theme"],
+      additionalProperties: false,
+      properties: {
+        colorRoles: {
+          type: "array",
+          items: {
+            type: "object",
+            required: ["role", "title", "description", "default", "label"],
+            additionalProperties: false,
+            properties: {
+              role: {
+                $ref: "#/definitions/name"
+              },
+              title: {
+                $ref: "#/definitions/name"
+              },
+              description: {
+                type: "string"
+              },
+              default: {
+                $ref: "#/definitions/hex"
+              },
+              label: {
+                type: "string"
+              }
+            }
+          }
+        },
+        settings: {
+          type: "object",
+          required: ["documentId", "fields"],
+          additionalProperties: false,
+          properties: {
+            documentId: {
+              $ref: "#/definitions/name"
+            },
+            fields: {
+              description: "Values: siteName, language, homePageId, domain, logoAssetId, faviconAssetId. A field whose value is missing is left out.",
+              type: "object"
+            }
+          }
+        },
+        theme: {
+          type: "object",
+          required: ["documentId", "colorDefault", "color", "defaults"],
+          additionalProperties: false,
+          properties: {
+            documentId: {
+              $ref: "#/definitions/name"
+            },
+            colorDefault: {
+              description: "Values: hex, label."
+            },
+            color: {
+              description: "Values: hex."
+            },
+            font: {
+              description: "Values: faces. Leave out, with fontFace, if the project takes no fonts."
+            },
+            fontFace: {
+              description: "Values: role, index, family, weight, style, fileAssetId."
+            },
+            defaults: {
+              type: "object"
+            }
+          }
+        }
+      }
+    }
+  }
+};
+
+// ../api/src/projects/manifest.ts
+var validate = new Ajv({ allErrors: true }).compile(workspace_manager_schema_default);
+var InvalidManifest = class extends Error {
+};
+function parseManifest(json) {
+  if (validate(json)) return json;
+  const problems = validate.errors.map((error) => `${error.instancePath || "/"} ${error.message}`);
+  throw new InvalidManifest(`Invalid workspace-manager.json:
+${problems.join("\n")}`);
+}
+function configFrom(manifest) {
+  const { languages, content, brand } = manifest;
+  const codeField = languages && Object.keys(languages.document).find((field) => languages.document[field] === "{{code}}");
+  if (languages && !codeField) {
+    throw new InvalidManifest('languages.document needs a field set to "{{code}}"');
+  }
+  return {
+    id: manifest.id,
+    title: manifest.title,
+    organizationId: manifest.organizationId,
+    ...manifest.vercelTeamId ? { vercelTeamId: manifest.vercelTeamId } : {},
+    site: manifest.site,
+    siteEnv: manifest.siteEnv,
+    schemaSourceProjectId: manifest.schemaSourceProjectId,
+    languageDocument: languages && ((code) => fill(languages.document, {
+      code,
+      codeUpper: code.toUpperCase(),
+      englishName: englishNameOf(code),
+      nativeName: nativeNameOf(code)
+    })),
+    content: {
+      sections: content.sections,
+      singletons: content.singletons,
+      homePage: content.homePage,
+      languages: languages && {
+        type: languages.document._type,
+        codeField,
+        setupTypes: languages.setupTypes
+      },
+      starter: (values) => fill(content.starter.documents, values),
+      starterHomeId: content.starter.homeId
+    },
+    brand: {
+      colorRoles: brand.colorRoles,
+      documents: (values, homePageId) => brandDocuments(brand, values, homePageId)
+    }
+  };
+}
+
+// ../api/src/content/labels.ts
+function humanize(name) {
+  const words = name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([a-z])([0-9])/g, "$1 $2").toLowerCase();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+// src/init/extract.ts
+var PLUGIN_TYPES = /^(sanity\.|system\.|assist\.|media\.tag$|translation\.metadata$|fieldTranslation\.metadata$)/;
+var Extract = class {
+  byName;
+  constructor(types) {
+    this.byName = new Map(types.map((type) => [type.name, type]));
+  }
+  get documents() {
+    return [...this.byName.values()].filter((type) => type.type === "document");
+  }
+  /** Document types an editor makes, not plugins' bookkeeping. */
+  get contentDocuments() {
+    return this.documents.filter((type) => !PLUGIN_TYPES.test(type.name));
+  }
+  has(name) {
+    return this.byName.has(name);
+  }
+  fields(typeName) {
+    const type = this.byName.get(typeName);
+    return type?.attributes ?? (type?.value?.type === "object" ? type.value.attributes : {}) ?? {};
+  }
+  /** The named type an attribute uses, e.g. "themeColor", or null for an inline shape. */
+  inlineName(value) {
+    return value.type === "inline" ? value.name ?? null : null;
+  }
+  referenceTarget(value) {
+    return this.inlineName(value)?.match(/^(.+)\.reference$/)?.[1] ?? null;
+  }
+  /** Where a colour sits: the attribute itself, or a field of the object type it uses. */
+  colorShape(value) {
+    const name = this.inlineName(value);
+    if (name === "color") return "direct";
+    if (!name) return null;
+    const fields = this.fields(name);
+    const field = Object.keys(fields).find((key) => this.inlineName(fields[key].value) === "color");
+    return field ? { wrapper: name, field, label: "label" in fields } : null;
+  }
+  /** An object type holding an array of faces, each with an uploaded file. */
+  fontShape(value) {
+    const family = this.inlineName(value);
+    if (!family) return null;
+    for (const [list, { value: listValue }] of Object.entries(this.fields(family))) {
+      const item = listValue.type === "array" ? listValue.of : void 0;
+      if (!item) continue;
+      const fields = this.attributesOf(item);
+      const face = fields._type?.value.value ?? this.inlineName(item);
+      const file = Object.keys(fields).find(
+        (key) => this.holdsAsset(fields[key].value, "sanity.fileAsset.reference")
+      );
+      if (face && file) return { family, list, face, file, faceFields: Object.keys(fields) };
+    }
+    return null;
+  }
+  isImage(value) {
+    return this.holdsAsset(value, "sanity.imageAsset.reference");
+  }
+  attributesOf(value) {
+    const name = this.inlineName(value);
+    return name ? this.fields(name) : value.attributes ?? {};
+  }
+  holdsAsset(value, reference) {
+    return Object.values(this.attributesOf(value)).some(
+      (inner) => this.inlineName(inner.value) === reference
+    );
+  }
+};
+
+// src/init/draft.ts
+var SYSTEM_FIELDS = /* @__PURE__ */ new Set(["_rev", "_createdAt", "_updatedAt", "_system"]);
+var ENV_DEFAULTS = {
+  projectId: "NEXT_PUBLIC_SANITY_PROJECT_ID",
+  dataset: "NEXT_PUBLIC_SANITY_DATASET",
+  defaultLocale: "NEXT_PUBLIC_DEFAULT_LOCALE",
+  studioWorkspace: "NEXT_PUBLIC_STUDIO_WORKSPACE",
+  baseUrl: "NEXT_PUBLIC_BASE_URL"
+};
+var ENV_PATTERNS = {
+  projectId: /SANITY_PROJECT_ID$/,
+  dataset: /SANITY_DATASET$/,
+  defaultLocale: /DEFAULT_LOCALE$/,
+  studioWorkspace: /STUDIO_WORKSPACE$/,
+  baseUrl: /(BASE|SITE)_URL$/
+};
+function suggestNames(repo) {
+  const name = (repo?.split("/")[1] ?? "site").replace(/\.git$/, "");
+  const id = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32);
+  return { id: id || "site", title: humanize(name.replace(/[-_]+/g, " ").trim()) || "Site" };
+}
+function draftManifest(repo, answers, live = {}) {
+  const notes = [];
+  const note = (message) => void notes.push(message);
+  const schema = new Extract(repo.types);
+  const singletons = schema.contentDocuments.map((type) => type.name).filter((name) => /settings$/i.test(name));
+  if (singletons.length)
+    note(`Singletons guessed from names ending in "Settings": ${singletons.join(", ")}`);
+  else note("No singletons found: list your settings documents in content.singletons");
+  const homePage = findHomePage(schema, singletons);
+  if (homePage) note(`Home page: ${homePage.documentId}.${homePage.field}`);
+  else note("No home page reference found: set content.homePage by hand");
+  const home = homePage ?? { documentId: singletons[0] ?? "siteSettings", field: "homePage" };
+  const languages = draftLanguages(schema, note);
+  const sections = schema.contentDocuments.map((type) => type.name).filter((name) => !singletons.includes(name) && !languages?.setupTypes.includes(name)).map((name) => [name, humanize(name)]);
+  note(`Copy sections list every content type (${sections.length}): remove the ones not to offer`);
+  const siteEnv = Object.fromEntries(
+    Object.entries(ENV_PATTERNS).map(([key, pattern]) => {
+      const matches = repo.envNames.filter((name) => pattern.test(name));
+      const found = matches.find((name) => name.startsWith("NEXT_PUBLIC_")) ?? matches[0];
+      if (!found)
+        note(
+          `No env var for ${key} in .env.example: using ${ENV_DEFAULTS[key]}`
+        );
+      return [key, found ?? ENV_DEFAULTS[key]];
+    })
+  );
+  if (!repo.repo) note("No GitHub remote found: set site.repo to owner/name");
+  if (!repo.hasRevalidateRoute) note("No /api/revalidate route found: check site.revalidatePath");
+  return {
+    manifest: {
+      id: answers.id,
+      title: answers.title,
+      organizationId: answers.organizationId,
+      site: {
+        repo: repo.repo ?? "owner/name",
+        branch: repo.branch ?? "main",
+        revalidatePath: "/api/revalidate"
+      },
+      siteEnv,
+      schemaSourceProjectId: answers.schemaSourceProjectId,
+      ...languages ? { languages } : {},
+      content: {
+        sections,
+        singletons,
+        homePage: home,
+        starter: draftStarter(schema, home, live, note)
+      },
+      brand: draftBrand(schema, home, live, note)
+    },
+    notes
+  };
+}
+function findHomePage(schema, singletons) {
+  for (const documentId of singletons) {
+    const fields = schema.fields(documentId);
+    const field = Object.keys(fields).find(
+      (key) => /home/i.test(key) && schema.referenceTarget(fields[key].value)
+    );
+    if (field) return { documentId, field };
+  }
+  return null;
+}
+var LANGUAGE_FIELDS = {
+  code: "{{code}}",
+  title: "{{englishName}}",
+  name: "{{englishName}}",
+  nativeName: "{{nativeName}}",
+  shortName: "{{codeUpper}}"
+};
+function draftLanguages(schema, note) {
+  const type = schema.contentDocuments.concat(schema.documents).find(
+    (entry) => /(^|\.)(locale|language)$/.test(entry.name) && "code" in schema.fields(entry.name)
+  );
+  if (!type) {
+    note("No language document type found: languages left out");
+    return void 0;
+  }
+  const fields = schema.fields(type.name);
+  const document = {
+    _id: `${type.name.split(".").pop()}-{{code}}`,
+    _type: type.name
+  };
+  for (const [field, value] of Object.entries(LANGUAGE_FIELDS))
+    if (field in fields) document[field] = value;
+  if ("enabled" in fields) document.enabled = true;
+  const prefix = type.name.includes(".") ? `${type.name.split(".")[0]}.` : null;
+  const setupTypes = prefix ? schema.documents.map((entry) => entry.name).filter((name) => name.startsWith(prefix)) : [type.name];
+  note(`Language documents: ${type.name}, ids like ${document._id}; check the id pattern`);
+  return { document, setupTypes };
+}
+function draftStarter(schema, home, live, note) {
+  if (live.starter?.length) {
+    const siteName = siteNameOf(live.settings);
+    const language = live.starter.find((doc) => typeof doc.language === "string")?.language;
+    const ids = new Set(live.starter.map((doc) => doc._id));
+    const documents = live.starter.map((doc) => placeholders(stripSystem(doc), siteName, language));
+    const outside = live.starter.flatMap((doc) => references(doc).filter((ref) => !ids.has(ref)));
+    if (outside.length)
+      note(
+        `Starter pages link to documents not in the starter: ${[...new Set(outside)].join(", ")}`
+      );
+    const liveHome = live.settings?.[home.field]?._ref;
+    const homeId = liveHome && ids.has(liveHome) ? liveHome : live.starter[0]._id;
+    note(`Starter: ${documents.length} documents from the live project, home ${homeId}`);
+    return { homeId, documents };
+  }
+  const homeField = schema.fields(home.documentId)[home.field];
+  const type = (homeField && schema.referenceTarget(homeField.value)) ?? "page";
+  const fields = schema.fields(type);
+  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");
+  return { homeId: "starter-home", documents: [page] };
+}
+function draftBrand(schema, home, live, note) {
+  const settingsFields = schema.fields(home.documentId);
+  const fields = {};
+  const siteName = settingsFields.siteName;
+  if (siteName) {
+    fields.siteName = schema.inlineName(siteName.value) === "internationalizedArrayString" ? [
+      {
+        _key: "{{language}}",
+        _type: "internationalizedArrayStringValue",
+        language: "{{language}}",
+        value: "{{siteName}}"
+      }
+    ] : "{{siteName}}";
+  }
+  fields[home.field] = { _type: "reference", _ref: "{{homePageId}}" };
+  if (settingsFields.domain) fields.domain = "{{domain}}";
+  for (const [field, id] of [
+    ["logo", "logoAssetId"],
+    ["favicon", "faviconAssetId"]
+  ]) {
+    const value = settingsFields[field]?.value;
+    if (!value || !schema.isImage(value)) continue;
+    fields[field] = {
+      _type: "image",
+      asset: { _type: "reference", _ref: `{{${id}}}` },
+      ...field === "logo" && "alt" in (value.attributes ?? {}) ? { alt: "{{siteName}}" } : {}
+    };
+  }
+  const themeType = schema.contentDocuments.find((type) => /theme/i.test(type.name));
+  const themeId = themeType?.name ?? "themeSettings";
+  if (!themeType) note("No theme document found: brand colours and fonts left empty");
+  const themeFields = schema.fields(themeId);
+  let color = { $color: "{{hex}}" };
+  let colorDefault = color;
+  const colorRoles = [];
+  for (const [role, { value }] of Object.entries(themeFields)) {
+    const shape = schema.colorShape(value);
+    if (!shape) continue;
+    if (shape !== "direct") {
+      const wrapped = { _type: shape.wrapper, [shape.field]: { $color: "{{hex}}" } };
+      color = wrapped;
+      colorDefault = shape.label ? { ...wrapped, label: "{{label}}" } : wrapped;
+    }
+    const current = live.theme?.[role];
+    const hex = shape === "direct" ? current?.hex : current?.[shape.field]?.hex;
+    colorRoles.push({
+      role,
+      title: humanize(role),
+      description: "",
+      default: hex ?? "#000000",
+      label: typeof current?.label === "string" ? current.label : humanize(role)
+    });
+  }
+  if (colorRoles.length && !live.theme)
+    note("Colour defaults are #000000: run with --live to read them");
+  const fontShape = Object.values(themeFields).map(({ value }) => schema.fontShape(value)).find(Boolean);
+  const fonts = fontShape ? {
+    font: { _type: fontShape.family, [fontShape.list]: "{{faces}}" },
+    fontFace: {
+      _key: "{{role}}-{{index}}",
+      _type: fontShape.face,
+      ...Object.fromEntries(
+        ["family", "weight", "style"].filter((field) => fontShape.faceFields.includes(field)).map((field) => [field, `{{${field}}}`])
+      ),
+      [fontShape.file]: { _type: "file", asset: { _type: "reference", _ref: "{{fileAssetId}}" } }
+    }
+  } : {};
+  if (!fontShape) note("No font fields found on the theme: fonts left out");
+  const defaults = live.theme ? compactColors(stripSystem(live.theme)) : {};
+  delete defaults._id;
+  delete defaults._type;
+  if (!live.theme) note("Theme defaults are empty: run with --live to copy the current theme");
+  const linked = Object.keys(defaults).filter((field) => hasReference(defaults[field]));
+  for (const field of linked) delete defaults[field];
+  if (linked.length) {
+    note(
+      `Left out of theme defaults, as they point at the source project's files: ${linked.join(", ")}`
+    );
+  }
+  return {
+    colorRoles,
+    settings: { documentId: home.documentId, fields },
+    theme: { documentId: themeId, colorDefault, color, ...fonts, defaults }
+  };
+}
+function siteNameOf(settings) {
+  const value = settings?.siteName;
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value[0]?.value;
+  return void 0;
+}
+function stripSystem(doc) {
+  return Object.fromEntries(Object.entries(doc).filter(([key]) => !SYSTEM_FIELDS.has(key)));
+}
+var I18N_VALUE = /^internationalizedArray\w*Value$/;
+function placeholders(value, siteName, language, key, parent) {
+  if (typeof value === "string") {
+    const isLanguage = language !== void 0 && value === language && (key === "language" || key === "_key" && I18N_VALUE.test(parent?._type ?? ""));
+    if (isLanguage) return "{{language}}";
+    return siteName && siteName.length > 2 ? value.split(siteName).join("{{siteName}}") : value;
+  }
+  if (Array.isArray(value)) return value.map((item) => placeholders(item, siteName, language));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([k, v]) => [k, placeholders(v, siteName, language, k, value)])
+    );
+  }
+  return value;
+}
+var hasReference = (value) => JSON.stringify(value ?? null).includes('"_ref":');
+function references(value) {
+  if (Array.isArray(value)) return value.flatMap(references);
+  if (value && typeof value === "object") {
+    const ref = value._ref;
+    const own = typeof ref === "string" && !/^(image|file)-/.test(ref) ? [ref] : [];
+    return [...own, ...Object.values(value).flatMap(references)];
+  }
+  return [];
+}
+function compactColors(value) {
+  if (Array.isArray(value)) return value.map(compactColors);
+  if (value && typeof value === "object") {
+    const object = value;
+    if (object._type === "color" && typeof object.hex === "string") return { $color: object.hex };
+    return Object.fromEntries(Object.entries(object).map(([k, v]) => [k, compactColors(v)]));
+  }
+  return value;
+}
+
+// src/init/live.ts
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createClient } from "@sanity/client";
+function sanityToken() {
+  if (process.env.SANITY_AUTH_TOKEN) return process.env.SANITY_AUTH_TOKEN;
+  const config = join(homedir(), ".config", "sanity", "config.json");
+  if (!existsSync(config)) return null;
+  return JSON.parse(readFileSync(config, "utf8")).authToken ?? null;
+}
+async function organizationOf(projectId, token) {
+  const response = await fetch(`https://api.sanity.io/v2021-06-07/projects/${projectId}`, {
+    headers: { Authorization: `Bearer ${token}` }
+  });
+  if (!response.ok) throw new Error(`Couldn't read project ${projectId}: ${response.status}`);
+  return (await response.json()).organizationId ?? "";
+}
+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 docs = await client.fetch("*[_id in $ids]", {
+    ids: [options.settingsId, options.themeId, ...options.starterIds]
+  });
+  const byId = new Map(docs.map((doc) => [doc._id, doc]));
+  const missing = options.starterIds.filter((id) => !byId.has(id));
+  if (missing.length) throw new Error(`No published documents with ids: ${missing.join(", ")}`);
+  return {
+    settings: byId.get(options.settingsId) ?? null,
+    theme: byId.get(options.themeId) ?? null,
+    starter: options.starterIds.map((id) => byId.get(id))
+  };
+}
+
+// src/init/repo.ts
+import { execFileSync } from "node:child_process";
+import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync2 } from "node:fs";
+import { join as join2 } from "node:path";
+var APP_DIRS = [".", "frontend", "web", "site", "studio", "apps"];
+var git = (dir, ...args) => {
+  try {
+    return execFileSync("git", ["-C", dir, ...args], { encoding: "utf8", stdio: "pipe" }).trim();
+  } catch {
+    return null;
+  }
+};
+function repoFromRemote(remote) {
+  return remote?.match(/[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/)?.[1] ?? null;
+}
+function appDirs(root) {
+  const apps = join2(root, "apps");
+  const nested = existsSync2(apps) ? readdirSync(apps, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => join2(apps, entry.name)) : [];
+  return [...APP_DIRS.map((dir) => join2(root, dir)), ...nested].filter((dir) => existsSync2(dir));
+}
+function readRepo(root) {
+  const dirs = appDirs(root);
+  const schemaPath = dirs.map((dir) => join2(dir, "sanity.schema.json")).find(existsSync2);
+  if (!schemaPath) {
+    throw new Error("No sanity.schema.json: run `npx sanity schema extract` in the Studio first");
+  }
+  const envNames = dirs.flatMap((dir) => {
+    const file = join2(dir, ".env.example");
+    if (!existsSync2(file)) return [];
+    return [...readFileSync2(file, "utf8").matchAll(/^\s*([A-Z][A-Z0-9_]*)\s*=/gm)].map((m) => m[1]);
+  });
+  const projectId = dirs.flatMap((dir) => ["sanity.cli.ts", "sanity.config.ts"].map((file) => join2(dir, file))).filter(existsSync2).map((file) => readFileSync2(file, "utf8").match(/projectId:\s*['"]([a-z0-9]+)['"]/)?.[1]).find(Boolean) ?? null;
+  const hasRevalidateRoute = dirs.some(
+    (dir) => ["app", "src/app", "pages", "src/pages"].some(
+      (base) => existsSync2(join2(dir, base, "api/revalidate")) || ["ts", "js"].some((ext) => existsSync2(join2(dir, base, `api/revalidate.${ext}`)))
+    )
+  );
+  return {
+    repo: repoFromRemote(git(root, "remote", "get-url", "origin")),
+    branch: git(root, "symbolic-ref", "--short", "refs/remotes/origin/HEAD")?.replace(/^origin\//, "") ?? null,
+    envNames: [...new Set(envNames)],
+    projectId,
+    hasRevalidateRoute,
+    types: JSON.parse(readFileSync2(schemaPath, "utf8"))
+  };
+}
+
+// src/register.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+import { join as join3 } from "node:path";
+async function register(options) {
+  const file = join3(options.dir, "workspace-manager.json");
+  const manifest = parseManifest(JSON.parse(readFileSync3(file, "utf8")));
+  configFrom(manifest);
+  const response = await (options.fetch ?? fetch)(
+    `${options.api.replace(/\/+$/, "")}/api/project-types`,
+    {
+      method: "POST",
+      headers: { "Authorization": `Bearer ${options.token}`, "Content-Type": "application/json" },
+      body: JSON.stringify(manifest)
+    }
+  );
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok)
+    throw new Error(`Not registered (${response.status}): ${body.error ?? "no reason given"}`);
+  return body;
+}
+
+// src/cli.ts
+var USAGE = `Usage: sanity-workspace-manager <init|register> [dir] [options]
+
+init [dir]
+
+Drafts workspace-manager.json for a site repo from its git remote, .env.example
+and sanity.schema.json (run \`npx sanity schema extract\` first).
+
+Options:
+  --yes              Accept the suggested id, title 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             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)
+  --force            Overwrite an existing workspace-manager.json
+  --print            Print the draft instead of writing it
+
+register [dir]
+Checks the repo's workspace-manager.json and saves it through the workspace manager API,
+signed in as you (SANITY_AUTH_TOKEN or \`npx sanity login\`).
+
+Options:
+  --api <url>        The workspace manager API (or set WORKSPACE_MANAGER_API_URL)`;
+var dirOf = (positional) => resolve(process.env.INIT_CWD ?? ".", positional ?? ".");
+async function registerCommand(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: { api: { type: "string" } }
+  });
+  const api = values.api ?? process.env.WORKSPACE_MANAGER_API_URL;
+  if (!api) throw new Error("Pass --api <url> or set WORKSPACE_MANAGER_API_URL");
+  const token = sanityToken();
+  if (!token) throw new Error("register needs SANITY_AUTH_TOKEN or `npx sanity login`");
+  const saved = await register({ dir: dirOf(positionals[0]), api, token });
+  console.log(`Registered ${saved.title} (${saved.id})`);
+}
+async function init(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      yes: { type: "boolean", default: false },
+      project: { type: "string" },
+      org: { type: "string" },
+      live: { type: "boolean", default: false },
+      dataset: { type: "string", default: "production" },
+      starter: { type: "string" },
+      force: { type: "boolean", default: false },
+      print: { type: "boolean", default: false }
+    }
+  });
+  const root = dirOf(positionals[0]);
+  const out = resolve(root, "workspace-manager.json");
+  if (existsSync3(out) && !values.force && !values.print)
+    throw new Error(`${out} exists: pass --force to replace it`);
+  if (values.starter && !values.live) throw new Error("--starter needs --live");
+  const token = values.live ? sanityToken() : null;
+  if (values.live && !token) throw new Error("--live needs SANITY_AUTH_TOKEN or `npx sanity login`");
+  const orgFor = async (projectId) => values.org ?? (token && projectId ? await organizationOf(projectId, token) : "");
+  const repo = readRepo(root);
+  const suggested = { ...suggestNames(repo.repo), project: values.project ?? repo.projectId ?? "" };
+  const answers = values.yes ? { ...suggested, org: await orgFor(suggested.project) } : await ask(suggested, orgFor);
+  if (!answers.project)
+    throw new Error("Pass --project <id>: the Sanity project to copy schemas from");
+  if (!answers.org) throw new Error("Pass --org <id>, or --live to read it from the project");
+  const base = {
+    id: answers.id,
+    title: answers.title,
+    organizationId: answers.org,
+    schemaSourceProjectId: answers.project
+  };
+  let draft = draftManifest(repo, base);
+  if (token) {
+    const live = await readLive({
+      projectId: answers.project,
+      dataset: values.dataset,
+      token,
+      settingsId: draft.manifest.brand.settings.documentId,
+      themeId: draft.manifest.brand.theme.documentId,
+      starterIds: values.starter?.split(",").map((id) => id.trim()).filter(Boolean) ?? []
+    });
+    draft = draftManifest(repo, base, live);
+  }
+  configFrom(parseManifest(draft.manifest));
+  const json = `${JSON.stringify(draft.manifest, null, 2)}
+`;
+  if (values.print) process.stdout.write(json);
+  else writeFileSync(out, json);
+  console.error(`${values.print ? "Drafted" : `Wrote ${out}`}
+
+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 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);
+    const title = await question("Name shown in the app", suggested.title);
+    const project = await question("Sanity project to copy schemas from", suggested.project);
+    const org = await question("Sanity organisation to create workspaces in", await orgFor(project));
+    return { id, title, project, org };
+  } finally {
+    prompt.close();
+  }
+}
+var commands = {
+  init,
+  register: registerCommand
+};
+var [command, ...rest] = process.argv.slice(2);
+var run = command ? commands[command] : void 0;
+if (!run) {
+  console.log(USAGE);
+  process.exit(command ? 1 : 0);
+}
+run(rest).catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@anyday/sanity-workspace-manager",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Drafts a site repo's workspace-manager.json for the Anyday workspace manager",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anydayagency/anyday-workspace-manager-sanity.git",
+    "directory": "cli"
+  },
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "sanity-workspace-manager": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "esbuild src/cli.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/cli.mjs --external:@sanity/client --external:ajv --banner:js='#!/usr/bin/env node'",
+    "prepublishOnly": "npm run build && npm test",
+    "start": "tsx src/cli.ts",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@sanity/client": "^7.27.0",
+    "ajv": "^8.20.0"
+  },
+  "devDependencies": {
+    "@anyday/workspace-manager-api": "*",
+    "@types/node": "^24.19.1",
+    "esbuild": "^0.28.2",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}