dsh-nga-reader

A persistent dsh-plugin Cordis Host/Client bundle for browsing NGA, reading discussions and using selected content in AI conversations.

Best used with DeepDeck. DeepDeck supplies the Apps launcher, standalone reader window, app-scoped Workspace, settings and canonical conversations used by Explain and Summarize. This plugin expects DeepDeck's App runtime service when it is mounted.

Screenshot

NGA Reader supports guest browsing and keeps authentication optional until a personal or write action needs it. QR, account/password and existing token sign-in are available; the screenshot below uses an isolated guest profile and contains no account identifier or credential.

Install with DeepDeck (recommended)

1. Open Settings → Apps in DeepDeck.
2. Paste https://github.com/jo32/dsh-nga-reader.git into Install an App plugin.
3. Choose Inspect source, review the detected package and build command, then choose Confirm install.
4. Restart DeepDeck when prompted.
5. Open Apps → NGA Reader from the sidebar.

For local development, build the checkout and install the resulting local bundle into the active DeepDeck web profile:

git clone https://github.com/jo32/dsh-nga-reader.git
cd dsh-nga-reader
npm install
npm run typecheck && npm test
dsh plugin --profile web add "$PWD"

The last command only mounts the Cordis bundle; run it in a DeepDeck-managed profile so the required App runtime is present.

Usage examples

• Open a forum, select a topic and read paginated posts in the focused reader.
• Select text or right-click a post, then choose Explain or Summarize to open a canonical Session in ~/DeepDeck/Apps/nga-reader.
• Ask the DeepDeck agent: 列出 NGA 当前热门主题，并按版面分组。
• Ask about a selected topic: 阅读这个帖子，提炼主要共识、争议点和有用链接。
• Connect an account only when you need favorites, notifications, messages, check-in, voting or replies. Agent-triggered publishing remains approval-gated.

Features

• NGA forum discovery and filtering
• Topic lists, topic search, pagination, post reading, icons, avatars and images
• QR scan login (NGA App scan-to-authorize) and account password login
• Manual access_uid/token entry as a fallback
• Persistent local credential storage; explicit reply publishing
• Agent tools for forum discovery, topic reading and current UI context
• Reader window: the sidebar launcher promotes GET /nga-reader (a self-contained reader document) into a real secondary Electron app window through the desktop shell's deepdeck:open-app-window IPC request; without a desktop IPC parent it stays closed; the Client contains no embedded reader
• Text selection -> right-click -> Explain or Summarize in the standalone window; a same-origin BroadcastChannel starts a canonical app Session and opens that conversation directly in the main DeepDeck window

Extended NGA support

MNGA feature parity (ported from logic/service/src contracts):

• Daily check-in, notifications (typed: replies / mentions / votes / PMs)
• Short messages: conversations, thread reader with paging, reply and new messages to one or more recipients
• Favorites: forum favorites (list/add/remove), topic folders (list/create/ rename/set-default/delete), favorite topics per folder, favor/unfavor a topic
• Hot topics per forum with day/week/month range and reply sorting
• User profiles by uid or name (stats, signature, mute/ip, follow state, avatar fallback), follow/unfollow, follow list, follow activity feed
• Per-user topic lists and per-user post search (searchpost)
• Post voting (topic recommend up/down), reply draft fetch (quote/reply/modify verbatim incl. attachment auth), report post, subforum filter block/show
• Signature update; notification read-state tracked client-side in the session
• Standalone-window UI: drawer panels for notifications / messages / favorites / user cards, clock-in and hot-topics buttons, vote and favor actions on posts

Agent tools added for agentic access: nga_clock_in, nga_notifications, nga_short_messages, nga_read_message, nga_send_message (approval-gated), nga_favorite_forums, nga_hot_topics, nga_user, nga_user_topic_list, nga_vote_post. The full action set is also exposed on /api/nga-reader (clock-in, notis, msg-*, fav-*, user*, follow-*, vote, reply-draft, report, signature, subforum-filter).

Authentication and credential storage

Login implementation notes:

• QR keys come from nuke.php?__act=qrlogin_gen; the QR encodes the official qrlogin_ui URL, and __act=login with qrkey/hiddenkey exchanges the authorization for uid/token (pending state: "license not found").
• Passwords are RSA (PKCS#1 v1.5) encrypted with the official web public key before submission, matching the passport page behavior.
• The QR image is generated locally by the vendored Nayuki QR encoder (src/vendor/qrcodegen.py, copied to lib/ during builds, MIT); no third-party QR service is used.

The Host persists only the NGA uid and access token as the plugin-owned dsh-nga-reader-plugin/nga-account grant in the Harness credential document $DSH_HOME/.credentials.yaml (default: ~/.dsh/.credentials.yaml). Account passwords are never stored. The mounted credentials-local service owns atomic writes, cross-process locking, private file permissions and durable reloads. The plugin reads the record for each NGA operation instead of caching the token as plugin state, and its Sign out action deletes that record.

Development

npm install
npm run typecheck
npm test
npm run build

The plugin is authored in strict TypeScript under src/ and compiled to the ESM/runtime artifacts under lib/. The Python helper remains an implementation detail for NGA HTTP requests and local QR generation. Generated lib/ output is not committed.

License

MIT. The vendored Nayuki QR Code generator in src/vendor/qrcodegen.py retains its included MIT notice.