dsh-output-styles 0.2.0

package/src/client/index.ts

@@ -0,0 +1,104 @@
+/**
+ * Browser half of `dsh-output-styles`: a popup picker decorating the HOST
+ * `/style` command. The picker reads the `style` session projection
+ * (`{ options, currentValue }`), which the host plugin keeps fresh, and
+ * submits the completed `/style <name>` / `/style off` line back through the
+ * command Remote — so every switch keeps the host's durable command
+ * lifecycle (`command/run`/`command/done`) and the projection stays the
+ * single displayed fact.
+ * @module dsh-output-styles/client
+ */
+
+import type { ClientContext, ISessions } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-api-remotes/client'
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+import type { CommandUiContract, SelectOption } from '@deepseek-ai/dsh-client-ui-commands/client'
+import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
+import type { StyleSelectionView } from '../types.ts'
+import { en, zh, type StyleKey } from './locales.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    /** The style picker's copy. */
+    style: StyleKey
+  }
+}
+
+/** Client plugin name; keep stable after publishing. */
+export const name = 'dsh-output-styles-client'
+
+/** Required client services: the command surface, the sessions face, the command Remote, and locale. */
+export const inject = ['commandUi', 'locale', 'remote', 'sessions']
+
+/** Dictionary namespace owned by this plugin. */
+const NS = 'style'
+
+/** The picker row that restores the project default; stable, never a style name. */
+const OFF_ID = 'off'
+
+/** Flatten the projection into picker rows: the off row first, then one row per style. */
+function optionsOf(view: StyleSelectionView, t: TranslateNS<typeof NS>): SelectOption[] {
+  const rows: SelectOption[] = [{
+    id: OFF_ID,
+    label: t('option.off'),
+    detail: t('option.offDetail'),
+    active: view.currentValue === null,
+  }]
+  for (const option of view.options) {
+    rows.push({
+      id: option.value,
+      label: option.name,
+      detail: option.whenToUse !== undefined
+        ? `${option.description} · ${option.whenToUse}`
+        : option.description,
+      active: view.currentValue === option.value,
+    })
+  }
+  return rows
+}
+
+/**
+ * Client plugin body: register the `style` dictionaries and decorate the
+ * host `/style` command's bare invocation with the projection-backed picker.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'dsh-output-styles: style dictionaries')
+  const t = ctx.locale.bind(NS)
+
+  ctx.inject(['commandUi', 'remote', 'sessions'], (scope: ClientContext) => {
+    const commandUi = scope.get('commandUi') as CommandUiContract
+    // The host graph (`dsh-session`) and the client graph (`dsh-client-runtime`)
+    // both declare a `sessions` service on Context; this package compiles
+    // against both faces, so the runtime value is the client service named
+    // 'sessions' and the host type is what the merged declaration resolves.
+    const sessions = scope.get('sessions') as unknown as ISessions
+    const remote = scope.remote
+
+    scope.effect(() => commandUi.decorate({
+      name: 'style',
+      available: () => true,
+      ui: {
+        kind: 'popupSelect',
+        options: async (session) => {
+          const binding = sessions.binding(session.sessionId)
+          const view = binding?.session.projections.faceOf('style').getSnapshot() as StyleSelectionView | undefined
+          if (view === undefined) return []
+          return optionsOf(view, t)
+        },
+        onSelect: async (option, session) => {
+          const line = option.id === OFF_ID ? '/style off' : `/style ${option.id}`
+          const result = await remote.commands.execute(session.sessionId, line)
+          if (!result.ok) {
+            throw new Error(`command.execute failed: ${result.error.code}: ${result.error.message}`)
+          }
+          if (result.value === undefined) {
+            throw new Error(`unknown or malformed command: ${line}`)
+          }
+        },
+      },
+    }), 'dsh-output-styles: /style picker')
+  })
+}
+
+export type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'

package/src/client/locales.ts

@@ -0,0 +1,14 @@
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export const zh = {
+  'option.off': '关闭（默认）',
+  'option.offDetail': '恢复项目默认输出风格',
+} satisfies Record<string, string>
+
+/** The style picker namespace key union. */
+export type StyleKey = keyof typeof zh
+
+/** English dictionary, checked complete against the zh key set. */
+export const en = {
+  'option.off': 'Off (default)',
+  'option.offDetail': 'Restore the project default output style',
+} satisfies Record<StyleKey, string>

package/src/config.ts

@@ -0,0 +1,110 @@
+/**
+ * Serializable configuration, schema, and direct-call defaults.
+ *
+ * Every tunable lives here: a deployment changes behavior through
+ * `cordis.yml`, never by editing source. The schema is validated by the
+ * harness Loader while the plugin loads; invalid configuration fails the
+ * load with an actionable error.
+ * @module dsh-output-styles/config
+ */
+
+import z from '@deepseek-ai/schemastery'
+import { resolve } from 'node:path'
+
+/** Plugin configuration supplied by the profile composition. */
+export interface Config {
+  /**
+   * Directories holding the style library (`*.md`, and with {@link Config.compatJson}
+   * also `*.json`). Each entry resolves against the process working directory.
+   * Later directories override earlier ones on a same-named style; the bundled
+   * `styles/` directory participates as the lowest-priority entry unless
+   * {@link Config.includeBuiltins} is false. An empty list means the bundled
+   * library only (or none, with `includeBuiltins: false`). A bare string is
+   * accepted as a single-directory list.
+   */
+  stylesDir?: string | string[]
+  /** Style-body budget in characters; longer bodies are truncated at the budget with a marker. */
+  maxStyleChars?: number
+  /**
+   * Style injected into sessions that never selected one (and no project
+   * settings default exists). The empty string (default) means new sessions
+   * get no style — the session's own selection, made through `/style`, is
+   * always what wins for a session that has one.
+   */
+  defaultStyle?: string
+  /** Load Claude Code `outputStyles` JSON entries (`{ name, description, prompt }`) beside Markdown styles. */
+  compatJson?: boolean
+  /** Order of the injected system-prompt section (90: after the persona, before tool guidance at 100–199). */
+  sectionOrder?: number
+  /** Marker appended at the truncation point when a style body exceeds {@link Config.maxStyleChars}. */
+  truncationMarker?: string
+  /** Include the package's bundled `styles/` directory in the library. */
+  includeBuiltins?: boolean
+  /** Reload the library when a style file changes on disk (default true). */
+  watchStyles?: boolean
+}
+
+/** Configuration after defaults have been resolved. */
+export interface ResolvedConfig {
+  /** Absolute style-library directories, lowest priority first (bundled styles first when included). */
+  stylesDirs: string[]
+  /** Style-body budget in characters; at least 1. */
+  maxStyleChars: number
+  /** Style injected into sessions that never selected one; `''` means none. */
+  defaultStyle: string
+  /** Whether Claude Code `outputStyles` JSON entries are loaded. */
+  compatJson: boolean
+  /** Order of the injected system-prompt section; a finite number. */
+  sectionOrder: number
+  /** Marker appended at the truncation point. */
+  truncationMarker: string
+  /** Whether the bundled `styles/` directory participates. */
+  includeBuiltins: boolean
+  /** Whether the library reloads on style-file changes. */
+  watchStyles: boolean
+}
+
+/** Loader-visible configuration schema and defaults. */
+export const Config: z<Config> = z.object({
+  stylesDir: z.union([z.string(), z.array(z.string())]).default([]),
+  maxStyleChars: z.number().min(1).default(4000),
+  defaultStyle: z.string().default(''),
+  compatJson: z.boolean().default(true),
+  sectionOrder: z.number().default(90),
+  truncationMarker: z.string().default('\n\n[style truncated]'),
+  includeBuiltins: z.boolean().default(true),
+  watchStyles: z.boolean().default(true),
+})
+
+/**
+ * Resolve the same defaults for direct callers that bypass the Cordis Loader,
+ * and fail loud on values the schema cannot express (a non-finite section
+ * order).
+ * @param config - Partial serialized configuration.
+ * @param defaultStylesDir - Absolute bundled directory used when built-ins are included.
+ * @returns Configuration with every default applied.
+ */
+export function resolveConfig(config: Config, defaultStylesDir: string): ResolvedConfig {
+  const maxStyleChars = config.maxStyleChars ?? 4000
+  if (!Number.isFinite(maxStyleChars) || maxStyleChars < 1) {
+    throw new Error(`dsh-output-styles: maxStyleChars must be a finite number ≥ 1, got ${String(config.maxStyleChars)}`)
+  }
+  const sectionOrder = config.sectionOrder ?? 90
+  if (!Number.isFinite(sectionOrder)) {
+    throw new Error(`dsh-output-styles: sectionOrder must be a finite number, got ${String(config.sectionOrder)}`)
+  }
+  const includeBuiltins = config.includeBuiltins ?? true
+  const rawDirs = Array.isArray(config.stylesDir) ? config.stylesDir : config.stylesDir === undefined || config.stylesDir === '' ? [] : [config.stylesDir]
+  const customDirs = rawDirs.map(dir => resolve(dir))
+  const stylesDirs = includeBuiltins ? [defaultStylesDir, ...customDirs] : customDirs
+  return {
+    stylesDirs,
+    maxStyleChars,
+    defaultStyle: config.defaultStyle ?? '',
+    compatJson: config.compatJson ?? true,
+    sectionOrder,
+    truncationMarker: config.truncationMarker ?? '\n\n[style truncated]',
+    includeBuiltins,
+    watchStyles: config.watchStyles ?? true,
+  }
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * `dsh-output-styles`: Claude Code `outputStyles`-equivalent runtime output
+ * styles for DeepSeek Harness. The plugin registers a model-visible system
+ * prompt section that injects the current session's style body, a `/style`
+ * slash command that switches it, per-session persistence over the
+ * `output_style` storage domain, and the `style` session projection.
+ * @module dsh-output-styles
+ */
+
+/** Cordis plugin name; keep this stable after publishing. */
+export const name = 'dsh-output-styles'
+
+/**
+ * Services that must exist before the plugin applies: the prompt-assembly
+ * registry for the injected section, and the storage domain facility for
+ * per-session persistence. A composition without a routed kv backend keeps
+ * the plugin pending until the storage rows appear (Cordis dependency
+ * semantics), instead of racing a parallel mount.
+ */
+export const inject = ['systemPrompt', 'storageDomain']
+
+export { Config, resolveConfig } from './config.ts'
+export type { ResolvedConfig } from './config.ts'
+export { apply, DEFAULT_STYLES_DIR, OutputStyleRuntime, STYLE_SECTION_NAME } from './runtime.ts'
+export {
+  applyStyleEvent,
+  EMPTY_STYLE_STATE,
+  parseStyleInput,
+  STYLE_COMMAND,
+} from './style-command.ts'
+export type { StyleFoldState, StyleInput } from './style-command.ts'
+export {
+  isValidStyleName,
+  loadStyleLibrary,
+  STYLE_NAME_RE,
+  truncateStyle,
+} from './style-library.ts'
+export type { OutputStyle } from './style-library.ts'
+export {
+  OFF,
+  OUTPUT_STYLE_DOMAIN,
+  STYLE_SOURCE,
+  styleSelectionSchema,
+  styleSelectionViewSchema,
+} from './types.ts'
+export type { StyleOption, StyleSelection, StyleSelectionView } from './types.ts'
+export { installInvariant, PACKAGE_NAME } from './invariant.ts'
+export type { InvariantFacts, InvariantInstaller, InvariantRegistry } from './invariant.ts'
+// Type-only re-export: keeps the `style` SessionProjectionMap merge edge in
+// the emitted index.d.ts, so consumers receive the projection key's type.
+export type * from './types.ts'

package/src/invariant.ts

@@ -0,0 +1,144 @@
+/**
+ * Package-owned invariant companion for `dsh-output-styles`.
+ *
+ * Two post-commit diagnostic checks over the events this plugin's write path
+ * produces (both target events are committed before dispatch, so a violation
+ * is reported — via the host registry's `fail` — rather than vetoed):
+ *
+ * 1. Every `output_style`/`selection` durable write carries this plugin's own
+ *    source marker and a legal style name; when the library is known,
+ *    the name must be a library member.
+ * 2. A successful `/style <name>` command has a matching selection record on
+ *    its session by the time its `command/done` settles, and `/style off`
+ *    leaves no record. The standalone companion (no library/domain handle)
+ *    skips this check.
+ *
+ * The main plugin registers a facts-bearing installer from its own context;
+ * the `./invariant` export is the standalone companion usable through a
+ * separate profile row.
+ * @module dsh-output-styles/invariant
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-commands'
+import type { DomainChanged } from '@deepseek-ai/dsh-storage-domain'
+import { parseStyleInput, STYLE_COMMAND } from './style-command.ts'
+import { isValidStyleName } from './style-library.ts'
+import { OFF, STYLE_SOURCE } from './types.ts'
+
+/** Full npm package name owning the reported failures. */
+export const PACKAGE_NAME = 'dsh-output-styles'
+
+/** A package-attributed invariant failure reported by the host registry. */
+export type InvariantFailure = (message: string) => never
+
+/** Facts the installer needs beyond the event stream. */
+export interface InvariantFacts {
+  /** Library style names, or undefined when the companion has no library handle. */
+  knownStyles(): ReadonlySet<string> | undefined
+  /** One session's durable selection record; absent disables the pairing check. */
+  selectionFor?(sessionId: SessionId): { style: string } | undefined
+}
+
+/** Installer callback accepted by the host's invariant registry. */
+export type InvariantInstaller = (ctx: Context, fail: InvariantFailure) => void | Promise<void>
+
+/** Minimal runtime contract used by the companion without a source checkout. */
+export interface InvariantRegistry {
+  register(packageName: string, installer: InvariantInstaller): () => void
+}
+
+/** Cordis companion plugin name. */
+export const name = 'dsh-output-styles-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** Facts for the standalone companion: envelope checks only, no library/domain handle. */
+const COMPANION_FACTS: InvariantFacts = {
+  knownStyles: () => undefined,
+}
+
+/** One `/style` command run awaiting its `command/done`. */
+interface PendingSwitch {
+  session: Session
+  expected: { name: string } | { off: true }
+}
+
+/**
+ * Build the installer over a facts source. The standalone companion and the
+ * main plugin share this body; only the facts differ.
+ * @param facts - library and domain access for the checks.
+ * @returns the installer the host registry activates in its child context.
+ */
+export function installInvariant(facts: InvariantFacts): InvariantInstaller {
+  return (ctx, fail) => {
+    const pending = new Map<string, PendingSwitch>()
+
+    ctx.on('domain/changed', (change: DomainChanged) => {
+      if (change.domain !== 'output_style' || change.table !== 'selection' || change.operation !== 'put') return
+      const value = change.value as { style?: unknown; source?: unknown }
+      if (typeof value.style !== 'string' || !isValidStyleName(value.style)) {
+        fail(`selection record names invalid style ${JSON.stringify(value.style)}`)
+      }
+      if (JSON.stringify(value.source) !== JSON.stringify(STYLE_SOURCE)) {
+        fail(`selection record source is ${JSON.stringify(value.source)}; expected this plugin's own marker`)
+      }
+      const known = facts.knownStyles()
+      if (known !== undefined && typeof value.style === 'string' && !known.has(value.style)) {
+        fail(`selection record names style "${value.style}" that is not in the style library`)
+      }
+    })
+
+    ctx.on('session/event', (session: Session, event: SessionEvent) => {
+      if (event.type === 'command/run'
+        && event.data.name === STYLE_COMMAND
+        && event.data.args !== undefined) {
+        const input = parseStyleInput(event.data.args)
+        if (input.kind === 'off') {
+          pending.set(String(event.data.commandId), { session, expected: { off: true } })
+        } else if (input.kind === 'switch') {
+          pending.set(String(event.data.commandId), { session, expected: { name: input.name } })
+        }
+        return
+      }
+      if (event.type !== 'command/done') return
+      const entry = pending.get(String(event.data.commandId))
+      if (entry === undefined) return
+      pending.delete(String(event.data.commandId))
+      if (event.data.kind !== 'success' || facts.selectionFor === undefined) return
+      const record = facts.selectionFor(entry.session.id)
+      if ('off' in entry.expected) {
+        if (record !== undefined) {
+          fail(`/style ${OFF} settled on session "${entry.session.id}" but its selection record still exists`)
+        }
+      } else if (record === undefined || record.style !== entry.expected.name) {
+        fail(`/style ${entry.expected.name} settled on session "${entry.session.id}" without a matching selection record`)
+      }
+    }, { global: true })
+  }
+}
+
+/**
+ * Resolve the host registry through Cordis's named service lookup. Keeping
+ * this narrow local contract lets the companion build without host source
+ * files; a composed DSH profile still supplies the real `invariants` service.
+ * @param ctx - Cordis context carrying the host service.
+ * @returns the host invariant registry.
+ * @throws {Error} when the companion is loaded without its host service.
+ */
+function getInvariantRegistry(ctx: Context): InvariantRegistry {
+  const registry = ctx.get('invariants') as InvariantRegistry | undefined
+  if (registry === undefined) {
+    throw new Error(`invariant companion requires the "invariants" service for ${PACKAGE_NAME}`)
+  }
+  return registry
+}
+
+/**
+ * Register the standalone companion with envelope-only facts.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(getInvariantRegistry(ctx).register(PACKAGE_NAME, installInvariant(COMPANION_FACTS)))