dsh-agora 0.2.0

package/assets/agora/references/testing-guidance/rtc-react.md

@@ -0,0 +1,51 @@
+# Testing Guidance — RTC React (`agora-rtc-react`)
+
+Mock at the hooks boundary. `agora-rtc-react` wraps `agora-rtc-sdk-ng` — mock the
+hooks directly rather than re-mocking the underlying SDK.
+
+Pattern: mock the `agora-rtc-react` module and wrap components under a mock provider.
+
+```javascript
+jest.mock('agora-rtc-react', () => ({
+  AgoraRTCProvider: ({ children }) => children,
+  useLocalMicrophoneTrack: jest.fn().mockReturnValue({
+    localMicrophoneTrack: null,
+    isLoading: false,
+    error: null,
+  }),
+  useLocalCameraTrack: jest.fn().mockReturnValue({
+    localCameraTrack: null,
+    isLoading: false,
+    error: null,
+  }),
+  useRemoteUsers: jest.fn().mockReturnValue([]),
+  useJoin: jest.fn().mockReturnValue({ isConnected: false, isLoading: false }),
+  usePublish: jest.fn(),
+}))
+```
+
+For integration tests that need real hook behavior, wrap the component under a real
+`AgoraRTCProvider` with a mocked `IAgoraRTCClient` injected as the `client` prop.
+
+Example:
+
+```javascript
+import { render, screen } from '@testing-library/react'
+import { useRemoteUsers } from 'agora-rtc-react'
+
+test('renders remote users returned by the hook', () => {
+  useRemoteUsers.mockReturnValue([{ uid: 42 }, { uid: 43 }])
+
+  render(<CallGrid />)
+
+  expect(screen.getByTestId('remote-user-42')).toBeInTheDocument()
+  expect(screen.getByTestId('remote-user-43')).toBeInTheDocument()
+})
+```
+
+Primary assertions:
+
+- loading and error states from hooks render correctly
+- join/publish hooks are called with expected inputs
+- remote user state updates the UI
+- provider cleanup occurs on unmount if the component owns client lifecycle

package/assets/agora/references/testing-guidance/rtc-web.md

@@ -0,0 +1,94 @@
+# Testing Guidance — RTC Web (`agora-rtc-sdk-ng`)
+
+Mock at the module boundary. The key interfaces to mock:
+
+- `AgoraRTC.createClient()` → mock client with `join`, `leave`, `publish`, `subscribe`
+- `AgoraRTC.createMicrophoneAudioTrack()` / `createCameraVideoTrack()` → mock tracks
+- `client.on(event, handler)` → capture event handlers for test assertions
+
+Pattern: use Jest's `jest.mock` with a manual mock file.
+
+```javascript
+// __mocks__/agora-rtc-sdk-ng.js
+const mockClient = {
+  join: jest.fn().mockResolvedValue(undefined),
+  leave: jest.fn().mockResolvedValue(undefined),
+  publish: jest.fn().mockResolvedValue(undefined),
+  subscribe: jest.fn().mockResolvedValue(undefined),
+  renewToken: jest.fn().mockResolvedValue(undefined),
+  on: jest.fn(),
+  off: jest.fn(),
+};
+
+const mockTrack = {
+  play: jest.fn(),
+  stop: jest.fn(),
+  close: jest.fn(),
+  setEnabled: jest.fn().mockResolvedValue(undefined),
+  getVolumeLevel: jest.fn().mockReturnValue(0.5),
+};
+
+const AgoraRTC = {
+  createClient: jest.fn().mockReturnValue(mockClient),
+  createMicrophoneAudioTrack: jest.fn().mockResolvedValue({ ...mockTrack }),
+  createCameraVideoTrack: jest.fn().mockResolvedValue({ ...mockTrack }),
+};
+
+module.exports = AgoraRTC;
+module.exports.default = AgoraRTC;
+```
+
+In tests, call `jest.mock('agora-rtc-sdk-ng')` at the top of the file to activate the
+manual mock automatically.
+
+Capture event handlers so tests can simulate SDK callbacks:
+
+```javascript
+test('subscribes when user-published fires', async () => {
+  const handlers = {}
+  mockClient.on.mockImplementation((event, cb) => {
+    handlers[event] = cb
+  })
+
+  render(<VideoCall />)
+
+  const user = {
+    uid: 42,
+    audioTrack: { play: jest.fn() },
+    videoTrack: { play: jest.fn() },
+  }
+
+  const onUserPublished = handlers['user-published']
+  await onUserPublished(user, 'audio')
+
+  expect(mockClient.subscribe).toHaveBeenCalledWith(user, 'audio')
+  expect(user.audioTrack.play).toHaveBeenCalled()
+})
+```
+
+Token renewal is a required production behavior:
+
+```javascript
+test('renews token before expiry', async () => {
+  global.fetch = jest.fn().mockResolvedValue({
+    ok: true,
+    json: async () => ({ token: 'new-token-xyz' }),
+  })
+
+  const handler = mockClient.on.mock.calls
+    .find(([e]) => e === 'token-privilege-will-expire')[1]
+
+  await handler()
+
+  expect(fetch).toHaveBeenCalledWith(expect.stringContaining('/token'))
+  expect(mockClient.renewToken).toHaveBeenCalledWith('new-token-xyz')
+})
+```
+
+Primary assertions:
+
+- joins the correct channel/UID
+- publishes expected tracks
+- subscribes after remote publish events
+- renews token before expiry
+- stops and closes tracks before leave

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-agora bundle patch: insert the bundled skill provider row.
+# Installed via `dsh plugin --profile <name> add <pkg>`; takes effect on restart.
+- insert:
+    - id: agora-skills
+      name: 'dsh-agora'

package/index.js

@@ -0,0 +1,53 @@
+// dsh-agora — bundled skill provider for DeepSeek Harness.
+//
+// Registers the `agora` skill on ctx.skills, mirroring the official
+// `@deepseek-ai/dsh-skill-badge` provider pattern: a Cordis plugin whose
+// apply() registers one immutable provider. The SKILL.md body and references/
+// live in assets/agora/ and are synced verbatim from AgoraIO/skills at a
+// pinned release tag (see scripts/sync-deps.sh) — zero rewrite, no drift.
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { BUNDLED_SKILL_RANK } from '@deepseek-ai/dsh-skill'
+
+const PROVIDER_NAME = 'agora'
+const SKILL_DIR_URL = new URL('./assets/agora/', import.meta.url)
+const SKILL_BODY_URL = new URL('./assets/agora/SKILL.md', import.meta.url)
+const RESOURCE_BASE = {
+  kind: 'directory',
+  path: fileURLToPath(SKILL_DIR_URL),
+}
+
+const CANDIDATE = {
+  name: 'agora',
+  description:
+    'Activate when the user wants to build voice AI agents, video or voice calls, live streaming, screen sharing, in-app messaging and presence, recording, token or auth flows, or use the `agora` CLI for login, quickstarts, env setup, diagnostics, introspection, skills, or MCP serving, especially when integrating Agora into an app.',
+  invocation: {
+    modelInvocable: true,
+    userInvocable: true,
+  },
+  provider: PROVIDER_NAME,
+  source: 'bundled',
+  resourceBase: RESOURCE_BASE,
+  rank: BUNDLED_SKILL_RANK,
+  locator: SKILL_BODY_URL,
+}
+
+const provider = {
+  name: PROVIDER_NAME,
+  list: () => Promise.resolve([CANDIDATE]),
+  async get(_candidate) {
+    return {
+      ...CANDIDATE,
+      content: await readFile(SKILL_BODY_URL, 'utf8'),
+    }
+  },
+}
+
+/** Cordis plugin name. */
+export const name = 'agora-skills'
+/** Service required by the bundled provider. */
+export const inject = ['skills']
+/** Register the bundled `agora` provider on `ctx.skills`. */
+export function apply(ctx) {
+  ctx.skills.registerProvider(() => provider)
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "dsh-agora",
+  "version": "0.2.0",
+  "description": "DSH skill bundle: the Agora skill (RTC, RTM, ConvoAI, CLI, Cloud Recording, tokens) synced verbatim from AgoraIO/skills at a pinned release tag. Install to add the `agora` skill to DeepSeek Harness.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "cordis.patch.yml",
+    "assets/agora"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/littleDogWang/dsh-agora.git"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "plugin",
+    "skill",
+    "agora",
+    "conversational-ai",
+    "rtc",
+    "rtm",
+    "voice-ai"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "sync:deps": "bash scripts/sync-deps.sh",
+    "prepack": "bash scripts/sync-deps.sh"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-skill": "^0.1.0-rc.7",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-skill": "^0.1.0-rc.7"
+  }
+}