dsh-plugin-discourse 0.0.0-stage → 1.0.1

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Discourse",
+    "description": "Search, read, post, moderate, and administer a Discourse forum."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Discourse 论坛",
+    "description": "搜索、阅读、发帖、审核与管理 Discourse 论坛。"
+  }
+}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "dsh-plugin-discourse",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Discourse administration and agent tools for the DeepSeek Harness: 16 tools for reading, posting, moderating, and administering a Discourse forum.",
+  "license": "MIT",
+  "author": "AkarinLiu",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "discourse",
+    "forum",
+    "plugin",
+    "agent-tools",
+    "moderation",
+    "chatops"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AkarinLiu/dsh-plugin-discourse.git"
+  },
+  "homepage": "https://github.com/AkarinLiu/dsh-plugin-discourse#readme",
+  "bugs": {
+    "url": "https://github.com/AkarinLiu/dsh-plugin-discourse/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node scripts/smoke.mjs",
+    "verify": "node scripts/verify-package.mjs",
+    "doctor": "node scripts/doctor.mjs",
+    "prepack": "node scripts/smoke.mjs"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "index.js",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE",
+    "locale/*.json",
+    "icon.svg",
+    "scripts/"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/scripts/doctor.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+/**
+ * Diagnose (and with --fix, remove) the Windows install trap where a stale
+ * directory junction for this bundle blocks a registry install:
+ *
+ *   [ERR_PNPM_EPERM] [importPackage ...\node_modules\dsh-plugin-discourse]
+ *   EPERM: operation not permitted, rename '..._tmp_...' -> '...dsh-plugin-discourse'
+ *
+ * A local-clone install (dsh plugin add ./dsh-plugin-discourse) creates that
+ * junction. pnpm's hoisted linker does not always record or prune it, so a
+ * later npm install cannot replace it. Removing the junction removes only the
+ * link; the checkout it points at is left untouched.
+ *
+ *   node scripts/doctor.mjs --profile desktop
+ *   node scripts/doctor.mjs --profile desktop --fix
+ */
+
+import { readFileSync, existsSync, lstatSync, realpathSync, unlinkSync, rmdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { basename, dirname, join, resolve } from 'node:path'
+
+const PACKAGE = 'dsh-plugin-discourse'
+
+const argv = process.argv.slice(2)
+const profileIndex = argv.indexOf('--profile')
+const profile = profileIndex >= 0 ? argv[profileIndex + 1] : 'desktop'
+const fix = argv.includes('--fix')
+
+if (profileIndex >= 0 && (profile === undefined || profile.startsWith('--'))) {
+  console.error('usage: node scripts/doctor.mjs [--profile <name>] [--fix]')
+  process.exit(2)
+}
+
+const dshHome = process.env.DSH_HOME ?? join(homedir(), '.dsh')
+const profileDir = join(dshHome, 'profiles', profile)
+const manifestPath = join(profileDir, 'package.json')
+const linkPath = join(profileDir, 'node_modules', PACKAGE)
+
+if (!existsSync(manifestPath)) {
+  console.error(`no DSH profile at ${profileDir}: open DeepSeek Harness once for that profile, then retry`)
+  process.exit(2)
+}
+
+/** Read JSON that a Windows editor or PowerShell may have prefixed with a BOM. */
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8').replace(/^\uFEFF/, ''))
+}
+
+/** The spec the profile records for this bundle, when it records one. */
+function dependencySpec() {
+  try {
+    const manifest = readJson(manifestPath)
+    for (const field of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+      const spec = manifest?.[field]?.[PACKAGE]
+      if (typeof spec === 'string' && spec.length > 0) return spec
+    }
+  } catch (error) {
+    console.error(`could not read ${manifestPath}: ${error.message}`)
+    process.exit(2)
+  }
+  return undefined
+}
+
+/**
+ * Inspect one node_modules entry. A junction (or symlink) resolves to a
+ * different path than the lexical entry; a normal package directory does not.
+ */
+function inspectEntry(path) {
+  let stats
+  try {
+    stats = lstatSync(path)
+  } catch {
+    return undefined
+  }
+  let target
+  try {
+    target = realpathSync.native(path)
+  } catch {
+    target = undefined
+  }
+  let expected = resolve(path)
+  try {
+    expected = join(realpathSync.native(dirname(path)), basename(path))
+  } catch {
+    // The parent is always readable when lstat succeeded; keep the lexical form.
+  }
+  const same = target !== undefined && (process.platform === 'win32'
+    ? target.toLowerCase() === expected.toLowerCase()
+    : target === expected)
+  return { target, isLink: stats.isSymbolicLink() || !same }
+}
+
+/** Remove a link without ever recursing into its target. */
+function removeLink(path) {
+  try {
+    unlinkSync(path)
+    return
+  } catch (error) {
+    if (!['EPERM', 'EISDIR', 'ENOTDIR', 'EACCES'].includes(error.code)) throw error
+  }
+  // On Windows rmdir deletes the junction's reparse point, not the target.
+  rmdirSync(path)
+}
+
+const entry = inspectEntry(linkPath)
+
+if (entry === undefined) {
+  console.log(`ok: no stale ${PACKAGE} entry in ${profileDir}; run "dsh plugin --profile ${profile} add ${PACKAGE}" to install it`)
+  process.exit(0)
+}
+
+if (!entry.isLink) {
+  if (existsSync(join(linkPath, 'package.json'))) {
+    console.log(`ok: ${PACKAGE} is installed as a normal directory in ${profileDir}`)
+    process.exit(0)
+  }
+  console.error(`${linkPath} exists but is not a package and not a link; inspect it by hand`)
+  process.exit(1)
+}
+
+const spec = dependencySpec()
+const target = entry.target ?? '(unresolvable)'
+const localSpec = spec !== undefined && (spec.startsWith('link:') || spec.startsWith('file:'))
+
+console.log(`found a directory link for ${PACKAGE}:`)
+console.log(`  link:       ${linkPath}`)
+console.log(`  target:     ${target}`)
+console.log(`  dependency: ${spec ?? '(not recorded)'}`)
+console.log(localSpec
+  ? 'The profile records a local spec, so this link is expected while the checkout is installed directly.'
+  : 'The profile records a registry spec, so this link is a leftover from an earlier local install.')
+
+if (!fix) {
+  if (localSpec) {
+    console.log('ok: this is a local development install; rerun with --fix only when switching the profile to the npm package.')
+    process.exit(0)
+  }
+  console.error('stale link blocks "pnpm install"; re-run with --fix to remove the link only, then install again:')
+  console.error(`  node scripts/doctor.mjs --profile ${profile} --fix`)
+  console.error(`  dsh plugin --profile ${profile} add ${PACKAGE}`)
+  process.exit(1)
+}
+
+try {
+  removeLink(linkPath)
+} catch (error) {
+  console.error(`could not remove ${linkPath}: ${error.message}`)
+  console.error('close DeepSeek Harness, then retry, or delete the junction in Explorer.')
+  process.exit(1)
+}
+
+if (existsSync(linkPath) || inspectEntry(linkPath) !== undefined) {
+  console.error(`${linkPath} still exists after removal`)
+  process.exit(1)
+}
+
+console.log(`removed the link; ${target === '(unresolvable)' ? 'the target' : target} was left untouched.`)
+console.log('now install the bundle:')
+console.log(`  dsh plugin --profile ${profile} add ${PACKAGE}`)

package/scripts/smoke.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * Offline and live smoke test for the Discourse plugin.
+ *
+ * The stub context mirrors what the Loader provides to `apply`, so this
+ * exercises the real registration path without booting a Harness.
+ *
+ *   node scripts/smoke.mjs          definition checks only
+ *   node scripts/smoke.mjs --live   also call read-only tools against the forum
+ */
+
+import { apply } from '../index.js'
+
+const live = process.argv.includes('--live')
+const baseUrl = process.env.DISCOURSE_BASE_URL ?? 'https://meta.discourse.org'
+const registry = new Map()
+const problems = []
+
+const ctx = {
+  tools: {
+    register(definition) {
+      if (registry.has(definition.name)) problems.push(`duplicate tool name ${definition.name}`)
+      registry.set(definition.name, definition)
+      return () => registry.delete(definition.name)
+    },
+  },
+  effect(callback, label) {
+    const dispose = callback()
+    return () => {
+      if (typeof dispose === 'function') dispose()
+    }
+  },
+}
+
+apply(ctx, { baseUrl, readOnly: true, maxItems: 5 })
+
+const expected = [
+  'discourse_search',
+  'discourse_topics',
+  'discourse_topic',
+  'discourse_categories',
+  'discourse_user',
+  'discourse_create_topic',
+  'discourse_reply',
+  'discourse_update_post',
+  'discourse_flag_post',
+  'discourse_review_queue',
+  'discourse_delete_post',
+  'discourse_restore_post',
+  'discourse_admin_users',
+  'discourse_moderate_user',
+  'discourse_site_settings',
+  'discourse_admin_stats',
+]
+
+for (const name of expected) {
+  if (!registry.has(name)) problems.push(`missing tool ${name}`)
+}
+for (const name of registry.keys()) {
+  if (!expected.includes(name)) problems.push(`unexpected tool ${name}`)
+}
+
+for (const [name, tool] of registry) {
+  if (!/^discourse_[a-z_]+$/.test(name)) problems.push(`${name}: name must match discourse_[a-z_]+`)
+  if (typeof tool.description !== 'string' || tool.description.length < 40) problems.push(`${name}: description too short`)
+  if (tool.parameters?.type !== 'object') problems.push(`${name}: parameters must be an object schema`)
+  if (tool.parameters?.additionalProperties !== false) problems.push(`${name}: parameters must set additionalProperties false`)
+  if (typeof tool.output?.render !== 'function') problems.push(`${name}: output.render missing`)
+  if (tool.output?.schema?.type !== 'object') problems.push(`${name}: output schema must be an object`)
+  if (typeof tool.execute !== 'function') problems.push(`${name}: execute missing`)
+  for (const [key, schema] of Object.entries(tool.parameters?.properties ?? {})) {
+    if (typeof schema.description !== 'string' || schema.description.length === 0) problems.push(`${name}.${key}: parameter needs a description`)
+    if (schema.type === undefined && schema.oneOf === undefined) problems.push(`${name}.${key}: parameter needs a type`)
+  }
+}
+
+// A malformed forum URL must fail at activation with a usable diagnostic,
+// before any tool is registered.
+try {
+  apply({
+    tools: { register() { problems.push('invalid baseUrl registered a tool') } },
+    effect(callback) { callback() },
+  }, { baseUrl: 'ftp://forum.example.com' })
+  problems.push('invalid baseUrl was accepted')
+} catch (error) {
+  if (!/http\(s\) URL/.test(error.message)) problems.push(`invalid baseUrl diagnostic is unhelpful: ${error.message}`)
+}
+
+const describe = (value) => {
+  const rendered = value.map((block) => block.text ?? `[${block.type}]`).join('\n')
+  return rendered.length > 700 ? `${rendered.slice(0, 700)}…` : rendered
+}
+
+if (live) {
+  const cases = [
+    ['discourse_categories', {}],
+    ['discourse_topics', { filter: 'latest', limit: 3 }],
+    ['discourse_search', { q: 'api', limit: 3 }],
+    ['discourse_topic', { topic: 1, limit: 2 }],
+    ['discourse_user', { username: 'system' }],
+  ]
+  for (const [name, args] of cases) {
+    try {
+      const value = await registry.get(name).execute(args, { signal: AbortSignal.timeout(30000) })
+      console.log(`\n=== ${name} ===\n${describe(registry.get(name).output.render(args, value))}`)
+    } catch (error) {
+      problems.push(`${name}: ${error.message}`)
+    }
+  }
+}
+
+if (problems.length > 0) {
+  console.error('smoke test failed:')
+  for (const problem of problems) console.error(`  - ${problem}`)
+  process.exit(1)
+}
+
+console.log(`ok: ${registry.size} tools registered${live ? ' (live calls included)' : ''}`)

package/scripts/verify-package.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * Verify that the published tarball contains every runtime asset the DeepSeek
+ * Harness needs: the Host entry, the bundle patch, both locales, the icon, and
+ * the manifest. Run before a release or from CI.
+ *
+ *   node scripts/verify-package.mjs
+ */
+
+import { spawnSync } from 'node:child_process'
+import { closeSync, existsSync, mkdtempSync, openSync, readFileSync, rmSync, statSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+/** Read JSON that may carry a UTF-8 BOM from a Windows editor. */
+const readJson = (path) => JSON.parse(readFileSync(path, 'utf8').replace(/^\uFEFF/, ''))
+const manifest = readJson(join(root, 'package.json'))
+const problems = []
+
+/** Record one packaging violation. */
+function check(condition, message) {
+  if (!condition) problems.push(message)
+}
+
+// --- Manifest --------------------------------------------------------------
+
+check(manifest.private !== true, 'package.json must not set "private": true, or npm refuses to publish it')
+check(typeof manifest.name === 'string' && manifest.name.length > 0, 'package.json needs a name')
+check(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(manifest.version ?? ''), `package.json version is not semver: ${JSON.stringify(manifest.version)}`)
+check(manifest.type === 'module', 'package.json must stay "type": "module"')
+check(manifest.publishConfig?.access === 'public', 'publishConfig.access must be "public"')
+check(manifest.publishConfig?.registry === 'https://registry.npmjs.org', 'publishConfig.registry must name npmjs.com')
+check(manifest.engines?.node === '>=20', 'engines.node must stay ">=20"')
+
+const patch = manifest.dsh?.bundle?.patch
+check(typeof patch === 'string' && patch.length > 0, 'package.json must declare dsh.bundle.patch')
+if (typeof patch === 'string') {
+  check(existsSync(join(root, patch)), `dsh.bundle.patch points at a missing file: ${patch}`)
+}
+
+for (const [subpath, target] of Object.entries(manifest.exports ?? {})) {
+  if (typeof target !== 'string' || target.includes('*')) continue
+  check(existsSync(join(root, target)), `exports["${subpath}"] points at a missing file: ${target}`)
+}
+
+// --- Local assets ----------------------------------------------------------
+
+const required = [
+  'index.js',
+  'cordis.patch.yml',
+  'README.md',
+  'LICENSE',
+  'locale/en.json',
+  'locale/zh.json',
+  'icon.svg',
+  'scripts/smoke.mjs',
+  'scripts/doctor.mjs',
+  'scripts/verify-package.mjs',
+]
+for (const relative of required) check(existsSync(join(root, relative)), `missing required file: ${relative}`)
+
+for (const locale of ['locale/en.json', 'locale/zh.json']) {
+  const file = join(root, locale)
+  if (!existsSync(file)) continue
+  try {
+    const value = readJson(file)
+    check(typeof value?.meta?.title === 'string' && value.meta.title.length > 0, `${locale} needs meta.title`)
+    check(typeof value?.meta?.description === 'string' && value.meta.description.length > 0, `${locale} needs meta.description`)
+  } catch (error) {
+    problems.push(`${locale} is not valid JSON: ${error.message}`)
+  }
+}
+
+const icon = join(root, 'icon.svg')
+if (existsSync(icon)) {
+  const size = statSync(icon).size
+  check(size > 0 && size <= 256 * 1024, `icon.svg must be between 1 byte and 256 KiB, got ${size} bytes`)
+  check(readFileSync(icon, 'utf8').includes('<svg'), 'icon.svg does not look like an SVG document')
+}
+
+// --- Packed file list ------------------------------------------------------
+
+// Run npm with its stdout attached to a real file descriptor instead of a pipe:
+// on Windows the Harness sandbox denies piped stdio, and a pipe cannot deadlock
+// a large pack listing when it is a file handle.
+/** Locate npm's JavaScript entry so it can run without a command shell. */
+function findNpmCli() {
+  const candidates = []
+  if (typeof process.env.npm_execpath === 'string') candidates.push(process.env.npm_execpath)
+  const nodeDir = dirname(process.execPath)
+  candidates.push(
+    join(nodeDir, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    join(nodeDir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    join(nodeDir, '..', 'libexec', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+  )
+  return candidates.find((candidate) => /npm-cli\.js$/i.test(candidate) && existsSync(candidate))
+}
+
+const npmCli = findNpmCli()
+const useNpmCli = npmCli !== undefined
+const command = useNpmCli ? process.execPath : process.platform === 'win32' ? 'npm.cmd' : 'npm'
+const args = [...(useNpmCli ? [npmCli] : []), 'pack', '--dry-run', '--json', '--ignore-scripts']
+const tempDir = mkdtempSync(join(tmpdir(), 'dsh-plugin-package-'))
+const packFile = join(tempDir, 'pack.json')
+let packOutput
+let fd
+try {
+  fd = openSync(packFile, 'w')
+  const result = spawnSync(command, args, {
+    cwd: root,
+    // Keep npm's cache inside this throwaway directory: the Harness sandbox
+    // cannot write the user-level cache, and CI should not depend on it either.
+    env: { ...process.env, npm_config_cache: join(tempDir, 'npm-cache') },
+    stdio: ['ignore', fd, 'inherit'],
+    shell: !useNpmCli && process.platform === 'win32',
+  })
+  closeSync(fd)
+  fd = undefined
+  if (result.error) problems.push(`npm pack failed: ${result.error.message}`)
+  else if (result.status !== 0) problems.push(`npm pack exited with status ${String(result.status)}`)
+  else packOutput = readFileSync(packFile, 'utf8')
+} finally {
+  if (fd !== undefined) closeSync(fd)
+  rmSync(tempDir, { recursive: true, force: true })
+}
+
+let packed = []
+if (packOutput) {
+  try {
+    const [info] = JSON.parse(packOutput)
+    packed = Array.isArray(info?.files) ? info.files.map((file) => file.path) : []
+  } catch (error) {
+    problems.push(`could not parse npm pack --json output: ${error.message}`)
+  }
+}
+
+if (packed.length > 0) {
+  const present = new Set(packed)
+  for (const relative of required) {
+    check(present.has(relative), `the packed tarball omits ${relative}; add it to package.json "files"`)
+  }
+  const forbidden = packed.filter((path) => path.startsWith('node_modules/') || path.startsWith('.git/') || path.includes('.tmp') || path.endsWith('.log'))
+  check(forbidden.length === 0, `the packed tarball contains development files: ${forbidden.join(', ')}`)
+}
+
+if (problems.length > 0) {
+  console.error('package verification failed:')
+  for (const problem of problems) console.error(`  - ${problem}`)
+  process.exit(1)
+}
+
+console.log(`ok: ${manifest.name}@${manifest.version} packs ${packed.length} files with every required asset`)