dsh-codex-session-pin 0.0.0-stage → 1.0.0

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.
@@ -0,0 +1,18 @@
1
+ # dsh-codex-session-pin: one row for the Host half (state / toggle routes, plus
2
+ # the opt-in verification channel) and one for the browser half (Session header
3
+ # toggle + sidebar pin buttons, menu row and pinned-first ordering).
4
+ #
5
+ # The pin data itself is the official Workspace `pinnedSessionIds`, so this
6
+ # bundle never adds a second pin index.
7
+ #
8
+ # `probe` is intentionally absent: the diagnostic sink and the command channel
9
+ # stay disabled for a normal install. Enable it temporarily in your own profile
10
+ # patch layer when you need to verify the browser half from the Host side:
11
+ #
12
+ # - id: codex-session-pin
13
+ # config:
14
+ # probe: true
15
+ - insert:
16
+ - id: codex-session-pin
17
+ name: 'dsh-codex-session-pin'
18
+ config: {}
@@ -0,0 +1,71 @@
1
+ # Verifying the browser half
2
+
3
+ The Client half draws into the running page, so a Host-only check cannot tell you whether it works. Two things are checked: that the code loads and tears down cleanly, and that a real pin/unpin changes the page.
4
+
5
+ ## 1. Offline load and teardown
6
+
7
+ `test/harness.mjs` runs the Client half against a minimal DOM stub, calls `apply()`, then runs every disposer the framework would run on unload:
8
+
9
+ ```sh
10
+ node test/harness.mjs
11
+ ```
12
+
13
+ Expected:
14
+
15
+ ```json
16
+ { "apply": { "ok": true }, "teardown": "ok", "cleanups": 3 }
17
+ ```
18
+
19
+ A failure here means the module throws on load or leaks on unload; neither needs a browser to reproduce.
20
+
21
+ ## 2. End to end in the running page
22
+
23
+ The Host half has an opt-in verification channel, off by default. Enable it in your own profile patch layer (not in the installed package):
24
+
25
+ ```yaml
26
+ - id: codex-session-pin
27
+ config:
28
+ probe: true
29
+ ```
30
+
31
+ Restart the Harness and reload the page. The browser half then polls `GET /codex-session-pin/command` for a few minutes after load, and the Host consumes a command file exactly once and only while it is fresh.
32
+
33
+ Write a command (UTF-8 **without BOM** — a BOM makes the JSON parse fail):
34
+
35
+ ```json
36
+ { "action": "selftest", "at": 1795236247976, "sessionId": "session-…" }
37
+ ```
38
+
39
+ to `~/.dsh/codex-session-pin/command.json`. Available actions:
40
+
41
+ | Action | Result written to `diag.jsonl` |
42
+ | --- | --- |
43
+ | `census` | Selector counts on the page: rows, pin buttons, marks, header buttons, current pin set |
44
+ | `rows` | Per project: whether ordering is active, computed `display`, and the first rows with their `order` |
45
+ | `row` + `sessionId` | One row: flag, mark, button, project, index, computed `order` |
46
+ | `ids` | Full Session ids in visual order |
47
+ | `selftest` + `sessionId` | Pins through the same call the buttons use, reads the DOM back, unpins, reads back, restores the original set |
48
+ | `sync` | Forces one reconciliation pass |
49
+
50
+ `selftest` reports `ok: true` only when all of these hold: the Session is pinned, the mark is present, the row carries an `order`, the project is ordered, and after unpinning the mark, the `order` and the pin set are back to their starting state.
51
+
52
+ Read the results:
53
+
54
+ ```sh
55
+ # PowerShell
56
+ Get-Content "$env:USERPROFILE\.dsh\codex-session-pin\diag.jsonl" -Tail 10
57
+ ```
58
+
59
+ ## 3. Persistence
60
+
61
+ Pinning must survive a restart, so check the official file rather than the UI:
62
+
63
+ ```sh
64
+ node -e "const d=require(process.env.USERPROFILE+'/.dsh/storages/workspace.json');console.log(d.global.pinnedSessionIds)"
65
+ ```
66
+
67
+ The id must appear there while the Session is pinned, and be gone after unpinning. This plugin has no pin state of its own to check.
68
+
69
+ ## What these checks do not establish
70
+
71
+ They confirm behaviour, not appearance. The pin button's size, spacing and colour beside the host's own controls still need a look, in both light and dark themes.
package/icon.svg ADDED
@@ -0,0 +1,12 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Session pin">
2
+ <rect x="2" y="2" width="60" height="60" rx="14" fill="#1f6feb" />
3
+ <g fill="#ffffff">
4
+ <path d="M24 12h16a2.4 2.4 0 0 1 2.34 2.98l-1.83 9.5 6.7 6.7A2.4 2.4 0 0 1 48 35.9v4.2a2.4 2.4 0 0 1-2.4 2.4H18.4A2.4 2.4 0 0 1 16 40.1v-4.2c0-.64.25-1.25.7-1.7l6.7-6.7-1.83-9.5A2.4 2.4 0 0 1 24 12Z" />
5
+ </g>
6
+ <g stroke="#1f6feb" stroke-width="5" stroke-linecap="round">
7
+ <path d="M32 43v13" />
8
+ </g>
9
+ <g stroke="#ffffff" stroke-width="5" stroke-linecap="round">
10
+ <path d="M32 44v12" />
11
+ </g>
12
+ </svg>
package/index.js ADDED
@@ -0,0 +1,195 @@
1
+ // Host half of dsh-codex-session-pin.
2
+ //
3
+ // The feature itself lives in the official Workspace registry: `pinSession`,
4
+ // `unpinSession` and `pinnedSessionIds` are already implemented and persisted in
5
+ // `~/.dsh/storages/workspace.json`. This plugin never keeps a second pin index.
6
+ // The Host half only adds:
7
+ //
8
+ // 1. state / toggle routes, so a Client whose `workspaces` service predates the
9
+ // pin methods still works;
10
+ // 2. an opt-in (`config.probe`) diagnostic sink and command channel, used to
11
+ // verify the browser half from the Host side without page automation. Both
12
+ // are off by default and write nothing until enabled.
13
+ import { mkdir, appendFile, readFile, rename, stat, truncate, unlink } from 'node:fs/promises'
14
+ import { homedir } from 'node:os'
15
+ import { join } from 'node:path'
16
+ import z from '@deepseek-ai/schemastery'
17
+
18
+ const STATE_DIR = join(homedir(), '.dsh', 'codex-session-pin')
19
+ const DIAG_FILE = join(STATE_DIR, 'diag.jsonl')
20
+ const COMMAND_FILE = join(STATE_DIR, 'command.json')
21
+ const DIAG_MAX_BYTES = 512 * 1024
22
+ const COMMAND_MAX_AGE_MS = 60_000
23
+
24
+ export const inject = ['webServer']
25
+
26
+ // The Loader validates a row's config against this schema at activation.
27
+ export const Config = z.object({
28
+ probe: z.boolean(),
29
+ })
30
+
31
+ /** Read a JSON body with a hard size cap; malformed input yields `{}`. */
32
+ async function readJsonBody(req, limit = 8192) {
33
+ const chunks = []
34
+ let size = 0
35
+ for await (const chunk of req) {
36
+ size += chunk.length
37
+ if (size > limit) throw new Error('request body too large')
38
+ chunks.push(chunk)
39
+ }
40
+ if (!chunks.length) return {}
41
+ try {
42
+ return JSON.parse(Buffer.concat(chunks).toString('utf8'))
43
+ } catch {
44
+ return {}
45
+ }
46
+ }
47
+
48
+ function sendJson(res, status, payload) {
49
+ const body = JSON.stringify(payload)
50
+ res.writeHead(status, {
51
+ 'content-type': 'application/json; charset=utf-8',
52
+ 'cache-control': 'no-store',
53
+ 'content-length': Buffer.byteLength(body),
54
+ })
55
+ res.end(body)
56
+ }
57
+
58
+ /** Only accept the ids the registry itself would accept. */
59
+ function asSessionId(value) {
60
+ return typeof value === 'string' && value.length > 0 && value.length <= 200 ? value : undefined
61
+ }
62
+
63
+ export function apply(ctx, config) {
64
+ const probe = config !== undefined && config !== null && config.probe === true
65
+ const disposers = []
66
+ const registry = () => ctx.get('workspaceRegistry')
67
+
68
+ disposers.push(
69
+ ctx.webServer.register({
70
+ kind: 'exact',
71
+ path: '/codex-session-pin/state',
72
+ handler: async (_req, res) => {
73
+ const workspaces = registry()
74
+ sendJson(res, 200, {
75
+ ok: true,
76
+ pinnedSessionIds: workspaces === undefined ? [] : [...workspaces.pinnedSessionIds],
77
+ })
78
+ },
79
+ }),
80
+ )
81
+
82
+ // Fallback command path for a Client that cannot reach `ctx.workspaces`.
83
+ disposers.push(
84
+ ctx.webServer.register({
85
+ kind: 'exact',
86
+ path: '/codex-session-pin/toggle',
87
+ handler: async (req, res) => {
88
+ const workspaces = registry()
89
+ if (workspaces === undefined) {
90
+ sendJson(res, 503, { ok: false, error: 'workspace registry unavailable' })
91
+ return
92
+ }
93
+ let body
94
+ try {
95
+ body = await readJsonBody(req)
96
+ } catch (error) {
97
+ sendJson(res, 400, { ok: false, error: String(error && error.message) })
98
+ return
99
+ }
100
+ const sessionId = asSessionId(body.sessionId)
101
+ if (sessionId === undefined) {
102
+ sendJson(res, 400, { ok: false, error: 'sessionId required' })
103
+ return
104
+ }
105
+ try {
106
+ if (body.pinned === true) await workspaces.pinSession(sessionId)
107
+ else await workspaces.unpinSession(sessionId)
108
+ } catch (error) {
109
+ sendJson(res, 409, { ok: false, error: String(error && error.message ? error.message : error) })
110
+ return
111
+ }
112
+ sendJson(res, 200, { ok: true, pinnedSessionIds: [...workspaces.pinnedSessionIds] })
113
+ },
114
+ }),
115
+ )
116
+
117
+ // Verification channel. The route always exists so the browser half can tell
118
+ // "disabled" (204) from "missing" (the app shell's HTML); with `probe` off it
119
+ // answers 204 and never touches the filesystem.
120
+ disposers.push(
121
+ ctx.webServer.register({
122
+ kind: 'exact',
123
+ path: '/codex-session-pin/diag',
124
+ handler: async (req, res) => {
125
+ if (!probe) {
126
+ sendJson(res, 204, { ok: true, action: 'disabled' })
127
+ return
128
+ }
129
+ let body
130
+ try {
131
+ body = await readJsonBody(req, 128 * 1024)
132
+ } catch (error) {
133
+ sendJson(res, 400, { ok: false, error: String(error && error.message) })
134
+ return
135
+ }
136
+ const line = `${JSON.stringify({ at: new Date().toISOString(), ...body })}\n`
137
+ try {
138
+ await mkdir(STATE_DIR, { recursive: true })
139
+ const info = await stat(DIAG_FILE).catch(() => undefined)
140
+ if (info !== undefined && info.size > DIAG_MAX_BYTES) await truncate(DIAG_FILE, 0)
141
+ await appendFile(DIAG_FILE, line, 'utf8')
142
+ } catch {
143
+ // Diagnostics are best-effort: a failed write must never fail the action.
144
+ }
145
+ sendJson(res, 200, { ok: true })
146
+ },
147
+ }),
148
+ )
149
+
150
+ // The command file is consumed exactly once (renamed away before reading) and
151
+ // only while fresh, so a stale file can never drive the page later.
152
+ disposers.push(
153
+ ctx.webServer.register({
154
+ kind: 'exact',
155
+ path: '/codex-session-pin/command',
156
+ handler: async (_req, res) => {
157
+ if (!probe) {
158
+ sendJson(res, 204, { ok: true, action: 'disabled' })
159
+ return
160
+ }
161
+ const claimed = `${COMMAND_FILE}.${process.pid}.${Date.now()}.claimed`
162
+ try {
163
+ await rename(COMMAND_FILE, claimed)
164
+ } catch {
165
+ sendJson(res, 200, { ok: true, action: 'none' })
166
+ return
167
+ }
168
+ try {
169
+ const raw = await readFile(claimed, 'utf8')
170
+ const command = JSON.parse(raw)
171
+ const age = Date.now() - Number(command.at ?? 0)
172
+ if (!Number.isFinite(age) || age < 0 || age > COMMAND_MAX_AGE_MS) {
173
+ sendJson(res, 200, { ok: true, action: 'expired' })
174
+ return
175
+ }
176
+ sendJson(res, 200, { ok: true, ...command })
177
+ } catch (error) {
178
+ sendJson(res, 200, { ok: false, action: 'invalid', error: String(error && error.message) })
179
+ } finally {
180
+ await unlink(claimed).catch(() => {})
181
+ }
182
+ },
183
+ }),
184
+ )
185
+
186
+ ctx.effect(() => () => {
187
+ for (const dispose of disposers.reverse()) {
188
+ try {
189
+ dispose()
190
+ } catch {
191
+ // A route already torn down by its owner needs no further cleanup.
192
+ }
193
+ }
194
+ }, 'dsh-codex-session-pin: routes')
195
+ }
package/locale/en.json ADDED
@@ -0,0 +1,6 @@
1
+ {
2
+ "meta": {
3
+ "title": "Codex Session Pin",
4
+ "description": "Pin or unpin any Session from its header or from the sidebar session list; pinned Sessions lead their project. Still works when a third-party sidebar such as @michengai/dsh-codex-ui replaces the shipped one. Pin state is the official workspace pinnedSessionIds."
5
+ }
6
+ }
package/locale/zh.json ADDED
@@ -0,0 +1,6 @@
1
+ {
2
+ "meta": {
3
+ "title": "Codex 会话置顶",
4
+ "description": "在会话标题栏或侧栏会话列表里置顶 / 取消置顶;置顶的会话排在所属项目最前面。第三方侧栏(如 @michengai/dsh-codex-ui)接管侧栏时同样可用。置顶数据就是官方工作区的 pinnedSessionIds,不另存一份。"
5
+ }
6
+ }
package/package.json CHANGED
@@ -1,6 +1,65 @@
1
1
  {
2
2
  "name": "dsh-codex-session-pin",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0",
4
+ "description": "DeepSeek Harness plugin: adds pin/unpin to every Session and orders pinned Sessions first inside their project. Pin state is the official workspace pinnedSessionIds, so it survives restarts and never duplicates another plugin's index. Works even when a third-party sidebar (such as @michengai/dsh-codex-ui) replaces the shipped one.",
5
+ "keywords": [
6
+ "deepseek-harness",
7
+ "dsh-plugin",
8
+ "dsh",
9
+ "session",
10
+ "pin",
11
+ "pinned",
12
+ "sidebar",
13
+ "codex-ui"
14
+ ],
15
+ "license": "MIT",
16
+ "author": "yhm138",
17
+ "type": "module",
18
+ "main": "index.js",
19
+ "exports": {
20
+ ".": "./index.js",
21
+ "./client": "./client.js",
22
+ "./locale/*.json": "./locale/*.json",
23
+ "./icon": "./icon.svg",
24
+ "./package.json": "./package.json"
25
+ },
26
+ "files": [
27
+ "index.js",
28
+ "client.js",
29
+ "cordis.patch.yml",
30
+ "locale/*.json",
31
+ "icon.svg",
32
+ "README.md",
33
+ "README.zh.md",
34
+ "docs/*.md",
35
+ "LICENSE"
36
+ ],
37
+ "repository": {
38
+ "type": "git",
39
+ "url": "git+https://github.com/yhm138/dsh-codex-session-pin.git"
40
+ },
41
+ "homepage": "https://github.com/yhm138/dsh-codex-session-pin#readme",
42
+ "bugs": {
43
+ "url": "https://github.com/yhm138/dsh-codex-session-pin/issues"
44
+ },
45
+ "engines": {
46
+ "dsh": ">=0.2.1-rc.2 <0.3.0-0"
47
+ },
48
+ "dsh": {
49
+ "bundle": {
50
+ "patch": "./cordis.patch.yml"
51
+ },
52
+ "client": {
53
+ "platform": "web",
54
+ "immediately": true,
55
+ "inject": [
56
+ "@deepseek-ai/dsh-api-workspace-controller",
57
+ "@deepseek-ai/dsh-client-locale",
58
+ "@deepseek-ai/dsh-client-ui-workspace"
59
+ ]
60
+ }
61
+ },
62
+ "peerDependencies": {
63
+ "@deepseek-ai/schemastery": "^3.18.4"
64
+ }
65
+ }