dsh-baize-rules 0.1.0

package/src/rules.ts

@@ -0,0 +1,116 @@
+/**
+ * User-set rule data model, scope reconciliation, and the model-visible
+ * rendering shared by the pre-step injection and the /rules command.
+ *
+ * @module @deepseek-ai/dsh-rules/rules
+ */
+
+export type RuleScope = 'global' | 'session' | 'project'
+
+/** One user requirement. Rules are plain text — the must-do / must-not intent is
+ *  expressed in the text itself (e.g. "用中文写注释" vs "不要改测试"), so there is
+ *  no separate kind tag. */
+export interface Rule {
+  /** Stable id minted once; the /rules command addresses rules by it. */
+  readonly id: string
+  readonly text: string
+  /** A rule may be temporarily paused without being deleted. */
+  readonly enabled: boolean
+  readonly createdAt: number
+  readonly updatedAt: number
+}
+
+/** Ordered, deduplicated rule sets per scope for a single session view. */
+export interface RuleView {
+  readonly global: readonly Rule[]
+  readonly session: readonly Rule[]
+  readonly project?: readonly Rule[]
+}
+
+/** Concatenate global then session rules, honoring scope precedence. */
+export function activeRules(view: RuleView): readonly Rule[] {
+  return [...view.global, ...view.session].filter(rule => rule.enabled)
+}
+
+/** Escape literal closing tags so user text cannot close the plugin frame. */
+export function escapeReminder(text: string): string {
+  return text.replace(/<\/(?:system-reminder)\s*>/gi, '<\\/system-reminder>')
+}
+
+/** Enforce the configured byte budget by keeping the *prefix* (up to `budgetBytes`
+ *  UTF-8 bytes) and dropping the tail. Precedence is thus decided by callers:
+ *  {@link renderRules} lays the most specific section first, so a tight budget
+ *  sheds the broadest (global) rules before any specific (session/project) rule. */
+export function enforceBudget(
+  lines: readonly string[],
+  budgetBytes: number,
+): { lines: readonly string[]; omitted: number } {
+  if (budgetBytes <= 0) return { lines: [], omitted: lines.length }
+  let bytes = 0
+  const kept: string[] = []
+  for (const line of lines) {
+    const next = bytes + Buffer.byteLength(line, 'utf8')
+    if (next > budgetBytes) {
+      return { lines: kept, omitted: lines.length - kept.length }
+    }
+    kept.push(line)
+    bytes = next
+  }
+  return { lines: kept, omitted: 0 }
+}
+
+/** Section order by precedence, most specific first. Global stays last so a tight
+ *  budget drops the broadest rules before any specific (session/project) rule. */
+const SCOPE_ORDER: readonly RuleScope[] = ['project', 'session', 'global']
+
+function sectionHeader(scope: RuleScope): string {
+  switch (scope) {
+    case 'project': return 'Project requirements (this directory only):'
+    case 'session': return 'Session requirements (this conversation only):'
+    default:        return 'Global requirements:'
+  }
+}
+
+const RULE_BULLET = /^- /
+
+/** Render the full model-visible <system-reminder> text, or undefined when empty.
+ *  Sections are laid out specific-first (project > session > global) so prefix
+ *  retention under {@link enforceBudget} keeps the specific rules and sheds the
+ *  broadest (global) rules first. Returns undefined when no rule bullet survives
+ *  the budget, so we never inject a boilerplate-only reminder. */
+export function renderRules(view: RuleView, budgetBytes: number): string | undefined {
+  const enabled = (rules: readonly Rule[] | undefined): readonly Rule[] =>
+    (rules ?? []).filter(rule => rule.enabled)
+
+  const sections = SCOPE_ORDER
+    .map(scope => ({
+      scope,
+      rules: enabled(scope === 'project' ? (view as { project?: readonly Rule[] }).project
+        : scope === 'session' ? view.session : view.global),
+    }))
+    .filter(section => section.rules.length > 0)
+  if (sections.length === 0) return undefined
+
+  const bullet = (rule: Rule): string => `- ${escapeReminder(rule.text)}`
+  const lines: string[] = [
+    'The following user requirements apply to every step of this conversation. Obey them.',
+    'More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.',
+  ]
+  for (const section of sections) {
+    lines.push('', sectionHeader(section.scope))
+    lines.push(...section.rules.map(bullet))
+  }
+
+  const { lines: kept } = enforceBudget(lines, budgetBytes)
+  if (!kept.some(line => RULE_BULLET.test(line))) return undefined
+  return `<system-reminder>\n${kept.join('\n')}\n</system-reminder>`
+}
+
+/** SHA-1 digest of the rendered text, used to suppress redundant injection. */
+export async function renderDigest(view: RuleView, budgetBytes: number): Promise<string | undefined> {
+  const text = renderRules(view, budgetBytes)
+  if (text === undefined) return undefined
+  const bytes = new TextEncoder().encode(text)
+  const hash = await crypto.subtle.digest('SHA-1', bytes)
+  return [...new Uint8Array(hash)].map(byte => byte.toString(16).padStart(2, '0')).join('')
+}

package/src/store.ts

@@ -0,0 +1,133 @@
+/**
+ * Durable rule store: `global` and `session` rules both persist to JSON files
+ * under DSH_HOME — `global` to `$DSH_HOME/rules/global.json`, and each session's
+ * rules to `$DSH_HOME/rules/sessions/<sessionId>.json`. Files are read lazily at
+ * every view/pre-step and written on every mutating `/rules` command, so both
+ * scopes survive process restarts. `ctx.fs.writeText` creates parent dirs.
+ *
+ * Note: an event-sourced `rules/set` session event (方案 A) would be the cleanest
+ * "model-visible ⟺ logged" guarantee, but the public `Session.append` cannot mark
+ * an out-of-repo event type `ignorable`, so a harness reading such a log would
+ * refuse to reconstruct it. The per-session file is the pragmatic durable path.
+ *
+ * Pure CRUD helpers (addRule/removeRule/mutate/newRule) live in `core.ts`.
+ *
+ * @module dsh-baize-rules/store
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type {} from '@deepseek-ai/dsh-fs' // augments Context with `fs`
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths'
+import type { Rule, RuleView } from './rules.ts'
+
+/** Resolve the global rules path (config override, else `$DSH_HOME/rules/global.json`). */
+function globalRulesPath(ctx: Context, config: { globalRulesPath?: string }): string {
+  return config.globalRulesPath ?? dshHomePath('rules', 'global.json')
+}
+
+/** Resolve one session's rules file: `$DSH_HOME/rules/sessions/<sessionId>.json`. */
+function sessionRulesPath(sessionId: unknown): string {
+  return dshHomePath('rules', 'sessions', `${String(sessionId)}.json`)
+}
+
+/** Slug a project (cwd) into a safe filename for `$DSH_HOME/rules/projects/<slug>.json`. */
+function projectSlug(projectId: unknown): string {
+  return String(projectId).replace(/[\\/:*?"<>|]/g, '_').replace(/^_+|_+$/g, '') || '_'
+}
+/** Resolve one project's rules file (project = session cwd). */
+function projectRulesPath(projectId: unknown): string {
+  return dshHomePath('rules', 'projects', `${projectSlug(projectId)}.json`)
+}
+
+/** Read a project's rule set from its durable file (empty when missing). */
+export async function readProject(ctx: Context, projectId: unknown): Promise<Rule[]> {
+  if (ctx.fs === undefined || projectId === undefined || String(projectId).length === 0) return []
+  const path = projectRulesPath(projectId)
+  const target = await ctx.fs.resolve(path)
+  const info = await ctx.fs.stat(target)
+  if (info === undefined) return []
+  const raw = await ctx.fs.readText(target)
+  const parsed: unknown = JSON.parse(raw)
+  if (!Array.isArray(parsed)) throw new Error(`rules: project rules file is not a JSON array: ${path}`)
+  return sanitizeRules(parsed)
+}
+
+/** Replace a project's rule set in its durable file. */
+export async function writeProject(ctx: Context, projectId: unknown, rules: readonly Rule[]): Promise<void> {
+  if (ctx.fs === undefined || projectId === undefined || String(projectId).length === 0) return
+  const path = projectRulesPath(projectId)
+  const target = await ctx.fs.resolve(path)
+  await ctx.fs.writeText(target, `${JSON.stringify(rules, null, 2)}\n`)
+}
+
+/** Validate a parsed array into well-formed rules; drop the malformed entries loudly.
+ *  Rules are plain text — there is no `kind` field anymore, but legacy stored
+ *  entries that carried `kind` are accepted (the field is ignored on rewrite). */
+function sanitizeRules(parsed: readonly unknown[]): Rule[] {
+  return parsed.flatMap((item) => {
+    if (typeof item !== 'object' || item === null) throw new Error('rules: entry is not an object')
+    const rule = item as Record<string, unknown>
+    const { text, id } = rule
+    if (typeof text !== 'string' || typeof id !== 'string') {
+      throw new Error('rules: entry must carry string id and text')
+    }
+    return [{
+      id,
+      text,
+      enabled: rule.enabled !== false,
+      createdAt: typeof rule.createdAt === 'number' ? rule.createdAt : 0,
+      updatedAt: typeof rule.updatedAt === 'number' ? rule.updatedAt : 0,
+    } satisfies Rule]
+  })
+}
+
+/** Read the global rule set, tolerating a missing file and failing loud on a malformed store. */
+export async function readGlobal(ctx: Context, config: { globalRulesPath?: string }): Promise<Rule[]> {
+  if (ctx.fs === undefined) return []
+  const path = globalRulesPath(ctx, config)
+  const target = await ctx.fs.resolve(path)
+  const info = await ctx.fs.stat(target)
+  if (info === undefined) return []
+  const raw = await ctx.fs.readText(target)
+  const parsed: unknown = JSON.parse(raw)
+  if (!Array.isArray(parsed)) throw new Error(`rules: global rules file is not a JSON array: ${path}`)
+  return sanitizeRules(parsed)
+}
+
+/** Write the global rule set. */
+export async function writeGlobal(ctx: Context, config: { globalRulesPath?: string }, rules: readonly Rule[]): Promise<void> {
+  if (ctx.fs === undefined) return
+  const path = globalRulesPath(ctx, config)
+  const target = await ctx.fs.resolve(path)
+  await ctx.fs.writeText(target, `${JSON.stringify(rules, null, 2)}\n`)
+}
+
+/** Read the per-session rule set from its durable file (empty when missing). */
+export async function readSession(ctx: Context, sessionId: unknown): Promise<Rule[]> {
+  if (ctx.fs === undefined) return []
+  const path = sessionRulesPath(sessionId)
+  const target = await ctx.fs.resolve(path)
+  const info = await ctx.fs.stat(target)
+  if (info === undefined) return []
+  const raw = await ctx.fs.readText(target)
+  const parsed: unknown = JSON.parse(raw)
+  if (!Array.isArray(parsed)) throw new Error(`rules: session rules file is not a JSON array: ${path}`)
+  return sanitizeRules(parsed)
+}
+
+/** Replace the per-session rule set in its durable file. */
+export async function writeSession(ctx: Context, sessionId: unknown, rules: readonly Rule[]): Promise<void> {
+  if (ctx.fs === undefined) return
+  const path = sessionRulesPath(sessionId)
+  const target = await ctx.fs.resolve(path)
+  await ctx.fs.writeText(target, `${JSON.stringify(rules, null, 2)}\n`)
+}
+
+/** Assemble the merged view used for injection and /rules list. */
+export async function view(ctx: Context, agent: Agent, config: { globalRulesPath?: string }): Promise<RuleView> {
+  return {
+    global: await readGlobal(ctx, config),
+    session: await readSession(ctx, agent.id),
+  }
+}