305 lines
13 KiB
TypeScript
305 lines
13 KiB
TypeScript
/**
|
||
* Runtime grouping overlay for @dsh-xhl/workspace-groups: manual groups created in
|
||
* the sidebar UI and per-workspace category overrides. Stored in a plugin-
|
||
* owned JSON sidecar (`$DSH_HOME/workspace-groups.manual.json`), separate from
|
||
* the operator YAML — the YAML stays the rule source, this file only records
|
||
* runtime decisions, and writes are atomic (temp file + fsync + rename).
|
||
*
|
||
* The browser PUT route writes the whole overlay (idempotent, last write
|
||
* wins); reads tolerate hand-edited content (parse-only) while the write
|
||
* boundary cross-validates against the current rule categories.
|
||
*/
|
||
import { mkdir, open, readFile, rename, unlink } from 'node:fs/promises'
|
||
import { dirname, resolve } from 'node:path'
|
||
import { homedir } from 'node:os'
|
||
import { ruleDisplayName } from './core/matcher.ts'
|
||
import {
|
||
GROUP_COLORS,
|
||
TOP_LEVEL_ORDER_KEY,
|
||
UNCATEGORIZED_LABEL,
|
||
type CategoryAppearance,
|
||
type GroupColor,
|
||
type ManualGroups,
|
||
} from './core/types.ts'
|
||
|
||
/** Default overlay location: `$DSH_HOME/workspace-groups.manual.json`. */
|
||
export function defaultManualPath(): string {
|
||
const home = process.env.DSH_HOME !== undefined && process.env.DSH_HOME !== ''
|
||
? process.env.DSH_HOME
|
||
: resolve(homedir(), '.dsh')
|
||
return resolve(home, 'workspace-groups.manual.json')
|
||
}
|
||
|
||
/**
|
||
* Parse + shape-validate a raw overlay document into a ManualGroups.
|
||
* Validates types only — category references are checked against the rule set
|
||
* at the write boundary (validateManualGroups), because reads must tolerate
|
||
* files written while the rule set was different.
|
||
* @param raw - parsed JSON value.
|
||
* @returns the normalized overlay.
|
||
* @throws when the shape is malformed (non-mapping, bad names, duplicates,
|
||
* the reserved uncategorized label, bad assignment/order values).
|
||
*/
|
||
export function parseManualGroups(raw: unknown): ManualGroups {
|
||
if (raw === undefined || raw === null) return { categories: [], assignments: {} }
|
||
if (typeof raw !== 'object' || Array.isArray(raw)) {
|
||
throw new Error('workspace-groups.manual.json: top-level value must be a mapping')
|
||
}
|
||
const source = raw as Record<string, unknown>
|
||
|
||
const categories: string[] = []
|
||
if (source.categories !== undefined) {
|
||
if (!Array.isArray(source.categories)) {
|
||
throw new Error('workspace-groups.manual.json: categories must be a list')
|
||
}
|
||
const seen = new Set<string>()
|
||
for (const entry of source.categories) {
|
||
if (typeof entry !== 'string' || entry.trim() === '') {
|
||
throw new Error('workspace-groups.manual.json: each manual category must be a non-empty string')
|
||
}
|
||
const name = entry.trim()
|
||
if (name === UNCATEGORIZED_LABEL) {
|
||
throw new Error(`workspace-groups.manual.json: manual category name "${name}" is reserved`)
|
||
}
|
||
if (seen.has(name)) {
|
||
throw new Error(`workspace-groups.manual.json: duplicate manual category "${name}"`)
|
||
}
|
||
seen.add(name)
|
||
categories.push(name)
|
||
}
|
||
}
|
||
|
||
const assignments: Record<string, string | null> = {}
|
||
if (source.assignments !== undefined) {
|
||
if (typeof source.assignments !== 'object' || source.assignments === null || Array.isArray(source.assignments)) {
|
||
throw new Error('workspace-groups.manual.json: assignments must be a mapping')
|
||
}
|
||
for (const [workspaceId, category] of Object.entries(source.assignments)) {
|
||
if (workspaceId === '__proto__') continue // assigning it would mutate the record's prototype
|
||
if (workspaceId.trim() === '') {
|
||
throw new Error('workspace-groups.manual.json: assignment keys must be non-empty')
|
||
}
|
||
if (category === null) {
|
||
assignments[workspaceId] = null // force uncategorized
|
||
continue
|
||
}
|
||
if (typeof category !== 'string' || category.trim() === '') {
|
||
throw new Error(`workspace-groups.manual.json: assignment "${workspaceId}" must be a category name or null`)
|
||
}
|
||
assignments[workspaceId] = category.trim()
|
||
}
|
||
}
|
||
|
||
const manual: ManualGroups = { categories, assignments }
|
||
if (typeof source.revision === 'number' && Number.isSafeInteger(source.revision) && source.revision >= 0) {
|
||
manual.revision = source.revision
|
||
}
|
||
|
||
if (source.categoryOrder !== undefined) {
|
||
manual.categoryOrder = parseStringList(source.categoryOrder, 'categoryOrder', true)
|
||
}
|
||
if (source.hidden !== undefined) {
|
||
manual.hidden = parseStringList(source.hidden, 'hidden', true)
|
||
}
|
||
if (source.renamed !== undefined) {
|
||
if (typeof source.renamed !== 'object' || source.renamed === null || Array.isArray(source.renamed)) {
|
||
throw new Error('workspace-groups.manual.json: renamed must be a mapping')
|
||
}
|
||
const renamed: Record<string, string> = {}
|
||
for (const [original, display] of Object.entries(source.renamed)) {
|
||
if (original === '__proto__') continue // assigning it would mutate the record's prototype
|
||
if (original.trim() === '') throw new Error('workspace-groups.manual.json: renamed keys must be non-empty')
|
||
if (typeof display !== 'string' || display.trim() === '') {
|
||
throw new Error(`workspace-groups.manual.json: renamed "${original}" must be a non-empty string`)
|
||
}
|
||
renamed[original] = display.trim()
|
||
}
|
||
manual.renamed = renamed
|
||
}
|
||
if (source.appearance !== undefined) {
|
||
if (typeof source.appearance !== 'object' || source.appearance === null || Array.isArray(source.appearance)) {
|
||
throw new Error('workspace-groups.manual.json: appearance must be a mapping')
|
||
}
|
||
const appearance: Record<string, CategoryAppearance> = {}
|
||
for (const [key, value] of Object.entries(source.appearance)) {
|
||
if (key === '__proto__') continue // assigning it would mutate the record's prototype
|
||
if (key.trim() === '') throw new Error('workspace-groups.manual.json: appearance keys must be non-empty')
|
||
const parsed = parseAppearance(value, key)
|
||
if (parsed !== undefined) appearance[key.trim()] = parsed
|
||
}
|
||
if (Object.keys(appearance).length > 0) manual.appearance = appearance
|
||
}
|
||
if (source.workspaceOrder !== undefined) {
|
||
if (typeof source.workspaceOrder !== 'object' || source.workspaceOrder === null || Array.isArray(source.workspaceOrder)) {
|
||
throw new Error('workspace-groups.manual.json: workspaceOrder must be a mapping')
|
||
}
|
||
const workspaceOrder: Record<string, string[]> = {}
|
||
for (const [categoryKey, ids] of Object.entries(source.workspaceOrder)) {
|
||
if (categoryKey === '__proto__') continue // assigning it would mutate the record's prototype
|
||
if (categoryKey.trim() === '') {
|
||
throw new Error('workspace-groups.manual.json: workspaceOrder keys must be non-empty')
|
||
}
|
||
workspaceOrder[categoryKey] = parseStringList(ids, `workspaceOrder["${categoryKey}"]`, true)
|
||
}
|
||
manual.workspaceOrder = workspaceOrder
|
||
}
|
||
|
||
return manual
|
||
}
|
||
|
||
/** Preset icon ids are lowercase kebab-case; anything else must be a short glyph. */
|
||
const ICON_PATTERN = /^(?:[a-z][a-z0-9-]{0,23}|[^\s\u0000-\u001f\u007f]{1,4})$/u
|
||
|
||
/** Narrow an unknown value to a palette id from the shared whitelist. */
|
||
function isGroupColor(value: unknown): value is GroupColor {
|
||
return GROUP_COLORS.some(color => color === value)
|
||
}
|
||
|
||
/**
|
||
* Parse one appearance entry. Unknown sub-keys are dropped; an entry that ends
|
||
* up empty is dropped entirely (returns undefined) so the file stays minimal.
|
||
*/
|
||
function parseAppearance(value: unknown, key: string): CategoryAppearance | undefined {
|
||
const field = `appearance["${key}"]`
|
||
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
|
||
throw new Error(`workspace-groups.manual.json: ${field} must be an object`)
|
||
}
|
||
const source = value as Record<string, unknown>
|
||
const appearance: CategoryAppearance = {}
|
||
if (source.color !== undefined) {
|
||
if (!isGroupColor(source.color)) {
|
||
throw new Error(
|
||
`workspace-groups.manual.json: ${field}.color must be one of: ${GROUP_COLORS.join(', ')}`,
|
||
)
|
||
}
|
||
appearance.color = source.color
|
||
}
|
||
if (source.icon !== undefined) {
|
||
const icon = typeof source.icon === 'string' ? source.icon.trim() : ''
|
||
if (icon === '' || !ICON_PATTERN.test(icon)) {
|
||
throw new Error(`workspace-groups.manual.json: ${field}.icon must be an icon id or a 1–4 character glyph`)
|
||
}
|
||
appearance.icon = icon
|
||
}
|
||
if (source.pinned !== undefined) {
|
||
if (typeof source.pinned !== 'boolean') {
|
||
throw new Error(`workspace-groups.manual.json: ${field}.pinned must be a boolean`)
|
||
}
|
||
// Never persist `pinned: false` — an absent flag already means unpinned.
|
||
if (source.pinned) appearance.pinned = true
|
||
}
|
||
return Object.keys(appearance).length === 0 ? undefined : appearance
|
||
}
|
||
|
||
/** Parse a list of non-empty strings, optionally de-duplicated. */
|
||
function parseStringList(value: unknown, field: string, unique: boolean): string[] {
|
||
if (!Array.isArray(value)) {
|
||
throw new Error(`workspace-groups.manual.json: ${field} must be a list`)
|
||
}
|
||
const seen = new Set<string>()
|
||
const result: string[] = []
|
||
for (const entry of value) {
|
||
if (typeof entry !== 'string' || entry.trim() === '') {
|
||
throw new Error(`workspace-groups.manual.json: ${field} entries must be non-empty strings`)
|
||
}
|
||
const trimmed = entry.trim()
|
||
if (unique && seen.has(trimmed)) {
|
||
throw new Error(`workspace-groups.manual.json: ${field} has duplicate entry "${trimmed}"`)
|
||
}
|
||
seen.add(trimmed)
|
||
result.push(trimmed)
|
||
}
|
||
return result
|
||
}
|
||
|
||
/**
|
||
* Cross-validate a parsed overlay against the current rule categories
|
||
* (write boundary only). Every assignment value must be `null`, a rule
|
||
* display name, a manual category name, or the uncategorized label; order
|
||
* keys must reference existing categories; renames/hides must reference
|
||
* actual rule categories.
|
||
* @param manual - parsed overlay.
|
||
* @param ruleCategoryNames - current YAML rule category original names.
|
||
* @throws when the overlay references categories that do not exist.
|
||
*/
|
||
export function validateManualGroups(manual: ManualGroups, ruleCategoryNames: readonly string[]): void {
|
||
const ruleNames = new Set(ruleCategoryNames)
|
||
const allowed = new Set<string>(ruleCategoryNames.map(name => ruleDisplayName(manual, name)))
|
||
for (const name of manual.categories) allowed.add(name)
|
||
allowed.add(UNCATEGORIZED_LABEL)
|
||
|
||
for (const [workspaceId, category] of Object.entries(manual.assignments)) {
|
||
if (category === null) continue
|
||
if (!allowed.has(category)) {
|
||
throw new Error(`workspace-groups.manual.json: assignment "${workspaceId}" references unknown category "${category}"`)
|
||
}
|
||
}
|
||
for (const key of manual.categoryOrder ?? []) {
|
||
if (!allowed.has(key) || key === UNCATEGORIZED_LABEL) {
|
||
throw new Error(`workspace-groups.manual.json: categoryOrder references unknown category "${key}"`)
|
||
}
|
||
}
|
||
for (const key of Object.keys(manual.workspaceOrder ?? {})) {
|
||
// The top-level order key is a reserved, non-category list.
|
||
if (key === TOP_LEVEL_ORDER_KEY) continue
|
||
if (!allowed.has(key) || key === UNCATEGORIZED_LABEL) {
|
||
throw new Error(`workspace-groups.manual.json: workspaceOrder references unknown category "${key}"`)
|
||
}
|
||
}
|
||
for (const original of Object.keys(manual.renamed ?? {})) {
|
||
if (!ruleNames.has(original)) {
|
||
throw new Error(`workspace-groups.manual.json: renamed references unknown rule category "${original}"`)
|
||
}
|
||
}
|
||
for (const original of manual.hidden ?? []) {
|
||
if (!ruleNames.has(original)) {
|
||
throw new Error(`workspace-groups.manual.json: hidden references unknown rule category "${original}"`)
|
||
}
|
||
}
|
||
// `appearance` is deliberately NOT cross-validated against existing
|
||
// categories: a presentation entry for a temporarily removed YAML category
|
||
// must survive, otherwise removing one category from the YAML would make
|
||
// every subsequent overlay save fail with 400 and freeze the whole tree.
|
||
}
|
||
|
||
/** Read + parse the overlay file. A missing file yields an empty overlay. */
|
||
export async function readManualGroups(path: string): Promise<ManualGroups> {
|
||
let text: string
|
||
try {
|
||
text = await readFile(path, 'utf8')
|
||
} catch (error) {
|
||
if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { categories: [], assignments: {} }
|
||
throw error
|
||
}
|
||
return parseManualGroups(JSON.parse(text))
|
||
}
|
||
|
||
/**
|
||
* Atomically replace the overlay file: write a same-directory temp file,
|
||
* fsync it, then rename over the target. A crash never leaves a torn JSON at
|
||
* the real path (readers see either the old or the new file).
|
||
* @param path - target file path.
|
||
* @param manual - overlay to persist.
|
||
*/
|
||
export async function writeManualGroups(path: string, manual: ManualGroups): Promise<void> {
|
||
const json = `${JSON.stringify(manual, null, 2)}\n`
|
||
await mkdir(dirname(path), { recursive: true })
|
||
const tmp = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`
|
||
const handle = await open(tmp, 'w')
|
||
try {
|
||
await handle.writeFile(json, 'utf8')
|
||
await handle.sync()
|
||
} catch (error) {
|
||
await handle.close().catch(() => {})
|
||
await unlink(tmp).catch(() => {})
|
||
throw error
|
||
}
|
||
await handle.close()
|
||
try {
|
||
await rename(tmp, path)
|
||
} catch (error) {
|
||
await unlink(tmp).catch(() => {})
|
||
throw error
|
||
}
|
||
}
|