Merge branch 'feature/update-skills' into development

Author: setoelkahfi

.agents/skills/smbcloud-cli-release/SKILL.md

@@ -19,6 +19,7 @@ Use this skill when work touches any part of the smbCloud CLI distribution flow:
 Use these files as the release source of truth:
 
 - Rust crate version and binary name: `crates/cli/Cargo.toml`
+- Workspace crate dependency versions: `Cargo.toml` under `[workspace.dependencies]`
 - SDK WASM crate version: `crates/smbcloud-auth-sdk-wasm/Cargo.toml`
 - SDK npm package version: `sdk/npm/smbcloud-auth/package.json`
 - SDK npm build script: `sdk/npm/smbcloud-auth/prepare-package.mjs`
@@ -27,6 +28,8 @@ Use these files as the release source of truth:
 - npm platform package generator: `npm/scripts/render-platform-package.cjs`
 - npm wrapper package generator: `npm/scripts/render-main-package.cjs`
 - npm wrapper launcher: `npm/smbcloud-cli/src/index.ts`
+- npm wrapper committed package metadata: `npm/smbcloud-cli/package.json`
+- npm wrapper committed lockfile: `npm/smbcloud-cli/package-lock.json`
 - PyPI package metadata: `pypi/pyproject.toml`
 - PyPI package README: `pypi/README.md`
 - SDK PyPI package metadata: `sdk/python/pyproject.toml`
@@ -39,8 +42,16 @@ Use these files as the release source of truth:
 
 The SDK npm package `@smbcloud/sdk-auth` must have its version in `sdk/npm/smbcloud-auth/package.json` match the version in `crates/smbcloud-auth-sdk-wasm/Cargo.toml` exactly. The `prepare-package.mjs` script enforces this at build time and will fail CI if they diverge.
 
+When bumping workspace crate versions for a release, also update the version constraints in the root `Cargo.toml` under `[workspace.dependencies]` so every `smbcloud-*` path dependency points at the same release version.
+
 When bumping workspace crate versions for a release, always update `sdk/npm/smbcloud-auth/package.json` in the same commit.
 
+The npm wrapper package is generated, but its checked-in files still need to match the release version before tagging:
+
+- rerender `npm/smbcloud-cli/package.json` with `node ../scripts/render-main-package.cjs ./package.json <version>`
+- refresh `npm/smbcloud-cli/package-lock.json` with `npm install`
+- commit both files so CI and local packaging agree on the wrapper version and optional dependency versions
+
 The same applies to the Ruby gems in `sdk/gems/`. For each gem (`auth`, `model`):
 
 - `lib/<gem>/version.rb` — the gem version constant
@@ -66,9 +77,16 @@ Workflow:
 If a tag was placed on the wrong commit (e.g. before a last-minute fix), move it:
 
 1. Merge the fix into `development`.
-2. Force-move the tag: `git tag -f v<version>`.
+2. Recreate the annotated tag on the correct commit: `git tag -fa v<version> -m "v<version>"`.
 3. Force-push the tag: `git push origin v<version> --force`.
 
+When verifying the remote tag, remember that annotated tags have two refs. `git ls-remote --tags origin refs/tags/v<version>*` should show:
+
+- `refs/tags/v<version>` — the tag object
+- `refs/tags/v<version>^{}` — the peeled commit
+
+The peeled `^{}` ref is the one that must match the intended release commit.
+
 The `release-crate.yml` orchestrator triggers on `push.tags: "v*.*.*"`, so the force-push will re-trigger the full release chain.
 
 ## Release model
@@ -109,6 +127,7 @@ It is built from `pypi/pyproject.toml` with `maturin` and `bindings = "bin"`, so
 1. Confirm npm auth with `npm whoami`.
 2. Confirm the crate version in `crates/cli/Cargo.toml`.
 3. Use the same version string for every npm package in that release.
+4. Rerender `npm/smbcloud-cli/package.json` and refresh `npm/smbcloud-cli/package-lock.json` before tagging if the wrapper version changed.
 
 ### Build platform binaries
 

.agents/skills/smbcloud-deploy-nextjs/SKILL.md

@@ -310,6 +310,13 @@ Fix:
 
 ### `Cannot find module 'styled-jsx'`, `@swc/helpers`, or other pnpm peer deps
 
+A common concrete failure looks like:
+
+- `code: 'MODULE_NOT_FOUND'`
+- `path: '/home/git/apps/web/<app>/node_modules/@swc/helpers'`
+
+That usually means the standalone upload succeeded, but the top-level hoisted symlink for a scoped package was not recreated on the server.
+
 Cause:
 
 - pnpm stores peer dependencies inside `node_modules/.pnpm/<pkg>@<version>/node_modules/<pkg>` with internal symlinks that Node's standard `require.resolve()` cannot follow
@@ -318,10 +325,15 @@ Cause:
 
 Fix:
 
-- the CLI deploy script now auto-hoists: after uploading standalone output, it scans `node_modules/.pnpm/*/node_modules/*` and creates symlinks at `node_modules/<pkg>` for any packages not already present
-- this restores the resolution structure that pnpm normally provides via its `.pnpm/node_modules/` virtual directory
-- no manual intervention needed for new deploys
-- to fix a server manually: `find node_modules/.pnpm -mindepth 2 -maxdepth 2 -type d -name node_modules` and symlink each child into the root `node_modules/`
+- the CLI deploy script now auto-hoists in two passes:
+  - first mirror pnpm's virtual directory at `node_modules/.pnpm/node_modules/*`
+  - then fall back to scanning `node_modules/.pnpm/*/node_modules/*` for anything still missing
+- this preserves pnpm's exact resolved package choice and fixes scoped packages like `@swc/helpers` as well as unscoped ones like `styled-jsx`
+- no manual intervention needed for new deploys once the updated CLI is used
+- to fix a server manually, prefer pnpm's virtual directory as the source of truth:
+  - create `node_modules/@scope/` directories as needed
+  - symlink `node_modules/<pkg>` or `node_modules/@scope/<pkg>` to the corresponding entry under `node_modules/.pnpm/node_modules/`
+  - only if that directory is missing, scan individual `.pnpm/<store-entry>/node_modules/*` folders as a fallback
 
 ### Wrong port after deploy
 

crates/cli/src/deploy/process_deploy_nextjs_ssr.rs

@@ -456,9 +456,30 @@ ECOSYSTEM_EOF
 
     # pnpm standalone output buries peer deps inside node_modules/.pnpm/
     # without the top-level symlinks Node needs for require.resolve().
-    # Scan the .pnpm store and create flat symlinks. For scoped packages,
-    # always force-replace partial rsync copies with symlinks to the .pnpm
-    # store entry that has the most content (not just package.json).
+    # First mirror pnpm's own virtual node_modules directory when it exists —
+    # this preserves the exact version selection pnpm already resolved, which is
+    # especially important for scoped packages like @swc/helpers.
+    # Then fall back to scanning individual .pnpm store entries for anything the
+    # virtual directory did not expose.
+    if [ -d "node_modules/.pnpm/node_modules" ]; then
+        for pkg_path in node_modules/.pnpm/node_modules/*; do
+            [ -e "$pkg_path" ] || continue
+            pkg_name=$(basename "$pkg_path")
+            if [ "${{pkg_name:0:1}}" = "@" ] && [ -d "$pkg_path" ]; then
+                mkdir -p "node_modules/$pkg_name"
+                for sub_path in "$pkg_path"/*; do
+                    [ -e "$sub_path" ] || continue
+                    sub_name=$(basename "$sub_path")
+                    rm -rf "node_modules/$pkg_name/$sub_name"
+                    ln -sfn "$APP_PATH/$sub_path" "node_modules/$pkg_name/$sub_name"
+                done
+            else
+                rm -rf "node_modules/$pkg_name"
+                ln -sfn "$APP_PATH/$pkg_path" "node_modules/$pkg_name"
+            fi
+        done
+    fi
+
     if [ -d "node_modules/.pnpm" ]; then
         find node_modules/.pnpm -mindepth 2 -maxdepth 2 -type d -name "node_modules" 2>/dev/null | while read pnpm_nm; do
             for pkg_path in "$pnpm_nm"/*; do
@@ -484,7 +505,10 @@ ECOSYSTEM_EOF
                         fi
                     done
                 else
-                    [ -e "node_modules/$pkg_name" ] || ln -sfn "$APP_PATH/$pkg_path" "node_modules/$pkg_name"
+                    if [ -e "node_modules/$pkg_name" ]; then
+                        continue
+                    fi
+                    ln -sfn "$APP_PATH/$pkg_path" "node_modules/$pkg_name"
                 fi
             done
         done