@storystick/cli 0.0.0-stage → 0.2.0-rc.1

package/dist/transport.js

@@ -0,0 +1,73 @@
+import { StorystickError } from './cli-error.js';
+export const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+export async function fetchWithDeadline(input, init = {}, options = {}) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const callerSignal = options.signal ?? init.signal ?? undefined;
+    const controller = new AbortController();
+    let timedOut = false;
+    const onCallerAbort = () => controller.abort(callerSignal?.reason);
+    if (callerSignal?.aborted)
+        onCallerAbort();
+    else
+        callerSignal?.addEventListener('abort', onCallerAbort, { once: true });
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        controller.abort(new DOMException('Request deadline exceeded.', 'TimeoutError'));
+    }, timeoutMs);
+    try {
+        return await fetchImpl(input, { ...init, signal: controller.signal });
+    }
+    catch (error) {
+        if (callerSignal?.aborted)
+            throw abortError(callerSignal.reason);
+        if (timedOut) {
+            throw new StorystickError(`Request timed out after ${timeoutMs}ms.`, {
+                code: 'REQUEST_TIMEOUT',
+                category: 'network',
+                recoverable: true,
+                retryable: true,
+                cause: error,
+            });
+        }
+        if (isAbortError(error))
+            throw error;
+        throw new StorystickError(error instanceof Error ? error.message : String(error), {
+            code: 'NETWORK_ERROR',
+            category: 'network',
+            recoverable: true,
+            retryable: true,
+            cause: error,
+        });
+    }
+    finally {
+        clearTimeout(timeout);
+        callerSignal?.removeEventListener('abort', onCallerAbort);
+    }
+}
+export function abortableSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(abortError(signal.reason));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            reject(abortError(signal?.reason));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function isAbortError(value) {
+    return value instanceof Error && value.name === 'AbortError';
+}
+function abortError(reason) {
+    if (reason instanceof DOMException && reason.name === 'AbortError')
+        return reason;
+    return new DOMException('The operation was aborted.', 'AbortError');
+}

package/examples/sanity/README.md

@@ -0,0 +1,79 @@
+# Sanity → Storystick reference mapping
+
+This is an executable, offline example distributed with `@storystick/cli`.
+Copy it into your migration project and adapt the mapping to the actual Sanity
+schema and the existing frontend's data contracts. It is deliberately a small
+project converter, not an automatic CMS remodeler or a new server plugin system.
+
+The included synthetic snapshot covers `en/fr/zh`, a singleton, cyclic document
+references, nested slices, Portable Text marks/nested lists/image embeds,
+image occurrence metadata, inherited fields, explicit clearing, `false`, `0`
+and empty arrays. The Story Files put the article rich text in the first group.
+No original Diduenjoy data or credentials are included.
+
+## Source preparation
+
+Export the authoritative dataset using Sanity's supported tools. Select the
+source perspective deliberately. This converter expects raw `_ref` identities;
+do not feed it an export that rewrote references to asset paths. Sanity documents
+`--raw` for that purpose and `--no-drafts` for published source documents. A
+published source is still imported as a Storystick **draft**.
+
+Inspect export warnings: Sanity can finish an export while reporting missing
+asset binaries. Preserve originals, including vector files; do not substitute
+transformed CDN thumbnails. The converter performs no download or archive
+extraction and never executes source data.
+
+- [Sanity export contract](https://www.sanity.io/docs/content-lake/exporting-data)
+- [Portable Text block contract](https://www.sanity.io/docs/studio/block-type)
+
+`fixture/mapping.json` is a reviewed manifest of translation families and local
+original paths. It is not Sanity's exported `assets.json` URL map. Each source
+belongs to one family and locale. Families come from your source's explicit
+translation relationships or a reviewed mapping, never matching titles/slugs.
+Absent translated fields inherit. `clearedPaths` records explicit, reviewed
+clearing; the converter does not infer it from missing values.
+
+The reference selects published source IDs and refuses `drafts.*` and
+`versions.*`. It reports excluded source documents, including unselected drafts.
+Review `report.json` before import. Adapting draft/release precedence, additional
+CMS types, annotations, route intent or deep containers requires an explicit
+mapping change and a fixture; unknown editorial fields fail instead of disappearing.
+
+## Run locally
+
+In a project with the release artifacts of `@storystick/cli` and `@storystick/core`
+installed, copy this directory to `migration/sanity`. Compile and push its Story
+Files using your normal project config, then explicitly configure `en/fr/zh`
+with `en` as default through Storystick. Use the installed schema version from
+`storystick push --json`:
+
+```sh
+node migration/sanity/convert.mjs migration/sanity/fixture/data.ndjson migration/sanity/fixture/mapping.json migration/prepared <installed-schema-version>
+storystick content import migration/prepared/manifest.json --project <short-id> --dry-run --json
+storystick content import migration/prepared/manifest.json --project <short-id> --apply --plan <digest> --json
+storystick content verify <run-id> --project <short-id> --json
+```
+
+Preparation creates a new directory, never overwrites one, and writes the
+manifest last. It binds the source snapshot, converter source code, mapping,
+output records and original bytes with digests. When source asset metadata has
+`size`/`sha1hash`, they must match the file. Files are copied unchanged and
+checked again; large files are hashed incrementally. The small reference
+converter caps snapshots at 32 MiB and mappings at 192 KiB. Split larger source
+inventories explicitly; the public import limits still apply.
+
+The output uses native Storystick fields and temporary source-ID markers. Rich
+text uses the existing ProseMirror grammar and native keyed embed representation;
+there is no intermediate rich-text AST in the importer. Repository regression
+tests compile the actual Story Files and run public Core validation. Server import
+still owns native IDs, tenancy, locale/reference/media validation, limits,
+replay and persistence.
+
+Keep the existing frontend components and styles. Adapt its fetching/projection,
+image and rich-text data boundaries, then check the same pages at the same
+viewports. This example contains no replacement frontend. Converter and native
+protocol tests do not prove Content Plane delivery, Studio editing, preview or
+visual parity; those remain real-deployment qualification steps. Nothing here
+publishes content or deploys a website. The CLI capabilities are in development;
+use matching release artifacts until the packages and service are publicly available.

package/examples/sanity/convert.mjs

@@ -0,0 +1,228 @@
+/** Reference project mapping, not a universal Sanity importer. Adapt explicitly. */
+import { createReadStream } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { readFile, writeFile, realpath, mkdir, copyFile, stat } from 'node:fs/promises'
+import { dirname, resolve, relative, isAbsolute, basename } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { importDigest, planImportBatches, parseImportRecord } from '@storystick/core/content-import'
+
+const hash = value => createHash('sha256').update(value).digest('hex')
+const fail = (path, message) => { throw new Error(`${path}: ${message}`) }
+const object = (value, path) => value && typeof value === 'object' && !Array.isArray(value) ? value : fail(path, 'expected an object')
+const exact = (value, keys, path) => { object(value, path); for (const key of Object.keys(value)) if (!keys.includes(key)) fail(`${path}.${key}`, 'no mapping; refusing silent data loss') }
+const keyOf = (value, path) => typeof value === 'string' && /^[A-Za-z0-9_-]+$/.test(value) ? value : fail(path, 'expected a stable source occurrence key')
+const array = (value, path) => Array.isArray(value) ? value : fail(path, 'expected an array')
+const plain = (value, path, type) => typeof value === type ? value : fail(path, `expected ${type}`)
+const optional = (input, name, convert) => Object.hasOwn(input, name) ? { [name]: convert(input[name]) } : {}
+
+/** Output is native ProseMirror JSON plus its native keyed embed records. */
+export function portableText(blocks, { path, reference, image }) {
+  const content = [], embeds = [], stack = [], seen = new Set()
+  const marksFor = (span, definitions, spanPath) => array(span.marks ?? [], spanPath).map(mark => {
+    const standard = { strong: 'bold', em: 'italic', underline: 'underline', 'strike-through': 'strike', code: 'code' }
+    if (Object.hasOwn(standard, mark)) return { type: standard[mark] }
+    const definition = definitions.find(d => d._key === mark)
+    if (!definition) fail(spanPath, `unknown annotation ${mark}`)
+    if (definition._type === 'link') {
+      exact(definition, ['_key', '_type', 'href'], spanPath)
+      if (typeof definition.href !== 'string' || !/^(https?:\/\/|mailto:|tel:)/.test(definition.href)) fail(spanPath, 'unsupported URL; map its routing semantics explicitly')
+      return { type: 'link', attrs: { href: definition.href } }
+    }
+    if (definition._type === 'internalLink') {
+      exact(definition, ['_key', '_type', 'reference'], spanPath)
+      return { type: 'link', attrs: { _ref: reference(definition.reference, spanPath) } }
+    }
+    fail(spanPath, `unsupported annotation ${definition._type}`)
+  })
+  for (const [index, block] of array(blocks, path).entries()) {
+    const at = `${path}[${index}]`, key = keyOf(block._key, at)
+    if (seen.has(key)) fail(at, 'duplicate block key')
+    seen.add(key)
+    if (block._type === 'image') {
+      stack.length = 0
+      const embedKey = `embed_${Buffer.from(`${path}:${key}`).toString('base64url')}`
+      embeds.push({ _key: embedKey, _type: 'picture', image: image(block, at) })
+      content.push({ type: 'sliceEmbed', attrs: { _key: embedKey, _type: 'picture' } })
+      continue
+    }
+    exact(block, ['_type', '_key', 'style', 'markDefs', 'children', 'listItem', 'level'], at)
+    if (block._type !== 'block') fail(at, `unsupported block ${block._type}`)
+    const definitions = array(block.markDefs ?? [], at)
+    if (new Set(definitions.map(d => keyOf(d._key, at))).size !== definitions.length) fail(at, 'duplicate annotation key')
+    const inline = array(block.children, at).flatMap((span, n) => {
+      const spanPath = `${at}.children[${n}]`
+      exact(span, ['_type', '_key', 'text', 'marks'], spanPath)
+      if (span._type !== 'span') fail(spanPath, 'custom inline objects require an explicit mapping')
+      const marks = marksFor(span, definitions, spanPath)
+      const text = plain(span.text, spanPath, 'string')
+      // Empty spans are not legal PM text nodes; their visible content is empty.
+      return text.split('\n').flatMap((part, j) => [...(j ? [{ type: 'hardBreak' }] : []), ...(part ? [{ type: 'text', text: part, ...(marks.length ? { marks } : {}) }] : [])])
+    })
+    const style = block.style ?? 'normal'
+    let node = { type: 'paragraph', attrs: { _key: key }, content: inline }
+    if (/^h[1-6]$/.test(style)) node = { ...node, type: 'heading', attrs: { _key: key, level: Number(style[1]) } }
+    else if (style === 'blockquote') node = { type: 'blockquote', attrs: { _key: key }, content: [{ ...node, attrs: { _key: `${key}_paragraph` } }] }
+    else if (style !== 'normal') fail(at, `unsupported block style ${style}`)
+    if (block.listItem === undefined) {
+      if (block.level !== undefined) fail(at, 'list level without list type')
+      stack.length = 0; content.push(node); continue
+    }
+    if (style !== 'normal' || !['bullet', 'number'].includes(block.listItem)) fail(at, 'unsupported list style')
+    const depth = block.level ?? 1, type = block.listItem === 'bullet' ? 'bulletList' : 'orderedList'
+    if (!Number.isInteger(depth) || depth < 1 || depth > 3 || depth > stack.length + 1) fail(at, 'ambiguous or unsupported list nesting')
+    stack.length = Math.min(stack.length, depth)
+    if (stack[depth - 1]?.type !== type) {
+      const list = { type, attrs: { _key: `${key}_list` }, content: [] }
+      if (depth === 1) content.push(list)
+      else stack[depth - 2].content.at(-1).content.push(list)
+      stack[depth - 1] = list
+    }
+    stack[depth - 1].content.push({ type: 'listItem', attrs: { _key: `${key}_item` }, content: [node] })
+  }
+  return { value: { type: 'doc', content: content.length ? content : [{ type: 'paragraph', attrs: { _key: 'empty' } }] }, embeds }
+}
+
+/** Families and asset paths are reviewed source facts, never guessed from slugs. */
+export function convertSnapshot(rows, mapping) {
+  exact(mapping, ['namespace', 'families', 'assets'], 'mapping')
+  plain(mapping.namespace, 'mapping.namespace', 'string')
+  const documents = new Map(), references = new Map(), selected = new Set(), familyKeys = new Set()
+  for (const row of rows) {
+    if (typeof row._id !== 'string' || documents.has(row._id)) fail('snapshot', 'missing or duplicate _id')
+    documents.set(row._id, row)
+  }
+  for (const family of array(mapping.families, 'families')) {
+    exact(family, ['key', 'primaryLocale', 'members'], 'family')
+    if (familyKeys.has(family.key)) fail(family.key, 'duplicate family key')
+    familyKeys.add(family.key)
+    if (!Object.hasOwn(family.members, family.primaryLocale)) fail(family.key, 'primary locale is missing')
+    for (const [locale, member] of Object.entries(family.members)) {
+      exact(member, ['sourceId', 'clearedPaths'], `${family.key}.${locale}`)
+      const id = member.sourceId
+      if (typeof id !== 'string' || /^(drafts|versions)\./.test(id)) fail(family.key, 'select an explicit published source document; draft/release mapping is separate')
+      if (!documents.has(id) || selected.has(id)) fail(id, 'missing source or source assigned twice')
+      const doc = documents.get(id)
+      if (doc.language !== undefined && doc.language !== locale) fail(id, 'language disagrees with reviewed family')
+      selected.add(id); references.set(id, family.key)
+    }
+  }
+  const media = object(mapping.assets, 'assets'), usedMedia = new Set()
+  const reference = (value, at) => {
+    exact(value, ['_type', '_ref', '_weak'], at)
+    if (value._type !== 'reference' || value._weak) fail(at, 'weak/cross-dataset references require a source decision')
+    const key = references.get(value._ref)
+    if (!key) fail(at, `missing source document ${value._ref}`)
+    return { _importDocument: key }
+  }
+  const image = (value, at) => {
+    exact(value, ['_type', '_key', 'asset', 'alt', 'caption', 'crop', 'hotspot'], at)
+    exact(value.asset, ['_type', '_ref'], `${at}.asset`)
+    const key = value.asset._ref, asset = documents.get(key)
+    if (value.asset._type !== 'reference' || !Object.hasOwn(media, key) || asset?._type !== 'sanity.imageAsset') fail(at, 'missing original image mapping')
+    usedMedia.add(key)
+    const occurrence = { assetId: { _importAsset: key } }
+    for (const name of ['alt', 'caption']) if (Object.hasOwn(value, name)) occurrence[name] = plain(value[name], at, 'string')
+    for (const name of ['crop', 'hotspot']) if (Object.hasOwn(value, name)) {
+      const keys = name === 'crop' ? ['top', 'bottom', 'left', 'right'] : ['x', 'y', 'height', 'width']
+      exact(value[name], ['_type', ...keys], `${at}.${name}`)
+      occurrence[name] = Object.fromEntries(keys.map(k => [k, plain(value[name][k], at, 'number')]))
+    }
+    return occurrence
+  }
+  const section = (value, at, nested = false) => {
+    const key = keyOf(value._key, at)
+    if (value._type === 'stack' && !nested) {
+      exact(value, ['_type', '_key', 'title', 'children'], at)
+      return { _key: key, _type: 'stack', ...optional(value, 'title', v => plain(v, at, 'string')), children: array(value.children, at).map((v, i) => section(v, `${at}.children[${i}]`, true)) }
+    }
+    if (value._type === 'image') return { _key: key, _type: 'picture', image: image(value, at) }
+    if (value._type === 'text') {
+      exact(value, ['_type', '_key', 'title'], at)
+      return { _key: key, _type: 'copy', title: plain(value.title, at, 'string') }
+    }
+    fail(at, `unsupported slice ${value._type}; nested containers need an explicit schema decision`)
+  }
+  const fields = id => {
+    const doc = documents.get(id)
+    exact(doc, ['_id', '_type', '_rev', '_createdAt', '_updatedAt', 'language', 'title', 'body', 'hero', 'sections', 'related', 'enabled', 'rank'], id)
+    if (!['page', 'settings'].includes(doc._type)) fail(id, `unmapped document type ${doc._type}`)
+    const result = {}
+    for (const [key, type] of [['title', 'string'], ['enabled', 'boolean'], ['rank', 'number']]) Object.assign(result, optional(doc, key, v => plain(v, `${id}.${key}`, type)))
+    Object.assign(result, optional(doc, 'related', v => reference(v, `${id}.related`)), optional(doc, 'hero', v => image(v, `${id}.hero`)),
+      optional(doc, 'sections', v => array(v, id).map((s, i) => section(s, `${id}.sections[${i}]`))))
+    if (Object.hasOwn(doc, 'body')) {
+      const body = portableText(doc.body, { path: 'body', reference, image })
+      result.body = body.value
+      if (body.embeds.length) result._richtextEmbeds = body.embeds
+    }
+    return result
+  }
+  const records = mapping.families.map(family => {
+    const primary = family.members[family.primaryLocale]
+    if (primary.clearedPaths?.length) fail(family.key, 'primary fields cannot inherit or clear fallback')
+    const storyType = documents.get(primary.sourceId)._type
+    const locales = Object.entries(family.members).filter(([locale]) => locale !== family.primaryLocale).sort(([a], [b]) => a.localeCompare(b)).map(([locale, member]) => {
+      if (documents.get(member.sourceId)._type !== storyType) fail(member.sourceId, 'family document types disagree')
+      const translated = fields(member.sourceId), clearedPaths = member.clearedPaths ?? []
+      for (const path of array(clearedPaths, member.sourceId)) if (!['title', 'body', 'hero', 'sections', 'related', 'enabled', 'rank'].includes(path) || Object.hasOwn(translated, path)) fail(member.sourceId, `ambiguous cleared path ${path}`)
+      return { locale, fields: translated, ...(clearedPaths.length ? { clearedPaths } : {}) }
+    })
+    return parseImportRecord({ key: family.key, storyType, primaryLocale: family.primaryLocale, fields: fields(primary.sourceId), ...(locales.length ? { locales } : {}) })
+  })
+  planImportBatches(records)
+  for (const key of Object.keys(media)) if (!documents.has(key) || !['sanity.imageAsset', 'sanity.fileAsset'].includes(documents.get(key)._type)) fail(key, 'asset mapping has no source asset document')
+  return { records: records.sort((a, b) => a.key.localeCompare(b.key)), assets: Object.entries(media).sort(([a], [b]) => a.localeCompare(b)).map(([key, file]) => ({ key, file, displayName: documents.get(key).originalFilename ?? basename(file), ...(documents.get(key).mimeType ? { mimeType: documents.get(key).mimeType } : {}) })),
+    report: { selectedDocuments: [...selected].sort(), excludedDocuments: rows.filter(r => !selected.has(r._id) && !Object.hasOwn(media, r._id)).map(r => r._id).sort(), unusedOriginals: Object.keys(media).filter(k => !usedMedia.has(k)).sort() } }
+}
+
+async function fingerprint(file) {
+  const sha1 = createHash('sha1'), sha256 = createHash('sha256')
+  let size = 0
+  for await (const bytes of createReadStream(file)) { sha1.update(bytes); sha256.update(bytes); size += bytes.length }
+  return { sha1: sha1.digest('hex'), sha256: sha256.digest('hex'), size }
+}
+
+/** Reads only local source data and creates a new output directory. No network. */
+export async function prepareSnapshot(sourcePath, mappingPath, outputPath, schemaVersion) {
+  if (!schemaVersion) throw new Error('Pass the installed target schema version explicitly.')
+  if ((await stat(sourcePath)).size > 32 * 1024 * 1024 || (await stat(mappingPath)).size > 192 * 1024) throw new Error('Reference converter input exceeds its bounded snapshot/mapping limit.')
+  const source = await readFile(sourcePath, 'utf8'), mappingBytes = await readFile(mappingPath, 'utf8'), mapping = JSON.parse(mappingBytes)
+  const rows = source.split('\n').filter(line => line.trim()).map((line, i) => { try { return JSON.parse(line) } catch { return fail(`source:${i + 1}`, 'invalid JSON') } })
+  const converted = convertSnapshot(rows, mapping), root = await realpath(dirname(mappingPath))
+  const originals = []
+  for (const asset of converted.assets) {
+    const actual = await realpath(resolve(root, asset.file)), rel = relative(root, actual)
+    if (isAbsolute(asset.file) || rel === '..' || rel.startsWith('../') || isAbsolute(rel)) fail(asset.key, 'original must be inside the mapping directory')
+    const observed = await fingerprint(actual)
+    const sourceAsset = rows.find(r => r._id === asset.key)
+    if (sourceAsset.size !== undefined && sourceAsset.size !== observed.size) fail(asset.key, 'original byte length differs from snapshot')
+    if (sourceAsset.sha1hash !== undefined && sourceAsset.sha1hash !== observed.sha1) fail(asset.key, 'original checksum differs from snapshot')
+    originals.push({ ...asset, actual, sha256: observed.sha256, size: observed.size })
+  }
+  // Validate all files before creating any output. Never overwrite a prior corpus.
+  await mkdir(outputPath)
+  const assetFiles = []
+  for (const [index, asset] of originals.entries()) {
+    const name = `${index}-${basename(asset.actual)}`, file = `originals/${name}`, manifest = `asset-${index}.json`
+    await mkdir(resolve(outputPath, 'originals'), { recursive: true })
+    await copyFile(asset.actual, resolve(outputPath, file))
+    const copied = await fingerprint(resolve(outputPath, file))
+    if (copied.sha256 !== asset.sha256) fail(asset.key, 'source changed during copy; output is incomplete')
+    await writeFile(resolve(outputPath, manifest), JSON.stringify({ namespace: mapping.namespace, key: asset.key, file, displayName: asset.displayName, ...(asset.mimeType ? { mimeType: asset.mimeType } : {}) }, null, 2))
+    assetFiles.push(manifest)
+  }
+  await writeFile(resolve(outputPath, 'documents.ndjson'), converted.records.map(r => JSON.stringify(r)).join('\n') + '\n')
+  const manifest = { version: 1, destination: 'main', namespace: mapping.namespace, sourceDigest: hash(source), converter: `sanity-reference-v1:${hash(await readFile(fileURLToPath(import.meta.url)))}`,
+    schemaVersion, policy: 'create-only', records: ['documents.ndjson'], assets: assetFiles }
+  await writeFile(resolve(outputPath, 'report.json'), JSON.stringify({ ...converted.report, mappingDigest: hash(mappingBytes), recordsDigest: await importDigest(converted.records),
+    originals: originals.map(({ key, sha256, size }) => ({ key, sha256, size })) }, null, 2))
+  // Manifest last: an interrupted preparation never looks like a ready corpus.
+  await writeFile(resolve(outputPath, 'manifest.json'), JSON.stringify(manifest, null, 2))
+  return manifest
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [, , source, mapping, output, schemaVersion] = process.argv
+  if (!source || !mapping || !output) throw new Error('Usage: node convert.mjs <raw.ndjson> <mapping.json> <new-output-directory> <installed-schema-version>')
+  await prepareSnapshot(resolve(source), resolve(mapping), resolve(output), schemaVersion)
+}

package/examples/sanity/fixture/data.ndjson

@@ -0,0 +1,7 @@
+{"_id": "page.en", "_type": "page", "_rev": "fixture-en", "language": "en", "title": "Hello", "enabled": true, "rank": 4, "hero": {"_type": "image", "_key": "photo", "asset": {"_type": "reference", "_ref": "image-mark-24x24-svg"}, "alt": ""}, "related": {"_type": "reference", "_ref": "about.en"}, "body": [{"_type": "block", "_key": "intro", "style": "normal", "markDefs": [{"_type": "link", "_key": "website", "href": "https://example.com/"}], "children": [{"_type": "span", "_key": "span", "text": "Hello ", "marks": ["strong"]}, {"_type": "span", "_key": "span", "text": "world", "marks": ["website"]}]}, {"_type": "block", "_key": "bullet", "style": "normal", "markDefs": [], "children": [{"_type": "span", "_key": "span", "text": "First", "marks": []}], "listItem": "bullet", "level": 1}, {"_type": "block", "_key": "nested", "style": "normal", "markDefs": [], "children": [{"_type": "span", "_key": "span", "text": "Nested", "marks": []}], "listItem": "number", "level": 2}, {"_type": "image", "_key": "photo", "asset": {"_type": "reference", "_ref": "image-mark-24x24-svg"}, "alt": ""}], "sections": [{"_type": "stack", "_key": "stack1", "title": "Features", "children": [{"_type": "text", "_key": "copy1", "title": "Composable"}, {"_type": "image", "_key": "photo", "asset": {"_type": "reference", "_ref": "image-mark-24x24-svg"}, "alt": ""}]}]}
+{"_id": "page.fr", "_type": "page", "language": "fr", "title": "Bonjour", "enabled": false, "rank": 0, "sections": []}
+{"_id": "page.zh", "_type": "page", "language": "zh", "title": "你好", "body": [{"_type": "block", "_key": "intro", "style": "normal", "markDefs": [], "children": [{"_type": "span", "_key": "s", "text": "你好，世界", "marks": ["em"]}]}, {"_type": "image", "_key": "photo", "asset": {"_type": "reference", "_ref": "image-mark-24x24-svg"}, "alt": "标志"}]}
+{"_id": "about.en", "_type": "page", "language": "en", "title": "About", "related": {"_type": "reference", "_ref": "page.en"}, "body": [{"_type": "block", "_key": "about", "style": "normal", "markDefs": [], "children": [{"_type": "span", "_key": "span", "text": "About us", "marks": []}]}]}
+{"_id": "settings.en", "_type": "settings", "language": "en", "title": "Site", "enabled": true}
+{"_id": "drafts.page.en", "_type": "page", "title": "Unpublished draft excluded"}
+{"_id": "image-mark-24x24-svg", "_type": "sanity.imageAsset", "originalFilename": "mark.svg", "mimeType": "image/svg+xml", "size": 112, "sha1hash": "61dd7f31ce2baf2c747a17ff256e9d7e7422d4af"}

package/examples/sanity/fixture/mapping.json

@@ -0,0 +1,44 @@
+{
+  "namespace": "sanity-reference-production",
+  "families": [
+    {
+      "key": "home",
+      "primaryLocale": "en",
+      "members": {
+        "en": {
+          "sourceId": "page.en"
+        },
+        "fr": {
+          "sourceId": "page.fr"
+        },
+        "zh": {
+          "sourceId": "page.zh",
+          "clearedPaths": [
+            "hero"
+          ]
+        }
+      }
+    },
+    {
+      "key": "about",
+      "primaryLocale": "en",
+      "members": {
+        "en": {
+          "sourceId": "about.en"
+        }
+      }
+    },
+    {
+      "key": "settings",
+      "primaryLocale": "en",
+      "members": {
+        "en": {
+          "sourceId": "settings.en"
+        }
+      }
+    }
+  ],
+  "assets": {
+    "image-mark-24x24-svg": "originals/mark.svg"
+  }
+}

package/examples/sanity/fixture/originals/mark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="currentColor" d="M4 4h16v16H4z"/></svg>

package/examples/sanity/stories/articleBody.story

@@ -0,0 +1,23 @@
+story: articleBody
+kind: field
+extends: richtext
+label: Article body
+---
+richtext:
+  blocks:
+    paragraph: {}
+    heading: { levels: [1, 2, 3, 4, 5, 6] }
+    blockquote: {}
+  lists:
+    bullet: { maxDepth: 3 }
+    ordered: { maxDepth: 3 }
+  inline:
+    marks:
+      bold: {}
+      italic: {}
+      underline: {}
+      strike: {}
+      code: {}
+      link: { linkTypes: [url, document] }
+    hardBreak: true
+  embeds: [picture]

package/examples/sanity/stories/copy.story

@@ -0,0 +1,7 @@
+story: copy
+kind: slice
+label: Text
+---
+fields:
+  content:
+    title: { type: text }

package/examples/sanity/stories/page.story

@@ -0,0 +1,19 @@
+story: page
+kind: document
+label: Page
+---
+fields:
+  article:
+    body:
+      type: articleBody
+      editor:
+        zone: true
+  content:
+    title: { type: text }
+    hero: { type: image }
+    related: { type: reference, target: page }
+    enabled: { type: boolean }
+    rank: { type: number }
+    sections:
+      type: sliceZone
+      allowed: [copy, picture, stack]

package/examples/sanity/stories/picture.story

@@ -0,0 +1,7 @@
+story: picture
+kind: slice
+label: Picture
+---
+fields:
+  content:
+    image: { type: image }

package/examples/sanity/stories/settings.story

@@ -0,0 +1,9 @@
+story: settings
+kind: document
+singleton: true
+label: Settings
+---
+fields:
+  content:
+    title: { type: text }
+    enabled: { type: boolean }

package/examples/sanity/stories/stack.story

@@ -0,0 +1,10 @@
+story: stack
+kind: slice
+label: Stack
+---
+fields:
+  content:
+    title: { type: text }
+    children:
+      type: sliceZone
+      allowed: [copy, picture]

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@storystick/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0-rc.1",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "bin": {
+    "storystick": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "LICENSE",
+    "README.md",
+    "CONTENT-IMPORT.md",
+    "examples/sanity/README.md",
+    "examples/sanity/convert.mjs",
+    "examples/sanity/stories",
+    "examples/sanity/fixture",
+    "PUBLIC-API.md"
+  ],
+  "exports": {
+    "./resolve": {
+      "types": "./dist/resolve.d.ts",
+      "import": "./dist/resolve.js"
+    },
+    "./content-import": {
+      "types": "./dist/content-import.d.ts",
+      "import": "./dist/content-import.js"
+    },
+    "./asset-import": {
+      "types": "./dist/asset-import.d.ts",
+      "import": "./dist/asset-import.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false,
+    "tag": "beta"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.2.1",
+    "@modelcontextprotocol/server": "2.4.0",
+    "cac": "^6.7.14",
+    "esbuild": "^0.28.2",
+    "execa": "^9.6.1",
+    "open": "^11.0.0",
+    "ora": "^8.2.0",
+    "picocolors": "^1.1.1",
+    "zod": "^4.6.7",
+    "@storystick/core": "0.2.0-rc.1",
+    "@storystick/source": "0.1.0-rc.1",
+    "@storystick/types": "0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.4.0",
+    "@types/node": "^22.13.10",
+    "typescript": "^5.8.2",
+    "vitest": "^3.1.1"
+  },
+  "engines": {
+    "node": ">=24.19.0 <25"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withstorystick/storystick.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://storystick.app",
+  "bugs": {
+    "url": "https://storystick.app"
+  },
+  "scripts": {
+    "build": "node scripts/clean-dist.mjs && tsc",
+    "test": "pnpm run test:lint && vitest run",
+    "test:lint": "node scripts/lint-output.mjs",
+    "test:watch": "vitest"
+  }
 }