feat(cli): stx sync + deterministic stx update --locked (v0.7.15)

- New top-level `stx sync` command: project-level uv sync --locked
  (idempotent), walks up to find pyproject.toml. --upgrade-deps to
  refresh lock from pyproject.
- `stx update` now uses `uv sync --locked` by default; new
  `--upgrade-deps` flag opts back into the legacy behaviour
  (uv lock --upgrade-package streamtex + plain uv sync) — required
  when bumping streamtex after a PyPI release.
- Eliminates silent uv.lock flip-flop between editable and PyPI modes
  during routine updates.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: nicolasguelfi

CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.15] — 2026-05-25 — `stx sync` + deterministic `stx update --locked`
+
+### Added
+
+- **New top-level command `stx sync`** — project-level dependency sync.
+  Wraps `uv sync --locked` (deterministic, idempotent) for any directory
+  containing a `pyproject.toml`. Walks up from the cwd to find the
+  project root; `stx sync <path>` targets a specific directory.
+- **`stx sync --upgrade-deps`** removes `--locked` so `uv sync` may
+  refresh `uv.lock` from `pyproject.toml`. Use when pyproject changes
+  intentionally.
+- **`stx update --upgrade-deps`** flag: opt back into the legacy
+  behaviour (`uv lock --upgrade-package streamtex` + plain `uv sync`).
+  Required when bumping streamtex after a new PyPI release.
+
+### Changed
+
+- **`stx update` now uses `uv sync --locked` by default.** Routine
+  updates no longer rewrite `uv.lock` — they fail loudly when the lock
+  diverges from `pyproject.toml`, with a hint pointing to
+  `--upgrade-deps`. Eliminates silent lock flip-flop between editable
+  and PyPI modes.
+- The `--no-sources` fallback (used when a local editable source is
+  missing) still rewrites the lock; `_restore_uv_lock_if_only_dirty`
+  brings it back to the committed state after sync.
+
 ## [0.7.14] — 2026-05-24 — `stx claude update` redesign
 
 ### Changed

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "streamtex"
-version = "0.7.14"
+version = "0.7.15"
 description = "AI-powered content framework for Streamlit — create presentations, courses, and web-books with Claude or Cursor, no coding required."
 readme = "README.md"
 requires-python = ">=3.11"

streamtex/cli/commands.py

@@ -54,6 +54,7 @@
 from .screenshot_cmd import screenshot as stx_screenshot
 from .shortcuts import run_lint, run_test
 from .status_cmd import status as workspace_status
+from .sync_cmd import sync as stx_sync
 from .upgrade_cmd import upgrade as project_upgrade
 from .validate_cmd import validate as stx_validate
 from .workspace_cmd import update as workspace_update
@@ -70,6 +71,7 @@ def cli():
 cli.add_command(stx_install)
 cli.add_command(stx_run)
 cli.add_command(stx_screenshot)
+cli.add_command(stx_sync, name="sync")
 cli.add_command(workspace_update, name="update")
 cli.add_command(workspace_status, name="status")
 

streamtex/cli/sync_cmd.py

@@ -0,0 +1,97 @@
+"""stx sync — project-level deterministic dependency sync.
+
+Wraps ``uv sync --locked`` for any directory containing a pyproject.toml.
+Use this when you are not at a workspace root (where ``stx update`` is
+the right command for the whole workspace), but inside a single project
+— e.g. a pack subdirectory, a standalone document folder, or any
+``pyproject.toml``-bearing dir outside the workspace orchestration.
+
+Default uses ``--locked`` for idempotent, deterministic syncs. Pass
+``--upgrade-deps`` to allow ``uv`` to refresh the lock from pyproject.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+import click
+
+from .console import get_console
+from .workspace_cmd import _find_uv, _has_missing_local_sources, _restore_uv_lock_if_only_dirty
+
+
+def _find_pyproject_dir(start: Path) -> Path | None:
+    """Walk up from `start` until a directory containing pyproject.toml is found."""
+    current = start.resolve()
+    while True:
+        if (current / "pyproject.toml").is_file():
+            return current
+        if current.parent == current:
+            return None
+        current = current.parent
+
+
+@click.command("sync")
+@click.option(
+    "--upgrade-deps",
+    is_flag=True,
+    help="Allow uv to refresh uv.lock from pyproject.toml. Default is "
+    "--locked (deterministic sync to the committed lock state).",
+)
+@click.argument("path", required=False, type=click.Path(exists=True, file_okay=False))
+def sync(upgrade_deps: bool, path: str | None) -> None:
+    """Sync the current project's venv from uv.lock (deterministic by default).
+
+    With no arguments, syncs the project containing the current directory.
+    Pass PATH to sync a specific project directory.
+    """
+    console = get_console()
+    start = Path(path) if path else Path.cwd()
+    project_dir = _find_pyproject_dir(start)
+    if project_dir is None:
+        raise click.ClickException(
+            f"No pyproject.toml found in {start} or any parent directory."
+        )
+
+    uv = _find_uv()
+    no_sources = _has_missing_local_sources(str(project_dir))
+
+    cmd = [uv, "sync"]
+    if no_sources:
+        cmd.append("--no-sources")
+        console.print(f"[cyan]{project_dir.name}[/cyan]: uv sync --no-sources (editable source not found) …")
+    elif upgrade_deps:
+        console.print(f"[cyan]{project_dir.name}[/cyan]: uv sync (upgrade-deps) …")
+    else:
+        cmd.append("--locked")
+        console.print(f"[cyan]{project_dir.name}[/cyan]: uv sync --locked …")
+
+    result = subprocess.run(
+        cmd,
+        cwd=str(project_dir),
+        capture_output=True,
+        text=True,
+        timeout=180,
+    )
+    if result.returncode == 0:
+        console.print(f"[green]{project_dir.name}[/green]: ok")
+        if no_sources:
+            _restore_uv_lock_if_only_dirty(str(project_dir))
+        return
+
+    stderr_text = (result.stderr or "").strip()
+    if "--locked" in cmd and ("lock" in stderr_text.lower() or "out of date" in stderr_text.lower()):
+        console.print(f"[yellow]{project_dir.name}[/yellow]: lock out of date")
+        console.print(
+            "[dim]Run `stx sync --upgrade-deps` to refresh the lock from pyproject.toml, "
+            "or fix the divergence manually.[/dim]"
+        )
+        if stderr_text:
+            console.print(f"[dim]{stderr_text}[/dim]")
+        raise click.ClickException("uv sync --locked failed")
+
+    console.print(f"[red]{project_dir.name}[/red]: uv sync failed")
+    if stderr_text:
+        console.print(f"  {stderr_text}")
+    raise click.ClickException("uv sync failed")

streamtex/cli/workspace_cmd.py

@@ -355,6 +355,8 @@ def _run_uv_sync(
     repos: dict,
     ws_root: str,
     type_filter: set[str] | None = None,
+    *,
+    upgrade_deps: bool = False,
 ) -> None:
     """Run ``uv sync`` in selected repos and projects.
 
@@ -366,11 +368,18 @@ def _run_uv_sync(
         Absolute path to the workspace root.
     type_filter:
         If provided, only sync repos whose *type* is in this set.
+    upgrade_deps:
+        When True, actively upgrade ``streamtex`` in the lock (legacy
+        behaviour). When False (default), pass ``--locked`` to ``uv sync``
+        so the lock is never modified — deterministic sync to the committed
+        state. The ``--no-sources`` fallback always drops ``--locked``
+        because it intentionally rewrites the lock to PyPI mode.
     """
     uv = _find_uv()
     console = get_console()
     synced = 0
     skipped = 0
+    needs_upgrade_hint = False
 
     targets = _collect_sync_targets(repos, ws_root, type_filter)
 
@@ -379,8 +388,7 @@ def _run_uv_sync(
         return
 
     for target_name, target_path in targets:
-        # Upgrade streamtex in the lock file first (skip for the library itself)
-        if _depends_on_streamtex(target_path):
+        if upgrade_deps and _depends_on_streamtex(target_path):
             no_src = _has_missing_local_sources(target_path)
             lock_cmd = [uv, "lock", "--upgrade-package", "streamtex"]
             if no_src:
@@ -399,13 +407,17 @@ def _run_uv_sync(
                 skipped += 1
                 continue
 
-        # If local editable sources are missing, fall back to PyPI
+        no_sources = _has_missing_local_sources(target_path)
         cmd = [uv, "sync"]
-        if _has_missing_local_sources(target_path):
+        if no_sources:
             cmd.append("--no-sources")
             console.print(f"  [cyan]{target_name}[/cyan]: running uv sync --no-sources (editable source not found) …")
+        elif upgrade_deps:
+            console.print(f"  [cyan]{target_name}[/cyan]: running uv sync (upgrade-deps) …")
         else:
-            console.print(f"  [cyan]{target_name}[/cyan]: running uv sync …")
+            cmd.append("--locked")
+            console.print(f"  [cyan]{target_name}[/cyan]: running uv sync --locked …")
+
         result = subprocess.run(
             cmd,
             cwd=target_path,
@@ -416,17 +428,28 @@ def _run_uv_sync(
         if result.returncode == 0:
             console.print(f"  [green]{target_name}[/green]: ok")
             synced += 1
-            # --no-sources rewrites uv.lock (local paths → PyPI).
-            # Restore the committed version so the repo stays clean.
-            if "--no-sources" in cmd:
+            if no_sources:
                 _restore_uv_lock_if_only_dirty(target_path)
         else:
-            console.print(f"  [red]{target_name}[/red]: failed")
-            if result.stderr:
-                console.print(f"    {result.stderr.strip()}")
+            stderr_text = (result.stderr or "").strip()
+            if "--locked" in cmd and ("lock" in stderr_text.lower() or "out of date" in stderr_text.lower()):
+                console.print(
+                    f"  [yellow]{target_name}[/yellow]: lock out of date "
+                    "— re-run with `stx update --upgrade-deps`"
+                )
+                needs_upgrade_hint = True
+            else:
+                console.print(f"  [red]{target_name}[/red]: failed")
+                if stderr_text:
+                    console.print(f"    {stderr_text}")
             skipped += 1
 
     console.print(f"\n[bold]Done:[/bold] {synced} synced, {skipped} skipped")
+    if needs_upgrade_hint:
+        console.print(
+            "[dim]Hint: `stx update --upgrade-deps` refreshes the lock when "
+            "pyproject.toml has new constraints or new streamtex versions exist.[/dim]"
+        )
 
 
 # ---------------------------------------------------------------------------
@@ -838,7 +861,13 @@ def _upgrade_cli_tool(
 @click.option("--dry-run", is_flag=True, help="Show steps without executing.")
 @click.option("--repair", is_flag=True, help="Run repair checks (broken venv, missing __init__.py).")
 @click.option("--force", is_flag=True, help="Overwrite locally modified profile files (backup in .claude/.backup/).")
-def update(skip_sync, skip_profiles, dry_run, repair, force):
+@click.option(
+    "--upgrade-deps",
+    is_flag=True,
+    help="Allow uv to refresh uv.lock (upgrade streamtex + apply pyproject changes). "
+    "Default is --locked: deterministic sync to the committed lock state.",
+)
+def update(skip_sync, skip_profiles, dry_run, repair, force, upgrade_deps):
     """Pull repos, clone missing, sync deps, install hooks, update profiles."""
     ws_root, config = _require_workspace()
     repos = config.get("repos", {})
@@ -995,10 +1024,13 @@ def _step(label: str) -> None:
         _step("Syncing dependencies …")
         if dry_run:
             for target_name, target_path in _collect_sync_targets(repos, ws_root):
-                upgrade = " (+ upgrade streamtex)" if _depends_on_streamtex(target_path) else ""
-                console.print(f"  [cyan]{target_name}[/cyan]: would uv sync{upgrade}")
+                if upgrade_deps:
+                    upgrade = " (+ upgrade streamtex)" if _depends_on_streamtex(target_path) else ""
+                    console.print(f"  [cyan]{target_name}[/cyan]: would uv sync{upgrade}")
+                else:
+                    console.print(f"  [cyan]{target_name}[/cyan]: would uv sync --locked")
         else:
-            _run_uv_sync(repos, ws_root)
+            _run_uv_sync(repos, ws_root, upgrade_deps=upgrade_deps)
 
     # --- project migrations ---
     if not skip_sync: