fix: harden sandbox flow and sync release bookkeeping

Author: flyingrobots

.devcontainer/README.md

@@ -7,7 +7,7 @@ It intentionally supports the existing contributor workflow:
 - `npm run dev`
 - `npm test`
 - `npm run test:e2e`
-- `npm run playground`
+- `npm run sandbox`
 
 Why it exists:
 
@@ -19,6 +19,6 @@ Why it exists:
 It is **not** the main reader quickstart. Blog readers should start with:
 
 - `npm run demo`
-- `npm run playground`
+- `npm run sandbox`
 
 Those paths are documented in [README.md](../README.md) and [docs/GETTING_STARTED.md](../docs/GETTING_STARTED.md).

CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to git-cms are documented in this file.
 
+## [Unreleased]
+
+## [1.2.0] — 2026-03-21
+
+### Added
+
+- **Reader-safe sandbox workflow:** Added a seeded long-lived `playground` container workflow with `sandbox` aliases, `GIT_CMS_REPO=/data/repo`, deterministic bootstrap, and host-side smoke coverage.
+- **Review lanes:** Added speculative editorial review lanes backed by `git-warp` working sets, including `CmsService` support, HTTP endpoints, admin UI controls, and E2E/integration tests.
+- **Blog and media support:** Added a public companion walkthrough (`docs/GIT_CMS_COMPANION.md`), reproducible browser/VHS media capture pipeline, and a contributor devcontainer.
+
+### Changed
+
+- **CLI repo root selection:** `bin/git-cms.js` now honors `GIT_CMS_REPO` before `process.cwd()`.
+- **Public onboarding:** README, quick reference, testing guide, ADR, and getting-started docs now distinguish `demo`, `sandbox`, and contributor `dev` modes explicitly.
+- **Dependencies:** Upgraded to `@git-stunts/git-cas` 5.3.2, `@git-stunts/git-warp` 14.8.0, `@git-stunts/vault` 1.0.1, `@playwright/test` 1.58.2, and `vitest` 4.1.0, with npm/pnpm overrides for patched transitives.
+
+### Fixed
+
+- **Published draft behavior:** Published articles can now accept newer draft commits while the published ref stays pinned until the next explicit publish.
+- **Publish semantics:** `publishArticle()` now only moves the published ref to the current draft tip; supplied `sha` values act as stale-write guards instead of arbitrary publish targets.
+- **Sandbox/bootstrap robustness:** Playground bootstrap now repairs incomplete seeded state instead of silently accepting any partial namespace.
+- **Warning noise:** Suppressed the `DEP0169` `url.parse()` warning from transitive dependencies and removed the `NO_COLOR`/`FORCE_COLOR` startup warning in wrapped entrypoints.
+- **Upload path handling:** Server upload path now uses the sanitized basename consistently when writing the temporary file and invoking asset storage.
+- **Version-restore UX/docs alignment:** Companion and reader docs now describe restore accurately: history is always visible, but published articles must be unpublished before restore.
+
 ## [1.1.5] — 2026-02-14
 
 ### Fixed
@@ -143,7 +168,9 @@ All notable changes to git-cms are documented in this file.
 - Admin UI: `selectVersion` guards against out-of-order async responses (prevents stale preview flash from rapid clicks)
 - **(P2) walkLimit divergence:** Extracted `HISTORY_WALK_LIMIT` as a shared exported constant used by both `_validateAncestry` and the server's history limit clamp
 
-[Unreleased]: https://github.com/flyingrobots/git-cms/compare/main...git-stunts
+[Unreleased]: https://github.com/flyingrobots/git-cms/compare/v1.2.0...main
+[1.2.0]: https://github.com/flyingrobots/git-cms/compare/v1.1.5...v1.2.0
+[1.1.5]: https://github.com/flyingrobots/git-cms/compare/v1.1.4...v1.1.5
 [1.1.4]: https://github.com/flyingrobots/git-cms/compare/v1.1.3...v1.1.4
 [1.1.3]: https://github.com/flyingrobots/git-cms/compare/v1.1.2...v1.1.3
 [1.1.2]: https://github.com/flyingrobots/git-cms/compare/v1.1.1...v1.1.2

QUICK_REFERENCE.md

@@ -1,6 +1,6 @@
 # Git CMS Quick Reference
 
-> Validated against v1.1.5 on 2026-03-15.
+> Validated against v1.2.0 on 2026-03-21.
 
 One-page cheat sheet for Git CMS commands, API endpoints, and concepts.
 

docs/GETTING_STARTED.md

@@ -1,6 +1,6 @@
 # Getting Started with Git CMS
 
-> Validated against v1.1.5 on 2026-03-15.
+> Validated against v1.2.0 on 2026-03-21.
 
 This guide is optimized for people arriving from the blog post. If you just want to see the stunt, use the reader-safe paths first.
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "git-cms",
-  "version": "1.1.5",
+  "version": "1.2.0",
   "description": "A Git-native, database-free CMS: article bodies in commit messages, publish by moving refs.",
   "homepage": "https://flyingrobots.dev/git-stunts/git-cms",
   "type": "module",

package.json

@@ -626,6 +626,7 @@ <h1>Git CMS</h1>
       selectedVersion: null,
       reviewLanes: [],
       activeReviewLane: null,
+      reviewLaneRequestId: 0,
     };
 
     /* ── API Layer ── */
@@ -1254,15 +1255,21 @@ <h1>Git CMS</h1>
       },
 
       async fetchReviewLanes() {
-        if (!state.currentSlug) {
+        const slug = state.currentSlug;
+        if (!slug) {
+          state.reviewLaneRequestId += 1;
           state.reviewLanes = [];
           this.renderReviewLanes();
           return;
         }
+        const requestId = ++state.reviewLaneRequestId;
         try {
-          state.reviewLanes = await api.listReviews(state.currentSlug);
+          const lanes = await api.listReviews(slug);
+          if (state.currentSlug !== slug || requestId !== state.reviewLaneRequestId) return;
+          state.reviewLanes = lanes;
           this.renderReviewLanes();
         } catch (err) {
+          if (state.currentSlug !== slug || requestId !== state.reviewLaneRequestId) return;
           state.reviewLanes = [];
           this.renderReviewLanes();
           toast('Failed to load review lanes', 'error');

pnpm-lock.yaml

@@ -209,8 +209,8 @@ echo ""
 echo "This is Git as a database. 🤯"
 echo ""
 echo "Next steps:"
-echo "  • Start the seeded playground: npm run playground"
-echo "  • Open a shell in it: npm run playground:shell"
+echo "  • Start the seeded sandbox: npm run sandbox"
+echo "  • Open a shell in it: npm run sandbox:shell"
 echo "  • Read the guide: docs/GETTING_STARTED.md"
 echo "  • Read the ADR: docs/ADR.md"
 echo "  • Explore the code: src/lib/CmsService.js"

public/index.html

@@ -10,6 +10,8 @@ AUTHOR_EMAIL="${GIT_AUTHOR_EMAIL:-playground@git-cms.local}"
 COMMITTER_NAME="${GIT_COMMITTER_NAME:-$AUTHOR_NAME}"
 COMMITTER_EMAIL="${GIT_COMMITTER_EMAIL:-$AUTHOR_EMAIL}"
 SKIP_SEED="${GIT_CMS_SKIP_SEED:-0}"
+DRAFT_REF="${REF_PREFIX}/articles/hello-world"
+PUBLISHED_REF="${REF_PREFIX}/published/hello-world"
 
 mkdir -p "$REPO_DIR"
 
@@ -20,10 +22,40 @@ fi
 git -C "$REPO_DIR" config user.name "$AUTHOR_NAME"
 git -C "$REPO_DIR" config user.email "$AUTHOR_EMAIL"
 
+seed_is_complete() {
+  local draft_sha published_sha history_count
+  draft_sha="$(git -C "$REPO_DIR" rev-parse -q --verify "$DRAFT_REF" 2>/dev/null || true)"
+  published_sha="$(git -C "$REPO_DIR" rev-parse -q --verify "$PUBLISHED_REF" 2>/dev/null || true)"
+
+  if [ -z "$draft_sha" ] || [ -z "$published_sha" ]; then
+    return 1
+  fi
+
+  if [ "$draft_sha" = "$published_sha" ]; then
+    return 1
+  fi
+
+  history_count="$(git -C "$REPO_DIR" rev-list --count "$DRAFT_REF" 2>/dev/null || echo 0)"
+  [ "$history_count" -ge 3 ]
+}
+
+delete_seed_refs() {
+  while IFS= read -r ref; do
+    if [ -n "$ref" ]; then
+      git -C "$REPO_DIR" update-ref -d "$ref"
+    fi
+  done < <(git -C "$REPO_DIR" for-each-ref "${REF_PREFIX}/" --format='%(refname)' || true)
+}
+
 existing_refs="$(git -C "$REPO_DIR" for-each-ref "${REF_PREFIX}/" --format='%(refname)' || true)"
 if [ -n "$existing_refs" ]; then
-  echo "Playground repo already contains refs under ${REF_PREFIX}; leaving existing state intact."
-  exit 0
+  if seed_is_complete; then
+    echo "Playground repo already contains the expected seeded state under ${REF_PREFIX}; leaving existing state intact."
+    exit 0
+  fi
+
+  echo "Playground repo contains incomplete state under ${REF_PREFIX}; repairing seeded refs."
+  delete_seed_refs
 fi
 
 if [ "$SKIP_SEED" = "1" ]; then
@@ -73,7 +105,7 @@ Try these next:
 - inspect refs
 - inspect the commit message
 - browse history
-- restore an older version
+- unpublish, then restore an older version
 EOF
 
 echo "Playground repo seeded under ${REF_PREFIX}."