esedre 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,214 +1,263 @@
1
- # 🏛️ Esedre (`/eh-ˈseh-dreh/`)
2
-
3
- <p align="center">
4
- <img src="https://cdn.jsdelivr.net/npm/esedre/docs/assets/esedre-hero.png" alt="Esedre: The Classical Council Forum for Developers & Companion Agents" width="100%" />
5
- </p>
6
-
7
- > **The open developer roadmap and ticketing engine engineered to provide long-term grounding for LLM agent context, powered by a fast CLI, local Web UI, and Model Context Protocol (MCP) server.**
8
-
9
- [![License: MPL 2.0](https://img.shields.io/badge/License-MPL_2.0-blue.svg)](LICENSE)
10
- [![Tests](https://img.shields.io/badge/Tests-100%25%20Passing-emerald.svg)](tests/)
11
- [![Website: www.arwam.com](https://img.shields.io/badge/Website-www.arwam.com-cyan.svg)](https://www.arwam.com)
12
-
13
- ---
14
-
15
- ## 🌟 Overview
16
-
17
- **Esedre** (with short CLI alias **`ese`**) is an open-source developer planning engine backed by plain text files (Markdown & JSON) that are easily version-controlled in git. Designed from the ground up for software engineers and autonomous companion LLM coding agents (such as Google Antigravity, Claude Code, and Cursor) to coordinate together, Esedre solves the single biggest bottleneck in LLM-assisted development: **agent context drift and session amnesia**.
18
-
19
- ### ⚓ Core Pillar: Long-Term Grounding for LLM Agent Context
20
-
21
- LLM coding agents possess extraordinary implementation speed, but face a fundamental architectural ceiling: **context windows fill up, compact, and reset between turns and sessions**. External issue trackers live in distant web silos that agents cannot inspect reliably or locally without API keys and network overhead. Over multi-turn pair programming sessions, models lose track of architectural intent, past verification history, and upcoming milestones.
22
-
23
- **Esedre's core feature is providing persistent, authoritative long-term grounding to LLM agent context:**
24
-
25
- * **Git-Backed Ground Truth**: Tickets, feature breakdowns, architecture plans, and verification comments reside right alongside source code in git. They branch, merge, and stay synchronized with the codebase.
26
- * **First-Class MCP Integration**: Through the official Model Context Protocol, companion LLMs query roadmap priorities (`esedre_list_tickets`), inspect deep specifications (`esedre_get_ticket`), and update plans (`esedre_save_plan`) in real time.
27
- * **Cross-Session Memory & Grounding**: When an LLM agent begins a new turn, recovers from a context compaction, or transitions across developer handoffs, Esedre grounds the model to concrete technical specifications, constraints, and upcoming milestones: preventing drift and hallucinated direction.
28
- * **Optimistic Concurrency Protection**: Multi-agent pair-programming remains safe through SHA-1 content hashing, ensuring concurrent agents or developers never silently overwrite each other's work.
29
-
30
- ### ⚡ Key Capabilities
31
-
32
- 1. **Long-Term LLM Agent Grounding**: The primary architectural foundation: anchoring companion LLM agents to persistent project memory, architectural plans, and git-backed roadmap milestones across multi-turn sessions and context compactions.
33
- 2. **CLI Commands (`esedre` / `ese`)**: List, query, plan, create, and update tickets via simple terminal commands with human-readable colored tables or machine-readable `--json` output.
34
- 3. **Model Context Protocol (MCP) Server**: Full JSON-RPC 2.0 stdio server implementing the official MCP specification (`2024-11-05`), exposing roadmap tickets as first-class tools and URI resources.
35
- 4. **Agent Project Allow-List (Multi-Project Isolation)**: Informs each companion LLM only of the projects it is authorized to access, keeping unrelated project tickets, specifications, and plans completely isolated.
36
- 5. **Optimistic Concurrency Control**: SHA-1 content hashing on all tickets and plans, preventing concurrent agents or humans from clobbering each other's edits.
37
- 6. **Local Web Dashboard & Embeddable Component**: Run a visual dashboard with `esedre serve` to manage tickets in your browser, or embed `<esedre-planner>` into any web app without adding UI framework dependencies to your project.
38
-
39
- ---
40
-
41
- ## 🏛️ About the Name
42
-
43
- ### Origin
44
-
45
- **Esedre** derives from classical Latin *exedra* (plural *esedre*), the semicircular architectural council pavilions where ancient architects, master builders, and planners gathered to debate designs, draft blueprints, and coordinate construction. That classical forum mirrors Esedre's mission: a structured, open workspace where developers and companion LLMs collaborate to scope work, align on plans, and ship software.
46
-
47
- ### Pronunciation Guide
48
-
49
- Esedre is pronounced **`eh-SEH-dreh`** (phonetically: **`/ɛˈsɛ.drɛ/`**).
50
-
51
- * Short CLI alias: **`ese`** (pronounced **`/ˈɛ.sɛ/`**).
52
-
53
- ---
54
-
55
- ## 🚀 Quick Start
56
-
57
- ### 1. Installation
58
-
59
- ```bash
60
- # Global CLI installation
61
- npm install -g esedre
62
-
63
- # Or run instantly without installation via npx
64
- npx esedre list
65
- npx ese list
66
- ```
67
-
68
- ### 2. Configure Your Project (`.esedre/esedre.json`)
69
-
70
- Create an `.esedre/esedre.json` (or root `esedre.json`) configuration:
71
-
72
- ```json
73
- {
74
- "projectCode": "MYAPP",
75
- "allowedProjects": ["MYAPP"]
76
- }
77
- ```
78
-
79
- > **Tip**: Passing `"allowedProjects": ["*"]` authorizes access to all registered projects in the workspace.
80
-
81
- ---
82
-
83
- ## 💻 CLI Commands
84
-
85
- Both `esedre` and `ese` can be used interchangeably:
86
-
87
- | Command | Usage | Description |
88
- |---|---|---|
89
- | `list` | `ese list [--project <code\|all>] [--status <status>] [--json]` | List roadmap tickets. Defaults to the active project. |
90
- | `get` | `ese get <id> [--json]` | View ticket specifications, feature breakdown, comments, and SHA-1 hash. |
91
- | `plan` | `ese plan <id> [--set "<markdown>"] [--file <path>] [--last-hash <h>]` | Read or update the active implementation plan markdown. |
92
- | `create` | `ese create --title "..." [--project <code>] [--category <cat>]` | Create a new ticket with auto-sequential ID. Title strictly capped at 48 chars. |
93
- | `update` | `ese update <id> [--status <status>] [--title "..."] [--last-hash <h>]` | Update ticket status or title with optimistic concurrency protection. |
94
- | `comment` | `ese comment <id> --text "..." [--author "..."]` | Append a developer or companion agent note to a ticket. |
95
- | `configure` | `ese configure [--project <code>] [--port <n>]` | Initialize workspace configuration, MCP config, and in-repo shell wrappers. |
96
- | `snapshot` | `ese snapshot [--json]` | Generate lean projection `.esedre/snapshot.json` for zero-latency agent context. |
97
- | `projects` | `ese projects [--json]` | List registered projects within authorized scope. |
98
- | `serve` | `ese serve [--port <n>]` | Start the reverse proxy gateway (default 5674) with internal UI & API. |
99
- | `mcp` | `ese mcp` | Launch the Model Context Protocol stdio server for companion LLMs. |
100
-
101
- ---
102
-
103
- ## 🤖 Model Context Protocol (MCP) Setup
104
-
105
- To connect Esedre to **Google Antigravity**, **Claude Code**, **Cursor**, or any MCP-compatible companion LLM:
106
-
107
- ```json
108
- {
109
- "mcpServers": {
110
- "esedre": {
111
- "command": "esedre",
112
- "args": ["mcp"]
113
- }
114
- }
115
- }
116
- ```
117
-
118
- ### Registered Tools
119
- - `esedre_list_tickets`: List tickets with optional project, status, category, or search filter.
120
- - `esedre_get_ticket`: Retrieve full specification, summary, comments, revision, and content hash (`sha1`).
121
- - `esedre_get_plan` & `esedre_save_plan`: Inspect and update implementation plans with optimistic concurrency (`lastHash`).
122
- - `esedre_create_ticket`: Mint new roadmap tickets with project code validation (up to 6 chars).
123
- - `esedre_update_ticket`: Modify status, title, complexity, or effort with optimistic concurrency (`lastHash`).
124
- - `esedre_add_comment`: Append developer or companion agent verification notes.
125
-
126
- ### Resources
127
- - URI Scheme: `esedre://tickets/{id}` (MIME type: `text/markdown`)
128
-
129
- ---
130
-
131
- ## 🎨 Embeddable Component & Theming
132
-
133
- Esedre includes a drop-in Web Component (`<esedre-planner>`) that allows you to embed the visual developer planner directly into any host web application (React, Vue, Svelte, or vanilla HTML) without adding UI framework dependencies to your project.
134
-
135
- ### Component Usage
136
-
137
- ```html
138
- <!-- Load the Esedre embed script -->
139
- <script type="module" src="node_modules/esedre/dist/web/embed.js"></script>
140
-
141
- <!-- Embed the planner -->
142
- <esedre-planner
143
- project="MYAPP"
144
- api-url="/esedre"
145
- show-header="false">
146
- </esedre-planner>
147
- ```
148
-
149
- ### Component Attributes
150
-
151
- | Attribute | Default | Description |
152
- |---|---|---|
153
- | `project` | `"all"` | Filter tickets to a specific project code (e.g. `Profe`, `Alce`) or `"all"` |
154
- | `api-url` | `"/api/planning"` | Base URL of the Esedre server or reverse proxy endpoint |
155
- | `show-header` | `"true"` | Set to `"false"` to hide the top navigation header for seamless dialog/drawer embedding |
156
- | `read-only` | `"false"` | Disable ticket creation, editing, and plan modification |
157
-
158
- ### Theming with CSS Tokens
159
-
160
- The planner UI is styled entirely using CSS custom properties. When embedding inside host applications, you can override these tokens to match your app's visual identity:
161
-
162
- ```css
163
- :root {
164
- /* Surfaces & Backgrounds */
165
- --bg-main: #060812; /* Main canvas background */
166
- --bg-card: #0b0f19; /* Card containers */
167
- --bg-surface: #0a0e1a; /* Surface panels */
168
- --bg-surface-elevated: #0f172a; /* Headers & elevated panels */
169
-
170
- /* Borders & Accents */
171
- --border-subtle: #1e293b; /* Subtle divider borders */
172
- --border-strong: #334155; /* Interactive/hover borders */
173
- --accent-primary: #818cf8; /* Primary interactive accent */
174
-
175
- /* Typography */
176
- --text-primary: #f8fafc; /* High-contrast headings and titles */
177
- --text-secondary: #94a3b8; /* Body and secondary text */
178
- --text-muted: #64748b; /* Metadata and subtle labels */
179
- }
180
- ```
181
-
182
- * **Standalone Theme Toggle**: When running via `esedre serve`, users can toggle between Day (Light) and Night (Dark) themes with one click in the header. Theme preferences persist automatically in `localStorage`.
183
-
184
- ---
185
-
186
- ## 🛡️ Multi-Project Agent Isolation & Upward Discovery
187
-
188
- Esedre enforces clean project isolation so each companion LLM is informed only of the projects it is authorized to access:
189
- - **Upward Discovery**: When invoked in any subdirectory, Esedre climbs upward until it encounters the nearest `.esedre/esedre.json` or `esedre.json`, binding its execution to that repository's scope.
190
- - **Scoped Project Awareness**: Storage operations and tools only inform and expose projects declared in `allowedProjects`. Companion LLMs cannot query, list, or mutate tickets outside their authorized scope.
191
- - Unauthorized requests throw `EsedreAuthorizationError`:
192
- - **CLI**: Prints `Access Denied: ...` and exits with status code 1.
193
- - **MCP**: Responds with standard JSON-RPC error `-32603`.
194
-
195
- ---
196
-
197
- ## 🛠️ Development & Testing
198
-
199
- ```bash
200
- # Run full unit and integration test suite
201
- npm test
202
-
203
- # Lint TypeScript types
204
- npm run lint
205
-
206
- # Build bundled standalone distribution & web components
207
- npm run build
208
- ```
209
-
210
- ---
211
-
212
- ## 📄 License
213
-
214
- [Mozilla Public License 2.0 (MPL-2.0)](LICENSE) © [ARWAM](https://www.arwam.com)
1
+ # 🏛️ Esedre (`/eh-ˈseh-dreh/`)
2
+
3
+ <p align="center">
4
+ <img src="https://cdn.jsdelivr.net/npm/esedre/docs/assets/esedre-hero.png" alt="Esedre: The Classical Council Forum for Developers & LLM Agents" width="100%" />
5
+ </p>
6
+
7
+ > **The open developer roadmap and ticketing engine engineered to provide long-term grounding for LLM agent context, powered by a fast CLI, local Web UI, and Model Context Protocol (MCP) server.**
8
+
9
+ [![License: MPL 2.0](https://img.shields.io/badge/License-MPL_2.0-blue.svg)](LICENSE)
10
+ [![Tests](https://img.shields.io/badge/Tests-100%25%20Passing-emerald.svg)](tests/)
11
+ [![Website: www.arwam.com](https://img.shields.io/badge/Website-www.arwam.com-cyan.svg)](https://www.arwam.com)
12
+
13
+ ---
14
+
15
+ ## 🌟 Overview
16
+
17
+ **Esedre** (with short CLI alias **`ese`**) is an open-source developer planning engine backed by plain text files (Markdown & JSON) that are easily version-controlled in git. Designed from the ground up for software engineers and autonomous LLM coding agents (such as Google Antigravity, Claude Code, and Cursor) to coordinate together, Esedre solves the single biggest bottleneck in LLM-assisted development: **agent context drift and session amnesia**.
18
+
19
+ <p align="center">
20
+ <img src="https://cdn.jsdelivr.net/npm/esedre/docs/assets/esedre-dashboard-light.png" alt="Esedre Web Dashboard (Light Theme)" width="100%" />
21
+ </p>
22
+
23
+ ### ⚓ Core Pillar: Long-Term Grounding for LLM Agent Context
24
+
25
+ LLM coding agents possess extraordinary implementation speed, but face a fundamental architectural ceiling: **context windows fill up, compact, and reset between turns and sessions**. External issue trackers live in distant web silos that agents cannot inspect reliably or locally without API keys and network overhead. Over multi-turn pair programming sessions, models lose track of architectural intent, past verification history, and upcoming milestones.
26
+
27
+ **Esedre's core feature is providing persistent, authoritative long-term grounding to LLM agent context:**
28
+
29
+ * **Git-Backed Ground Truth**: Tickets, feature breakdowns, architecture plans, and verification comments reside right alongside source code in git. They branch, merge, and stay synchronized with the codebase.
30
+ * **First-Class MCP Integration**: Through the official Model Context Protocol, LLM agents query roadmap priorities (`esedre_list_tickets`), inspect deep specifications (`esedre_get_ticket`), and update plans (`esedre_save_plan`) in real time.
31
+ * **Cross-Session Memory & Grounding**: When an LLM agent begins a new turn, recovers from a context compaction, or transitions across developer handoffs, Esedre grounds the model to concrete technical specifications, constraints, and upcoming milestones: preventing drift and hallucinated direction.
32
+ * **Optimistic Concurrency Protection**: Multi-agent pair-programming remains safe through SHA-1 content hash versioning, ensuring concurrent agents or developers never silently overwrite each other's work.
33
+
34
+ ### ⚡ Key Capabilities
35
+
36
+ 1. **Long-Term LLM Agent Grounding**: The primary architectural foundation: anchoring LLM agents to persistent project memory, architectural plans, and git-backed roadmap milestones across multi-turn sessions and context compactions.
37
+ 2. **CLI Commands (`esedre` / `ese`)**: List, query, plan, create, and update tickets via simple terminal commands with human-readable colored tables or machine-readable `--json` output.
38
+ 3. **Model Context Protocol (MCP) Server**: Full JSON-RPC 2.0 stdio server implementing the official MCP specification (`2024-11-05`), exposing roadmap tickets as first-class tools and URI resources.
39
+ 4. **Agent Project Allow-List (Multi-Project Isolation)**: Informs each LLM agent only of the projects it is authorized to access, keeping unrelated project tickets, specifications, and plans completely isolated.
40
+ 5. **Optimistic Concurrency Control**: SHA-1 content hashing on all tickets and plans, preventing concurrent agents or humans from clobbering each other's edits.
41
+ 6. **Local Web Dashboard & Embeddable Component**: Run a visual dashboard with `ese start` to manage tickets in your browser, or embed `<esedre-planner>` into any web app without adding UI framework dependencies to your project.
42
+
43
+ ---
44
+
45
+ ## 🏛️ About the Name
46
+
47
+ ### Origin
48
+
49
+ **Esedre** derives from classical Latin *exedra* (plural *esedre*), the semicircular architectural council pavilions where ancient architects, master builders, and planners gathered to debate designs, draft blueprints, and coordinate construction. That classical forum mirrors Esedre's mission: a structured, open workspace where developers and LLM coding partners collaborate to scope work, align on plans, and ship software.
50
+
51
+ ### Pronunciation Guide
52
+
53
+ Esedre is pronounced **`eh-SEH-dreh`** (phonetically: **`/ɛˈsɛ.drɛ/`**).
54
+
55
+ * Short CLI alias: **`ese`** (pronounced **`/ˈɛ.sɛ/`**).
56
+
57
+ ---
58
+
59
+ ## 🚀 Quick Start
60
+
61
+ ### 1. Installation
62
+
63
+ ```bash
64
+ # Global CLI installation (recommended)
65
+ npm install -g esedre
66
+
67
+ # Or run instantly without global installation via npx
68
+ npx esedre init
69
+ ```
70
+
71
+ ### 2. Initialize Your Project
72
+
73
+ Run `ese init` inside any project repository. It automatically configures `.esedre/esedre.json`, plants in-repo shell wrappers (`.esedre/ese`), configures MCP for LLM agents, and generates your initial snapshot:
74
+
75
+ ```bash
76
+ ese init
77
+
78
+ # Or non-interactive with custom project code and display name:
79
+ ese init --project MYAPP --name "My App" -y
80
+ ```
81
+
82
+ ### 3. Start the Web UI & Server
83
+
84
+ ```bash
85
+ # Start background server daemon on port 5674
86
+ ese start
87
+
88
+ # Open dashboard: http://localhost:5674/app
89
+ ```
90
+
91
+ ### 4. Create Your First Ticket
92
+
93
+ ```bash
94
+ ese create --title "Build authentication flow" --type Feature
95
+ ese list
96
+ ese get 1
97
+ ```
98
+
99
+ > **Multi-Project Tip**: Passing `"allowedProjects": ["*"]` in `.esedre/esedre.json` authorizes access to all registered projects in the workspace.
100
+
101
+ ---
102
+
103
+ ## 💻 CLI Commands
104
+
105
+ Both `esedre` and `ese` can be used interchangeably. Commands are structured into semantic categories:
106
+
107
+ ### Roadmap Commands (Pair Programming & LLM Agents)
108
+
109
+ Core day-to-day workflow commands for scoping, viewing, planning, and verifying tickets:
110
+
111
+ | Command | Usage | Description |
112
+ |---|---|---|
113
+ | `list` | `ese list [-p\|--project <code\|all>] [-s\|--status <status>] [-t\|--type <type>] [--json]` | List roadmap tickets with optional filters. Defaults to the active project. |
114
+ | `get` | `ese get <id> [--json]` | View ticket specifications, feature breakdown, comments, and SHA-1 hash. |
115
+ | `plan` | `ese plan <id> [--set "<markdown>"] [--file <path>] [--last-hash <h>]` | Read or update the active implementation plan markdown. |
116
+ | `create` | `ese create --title "..." [-p\|--project <code>] [-t\|--type <type>]` | Create a new ticket with auto-sequential ID. Title strictly capped at 48 chars. |
117
+ | `update` | `ese update <id> [-s\|--status <status>] [-t\|--type <type>] [--title "..."] [--last-hash <h>]` | Update ticket status, type, or title with optimistic concurrency protection. |
118
+ | `comment` | `ese comment <id> ["<text>"] [--text "..."] [--author "..."]` | Append a developer or LLM agent note to ticket history. |
119
+ | `snapshot` | `ese snapshot [--project <code>] [--json]` | Generate lean projection `.esedre/snapshot.json` for zero-latency agent context. |
120
+ | `projects` | `ese projects [--json]` | List registered projects within authorized scope. |
121
+
122
+ ### Service Daemon Commands
123
+
124
+ Manage the local web dashboard and API server:
125
+
126
+ | Command | Usage | Description |
127
+ |---|---|---|
128
+ | `start` | `ese start [--port <n>] [--foreground \| -f]` | Start the Esedre background server daemon (or foreground with `-f`). |
129
+ | `stop` | `ese stop [--port <n>]` | Stop the running Esedre background server daemon. |
130
+ | `status` | `ese status [--port <n>]` | Check health, uptime, and diagnostics of the running server. |
131
+ | `logs` | `ese logs [--port <n>] [--lines <n>]` | Tail recent server output logs. |
132
+ | `mcp` | `ese mcp` | Launch the Model Context Protocol stdio server for LLM agents. |
133
+
134
+ ### Developer Administration (Human Machine Setup)
135
+
136
+ Commands for repository onboarding, central machine linking, and maintenance:
137
+
138
+ | Command | Usage | Description |
139
+ |---|---|---|
140
+ | `init` | `ese init [<path>] [--project <code>] [--name <name>] [--hub] [-y]` | Bring a project repository online or bootstrap a dedicated data hub. |
141
+ | `configure` | `ese configure [add <path> \| remove <target> \| set <k> <v>]` | Inspect or mutate central Esedre configuration (`~/.esedre/config.json`). |
142
+ | `upgrade` | `ese upgrade [<path>] [--force \| -f]` | Upgrade workspace configuration schema, in-repo wrappers, and agent skills. |
143
+
144
+ > **Human vs LLM Agent Workflows**: Developer Administration commands (`init`, `configure`, `upgrade`) manage system-level repository linking and central machine configuration. They are intended for human developers during initial setup. Autonomous LLM coding partners operate within the authorized workspace scope using Roadmap and Service Daemon commands (`list`, `get`, `plan`, `create`, `update`, `comment`, `snapshot`, `start`, `status`).
145
+
146
+ ---
147
+
148
+ ## 🤖 Model Context Protocol (MCP) Setup
149
+
150
+ To connect Esedre to **Google Antigravity**, **Claude Code**, **Cursor**, or any MCP-compatible LLM agent:
151
+
152
+ ```json
153
+ {
154
+ "mcpServers": {
155
+ "esedre": {
156
+ "command": "esedre",
157
+ "args": ["mcp"]
158
+ }
159
+ }
160
+ }
161
+ ```
162
+
163
+ ### Registered Tools
164
+ - `esedre_list_tickets`: List tickets with optional project, status, category, or search filter.
165
+ - `esedre_get_ticket`: Retrieve full specification, summary, comments, revision, and content hash (`sha1`).
166
+ - `esedre_get_plan` & `esedre_save_plan`: Inspect and update implementation plans with optimistic concurrency (`lastHash`).
167
+ - `esedre_create_ticket`: Mint new roadmap tickets with project code validation (up to 6 chars).
168
+ - `esedre_update_ticket`: Modify status, title, complexity, or effort with optimistic concurrency (`lastHash`).
169
+ - `esedre_add_comment`: Append developer or LLM agent verification notes.
170
+
171
+ ### Resources
172
+ - URI Scheme: `esedre://tickets/{id}` (MIME type: `text/markdown`)
173
+
174
+ ---
175
+
176
+ ## 🎨 Embeddable Component & Theming
177
+
178
+ Esedre includes a drop-in Web Component (`<esedre-planner>`) that allows you to embed the visual developer planner directly into any host web application (React, Vue, Svelte, or vanilla HTML) without adding UI framework dependencies to your project.
179
+
180
+ ### Component Usage
181
+
182
+ ```html
183
+ <!-- Load the Esedre embed script -->
184
+ <script type="module" src="node_modules/esedre/dist/web/embed.js"></script>
185
+
186
+ <!-- Embed the planner -->
187
+ <esedre-planner
188
+ project="MYAPP"
189
+ api-url="/esedre"
190
+ show-header="false">
191
+ </esedre-planner>
192
+ ```
193
+
194
+ ### Component Attributes
195
+
196
+ | Attribute | Default | Description |
197
+ |---|---|---|
198
+ | `project` | `"all"` | Filter tickets to a specific project code (e.g. `Profe`, `Alce`) or `"all"` |
199
+ | `api-url` | `"/api/planning"` | Base URL of the Esedre server or reverse proxy endpoint |
200
+ | `show-header` | `"true"` | Set to `"false"` to hide the top navigation header for seamless dialog/drawer embedding |
201
+ | `read-only` | `"false"` | Disable ticket creation, editing, and plan modification |
202
+
203
+ ### Theming with CSS Tokens
204
+
205
+ The planner UI is styled entirely using CSS custom properties. When embedding inside host applications, you can override these tokens to match your app's visual identity:
206
+
207
+ ```css
208
+ :root {
209
+ /* Surfaces & Backgrounds */
210
+ --bg-main: #060812; /* Main canvas background */
211
+ --bg-card: #0b0f19; /* Card containers */
212
+ --bg-surface: #0a0e1a; /* Surface panels */
213
+ --bg-surface-elevated: #0f172a; /* Headers & elevated panels */
214
+
215
+ /* Borders & Accents */
216
+ --border-subtle: #1e293b; /* Subtle divider borders */
217
+ --border-strong: #334155; /* Interactive/hover borders */
218
+ --accent-primary: #818cf8; /* Primary interactive accent */
219
+
220
+ /* Typography */
221
+ --text-primary: #f8fafc; /* High-contrast headings and titles */
222
+ --text-secondary: #94a3b8; /* Body and secondary text */
223
+ --text-muted: #64748b; /* Metadata and subtle labels */
224
+ }
225
+ ```
226
+
227
+ * **Standalone Theme Toggle**: When running via `ese start`, users can toggle between Day (Light) and Night (Dark) themes with one click in the header. Theme preferences persist automatically in `localStorage`.
228
+
229
+ <p align="center">
230
+ <img src="https://cdn.jsdelivr.net/npm/esedre/docs/assets/esedre-dashboard-dark.png" alt="Esedre Web Dashboard (Dark Theme)" width="100%" />
231
+ </p>
232
+
233
+ ---
234
+
235
+ ## 🛡️ Multi-Project Agent Isolation & Upward Discovery
236
+
237
+ Esedre enforces clean project isolation so each LLM agent is informed only of the projects it is authorized to access:
238
+ - **Upward Discovery**: When invoked in any subdirectory, Esedre climbs upward until it encounters the nearest `.esedre/esedre.json` or `esedre.json`, binding its execution to that repository's scope.
239
+ - **Scoped Project Awareness**: Storage operations and tools only inform and expose projects declared in `allowedProjects`. LLM agents cannot query, list, or mutate tickets outside their authorized scope.
240
+ - Unauthorized requests throw `EsedreAuthorizationError`:
241
+ - **CLI**: Prints `Access Denied: ...` and exits with status code 1.
242
+ - **MCP**: Responds with standard JSON-RPC error `-32603`.
243
+
244
+ ---
245
+
246
+ ## 🛠️ Development & Testing
247
+
248
+ ```bash
249
+ # Run full unit and integration test suite
250
+ npm test
251
+
252
+ # Lint TypeScript types
253
+ npm run lint
254
+
255
+ # Build bundled standalone distribution & web components
256
+ npm run build
257
+ ```
258
+
259
+ ---
260
+
261
+ ## 📄 License
262
+
263
+ [Mozilla Public License 2.0 (MPL-2.0)](LICENSE) © [ARWAM](https://www.arwam.com)