@chatcode/cco-market 1.45.1

package/src/dsh-install.ts

@@ -0,0 +1,118 @@
+/** Locate the DSH host package in CLI and packaged Desktop runtimes. */
+
+import { readFileSync, realpathSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+/** The entry with symlinks resolved, or unchanged when it cannot be read. */
+function realpathOf(entry: string): string {
+  try {
+    return realpathSync(entry)
+  } catch {
+    // A path that does not exist, or one inside an ASAR archive, where
+    // realpath fails: the raw entry is still the best guess and the walk
+    // below simply answers null if it leads nowhere.
+    return entry
+  }
+}
+
+const DSH_PACKAGE = '@deepseek-ai/dsh'
+
+/**
+ * The host package's own manifest, or null when `directory` is not it.
+ * @returns the parsed manifest of `@deepseek-ai/dsh`, or null.
+ */
+function readDshManifest(directory: string): { name: string; version?: unknown } | null {
+  try {
+    const manifest = JSON.parse(
+      readFileSync(join(directory, 'package.json'), 'utf8'),
+    ) as { name?: unknown; version?: unknown }
+    return manifest.name === DSH_PACKAGE ? { name: DSH_PACKAGE, version: manifest.version } : null
+  } catch {
+    return null
+  }
+}
+
+function isDshPackage(directory: string): boolean {
+  return readDshManifest(directory) !== null
+}
+
+/**
+ * The version of the DSH host this market is running inside.
+ *
+ * Read from the same manifest `findDshInstallDir` already parses to identify
+ * the package — the version was sitting in that object and being discarded.
+ *
+ * Worth reporting because the host version has repeatedly been the thing
+ * neither side could see. #293 turned on it (the reporter was on
+ * 0.1.1-rc.2 while every attempt to reproduce had been on 0.1.0-rc.8, which
+ * nobody knew until three rounds in), and #404 is entirely about a plugin
+ * that requires a host newer than the Desktop build it was installed on.
+ *
+ * The directory comes back too, because WHERE it was found is the other half
+ * of the answer: a path under Electron's resources is a Desktop-bundled host,
+ * which #139 established can be older than whatever `npm ls` would report.
+ * Asking the user is not a substitute — that is the number they do not have.
+ * @returns the host version and the directory it was read from, or null when
+ * no host package is locatable (a plain `dsh web` from a global install can
+ * legitimately land here).
+ */
+export function dshHostInfo(entry = process.argv[1]): { version: string; directory: string } | null {
+  const directory = findDshInstallDir(entry)
+  if (directory === null) return null
+  const manifest = readDshManifest(directory)
+  // Located but unversioned: report the directory anyway. "The host is here
+  // and declares no version" is a fact worth carrying, and it is not the
+  // same fact as "no host found".
+  const version = typeof manifest?.version === 'string' && manifest.version !== ''
+    ? manifest.version
+    : 'unknown'
+  return { version, directory }
+}
+
+/**
+ * Walk up from the CLI entry first, then inspect Electron's authoritative
+ * resources directory. Desktop distributions may keep node_modules outside
+ * the ASAR, expose them through ASAR's virtual filesystem, or disable ASAR.
+ *
+ * The entry is resolved through symlinks before the walk, because for a
+ * globally installed dsh it IS one. `npm i -g` and Homebrew both put a link
+ * in a `bin/` directory pointing at the real package, so `process.argv[1]`
+ * is `/opt/homebrew/bin/dsh` and walking up from there reaches `/` without
+ * ever passing the package. Measured: the same call answers `null` for the
+ * link and the correct directory for its target.
+ *
+ * That was not a cosmetic gap. Everything downstream reads the host version
+ * from here — the exported log's `dsh host:` line (#426), Discover's
+ * host-requirement column and filter (#473), and the pre-update check
+ * (#404) — and a null version makes every one of them answer "unknown",
+ * silently, on exactly the ordinary global install. A bundled Desktop host
+ * is reached by the resources branch below and was never affected, which is
+ * why this survived: the case that worked is the one that gets tested.
+ */
+export function findDshInstallDir(entry = process.argv[1]): string | null {
+  if (entry !== undefined) {
+    let directory = resolve(dirname(realpathOf(entry)))
+    for (let depth = 0; depth < 10; depth += 1) {
+      if (isDshPackage(directory)) return directory
+      const parent = dirname(directory)
+      if (parent === directory) break
+      directory = parent
+    }
+  }
+
+  const electronProcess = process as NodeJS.Process & { resourcesPath?: unknown }
+  if (typeof electronProcess.resourcesPath !== 'string'
+    || electronProcess.resourcesPath.length === 0) return null
+
+  for (const applicationRoot of ['app.asar.unpacked', 'app.asar', 'app']) {
+    const candidate = join(
+      electronProcess.resourcesPath,
+      applicationRoot,
+      'node_modules',
+      '@deepseek-ai',
+      'dsh',
+    )
+    if (isDshPackage(candidate)) return candidate
+  }
+  return null
+}

package/src/gist.ts

@@ -0,0 +1,362 @@
+/**
+ * GitHub Gist transport for profile backups — the third backup channel next
+ * to the local download and WebDAV (issue #89).
+ *
+ * Security posture:
+ * - The API host is hard-coded to api.github.com, so there is no SSRF surface
+ *   (unlike WebDAV, which accepts arbitrary user URLs).
+ * - The Gist id is validated against a strict character allowlist before it
+ *   is interpolated into the request path.
+ * - Tokens are never persisted: the client sends one per request (session
+ *   memory only) or the operator sets CHATCODE_CLI_MARKET_GITHUB_TOKEN on the
+ *   host; nothing
+ *   is written to disk by this module.
+ * - Downloaded content goes through `validatedBackup` before it is returned,
+ *   mirroring downloadWebdav's strict restore-side validation.
+ *
+ * Timeouts and errors:
+ * - Every request carries an AbortSignal: the caller's (route-level timeout,
+ *   so a wedged gh CLI or slow network yields a definite answer) merged with
+ *   a 30 s hard ceiling. Errors are classified into machine-readable codes
+ *   (`GistError`) so the UI can show friendly localized messages instead of
+ *   raw DOMException/network noise like "TimeoutError: signal timed out".
+ */
+import { spawn } from 'node:child_process'
+import { request as httpsRequest } from 'node:https'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { MAX_BACKUP_BYTES, validatedBackup, type ProfileBackup } from './backup.ts'
+import { compatibilityEnv } from './home-paths.ts'
+
+/** The single file every dshmarket backup Gist carries. */
+export const GIST_FILENAME = 'dsh-profile-backup.json'
+
+/** GitHub hard limit for one Gist file (1 MB); enforced before upload. */
+export const GIST_MAX_BYTES = 1024 * 1024
+
+/** Environment variable for a host-configured token (never read from disk). */
+export const GIST_TOKEN_ENV = 'CHATCODE_CLI_MARKET_GITHUB_TOKEN'
+export const LEGACY_GIST_TOKEN_ENV = 'DSH_GITHUB_TOKEN'
+
+const GIST_API_HOST = 'api.github.com'
+const GIST_ID_RE = /^[A-Za-z0-9_-]{1,64}$/
+const REQUEST_TIMEOUT_MS = 30_000
+
+/** Node network error codes that mean "GitHub is unreachable". */
+const NETWORK_ERROR_CODES = new Set([
+  'ENOTFOUND', 'EAI_AGAIN', 'ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT',
+  'EPIPE', 'EHOSTUNREACH', 'ENETUNREACH', 'ECONNABORTED',
+])
+
+/** Machine-readable error codes the client maps to localized messages. */
+export type GistErrorCode = 'auth' | 'notfound' | 'rate-limit' | 'invalid' | 'timeout' | 'network' | 'other'
+
+/** Error with a code for the UI; the message stays human-readable. */
+export class GistError extends Error {
+  readonly code: GistErrorCode
+  constructor(message: string, code: GistErrorCode = 'other') {
+    super(message)
+    this.name = 'GistError'
+    this.code = code
+  }
+}
+
+/** Classify any thrown value into a stable GistErrorCode. */
+export function gistErrorCode(error: unknown): GistErrorCode {
+  if (error instanceof GistError) return error.code
+  if (error instanceof Error) {
+    if (error.name === 'TimeoutError' || error.name === 'AbortError') return 'timeout'
+    const raw = (error as { code?: unknown }).code ?? (error as { cause?: { code?: unknown } }).cause?.code
+    if (typeof raw === 'string' && NETWORK_ERROR_CODES.has(raw)) return 'network'
+  }
+  return 'other'
+}
+
+export interface GistRef {
+  id: string
+  htmlUrl: string
+}
+
+/** Where the token used for a request came from (shown in the UI). */
+export type GistTokenSource = 'token' | 'env' | 'gh'
+
+/**
+ * Normalize a Gist id or a gist.github.com URL to a bare id.
+ * Anything else (paths, embedded slashes, oversize input) is rejected.
+ */
+export function parseGistId(input: string): string {
+  const trimmed = input.trim()
+  if (trimmed === '') throw new Error('gist id is required')
+  let candidate = trimmed
+  try {
+    const url = new URL(trimmed)
+    if (url.protocol === 'https:' && (url.hostname === 'gist.github.com' || url.hostname.endsWith('.gist.github.com'))) {
+      const parts = url.pathname.split('/').filter(Boolean)
+      candidate = parts[parts.length - 1] ?? ''
+    }
+  } catch {
+    // Not a URL — treat the raw input as the candidate; the allowlist decides.
+  }
+  if (!GIST_ID_RE.test(candidate)) throw new Error('invalid gist id')
+  return candidate
+}
+
+/**
+ * Resolve the token for one request, in order of preference:
+ * 1. an explicitly supplied token (session memory only);
+ * 2. the host-configured CHATCODE_CLI_MARKET_GITHUB_TOKEN environment variable;
+ * 3. an already-logged-in GitHub CLI (`gh auth token`) — the token is used
+ *    for this request only and never written to disk.
+ */
+export async function resolveGistTokenSource(bodyToken: unknown): Promise<{ token: string; source: GistTokenSource }> {
+  if (typeof bodyToken === 'string' && bodyToken.trim() !== '') return { token: bodyToken.trim(), source: 'token' }
+  const configured = compatibilityEnv(process.env, GIST_TOKEN_ENV, LEGACY_GIST_TOKEN_ENV)
+  if (configured !== undefined) return { token: configured, source: 'env' }
+  const ghToken = await ghAuthToken()
+  if (ghToken !== null) return { token: ghToken, source: 'gh' }
+  throw new GistError(
+    'GitHub token is required (enter it in the Backup tab, set CHATCODE_CLI_MARKET_GITHUB_TOKEN, or log in with the gh CLI)',
+    'auth',
+  )
+}
+
+/** Resolve just the token (kept for callers that do not need the source). */
+export async function resolveGistToken(bodyToken: unknown): Promise<string> {
+  return (await resolveGistTokenSource(bodyToken)).token
+}
+
+/** Short-lived in-memory cache for the gh-derived token (no disk, no browser). */
+let ghTokenCache: { token: string | null; expires: number } | null = null
+
+/** Test hook: drop the gh token cache between tests. */
+export function resetGhTokenCache(): void {
+  ghTokenCache = null
+}
+
+/** Ask an already-authenticated GitHub CLI for its token, if available. */
+async function ghAuthToken(): Promise<string | null> {
+  if (ghTokenCache !== null && Date.now() < ghTokenCache.expires) return ghTokenCache.token
+  const token = await fetchGhToken()
+  // Positive cache 10 min; negative cache 30 s so a wedged gh cannot make
+  // every click wait.
+  ghTokenCache = { token, expires: Date.now() + (token !== null ? 10 * 60_000 : 30_000) }
+  return token
+}
+
+/**
+ * Run `gh auth token` in a DETACHED child and give up after 8 s no matter
+ * what. The parent never waits on the child (unref), so even if gh.exe
+ * wedges under WSL interop the host event loop stays free and the request
+ * returns a definite answer. 8 s because a Windows gh.exe cold start through
+ * WSL interop is routinely slower than a native binary.
+ */
+function fetchGhToken(): Promise<string | null> {
+  return new Promise<string | null>((resolve) => {
+    const candidates = ['gh', join(homedir(), '.local', 'bin', 'gh')]
+    let settled = false
+    const finish = (value: string | null): void => {
+      if (settled) return
+      settled = true
+      resolve(value)
+    }
+    const tryNext = (index: number): void => {
+      if (index >= candidates.length) {
+        finish(null)
+        return
+      }
+      const command = candidates[index]!
+      let child: ReturnType<typeof spawn> | null = null
+      try {
+        child = spawn(command, ['auth', 'token'], {
+          stdio: ['ignore', 'pipe', 'ignore'],
+          detached: true,
+          windowsHide: true,
+        })
+      } catch {
+        tryNext(index + 1)
+        return
+      }
+      // Defensive: a mocked/odd spawn can return nullish — never crash on it.
+      if (child == null) {
+        tryNext(index + 1)
+        return
+      }
+      let out = ''
+      child.stdout?.on('data', (chunk: Buffer) => { out += chunk.toString() })
+      const timer = setTimeout(() => {
+        // Parent gives up; the detached child may keep running as an orphan
+        // but cannot block this process or its event loop.
+        try { child?.kill('SIGKILL') } catch { /* already gone */ }
+        finish(out.trim() !== '' ? out.trim() : null)
+      }, 8_000)
+      // On spawn failure (e.g. ENOENT) Node emits 'error' AND THEN 'close'
+      // (code -2). The 'close' handler must not resolve from an errored
+      // child: when 'gh' is missing from PATH (typical for systemd services)
+      // that premature finish(null) would race ahead of the next candidate's
+      // successful token and lock the result to null.
+      let errored = false
+      child.on('error', () => {
+        if (errored) return
+        errored = true
+        clearTimeout(timer)
+        if (!settled) tryNext(index + 1)
+      })
+      child.on('close', () => {
+        if (errored) return // companion of 'error' — the next candidate owns the result
+        clearTimeout(timer)
+        finish(out.trim() !== '' ? out.trim() : null)
+      })
+      child.unref()
+    }
+    tryNext(0)
+  })
+}
+
+interface GistResponse {
+  status: number
+  body: string
+}
+
+/** Map a request-level failure (abort or network error) to a GistError. */
+function classifyRequestError(error: unknown): Error {
+  if (error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError')) {
+    return new GistError('GitHub request timed out', 'timeout')
+  }
+  const raw = (error as { code?: unknown } | null)?.code ?? (error as { cause?: { code?: unknown } } | null)?.cause?.code
+  if (typeof raw === 'string' && NETWORK_ERROR_CODES.has(raw)) {
+    return new GistError(`GitHub is unreachable (${raw})`, 'network')
+  }
+  return error instanceof Error ? error : new GistError(String(error), 'other')
+}
+
+function gistRequest(token: string, method: 'GET' | 'POST' | 'PATCH', path: string, body?: string, signal?: AbortSignal): Promise<GistResponse> {
+  return new Promise<GistResponse>((resolve, reject) => {
+    const headers: Record<string, string> = {
+      authorization: `Bearer ${token}`,
+      'user-agent': 'ChatCode-CLI-Market',
+      accept: 'application/vnd.github+json',
+    }
+    if (body !== undefined) {
+      headers['content-type'] = 'application/json'
+      headers['content-length'] = String(Buffer.byteLength(body))
+    }
+    // Route-level signal (when given) wins; the 30 s ceiling still applies
+    // as a hard fallback so a forgotten signal can never hang the server.
+    const hardCeiling = AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    const effectiveSignal = signal !== undefined ? AbortSignal.any([signal, hardCeiling]) : hardCeiling
+    const request = httpsRequest({
+      protocol: 'https:',
+      hostname: GIST_API_HOST,
+      path,
+      method,
+      headers,
+      signal: effectiveSignal,
+    }, (response) => {
+      const chunks: Buffer[] = []
+      let size = 0
+      // GET returns the whole Gist including metadata; POST/PATCH return the
+      // created/updated Gist object, which ECHOES the file content back — so
+      // a large backup makes the response as large as the upload. Cap all
+      // methods alike so a hostile Gist cannot OOM us.
+      const maxBytes = MAX_BACKUP_BYTES + 16 * 1024
+      response.once('error', reject)
+      const declared = Number(response.headers['content-length'])
+      if (Number.isFinite(declared) && declared > maxBytes) {
+        response.destroy(new Error('GitHub response is too large'))
+        return
+      }
+      response.on('data', (chunk: Buffer | string) => {
+        const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+        size += value.byteLength
+        if (size > maxBytes) {
+          response.destroy(new Error('GitHub response is too large'))
+          return
+        }
+        chunks.push(value)
+      })
+      response.once('end', () => resolve({ status: response.statusCode ?? 0, body: Buffer.concat(chunks).toString('utf8') }))
+    })
+    request.once('error', (error) => reject(classifyRequestError(error)))
+    if (body !== undefined) request.end(body)
+    else request.end()
+  })
+}
+
+function parseGistError(status: number, body: string, action: string): Error {
+  let message = body
+  try {
+    const parsed = JSON.parse(body) as { message?: unknown }
+    if (typeof parsed.message === 'string' && parsed.message !== '') message = parsed.message
+  } catch { /* keep the raw body */ }
+  if (status === 401) return new GistError('GitHub token is invalid or revoked', 'auth')
+  if (status === 403) return new GistError(`GitHub rejected the ${action} (rate limit or insufficient scope): ${message}`, 'rate-limit')
+  if (status === 404) return new GistError('Gist not found (check the id/URL)', 'notfound')
+  if (status === 422) return new GistError(`GitHub rejected the ${action}: ${message}`, 'invalid')
+  return new GistError(`GitHub ${action} failed: HTTP ${status} ${message}`, 'other')
+}
+
+async function sendGistRequest(token: string, method: 'GET' | 'POST' | 'PATCH', path: string, body: string | undefined, action: string, signal?: AbortSignal): Promise<GistResponse> {
+  const response = await gistRequest(token, method, path, body, signal)
+  const ok = method === 'POST' ? response.status === 201 : response.status === 200
+  if (!ok) throw parseGistError(response.status, response.body, action)
+  return response
+}
+
+/** Create a new private Gist carrying one backup file. */
+export async function createGist(token: string, content: string, signal?: AbortSignal): Promise<GistRef> {
+  const body = JSON.stringify({
+    description: 'ChatCode CLI Market profile backup',
+    public: false,
+    files: { [GIST_FILENAME]: { content } },
+  })
+  const response = await sendGistRequest(token, 'POST', '/gists', body, 'Gist creation', signal)
+  const data = JSON.parse(response.body) as { id?: unknown; html_url?: unknown }
+  if (typeof data.id !== 'string' || data.id === '') throw new Error('GitHub returned an invalid Gist')
+  return { id: data.id, htmlUrl: typeof data.html_url === 'string' ? data.html_url : `https://gist.github.com/${data.id}` }
+}
+
+/** Overwrite the backup file inside an existing Gist (other files kept). */
+export async function updateGist(token: string, gistId: string, content: string, signal?: AbortSignal): Promise<GistRef> {
+  const body = JSON.stringify({ files: { [GIST_FILENAME]: { content } } })
+  const response = await sendGistRequest(token, 'PATCH', `/gists/${gistId}`, body, 'Gist update', signal)
+  const data = JSON.parse(response.body) as { id?: unknown; html_url?: unknown }
+  return { id: typeof data.id === 'string' ? data.id : gistId, htmlUrl: typeof data.html_url === 'string' ? data.html_url : `https://gist.github.com/${gistId}` }
+}
+
+/** Download and strictly validate the backup file inside a Gist. */
+export async function readGist(token: string, gistId: string, signal?: AbortSignal): Promise<ProfileBackup> {
+  const response = await sendGistRequest(token, 'GET', `/gists/${gistId}`, undefined, 'Gist read', signal)
+  let data: { files?: Record<string, unknown> }
+  try {
+    data = JSON.parse(response.body) as { files?: Record<string, unknown> }
+  } catch {
+    throw new GistError('GitHub returned an unreadable Gist payload', 'invalid')
+  }
+  const file = data.files?.[GIST_FILENAME]
+  const content = file !== null && typeof file === 'object' && !Array.isArray(file)
+    ? (file as { content?: unknown }).content
+    : undefined
+  if (typeof content !== 'string') throw new GistError(`Gist has no ${GIST_FILENAME} file`, 'invalid')
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(content)
+  } catch {
+    throw new GistError('Gist backup is not valid JSON', 'invalid')
+  }
+  // Strict validation server-side: restore only accepts real backups.
+  try {
+    return validatedBackup(parsed)
+  } catch (error) {
+    throw new GistError(error instanceof Error ? error.message : String(error), 'invalid')
+  }
+}
+
+/** Confirm the token is usable (GET /user). */
+export async function verifyGistToken(token: string, signal?: AbortSignal): Promise<void> {
+  await sendGistRequest(token, 'GET', '/user', undefined, 'token verification', signal)
+}
+
+/** True when the serialized backup fits inside a Gist file. */
+export function fitsGistLimit(content: string): boolean {
+  return Buffer.byteLength(content) <= GIST_MAX_BYTES
+}

package/src/groups.ts

@@ -0,0 +1,111 @@
+/**
+ * Custom plugin groups (Roadmap #60): user-defined named collections of
+ * installed plugins whose enable/disable state can be switched as a unit —
+ * borrowing the "group by capability, toggle as one" idea from Claude
+ * Desktop's skill management. Membership lives in state.json and is the
+ * only durable truth: a group's switch state is always derived from its
+ * members and never persisted itself.
+ *
+ * Pure CRUD over the caller-owned state objects; routes.ts persists after
+ * each mutation and applies the live toggles for the batch action.
+ */
+
+export type GroupAction = 'create' | 'rename' | 'delete' | 'set-members' | 'toggle'
+
+/** The slices of market state group CRUD touches (routes.ts owns the rest). */
+export interface GroupState {
+  groups: Record<string, string[]>
+  groupOrder: string[]
+}
+
+export interface GroupMutationResult {
+  ok: boolean
+  error?: string
+}
+
+/** Group names: letters/digits (incl. CJK), spaces, underscores, hyphens. */
+const GROUP_NAME_RE = /^[\p{L}\p{N}_ -]{1,40}$/u
+
+function isGroupName(value: unknown): value is string {
+  return typeof value === 'string' && GROUP_NAME_RE.test(value)
+}
+
+export function createGroup(state: GroupState, name: unknown): GroupMutationResult {
+  if (!isGroupName(name)) return { ok: false, error: 'invalid group name / 分组名称无效' }
+  if (state.groups[name] !== undefined) return { ok: false, error: 'group already exists / 分组已存在' }
+  state.groups[name] = []
+  state.groupOrder.push(name)
+  return { ok: true }
+}
+
+export function renameGroup(state: GroupState, name: unknown, newName: unknown): GroupMutationResult {
+  if (typeof name !== 'string' || state.groups[name] === undefined) {
+    return { ok: false, error: 'group not found / 分组不存在' }
+  }
+  if (!isGroupName(newName)) return { ok: false, error: 'invalid group name / 分组名称无效' }
+  if (newName !== name && state.groups[newName] !== undefined) {
+    return { ok: false, error: 'group already exists / 分组已存在' }
+  }
+  const members = state.groups[name]
+  delete state.groups[name]
+  state.groups[newName] = members
+  const index = state.groupOrder.indexOf(name)
+  if (index !== -1) state.groupOrder[index] = newName
+  return { ok: true }
+}
+
+export function deleteGroup(state: GroupState, name: unknown): GroupMutationResult {
+  if (typeof name !== 'string' || state.groups[name] === undefined) {
+    return { ok: false, error: 'group not found / 分组不存在' }
+  }
+  delete state.groups[name]
+  // Mutate in place: routes.ts hands over the LIVE groupOrder array, and the
+  // response serializes that same array — replacing it here would orphan it.
+  const index = state.groupOrder.indexOf(name)
+  if (index !== -1) state.groupOrder.splice(index, 1)
+  return { ok: true }
+}
+
+/**
+ * Replace a group's membership. Only currently installed plugins can be
+ * members — ghost names (uninstalled meanwhile) are dropped and duplicates
+ * collapse, so the persisted list stays clean. Themes are exclusive: a group
+ * may hold at most one theme plugin, mirroring the global one-active-theme
+ * rule (only one theme can be enabled at a time).
+ */
+export function setGroupMembers(
+  state: GroupState,
+  name: unknown,
+  members: unknown,
+  installed: ReadonlySet<string>,
+  themes: ReadonlySet<string>,
+): GroupMutationResult {
+  if (typeof name !== 'string' || state.groups[name] === undefined) {
+    return { ok: false, error: 'group not found / 分组不存在' }
+  }
+  if (!Array.isArray(members)) return { ok: false, error: 'members must be an array / 成员必须是数组' }
+  const kept: string[] = []
+  const seen = new Set<string>()
+  for (const member of members) {
+    if (typeof member !== 'string' || member === '' || seen.has(member)) continue
+    // The market itself never participates in groups (#60 assumptions).
+    if (member === '@chatcode/cco-market' || member === 'dsh-market' || member === 'dshmarket') continue
+    seen.add(member)
+    if (installed.has(member)) kept.push(member)
+  }
+  let themeCount = 0
+  for (const member of kept) if (themes.has(member)) themeCount += 1
+  if (themeCount > 1) {
+    return { ok: false, error: 'a group can contain at most one theme / 每组最多一个主题' }
+  }
+  state.groups[name] = kept
+  return { ok: true }
+}
+
+/** Drop `name` from every group (called after a successful uninstall). */
+export function removeFromGroups(state: GroupState, name: string): void {
+  for (const group of Object.keys(state.groups)) {
+    const members = state.groups[group]
+    if (members.includes(name)) state.groups[group] = members.filter(member => member !== name)
+  }
+}

package/src/home-paths.ts

@@ -0,0 +1,53 @@
+/** ChatCode CLI Home resolution with legacy Harness input compatibility. */
+
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+/** Default single-root ChatCode CLI home. */
+export function defaultChatCodeHome(): string {
+  return join(homedir(), '.chatcode-cli')
+}
+
+/** @deprecated Compatibility alias for downstream code. */
+export const defaultDshHome = defaultChatCodeHome
+
+/** Expand the tilde forms supported by ChatCode CLI configuration. */
+export function expandHomePath(path: string): string {
+  if (path === '~') return homedir()
+  if (path.startsWith('~/') || path.startsWith('~\\')) return join(homedir(), path.slice(2))
+  return path
+}
+
+/**
+ * Resolve an explicit home, `CHATCODE_CLI_HOME`, legacy `DSH_HOME`, or the
+ * default to one normalized absolute path. Blank environment values are unset.
+ */
+export function resolveChatCodeHome(
+  configured?: string,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  const chatCodeHome = env.CHATCODE_CLI_HOME?.trim()
+  const legacyHome = env.DSH_HOME?.trim()
+  const selected = configured
+    ?? (chatCodeHome !== undefined && chatCodeHome.length > 0
+      ? chatCodeHome
+      : legacyHome !== undefined && legacyHome.length > 0
+        ? legacyHome
+        : defaultChatCodeHome())
+  return resolve(expandHomePath(selected))
+}
+
+/** @deprecated Compatibility alias for callers that still import the old API. */
+export const resolveDshHome = resolveChatCodeHome
+
+/** Read a non-empty ChatCode variable before its legacy compatibility input. */
+export function compatibilityEnv(
+  env: Record<string, string | undefined>,
+  currentName: string,
+  legacyName: string,
+): string | undefined {
+  const current = env[currentName]?.trim()
+  if (current !== undefined && current.length > 0) return current
+  const legacy = env[legacyName]?.trim()
+  return legacy !== undefined && legacy.length > 0 ? legacy : undefined
+}