AGENTS.md

1# Chat2DB Community Agent Contract
2 
3## Context
4 
5This file applies to the entire repository. Chat2DB Community is a Java 17,
6Spring Boot, Maven, React, TypeScript, and Umi application distributed as a web
7application, Docker image, and JCEF desktop package.
8 
9The current repository is the source of truth for current behavior. A user
10request can define a desired behavior change, but it does not turn a historical
11assumption into fact or grant permission for an unrelated external action.
12 
13Instruction authority and factual evidence are separate:
14 
15- Follow applicable higher-level instructions, then the nearest scoped
16  `AGENTS.md`, then the latest user request. At the same authority level, the
17  newer explicit instruction wins.
18- For current checkout behavior, prefer current source and tests, then
19  repository-local workflows and scripts, and then documentation. For current
20  runtime state, live evidence wins only after the process `cwd`, artifact,
21  branch/ref, or equivalent provenance ties it to the intended checkout.
22  Unproven processes from another checkout do not override source facts.
23  Prior memory or subagent reports rank below inspected evidence; inference is
24  last.
25- Treat prior memory and subagent output as potentially stale leads. Verify
26  consequential claims against this checkout and never let memory authorize a
27  mutation or external action.
28- Do not write durable memory about the repository unless the user explicitly
29  asks for it. Never carry secrets or user data into memory.
30 
31### Product invariants
32 
33- Backend Community behavior is selected by
34  `-Dchat2db.runtime.mode=community`.
35- Frontend Community behavior is selected by `UMI_ENV=community`.
36- `-Dchat2db.finalName=chat2db-community` changes the artifact name only; it is
37  not a runtime-mode signal.
38- Community desktop/package scripts and the documented local backend command
39  bind `127.0.0.1:10825`. The Community frontend dev server uses port `8889`
40  and proxies to that backend. `application-dev.yml` sets only port `10825`, so
41  local launchers must pass the address when loopback-only behavior is required.
42- The Docker container intentionally listens on `0.0.0.0:10825` internally;
43  Compose limits the default host publication to `127.0.0.1:10825`.
44- Packaged Community desktop runtime is offline-first and local: keep
45  `-Dchat2db.network.status=OFFLINE`, loopback binding, Community identity, and
46  Community storage paths intact unless the task explicitly changes the
47  product contract.
48- Do not reintroduce Enterprise Gateway forwarding, cloud account,
49  subscription, payment, commercial license, Local-edition packaging, or
50  Electron runtime paths into Community code.
51- Community desktop supports in-app updates. Keep the renderer update UI and
52  state, JCEF update handlers, updater metadata, packaged payloads, and Windows
53  elevated updater helper aligned when changing the release format.
54- Do not treat hidden frontend UI as backend isolation. Remote calls, headers,
55  cookies, controllers, and service registration must also be Community-safe.
56- Preserve public API, storage, datasource, namespace, console, task, pin,
57  operation-log, and ER-position semantics unless an explicit compatibility or
58  migration change is requested.
59 
60### Repository map
61 
62- `chat2db-community-client/`: Umi/React frontend and JCEF renderer bridge.
63- `chat2db-community-server/`: Maven reactor containing domain, storage, web,
64  JCEF, SPI, plugin, tools, and startup modules.
65- `chat2db-community-server/chat2db-community-start/`: executable backend,
66  configuration, assembled frontend resources, and final jar.
67- `chat2db-community-server/chat2db-community-plugins/`: database-specific
68  implementations. Keep dialect-specific behavior inside the owning plugin.
69- `docker/`: Community image, Compose file, and local image build entry point.
70- `script/package/`: Community desktop preparation, metadata, and native
71  packaging entry points.
72- `jpackage/`: only versioned native packaging resources belong in source;
73  runtime images, staged jars/libraries, renderer output, and installers are
74  generated.
75- `.github/workflows/`: Community desktop artifact and Docker publication
76  workflows.
77- `spec/code/server/`: maintained Java boundary and contract documentation.
78  These Markdown files are rules, not executable checks.
79 
80### Structural code navigation
81 
82Use CodeGraph for structural questions when `.codegraph/` is initialized and
83the CodeGraph tools are available:
84 
85- `codegraph_context` first for a feature, architecture, or bug path.
86- `codegraph_explore` once for the related source surfaced by context.
87- `codegraph_search` for symbol lookup, `codegraph_callers` and
88  `codegraph_callees` for call paths, and `codegraph_impact` before shared
89  symbol changes.
90- `codegraph_files` for indexed source-tree exploration and
91  `codegraph_status` for index health.
92 
93Use `rg` for literal strings, configuration keys, logs, comments, generated
94flags, and command lines. Do not repeat CodeGraph results with a grep/read loop.
95The index can lag writes, and build tools remain the correctness authority. If
96CodeGraph is unavailable, use focused native file reads and `rg` without
97pretending indexed results exist. If the repository has no initialized
98CodeGraph index, ask before creating one.
99 
100## Request
101 
102Classify the request before acting:
103 
104- Answer, explain, review, diagnose, and status requests are read-only by
105  default. Use non-mutating inspection and report evidence; do not edit files,
106  run mutation-heavy builds, or implement a fix unless requested.
107- Change, fix, and cleanup requests authorize local source edits and relevant
108  local commands within the named scope. A build request authorizes build
109  commands, dependency caches, and generated output only; it does not authorize
110  source repair unless the user also asks for a fix.
111- Commit, push, tag, workflow dispatch, publication, deployment, signing, and
112  production or customer-data actions require explicit authorization for that
113  external effect.
114 
115For an authorized implementation task, deliver the requested outcome end to
116end within the smallest coherent scope.
117 
1181. Confirm the exact repository, branch, status, and existing user changes.
1192. Read the nearest implementation, tests, configuration, and workflow before
120   editing. Trace cross-layer behavior when a change spans frontend, backend,
121   storage, Docker, or desktop packaging.
1223. Classify the change by affected surface and choose verification from the
123   matrix below.
1244. Edit narrowly. Follow existing module ownership and local conventions.
1255. Run the relevant checks, inspect the final diff, and distinguish executed
126   verification from checks that were not available.
1276. Report the result, remaining risk, and exact uncommitted or unpushed state.
128 
129### Backend boundaries
130 
131- Keep controllers and transport adapters thin. Business behavior belongs in
132  domain services; persistence belongs behind storage APIs/providers.
133- Preserve Maven module direction and the contracts documented under
134  `spec/code/server/`. Do not bypass domain APIs with new web-to-storage
135  coupling.
136- Use Java 17 and existing Spring/MyBatis/Lombok patterns. Avoid introducing a
137  parallel framework or utility abstraction for behavior already owned by a
138  module.
139- New Community runtime branches must use the real runtime-mode signal. Never
140  infer mode from jar name, app name, port, or artifact path.
141- Changes to shared request context, identity, Gateway isolation, storage
142  routing, AI services, or JCEF startup require explicit call-path and
143  regression review.
144- Keep database-specific SQL, metadata, completion, and type behavior in its
145  plugin. Add focused plugin tests for dialect changes.
146 
147### Frontend boundaries
148 
149- Use TypeScript, React, Umi, Zustand, Ant Design, and existing project
150  components and service helpers.
151- Community conditions must derive from the current runtime-edition helpers or
152  `UMI_ENV=community`; do not scatter unrelated environment checks.
153- Do not add Electron APIs, `ipcRenderer`, Electron packaging, or a duplicate
154  desktop bridge. Desktop renderer communication uses the existing JCEF
155  `window.javaQuery` wrappers.
156- Preserve service response contracts and storage keys. UI removal does not
157  authorize deleting a backend contract that another Community path uses.
158- Keep user-facing strings in the existing i18n system when the surrounding
159  feature is localized.
160 
161### Configuration and generated files
162 
163- Never commit credentials, tokens, signing material, private URLs, local
164  database contents, IDE files, runtime downloads, Maven/Yarn output, frontend
165  `dist`, staged `jpackage` content, or installers.
166- Read secrets only when the explicitly authorized operation requires them.
167  Never print, log, paste, summarize, or persist secret values. Do not reuse a
168  credential for a different repository, registry, account, or environment.
169- Do not access or mutate production data, user data, or an unrelated local
170  database for build or diagnostic convenience. Use fixtures or a named local
171  test datasource unless the user explicitly places another system in scope.
172- Keep desktop and host-published listeners on loopback unless remote exposure
173  is explicitly requested and documented with its security impact. Do not
174  change the container's required internal `0.0.0.0` binding to enforce a host
175  publication policy.
176- Keep these six `jpackage/input` resources versioned:
177  `icons/community/logo.icns`, `icons/community/logo.ico`,
178  `icons/community/logo.png`, `macres/Info.plist`, `win/updater.jar`, and
179  `win/run-as-admin.vbs`.
180- Treat `target/`, frontend `dist/`, `jpackage/output/`,
181  `jpackage/input/runtime/`, and generated platform content such as
182  `chat2db-community.jar`, `dist/`, `lib/`, and macOS `Frameworks/` as
183  reproducible output. Do not
184  remove a tracked resource merely because it shares a parent directory with
185  generated files.
186- Update README and workflow examples when a public command, port, artifact,
187  environment variable, or release input changes.
188 
189## Output Format
190 
191At handoff, state:
192 
193- what behavior changed and which files own it;
194- which commands were actually run and whether they passed;
195- any verification that remains CI-only, platform-only, or otherwise unrun;
196- the current Git state, including unrelated modifications left untouched; and
197- every attempted external action and its commit, remote branch, workflow run,
198  image, release, or artifact identifier, including partial or failed actions.
199 
200For code review, report findings first in severity order with `file:line`, the
201affected runtime surface, the behavioral risk, and the required fix or missing
202evidence. If there are no findings, say so and list residual test gaps.
203 
204Do not claim that a build ran tests when Maven was invoked with
205`-Dmaven.test.skip=true`. Do not claim a native package works from shell syntax
206or `prepare` alone.
207 
208## Constraints
209 
210### Baseline commands
211 
212Use Java 17, Maven 3.8 or later, Node.js 18 or later, and Yarn with the checked-in
213`chat2db-community-client/yarn.lock`.
214 
215Frontend setup and verification:
216 
217```bash
218cd chat2db-community-client
219yarn install --frozen-lockfile
220yarn run lint
221yarn run test:sql-in-clipboard
222yarn run build:web:community --app_version=0.0.0
223```
224 
225Run a focused backend test with tests explicitly enabled because the parent BOM
226defaults `maven.test.skip` to `true`. The reactor POM also has a stale Surefire
227include and `testFailureIgnore=true`; override both. Replace the example module
228and test with the owning artifact ID and test class:
229 
230```bash
231MODULE=:chat2db-community-spi
232TEST=DefaultSqlBuilderSegmentTest
233mvn -B -f chat2db-community-server/pom.xml \
234  -pl "${MODULE}" -am \
235  -Dmaven.test.skip=false -DskipTests=false \
236  -Dtest="${TEST}" \
237  -Dsurefire.failIfNoSpecifiedTests=false \
238  -Dmaven.test.failure.ignore=false \
239  test
240```
241 
242For the owning module's full test set, replace `-Dtest` with the quoted argument
243`'-Dsurefire.includes=**/*Test.java'`. This can surface stale test-compilation
244failures elsewhere in that module; report those instead of weakening test
245discovery. Always confirm the Surefire summaries report a nonzero test count
246with zero failures and errors; `BUILD SUCCESS` alone is not sufficient in this
247reactor.
248 
249Build the executable Community backend:
250 
251```bash
252mvn -B clean package \
253  -Dmaven.test.skip=true \
254  -Dchat2db.finalName=chat2db-community \
255  -f chat2db-community-server/pom.xml \
256  -pl chat2db-community-start -am
257```
258 
259Run it locally with the explicit Community contract:
260 
261```bash
262java -Dloader.path=chat2db-community-server/chat2db-community-start/target/lib \
263  -Dchat2db.gui=false \
264  -Dchat2db.runtime.mode=community \
265  -Dchat2db.network.status=OFFLINE \
266  -Dserver.address=127.0.0.1 \
267  -Dserver.port=10825 \
268  -Dspring.profiles.active=dev \
269  -jar chat2db-community-server/chat2db-community-start/target/chat2db-community.jar
270```
271 
272Build local distribution surfaces only when relevant:
273 
274```bash
275./docker/docker-build.sh 0.0.0-local chat2db-community:local
276docker compose -f docker/docker-compose.yml config
277script/package/package-community-jcef.sh 0.0.0-local prepare
278```
279 
280The desktop script's `mac`, `linux`, and `win` targets are platform-specific and
281may download a JBR. Signed macOS packages require CI secrets. A manual desktop
282workflow dispatch only uploads GitHub Actions artifacts. Pushing a numeric
283`v5.3.0`-style tag validates all nine native installers, adds `SHA256SUMS`,
284stages a draft GitHub Release, calls the reusable Docker workflow for the
285versioned and `latest` tags, and publishes the Release only after Docker
286succeeds. Neither path uploads to the updater CDN. These are external
287publication actions, not routine local verification commands.
288 
289### Tool and environment boundaries
290 
291- For an authorized change/build task, repository edits, generated build
292  output, standard Maven/Yarn caches, and ordinary dependency downloads are
293  allowed. Do not change global package-manager configuration or install system
294  packages unless the task requires it and the impact is explicit.
295- Starting a local service is allowed only when needed for the requested smoke
296  test. Inspect the port first, bind to loopback, record the process, and stop
297  only the process started for this task. Never bounce an unrelated service.
298- Docker build and task-scoped test containers/images are allowed for a Docker
299  build request. Do not prune the daemon, remove unrelated resources, or start
300  Compose services that are outside the task.
301- Use only named local/test databases for autonomous verification. Schema/data
302  mutation in shared, staging, or production systems requires explicit scope,
303  a recovery plan, and authorization.
304- Read-only network access for dependency resolution and public source checks
305  is allowed when needed. Authenticated writes, uploads, workflow dispatches,
306  messages, and publication remain external actions requiring explicit user
307  authority.
308- If a required tool is unavailable, report the missing check or use an
309  equivalent read-only fallback. Do not fabricate tool output or silently
310  broaden the environment.
311 
312### Verification matrix
313 
314- Frontend logic, route, service, or state: relevant focused test, `yarn run
315  lint`, and `build:web:community`.
316- Backend domain, web, storage, SPI, or plugin code: focused tests with Maven
317  tests explicitly enabled, the stale Surefire include and failure-ignore
318  behavior overridden, and a confirmed nonzero test count; then package the
319  affected module and dependencies.
320- Shared API or persistence contract: add compatibility coverage and inspect
321  callers plus serialization/storage effects.
322- Runtime-mode, identity, Gateway, AI, or network isolation: inspect both the
323  registration path and call path; run a Community-mode smoke when feasible.
324- JCEF Java bridge: focused JCEF tests, reactor compile/package, and matching
325  renderer bridge verification.
326- Desktop scripts/resources: `bash -n` for touched shell scripts, plist or
327  platform metadata validation, `prepare`, and cross-platform workflow review.
328  Only claim native installer success for an installer actually built and run
329  on its target platform.
330- Docker: script syntax, Compose expansion, image build, and an HTTP/static
331  asset smoke when Docker is available.
332- Workflow YAML: parse or inspect the resolved workflow inputs and commands;
333  distinguish artifact upload from GitHub Release publication and CDN upload.
334- Documentation-only changes: verify commands, links, paths, ports, and names
335  against current source and workflows.
336- Every change: `git diff --check`, focused diff review, and final `git status`.
337 
338### Git and external-action rules
339 
340- Preserve unrelated user changes, including changes in files you also need to
341  edit. Never reset, checkout, clean, or overwrite them to simplify the task.
342- Do not use destructive Git commands. Do not remove local data or generated
343  caches outside the requested scope.
344- Do not stage, commit, push, tag, dispatch workflows, publish releases, upload
345  packages, or push images unless the user explicitly requests that action.
346- When commit or push is requested, stage only the intended semantic scope,
347  inspect the staged diff, check it for credentials or generated output, run
348  its checks, and verify local/remote commit IDs.
349- Treat workflow dispatch, release publication, Docker push, CDN upload,
350  `latest` updates, and signing as external mutations with an explicit approval
351  boundary.
352 
353## Checkpoint
354 
355Continue autonomously for normal read, edit, build, and test work within the
356requested scope. Stop and ask only when one of these conditions materially
357changes the result:
358 
359- applicable instructions conflict, or the desired behavior remains ambiguous
360  after current source has established the existing behavior;
361- the task requires deleting user data, changing a public compatibility
362  contract, exposing a listener, or crossing into Enterprise/Local behavior;
363- credentials, signing identity, release destination, or production authority
364  are missing;
365- an irreversible or externally visible action was not explicitly requested;
366- unrelated user edits make the requested change unsafe to isolate; or
367- required verification still fails after one diagnosis-and-repair cycle and
368  no safe in-scope recovery remains.
369 
370Retry a transient, idempotent operation at most twice. Never blindly repeat a
371push, workflow dispatch, release, upload, signing request, or other external
372mutation after an ambiguous result. Inspect the remote or provider state first.
373After interruption or partial completion, recheck branch, worktree, remote, and
374workflow state before resuming.
375 
376On failure, keep the worktree recoverable, record the exact command and error,
377avoid unsupported success claims, and hand off the current goal, evidence,
378actions already attempted, identifiers, open risks, and next safe action.
379