@omercnet/paseo-fresh-worktrees 2.1.0 → 2.2.0-next.227.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/OVERVIEW.md ADDED
@@ -0,0 +1,7 @@
1
+ Fresh Worktrees updates the local base branch before Paseo creates a branch-off worktree, so new work starts from the latest remote code instead of a stale `main`.
2
+
3
+ Before the worktree is created, the plugin runs `git fetch --prune` against the repository's remote, then fast-forwards the local base branch with `git merge --ff-only`. It does this only when that branch is checked out in the source checkout and the checkout has no uncommitted changes. If the checkout is dirty, the fetch fails, or the update is not a fast-forward, it warns and the workspace is created from the existing local base. Explicit remote bases are fetched but no local branch is changed, and repositories without a remote are left alone.
4
+
5
+ It also shows `Behind · N` in the workspace header when a worktree is behind its source branch's remote. On Paseo 0.11 and later, a sidebar footer lists behind workspaces and offers **Refresh all**, which fast-forwards each clean source checkout and skips dirty or diverged ones. It never modifies worktree branches.
6
+
7
+ Setup: `git` on the daemon host. The plugin runs `git` there with the daemon's environment and contacts the repository's remote on each fetch. Requires Paseo ^0.9.0, ^0.10.0 or ^0.11.0.
package/README.md CHANGED
@@ -42,6 +42,15 @@ checkout emits a warning and skips the local branch update, allowing workspace c
42
42
  from the existing local base. Failed fetches and non-fast-forward updates do the same.
43
43
  Concurrent requests for the same target share one refresh, and updates are serialized per repository.
44
44
 
45
+ ### Sidebar footer (Paseo 0.11+)
46
+
47
+ On Paseo 0.11 and later a "Behind source branch" footer row shows how many workspaces are behind
48
+ their source branch. Its popover lists them and offers **Refresh all**, which fast-forwards each
49
+ clean source checkout to its upstream (never a dirty or diverged one, which are skipped and
50
+ reported), then rechecks every listed workspace. Worktree branches are not touched. "Behind" compares the
51
+ workspace `HEAD` with the remote-tracking ref of the source checkout's current branch, which is not
52
+ necessarily the workspace's recorded base. Paseo 0.9 and 0.10 hosts get no footer row.
53
+
45
54
  ## Install
46
55
 
47
56
  Paseo plugins are trusted, unsandboxed code. Review the source before installing it on the daemon
@@ -51,7 +60,7 @@ host.
51
60
  paseo plugin install npm:@omercnet/paseo-fresh-worktrees
52
61
  ```
53
62
 
54
- The plugin requires Paseo `^0.9.0 || ^0.10.0`.
63
+ The plugin requires Paseo `^0.9.0 || ^0.10.0 || ^0.11.0`.
55
64
 
56
65
  ## Develop
57
66
 
@@ -0,0 +1,99 @@
1
+ import type {
2
+ PluginClientContext,
3
+ PluginPopoverProps,
4
+ PluginSidebarItemProps,
5
+ } from "@getpaseo/plugin/client";
6
+ import { ScrollView } from "@getpaseo/plugin/client/react-native";
7
+ import { SidebarRow } from "@getpaseo/plugin/client/ui";
8
+ import { useState, useSyncExternalStore } from "react";
9
+ import { Pressable, Text, View } from "react-native";
10
+ import { describeRefresh, type WorkspaceSummary } from "./workspace-summary";
11
+
12
+ export function registerWorkspaceFooter(client: PluginClientContext, summary: WorkspaceSummary) {
13
+ if (typeof client.addSidebarFooterItem !== "function" || !SidebarRow) return;
14
+
15
+ function Popover({ theme, layout }: PluginPopoverProps) {
16
+ const entries = useSyncExternalStore(summary.subscribe, summary.getSnapshot);
17
+ const [pending, setPending] = useState(false);
18
+ const [message, setMessage] = useState<string | null>(null);
19
+ async function refreshAll() {
20
+ setPending(true);
21
+ setMessage(null);
22
+ try {
23
+ setMessage(describeRefresh(await summary.refreshAll()));
24
+ } finally {
25
+ setPending(false);
26
+ }
27
+ }
28
+ return (
29
+ <View
30
+ style={{
31
+ padding: layout.compact ? 16 : 20,
32
+ gap: 12,
33
+ backgroundColor: theme.colors.surface0,
34
+ width: layout.compact ? "100%" : 360,
35
+ }}
36
+ >
37
+ <Text style={{ color: theme.colors.foreground, fontWeight: "600" }}>
38
+ Behind its source branch
39
+ </Text>
40
+ <Text style={{ color: theme.colors.foregroundMuted }}>
41
+ Refresh all fast-forwards each clean source checkout to its upstream, then rechecks.
42
+ Worktree branches are not updated, so they can stay listed.
43
+ </Text>
44
+ <ScrollView style={{ maxHeight: 280 }} contentContainerStyle={{ gap: 12 }}>
45
+ {entries.map((entry) => (
46
+ <View key={entry.id} style={{ gap: 4 }}>
47
+ <Text style={{ color: theme.colors.foreground }}>{entry.directory}</Text>
48
+ <Text style={{ color: theme.colors.foregroundMuted }}>
49
+ {entry.behindBy} {entry.behindBy === 1 ? "commit" : "commits"} behind{" "}
50
+ {entry.remoteRef}
51
+ </Text>
52
+ </View>
53
+ ))}
54
+ {!entries.length && (
55
+ <Text style={{ color: theme.colors.foregroundMuted }}>
56
+ No workspaces behind their source branch.
57
+ </Text>
58
+ )}
59
+ </ScrollView>
60
+ {message && <Text style={{ color: theme.colors.foregroundMuted }}>{message}</Text>}
61
+ <Pressable
62
+ accessibilityRole="button"
63
+ disabled={pending || !entries.length}
64
+ onPress={() => {
65
+ void refreshAll();
66
+ }}
67
+ style={{
68
+ minHeight: 44,
69
+ justifyContent: "center",
70
+ paddingHorizontal: 12,
71
+ borderRadius: 8,
72
+ backgroundColor: theme.colors.surface2,
73
+ opacity: pending || !entries.length ? 0.5 : 1,
74
+ }}
75
+ >
76
+ <Text style={{ color: theme.colors.foreground }}>
77
+ {pending ? "Refreshing..." : "Refresh all"}
78
+ </Text>
79
+ </Pressable>
80
+ </View>
81
+ );
82
+ }
83
+ function Footer({ theme, openPopover }: PluginSidebarItemProps) {
84
+ const entries = useSyncExternalStore(summary.subscribe, summary.getSnapshot);
85
+ return (
86
+ <SidebarRow
87
+ icon="GitPullRequest"
88
+ label="Behind source branch"
89
+ onPress={() => openPopover(Popover)}
90
+ trailing={<Text style={{ color: theme.colors.foregroundMuted }}>{entries.length}</Text>}
91
+ />
92
+ );
93
+ }
94
+ return client.addSidebarFooterItem({
95
+ id: "workspace-freshness",
96
+ title: "Behind source branch",
97
+ Component: Footer,
98
+ });
99
+ }
@@ -0,0 +1,93 @@
1
+ export interface StaleWorkspace {
2
+ id: string;
3
+ projectRootPath: string;
4
+ directory: string;
5
+ remoteRef: string;
6
+ behindBy: number;
7
+ }
8
+
9
+ export interface WorkspaceSummary {
10
+ getSnapshot(): readonly StaleWorkspace[];
11
+ subscribe(listener: () => void): () => void;
12
+ set(entry: StaleWorkspace): void;
13
+ remove(id: string): void;
14
+ clear(): void;
15
+ refreshAll(): Promise<RefreshReport>;
16
+ }
17
+
18
+ export type RefreshOutcome = "updated" | "unchanged" | "dirty" | "unavailable";
19
+ export interface RefreshReport {
20
+ updated: number;
21
+ unchanged: number;
22
+ dirty: number;
23
+ unavailable: number;
24
+ failed: number;
25
+ }
26
+
27
+ export function describeRefresh(report: RefreshReport): string {
28
+ const parts: string[] = [];
29
+ if (report.updated) parts.push(`Fast-forwarded ${report.updated}.`);
30
+ if (report.dirty) parts.push(`${report.dirty} skipped: source checkout has uncommitted changes.`);
31
+ if (report.unavailable) parts.push(`${report.unavailable} could not be refreshed.`);
32
+ if (report.failed) parts.push(`${report.failed} failed.`);
33
+ if (report.unchanged) parts.push(`${report.unchanged} source already up to date.`);
34
+ return parts.join(" ");
35
+ }
36
+
37
+ export interface RefreshActions {
38
+ refreshRoot(projectRootPath: string): Promise<RefreshOutcome>;
39
+ recheck(workspaceId: string): Promise<void>;
40
+ }
41
+
42
+ export function createWorkspaceSummary({ refreshRoot, recheck }: RefreshActions): WorkspaceSummary {
43
+ let entries: readonly StaleWorkspace[] = [];
44
+ const listeners = new Set<() => void>();
45
+ function publish(next: readonly StaleWorkspace[]) {
46
+ entries = next;
47
+ for (const listener of listeners) listener();
48
+ }
49
+ return {
50
+ getSnapshot: () => entries,
51
+ subscribe(listener: () => void) {
52
+ listeners.add(listener);
53
+ return () => {
54
+ listeners.delete(listener);
55
+ };
56
+ },
57
+ set(entry: StaleWorkspace) {
58
+ publish([...entries.filter(({ id }) => id !== entry.id), entry]);
59
+ },
60
+ remove(id: string) {
61
+ if (entries.some((entry) => entry.id === id)) {
62
+ publish(entries.filter((entry) => entry.id !== id));
63
+ }
64
+ },
65
+ clear() {
66
+ publish([]);
67
+ },
68
+ async refreshAll() {
69
+ const byRoot = new Map<string, string[]>();
70
+ for (const { id, projectRootPath } of entries) {
71
+ byRoot.set(projectRootPath, [...(byRoot.get(projectRootPath) ?? []), id]);
72
+ }
73
+ const report: RefreshReport = {
74
+ updated: 0,
75
+ unchanged: 0,
76
+ dirty: 0,
77
+ unavailable: 0,
78
+ failed: 0,
79
+ };
80
+ await Promise.all(
81
+ [...byRoot].map(async ([projectRootPath, ids]) => {
82
+ try {
83
+ report[await refreshRoot(projectRootPath)]++;
84
+ } catch {
85
+ report.failed++;
86
+ }
87
+ await Promise.allSettled(ids.map(recheck));
88
+ }),
89
+ );
90
+ return report;
91
+ },
92
+ };
93
+ }
package/index.client.ts CHANGED
@@ -3,7 +3,9 @@ import type {
3
3
  PluginButtonRegistration,
4
4
  PluginClientContext,
5
5
  } from "@getpaseo/plugin/client";
6
- import { workspaceFreshness } from "./shared/workspace-freshness";
6
+ import { registerWorkspaceFooter } from "./client/workspace-footer";
7
+ import { createWorkspaceSummary } from "./client/workspace-summary";
8
+ import { refreshSourceBranch, workspaceFreshness } from "./shared/workspace-freshness";
7
9
 
8
10
  const REFRESH_INTERVAL_MS = 5 * 60_000;
9
11
 
@@ -26,6 +28,17 @@ export default function contribute(client: PluginClientContext) {
26
28
  let workspaceSubscription: ReleasableSubscription | undefined;
27
29
  let releaseSubscriptionPromise: Promise<void> | undefined;
28
30
  let initializationFailed = false;
31
+ const summary = createWorkspaceSummary({
32
+ async refreshRoot(projectRootPath) {
33
+ return (await client.rpc(refreshSourceBranch, { projectRootPath })).kind;
34
+ },
35
+ async recheck(workspaceId) {
36
+ // A check already in flight may have read the pre-fast-forward state.
37
+ await checks.get(workspaceId)?.catch(() => {});
38
+ await scheduleFreshnessCheck(workspaceId);
39
+ },
40
+ });
41
+ const removeFooter = registerWorkspaceFooter(client, summary);
29
42
 
30
43
  function releaseWorkspaceSubscription(): Promise<void> {
31
44
  if (releaseSubscriptionPromise) return releaseSubscriptionPromise;
@@ -39,17 +52,23 @@ export default function contribute(client: PluginClientContext) {
39
52
  function removeIndicator(workspaceId: string) {
40
53
  buttons.get(workspaceId)?.remove();
41
54
  buttons.delete(workspaceId);
55
+ summary.remove(workspaceId);
42
56
  }
43
57
 
44
- async function checkFreshness(workspaceId: string) {
45
- const location = workspaceLocations.get(workspaceId);
46
- if (!location) return;
58
+ async function projectRootFor(location: { projectId: string }) {
47
59
  let projectRootPath = projectRoots.get(location.projectId);
48
60
  if (!projectRootPath) {
49
61
  const { projects } = await client.paseo.projects.list();
50
62
  for (const project of projects) projectRoots.set(project.projectId, project.projectRootPath);
51
63
  projectRootPath = projectRoots.get(location.projectId);
52
64
  }
65
+ return projectRootPath;
66
+ }
67
+
68
+ async function checkFreshness(workspaceId: string) {
69
+ const location = workspaceLocations.get(workspaceId);
70
+ if (!location) return;
71
+ const projectRootPath = await projectRootFor(location);
53
72
  if (!projectRootPath) return;
54
73
 
55
74
  const freshness = await client.rpc(workspaceFreshness, {
@@ -62,9 +81,16 @@ export default function contribute(client: PluginClientContext) {
62
81
  return;
63
82
  }
64
83
 
84
+ summary.set({
85
+ id: workspaceId,
86
+ projectRootPath,
87
+ directory: location.workspaceDirectory,
88
+ remoteRef: freshness.remoteRef,
89
+ behindBy: freshness.behindBy,
90
+ });
65
91
  const commits = freshness.behindBy === 1 ? "commit" : "commits";
66
92
  const button: PluginButton = {
67
- title: `Worktree is ${freshness.behindBy} ${commits} behind ${freshness.remoteRef}. Select to recheck.`,
93
+ title: `Worktree is ${freshness.behindBy} ${commits} behind its source branch (${freshness.remoteRef}). Select to recheck.`,
68
94
  icon: "GitPullRequest",
69
95
  label: `Behind · ${freshness.behindBy}`,
70
96
  behavior: {
@@ -116,6 +142,7 @@ export default function contribute(client: PluginClientContext) {
116
142
  workspaceDirectory: workspace.workspaceDirectory,
117
143
  };
118
144
  workspaceLocations.set(workspace.id, location);
145
+ removeIndicator(workspace.id);
119
146
 
120
147
  const existing = checks.get(workspace.id);
121
148
  if (existing) {
@@ -176,6 +203,8 @@ export default function contribute(client: PluginClientContext) {
176
203
  stopped = true;
177
204
  clearInterval(interval);
178
205
  unsubscribe();
206
+ removeFooter?.();
207
+ summary.clear();
179
208
  for (const button of buttons.values()) button.remove();
180
209
  buttons.clear();
181
210
  workspaceLocations.clear();
package/index.server.ts CHANGED
@@ -3,8 +3,11 @@ import {
3
3
  createRepositoryRefreshCoordinator,
4
4
  refreshWorkspaceRequest,
5
5
  } from "./server/fresh-worktrees";
6
- import { inspectWorkspaceFreshness } from "./server/workspace-freshness";
7
- import { workspaceFreshness } from "./shared/workspace-freshness";
6
+ import { inspectWorkspaceFreshness, refreshSourceBranch } from "./server/workspace-freshness";
7
+ import {
8
+ refreshSourceBranch as refreshSourceBranchContract,
9
+ workspaceFreshness,
10
+ } from "./shared/workspace-freshness";
8
11
 
9
12
  export default function contribute(server: PluginServerContext) {
10
13
  const refreshRepository = createRepositoryRefreshCoordinator();
@@ -16,6 +19,13 @@ export default function contribute(server: PluginServerContext) {
16
19
  }),
17
20
  );
18
21
 
22
+ server.handle(refreshSourceBranchContract, ({ projectRootPath }) =>
23
+ refreshSourceBranch(projectRootPath, {
24
+ signal: new AbortController().signal,
25
+ refreshRepository,
26
+ }),
27
+ );
28
+
19
29
  server.before("workspace.create", async ({ request }, { paseo, signal }) => {
20
30
  return refreshWorkspaceRequest(request, {
21
31
  signal,
package/package.json CHANGED
@@ -28,10 +28,12 @@
28
28
  "index.client.ts",
29
29
  "index.server.ts",
30
30
  "server",
31
+ "client",
31
32
  "shared",
32
- "paseo-plugin.json"
33
+ "paseo-plugin.json",
34
+ "OVERVIEW.md"
33
35
  ],
34
- "version": "2.1.0",
36
+ "version": "2.2.0-next.227.1",
35
37
  "type": "module",
36
38
  "packageManager": "bun@1.4.2",
37
39
  "engines": {
@@ -41,15 +43,16 @@
41
43
  "check": "biome check .",
42
44
  "check:write": "biome check --write .",
43
45
  "test": "vitest run",
44
- "typecheck": "tsc --noEmit"
46
+ "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.client.json"
45
47
  },
46
48
  "devDependencies": {
47
49
  "@biomejs/biome": "^2.5.10",
48
- "@getpaseo/client": "0.10.1",
49
- "@getpaseo/plugin": "0.10.1",
50
+ "@getpaseo/client": "0.11.0-beta.5",
51
+ "@getpaseo/plugin": "0.11.0-beta.5",
50
52
  "@types/node": "^24.10.1",
51
53
  "@types/react": "^19.2.18",
52
54
  "react": "19.1.0",
55
+ "react-native": "0.81.5",
53
56
  "typescript": "^7.0.2",
54
57
  "vitest": "^5.0.0",
55
58
  "zod": "4.4.3"
package/paseo-plugin.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "id": "fresh-worktrees",
3
3
  "description": "Fast-forwards clean local base branches before Paseo creates branch-off worktrees.",
4
- "requirements": { "paseo": "^0.9.0 || ^0.10.0" }
4
+ "requirements": { "paseo": "^0.9.0 || ^0.10.0 || ^0.11.0" }
5
5
  }
@@ -1,5 +1,8 @@
1
1
  import type { RpcOutput } from "@getpaseo/plugin";
2
- import type { workspaceFreshness } from "../shared/workspace-freshness";
2
+ import type {
3
+ refreshSourceBranch as refreshSourceBranchContract,
4
+ workspaceFreshness,
5
+ } from "../shared/workspace-freshness";
3
6
  import type { GitRunner, RepositoryRefresh } from "./fresh-worktrees";
4
7
  import { executeGit } from "./fresh-worktrees";
5
8
 
@@ -74,3 +77,49 @@ export async function inspectWorkspaceFreshness(
74
77
  }
75
78
  return { kind: "behind", remoteRef, behindBy };
76
79
  }
80
+
81
+ export async function refreshSourceBranch(
82
+ projectRootPath: string,
83
+ dependencies: WorkspaceFreshnessDependencies,
84
+ ): Promise<RpcOutput<typeof refreshSourceBranchContract>> {
85
+ const runGit = dependencies.runGit ?? executeGit;
86
+ const { signal } = dependencies;
87
+ const branch = await optionalGit(
88
+ runGit,
89
+ projectRootPath,
90
+ ["symbolic-ref", "--quiet", "--short", "HEAD"],
91
+ signal,
92
+ );
93
+ if (!branch) return { kind: "unavailable" };
94
+ const remote = await optionalGit(
95
+ runGit,
96
+ projectRootPath,
97
+ ["config", "--get", `branch.${branch}.remote`],
98
+ signal,
99
+ );
100
+ const mergeRef = await optionalGit(
101
+ runGit,
102
+ projectRootPath,
103
+ ["config", "--get", `branch.${branch}.merge`],
104
+ signal,
105
+ );
106
+ if (!remote || remote === "." || !mergeRef?.startsWith("refs/heads/")) {
107
+ return { kind: "unavailable" };
108
+ }
109
+ const headBefore = await optionalGit(runGit, projectRootPath, ["rev-parse", "HEAD"], signal);
110
+ try {
111
+ const result = await dependencies.refreshRepository(
112
+ projectRootPath,
113
+ remote,
114
+ branch,
115
+ `${remote}/${mergeRef.slice("refs/heads/".length)}`,
116
+ signal,
117
+ );
118
+ if (result.kind !== "updated") return { kind: result.kind };
119
+ const headAfter = await optionalGit(runGit, projectRootPath, ["rev-parse", "HEAD"], signal);
120
+ return { kind: headAfter === headBefore ? "unchanged" : "updated" };
121
+ } catch (error) {
122
+ if (signal.aborted) throw error;
123
+ return { kind: "unavailable" };
124
+ }
125
+ }
@@ -17,3 +17,11 @@ export const workspaceFreshness = defineRpc({
17
17
  z.object({ kind: z.literal("unavailable") }),
18
18
  ]),
19
19
  });
20
+
21
+ export const refreshSourceBranch = defineRpc({
22
+ name: "fresh-worktrees.refresh-source-branch",
23
+ input: z.object({ projectRootPath: z.string().min(1) }),
24
+ output: z.object({
25
+ kind: z.enum(["updated", "unchanged", "dirty", "unavailable"]),
26
+ }),
27
+ });