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

package/CONTENT-IMPORT.md

@@ -0,0 +1,349 @@
+# Content import (development implementation)
+
+This interface imports Main drafts through the Storystick gateway. It never
+publishes documents, deploys a website, or changes schema/locale configuration.
+The path is qualified locally with release tarballs, an actual isolated backend,
+Content Plane, workerd, real development R2 and manual Studio/site preview. It
+is not publicly released; coordinated service/package rollout remains pending.
+
+Authenticate with `storystick login`, select a project with `--project`, and
+install Story Files and locales through the existing tools first. The expected
+`schemaVersion` is the installed version returned by `push --json`.
+
+## Input
+
+A JSON manifest references local NDJSON files inside its directory:
+
+```json
+{
+  "version": 1,
+  "destination": "main",
+  "namespace": "sanity-production",
+  "sourceDigest": "sha256-of-the-authoritative-source-snapshot",
+  "converter": "diduenjoy-converter-v1",
+  "schemaVersion": "installed-schema-version",
+  "policy": "create-only",
+  "records": ["documents.ndjson"],
+  "assets": ["hero.asset.json"]
+}
+```
+
+Each NDJSON line is one document family. Fields use the native content contract.
+The temporary marker `{"_importDocument":"source-key"}` resolves to a native ID
+wherever that ID belongs (reference field, link or pathname segment).
+Rich text uses the native serialized ProseMirror document contract: store
+`JSON.stringify({ type: "doc", content: [...] })` in the rich-text field. Import
+markers inside its link attributes are resolved too; literal prose is preserved.
+This keeps nested lists editable without exceeding database nesting limits.
+
+```json
+{"key":"home","storyType":"page","primaryLocale":"en","fields":{"title":"Hello","related":{"_importDocument":"about"}},"locales":[{"locale":"fr","fields":{"title":"Bonjour"}},{"locale":"zh","fields":{},"clearedPaths":["title"],"ownedPaths":[]}]}
+{"key":"about","storyType":"page","primaryLocale":"en","fields":{"title":"About"}}
+```
+
+Omitted locales stay absent. Omitted localized paths inherit; `clearedPaths`
+masks fallback. Supplied paths are owned by default, including empty strings,
+empty arrays, `false` and `0`. `ownedPaths` specifies native path ownership.
+`richtextEmbedOrder` optionally preserves the native relative order of localized
+rich-text sidecar blocks. The current input does not expose keyed-array overlays;
+do not flatten those existing states into this format.
+
+Document writes require ready Storystick assets. A native `assetId` may be
+replaced in the input by `{"_importAsset":"image-hero-original"}`. The server
+resolves that source key inside this project's manifest namespace; document and
+asset keyspaces are distinct. List local asset manifests in `assets` to plan
+files and documents together. The CLI checks every original locally before any
+remote planning, then reserves source identities without creating media. The
+server validates prospective media types against the target schema. Existing
+ready assets can also be referenced without including local originals.
+For example, `{"hero":{"assetId":{"_importAsset":"image-hero-original"},"alt":""}}`
+preserves the decorative occurrence while resolving only its identity.
+Crop, hotspot, caption and locale overrides remain native field data.
+The corpus digest binds every declared original, including unused files. Before
+writing any documents, apply requires native verified-ready receipts for the
+entire media inventory. Imported originals retain their source identity across
+first upload and explicit renewal; other native asset references pin a version.
+Editor replacements and archive are conflicts. Source URLs, storage
+credentials and server fetching of arbitrary URLs are not accepted here.
+
+## Original-file imports
+
+A combined corpus imports its listed originals automatically after the reviewed
+plan digest is checked. Individual files can also be planned and uploaded with
+`import-asset`, then referenced by source key or native `assetId`. The Node client is exported as
+`@storystick/cli/asset-import`. No Convex or storage credentials are needed.
+
+An asset manifest references a local file (inside the manifest directory):
+
+```json
+{
+  "namespace": "sanity-production",
+  "key": "image-hero-original",
+  "file": "originals/hero.png",
+  "displayName": "Hero",
+  "altDefault": "Description of the image"
+}
+```
+
+```sh
+storystick content import-asset asset.json --project 12345678 --dry-run --json
+storystick content import-asset asset.json --project 12345678 --apply --plan <digest> --json
+```
+
+The dry run hashes bytes locally and validates metadata remotely without creating
+assets or upload sessions. It reserves `(project, namespace, key)` to a native
+asset identity in protocol state. Apply creates that native asset/session before
+returning a scoped upload URL. Retrying that key
+with changed bytes or metadata is a conflict. Retrying identical input reuses
+the session or its ready receipt, including after temporary session GC. An
+editor's replacement or archive is never overwritten by this path.
+
+The client transfers exact bytes; native finalization verifies them and may strip
+invisible image metadata under the existing media policy. It does not resize or
+re-encode pixels. A lost PUT response is resolved through checksum verification;
+an existing object cannot be overwritten with the delegated URL. Sanitization
+retries require a server-authenticated source proof, never client checksum metadata.
+
+This interface covers JPEG, PNG, WebP, GIF, still AVIF, static SVG, video and supported file
+formats. Videos and files larger than 8 MiB use the native multipart cycle.
+The CLI hashes incrementally and uploads bounded parts, resumes from server
+receipts, and finalizes only after the server verifies the complete SHA-256.
+Part URLs bind the part number, byte length and MD5, and expire no later than the
+native session. Concurrent initialization retains one provider upload identity;
+known unused uploads are aborted. An unknown initialization outcome relies on
+the bucket's incomplete-multipart lifecycle, which must be qualified at deployment.
+
+An expired or failed upload returns a `renewable` receipt. Review the reported
+failure, then renew explicitly with the session ID and the same source/plan:
+
+```sh
+storystick content import-asset asset.json --project 12345678 --apply --plan <digest> --renew <upload-session-id> --json
+```
+
+Renewal retains the asset identity, allocates a new version/storage key, and
+passes native admission again. Replaying the same renewal returns that attempt;
+it never renews a second time implicitly. A pending upload must be resumed.
+An editor's intervening upload or archive is a conflict. Failed import shells
+remain owned by their source binding so session/version cleanup does not lose
+the asset identity; explicit library archive still prevents renewal. Version
+allocation stays monotonic even after failed-version cleanup. Old transferred
+objects follow native GC. After standalone renewal, resume the combined corpus
+with its original sealed plan. Asset acknowledgements are replayable receipts;
+`verify` rechecks all media, including originals unused by documents.
+
+### Project upload budgets
+
+The hourly upload guard is not a commercial tariff. A team owner or administrator
+can explicitly authorize a bounded project allowance through the gateway:
+
+```json
+{"requestId":"migration-2026-10","sessions":400,"bytes":1073741824,"reason":"Production snapshot originals"}
+```
+
+```sh
+storystick content upload-budget budget.json --project 12345678 --dry-run --json
+storystick content upload-budget budget.json --project 12345678 --apply --plan <digest> --json
+storystick content upload-budget --project 12345678 --json
+storystick content upload-budget-cancel migration-2026-10 --project 12345678 --json
+```
+
+The pre-launch server policy admits at most one budget per rolling 24 hours,
+capped at 5,000 new upload sessions and 10 GiB of declared bytes, expiring after
+24 hours. It replaces only the 120-sessions/hour guard while active. The ten
+simultaneous-upload guard, individual format limits and ready-storage quotas
+still apply. This policy is separate from future commercial entitlements.
+
+The project allowance covers **all native Media uploads**, including Studio and
+CLI uploads. Each new attempt consumes a session and its declared bytes in the
+allocation transaction. Resume/replay consumes nothing more; renewal is a new
+attempt. Failure does not refund admission. Cancellation ends the allowance;
+it does not stop already admitted transfers or allow another grant within the
+same day. Exhaustion returns a structured `RATE_LIMITED` error and `Retry-After`.
+
+Budget receipts and `assetUploadAdmissions` survive temporary-session cleanup
+and content wipe. They record admission, not actual network traffic or invoices.
+The public Node transport is `uploadBudgetTransport` from
+`@storystick/cli/asset-import`, using the same gateway session as other imports.
+
+### Static SVG originals
+
+SVG is a native image format, capped at 8 MiB. The server parses the entire UTF-8
+XML document and admits a bounded static profile: paths, basic shapes, groups,
+text, local gradients/patterns, clips/masks, local `<use>` references, simple
+presentation styles and bounded class/ID/element CSS rules. Embedded raster
+data URLs admit PNG, JPEG and WebP only. `currentColor` stays intact. Scripts,
+event handlers, custom DTDs/entities, external resources, links, CSS at-rules,
+animation and nested viewports are rejected explicitly. Standard SVG 1.0/1.1
+DOCTYPE declarations are recognized without fetching resources. Reference
+cycles and ambiguous referenced IDs are rejected. Accepted bytes are preserved
+exactly; rejected artwork is
+never silently sanitized or rasterized. Export a compatible static original
+when the error identifies an unsupported feature.
+
+Dimensions come from positive pixel lengths and/or `viewBox`. Delivery adds
+`nosniff` and an isolated CSP. The SDK and Studio display the vector original;
+width, height and display density do not generate raster substitutes. Cropping
+and explicit raster encoding are unsupported and return an error instead of
+being ignored. An external SVG's `currentColor` does not inherit the HTML page's
+color: preserve the original frontend's image/mask integration.
+
+## Plan, apply, resume
+
+```sh
+storystick content import manifest.json --project 12345678 --dry-run --json
+storystick content import manifest.json --project 12345678 --apply --plan <digest> --json
+storystick content import manifest.json --project 12345678 --resume <run-id> --apply --plan <digest> --json
+storystick content import-status <run-id> --project 12345678 --json
+storystick content verify <run-id> --project 12345678 --json
+storystick content import-cancel <run-id> --project 12345678 --json
+```
+
+Dry run reserves source identities and stores resumable protocol records on the
+server. It writes **no documents, assets, schema or locale configuration**. Only
+authorized project editors can stage or inspect that private input.
+`.storystick/imports/` stores a local run handle, not source content or credentials.
+The server is authoritative if that local file is lost. Keep local handles out
+of version control with the rest of `.storystick/` state.
+
+At most ten imports can be active per project. Temporary source input expires
+after 30 days and is pruned in bounded batches. Completed/cancelled runs are
+eligible immediately. Plans, receipts and source bindings survive input cleanup;
+an expired unfinished run must be prepared again with a new run ID.
+
+All batches must be planned before sealing the digest. Apply requires that exact
+digest and rechecks live permissions, schema generation, locale settings, draft
+witnesses and media versions. Lost responses reuse the same run/batch identity.
+Transient retries are bounded and honor Retry-After; longer waits are resumable.
+Native writes, usage facts, receipts and Preview clocks commit atomically per batch.
+
+- `create-only`: create new bindings; an identical unchanged prior import is a no-op.
+- `missing-only`: preserve existing bound drafts, including editor modifications.
+- `update-bound`: update only drafts matching the last imported witness. An
+  intervening editor change is a conflict even when requesting a fresh plan.
+
+No policy deletes content, changes a story/primary locale, or removes a locale
+implicitly. A new namespace does not take ownership of existing singletons.
+Resolve editorial conflicts explicitly; `--dry-run --new-run` prepares a fresh
+protocol run when appropriate. Cancel retains committed batches; it is not Undo.
+
+`verify` compares native readback with receipts and checks the Content Plane
+watermark separately. It exits nonzero for drift, incomplete imports or pending
+projection. A ready watermark is not proof of browser rendering: SDK readback,
+preview and visual acceptance remain separate.
+
+## Bounds and architecture
+
+The pure planner computes strongly connected components and orders dependencies
+before consumers. Cycles stay within one transaction; there are no invalid
+placeholder documents. Independent components are packed into batches of up to
+five documents to leave native execution headroom. Larger cycles remain atomic.
+Hard limits: 2,000 documents, 20 documents / 256 KiB per batch,
+32 MiB of staged input per run. Asset inventories are capped at 2,000 entries
+and the whole manifest at 384 KiB; acknowledgements/readback use groups of 20. Oversized cycles fail before staging. Native
+transaction limits still apply with large schemas/locales; exceeding them rolls
+back the batch rather than bypassing validation.
+
+The Node-only client is `@storystick/cli/content-import`; the pure format/planner
+is `@storystick/core/content-import`. Neither belongs in a rendering bundle.
+For a scripted combined corpus, compose `readContentImport`,
+`prepareContentImportAssets` and `prepareContentImport`, review the returned
+digest, upload the returned asset plans using `applyAssetImport`, then call
+`applyContentImport`. The latter acknowledges verified files before documents.
+A cancellation stops future document batches; independent asset uploads already
+admitted retain their normal native lifecycle.
+
+## Sanity reference converter
+
+The distributed [Sanity example](examples/sanity/README.md) is a local, explicit
+project mapping with Story Files, a synthetic three-language snapshot and tests.
+It preserves native rich text/embeds, container slices, cyclic references,
+original files and sparse locale intent. Unknown editorial data fails with a
+source path. Copy and adapt it to the actual source/frontend contract; it is not
+a universal schema converter. The isolated tarball qualification also runs its
+public Core/schema/client tests. A native component test checks its sidecar,
+locale and SVG writes without publication.
+
+## Gateway access boundary
+
+The SDK's public token audience is no longer accepted by raw Convex RPC. The
+WebSocket gateway exchanges it for a server-only, equally bounded credential;
+Next Preview's control reads/commands use the Storystick HTTP gateway and the
+existing native operations. This requires a coordinated Central/Worker/Next SDK
+release and a paired Worker service secret. See
+[`sub-gateway/README.md`](../../services/sub-gateway/README.md#gateway-only-sdk-authentication).
+No infrastructure secret is part of the migration client setup.
+
+## Qualification completed locally — 28 October 2026
+
+The consumer was installed outside the monorepo from release tarballs, including
+the CLI, Core and Next SDK. Its importer used ordinary Storystick credentials
+and public HTTP contracts; it received no Convex administration or R2 keys.
+An operator provisioned the isolated local Convex/Postgres/Content Plane/Workers
+and their secrets separately, as platform operations would in a hosted service.
+
+- The bundled Sanity example imported three document families, cyclic refs,
+  nested slices, a singleton, sparse `en/fr/zh`, native rich-text marks/lists and
+  embeds, and one original SVG. Native readback and projection matched receipts.
+- Actual R2 accepted exact original bytes, refused a signed-length mismatch and
+  refused overwrite after finalize. A 9 MiB multipart file resumed after its
+  first part, without resending it; replay transferred no more parts. A small
+  video used the native multipart cycle too. Complete hashes were verified.
+- The development bucket needed the already-tracked `If-None-Match` CORS header.
+  After applying that development CORS config, the real preflight returned 204.
+  Its incomplete multipart lifecycle was inspected: abort after seven days.
+  That configuration check does not claim an elapsed seven-day lifecycle test.
+- A consumer-only routable Story exercised Next preview. Native Studio edits
+  appeared in English, French and Chinese without a manual reload. The SVG
+  rendered as a vector in both Studio and the site. False/zero/empty collections,
+  inheritance and a deliberately cleared Chinese hero stayed distinct.
+- Final verification still matched the untouched Sanity corpus. The separately
+  edited route correctly reported a content conflict with a ready projection;
+  verification neither overwrote the editor's changes nor confused them with
+  delivery lag. CLI JSON classifies drift as a conflict and lag as retryable.
+- The actual auth provider rejected direct SDK RPC, accepted the server relay
+  credential, and the Worker relayed subscriptions/refresh. Public credentials
+  alone could not exchange for an internal token or submit usage counters.
+- HTTP attempt observations and sequential cumulative relay receipts were read
+  from the local backend. Unit/native-runtime cases cover unknown outcomes,
+  idempotent replay, producer authentication and bounded queues on meter failure.
+
+The real exercise found and corrected inherited-rich-text materialization,
+object rich-text embed composition, a Workers redirect-mode mismatch and the
+Studio reader's remaining raster-only restriction. It used synthetic content;
+it neither rewrote nor reimported the Diduenjoy website. All documents remained
+drafts and no website was deployed.
+
+Reproducible fast gates include `node scripts/content-import-qualification.mjs`
+(after package builds), the CLI's bundled Sanity tests, the native
+`content-import*.test.ts` component tests, targeted gateway authority/usage
+suites, and `pnpm --filter @storystick/sub-gateway test:runtime`. Mock-gateway
+packaging checks, local native infrastructure, and manual preview are separate
+proofs. None establishes production capacity.
+
+## Remaining release gates and limits
+
+- Publish matching artifacts/docs and roll out Central, relay and SDK together;
+  qualify deployment-specific auth, CORS, storage lifecycle and capacity there.
+- Choose commercial entitlements, aggregation/retention policy and accounting
+  export. The implementation provides durable facts, not a tariff or invoices.
+  `gatewayUsageAttempts` observes management and SDK HTTP attempts;
+  `gatewayRelayUsage` observes Worker-admitted payloads before forwarding.
+  Neither measures confirmed network delivery, repeated delegated R2 transfers
+  or provider egress. `contentUsageEvents` and upload admissions separately
+  describe native effects and admitted sessions/bytes. See the relay README.
+- The migration skill is structurally validated and now points to these concrete
+  capabilities. Its controlled with/without-skill behavioral evaluation is still
+  unmeasured; no model-quality improvement is claimed from infrastructure tests.
+- V1 imports Main drafts. Native `richtextEmbedOrder` is preserved on sparse
+  locale layers. Release destinations, keyed-array locale overlays and other
+  bundled CMS converters remain unsupported.
+
+Local qualification is not a deployment or publication.
+
+The image profile preserves GIF frame payloads, timing and loops. Still AVIF
+accepts unrotated item-based images and erases Exif/XMP without changing encoded
+image extents. Sequences and unsupported transforms fail explicitly. Static SVG
+originals up to 8 MiB may contain simple presentation styles, bounded local
+reuse, masks, gradients, color-matrix filters and embedded PNG/JPEG/WebP. Scripts,
+external resources, arbitrary DTDs, recursive or excessive expansion remain
+rejected. The delivery CSP allows only inline styles and embedded image data.

package/LICENSE

@@ -0,0 +1,112 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Tanguy Freycon
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+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.
+
+This Agreement shall be governed by the laws of France.

package/PUBLIC-API.md

@@ -0,0 +1,30 @@
+# @storystick/cli API contract
+
+Install this candidate explicitly with `@storystick/cli@0.2.0-rc.0` after registry bootstrap and publication. This repository alone does not make the candidate or beta channel available on npm.
+
+Version 0.2.0-rc.0, cohort `sdk-0.2.0-rc.0`. ESM distribution; no CommonJS or universal Edge compatibility is promised.
+
+This package is a product integration facade. Reserved contracts are required between SDK packages and must be upgraded with the same cohort. Their public export paths do not promise independent stability.
+
+| Entry | Status |
+| --- | --- |
+| `./resolve` | Supported beta entry |
+| `./content-import` | Supported beta entry |
+| `./asset-import` | Supported beta entry |
+
+## Command contract
+
+| Commands | Status |
+| --- | --- |
+| `setup`, `schema`, `generate`, `guide` | Supported beta local tooling |
+| `init`, `connect`, `login`, `logout`, `whoami`, `list`, `info`, `push`, `sync` | Supported beta onboarding/schema workflow; matching service and operator permissions required |
+| `archive`, `content`, `migrate`, `backfill-refs`, `slice-previews sync` | Advanced beta operations; plans, receipts, authorization and readback remain command-specific |
+| `source`, `release`, `connection`, `delivery`, `mcp` | Advanced matching-service contracts; server capability/permission checks apply, without independent protocol stability |
+
+Library exports `resolve`, `content-import` and `asset-import` are advanced beta Node APIs. The MCP host owns its model loop. Commands never acquire effect authority from this support table. Use each command's `--help` and the README for its exact flags, JSON/exit contract, confirmation and resumability rules.
+
+The qualified toolchain is Node 24.19.0 and pnpm 9.15.9. Next uses App Router 15.5.28, Sharp 0.35.5 and React/React DOM 19.2.8; Astro uses 7.4.4 with the Node adapter 11.1.9. Browser delivery is verified by bundling; hosted Preview activation and cross-browser behavior require the staging manual check. Source/CLI are Node tools, server entries belong on the server, and browser entries must never receive a server API key.
+
+This is a support/tooling contract. It does not independently grant project access or permission to perform effects.
+
+The repository is private. Public package availability does not make the monorepo public, and npm provenance from that repository is unavailable. Product and pilot support: [Storystick](https://storystick.app).