@maci0/dsh-alias 0.5.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcel W. Wysocki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# dsh-alias
+
+Define your own slash commands in DeepSeek Harness, from the composer or from
+the Plugins page.
+
+## What you get
+
+```
+/alias add gm summarize the repository in five bullets
+/alias add rev /perf-review {args}
+/alias add ship /cordis-review
+/alias list
+/alias remove gm
+```
+
+After that, `/gm`, `/rev src/app.ts`, and `/ship` are ordinary commands: they
+show up in the composer's command directory and run without a model turn of
+their own. The Plugins page gains an **Alias** card that edits the same set.
+
+## Install
+
+> **Install it as a bundle.** `dsh plugin add …` mounts the row from the
+> package's own patch layer, which is what the settings editor can write to. A
+> row added with `--patch` is an overlay: it disappears at the next start, and
+> the Plugins card cannot save into it (the editor refuses a write an overlay
+> would win).
+
+```sh
+dsh plugin --profile web add @maci0/dsh-alias@0.5.2
+```
+
+This installs the public npm package; no GitHub token or `~/.secrets` setup is needed.
+The version is pinned. To upgrade, run the same command with a newer version,
+then restart `dsh web` (bundle layers compose at boot).
+
+The bundled `cordis.patch.yml` inserts the `alias` row.
+
+## Commands
+
+`/alias add <name> <text>` registers `/<name>`. What `/<name>` does depends on
+the text it stands for:
+
+- **Text starting with `/` runs that command.** `/alias add rev /perf-review`
+  makes `/rev --staged` equivalent to `/perf-review --staged`, including the
+  `/perf-review` lifecycle row in the log. Nested aliases are allowed and stop
+  after four levels, so a cycle is reported instead of hanging.
+- **Anything else is queued to the agent as a prompt.** `/alias add gm good
+  morning` turns `/gm now what` into a follow-up turn whose prompt is
+  `good morning now what`. The message is attributed to the alias rather than
+  to you, so mode commands such as `normal mode` inside an alias text cannot
+  be mistaken for your own words.
+
+`{args}` in the text is replaced with whatever you typed after the alias name;
+when the text has no placeholder and you did type arguments, they are appended.
+A name is lowercase letters, digits, `_` or `-`, must start with a letter, and
+may not be `alias` or shadow another registered command.
+
+`/alias` with no verb lists the aliases; `/alias set` is a synonym for `add`,
+and `rm` and `delete` are synonyms for `remove`.
+
+## Configure
+
+Aliases live in one settings field, the plugin's own row:
+
+```yaml
+- id: alias
+  name: '@maci0/dsh-alias'
+  config:
+    aliases:
+      gm: summarize the repository in five bullets
+      rev: /perf-review {args}
+```
+
+## How it works
+
+The field is `volatile()`, so the Plugins page's **Alias** card, `/alias`, and
+the profile patch are three views of one document: a write from any of them
+lands on the running instance with no remount. A deployment whose settings
+document refuses writes still gets working aliases in every current session
+until dsh restarts, and the reply says so. The card reports a write the host refuses.
+
+The card's **Edit** control loads a row back into the form; the same write
+adds and updates, and the button says which one it will do.
+
+## Limits
+
+- Aliases accept no attachments; the composer refuses a submission that carries
+  any, rather than dropping them silently.
+- A name typed in `/alias add` must already be lowercase; the card lowercases
+  the name for you.
+
+## Development
+
+dsh loads plugins on Node `^22.19.0 || >=24.0.0`; development and tests run on
+bun.
+
+Plain JavaScript, no build step: `bun test` runs the suite over the host
+half (`index.js`) and the browser half (`lib/client.js`) against structural
+fakes of the harness surfaces they use, plus a composition test that mounts the
+plugin in a real `@deepseek-ai/cordis` context.
+
+```sh
+bun install --frozen-lockfile
+bun test
+```
+
+For local development, `dsh plugin --profile <name> add <path-to-checkout>`.
+
+## Licence
+
+MIT, see [LICENSE](LICENSE).

package/cordis.patch.yml

@@ -0,0 +1,15 @@
+# Bundle layer: applied when a profile lists this bundle in dsh.profile.bundles
+# (dsh plugin add does that from dsh.bundle). That list is frozen at boot.
+# Do not also paste this row into the profile's cordis.patch.yml: insert does
+# not dedupe ids, two rows would register the plugin twice.
+#
+# `name` stays a bare package specifier: the browser half is served by the
+# client module system, which resolves the Loader entry's package, reads its
+# `dsh.client` manifest, and serves `exports["./client"]`.
+- insert:
+    - id: alias
+      name: '@maci0/dsh-alias'
+      config:
+        # name (without the slash) -> the text /<name> expands to. Edit them
+        # here, with /alias, or from the Plugins page's Alias card.
+        aliases: {}

package/icon.svg

@@ -0,0 +1,5 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <path d="M12 18h16" stroke="#145AF3" stroke-width="2.4" stroke-linecap="round"/>
+  <path d="M22.5 11.8 28.7 18l-6.2 6.2" stroke="#145AF3" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M7.6 25.4 11.6 10.6" stroke="#145AF3" stroke-width="2.4" stroke-linecap="round" opacity="0.55"/>
+</svg>

package/index.js

@@ -0,0 +1,487 @@
+/**
+ * dsh-alias: user-defined slash commands, as a DeepSeek Harness plugin.
+ *
+ * `/alias add <name> <text>` registers `/<name>`, `/alias remove <name>` drops
+ * it, `/alias list` prints them; a bare `/alias` lists. The same aliases are
+ * editable from the Plugins page, where this package's browser half renders the
+ * row's configuration card (`lib/client.js`).
+ *
+ * One settings field carries the state: the `aliases` dictionary of the
+ * plugin's own row in the profile patch.
+ *
+ * ```yaml
+ * - id: alias
+ *   name: '@maci0/dsh-alias'
+ *   config:
+ *     aliases: { gm: good morning, summarize the repo }
+ * ```
+ *
+ * The field is `volatile()`, so a write from either surface updates the live
+ * config reference in place, with no remount, and emits
+ * `loader/volatile-update`; this half re-reads the dictionary there and
+ * re-registers exactly the commands that changed. A deployment whose settings
+ * document refuses the write still gets a working alias until dsh restarts, held
+ * in a local overlay, and the reply says so.
+ *
+ * What `/<name>` does when invoked:
+ *
+ * - expanded text starting with `/` runs that command through `ctx.commands`,
+ *   so `/alias add rev /perf-review` makes `/rev src/app.ts` equivalent to
+ *   `/perf-review src/app.ts` (bounded to {@link MAX_DEPTH} nested expansions);
+ * - anything else is queued to the agent as the ordinary follow-up prompt
+ *   `/loop`-style, which is what makes `/alias add gm summarize the repo` a
+ *   usable shortcut.
+ *
+ * `{args}` in the text is replaced with whatever follows the alias name; when
+ * the text has no placeholder and the caller typed arguments, they are
+ * appended.
+ *
+ * This file is plain JavaScript on purpose, like `dsh-loop`: the plugin needs
+ * no build step, no bundled runtime, and `bun test` runs the suite on the
+ * sources directly.
+ *
+ * @module dsh-alias
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { randomUUID } from 'node:crypto'
+import Schema from '@deepseek-ai/schemastery'
+
+/** Plugin name as it appears in the loader. */
+export const name = 'alias'
+
+/**
+ * Row id this plugin's browser card is keyed by: the Plugins page pairs
+ * `plugins.row.config` entry `dsh-alias#alias` with the settings namespace the
+ * row declares, which is this same id.
+ */
+export const ROW_ID = 'alias'
+
+/** The names the command registry accepts, and this plugin therefore allows. */
+const COMMAND_NAME = /^[a-z][a-z0-9_-]*$/u
+
+/** A complete slash-command line, split the way the registry splits it. */
+const COMMAND_LINE = /^\/([a-z][a-z0-9_-]*)(?=$|[\t\n\r ])/u
+
+/** Name of the management command itself: no alias may shadow it. */
+const ALIAS_COMMAND = 'alias'
+
+/** How far one alias may expand into another before the call is refused. */
+export const MAX_DEPTH = 4
+
+/**
+ * Nested-expansion depth of the invocation chain currently running. Per async
+ * chain, not per plugin: concurrent invocations (another session, another
+ * plugin's nested command) must not count each other's nesting.
+ */
+const aliasDepth = new AsyncLocalStorage()
+
+/** Longest alias text echoed in a description line or a listing. */
+const PREVIEW_LIMIT = 72
+
+/** Usage line shared by every rejected `/alias` form. */
+const USAGE = 'Usage: /alias add <name> <text> (creates /<name>); '
+  + '/alias remove <name>; /alias list. A name is lowercase letters, digits, `_` or `-`. '
+  + 'Text may use {args} for whatever you type after the alias.'
+
+/**
+ * Configuration accepted from this plugin's row in a profile patch.
+ *
+ * `aliases` maps a command name (without the slash) to the text that command
+ * expands to. It is the only editable field, it is `volatile()` so both
+ * surfaces edit it live, and the `default({})` keeps the form present in a
+ * deployment whose row states no aliases.
+ *
+ * `apply` receives the schema-resolved row, so the field is a live reference
+ * rather than a value: read it with `.get()`, as the harness documents for
+ * every volatile Config field.
+ *
+ * @typedef {{ readonly aliases: import('@deepseek-ai/cordis').Volatile<Record<string, string>> }} Config
+ */
+export const Config = Schema.object({
+  aliases: Schema.dict(Schema.string()).default({}).volatile(),
+})
+
+/**
+ * Parse the text after `/alias`.
+ * @param {string} input - verbatim `rawInput` of the invocation.
+ * @returns {{ kind: 'list' }
+ *   | { kind: 'add', name: string, text: string }
+ *   | { kind: 'remove', name: string }
+ *   | { kind: 'error', text: string }} the requested verb.
+ */
+export function parseAliasInput(input) {
+  const trimmed = input.trim()
+  if (trimmed === '') return { kind: 'list' }
+  const space = trimmed.search(/\s/u)
+  const verb = (space === -1 ? trimmed : trimmed.slice(0, space)).toLowerCase()
+  const rest = space === -1 ? '' : trimmed.slice(space + 1).trim()
+
+  if (verb === 'list') return rest === '' ? { kind: 'list' } : { kind: 'error', text: USAGE }
+  if (verb === 'add' || verb === 'set') {
+    // The name and the text are separated by whitespace; the text keeps its own.
+    const match = /^([a-z][a-z0-9_-]*)\s+([\s\S]+)$/u.exec(rest)
+    if (match === null) return { kind: 'error', text: USAGE }
+    const text = match[2].trim()
+    if (text === '') return { kind: 'error', text: USAGE }
+    return { kind: 'add', name: match[1], text }
+  }
+  if (verb === 'remove' || verb === 'rm' || verb === 'delete') {
+    if (!COMMAND_NAME.test(rest)) return { kind: 'error', text: USAGE }
+    return { kind: 'remove', name: rest }
+  }
+  return { kind: 'error', text: USAGE }
+}
+
+/**
+ * Expand one alias into the line it stands for.
+ * @param {string} text - the alias text as configured.
+ * @param {string} args - what the caller typed after the alias name, trimmed.
+ * @returns {string} the expanded text.
+ */
+export function expandAlias(text, args) {
+  const expanded = text.includes('{args}') ? text.split('{args}').join(args) : text
+  if (text.includes('{args}') || args === '') return expanded
+  return `${expanded} ${args}`
+}
+
+/**
+ * Freeze a freshly built message graph in place.
+ * @template T
+ * @param {T} value - the value to freeze, children included.
+ * @returns {T} the same value.
+ */
+function deepFreeze(value) {
+  if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.freeze(value)
+    for (const child of Object.values(value)) deepFreeze(child)
+  }
+  return value
+}
+
+/**
+ * Build the follow-up prompt one alias expands to.
+ *
+ * Mirrors `createUserMessage` from `@deepseek-ai/dsh-llm/message` (a frozen,
+ * freshly identified plain object) instead of importing the harness package:
+ * this plugin then carries no runtime dependency beyond its Config schema, and
+ * the suite runs against these sources without the harness installed. The
+ * source is deliberately not `user`, so the terse-talk deactivation watchers
+ * cannot mistake echoed text for the human's own words.
+ * @param {string} text - the prompt the alias stands for.
+ * @returns {object} a frozen user message ready for `agent.followup`.
+ */
+export function userMessage(text) {
+  return deepFreeze({
+    id: randomUUID(),
+    role: 'user',
+    content: [{ type: 'text', text }],
+    source: { kind: 'alias', form: 'relay' },
+  })
+}
+
+/**
+ * One-line rendering of an alias text for listings and descriptions.
+ * @param {string} text - the alias text as configured.
+ * @returns {string} whitespace-collapsed, bounded text.
+ */
+export function preview(text) {
+  const collapsed = text.replace(/\s+/gu, ' ').trim()
+  return collapsed.length <= PREVIEW_LIMIT
+    ? collapsed
+    : `${collapsed.slice(0, PREVIEW_LIMIT - 1)}…`
+}
+
+/**
+ * Mount the plugin.
+ * @param {object} ctx - the host context.
+ * @param {Config} config - the row's resolved configuration.
+ */
+export function apply(ctx, config) {
+  const warn = (message) => { console.warn(`[alias] ${message}`) }
+  const message = (error) => (error instanceof Error ? error.message : String(error))
+
+  /** Aliases already reported as unusable, so one bad row warns once. */
+  const reported = new Set()
+
+  /**
+   * The configured dictionary, validated field by field: a hand-edited row can
+   * name a command the registry refuses, and that must cost one warning rather
+   * than the whole plugin.
+   * @returns {Record<string, string>} name to text, invalid entries dropped.
+   */
+  const configured = () => {
+    const raw = config.aliases.get()
+    const aliases = {}
+    if (raw === null || typeof raw !== 'object') return aliases
+    for (const [aliasName, text] of Object.entries(raw)) {
+      if (!COMMAND_NAME.test(aliasName) || aliasName === ALIAS_COMMAND) {
+        if (!reported.has(aliasName)) {
+          reported.add(aliasName)
+          warn(`ignoring alias "${aliasName}": a name must match ${String(COMMAND_NAME)} and must not be "${ALIAS_COMMAND}"`)
+        }
+        continue
+      }
+      if (typeof text !== 'string' || text.trim() === '') {
+        if (!reported.has(aliasName)) {
+          reported.add(aliasName)
+          warn(`ignoring alias "${aliasName}": its text must be a non-empty string`)
+        }
+        continue
+      }
+      aliases[aliasName] = text.trim()
+    }
+    return aliases
+  }
+
+  /**
+   * Runtime aliases the settings document could not hold. They shadow the
+   * document until it carries the same value, so an alias added on a read-only
+   * deployment still works in every session until dsh restarts.
+   * @type {Map<string, string>}
+   */
+  const local = new Map()
+
+  /** @returns {Record<string, string>} the document's aliases overlaid by the runtime's. */
+  const effective = () => ({ ...configured(), ...Object.fromEntries(local) })
+
+  /** The injected `commands` scope, once the service is mounted. */
+  let commandScope
+  /**
+   * Every alias command this instance owns, by name, with the text it was
+   * registered for. `dispose` is absent when the registry refused the name
+   * (another plugin already owns it), which keeps `sync` from retrying.
+   * @type {Map<string, { text: string, dispose?: () => void }>}
+   */
+  const registered = new Map()
+
+  const entryId = () => {
+    const id = ctx.fiber?.entry?.options?.id
+    return typeof id === 'string' ? id : undefined
+  }
+  const settingsService = () => ctx.get('settings')
+
+  /**
+   * Run one alias command.
+   *
+   * The nested-expansion depth rides the async context of this call, never a
+   * shared variable: one counter for the whole plugin would count an expansion
+   * suspended elsewhere in the process as this call's own nesting and refuse a
+   * legitimate alias as a cycle.
+   * @param {string} aliasName - the alias being invoked.
+   * @param {object} invocation - the registry's command invocation.
+   * @returns {Promise<object>} the command result the UI renders.
+   */
+  const invokeAlias = async (aliasName, invocation) => {
+    const text = effective()[aliasName]
+    if (text === undefined) {
+      return { kind: 'error', text: `Alias "/${aliasName}" is no longer defined.` }
+    }
+    const line = expandAlias(text, invocation.rawInput.trim())
+
+    if (!line.startsWith('/')) {
+      // An ordinary prompt: queued as its own follow-up turn, exactly as if the
+      // caller had typed the text.
+      invocation.agent.followup(userMessage(line))
+      return { kind: 'success', text: `/${aliasName}: ${preview(line)}` }
+    }
+
+    const parsed = COMMAND_LINE.exec(line)
+    if (parsed === null || commandScope.commands.find(invocation.agent, parsed[1]) === undefined) {
+      return {
+        kind: 'error',
+        text: `Alias "/${aliasName}" stands for ${preview(line)}, which is not a command this session can run.`,
+      }
+    }
+    const depth = aliasDepth.getStore() ?? 0
+    if (depth >= MAX_DEPTH) {
+      return {
+        kind: 'error',
+        text: `Alias "/${aliasName}" expands more than ${MAX_DEPTH} levels deep; check the aliases for a cycle.`,
+      }
+    }
+    try {
+      const execution = await aliasDepth.run(
+        depth + 1,
+        () => commandScope.commands.execute(invocation.agent, line, [], invocation.signal),
+      )
+      return execution === undefined
+        ? { kind: 'error', text: `Alias "/${aliasName}" could not run ${preview(line)}.` }
+        : execution.result
+    } catch (error) {
+      return { kind: 'error', text: message(error) }
+    }
+  }
+
+  /**
+   * Register one alias command.
+   * @param {string} aliasName - command name without the slash.
+   * @param {string} text - the text it expands to.
+   * @returns {boolean} whether the registry accepted the name.
+   */
+  const registerAlias = (aliasName, text) => {
+    try {
+      const dispose = commandScope.commands.register({
+        name: aliasName,
+        description: `↪ ${preview(text)}`,
+        input: { hint: '{args}' },
+        handler: (invocation) => invokeAlias(aliasName, invocation),
+      })
+      registered.set(aliasName, { text, dispose })
+      return true
+    } catch (error) {
+      warn(`could not register "/${aliasName}": ${message(error)}`)
+      registered.set(aliasName, { text })
+      return false
+    }
+  }
+
+  /**
+   * Make the live registry match {@link effective}: drop commands whose alias
+   * is gone or whose text moved, register the rest.
+   */
+  const sync = () => {
+    if (commandScope === undefined) return
+    const aliases = effective()
+    for (const [aliasName, entry] of [...registered]) {
+      if (aliases[aliasName] === entry.text) continue
+      entry.dispose?.()
+      registered.delete(aliasName)
+    }
+    for (const [aliasName, text] of Object.entries(aliases)) {
+      if (!registered.has(aliasName)) registerAlias(aliasName, text)
+    }
+  }
+
+  /**
+   * Write one field operation through the settings document.
+   * @param {Array<{ op: 'set' | 'unset', path: string[], value?: string }>} ops - the edit.
+   * @returns {Promise<boolean>} whether the document accepted the write.
+   */
+  const persist = async (ops) => {
+    const settings = settingsService()
+    const id = entryId()
+    if (settings === undefined || id === undefined) return false
+    try {
+      await settings.mutate(id, ops)
+      return true
+    } catch (error) {
+      warn(`settings write refused: ${message(error)}`)
+      return false
+    }
+  }
+
+  /**
+   * `/alias add <name> <text>`.
+   * @param {string} aliasName - command name without the slash.
+   * @param {string} text - the text it expands to.
+   * @returns {Promise<object>} the command result.
+   */
+  const addAlias = async (aliasName, text) => {
+    const previous = effective()[aliasName]
+    // The runtime overlay lands first, so the alias works on this turn
+    // even when the document refuses the write.
+    local.set(aliasName, text)
+    sync()
+    if (registered.get(aliasName)?.dispose === undefined) {
+      local.delete(aliasName)
+      sync()
+      return { kind: 'error', text: `"/${aliasName}" is already a registered command; pick another name.` }
+    }
+    if (!await persist([{ op: 'set', path: ['aliases', aliasName], value: text }])) {
+      return {
+        kind: 'success',
+        text: `/${aliasName} is set until dsh restarts: the settings document did not accept the write.`,
+      }
+    }
+    if (local.get(aliasName) === text) local.delete(aliasName) // leave any newer edit intact
+    return {
+      kind: 'success',
+      text: previous === undefined
+        ? `/${aliasName} now stands for: ${preview(text)}`
+        : `/${aliasName} updated to: ${preview(text)}`,
+    }
+  }
+
+  /**
+   * `/alias remove <name>`.
+   * @param {string} aliasName - command name without the slash.
+   * @returns {Promise<object>} the command result.
+   */
+  const removeAlias = async (aliasName) => {
+    if (!Object.hasOwn(effective(), aliasName)) {
+      return { kind: 'error', text: `Unknown alias "/${aliasName}".` }
+    }
+    local.delete(aliasName)
+    const persisted = await persist([{ op: 'unset', path: ['aliases', aliasName] }])
+    sync()
+    if (Object.hasOwn(effective(), aliasName)) {
+      return {
+        kind: 'error',
+        text: local.has(aliasName)
+          ? `/${aliasName} changed while it was being removed; the newer alias remains.`
+          : persisted
+            ? `/${aliasName} comes from the profile's composition layer; remove it there.`
+            : `/${aliasName} could not be removed: the settings document did not accept the write.`,
+      }
+    }
+    return {
+      kind: 'success',
+      text: persisted
+        ? `Removed /${aliasName}.`
+        : `Removed /${aliasName} until dsh restarts: the settings document did not accept the write.`,
+    }
+  }
+
+  /**
+   * `/alias list`.
+   * @returns {object} the command result.
+   */
+  const listAliases = () => {
+    const aliases = effective()
+    const names = Object.keys(aliases).sort()
+    if (names.length === 0) {
+      return { kind: 'success', text: `No aliases defined. Add one with /alias add <name> <text>.` }
+    }
+    const lines = names.map((aliasName) => `  /${aliasName}  ${preview(aliases[aliasName])}`)
+    return { kind: 'success', text: [`Aliases (${names.length}):`, ...lines].join('\n') }
+  }
+
+  /**
+   * `/alias …`.
+   * @param {object} invocation - the registry's command invocation.
+   * @returns {Promise<object>} the command result.
+   */
+  const handleAlias = async (invocation) => {
+    const parsed = parseAliasInput(invocation.rawInput)
+    if (parsed.kind === 'error') return { kind: 'error', text: parsed.text }
+    if (parsed.kind === 'list') return listAliases()
+    if (parsed.kind === 'add') return addAlias(parsed.name, parsed.text)
+    return removeAlias(parsed.name)
+  }
+
+  // The document is authoritative once it moves: a runtime alias the
+  // write did land is dropped, and everything is re-registered from scratch.
+  ctx.on('loader/volatile-update', () => {
+    for (const [aliasName, text] of [...local]) {
+      if (configured()[aliasName] === text) local.delete(aliasName)
+    }
+    sync()
+  })
+
+  ctx.inject(['commands'], (scope) => {
+    commandScope = scope
+    scope.commands.register({
+      name: ALIAS_COMMAND,
+      description: '⇄ Define slash-command aliases: /alias add <name> <text>, /alias remove <name>, /alias list',
+      input: { hint: 'add <name> <text> | remove <name> | list' },
+      handler: handleAlias,
+    })
+    sync()
+    scope.effect(() => () => {
+      for (const entry of registered.values()) entry.dispose?.()
+      registered.clear()
+      commandScope = undefined
+    }, 'dsh-alias: alias commands')
+  })
+}

package/lib/client.js

@@ -0,0 +1,346 @@
+/**
+ * dsh-alias: browser half.
+ *
+ * One surface: the Alias card on the Plugins page, keyed on the `alias`
+ * settings namespace the host half declares as its row id. It lists every
+ * defined alias with a Remove control and adds one through a name + text pair;
+ * every write goes through `ctx.configForms`, the same settings document
+ * `/alias` writes on the host, so the two surfaces cannot disagree.
+ *
+ * Chrome is a stylesheet, not inline style objects: the module system claims
+ * every `<style>` tag a factory appends while it materializes and removes it
+ * when the package unloads, so the tags cost nothing to own. All classes are
+ * `da-`-prefixed because that sheet lands in the page's own document.
+ *
+ * This file is plain JavaScript on purpose. The client module system serves a
+ * package's `exports["./client"]` artifact as a lazy-CJS factory registered on
+ * `window.__ModuleLoader__`, and that is the whole format: an out-of-tree
+ * plugin can author it directly instead of reproducing the repository's tsdown
+ * client preset. `react` is provided by the module system; nothing else is
+ * required here.
+ *
+ * The card mirrors the shipped plugin cards: the page draws the title, icon,
+ * and breadcrumb, and the entry renders the body (`view: 'page'`) or the
+ * one-liner under the title (`view: 'summary'`).
+ */
+
+window.__ModuleLoader__.load({
+  id: '@maci0/dsh-alias',
+
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+
+    const React = require('react')
+
+    /** Settings namespace shared with the host half; also this card's slot key. */
+    const NAMESPACE = 'alias'
+
+    /** Locale namespace for this plugin's copy. */
+    const LOCALE_NS = 'alias'
+
+    /** The names the command registry accepts, mirroring the host half. */
+    const COMMAND_NAME = /^[a-z][a-z0-9_-]*$/u
+
+    /** Every class is `da-`-prefixed: the sheet lands in the page's own document. */
+    const CSS = [
+      '.da-page{display:flex;flex-direction:column;gap:12px}',
+      '.da-group{display:flex;flex-direction:column;gap:8px}',
+      '.da-label{font-size:12px;line-height:1.5;color:var(--dsw-alias-label-tertiary)}',
+      '.da-list{display:flex;flex-direction:column;gap:6px;margin:0;padding:0;list-style:none}',
+      '.da-item{display:flex;align-items:flex-start;gap:10px;padding:8px 10px;border:1px solid var(--dsw-alias-border-l2);border-radius:10px;background:var(--dsw-alias-bg-layer-4)}',
+      '.da-item-main{flex:1;min-width:0;display:flex;flex-direction:column;gap:2px}',
+      '.da-name{font-size:13px;font-weight:600;line-height:1.5;color:var(--dsw-alias-label-primary)}',
+      '.da-text{font-size:13px;line-height:1.5;color:var(--dsw-alias-label-secondary);white-space:pre-wrap;overflow-wrap:anywhere}',
+      '.da-row{display:flex;flex-wrap:wrap;gap:8px}',
+      '.da-input{font:inherit;font-size:13px;line-height:1.5;padding:5px 12px;color:var(--dsw-alias-label-primary);background:var(--dsw-alias-bg-layer-4);border:1px solid var(--dsw-alias-border-l2);border-radius:8px;box-sizing:border-box}',
+      '.da-input:disabled{cursor:default;opacity:.5}',
+      '.da-input-name{width:160px;flex:none}',
+      '.da-input-text{flex:1;min-width:200px}',
+      '.da-button{appearance:none;font:inherit;font-size:13px;line-height:1.5;padding:5px 14px;cursor:pointer;color:var(--dsw-alias-label-primary);background:var(--dsw-alias-bg-layer-4);border:1px solid var(--dsw-alias-border-l2);border-radius:8px}',
+      '.da-button:disabled{cursor:default;opacity:.5}',
+      '.da-button-remove{flex:none;padding:3px 10px;font-size:12px;color:var(--dsw-alias-label-secondary)}',
+      '.da-status{font-size:12px;line-height:1.5;color:var(--dsw-alias-label-tertiary)}',
+      '.da-error{font-size:12px;line-height:1.5;color:var(--dsw-alias-label-error)}',
+    ].join('')
+
+    // Appended while the factory materializes: the module system claims the tag
+    // for this package and disposes it on unload. Guarded because the node unit
+    // tests evaluate this file without a DOM.
+    if (typeof document !== 'undefined') {
+      const style = document.createElement('style')
+      style.textContent = CSS
+      document.head.append(style)
+    }
+
+    /** Plugin version, shown in the card header. Kept in lockstep with package.json. */
+    const VERSION = '0.5.2'
+
+    const en = {
+      title: 'Alias',
+      summaryEmpty: 'No aliases defined.',
+      summary: '{count} alias(es) defined.',
+      groupExisting: 'Defined aliases',
+      groupNew: 'Add an alias',
+      namePlaceholder: 'name',
+      textPlaceholder: 'text it stands for ({args} optional)',
+      add: 'Add',
+      update: 'Update',
+      edit: 'Edit',
+      remove: 'Remove',
+      empty: 'No aliases yet. Add one below, or run /alias add <name> <text>.',
+      badName: 'A name is lowercase letters, digits, `_` or `-`, and must start with a letter.',
+      emptyText: 'The alias text must not be empty.',
+      persists: 'Saved to your profile; /alias lists the same set.',
+      readOnly: 'Read-only: this deployment does not persist settings, so changes apply to this page only.',
+      refused: 'The settings document refused the change.',
+      version: 'v{version}',
+    }
+
+    const zh = {
+      title: '别名',
+      summaryEmpty: '未定义别名。',
+      summary: '已定义 {count} 个别名。',
+      groupExisting: '已定义的别名',
+      groupNew: '添加别名',
+      namePlaceholder: '名称',
+      textPlaceholder: '它代表的文本（可用 {args}）',
+      add: '添加',
+      update: '更新',
+      edit: '编辑',
+      remove: '删除',
+      empty: '还没有别名。在下面添加，或运行 /alias add <name> <text>。',
+      badName: '名称只能是小写字母、数字、`_` 或 `-`，且必须以字母开头。',
+      emptyText: '别名文本不能为空。',
+      persists: '已保存到你的配置；/alias 列出同一组别名。',
+      readOnly: '只读：此部署不持久化设置，改动仅对本页面生效。',
+      refused: '设置文档拒绝了此改动。',
+      version: 'v{version}',
+    }
+
+    /**
+     * Bind one settings scope to a React subscription.
+     * @param scope - the scope bound to the alias settings namespace.
+     * @returns a hook reading that scope's current snapshot.
+     */
+    function useScope(scope) {
+      const subscribe = (listener) => scope.subscribe(listener)
+      const getSnapshot = () => scope.getSnapshot()
+      return () => React.useSyncExternalStore(subscribe, getSnapshot)
+    }
+
+    /**
+     * Read a snapshot's alias dictionary. A namespace this deployment does not
+     * serve reports no dictionary, which the card renders as nothing at all.
+     * @param snapshot - the settings scope snapshot.
+     * @returns name-to-text, or `undefined` when unreadable.
+     */
+    function aliasesOf(snapshot) {
+      if (snapshot.status !== 'ready') return undefined
+      const value = snapshot.value !== null && typeof snapshot.value === 'object' ? snapshot.value : {}
+      const aliases = value.aliases
+      if (aliases === null || typeof aliases !== 'object' || Array.isArray(aliases)) return {}
+      return aliases
+    }
+
+    /**
+     * One alias row: the name, its text, and the Edit and Remove controls.
+     *
+     * Edit loads the row into the form below, because a list whose entries can
+     * only be deleted is a list users re-type from scratch.
+     */
+    function AliasRow(props) {
+      const { t, name, text, disabled, onRemove, onEdit } = props
+      return React.createElement(
+        'li',
+        { className: 'da-item' },
+        React.createElement(
+          'div',
+          { className: 'da-item-main' },
+          React.createElement('span', { className: 'da-name' }, `/${name}`),
+          React.createElement('span', { className: 'da-text' }, text),
+        ),
+        React.createElement(
+          'button',
+          {
+            type: 'button',
+            className: 'da-button da-button-remove',
+            disabled,
+            onClick: () => { onEdit(name, text) },
+          },
+          t('edit'),
+        ),
+        React.createElement(
+          'button',
+          {
+            type: 'button',
+            className: 'da-button da-button-remove',
+            disabled,
+            onClick: () => { onRemove(name) },
+          },
+          t('remove'),
+        ),
+      )
+    }
+
+    /**
+     * Build the card component over one bound settings scope.
+     * @param scope - the scope bound to the alias settings namespace.
+     * @param t - translate function bound to this plugin's locale namespace.
+     * @returns the component the slot renders.
+     */
+    function createCard(scope, t) {
+      const useAlias = useScope(scope)
+
+      return function AliasCard(props) {
+        const snapshot = useAlias()
+        const [error, setError] = React.useState(null)
+        const [draftName, setDraftName] = React.useState('')
+        const [draftText, setDraftText] = React.useState('')
+        const [pending, setPending] = React.useState(false)
+
+        const aliases = aliasesOf(snapshot)
+        // A namespace this deployment does not serve renders no trace of itself.
+        if (aliases === undefined) return null
+
+        const names = Object.keys(aliases).sort()
+        if (props != null && props.view === 'summary') {
+          return names.length === 0 ? t('summaryEmpty') : t('summary', { count: String(names.length) })
+        }
+
+        const disabled = !snapshot.writable || pending
+        // `mutate` resolves `false` when the host refuses the write (an overlay
+        // row, a revision conflict), so a refusal is reported here, not thrown.
+        const write = (ops, onAccepted) => {
+          if (disabled) return
+          setError(null)
+          setPending(true)
+          new Promise((resolve) => { resolve(scope.mutate(ops)) }).then((accepted) => {
+            if (accepted === false) setError(t('refused'))
+            else onAccepted?.()
+          }).catch((cause) => {
+            setError(cause instanceof Error ? cause.message : String(cause))
+          }).finally(() => { setPending(false) })
+        }
+        const edit = (name, text) => {
+          setError(null)
+          setDraftName(name)
+          setDraftText(text)
+        }
+        const remove = (name) => {
+          write([{ op: 'unset', path: ['aliases', name] }])
+        }
+        const add = () => {
+          const name = draftName.trim().toLowerCase()
+          const text = draftText.trim()
+          if (!COMMAND_NAME.test(name)) {
+            setError(t('badName'))
+            return
+          }
+          if (text === '') {
+            setError(t('emptyText'))
+            return
+          }
+          write([{ op: 'set', path: ['aliases', name], value: text }], () => {
+            setDraftName('')
+            setDraftText('')
+          })
+        }
+
+        return React.createElement(
+          'div',
+          { className: 'da-page' },
+          React.createElement(
+            'div',
+            { className: 'da-group' },
+            React.createElement('span', { className: 'da-label' }, t('groupExisting')),
+            names.length === 0
+              ? React.createElement('span', { className: 'da-status' }, t('empty'))
+              : React.createElement(
+                'ul',
+                { className: 'da-list' },
+                names.map((name) => React.createElement(AliasRow, {
+                  key: name, t, name, text: aliases[name], disabled, onRemove: remove, onEdit: edit,
+                })),
+              ),
+          ),
+          React.createElement(
+            'div',
+            { className: 'da-group' },
+            React.createElement('span', { className: 'da-label' }, t('groupNew')),
+            React.createElement(
+              'div',
+              { className: 'da-row' },
+              React.createElement('input', {
+                className: 'da-input da-input-name',
+                type: 'text',
+                value: draftName,
+                placeholder: t('namePlaceholder'),
+                'aria-label': t('namePlaceholder'),
+                disabled,
+                onChange: (event) => { setDraftName(event.target.value) },
+              }),
+              React.createElement('input', {
+                className: 'da-input da-input-text',
+                type: 'text',
+                value: draftText,
+                placeholder: t('textPlaceholder'),
+                'aria-label': t('textPlaceholder'),
+                disabled,
+                onChange: (event) => { setDraftText(event.target.value) },
+                onKeyDown: (event) => {
+                  if (event.key === 'Enter') add()
+                },
+              }),
+              React.createElement(
+                'button',
+                { type: 'button', className: 'da-button', disabled, onClick: add },
+                // The same write serves both: `set` on an existing name is an
+                // update, and saying so is the whole difference.
+                Object.hasOwn(aliases, draftName.trim().toLowerCase()) ? t('update') : t('add'),
+              ),
+            ),
+          ),
+          React.createElement(
+            'div',
+            { className: 'da-status' },
+            snapshot.writable ? t('persists') : t('readOnly'),
+            ' ',
+            t('version', { version: VERSION }),
+          ),
+          error === null ? null : React.createElement('div', { className: 'da-error' }, error),
+        )
+      }
+    }
+
+    /**
+     * Mount the browser surface: the Alias card on the Plugins page.
+     * @param ctx - the browser plugin context.
+     */
+    function apply(ctx) {
+      const t = ctx.locale.bind(LOCALE_NS)
+      ctx.effect(
+        () => ctx.locale.register(LOCALE_NS, { en, zh }),
+        'dsh-alias: locale dictionary',
+      )
+
+      const scope = ctx.configForms.get(NAMESPACE)
+      const Card = createCard(scope, t)
+
+      // The owner declares its own slot; injecting waits for it to exist, so
+      // this registration does not depend on plugin load order. The card takes
+      // no injected props (it closes over its own bound scope), so the entry
+      // declares the documented `locale` namespace and no `inject`.
+      ctx.slots.inject('plugins.row.config', () => ctx.slots.register({
+        name: 'plugins.row.config',
+        key: '@maci0/dsh-alias#alias',
+        locale: LOCALE_NS,
+      }, Card))
+    }
+
+    exports.apply = apply
+    exports.inject = ['slots', 'configForms', 'locale']
+    return module.exports
+  },
+})

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Alias",
+    "description": "Define your own slash commands with /alias, or from the Alias card on the Plugins page."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "别名",
+    "description": "用 /alias 或 Plugins 页面的「别名」卡片定义自己的斜杠命令。"
+  }
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@maci0/dsh-alias",
+  "version": "0.5.2",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "index.js",
+  "description": "/alias add|remove|list for DeepSeek Harness: define your own slash commands, persisted in settings, with a configuration card on the Plugins page.",
+  "license": "MIT",
+  "exports": {
+    ".": "./index.js",
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./locale/*.json": "./locale/*.json",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-plugin-manager"
+      ]
+    },
+    "compatibility": {
+      "dsh": ">=0.2.0-rc.2 <0.3.0"
+    }
+  },
+  "files": [
+    "icon.svg",
+    "locale/*.json",
+    "index.js",
+    "lib/client.js",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:node": "node --test tests/*.test.*"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.5-alpha.1",
+    "@deepseek-ai/cosmokit": "~1.8.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/maci0/dsh-alias.git"
+  },
+  "icon": "./icon.svg",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.4"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.0.5-alpha.1"
+  }
+}