Skip to content

Commit 0b708ab

Browse files
leandromqrsleandromqrs
committed
docs: add AGENTS developer instructions
1 parent 34c7074 commit 0b708ab

1 file changed

Lines changed: 105 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# AGENTS instructions
2+
3+
## Environment Setup
4+
5+
- Install dependencies: `yarn install` (or just run `just build` — it runs `yarn install` automatically)
6+
- Requires **Node.js 20+**, **Yarn 4+**, and **[just](https://github.com/casey/just)**.
7+
- For a full test environment, create a Fedora toolbox: `just toolbox create` (first time only).
8+
- To run GNOME Shell in devkit mode: `just run` (host) or `just toolbox run` (inside toolbox).
9+
- **Never run gnome-shell directly** — always use `just run` or `just toolbox run` to ensure the correct environment flags (`--wayland --devkit`) are set.
10+
11+
## Commands
12+
13+
- **Build:** `just build` — installs deps, compiles TypeScript and SCSS, copies metadata/schemas, compiles `.mo` files
14+
- **Install:** `just install` — builds + packages as `.zip` + installs to GNOME Shell
15+
- **Quick update:** `just quick` — rebuild + rsync files to extension dir (skips full install)
16+
- **Uninstall:** `just uninstall` — disables and removes the extension
17+
- **Run (host):** `just run` — build + install + launch a devkit GNOME Shell session
18+
- **Run (toolbox):** `just toolbox run` — same as above, but inside the Fedora toolbox
19+
- **Create toolbox:** `just toolbox create` — create the `gnome-shell-devel` Fedora toolbox
20+
- **Remove toolbox:** `just toolbox remove` — delete the toolbox
21+
- **Type-check:** `just validate` — runs `tsc` without emitting output
22+
- **Lint:** `just lint` — runs ESLint
23+
- **Watch SCSS:** `just watch` — watches `src/styles/` and recompiles on change
24+
- **View logs:** `just logs` — shows recent `aurora` entries from the current boot journal
25+
- **Clean:** `just clean` — removes `dist/`
26+
- **Deep clean:** `just distclean` — removes `dist/` and `node_modules/`
27+
28+
### Translation commands
29+
30+
- **Regenerate POT template:** `just pot` — scans compiled JS (`dist/`) and rewrites `po/aurora-shell@luminusos.github.io.pot` with all `_()` strings. Run this whenever translatable strings are added or removed.
31+
- **Merge new strings into .po files:** `just update-po` — runs `msgmerge` on every `po/*.po` file against the current `.pot`. Run after `just pot`.
32+
- **Compile .mo binaries:** `just compile-mo` — compiles each `po/*.po` into `dist/locale/<lang>/LC_MESSAGES/*.mo`. Called automatically by `just build`.
33+
34+
## Repository Structure
35+
36+
- `src/` — TypeScript source root
37+
- `extension.ts` — entry point; loads and manages all modules via `MODULE_FACTORIES`
38+
- `module.ts` — base `Module` class (`enable` / `disable` lifecycle)
39+
- `registry.ts` — `MODULE_REGISTRY` metadata list (key, settingsKey, title, subtitle)
40+
- `prefs.ts` — extension preferences UI
41+
- `modules/` — one file (or subfolder) per feature module
42+
- `shared/` — shared utilities used across modules
43+
- `styles/` — SCSS stylesheets (compiled to light + dark CSS)
44+
- `types/` — TypeScript type declarations (`@girs`, GJS, etc.)
45+
- `schemas/` — GSettings schema XML
46+
- `scripts/` — helper shell scripts (`create-toolbox.sh`, `run-gnome-shell.sh`, `bump-version.sh`)
47+
- `esbuild.ts` — esbuild bundler configuration
48+
- `sass.config.ts` — Sass compiler configuration
49+
- `justfile` — all project commands
50+
- `metadata.json` — GNOME extension metadata (uuid, version, shell versions)
51+
- `dist/` — build output (gitignored)
52+
53+
## Architecture
54+
55+
1. `extension.ts` is the GNOME Shell extension entry point. It instantiates all modules from `MODULE_FACTORIES` on `enable()` and disposes them on `disable()`.
56+
2. Each module is an independent class that extends `Module` and implements `enable()` and `disable()`.
57+
3. `MODULE_REGISTRY` in `registry.ts` drives the preferences UI — every module needs an entry here.
58+
4. GSettings keys (in `schemas/`) control per-module toggles from the preferences panel.
59+
5. The build toolchain (esbuild + Sass) targets **GJS 1.73.2+ / Firefox 102** (ESM format).
60+
61+
## Adding a Module
62+
63+
1. Create `src/modules/myModule.ts` extending `Module`:
64+
65+
```typescript
66+
import { Module } from './module.ts';
67+
68+
export class MyModule extends Module {
69+
override enable(): void { /* setup */ }
70+
override disable(): void { /* cleanup */ }
71+
}
72+
```
73+
74+
2. Register it in `MODULE_REGISTRY` (`src/registry.ts`):
75+
76+
```typescript
77+
{ key: 'myModule', settingsKey: 'module-my-module', title: 'My Module', subtitle: 'Description' },
78+
```
79+
80+
3. Add its factory to `MODULE_FACTORIES` (`src/extension.ts`):
81+
82+
```typescript
83+
import { MyModule } from "./modules/myModule.ts";
84+
// inside MODULE_FACTORIES:
85+
myModule: () => new MyModule(),
86+
```
87+
88+
4. Add a GSettings key (`schemas/org.gnome.shell.extensions.aurora-shell.gschema.xml`):
89+
90+
```xml
91+
<key name="module-my-module" type="b">
92+
<default>true</default>
93+
<summary>Enable My Module</summary>
94+
<description>What this module does</description>
95+
</key>
96+
```
97+
98+
## Coding Standards
99+
100+
- File names: `camelCase.ts`
101+
- Classes: `PascalCase`
102+
- Private members: `_prefixed`
103+
- Constants: `UPPER_CASE`
104+
- Keep `enable()` and `disable()` symmetric — everything connected in `enable()` must be disconnected in `disable()`.
105+
- Avoid importing GJS global modules at the top level in code paths that run in multiple processes; use lazy / conditional imports where needed.

0 commit comments

Comments
 (0)