39 lines
3.7 KiB
Markdown
39 lines
3.7 KiB
Markdown
# Repository Working Rules
|
|
|
|
## Scope and architecture
|
|
|
|
- This repository implements one lightweight stdio bridge and one unified remote gateway for DingTalk OA and XFT approvals.
|
|
- The supported customer architecture uses one gateway OAuth login for both approval sources. Do not reintroduce a local DWS dependency or a second user login without explicit product approval.
|
|
- The gateway must derive identity from its verified OAuth token. Never accept caller-supplied `userId`, employee ID, owner ID, or equivalent identity selectors.
|
|
- The gateway must not persist approval bodies, expense details, attachments, or upstream schemas; they remain real-time. The only exception is a user-explicit local submission draft stored on the Agent machine under the current OS user's private data directory. Local drafts must never be uploaded to the gateway or repository, and every resumed draft must be revalidated against the live template schema before submission.
|
|
|
|
## Git workflow
|
|
|
|
- Use Git for every source, documentation, test, deployment, and distribution change.
|
|
- Keep `main` releasable. Develop non-trivial changes on short-lived branches named `feat/<topic>`, `fix/<topic>`, `docs/<topic>`, or `chore/<topic>`.
|
|
- Prefer small, atomic commits using Conventional Commit subjects such as `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, and `chore:`.
|
|
- Do not rewrite published history, force-push, or delete remote branches/tags unless the user explicitly requests it.
|
|
- Before commit, run `npm test`, relevant distribution checks, and `git diff --check`. Update docs when architecture, installation, tools, authentication, or deployment changes.
|
|
- Releases should be tagged only from a tested `main` commit. Do not commit generated `dist`, `release`, test bundles, package archives, or npm caches.
|
|
|
|
## Secrets and privacy
|
|
|
|
- Never commit `.secrets`, `.runtime`, `.env`, the root `secret` file, OAuth databases, tokens, cookies, credentials, approval data, or machine-specific absolute paths.
|
|
- Before the first push and every release, inspect the staged file list and scan it for likely secrets.
|
|
- Logs, tests, fixtures, and support references must not expose access tokens, AppSecret, AuthoritySecret, private approval IDs, internal user IDs, or raw upstream payloads.
|
|
|
|
## Testing and safety
|
|
|
|
- All approval reads and writes in product tests must go through MCP tools; do not bypass MCP to claim end-to-end coverage.
|
|
- Automated tests must use mocks unless the user explicitly authorizes a real approval write. Never run real reject or return actions implicitly.
|
|
- Preserve the distinction between `failed`, `succeeded`, and `outcome_uncertain`; never automatically retry an uncertain write.
|
|
- Keep opaque approval references user-bound, source-bound, expiring, and revalidated against live ownership before every write.
|
|
|
|
## Deployment and distribution
|
|
|
|
- Use `./deploy/install.sh` for gateway installation and updates and `./deploy/uninstall.sh` for gateway removal. These are server-operator commands; keep both idempotent and preserve server secrets by default.
|
|
- Customer installation and updates must use the signed native client installer. Do not reintroduce global npm installation, Node-version-specific MCP paths, prose-only installation, or direct mutation of host-private configuration.
|
|
- Release manifests must be Ed25519 signed. Never commit, publish, or expose the release private key; release verification must fail closed on missing/invalid signatures or artifact hashes.
|
|
- Customer installation must remain user-level, lightweight, and free of enterprise credentials. The distributed MCP command is `dingtalk-approval-bridge` pointing at the HTTPS gateway.
|
|
- A complete test release must expose both DingTalk OA and XFT. Treat either source being disabled as a release error.
|