Mercurial

annotate .claude/skills/zenbu-bazel-c/SKILL.md @ 264:04fee26ecce0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
add authenticated JRPG conversation platform Add reusable auth/session storage, owned conversation recovery, guest quotas, admin workflows, URL-routed conversation UI, mobile frame support, and parallel browser acceptance. Co-authored-by: Copilot <[email protected]>
author MrJuneJune <me@mrjunejune.com>
date Fri, 07 Aug 2026 07:34:12 -0700
parents 5ec271d612ae
children 056790c4fb0d
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
248
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
1 ---
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
2 name: zenbu-bazel-c
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
3 description: Use this skill when working anywhere in the Zenbu monorepo, especially C/C++ libraries, Bazel targets, Mercurial workflow, shared assets, or cross-project dependencies.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
4 ---
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
5
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
6 # Zenbu Bazel/C Monorepo
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
7
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
8 Use this skill to orient yourself before changing first-party code in this workspace.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
9
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
10 ## What this repo is
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
11
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
12 Zenbu is a Mercurial/Bazel monorepo for reusable C libraries, web servers, frontend bundles, and experiments. Prefer first-party libraries over adding new external dependencies.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
13
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
14 Important first-party packages:
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
15
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
16 - `dowa`: core C utilities, arena allocation, strings, math, dynamic arrays/hash maps.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
17 - `seobeo`: HTTP/TCP/WebSocket/networking library.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
18 - `mrjunejune`: personal website and production server.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
19 - `hg-web`: Mercurial repository browser served by a C backend.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
20 - `markdown_converter`: markdown-to-HTML C/WASM converter.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
21 - `deita`: SQLite wrapper library.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
22 - `s3`: S3 presigned upload helper.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
23 - `gui_ze`: Bazel macros for bundling/copying web assets.
251
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents: 248
diff changeset
24 - `design_system`: light-DOM Web Components, shared CSS tokens, and a Seobeo
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents: 248
diff changeset
25 component catalog.
248
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
26
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
27 Avoid broad searches in `third_party/`, Bazel output directories, virtualenvs, `node_modules`, and generated bundles unless the task specifically requires them.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
28
255
5ec271d612ae [dowa] Enforce arena ownership
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
29 For cross-codebase audits, inspect `BUILD` files and Bazel dependencies first.
5ec271d612ae [dowa] Enforce arena ownership
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
30 Use the dependency graph to identify actual first-party consumers before broad
5ec271d612ae [dowa] Enforce arena ownership
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
31 text search, then audit only those targets and their transitive owners.
5ec271d612ae [dowa] Enforce arena ownership
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
32
248
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
33 ## Build and test commands
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
34
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
35 Use Bazel targets from the repository root:
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
36
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
37 ```bash
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
38 bazel build //seobeo:seobeo
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
39 bazel test //seobeo:seobeo_client_test
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
40 bazel test //seobeo:seobeo_websocket_test
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
41 bazel test //seobeo:seobeo_websocket_server_test
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
42
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
43 bazel build //mrjunejune:mrjunejune_server
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
44 bazel test //mrjunejune/test:integration_test
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
45
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
46 bazel build //hg-web:hg_web_server
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
47 ```
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
48
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
49 For debug builds, prefer existing debug targets where present:
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
50
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
51 ```bash
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
52 bazel build //mrjunejune:mrjunejune_server_debug -c dbg
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
53 bazel build //seobeo:seobeo_debug -c dbg
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
54 ```
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
55
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
56 If a change only touches docs or assistant skill files, Bazel verification is not required.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
57
264
04fee26ecce0 add authenticated JRPG conversation platform
MrJuneJune <me@mrjunejune.com>
parents: 255
diff changeset
58 ### Parallel test structure
04fee26ecce0 add authenticated JRPG conversation platform
MrJuneJune <me@mrjunejune.com>
parents: 255
diff changeset
59
04fee26ecce0 add authenticated JRPG conversation platform
MrJuneJune <me@mrjunejune.com>
parents: 255
diff changeset
60 - Do not let unrelated browser, integration, or end-to-end concerns accumulate
04fee26ecce0 add authenticated JRPG conversation platform
MrJuneJune <me@mrjunejune.com>
parents: 255
diff changeset
61 in one long serial test process.
04fee26ecce0 add authenticated JRPG conversation platform
MrJuneJune <me@mrjunejune.com>
parents: 255
diff changeset
62 - Split slow suites into independently runnable Bazel test targets by concern.
04fee26ecce0 add authenticated JRPG conversation platform
MrJuneJune <me@mrjunejune.com>
parents: 255
diff changeset
63 Use a `test_suite` target to preserve a single aggregate command.
04fee26ecce0 add authenticated JRPG conversation platform
MrJuneJune <me@mrjunejune.com>
parents: 255
diff changeset
64 - Run related targets in one `bazel test` invocation so Bazel schedules them in
04fee26ecce0 add authenticated JRPG conversation platform
MrJuneJune <me@mrjunejune.com>
parents: 255
diff changeset
65 parallel. Do not loop over targets or invoke Bazel separately for each test.
04fee26ecce0 add authenticated JRPG conversation platform
MrJuneJune <me@mrjunejune.com>
parents: 255
diff changeset
66 - Parallel shards must use independent ports, temporary directories, databases,
04fee26ecce0 add authenticated JRPG conversation platform
MrJuneJune <me@mrjunejune.com>
parents: 255
diff changeset
67 and mutable fixtures. Never share process-global test state between shards.
04fee26ecce0 add authenticated JRPG conversation platform
MrJuneJune <me@mrjunejune.com>
parents: 255
diff changeset
68 - During iteration, run only the narrow shard for the changed behavior; run the
04fee26ecce0 add authenticated JRPG conversation platform
MrJuneJune <me@mrjunejune.com>
parents: 255
diff changeset
69 aggregate suite before completion.
04fee26ecce0 add authenticated JRPG conversation platform
MrJuneJune <me@mrjunejune.com>
parents: 255
diff changeset
70
248
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
71 ## Coding conventions to preserve
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
72
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
73 - Prefer Dowa's integer and boolean aliases (`uint8`, `uint16`, `uint32`,
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
74 `uint64`, `int8`, `int16`, `int32`, `int64`, and `boolean`) plus
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
75 `TRUE`/`FALSE` in first-party C. Do not introduce `<stdint.h>` `_t` aliases
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
76 or `<stdbool.h>` `bool` when a Dowa type already expresses the value.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
77 - C code generally uses `Dowa_Arena` for request-scoped allocations.
255
5ec271d612ae [dowa] Enforce arena ownership
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
78 - An arena owns every pointer returned by `Dowa_Arena_Allocate`, aligned arena
5ec271d612ae [dowa] Enforce arena ownership
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
79 allocation, arena string helpers, and arena array/hash-map macros. Never pass
5ec271d612ae [dowa] Enforce arena ownership
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
80 those pointers to libc `free()`, `Dowa_Free`, or an element-level destroy
5ec271d612ae [dowa] Enforce arena ownership
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
81 function.
5ec271d612ae [dowa] Enforce arena ownership
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
82 - Release a locally created arena exactly once with `Dowa_Arena_Free()` on
5ec271d612ae [dowa] Enforce arena ownership
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
83 every return path. Do not release a borrowed request arena; its owner must
5ec271d612ae [dowa] Enforce arena ownership
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
84 free it.
5ec271d612ae [dowa] Enforce arena ownership
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
85 - Prefer `Dowa_Free` over raw libc `free()` for separately heap-allocated
5ec271d612ae [dowa] Enforce arena ownership
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
86 first-party pointers. Keep the allocation source explicit when heap and arena
5ec271d612ae [dowa] Enforce arena ownership
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
87 ownership coexist in one function.
248
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
88 - HTTP responses are usually `Seobeo_Request_Entry *resp = NULL` maps filled with `Dowa_HashMap_Push_Arena`.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
89 - Route handlers return response maps; streaming handlers receive `Seobeo_Handle *` directly.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
90 - Existing code favors explicit status/content-type/body response fields.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
91 - Use `Seobeo_Log` for seobeo-aware logging instead of introducing another logger.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
92 - Keep Bazel dependencies precise. Add deps to the smallest target that needs them.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
93 - Preserve platform-aware `select()` aliases for macOS/Linux targets.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
94
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
95 ## Mercurial workflow
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
96
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
97 This repo is not a Git repository. Use Mercurial commands if you need VCS status:
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
98
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
99 ```bash
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
100 hg status
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
101 hg diff
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
102 ```
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
103
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
104 Do not create Git-specific metadata or workflows unless explicitly asked.