dsh-project-mcp 0.2.0 → 0.3.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/README.md CHANGED
@@ -48,6 +48,7 @@ other tool's file) is one config line away, never an implicit second source.
48
48
  - [Resource behaviour](#resource-behaviour)
49
49
  - [Runtimes](#runtimes)
50
50
  - [Verifying](#verifying)
51
+ - [Releasing](#releasing)
51
52
  - [Limitations](#limitations)
52
53
  - [Dogfooding](#dogfooding)
53
54
 
@@ -58,9 +59,9 @@ Implementation notes: [how it works](#how-it-works) · [bundle format](#bundle-f
58
59
  ```bash
59
60
  pnpm install && pnpm check # typecheck + build + tests under the coverage gate + resource audit
60
61
  pnpm coverage # the same suite with the coverage report only
61
- pnpm pack # -> dsh-project-mcp-0.2.0.tgz
62
- mv dsh-project-mcp-0.2.0.tgz ~/.dsh/packages/
63
- dsh plugin --profile web add file:$HOME/.dsh/packages/dsh-project-mcp-0.2.0.tgz
62
+ pnpm pack # -> dsh-project-mcp-<version>.tgz (builds first, via prepack)
63
+ mv dsh-project-mcp-<version>.tgz ~/.dsh/packages/
64
+ dsh plugin --profile web add file:$HOME/.dsh/packages/dsh-project-mcp-<version>.tgz
64
65
  ```
65
66
 
66
67
  `pnpm check` runs the suite through `--coverage`, and `vitest.config.ts` gates all
@@ -565,9 +566,11 @@ a clock:
565
566
 
566
567
  ## Sidebar panel
567
568
 
568
- The package has a browser half (`./client`) that registers a tab with
569
- [`dsh-better-sidebar`](https://github.com/omdsh-dev/DSH-better-sidebar). A tab
570
- belongs to one conversation, so it shows **only that session's project** — never
569
+ The package has a browser half (`./client`) that registers a tab type with DSH's
570
+ **own right sidebar** — `ctx.sidebarRightTabs` for the type, the keyed
571
+ `sidebar.right.pane.tab` seat for the body (see `src/client/sidebar-tab.ts`) —
572
+ which the sidebar's guide page lists. A tab belongs to one conversation, so it
573
+ shows **only that session's project** — never
571
574
  another one: the servers it declares and their merged live status, then the same
572
575
  project broken down **per session** — which session holds a mount, which has not
573
576
  turned yet, which one is this tab's — with `Sync` / `Release` actions. `Release`
@@ -590,12 +593,14 @@ that has nothing to list names what is missing instead of showing an empty box
590
593
  no session, no project marker above the session cwd, no declared server, or
591
594
  nothing that needs attention.
592
595
 
593
- The same tab declares its own settings panel in the side card settings popup, and
594
- that panel is where the whole picture lives: **every** project with a live
595
- session, not just this tab's, plus the panel's poll interval, persisted in the
596
- sidebar's `pluginSettings`.
596
+ The tab chip's actions menu carries one row of this plugin's own — `Panel
597
+ settings…` — and the popup it opens is where the whole picture lives: **every**
598
+ project with a live session, not just this tab's, plus the panel's poll interval,
599
+ persisted in browser-local storage (`dsh-project-mcp:servers:refreshMs`). The row
600
+ dismisses the menu and the popup renders in DSH's `shell.overlay` floating layer,
601
+ so it outlives the menu it was opened from.
597
602
 
598
- `ctx.betterSidebar` exists only in the browser half, so the panel does not call
603
+ The browser half runs in its own process, so the panel does not call
599
604
  the runtime in process: the host half registers HTTP routes on the DSH web server
600
605
  (`/project-mcp/snapshot|events|logs|sync|retry|release|save|pin|policy`, see
601
606
  `src/ui.ts`) and the panel fetches them. Responses are `{ ok: true, value }` or
@@ -636,14 +641,16 @@ what the `change` frames of `GET /project-mcp/events` say, and the baseline
636
641
  servers starting at once.
637
642
 
638
643
  ```
639
- browser: ctx.inject(['betterSidebar'], s => s.betterSidebar.registerTab({ … }))
644
+ browser: ctx.inject(['slots', 'sidebarRightTabs'], s => s.sidebarRightTabs.register({ id, kind, … }))
645
+ s.slots.register({ name: 'sidebar.right.pane.tab', key: id }, Panel)
640
646
  fetch('/project-mcp/snapshot')
641
647
  host: ctx.webServer.register({ kind: 'prefix', path: '/project-mcp', … })
642
648
  ```
643
649
 
644
- Requirements: `react` in the composition. If the host already provides a
645
- `betterSidebar` service, the sidebar tab is registered; otherwise the host half
646
- keeps mounting servers. Client changes hot-reload (hard-refresh the browser);
650
+ Requirements: `react` in the composition. If the composition has DSH's right
651
+ sidebar (`slots` + `sidebarRightTabs`), the tab type is registered; otherwise the
652
+ host half keeps mounting servers and the settings page, the configuration card and
653
+ the toasts still work. Client changes hot-reload (hard-refresh the browser);
647
654
  host changes need a `dsh web` restart.
648
655
 
649
656
  ### Settings page
@@ -688,13 +695,13 @@ ctx.inject(['slots', 'locale'], (scope) => { // optional client service
688
695
  })
689
696
  ```
690
697
 
691
- The module-level `inject` is empty, and neither `betterSidebar` nor `locale` is
692
- listed there: an entry that waits on an optional service stays **pending**, and
693
- DSH's web boot audit refuses to start while any entry is pending. Both are read
694
- without gating the entry instead — the sidebar tab parks behind
695
- `ctx.inject(['betterSidebar'], …)` (so it registers whenever that service exists,
696
- in a composition that has one), and the tab's translate seat comes from
697
- `ctx.get('locale')`. A property read of a service the fiber did not declare
698
+ The module-level `inject` is empty, and neither `slots`, nor `sidebarRightTabs`,
699
+ nor `locale` is listed there: an entry that waits on an optional service stays
700
+ **pending**, and DSH's web boot audit refuses to start while any entry is pending.
701
+ All three are read without gating the entry instead — the tab type and its two
702
+ seats park behind `ctx.inject(['slots', 'sidebarRightTabs'], …)` (so they register
703
+ whenever the composition has a right sidebar), and the tab's translate seat comes
704
+ from `ctx.get('locale')`. A property read of a service the fiber did not declare
698
705
  throws `cannot get property "…" without inject` and fails the entry, which is
699
706
  what took the whole GUI down in 0.1.9. The host half and every slot-based surface
700
707
  continue without either service. The bundle requests
@@ -789,7 +796,7 @@ check passes on both:
789
796
  | 600 unrelated writes (`node_modules`, `dist`, `.git`) | 3 watch events → 1 pass, 0 catalog scans, 0 remounts |
790
797
  | mount → dispose | MCP child process exits, its pid file is removed |
791
798
  | server that cannot start | one detailed `error` row, no respawn storm, no leaked child |
792
- | 10 × session create/dispose | 0 surviving children, file descriptors flat, heap +0.9 MB |
799
+ | 10 × session create/dispose | 0 surviving children, file descriptors flat, heap +0.3 MB (settled: read after a collection; a runtime exposing no collector reads raw under the same 8 MB budget) |
793
800
  | two sessions, one project | 1 mount attempt, 1 child, 1 creation line — the second session's turn reuses it |
794
801
  | a release while another session holds | child stays up for the remaining holder, goes down with the last one |
795
802
  | teardown | watchers closed, descriptors released, 0 passes and ~1 ms CPU afterwards |
@@ -866,6 +873,44 @@ Manual acceptance on a running GUI:
866
873
  4. Editing the file adds/removes tools after the debounce (~300 ms), without a
867
874
  restart and without disturbing the profile-level servers.
868
875
 
876
+ ## Releasing
877
+
878
+ `package.json`'s `version` is the published version; a `v<version>` tag only selects
879
+ the commit, and the two are checked against each other before every publish.
880
+
881
+ Every push to `main` releases, when the commits since the last tag ask for one
882
+ (Conventional Commits: `feat` → minor, `fix`/`perf`/`revert` → patch, `!` or a
883
+ `BREAKING CHANGE:` paragraph → major; `docs`, `chore`, `ci`, `test` and `refactor`
884
+ release nothing on their own). `.github/workflows/release.yml` runs the full
885
+ `pnpm check` gate, decides the version with `scripts/next-version.mjs`, writes that one
886
+ line of `package.json`, commits it as `release: dsh-project-mcp <version>`, tags it,
887
+ creates the GitHub Release, and calls `npm-publish.yml` to publish the tag to npm —
888
+ called rather than triggered, because a Release created with the workflow's own
889
+ `GITHUB_TOKEN` starts no other run. The decision reads both `package.json` and the
890
+ highest `v*` tag and takes the newer of the two, so a tag that outran its manifest
891
+ cannot publish the wrong number twice; before tagging, the job refuses to reuse a tag
892
+ or an already-published version rather than failing later inside `npm publish`.
893
+
894
+ To see what the next push would release:
895
+
896
+ ```bash
897
+ node scripts/next-version.mjs # the decision, as JSON (nothing is written)
898
+ node scripts/next-version.mjs --bump patch # force a level over a docs-only range
899
+ ```
900
+
901
+ The `Release` workflow also has a manual entry point (*Run workflow*: `bump`, `dry_run`)
902
+ for re-driving a run that died between its tag and npm. To publish by hand, create a
903
+ GitHub Release for a tag whose `package.json` already carries that version; the publish
904
+ job fails loudly when the two disagree. `pnpm pack` builds by itself (`prepack`), so a
905
+ hand-made tarball cannot ship the package without its `lib/` — the shape the published
906
+ `0.2.0` had.
907
+
908
+ The publish credential is an **OIDC token**, not a repository secret: the job asks for
909
+ `id-token: write` and exchanges it with npm's trusted publishing (registered for this
910
+ repository and `npm-publish.yml` on npmjs.com), so nothing has to be rotated and a
911
+ stale `NODE_AUTH_TOKEN` must not be set — it would take precedence over the exchange.
912
+ That job pins Node 24, because the exchange needs npm ≥ 11.5.1.
913
+
869
914
  ## Limitations
870
915
 
871
916
  - Per-project cost: one MCP instance per project per server, shared by every
@@ -973,8 +1018,9 @@ src/usage.ts durable per-project tool-call counters
973
1018
  src/policy.ts durable per-project tool policy: mode (disclosure/direct/off), pins
974
1019
  src/guidance.ts project-MCP guidance section: deterministic text + wiring
975
1020
  src/types.ts snapshot/row vocabulary
976
- src/client/ browser half: sidebar tab, side card settings, native
977
- Settings page (`settings.section`), shared view helpers
1021
+ src/client/ browser half: the right-sidebar tab and its settings popup,
1022
+ the native Settings page (`settings.section`), shared view
1023
+ helpers
978
1024
  tests/ unit tests (parse, discovery, runtime, guidance, both views),
979
1025
  plus a load-path guard for the wrapped client bundle
980
1026
  scripts/ MCP fixture server, live smoke test, resource audit,
@@ -0,0 +1,77 @@
1
+ import { ReactNode } from "react";
2
+ import { Context } from "@deepseek-ai/cordis";
3
+ //#region src/client/view.d.ts
4
+ /** Translate one key, with optional `{name}` template params (the DSH seat). */
5
+ type Translate = (key: string, params?: Record<string, unknown>) => string;
6
+ //#endregion
7
+ //#region src/client/sidebar-tab.d.ts
8
+ /** The tab body's props: the framework's own, plus the seats this module binds. */
9
+ interface SidebarTabBodyProps {
10
+ /** The session the tab belongs to — the panel shows that session's project only. */
11
+ sessionId: string | undefined;
12
+ /** Whether the tab is on screen; an off-screen panel stops polling. */
13
+ visible: boolean;
14
+ /** The poll interval, followed live so a change in the settings popup reaches the panel. */
15
+ refreshMs: number;
16
+ t: Translate;
17
+ hostT: Translate;
18
+ }
19
+ /** The settings popup's content, with the seats it needs. */
20
+ interface SidebarSettingsProps {
21
+ refreshMs: number;
22
+ /** Write a new interval; the popup's own row is the only writer. */
23
+ onRefreshMs: (value: number) => void;
24
+ onClose: () => void;
25
+ t: Translate;
26
+ hostT: Translate;
27
+ }
28
+ //#endregion
29
+ //#region src/client/index.d.ts
30
+ /** Plugin name: matches the package name and the host half. */
31
+ export declare const name = "dsh-project-mcp";
32
+ /**
33
+ * Register the surfaces, each behind the services it actually needs.
34
+ *
35
+ * No module-level dependency is declared, because every one of them is optional:
36
+ * a module-level `inject` would leave this entry **pending** for good in a
37
+ * composition without the right sidebar, and DSH's web boot audit refuses to
38
+ * start while an entry is pending. `ctx.inject(name, …)` waits for the same
39
+ * services without gating the entry, so a composition without the sidebar keeps
40
+ * the native Settings page, the config card and the toast stack.
41
+ *
42
+ * A service this fiber did not declare must never be read as a property: Cordis
43
+ * throws `cannot get property "…" without inject`, and that throw fails the
44
+ * entry, which takes the whole web client boot down. Optional reads go through
45
+ * {@link Context.get}.
46
+ */
47
+ export declare const inject: string[];
48
+ /**
49
+ * Register the browser half's surfaces. Every registration returns a disposer and
50
+ * Cordis runs them on fiber disposal, which is what keeps HMR and plugin
51
+ * disabling free of "already registered" failures.
52
+ * @param ctx - client root context.
53
+ */
54
+ export declare function apply(ctx: Context): void;
55
+ /**
56
+ * The sidebar panel.
57
+ *
58
+ * `./sidebar-tab.ts` already bound the two translate seats — the UI namespace and
59
+ * the host-message one — before calling this, so the adapter has nothing left to
60
+ * do but name the component and let React render it as an element rather than as
61
+ * a bare call.
62
+ * @param props - the body's props, seats included.
63
+ * @returns the panel element.
64
+ */
65
+ export declare function LocalizedPanel(props: SidebarTabBodyProps): ReactNode;
66
+ /**
67
+ * The settings popup's content, with the same two seats.
68
+ *
69
+ * The popup is an entry of the frame-wide floating layer, so its chrome has to
70
+ * repaint on a language switch exactly like the tab's: the seats are bound per
71
+ * render by `./sidebar-tab.ts`, and this adapter only names the component.
72
+ * @param props - the popup's props, seats included.
73
+ * @returns the settings panel element.
74
+ */
75
+ export declare function LocalizedSettings(props: SidebarSettingsProps): ReactNode;
76
+ //#endregion
77
+ //# sourceMappingURL=client.d.ts.map