@cowwo/dsh-lookout 0.1.2 → 0.2.0

package/lib/icon/index.js

@@ -41,6 +41,13 @@ import {
 	pruneSeen
 } from './unread.js'
 import { normalizeRunningConfig } from './running.js'
+import {
+	emptyWorkspacePrefs,
+	normalizeWorkspacePrefs,
+	readWorkspacePrefs,
+	workspacePrefsFilePath,
+	writeWorkspacePrefs
+} from './workspace-prefs.js'
 
 const MAX_BYTES = 10 * 1024 * 1024 // 10 MB
 // Normalized mime -> safe extension. CUR (mouse cursor) is accepted as ICO.
@@ -344,6 +351,10 @@ export class FaviconCustomService extends TypertRemoteService {
 		// list already carries each session's `running`), so nothing about it is
 		// stored here — only whether to show the projection of it.
 		this.runningPath = join(this.storageDir, 'running.json')
+		// Per-workspace preferences (tag / color / pinned / hidden). Same folder as
+		// the icon library, but its own file + endpoint pair: a corrupt preference
+		// document must never take the favicon or the badge rules down with it.
+		this.workspacePrefsPath = workspacePrefsFilePath(this.storageDir)
 		// { activeId, icons: { [id]: { id, mime, ext, name, size, savedAt, rev, pwa, logo } } }
 		this.library = { activeId: null, icons: {} }
 		// The active icon's loaded state: { rev, mime, ext, name, size, savedAt, pwa, logo, bytes } | null
@@ -355,6 +366,9 @@ export class FaviconCustomService extends TypertRemoteService {
 		// Running-mark switch: whether the yellow projection of the official
 		// `running` fact is drawn. See lib/running.js.
 		this.running = normalizeRunningConfig(null)
+		// Workspace preferences: { version: 1, workspaces: { [workspaceId]: { tag, color, pinned, hidden, pinAnchor } } }.
+		// The client sends the whole document on every set (full replacement).
+		this.workspacePrefs = emptyWorkspacePrefs()
 		// Host-side watermark: { [sessionId]: endAt } — see lib/unread.js.
 		this.seen = {}
 		// Platform PWA manifest (raw + parsed), read once at startup.
@@ -362,6 +376,7 @@ export class FaviconCustomService extends TypertRemoteService {
 		this._load()
 		this._loadUnread()
 		this._loadRunning()
+		this._loadWorkspacePrefs()
 		this._loadUnreadSeen()
 		// "How did this session's last turn end" as an official session
 		// projection. Optional registration on purpose: this plugin is a display
@@ -477,6 +492,16 @@ export class FaviconCustomService extends TypertRemoteService {
 		return writeFile(this.runningPath, JSON.stringify(this.running, null, 2))
 	}
 
+	/** Load workspace preferences (missing or corrupt file = empty document). */
+	_loadWorkspacePrefs() {
+		this.workspacePrefs = readWorkspacePrefs(this.workspacePrefsPath)
+	}
+
+	/** Persist workspace preferences (best effort; atomic tmp+rename in the helper). */
+	_saveWorkspacePrefs() {
+		return writeWorkspacePrefs(this.workspacePrefsPath, this.workspacePrefs)
+	}
+
 	/**
 	 * Load the host-side watermark.
 	 *
@@ -585,6 +610,35 @@ export class FaviconCustomService extends TypertRemoteService {
 		return { ...this.running }
 	}
 
+	/**
+	 * typert endpoint: read the per-workspace preferences (tag / color / pinned /
+	 * hidden). A copy, not the live object: a caller must not be able to mutate the
+	 * Host's state by editing the response.
+	 * @returns `{ version: 1, workspaces: { [workspaceId]: { tag, color, pinned, hidden, pinAnchor } } }`.
+	 */
+	async getWorkspacePrefs() {
+		return normalizeWorkspacePrefs(this.workspacePrefs)
+	}
+
+	/**
+	 * typert endpoint: replace the whole workspace-preferences document.
+	 *
+	 * Full replacement, not a patch: the client owns the document and sends it
+	 * whole, so a workspace the client dropped disappears here too. Dirty input is
+	 * normalized (invalid ids/values degrade to defaults) and never throws; the
+	 * write is best effort, like the other advisory preference files.
+	 * @param request - `{ version: 1, workspaces: { ... } }`.
+	 * @returns the stored (normalized) document.
+	 */
+	async setWorkspacePrefs(request) {
+		if (request === null || typeof request !== 'object' || Array.isArray(request)) {
+			throw new Error('缺少 workspaces 参数')
+		}
+		this.workspacePrefs = normalizeWorkspacePrefs(request)
+		await this._saveWorkspacePrefs().catch(() => {}) // preference file is advisory
+		return normalizeWorkspacePrefs(this.workspacePrefs)
+	}
+
 	/**
 	 * typert endpoint: merge this browser's "seen" watermarks into the Host's copy.
 	 *

package/lib/icon/workspace-prefs.js

@@ -0,0 +1,129 @@
+/**
+ * dsh-lookout · 工作区偏好(标签/隐藏/置顶)的宿主半
+ *
+ * 只干两件事:
+ *   1. 把任意脏输入夹成一份**完整、可安全落盘**的偏好文档;
+ *   2. 在 $DSH_HOME/custom-favicon/workspace-prefs.json 上读/写这份文档。
+ *
+ * 设计约束(与 unread.js 的规则开关同一条思路):
+ *   * normalize 永不抛错 —— 文件被手改坏、客户端版本对不上,都只降级成默认值,
+ *     绝不因为一条偏好把图标/红点这些主功能一起带崩;
+ *   * 写盘 best effort —— 调用方(index.js)吞掉落盘错误,内存里的偏好照常生效;
+ *   * 文档整份覆盖 —— 客户端每次提交完整文档,宿主不保留任何"上一版残留"。
+ *
+ * 文档形状(version 固定为 1):
+ *   { "version": 1, "workspaces": { "<workspaceId>": { "tag", "color",
+ *     "pinned", "hidden", "pinAnchor" } } }
+ */
+import { readFileSync } from 'node:fs'
+import { mkdir, rename, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+/** 文档版本。未来改结构时靠它整份丢弃旧文档,而不是猜字段。 */
+export const WORKSPACE_PREFS_VERSION = 1
+
+/** 与 library.json / unread.json 同目录:custom-favicon/。 */
+export const WORKSPACE_PREFS_FILE = 'workspace-prefs.json'
+
+/** 标签颜色白名单。非法颜色一律落到 gray,不猜"最接近的颜色"。 */
+export const WORKSPACE_COLORS = ['red', 'orange', 'yellow', 'green', 'cyan', 'blue', 'purple', 'gray']
+
+/** 非法/缺省颜色。 */
+export const WORKSPACE_COLOR_DEFAULT = 'gray'
+
+/** 标签最多 6 个 Unicode 字符(不是 UTF-16 单元:emoji 也只算一个)。 */
+export const WORKSPACE_TAG_MAX = 6
+
+/** 工作区 id 长度上限(与客户端约定一致)。 */
+export const WORKSPACE_ID_MAX = 200
+
+/** 危险对象键:绝不能通过 JSON 里的 `__proto__` 改到原型。 */
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
+/** 空文档。文件缺失/损坏/版本未知时都用它。 */
+export function emptyWorkspacePrefs() {
+	return { version: WORKSPACE_PREFS_VERSION, workspaces: {} }
+}
+
+/** 只留可打印字符:去掉控制字符(Cc),再 trim。 */
+export function normalizeTag(input) {
+	if (typeof input !== 'string') return ''
+	const cleaned = input.replace(/\p{Cc}/gu, '').trim()
+	return [...cleaned].slice(0, WORKSPACE_TAG_MAX).join('')
+}
+
+/** 颜色白名单,非法回落 gray。 */
+export function normalizeColor(input) {
+	return WORKSPACE_COLORS.includes(input) ? input : WORKSPACE_COLOR_DEFAULT
+}
+
+/**
+ * 夹一个工作区条目。未知字段丢弃,坏类型一律降级:
+ * tag 非法 → '';color 非法 → 'gray';pinned/hidden 非 true → false;
+ * pinAnchor 非 string → null。
+ */
+export function normalizeWorkspaceEntry(input) {
+	const source = input !== null && typeof input === 'object' && !Array.isArray(input) ? input : {}
+	return {
+		tag: normalizeTag(source.tag),
+		color: normalizeColor(source.color),
+		// 只认真正的 true:字符串 'true' / 1 都不能把工作区置顶或藏起来。
+		pinned: source.pinned === true,
+		hidden: source.hidden === true,
+		pinAnchor: typeof source.pinAnchor === 'string' ? source.pinAnchor : null
+	}
+}
+
+/** 工作区 id 是否可用:非空 string,长度不超过 200。 */
+export function isValidWorkspaceId(input) {
+	return typeof input === 'string' && input.length > 0 && input.length <= WORKSPACE_ID_MAX
+}
+
+/**
+ * 把任意输入夹成完整文档 —— 永不抛错。
+ * @param {unknown} input - 可能是 null、数组、字符串、缺字段、字段类型全错的对象,或一份旧文档
+ * @returns {{ version: 1, workspaces: Record<string, { tag: string, color: string, pinned: boolean, hidden: boolean, pinAnchor: string | null }> }}
+ */
+export function normalizeWorkspacePrefs(input) {
+	const document = emptyWorkspacePrefs()
+	if (input === null || typeof input !== 'object' || Array.isArray(input)) return document
+	const workspaces = input.workspaces
+	if (workspaces === null || typeof workspaces !== 'object' || Array.isArray(workspaces)) return document
+	for (const [workspaceId, entry] of Object.entries(workspaces)) {
+		if (!isValidWorkspaceId(workspaceId) || UNSAFE_KEYS.has(workspaceId)) continue
+		document.workspaces[workspaceId] = normalizeWorkspaceEntry(entry)
+	}
+	return document
+}
+
+/** 偏好文件路径(与图标库同目录)。 */
+export function workspacePrefsFilePath(storageDir) {
+	return join(storageDir, WORKSPACE_PREFS_FILE)
+}
+
+/**
+ * 读偏好文档。文件缺失、空文件、坏 JSON、版本/结构不对 —— 一律返回空文档,绝不抛错。
+ * 同步读:与 index.js 其余"启动时读一次"的文件保持一致,调用方不必等 Promise。
+ */
+export function readWorkspacePrefs(filePath) {
+	try {
+		const raw = readFileSync(filePath, 'utf8').replace(/^\uFEFF/, '')
+		return normalizeWorkspacePrefs(JSON.parse(raw))
+	} catch {
+		return emptyWorkspacePrefs()
+	}
+}
+
+/**
+ * 原子写偏好文档:先写 `<file>.tmp`,再 rename 覆盖正式文件,
+ * 这样进程在写一半时被杀也不会留下半截 JSON(照 unread-seen.json 的写法)。
+ * 失败会 throw,由调用方决定是否吞掉 —— 偏好文件是 advisory(尽力而为)。
+ */
+export async function writeWorkspacePrefs(filePath, prefs) {
+	const document = normalizeWorkspacePrefs(prefs)
+	await mkdir(dirname(filePath), { recursive: true })
+	const tmp = `${filePath}.tmp`
+	await writeFile(tmp, JSON.stringify(document, null, 2))
+	await rename(tmp, filePath)
+	return document
+}

package/lib/typert.host.js

@@ -116,6 +116,36 @@ const setRunningRuleRequestSchema = z.object({
 	headerRing: z.boolean().optional()
 })
 
+/**
+ * 工作区偏好(标签 / 颜色 / 置顶 / 隐藏)。
+ *
+ * 与图标 RPC 分开的一对端点:偏好文件坏了最多丢标签,不能拖累 favicon、红点
+ * 和进行中黄点。文档整份读写(客户端每次提交完整文档,宿主整份覆盖)。
+ */
+const workspacePrefsEntrySchema = z.object({
+	// 按 Unicode 字符数(不是 UTF-16 长度)限 6:6 个 emoji 是合法标签。
+	tag: z.string().refine((value) => [...value].length <= 6, { message: 'tag 最多 6 个字符' }),
+	color: z.enum(['red', 'orange', 'yellow', 'green', 'cyan', 'blue', 'purple', 'gray']),
+	pinned: z.boolean(),
+	hidden: z.boolean(),
+	pinAnchor: z.string().nullable()
+})
+
+const workspacePrefsSchema = z.object({
+	version: z.literal(1),
+	workspaces: z.record(z.string().min(1).max(200), workspacePrefsEntrySchema)
+})
+
+/**
+ * set 的请求 schema 故意放宽到"只验形状":端点自己会用 normalize 把非法 tag /
+ * 颜色 / 布尔值降级成默认值,所以旧客户端或手改的文档不会在网关层被整份拒绝,
+ * 从而丢掉本来还能用的那些工作区。
+ */
+const setWorkspacePrefsRequestSchema = z.object({
+	version: z.number().int().optional(),
+	workspaces: z.record(z.string(), z.unknown())
+})
+
 const setIconResultSchema = statusSchema
 
 
@@ -250,13 +280,31 @@ const services = [
 						summary: "Set the running-mark switch.",
 						jsDoc: "/** Set the running-mark switch. */",
 						tags: []
+					},
+					{
+						kind: 'method',
+						name: 'getWorkspacePrefs',
+						signature: 'async getWorkspacePrefs(): Promise<{ version: 1; workspaces: Record<string, { tag: string; color: string; pinned: boolean; hidden: boolean; pinAnchor: string | null }> }>',
+						description: "Read the per-workspace preferences (tag, color, pinned, hidden).",
+						summary: "Read workspace preferences.",
+						jsDoc: "/** Read workspace preferences. */",
+						tags: []
+					},
+					{
+						kind: 'method',
+						name: 'setWorkspacePrefs',
+						signature: 'async setWorkspacePrefs(request: { version?: number; workspaces: Record<string, unknown> }): Promise<{ version: 1; workspaces: Record<string, { tag: string; color: string; pinned: boolean; hidden: boolean; pinAnchor: string | null }> }>',
+						description: "Replace the whole workspace-preferences document (dirty fields degrade to defaults).",
+						summary: "Set workspace preferences.",
+						jsDoc: "/** Set workspace preferences. */",
+						tags: []
 					}
 				],
 				types: []
 			}
 ]
 
-/** 合并后的宿主端点:A 的 9 条 iconCustom/* + B 的 2 条 mailNotify/*。 */
+/** 合并后的宿主端点:A 的 12 条 iconCustom/* + B 的 2 条 mailNotify/*。 */
 const invocations = [
 {
 			id: 'dsh-lookout#iconCustom/getStatus',
@@ -439,6 +487,45 @@ const invocations = [
 			},
 			sourceLocation: { file: 'lib/index.js', line: 1, column: 1 }
 		},
+		{
+			id: 'dsh-lookout#iconCustom/getWorkspacePrefs',
+			service: 'iconCustom',
+			namespace: 'iconCustom',
+			method: 'getWorkspacePrefs',
+			invocation: { kind: 'direct' },
+			parameters: [],
+			result: {
+				mode: 'strict',
+				typeSymbol: 'dsh-lookout#iconCustom/getWorkspacePrefs:result',
+				create: () => workspacePrefsSchema
+			},
+			sourceLocation: { file: 'lib/index.js', line: 1, column: 1 }
+		},
+		{
+			id: 'dsh-lookout#iconCustom/setWorkspacePrefs',
+			service: 'iconCustom',
+			namespace: 'iconCustom',
+			method: 'setWorkspacePrefs',
+			invocation: { kind: 'direct' },
+			parameters: [
+				{
+					name: 'request',
+					wire: 'request',
+					source: 'json',
+					codec: {
+						mode: 'strict',
+						typeSymbol: 'dsh-lookout#iconCustom/setWorkspacePrefs:request',
+						create: () => setWorkspacePrefsRequestSchema
+					}
+				}
+			],
+			result: {
+				mode: 'strict',
+				typeSymbol: 'dsh-lookout#iconCustom/setWorkspacePrefs:result',
+				create: () => workspacePrefsSchema
+			},
+			sourceLocation: { file: 'lib/index.js', line: 1, column: 1 }
+		},
 		{
 			id: 'dsh-lookout#iconCustom/setUnreadSeen',
 			service: 'iconCustom',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cowwo/dsh-lookout",
   "description": "瞭望哨：盯着你的每个会话——谁跑完了、谁出错了、谁卡住了、谁在等你审批，用浏览器图标角标、红点/黄点和邮件通知你；顺带显示当前会话 ID。· Lookout: watches every session — who finished, who errored, who is stuck, and who is waiting for your approval — and notifies you through the browser favicon badge, red/yellow dots, and email, while also showing the current session ID.",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "main": "lib/index.js",