dsh-keys-manager 0.0.0 → 0.2.0

package/package.json

@@ -1,27 +1,92 @@
 {
   "name": "dsh-keys-manager",
-  "version": "0.0.0",
-  "description": "Placeholder release that reserves the package name. The real package ships from https://github.com/btspoony/dsh-keys-manager via CI trusted publishing. Do not install 0.0.0.",
-  "license": "MIT",
-  "main": "index.js",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Multi-key management for DSH providers: sticky per-session round-robin, retry failover, cooldown recovery, and searchable extra providers.",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/btspoony/dsh-keys-manager.git"
-  },
-  "bugs": {
-    "url": "https://github.com/btspoony/dsh-keys-manager/issues"
+    "url": "https://github.com/btspoony/dsh-keys-manager"
   },
-  "homepage": "https://github.com/btspoony/dsh-keys-manager#readme",
   "keywords": [
     "dsh",
     "dsh-plugin",
     "keys",
     "provider",
-    "llm",
-    "placeholder"
+    "llm"
+  ],
+  "license": "MIT",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "icon": "./icon.svg",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./bundle/cordis.patch.yml": "./bundle/cordis.patch.yml",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "bundle",
+    "locale",
+    "icon.svg",
+    "scripts"
   ],
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
+  "dsh": {
+    "bundle": {
+      "patch": "./bundle/cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-plugin-manager",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-settings-models",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-connection"
+      ]
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.client.json --noEmit && tsc -p tsconfig.spec.json --noEmit",
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.client.json && node scripts/build-client.mjs && node scripts/verify-dist.mjs",
+    "build:client": "tsc -p tsconfig.client.json && node scripts/build-client.mjs",
+    "test": "vitest run",
+    "release:prepare": "node scripts/prepare-release.mjs",
+    "prepare": "pnpm run build",
+    "prepack": "pnpm run build"
+  },
+  "engines": {
+    "node": "^22.19 || >=24"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-client-connection": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings-models": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-credentials": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-typert-registry": "^0.2.1-rc.2",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@types/node": "^22.20.0",
+    "@types/react": "~18.3.31",
+    "esbuild": "^0.28.2",
+    "react": "^18.3.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.8"
   }
 }

package/scripts/build-client.mjs

@@ -0,0 +1,53 @@
+/**
+ * Bundle the browser half into the module-loader artifact the DSH Web client
+ * executes.
+ *
+ * The source is a normal ESM TypeScript entry; esbuild emits CommonJS and the
+ * banner/footer wrap it in the loader's closure factory. React stays external
+ * because the browser module table provides it. Host and DSH packages must
+ * never appear as runtime imports: the Client half is rendered inside the
+ * harness, so only React is loaded from the module table.
+ */
+import { build } from 'esbuild'
+import { readFile } from 'node:fs/promises'
+
+const ID = 'dsh-keys-manager'
+const OUT = 'lib/client.js'
+
+const result = await build({
+  entryPoints: ['src/client/index.ts'],
+  outfile: OUT,
+  bundle: true,
+  format: 'cjs',
+  platform: 'browser',
+  target: 'es2020',
+  external: ['react', 'react/jsx-runtime'],
+  sourcemap: false,
+  logLevel: 'warning',
+  banner: {
+    js: [
+      '/* Keys Manager Client bundle; generated by scripts/build-client.mjs. */',
+      `window.__ModuleLoader__.load({ id: ${JSON.stringify(ID)}, factory: (require) => {`,
+      'var module = { exports: {} }; var exports = module.exports;',
+    ].join('\n'),
+  },
+  footer: {
+    js: 'return module.exports; } });',
+  },
+})
+
+if (result.errors.length > 0) {
+  throw new Error(`client bundle build failed:\n${result.errors.map(error => error.text).join('\n')}`)
+}
+
+const text = await readFile(OUT, 'utf8')
+if (!text.includes(`window.__ModuleLoader__.load({ id: ${JSON.stringify(ID)}`)) {
+  throw new Error('client bundle is missing the module-loader handoff')
+}
+if (text.includes('import.meta')) {
+  throw new Error('client bundle must not contain import.meta; the loader executes it as a classic script')
+}
+if (/require\(["']@deepseek-ai\//.test(text)) {
+  throw new Error('client bundle must not require @deepseek-ai packages at runtime')
+}
+console.log(`built ${OUT} (${Buffer.byteLength(text)} bytes)`)

package/scripts/prepare-release.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+/**
+ * Release-prep version helper (plan dsh-keys-manager-ci-release, task 2 + 4):
+ * resolves the target version — explicit `X.Y.Z` / `X.Y.Z-prerelease`
+ * argument (e.g. 0.1.1-alpha.1) or an auto patch bump from package.json —
+ * refuses already-released versions (existing `v<version>` git tag), aborts
+ * when there are no commits since the previous release tag (nothing to
+ * release), bumps package.json, inserts the `## [<version>]` section into
+ * CHANGELOG.md (from the same git-log notes the workflows use; keeps
+ * existing sections, no-op when already present), and prints
+ * `VERSION=<version>` for the workflow to capture. Node built-ins only, no
+ * new dependencies.
+ *
+ * Usage:
+ *   node scripts/prepare-release.mjs            # auto patch bump
+ *   node scripts/prepare-release.mjs 0.2.0      # explicit version
+ *   node scripts/prepare-release.mjs 0.1.1-alpha.1  # explicit prerelease
+ *
+ * Exit codes: 0 = bumped and printed VERSION; 1 = rejected (unparseable
+ * version, existing tag, no commits since the previous release tag,
+ * unparseable current package.json version, or CHANGELOG.md write error).
+ */
+
+import { execFileSync } from 'node:child_process'
+import { readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const PKG_PATH = join(REPO_ROOT, 'package.json')
+const CHANGELOG_PATH = join(REPO_ROOT, 'CHANGELOG.md')
+const CHANGELOG_HEADER =
+  '# Changelog\n\nAll notable changes to dsh-keys-manager are documented here. Generated from git log by the release-prep workflow.\n'
+
+/**
+ * Parse X.Y.Z or X.Y.Z[-prerelease] (numeric parts; optional prerelease
+ * suffix); null when not parseable. The suffix character set matches the
+ * workflows' guard regex `[0-9A-Za-z.-]+` (keep-simple: no leading-zero or
+ * empty-identifier rules), with one tightening: the suffix MUST contain at
+ * least one digit, so `1.2.3-alpha.1` / `1.2.3-rc.2` parse but `1.2.3-alpha`
+ * (no numeric identifier) and `1.2.3-` (empty suffix) are rejected. Returns
+ * { major, minor, patch, prerelease? } — prerelease is the raw suffix text
+ * (e.g. 'alpha.1') when present, undefined for formal versions.
+ */
+function parseVersion(value) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]*[0-9][0-9A-Za-z.-]*))?$/.exec(value)
+  if (!match) return null
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] === undefined ? undefined : match[4],
+  }
+}
+
+const pkg = JSON.parse(readFileSync(PKG_PATH, 'utf8'))
+
+let target
+if (process.argv[2] !== undefined) {
+  target = parseVersion(process.argv[2])
+  if (target === null) {
+    console.error(`Error: invalid version "${process.argv[2]}". Expected X.Y.Z or X.Y.Z-prerelease (e.g. 0.2.0, 0.1.1-alpha.1).`)
+    process.exit(1)
+  }
+} else {
+  // Auto patch bump (mirrors sibling dsh-llm-fallbacks autoBumpPatch): parse
+  // the current version as X.Y.Z or X.Y.Z-pre, then:
+  //  - formal version X.Y.Z            -> X.Y.(Z+1)       (0.1.2 -> 0.1.3)
+  //  - prerelease with numeric tail    -> bump only the tail, staying on the
+  //    prerelease line (0.1.3-alpha.3 -> 0.1.3-alpha.4)
+  //  - prerelease with non-numeric tail (e.g. 0.1.0-alpha) -> cannot auto
+  //    bump; require an explicit version argument.
+  // The looser regex is deliberate: parseVersion (explicit args) requires a
+  // digit in the suffix, so it cannot tell "alpha" from a malformed version;
+  // this path needs the raw suffix to reject non-numeric tails with the
+  // explicit-version hint.
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(pkg.version)
+  if (!m) {
+    console.error(`Error: cannot parse current package.json version "${pkg.version}".`)
+    process.exit(1)
+  }
+  const [, major, minor, patch, pre] = m
+  if (pre === undefined) {
+    target = { major: Number(major), minor: Number(minor), patch: Number(patch) + 1 }
+  } else {
+    const tail = pre.split('.').at(-1)
+    if (tail === undefined || !/^\d+$/.test(tail)) {
+      console.error(
+        `Error: cannot auto-bump "${pkg.version}": prerelease tail "${pre}" is not numeric. ` +
+          'Pass an explicit version instead (e.g. `node scripts/prepare-release.mjs 0.1.1-alpha.1`).',
+      )
+      process.exit(1)
+    }
+    const prefix = pre.slice(0, pre.length - tail.length) // "alpha." for "alpha.1"
+    target = {
+      major: Number(major),
+      minor: Number(minor),
+      patch: Number(patch),
+      prerelease: `${prefix}${Number(tail) + 1}`,
+    }
+  }
+}
+
+const version =
+  target.prerelease === undefined
+    ? `${target.major}.${target.minor}.${target.patch}`
+    : `${target.major}.${target.minor}.${target.patch}-${target.prerelease}`
+
+// Validate the npm dist-tag derived by the release workflow. A prerelease
+// identifier like "latest" would move the stable tag, and a numeric one like
+// "1" is not a legal npm tag. Reject both before the release PR is opened.
+if (target.prerelease !== undefined) {
+  const distTag = target.prerelease.split('.')[0]
+  if (distTag === 'latest' || !/^[a-z][a-z0-9-]*$/.test(distTag)) {
+    console.error(
+      `Error: prerelease "${target.prerelease}" maps to invalid npm dist-tag "${distTag}". ` +
+        'Use a prerelease such as alpha.1, beta.1, or rc.1.',
+    )
+    process.exit(1)
+  }
+}
+
+// Reject already-released versions: `git rev-parse v<version>` succeeds iff
+// the tag exists. Works unchanged for prerelease tags (v0.1.1-alpha.1 is a
+// plain tag name). Run from REPO_ROOT so the check is cwd-independent.
+try {
+  execFileSync('git', ['rev-parse', `v${version}`], { cwd: REPO_ROOT, stdio: 'ignore' })
+  console.error(`Error: tag v${version} already exists — this version is already released.`)
+  process.exit(1)
+} catch {
+  // Tag absent → OK to prepare.
+}
+
+// Fail fast on a no-change release: an empty notes range means no commits
+// since the previous release tag — prepare-release must not bump the version
+// or touch CHANGELOG.md for an empty release (no empty release PR). First-
+// ever releases (no ancestor tag yet) span the full first-parent history,
+// which is non-empty by construction, so they still pass.
+const { prevTag, notes } = resolveReleaseNotes()
+if (notes === '') {
+  console.error(
+    `Error: no commits since previous release tag ${prevTag === '' ? '<first commit>' : prevTag} — nothing to release. Aborting.`,
+  )
+  process.exit(1)
+}
+
+pkg.version = version
+// Preserve repo formatting: 2-space indent + trailing newline. The version
+// line must be the only diff (verified by `git diff package.json` in the
+// dry-run validation).
+writeFileSync(PKG_PATH, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8')
+
+/**
+ * Resolve the previous release tag (nearest ancestor tag of HEAD; empty
+ * when none exists yet) and the first-parent commit subjects since that
+ * tag (full first-parent history when no tag exists). Same git-log snippet
+ * the workflows use for the PR body — the CHANGELOG section and the PR body
+ * stay consistent. Do NOT use "v$VERSION^": the version string is not a
+ * git ref — the bump commit is not tagged yet.
+ */
+function resolveReleaseNotes() {
+  let prevTag = ''
+  try {
+    prevTag = execFileSync('git', ['describe', '--tags', '--abbrev=0', 'HEAD'], {
+      cwd: REPO_ROOT,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+  } catch {
+    // No ancestor tag yet → full history.
+  }
+  const range = prevTag === '' ? 'HEAD' : `${prevTag}..HEAD`
+  const notes = execFileSync('git', ['log', '--oneline', '--first-parent', range], {
+    cwd: REPO_ROOT,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim()
+  return { prevTag, notes }
+}
+
+/**
+ * Insert a `## [<version>] - <YYYY-MM-DD>` section under the `# Changelog`
+ * header, above the existing sections, from the pre-collected git-log notes
+ * (guaranteed non-empty by the no-change guard, so no fallback text is ever
+ * written). Preserves all existing sections; no-op when the section for this
+ * version already exists (idempotent re-runs must not duplicate it); write
+ * failures exit 1.
+ */
+function updateChangelog(version, notes) {
+  let content
+  try {
+    content = readFileSync(CHANGELOG_PATH, 'utf8')
+  } catch {
+    content = CHANGELOG_HEADER
+  }
+  // A 0-byte or whitespace-only CHANGELOG.md (e.g. manual truncation) is
+  // treated as missing: such a file must still bootstrap with the standard
+  // header, otherwise the new section would land at the top with leading
+  // blank lines and no `# Changelog` header.
+  if (content.trim() === '') {
+    content = CHANGELOG_HEADER
+  }
+
+  if (content.includes(`## [${version}]`)) {
+    return
+  }
+
+  const sectionHeader = `## [${version}] - ${new Date().toISOString().slice(0, 10)}`
+  const sectionBody = notes
+    .split('\n')
+    .map((line) => `- ${line}`)
+    .join('\n')
+  // The section's own trailing `\n` plus the inserted `\n` below form the
+  // blank-line separator between the new section and the existing sections.
+  const section = `${sectionHeader}\n\n${sectionBody}\n`
+
+  // Insert on the first `## [` section header via string slice: everything
+  // at and below the insertion point — including the file's exact trailing
+  // newline — is preserved byte-for-byte. (A split('\n')/splice/join('\n')
+  // round-trip would re-normalize line breaks and could alter the tail, e.g.
+  // appending a trailing newline that was not in the source file.)
+  const firstSectionMatch = /^## \[/m.exec(content)
+  const firstSectionIdx = firstSectionMatch === null ? -1 : firstSectionMatch.index
+  let next
+  if (firstSectionIdx === -1) {
+    // No sections yet — append the new section after the header block,
+    // keeping the file's own trailing-newline state.
+    next = content.endsWith('\n') ? `${content}\n${section}` : `${content}\n\n${section}`
+  } else {
+    next = `${content.slice(0, firstSectionIdx)}${section}\n${content.slice(firstSectionIdx)}`
+  }
+
+  try {
+    writeFileSync(CHANGELOG_PATH, next, 'utf8')
+  } catch (error) {
+    console.error(`Error: cannot write ${CHANGELOG_PATH}: ${error.message}`)
+    process.exit(1)
+  }
+}
+
+updateChangelog(version, notes)
+
+console.log(`VERSION=${version}`)

package/scripts/verify-dist.mjs

@@ -0,0 +1,30 @@
+/**
+ * Assert the built package contains every path the bundle manifest and the
+ * Web module loader resolve at runtime.
+ */
+import { access, readFile } from 'node:fs/promises'
+
+const REQUIRED = [
+  'lib/index.js',
+  'lib/index.d.ts',
+  'lib/client.js',
+  'lib/client/index.d.ts',
+  'bundle/cordis.patch.yml',
+  'locale/en.json',
+  'locale/zh.json',
+  'icon.svg',
+]
+
+for (const path of REQUIRED) {
+  try {
+    await access(path)
+  } catch {
+    throw new Error(`missing built artifact: ${path}`)
+  }
+}
+
+const client = await readFile('lib/client.js', 'utf8')
+if (!client.includes('dsh-keys-manager')) throw new Error('lib/client.js does not identify the bundle')
+if (!client.includes('__ModuleLoader__')) throw new Error('lib/client.js is not a module-loader bundle')
+
+console.log(`verified ${REQUIRED.length} artifacts`)

package/index.js

@@ -1,30 +0,0 @@
-// Placeholder stub for the `dsh-keys-manager` package name.
-// The real package ships from https://github.com/btspoony/dsh-keys-manager
-// via GitHub Actions OIDC trusted publishing (.github/workflows/release.yml).
-//
-// 0.0.0 is permanently reserved as the placeholder version: npm never allows
-// republishing the same version, so every real release must use a version
-// greater than 0.0.0.
-//
-// Load-time behavior: warn only, so bundler static analysis and accidental
-// transitive installs never crash at require/import time. Call-time behavior:
-// the exported function throws, so actual usage of this stub fails loudly
-// with an actionable message instead of being silently broken.
-
-'use strict';
-
-const MESSAGE =
-  'dsh-keys-manager@0.0.0 is a placeholder package. Install a real version (> 0.0.0) from https://github.com/btspoony/dsh-keys-manager';
-
-// Warn once at load time except in production builds (set
-// DSH_KEYS_MANAGER_WARN=1 to force the warning there too).
-if (process.env.NODE_ENV !== 'production' || process.env.DSH_KEYS_MANAGER_WARN === '1') {
-  console.warn(`[dsh-keys-manager] ${MESSAGE}`);
-}
-
-module.exports = function dshKeysManagerPlaceholder() {
-  throw new Error(MESSAGE);
-};
-
-// Machine-readable marker so tooling can detect the stub without importing it.
-module.exports.isPlaceholder = true;