@uxnan/shared 0.0.14-alpha.20260810 → 0.0.15-alpha.20260813

package/README.md

@@ -3,7 +3,7 @@
 ![TypeScript](https://img.shields.io/badge/TypeScript-ESM-3178C6?style=for-the-badge&logo=typescript&logoColor=white)
 ![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A518-339933?style=for-the-badge&logo=nodedotjs&logoColor=white)
 ![JSON Schema](https://img.shields.io/badge/validation-Ajv-000000?style=for-the-badge&logo=json&logoColor=white)
-![Contracts](https://img.shields.io/badge/69_methods_%7C_12_notifications-blue?style=for-the-badge)
+![Contracts](https://img.shields.io/badge/70_methods_%7C_12_notifications-blue?style=for-the-badge)
 
 Shared JSON-RPC and E2EE contracts for the [Uxnan](../README.md) ecosystem — the
 single source of truth every component agrees on. Consumed as a local workspace

package/dist/src/jsonrpc/methods.d.ts

@@ -223,7 +223,23 @@ export interface GitBranchParams {
 export interface GitWorktreeParams {
     cwd: string;
     branch: string;
-    path: string;
+    /**
+     * Absolute directory for the new worktree. **Optional**: omit it (with
+     * {@link managed}) and the bridge resolves the location itself, from its
+     * `worktrees` config — by default the managed root
+     * `<home>/uxnan/worktrees/<repo>/<branch>`, the same layout the desktop uses,
+     * so both apps group one repository's checkouts in one place.
+     *
+     * A bridge that does not advertise `features.managedWorktrees` still
+     * **requires** this, so a client that wants to work against an older bridge
+     * has to keep deriving a path as its fallback.
+     */
+    path?: string;
+    /**
+     * Let the bridge own the location (the default when {@link path} is absent).
+     * A managed worktree is recorded in the bridge's registry, so the ones uxnan
+     * created can be told from the ones that were already there.
+     */
     managed?: boolean;
 }
 export interface GitRevertParams {

package/dist/src/models/git.d.ts

@@ -56,10 +56,12 @@ export interface GitWorktreeResult {
 /**
  * One entry of `git worktree list --porcelain`.
  *
- * A repository's worktrees are siblings on disk, not children — a checkout of
- * `repo` at `../repo-feature` is a peer directory with no path relationship to
- * its main worktree. That is precisely why a client cannot infer the hierarchy
- * from paths alone and has to be told.
+ * A worktree can live anywhere: beside its repository (`../repo-feature`),
+ * grouped under the folder uxnan manages (`~/uxnan/worktrees/<repo>/<branch>`),
+ * or wherever the user put it. None of those spellings is a child of the main
+ * worktree, and the grouped one shares a prefix with worktrees of OTHER
+ * repositories — which is precisely why a client cannot infer the hierarchy
+ * from paths and has to be told.
  */
 export interface GitWorktreeEntry {
     /** Absolute path of the worktree. */

package/dist/src/models/session.d.ts

@@ -72,4 +72,17 @@ export interface BridgeFeatures {
      * whether it waits there or goes straight through.
      */
     midTurnDelivery?: boolean;
+    /**
+     * The bridge resolves where a worktree goes on its own, so `git/createWorktree`
+     * accepts `managed: true` **without** a `path` and places it under the managed
+     * root (`<home>/uxnan/worktrees/<repo>/<branch>` by default) — the same layout
+     * the desktop uses, so one repository's checkouts stay grouped no matter which
+     * app created them.
+     *
+     * Absent/false → the bridge still **requires** `path`, and a client must keep
+     * deriving one itself. That fallback is worth keeping aligned with the
+     * desktop's spelling: the two derivations had already drifted into different
+     * folder names for the same repository and branch.
+     */
+    managedWorktrees?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uxnan/shared",
-  "version": "0.0.14-alpha.20260810",
+  "version": "0.0.15-alpha.20260813",
   "description": "Shared JSON-RPC and E2EE contracts for the Uxnan ecosystem (bridge, relay, mobile).",
   "license": "MPL-2.0",
   "author": "Luis Donaldo Gamas Vazquez",