@uxnan/shared 0.0.14-alpha.20260810 → 0.0.16-alpha.20260919

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/dist/src/models/usage.d.ts

@@ -11,8 +11,11 @@
  * over `agent/usageStats`. The Dart equivalents live in uxnanmobile and are kept
  * in sync manually (see 02e-bridge-integration.md §4.2).
  *
- * Posture: only the CLI's own stored token is read — never browser cookies or
- * user-pasted API keys.
+ * Posture: only the token the CLI itself stored is read — from its file, or
+ * from the OS credential store where that is where the CLI keeps it (Claude
+ * Code on macOS), and then only after the user has granted the OS-level
+ * permission once (see `accessRequired`). Never browser cookies, never
+ * user-pasted API keys, never a refresh token.
  */
 /** A coding CLI whose usage we read from its own stored token. */
 export type UsageProvider = 'codex' | 'claude' | 'copilot' | 'grok';
@@ -22,6 +25,11 @@ export type UsageStatus =
 'ok'
 /** CLI is present but not signed in (no usable token). */
  | 'authRequired'
+/** The CLI's token exists in the OS credential store, but the OS has not yet
+ *  authorized the reader to open it. The user grants that once from the
+ *  desktop's Providers panel (the OS shows its own dialog); the reader never
+ *  prompts on its own. A phone shows "grant access on the PC". */
+ | 'accessRequired'
 /** CLI / its config directory is not present on this machine. */
  | 'notInstalled'
 /** Read/network/parse failure — see {@link ProviderUsage.message}. */
@@ -121,7 +129,8 @@ export interface ProviderUsage {
     resetCredits?: ResetCredits;
     /** When this snapshot was produced (epoch ms). */
     updatedAt: number;
-    /** Error/hint message for `error` / `authRequired` / `notInstalled` states. */
+    /** Error/hint message for `error` / `authRequired` / `accessRequired` /
+     *  `notInstalled` states. */
     message?: string;
 }
 /**

package/dist/src/models/usage.js

@@ -11,8 +11,11 @@
  * over `agent/usageStats`. The Dart equivalents live in uxnanmobile and are kept
  * in sync manually (see 02e-bridge-integration.md §4.2).
  *
- * Posture: only the CLI's own stored token is read — never browser cookies or
- * user-pasted API keys.
+ * Posture: only the token the CLI itself stored is read — from its file, or
+ * from the OS credential store where that is where the CLI keeps it (Claude
+ * Code on macOS), and then only after the user has granted the OS-level
+ * permission once (see `accessRequired`). Never browser cookies, never
+ * user-pasted API keys, never a refresh token.
  */
 export {};
 //# sourceMappingURL=usage.js.map

package/dist/src/models/usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../../src/models/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../../src/models/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/package.json

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