sanity-canvas-skill 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sanity.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# sanity-canvas-skill
+
+> ### 🤖 Vibe coded by a [Miriad](https://miriad.app) Team
+> This package was built entirely by a team of AI agents collaborating on Miriad — from spec to implementation to tests. 362 tests, zero hand-written lines.
+
+Read and write [Sanity Canvas](https://www.sanity.io/canvas) documents programmatically. Markdown ↔ Canvas Portable Text conversion with diff-based push for concurrent editing.
+
+> 📖 **Run `npx sanity-canvas-skill@latest --help` for the full command reference.**
+
+## Quick Start
+
+```bash
+export SANITY_TOKEN="your-global-sanity-token"
+
+# Pull a Canvas doc to markdown (with block keys for roundtrip)
+npx sanity-canvas-skill@latest --org <orgId> pull <docId> > doc.md
+
+# Edit doc.md, then push changes back (diff-based, only patches changed blocks)
+cat doc.md | npx sanity-canvas-skill@latest --org <orgId> push
+
+# Preview changes without applying
+cat doc.md | npx sanity-canvas-skill@latest --org <orgId> push --dry-run
+
+# Force full overwrite (skips diff)
+cat doc.md | npx sanity-canvas-skill@latest --org <orgId> push --force
+
+# List docs
+npx sanity-canvas-skill@latest --org <orgId> list
+```
+
+## Getting a Token
+
+You need a **global** Sanity auth token (not project-scoped). The easiest way:
+
+```bash
+npx sanity debug --secrets
+```
+
+This prints your CLI's auth token, which works as a global token. Alternatively, create one at [manage.sanity.io](https://manage.sanity.io) → API → Tokens.
+
+## Programmatic API
+
+```typescript
+import {
+  canvasToMarkdown,
+  markdownToCanvas,
+  normalizeKeys,
+  computeOps,
+  diffPush,
+  resolveResource,
+} from 'sanity-canvas-skill'
+```
+
+### Convert Canvas blocks to markdown
+
+```typescript
+const markdown = canvasToMarkdown(doc.content, {emitKeys: true})
+// Produces markdown with <!-- k:KEY --> comments for roundtrip
+```
+
+### Convert markdown to Canvas blocks
+
+```typescript
+const blocks = markdownToCanvas(markdown)
+// Parses key comments, restores block identity
+```
+
+### Diff two block arrays
+
+```typescript
+const normalized = normalizeKeys(originalBlocks, editedBlocks)
+const ops = computeOps(originalBlocks, normalized)
+// [{type: 'set', key: 'abc', block: {...}}, {type: 'insert', afterKey: 'def', blocks: [...]}]
+```
+
+### Full push pipeline
+
+```typescript
+import {createClient} from '@sanity/client'
+
+const resource = await resolveResource(token, orgId)
+const client = createClient({resource: {type: 'canvas', id: resource.id}})
+
+const result = await diffPush(client, markdownFileContent)
+// {docId: '...', ops: [...], summary: '1 changed, 2 inserted, 0 deleted', rev: '...'}
+```
+
+## How it works
+
+**Pull** serializes Canvas Portable Text blocks to markdown with `<!-- k:KEY -->` HTML comments that preserve block identity.
+
+**Push** is diff-based:
+1. Pulls the current doc from Canvas (fresh revision for locking)
+2. Parses edited markdown back to blocks
+3. Matches blocks by `_key` from key comments
+4. Computes minimal SET/INSERT/UNSET operations via `@sanity/diff`
+5. Applies atomically with `ifRevisionId` optimistic locking
+
+Only changed blocks are patched. Notes are preserved. Concurrent edits are detected (409 on conflict).
+
+Unknown block types survive roundtrip via opaque base64 encoding (`<!-- canvas:TYPE:BASE64 -->`).
+
+## Block type support
+
+| Markdown | Canvas Type | Roundtrip |
+|---|---|---|
+| Text, headings, blockquotes | `block` | ✅ |
+| Bold, italic, code, links | marks/annotations | ✅ |
+| Lists (bullet, numbered) | `block` with `listItem` | ✅ |
+| Code blocks | `canvasCode` | ✅ |
+| Images | `canvasImage` | ✅ |
+| Horizontal rules | `canvasDivider` | ✅ |
+| Unknown types | opaque base64 | ✅ |
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `SANITY_TOKEN` | Yes | Global Sanity auth token (get with `npx sanity debug --secrets`) |
+| `SANITY_ORG` | No | Default org ID (alternative to `--org`) |
+
+## License
+
+MIT © [Sanity.io](https://www.sanity.io)

package/README.old.md

@@ -0,0 +1,141 @@
+# Canvas Writer
+
+Create and update [Sanity Canvas](https://www.sanity.io/canvas) documents programmatically.
+
+Includes a reusable TypeScript library for markdown ↔ Canvas Portable Text conversion, and a CLI tool for reading/writing Canvas documents directly.
+
+## How It Works
+
+Canvas documents live in a **resource** (not a regular Sanity project/dataset). The CLI uses `@sanity/client` with a special `resource` config to talk directly to the Canvas API.
+
+The conversion library handles mapping between standard markdown and Canvas-specific Portable Text block types:
+
+| Markdown | Canvas PTE Type |
+|---|---|
+| Paragraphs, headings, blockquotes | `block` (with style) |
+| Bold, italic, code, strikethrough | `span` marks (`strong`, `em`, `code`, `strike-through`) |
+| Bullet/numbered lists | `block` with `listItem` |
+| Links `[text](url)` | `link` annotation with `href` |
+| Code blocks ` ```lang ``` ` | `canvasCode` (lines as nested blocks) |
+| Images `![alt](url)` | `canvasImage` (ephemeral src) |
+| Horizontal rules `---` | `canvasDivider` |
+
+## What an Agent Needs From the User
+
+To write to Canvas, an agent needs two things:
+
+1. **A Sanity auth token** — a global token (not project-scoped). Set as `SANITY_TOKEN` environment variable. The user can generate one at [sanity.io/manage](https://www.sanity.io/manage).
+
+2. **A Canvas resource ID** — identifies which Canvas workspace to write to. The user can find this by:
+   - Going to `canvas.sanity.io` and looking at the URL path, OR
+   - Using the Canvas API: `GET https://api.sanity.io/vX/canvases?organizationId={orgId}` returns resources with an `id` field.
+
+That's it. With those two values, the agent can create, read, update, and delete Canvas documents.
+
+## Setup
+
+```bash
+# Clone and install
+git clone git@github.com:snorrees/canvas-writer-studio.git
+cd canvas-writer-studio
+pnpm install
+
+# Set your Sanity token
+export SANITY_TOKEN="your-global-sanity-token"
+```
+
+## CLI Usage
+
+All commands require `--resource <id>` to specify the Canvas resource.
+
+```bash
+# List all documents
+pnpm canvas --resource <resourceId> list
+pnpm canvas --resource <resourceId> list --search "query"
+
+# Read a document
+pnpm canvas --resource <resourceId> read <docId>
+
+# Create a new document from markdown
+echo "# Hello World" | pnpm canvas --resource <resourceId> create "My Document"
+
+# Set (replace) content from markdown
+cat article.md | pnpm canvas --resource <resourceId> set <docId> content
+
+# Set (replace) notes from markdown
+cat notes.md | pnpm canvas --resource <resourceId> set <docId> notes
+
+# Set title
+pnpm canvas --resource <resourceId> set <docId> title "New Title"
+
+# Append to content
+cat extra.md | pnpm canvas --resource <resourceId> append <docId> content
+
+# Append to notes
+cat extra.md | pnpm canvas --resource <resourceId> append <docId> notes
+
+# Delete a document
+pnpm canvas --resource <resourceId> delete <docId>
+```
+
+## Library API
+
+The conversion functions can be imported directly for use in other tools:
+
+```typescript
+import {markdownToCanvas} from './src/lib/markdownToCanvas'
+import {canvasToMarkdown} from './src/lib/canvasToMarkdown'
+
+// Markdown → Canvas Portable Text blocks
+const blocks = markdownToCanvas('# Hello\n\nA paragraph with **bold**.')
+
+// Canvas Portable Text blocks → Markdown
+const markdown = canvasToMarkdown(blocks)
+```
+
+## Development
+
+```bash
+# Run tests (37 tests covering all block types + roundtrip)
+pnpm test
+
+# Type check
+pnpm typecheck
+
+# Regenerate types after schema changes
+pnpm typegen
+
+# Lint
+pnpm lint
+
+# Build Studio
+pnpm build
+
+# Deploy Studio
+pnpm deploy
+```
+
+## Project Structure
+
+```
+src/
+  lib/
+    markdownToCanvas.ts    # Markdown → Canvas PTE conversion
+    canvasToMarkdown.ts    # Canvas PTE → Markdown conversion
+    __tests__/
+      canvasMarkdown.test.ts  # 37 vitest tests
+  scripts/
+    canvas-write.ts        # CLI tool
+  schemaTypes/             # Canvas document schema (mirrors sanity-io/canvas)
+  components/
+    SyncToCanvasInput.tsx   # Studio sync component (browser-side)
+  structure.ts             # Custom Studio structure
+  sanity.types.ts          # Generated types (via pnpm typegen)
+sanity.config.ts           # Studio config
+sanity.cli.ts              # CLI config + typegen config
+schema.json                # Extracted schema (for typegen)
+```
+
+## Studio
+
+This repo also includes a Sanity Studio deployed at [canvas-writer.sanity.studio](https://canvas-writer.sanity.studio/). The Studio mirrors the Canvas schema and includes a sync component that can push documents to Canvas from the browser. The CLI approach is generally more useful for agents.

package/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: canvas-skill
+description: "Read and write Sanity Canvas documents. Three-verb CLI with path-based access, diff-based push, and notes diffing."
+---
+
+# Canvas Skill
+
+Read and write [Sanity Canvas](https://www.sanity.io/canvas) documents. Three verbs (`pull`, `push`, `list`), path-based access to content and notes, diff-based push for concurrent editing.
+
+## Prerequisites
+
+- **Node.js 18+**
+- **SANITY_TOKEN** — a global Sanity auth token (not project-scoped). Get one with `npx sanity debug --secrets`, or from [manage.sanity.io](https://manage.sanity.io) → API → Tokens.
+- **Organization ID** — the Sanity org that owns the Canvas.
+
+## Quick Start
+
+```bash
+# Pull a Canvas doc to markdown
+npx sanity-canvas-skill@latest --org <orgId> pull <docId>
+
+# Pull just the content (no notes, no frontmatter)
+npx sanity-canvas-skill@latest --org <orgId> pull <docId> content
+
+# Edit, then push changes back (diff-based — only changed blocks are patched)
+cat doc.md | npx sanity-canvas-skill@latest --org <orgId> push
+
+# List all Canvas docs
+npx sanity-canvas-skill@latest --org <orgId> list
+```
+
+## Three Verbs
+
+| Verb | What it does |
+|------|-------------|
+| `pull` | Read document data → stdout as markdown |
+| `push` | Write markdown from stdin → document (diff-based) |
+| `list` | List documents in a Canvas resource |
+
+## Path Model
+
+A Canvas document is a tree. The CLI exposes it through **paths**:
+
+| Path | What it addresses |
+|------|-------------------|
+| (none) | Entire document (content + notes + title) |
+| `content` | The content block array |
+| `notes` | All notes |
+| `notes[0]` | A single note (by index) |
+| `notes[_key=="k"]` | A single note (by key) |
+| `title` | The document title string |
+
+Paths are positional arguments: `npx sanity-canvas-skill@latest pull <docId> <path>`
+
+## Pull
+
+```bash
+# Full document (frontmatter + content + notes)
+npx sanity-canvas-skill@latest --org <orgId> pull <docId>
+
+# Content blocks only (with key comments)
+npx sanity-canvas-skill@latest --org <orgId> pull <docId> content
+
+# All notes with headers
+npx sanity-canvas-skill@latest --org <orgId> pull <docId> notes
+
+# Single note by index or key
+npx sanity-canvas-skill@latest --org <orgId> pull <docId> 'notes[0]'
+npx sanity-canvas-skill@latest --org <orgId> pull <docId> 'notes[_key=="abc"]'
+
+# Just the title
+npx sanity-canvas-skill@latest --org <orgId> pull <docId> title
+
+# Range reads (content or note body)
+npx sanity-canvas-skill@latest --org <orgId> pull <docId> content --from <key> --to <key>
+npx sanity-canvas-skill@latest --org <orgId> pull <docId> content --from <key>
+npx sanity-canvas-skill@latest --org <orgId> pull <docId> content --range 0-10
+npx sanity-canvas-skill@latest --org <orgId> pull <docId> content --range -5
+
+# Outline — structural overview (heading hierarchy + block counts)
+npx sanity-canvas-skill@latest --org <orgId> pull <docId> --outline
+```
+
+### Pull Output Format
+
+Full document pull produces:
+
+```markdown
+---
+id: n36GqUekRrdauhzK15EtOM
+org: oSyH1iET5
+rev: 2TJuQTedaNK0J2PgZg0gcu
+---
+
+<!-- k:abc123 -->
+# Document Title
+
+<!-- k:def456 -->
+First paragraph.
+
+---notes---
+
+## Note: "Research Sources" [fact] <!-- k:note1 -->
+
+<!-- k:n1_b0 -->
+Note body here.
+
+## Note: "Style Guide" [style] <!-- k:note2 -->
+
+<!-- k:n2_b0 -->
+Another note body.
+```
+
+- **Frontmatter**: document ID, org, revision (for conflict detection)
+- **`<!-- k:KEY -->`**: block identity preserved through roundtrip
+- **`---notes---`**: delimiter between content and notes
+- **`## Note: "Title" [category]`**: note headers with key comment
+
+## Push
+
+Push is **diff-based by default** — only changed blocks are patched.
+
+```bash
+# Full document push (diffs both content AND notes)
+cat doc.md | npx sanity-canvas-skill@latest --org <orgId> push
+
+# Preview changes without applying
+cat doc.md | npx sanity-canvas-skill@latest --org <orgId> push --dry-run
+
+# Force full overwrite (no diff)
+cat doc.md | npx sanity-canvas-skill@latest --org <orgId> push --force
+
+# Targeted writes
+npx sanity-canvas-skill@latest --org <orgId> push <docId> content --keys < blocks.md
+npx sanity-canvas-skill@latest --org <orgId> push <docId> content --after <key> < new.md
+npx sanity-canvas-skill@latest --org <orgId> push <docId> content --after-index 3 < new.md
+npx sanity-canvas-skill@latest --org <orgId> push <docId> content --append < new.md
+npx sanity-canvas-skill@latest --org <orgId> push <docId> title "New Title"
+
+# Create a new document
+cat content.md | npx sanity-canvas-skill@latest --org <orgId> push --new "Document Title"
+```
+
+### How Push Works
+
+1. Pulls the current document from Canvas (fresh `_rev` for locking)
+2. Parses your edited markdown back to Portable Text blocks
+3. Normalizes keys (restores span-level keys that markdown roundtrip regenerates)
+4. Computes minimal operations via `@sanity/diff`: SET, INSERT, UNSET
+5. Diffs both `content` AND `notes` arrays
+6. Applies all operations in a single atomic transaction with `ifRevisionId`
+
+This means:
+- **Only changed blocks are patched** — unchanged content is untouched
+- **Notes are diffed too** — edit a note body, only that note is patched
+- **Concurrent edits are safe** — 409 on conflict, re-pull and try again
+- **New blocks** (without `<!-- k:KEY -->`) are inserted at the correct position
+
+## Programmatic API
+
+```typescript
+import {
+  canvasToMarkdown,
+  markdownToCanvas,
+  normalizeKeys,
+  computeOps,
+  diffPush,
+  parseCanvasDoc,
+  serializeCanvasDoc,
+  resolveResourceId,
+} from 'sanity-canvas-skill'
+import {createClient} from '@sanity/client'
+
+// Setup
+const resourceId = await resolveResourceId(token, orgId)
+const client = createClient({
+  resource: {type: 'canvas', id: resourceId},
+  token,
+  apiVersion: '2025-10-01',
+  useCdn: false,
+})
+
+// Pull → markdown
+const doc = await client.fetch('*[_id == $id][0]{ _id, _rev, title, content, notes }', {id: docId})
+const markdown = canvasToMarkdown(doc.content, {emitKeys: true})
+
+// Markdown → blocks
+const blocks = markdownToCanvas(markdown)
+
+// Diff two block arrays
+const normalized = normalizeKeys(originalBlocks, editedBlocks)
+const ops = computeOps(originalBlocks, normalized)
+
+// Full push pipeline (pull + diff + apply atomically)
+const result = await diffPush(client, markdownFileContent)
+// result: {docId, ops, summary, rev}
+```
+
+## Block Type Support
+
+| Markdown | Canvas Type | Roundtrip |
+|---|---|---|
+| Paragraphs, headings, blockquotes | `block` (with style) | ✅ Lossless |
+| Bold, italic, code, strikethrough | `span` marks | ✅ Lossless |
+| Bullet/numbered lists | `block` with `listItem` | ✅ Lossless |
+| Links `[text](url)` | `link` annotation | ✅ Lossless |
+| Code blocks `` ```lang ``` `` | `canvasCode` | ✅ Lossless |
+| Images `![alt](url)` | `canvasImage` | ✅ Lossless |
+| Horizontal rules `---` | `canvasDivider` | ✅ Lossless |
+| Unknown types | `<!-- canvas:TYPE:BASE64 -->` | ✅ Opaque preservation |
+
+## Key Concepts
+
+- **Key comments** (`<!-- k:KEY -->`) — preserve block identity. Don't remove them unless you want to delete that block.
+- **Generated keys** — new blocks get `g_` prefixed keys (e.g., `g_0`). Replaced by Canvas-generated keys on push.
+- **Optimistic locking** — push uses `ifRevisionId`. If the doc changed, you get a 409. Re-pull and try again.
+- **Opaque blocks** — unknown types preserved as `<!-- canvas:TYPE:BASE64 -->`. Don't edit these.
+- **Notes diffing** — notes are diffed the same way as content. Edit a note body, only that note is patched.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `SANITY_TOKEN` | Yes | Global Sanity auth token (get with `npx sanity debug --secrets`) |
+| `SANITY_ORG` | No | Default organization ID (alternative to `--org`) |

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}