Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 31 additions & 20 deletions .agents/skills/starter/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,17 +36,17 @@ my-starter/

Every starter must have:

| File | Purpose |
| --- | --- |
| `package.json` | `"type": "module"`, `engines`, `packageManager`, scripts |
| `pnpm-workspace.yaml` | Workspace packages + `catalog:` for shared dep versions |
| `.env.example` | Template with comments, no real values |
| `.gitignore` | Self-contained, covers all starter concerns |
| `.npmrc` | `enable-pre-post-scripts=true` (required for pnpm 10.x) |
| `.oxfmtrc.json` | `semi: false`, `singleQuote: true`, `printWidth: 100`, `bracketSpacing: false` |
| `README.md` | Getting started, prerequisites, project structure |
| `AGENT.md` | Agent context for Claude Code / Cursor / etc. |
| `CLAUDE.md` | Symlink to `AGENT.md` |
| File | Purpose |
| --------------------- | ------------------------------------------------------------------------------ |
| `package.json` | `"type": "module"`, `engines`, `packageManager`, scripts |
| `pnpm-workspace.yaml` | Workspace packages + `catalog:` for shared dep versions |
| `.env.example` | Template with comments, no real values |
| `.gitignore` | Self-contained, covers all starter concerns |
| `.npmrc` | `enable-pre-post-scripts=true` (required for pnpm 10.x) |
| `.oxfmtrc.json` | `semi: false`, `singleQuote: true`, `printWidth: 100`, `bracketSpacing: false` |
| `README.md` | Getting started, prerequisites, project structure |
| `AGENT.md` | Agent context for Claude Code / Cursor / etc. |
| `CLAUDE.md` | Symlink to `AGENT.md` |

## Environment Variables

Expand All @@ -58,11 +58,11 @@ Single root `.env.local` cascades to all workspaces. Never committed.

Loading patterns by context:

| Context | Pattern |
| --- | --- |
| Studio CLI (`sanity.cli.ts`) | `process.loadEnvFile(\`${__dirname}/../.env.local\`)` |
| Blueprint (`sanity.blueprint.ts`) | `readFileSync` + manual parse (jiti quirk) |
| Vite apps | `vite: { envDir: '..' }` pointing to root |
| Context | Pattern |
| --------------------------------- | ----------------------------------------------------- |
| Studio CLI (`sanity.cli.ts`) | `process.loadEnvFile(\`${__dirname}/../.env.local\`)` |
| Blueprint (`sanity.blueprint.ts`) | `readFileSync` + manual parse (jiti quirk) |
| Vite apps | `vite: { envDir: '..' }` pointing to root |

## Shared Config Packages

Expand Down Expand Up @@ -121,13 +121,24 @@ Root `package.json` delegates to workspaces:

## GitHub Workflows

Each starter ships its own workflows for standalone use:
Each starter ships its own workflows under `<starter>/.github/workflows/` for standalone use (they run when the starter is cloned via `sanity init --template`):

- **`ci.yml`** — format check, lint, typecheck, test, validate
- **`deploy.yml`** — deploy Studio, functions, apps on push to main (path-filtered)
- **`ci.yml`** — format check, lint, typecheck, validate, and (if it has Functions) build + manifest extract + bundle-size check
- **`deploy.yml`** — deploy Studio, functions, and blueprint on push to main (path-filtered); build the frontend as a guard. The Next.js storefront itself deploys via Vercel (dashboard import), not this workflow.
- **`eval.yml`** — manual triggers for quality evals (if applicable)

These also exist in the root `.github/workflows/ci.yml` for monorepo CI but scoped with `working-directory` and `cache-dependency-path`.
## Wiring a New Starter into the Monorepo

The starter's own workflows do **not** run in this repo — the root `.github/workflows/ci.yml` runs CI for every starter. Adding a new starter is not complete until you do all of the following (it's easy to forget the root CI job — a starter with green local `pnpm validate` still has **zero** monorepo coverage without it):

1. **Add a job to the root `.github/workflows/ci.yml`.** Mirror an existing starter job (e.g. `knowledge-base`): a Node 20/22 matrix, `environment: <starter-name>`, `defaults.run.working-directory: <starter-name>`, then `pnpm install` + format check + lint + typecheck + validate (+ functions build, manifest extract, and bundle-size check if it has Functions). Steps that touch the Content Lake read `SANITY_STUDIO_PROJECT_ID`/`SANITY_STUDIO_DATASET` from `${{ vars.SANITY_PROJECT_ID }}` / `${{ vars.SANITY_DATASET }}`.
2. **Create a GitHub Environment** named exactly after the starter (repo Settings → Environments) with:
- vars: `SANITY_PROJECT_ID`, `SANITY_DATASET` (add `SANITY_STACK_ID` if it deploys a blueprint)
- secrets: `SANITY_AUTH_TOKEN` (only if the starter deploys)
3. **Add a row** to the starters table in the root `README.md`.
4. **Husky needs no edit** — the root `.husky/pre-commit` hook auto-discovers each starter by its own `package.json` / `eslint.config.*`, so formatting and lint-fix scope automatically.

Verify from the starter directory with `pnpm validate` (template compatibility) and confirm the new `<starter-name>` job appears in the PR's checks.

## Template Validation

Expand Down
10 changes: 6 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -166,16 +166,16 @@ jobs:
done
exit $failed

analytics-content-ops:
name: analytics-content-ops (Node ${{ matrix.node-version }})
commerce-plp-management:
name: commerce-plp-management (Node ${{ matrix.node-version }})
runs-on: ubuntu-latest
environment: analytics-content-ops
environment: commerce-plp-management
strategy:
matrix:
node-version: [20, 22]
defaults:
run:
working-directory: analytics-content-ops
working-directory: commerce-plp-management
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
Expand All @@ -194,6 +194,8 @@ jobs:
SANITY_STUDIO_DATASET: ${{ vars.SANITY_DATASET }}
- name: Validate template
run: pnpm run validate
- name: Build functions
run: pnpm --filter @starter/functions build
- name: Manifest extract
run: pnpm --filter studio exec sanity manifest extract
env:
Expand Down
7 changes: 4 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,11 +23,12 @@ Then customize it:

When it's ready, wire it into the monorepo:

- Add a job to `.github/workflows/ci.yml` (with `environment: <starter-name>`)
- Create a GitHub Environment in repo settings with `SANITY_PROJECT_ID` and `SANITY_DATASET` (add `SANITY_AUTH_TOKEN` as a secret if the starter deploys)
- Add the starter name to the lint loop in `.husky/pre-commit`
- Add a job to `.github/workflows/ci.yml` (with `environment: <starter-name>`) — the starter's own workflows don't run here, so without this job the starter has no monorepo CI coverage
- Create a GitHub Environment in repo settings with `SANITY_PROJECT_ID` and `SANITY_DATASET` (add `SANITY_AUTH_TOKEN` as a secret, and `SANITY_STACK_ID` as a var, if the starter deploys)
- Add a row to the table in `README.md`

The `.husky/pre-commit` hook auto-discovers starters — no manual edit needed.

The starter must work standalone when cloned via `sanity init --template`. Run `pnpm validate` to check.

## Conventions
Expand Down
15 changes: 8 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,14 @@ pnpm create sanity@latest --template sanity-labs/starters/<starter-name>

## Starters

| Starter | Description |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| [agent-ready-content](./agent-ready-content) | Serve HTML to humans and markdown to agents from the same URLs, in Next.js and Astro |
| [agentic-localization](./agentic-localization) | AI translation with glossaries, style guides, quality evals, and a translations dashboard |
| [ai-shopping-assistant](./ai-shopping-assistant) | Ecommerce storefront with a Claude chatbot powered by Context MCP |
| [analytics-content-ops](./analytics-content-ops) | Analytics signal → Studio triage, GROQ intelligence rails, and Content Agent overnight |
| [knowledge-base](./knowledge-base) | Governed knowledge base feeding external and internal AI chat surfaces from one dataset |

| Starter | Description |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [agentic-localization](./agentic-localization) | AI translation with glossaries, style guides, quality evals, and a translations dashboard |
| [ai-shopping-assistant](./ai-shopping-assistant) | Ecommerce storefront with a Claude chatbot powered by Context MCP |
| [knowledge-base](./knowledge-base) | Governed knowledge base feeding external and internal AI chat surfaces from one dataset |
| [analytics-content-ops](./analytics-content-ops) | Analytics signal → Studio triage, GROQ intelligence rails, and Content Agent overnight |
| [commerce-plp-management](./commerce-plp-management) | Editorial merchandising layer over Shopify PLPs — curation, badges, facets, custom collections |

## Repo structure

Expand Down
33 changes: 33 additions & 0 deletions commerce-plp-management/.env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Copy this file to .env and fill in your values.
#
# This root file is loaded by the blueprint deploy (sanity.blueprint.ts, via
# dotenv/config) and the push-sync Function tooling. It holds the Sanity project
# coordinates plus the Shopify Admin credentials the push-sync needs.
# Never commit .env (it is gitignored).

# --- Sanity ---------------------------------------------------------------
# From sanity.io/manage. `sanity init --template` fills these in for you.
SANITY_STUDIO_PROJECT_ID=
SANITY_STUDIO_DATASET=production

# Write token (Editor+). Used by the seed script and the push-sync Function to
# update syncStatus on documents. Create at sanity.io/manage -> API -> Tokens.
SANITY_API_WRITE_TOKEN=

# --- Shopify Admin API (push-sync: writes the sanity_plp_collection metaobject)
# Sensitive: server/Function only, never shipped to the browser.
# App needs scopes: write_metaobjects, write_metaobject_definitions, read_products.
SHOPIFY_STORE_DOMAIN=your-store.myshopify.com

# Dev Dashboard app: Client ID + Secret are exchanged for a short-lived Admin
# token automatically (client credentials grant). Find them in the Dev Dashboard
# under your app -> Settings. See:
# https://shopify.dev/docs/apps/build/dev-dashboard/get-api-access-tokens
SHOPIFY_CLIENT_ID=
SHOPIFY_CLIENT_SECRET=

# Legacy alternative: store-level custom app static token (shpat_...). Use this
# INSTEAD of the client credentials above if your app provides a static token.
# SHOPIFY_ADMIN_API_TOKEN=

SHOPIFY_ADMIN_API_VERSION=2025-07
58 changes: 58 additions & 0 deletions commerce-plp-management/.github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
name: CI

on:
push:
branches: [main]
pull_request:
workflow_dispatch:

jobs:
build:
name: Build & Validate (Node ${{ matrix.node-version }})
runs-on: ubuntu-latest
environment: commerce-plp-management
strategy:
matrix:
node-version: [20, 22]
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
- run: pnpm install
- name: Format check
run: pnpm run format:check
- name: Lint
run: pnpm run lint
- name: Typecheck
run: pnpm run typecheck
env:
SANITY_STUDIO_PROJECT_ID: ${{ vars.SANITY_PROJECT_ID }}
SANITY_STUDIO_DATASET: ${{ vars.SANITY_DATASET }}
- name: Validate template
run: pnpm run validate
- name: Build functions
run: pnpm --filter @starter/functions build
- name: Manifest extract
run: pnpm --filter studio exec sanity manifest extract
env:
SANITY_STUDIO_PROJECT_ID: ${{ vars.SANITY_PROJECT_ID }}
SANITY_STUDIO_DATASET: ${{ vars.SANITY_DATASET }}
- name: Check function bundle sizes
run: |
max_kb=512
failed=0
for dir in functions/dist/*/; do
bundle="$dir/index.js"
[ -f "$bundle" ] || continue
size_kb=$(( $(wc -c < "$bundle") / 1024 ))
name=$(basename "$dir")
if [ "$size_kb" -gt "$max_kb" ]; then
echo "::error::$name bundle is ${size_kb} KB (max ${max_kb} KB)"
failed=1
else
echo "$name: ${size_kb} KB ✓"
fi
done
exit $failed
78 changes: 78 additions & 0 deletions commerce-plp-management/.github/workflows/deploy.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
name: Deploy

# Deploys the Sanity-hosted surfaces on push to main. The Next.js storefront is
# deployed by Vercel (see "Deploying" in the README) — this workflow only builds
# it as a guard.
#
# Requires these GitHub Environment values (Settings → Environments):
# vars: SANITY_PROJECT_ID, SANITY_DATASET, SANITY_STACK_ID
# secrets: SANITY_AUTH_TOKEN

on:
push:
branches: [main]
paths:
- 'studio/**'
- 'packages/@starter/**'
- 'functions/**'
- 'sanity.blueprint.ts'
- 'frontend/**'

jobs:
studio:
name: Deploy Studio
runs-on: ubuntu-latest
environment: commerce-plp-management
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: lts/*
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm --filter studio run deploy
env:
SANITY_STUDIO_PROJECT_ID: ${{ vars.SANITY_PROJECT_ID }}
SANITY_STUDIO_DATASET: ${{ vars.SANITY_DATASET }}
SANITY_AUTH_TOKEN: ${{ secrets.SANITY_AUTH_TOKEN }}

blueprint:
name: Deploy Blueprint
runs-on: ubuntu-latest
environment: commerce-plp-management
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: lts/*
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm --filter @starter/functions run build
- name: Deploy blueprints
uses: sanity-io/blueprints-actions/deploy@deploy-v3
with:
sanity-token: ${{ secrets.SANITY_AUTH_TOKEN }}
stack-id: ${{ vars.SANITY_STACK_ID }}
project-id: ${{ vars.SANITY_PROJECT_ID }}
env:
SANITY_STUDIO_PROJECT_ID: ${{ vars.SANITY_PROJECT_ID }}
SANITY_STUDIO_DATASET: ${{ vars.SANITY_DATASET }}

frontend:
name: Build Frontend
runs-on: ubuntu-latest
environment: commerce-plp-management
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: lts/*
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm --filter frontend build
env:
NEXT_PUBLIC_SANITY_PROJECT_ID: ${{ vars.SANITY_PROJECT_ID }}
NEXT_PUBLIC_SANITY_DATASET: ${{ vars.SANITY_DATASET }}
43 changes: 43 additions & 0 deletions commerce-plp-management/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Dependencies
node_modules/

# Environment files — only .env.example is committed
.env
.env.*
!.env.example

# Temporary Sanity runtime, generated by the CLI
.sanity/

# Sanity Functions build output
.build/

# Compiled Sanity Studio
dist/

# Next.js build output and generated files
.next/
next-env.d.ts

# Logs
*.log

# OS files
.DS_Store

# IDE
.vscode/
.idea/

# TypeScript
*.tsbuildinfo

# Generated Sanity artifacts
schema.json
sanity.types.ts

# Claude Code
.claude/

# Internal
notes/
1 change: 1 addition & 0 deletions commerce-plp-management/.npmrc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
enable-pre-post-scripts=true
6 changes: 6 additions & 0 deletions commerce-plp-management/.oxfmtrc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"semi": false,
"singleQuote": true,
"printWidth": 100,
"bracketSpacing": false
}
Loading
Loading