dsh-plugin-show-me-data 0.1.0

package/lib/host/index.js

@@ -0,0 +1,293 @@
+/**
+ * The host half — the Cordis plugin the profile mounts (docs/09 §4).
+ *
+ * Composition only: it wires the ports (clock, repositories, adapters, gateways)
+ * to the use cases, then contributes routes, tools and a refresh timer. Every
+ * contribution is disposed when the plugin unloads, which is asserted by
+ * 'test/host/plugin-shape.test.js'.
+ *
+ * @module host/index
+ */
+import { fileURLToPath } from 'node:url'
+
+import { createRefreshService } from '../app/refresh.js'
+import { createOverviewUseCase } from '../app/overview.js'
+import { createSeriesViewUseCase } from '../app/series-view.js'
+import { createWatchlistUseCase } from '../app/watchlist.js'
+import { createHealthUseCase } from '../app/health.js'
+import { createAiUseCases } from '../app/ai.js'
+import { createDeterministicGateway } from '../app/ai-deterministic.js'
+import { createProposeUseCase } from '../app/propose-indicator.js'
+import { searchIndicators } from '../core/indicators/resolve.js'
+import { CATALOG, indexById, UNSUPPORTED } from '../core/indicators/catalog.js'
+import { hasAdapter, fetchViaAdapter, adapterIds, sourceTimeoutMs, supportsBarSize } from '../sources/registry.js'
+import { systemClock } from '../ports/clock.js'
+import { createFileSnapshotRepository, createFileWatchlistRepository } from './infra/fs-repos.js'
+import { createRoutes, ROUTES } from './http/routes.js'
+import { registerTools, TOOL_NAMES } from './tools/register.js'
+import { API_PREFIX } from './http/respond.js'
+import { createDshLlmGateway } from './ai/dsh-llm-gateway.js'
+import { memorySnapshotRepository, memoryWatchlistRepository } from './infra/memory-fallback.js'
+import { ConfigSchema, DEFAULT_CONFIG, resolveConfig } from './config.js'
+import { createDiscussionGateway } from './ai/discussion.js'
+
+/** Plugin name, as it appears in the loader tree. */
+export const name = 'show-me-data'
+
+/**
+ * Absolute path of this package's root — the workspace an iteration session runs in.
+ *
+ * Derived from the module URL rather than configured, so it is correct whether the
+ * plugin is loaded from `src/` or from the published `lib/` tree (`lib/host.js`
+ * sits at the same depth).
+ */
+export const PLUGIN_ROOT = fileURLToPath(new URL('../..', import.meta.url)).replace(/\/$/, '')
+
+
+/**
+ * Hard dependencies. Optional services ('llm', 'agentDefaultModel', 'timer') are
+ * read with 'ctx.get' and degrade instead of blocking activation.
+ */
+export const inject = ['webServer', 'tools']
+
+/**
+ * The plugin's config schema, read by the loader **before** 'apply' runs.
+ *
+ * This must be a Standard Schema ('Config["~standard"].validate'), not a plain
+ * defaults object: Cordis calls that method during row resolution, so a plain
+ * object crashes the entire profile at boot rather than failing this one row.
+ * See 'src/host/config.js' for the validation rules and the defaults.
+ */
+export const Config = ConfigSchema
+
+/** The row defaults, exported for documentation and tests. */
+export const defaults = DEFAULT_CONFIG
+
+/**
+ * Mount the plugin.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx - host context.
+ * @param {object} [config] - row configuration.
+ * @returns {() => void} disposer.
+ */
+export function apply(ctx, config = {}) {
+  // `resolveConfig` returns `{ value, issues }`; by the time `apply` runs the
+  // loader has already validated the row, so the normalized value is what we use.
+  const { value: resolved } = resolveConfig(config)
+  // Diagnostics must be readable even when the deployment's logger is quiet (the
+  // web profile's default), because "why did the model return nothing" is a
+  // question only the host can answer about its own process.
+  const log = (message, meta) => {
+    try {
+      ctx.logger?.info?.(`[show-me-data] ${message}`, meta ?? '')
+    } catch {
+      // Logging must never break the data path.
+    }
+  }
+  const logVerbose = (message, meta) => {
+    log(message, meta)
+    if (resolved.debug === true) {
+      try {
+        console.error(`[show-me-data] ${message}`, meta === undefined ? '' : JSON.stringify(meta))
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  const clock = systemClock()
+  const snapshots = resolved.storageDir === undefined
+    ? memorySnapshotRepository()
+    : createFileSnapshotRepository({ file: `${resolved.storageDir}/snapshots.json` })
+  const watchlistRepo = resolved.storageDir === undefined
+    ? memoryWatchlistRepository()
+    : createFileWatchlistRepository({ file: `${resolved.storageDir}/watchlist.json` })
+
+  const catalogById = Object.fromEntries(indexById())
+  const runtime = { fetch: (...args) => globalThis.fetch(...args), clock }
+
+  const refresh = createRefreshService({
+    snapshots,
+    clock,
+    fetchViaAdapter: (adapterId, req, deps) => {
+      if (resolved.sources[adapterId] === false) {
+        return Promise.reject(Object.assign(new Error(`source ${adapterId} is disabled by configuration`), { name: 'SourceDisabled' }))
+      }
+      return fetchViaAdapter(adapterId, req, deps)
+    },
+    log,
+    options: { ttlMinutes: resolved.cacheTtl, timeoutFor: sourceTimeoutMs },
+  })
+
+  const overview = createOverviewUseCase({ catalog: CATALOG, catalogById, refresh, clock, runtime, log })
+  const seriesView = createSeriesViewUseCase({ catalogById, refresh, clock, runtime })
+  const watchlist = createWatchlistUseCase({ repository: watchlistRepo, clock, catalogById })
+  const health = createHealthUseCase({ overview, clock, log })
+
+  const deterministic = createDeterministicGateway()
+  const gateway = buildGateway({ ctx, resolved, log })
+  // Built before the AI use cases because `createAiUseCases` needs it injected:
+  // without this argument `ai.propose` silently fell back to a stub and the
+  // route answered 500 ("propose is not a function").
+  const propose = createProposeUseCase({ gateway, catalogById, refresh, clock, runtime, hasAdapter, log })
+  // Discussion sessions inherit the workspace root by default (`storageDir` when
+  // the row sets one), so they open beside the session that spawned them.
+  const discussion = createDiscussionGateway({
+    ctx,
+    clock,
+    log,
+    options: { cwd: resolved.storageDir ?? (typeof process !== 'undefined' ? process.cwd() : undefined) },
+  })
+  const ai = createAiUseCases({
+    gateway,
+    fallback: deterministic,
+    overview,
+    catalogById,
+    snapshots,
+    clock,
+    propose,
+    displaySeries: overview.displaySeries,
+    options: { cacheMinutes: resolved.ai.cacheMinutes },
+    log: logVerbose,
+  })
+
+  const useCases = {
+    overview: overview.overview,
+    seriesView: seriesView.seriesView,
+    watchlist,
+    health: health.health,
+    search: (query, options = {}) => {
+      const result = searchIndicators(query, { limit: 12, ...options })
+      return {
+        matches: result.matches.map((entry) => ({ ...entry.indicator, score: entry.score })),
+        suggestions: result.suggestions,
+      }
+    },
+    ai,
+    discussion,
+    catalog: {
+      all: CATALOG,
+      unsupported: UNSUPPORTED,
+      adapters: adapterIds(),
+      workspace: PLUGIN_ROOT,
+      barSizes: supportsBarSize,
+    },
+    describe: () => ({ ...ai.describe(), routes: ROUTES, tools: TOOL_NAMES }),
+    /**
+     * Everything the panel's settings screen needs, in one payload.
+     *
+     * "What can I change here?" was unanswerable: the screen listed four facts
+     * with no values and no origin. Each knob below therefore carries its
+     * effective value, the config path it came from, and whether the panel can
+     * change it at runtime (most cannot — they are row config, and a row is
+     * rewritten through `dsh`, not from the browser).
+     */
+    settings: () => {
+      const resolved = resolveConfig(config).value
+      const sourcesOff = Object.entries(resolved.sources).filter(([, on]) => on === false).map(([id]) => id)
+      return {
+        configPath: 'profiles/web/cordis.patch.yml → id: show-me-data → config',
+        ai: {
+          ...ai.describe(),
+          enabled: resolved.ai.enabled,
+          maxChars: resolved.ai.maxChars,
+        },
+        refreshMinutes: resolved.refreshMinutes,
+        cacheTtl: resolved.cacheTtl,
+        groups: resolved.groups,
+        noteworthyLimit: resolved.noteworthyLimit,
+        storageDir: resolved.storageDir ?? '(内存，重启即清空)',
+        debug: resolved.debug,
+        sourcesOff,
+        runtime: {
+          routes: ROUTES.length,
+          tools: TOOL_NAMES.length,
+          indicators: CATALOG.length,
+          unsupported: UNSUPPORTED.length,
+          adapters: adapterIds().length,
+          prefix: API_PREFIX,
+        },
+      }
+    },
+  }
+
+  /** @type {Array<() => void>} */
+  const disposers = []
+
+  const webServer = ctx.get('webServer')
+  if (webServer === undefined) {
+    log('webServer is unavailable: routes are not registered (tools still work)')
+  } else {
+    const handler = createRoutes({ useCases, log })
+    disposers.push(webServer.register({ kind: 'prefix', path: API_PREFIX, handler }))
+    log(`registered ${ROUTES.length} routes under ${API_PREFIX}`)
+  }
+
+  disposers.push(registerTools({ tools: ctx.tools, useCases, clock, log }))
+
+  // Periodic refresh: always through the injected timer so disposal cancels it.
+  const timer = ctx.get('timer')
+  if (timer !== undefined && resolved.refreshMinutes > 0) {
+    disposers.push(
+      timer.interval(() => {
+        overview.overview({ range: '1Y', force: true, limit: 1 }).catch((error) => log('scheduled refresh failed', { message: error?.message }))
+      }, resolved.refreshMinutes * 60_000),
+    )
+  }
+
+  ctx.effect?.(() => () => {
+    for (const dispose of [...disposers].reverse()) dispose()
+  }, 'show-me-data: contributions')
+
+  // Discussion sessions are real sessions owned by this plugin: they are
+  // disposed when the plugin unloads, so a restart never leaves orphans behind.
+  ctx.effect?.(() => () => {
+    discussion.dispose().catch((error) => log('discussion disposal failed', { message: error?.message }))
+  }, 'show-me-data: discussion sessions')
+
+  log('mounted', {
+    routes: webServer === undefined ? 0 : ROUTES.length,
+    tools: TOOL_NAMES.length,
+    aiMode: gateway.describe().mode,
+    indicators: CATALOG.length,
+  })
+
+  return () => {
+    for (const dispose of [...disposers].reverse()) dispose()
+  }
+}
+
+/**
+ * Pick the AI gateway for this deployment (docs/06 §1).
+ *
+ * @param {object} options - options.
+ * @param {object} options.ctx - host context.
+ * @param {object} options.resolved - resolved configuration.
+ * @param {(msg: string, meta?: object) => void} options.log - logger.
+ * @returns {object} 'AiGateway'.
+ */
+function buildGateway({ ctx, resolved, log }) {
+  const deterministic = createDeterministicGateway()
+  if (resolved.ai.enabled === false || resolved.ai.mode === 'deterministic') {
+    log('AI gateway: deterministic (disabled by configuration)')
+    return deterministic
+  }
+  const llm = ctx.get('llm')
+  if (llm === undefined) {
+    log('AI gateway: deterministic (no `llm` service in this deployment)')
+    return deterministic
+  }
+  try {
+    const gateway = createDshLlmGateway({
+      llm,
+      defaultModel: ctx.get('agentDefaultModel'),
+      maxChars: resolved.ai.maxChars,
+      log,
+    })
+    log(`AI gateway: llm (${gateway.describe().provider ?? 'unknown'}/${gateway.describe().model ?? 'unknown'})`)
+    return gateway
+  } catch (error) {
+    log('AI gateway: deterministic (llm adapter failed to initialize)', { message: error?.message })
+    return deterministic
+  }
+}

package/lib/host/infra/fs-repos.js

@@ -0,0 +1,179 @@
+/**
+ * File-backed ports for the host half (docs/07 T7.3).
+ *
+ * Both repositories keep a small JSON document and rewrite it atomically
+ * (write to a temp file, then rename), so a crash or a concurrent write cannot
+ * leave a half-written file behind. A file that does not parse is treated as
+ * absent and rebuilt from defaults rather than crashing the plugin.
+ *
+ * @module host/infra/fs-repos
+ */
+import { readFileSync, renameSync, writeFileSync, mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+/**
+ * Read a JSON file, falling back to a default on any failure.
+ *
+ * @param {string} file - path.
+ * @param {any} fallback - value used when the file is missing or corrupt.
+ * @returns {{ value: any, recovered: boolean }} parsed value and whether recovery happened.
+ */
+function readJson(file, fallback) {
+  try {
+    const text = readFileSync(file, 'utf8')
+    if (text.trim() === '') return { value: fallback, recovered: false }
+    return { value: JSON.parse(text), recovered: false }
+  } catch {
+    return { value: fallback, recovered: true }
+  }
+}
+
+/**
+ * Write a JSON file atomically.
+ *
+ * @param {string} file - path.
+ * @param {any} value - JSON-serializable value.
+ * @returns {void}
+ */
+function writeJson(file, value) {
+  mkdirSync(dirname(file), { recursive: true })
+  const temp = `${file}.${process.pid}.tmp`
+  writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`)
+  renameSync(temp, file)
+}
+
+/**
+ * @typedef {Object} FileSnapshotOptions
+ * @property {string} file - snapshot store path.
+ * @property {number} [maxEntries] - cap on retained entries (oldest evicted first).
+ */
+
+/**
+ * A JSON-file snapshot cache.
+ *
+ * @param {FileSnapshotOptions} options - options.
+ * @returns {import('../../ports/snapshot-repo.js').SnapshotRepository} repository.
+ */
+export function createFileSnapshotRepository({ file, maxEntries = 500 }) {
+  /** Serialize writes so concurrent callers cannot interleave a read-modify-write. */
+  let queue = Promise.resolve()
+
+  /**
+   * Run one mutation against the current document.
+   *
+   * @param {(doc: Record<string, any>) => void} mutate - mutation.
+   * @returns {Promise<void>} completion.
+   */
+  function withDocument(mutate) {
+    queue = queue.then(() => {
+      const { value } = readJson(file, {})
+      const doc = value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {}
+      mutate(doc)
+      const keys = Object.keys(doc)
+      if (keys.length > maxEntries) {
+        const ordered = keys.sort((a, b) => String(doc[a].storedAt).localeCompare(String(doc[b].storedAt)))
+        for (const key of ordered.slice(0, keys.length - maxEntries)) delete doc[key]
+      }
+      writeJson(file, doc)
+    })
+    return queue
+  }
+
+  return {
+    async read(key) {
+      await queue
+      const { value } = readJson(file, {})
+      const entry = value?.[key]
+      if (entry === undefined) return undefined
+      return { payload: structuredClone(entry.payload), storedAt: entry.storedAt, ttlMs: entry.ttlMs }
+    },
+    async write(key, payload, { ttlMs, at }) {
+      await withDocument((doc) => {
+        doc[key] = { payload: structuredClone(payload), storedAt: at, ttlMs }
+      })
+    },
+    async list() {
+      await queue
+      const { value } = readJson(file, {})
+      return Object.entries(value ?? {}).map(([key, entry]) => ({ key, storedAt: entry.storedAt, ttlMs: entry.ttlMs }))
+    },
+    async clear() {
+      await withDocument((doc) => {
+        for (const key of Object.keys(doc)) delete doc[key]
+      })
+    },
+  }
+}
+
+/**
+ * @typedef {Object} FileWatchlistOptions
+ * @property {string} file - watchlist path.
+ */
+
+/**
+ * A JSON-file watchlist.
+ *
+ * @param {FileWatchlistOptions} options - options.
+ * @returns {import('../../ports/snapshot-repo.js').WatchlistRepository} repository.
+ */
+export function createFileWatchlistRepository({ file }) {
+  let queue = Promise.resolve()
+
+  /**
+   * Read the current item list.
+   *
+   * @returns {object[]} items.
+   */
+  function readItems() {
+    const { value } = readJson(file, [])
+    return Array.isArray(value) ? value : []
+  }
+
+  /**
+   * Run one mutation against the item list.
+   *
+   * @param {(items: object[]) => any} mutate - mutation returning a value.
+   * @returns {Promise<any>} mutation result.
+   */
+  function withItems(mutate) {
+    let result
+    queue = queue.then(() => {
+      const items = readItems()
+      result = mutate(items)
+      writeJson(file, items)
+    })
+    return queue.then(() => result)
+  }
+
+  return {
+    async list() {
+      await queue
+      return structuredClone(readItems())
+    },
+    async add(item) {
+      return withItems((items) => {
+        const existing = items.find((entry) => entry.indicatorId === item.indicatorId)
+        if (existing !== undefined) return { item: structuredClone(existing), created: false }
+        const stored = structuredClone(item)
+        items.push(stored)
+        return { item: structuredClone(stored), created: true }
+      })
+    },
+    async remove(indicatorId) {
+      return withItems((items) => {
+        const index = items.findIndex((entry) => entry.indicatorId === indicatorId)
+        if (index === -1) return 'notFound'
+        items.splice(index, 1)
+        return 'removed'
+      })
+    },
+    async update(indicatorId, patch) {
+      return withItems((items) => {
+        const index = items.findIndex((entry) => entry.indicatorId === indicatorId)
+        if (index === -1) return undefined
+        items[index] = { ...items[index], ...structuredClone(patch), indicatorId }
+        return structuredClone(items[index])
+      })
+    },
+  }
+}

package/lib/host/infra/memory-fallback.js

@@ -0,0 +1,64 @@
+/**
+ * In-memory port implementations used when the host has no writable storage
+ * (docs/02 §3.2). Same contracts as the file-backed ones, so behaviour does not
+ * change when a deployment adds a storage directory.
+ *
+ * @module host/infra/memory-fallback
+ */
+
+/**
+ * In-memory snapshot cache.
+ *
+ * @returns {import('../../ports/snapshot-repo.js').SnapshotRepository} repository.
+ */
+export function memorySnapshotRepository() {
+  /** @type {Map<string, { payload: any, storedAt: string, ttlMs: number }>} */
+  const store = new Map()
+  return {
+    async read(key) {
+      const entry = store.get(key)
+      return entry === undefined ? undefined : { payload: structuredClone(entry.payload), storedAt: entry.storedAt, ttlMs: entry.ttlMs }
+    },
+    async write(key, payload, { ttlMs, at }) {
+      store.set(key, { payload: structuredClone(payload), storedAt: at, ttlMs })
+    },
+    async list() {
+      return [...store.entries()].map(([key, entry]) => ({ key, storedAt: entry.storedAt, ttlMs: entry.ttlMs }))
+    },
+    async clear() {
+      store.clear()
+    },
+  }
+}
+
+/**
+ * In-memory watchlist.
+ *
+ * @returns {import('../../ports/snapshot-repo.js').WatchlistRepository} repository.
+ */
+export function memoryWatchlistRepository() {
+  /** @type {Map<string, any>} */
+  const items = new Map()
+  return {
+    async list() {
+      return [...items.values()].map((item) => structuredClone(item))
+    },
+    async add(item) {
+      const existing = items.get(item.indicatorId)
+      if (existing !== undefined) return { item: structuredClone(existing), created: false }
+      const stored = structuredClone(item)
+      items.set(stored.indicatorId, stored)
+      return { item: structuredClone(stored), created: true }
+    },
+    async remove(indicatorId) {
+      return items.delete(indicatorId) ? 'removed' : 'notFound'
+    },
+    async update(indicatorId, patch) {
+      const existing = items.get(indicatorId)
+      if (existing === undefined) return undefined
+      const next = { ...existing, ...structuredClone(patch), indicatorId }
+      items.set(indicatorId, next)
+      return structuredClone(next)
+    },
+  }
+}