Files
mp-silma-ai-aide/AGENTS.md
T

82 lines
6.6 KiB
Markdown
Raw Normal View History

2026-07-17 14:08:03 -05:00
# AGENTS.md
## Project
`mp-silma-ai-aide` is a Vite + TypeScript Chrome extension scaffold. The built `dist/` directory is intended to be loaded in Chrome as an unpacked Manifest V3 extension.
2026-07-17 14:33:11 -05:00
## Required Reading
- Read `docs/extension-management.md` before doing Chrome extension loading, reloading, testing, browser automation, or profile-dependent work.
- Keep `AGENTS.md`, `llm.txt`, `manifest.llm.json`, `README.md`, and `docs/extension-management.md` in sync when commands, environment variables, deployable output, workflows, or extension-management rules change.
2026-07-17 14:08:03 -05:00
## Commands
2026-07-17 14:16:54 -05:00
- Install dependencies: `npm ci`
- Codex setup: `npm run codex:setup`
2026-07-17 14:08:03 -05:00
- Run local Vite dev server: `npm run dev`
2026-07-17 14:16:54 -05:00
- Run app in Codex: `npm run dev:codex`
2026-07-17 14:08:03 -05:00
- Build extension: `npm run build`
2026-07-17 14:16:54 -05:00
- Build extension in Codex: `npm run build:codex`
2026-07-17 14:08:03 -05:00
- Preview build output: `npm run preview`
2026-07-17 14:16:54 -05:00
- Verify generated extension output: `npm run verify:dist`
2026-07-17 14:08:03 -05:00
## Environment
Configuration is read from Vite environment variables:
- `VITE_GITEA_BASE_URL`: Base URL for the Gitea instance, for example `http://gitea.orson.tealthrone`.
- `VITE_GITEA_TOKEN`: Gitea API token.
- `VITE_GITEA_REPO_OWNER`: Target Gitea owner. Default: `jacob-mathison`.
- `VITE_GITEA_REPO_NAME`: Target Gitea repository. Default: `mp-silma-ai-aide`.
Use `.env.local` for local secrets. Keep `.env.local` and any real token-bearing env files out of git. Update `.env.example` when adding new required variables.
## Extension Build Notes
- `vite.config.ts` emits `dist/manifest.json` during production builds.
2026-07-17 14:16:54 -05:00
- `dist/` is the deployable output directory. Deployment or Chrome load-unpacked flows should point directly at `dist/`.
2026-07-17 14:08:03 -05:00
- `dist/` is generated output and should not be edited directly.
2026-07-17 15:45:30 -05:00
- Static extension assets live in `public/`; extension icon sources live under `public/icons/`.
- `scripts/generate-local-context.mjs` generates `public/local-context.json` from `/Users/Tabitha/.openclaw/workspace_Father` before builds.
- `public/local-context.json` is a committed fallback snapshot so CI builds can still produce a self-contained `dist/` if the local workspace root is unavailable.
2026-07-17 14:16:54 -05:00
- `npm run build` runs `scripts/verify-dist.mjs` after Vite to ensure the generated output has the required extension files.
2026-07-17 15:53:31 -05:00
- Host permissions include `<all_urls>` for Chrome visible-tab screenshot capture plus the Gitea host derived from `VITE_GITEA_BASE_URL`. Rebuild after changing the base URL.
2026-07-17 14:08:03 -05:00
- Runtime API calls are centralized in `src/api.ts`.
2026-07-17 15:45:30 -05:00
- Side panel state is centralized in the vanilla Zustand store at `src/store.ts`.
- The extension opens as a Chrome side panel. It is not a draggable in-page window.
2026-07-18 10:50:04 -05:00
- The side panel has icon menu sections for Add URL, URLs, Gitea repos, Workspaces, Agents, Open Issues, and Add Issue.
2026-07-17 15:45:30 -05:00
- Add URL is enabled only when the active tab's base URL is not already in the URLs list. The user must pick either a workspace or a Gitea repo; the app infers the linked counterpart from local context.
2026-07-17 15:51:15 -05:00
- URLs can be deleted from the URLs list. User-added URLs are removed from storage; generated known URLs are hidden through the stored deleted-base list.
2026-07-18 10:17:06 -05:00
- The Agents view lists available agent files and must allow adding, editing, and deleting persisted agents from `chrome.storage.local`. At least one agent must remain available.
- The default `GLOBAL AGENT` is backed by `AGENTS.md` and contains agnostic handoff rules with template variables such as `{{git}}`, `{{workspace}}`, `{{url}}`, `{{baseUrl}}`, `{{profile}}`, and `{{issue}}`.
- Add Issue is enabled only when the active tab's base URL is already in the URLs list and has a linked Gitea repo. The issue form must show the target repo, the active URL the extension believes it is attached to, let the user select an agent file, capture visible-tab screenshots, accept multiple accumulated Gitea-friendly file attachments, and include `Chrome profile: Silma` plus the selected agent in created issue bodies.
2026-07-18 11:01:51 -05:00
- Clicking a captured screenshot must open an expanded preview with Close, Remove, and Crop controls. The crop area should be a simple draggable/resizable box without a shaded crop fill, and the preview panel should use the available viewport without horizontal scrolling.
2026-07-17 17:22:08 -05:00
- Newly created issues must be created with the `Change Request` label.
2026-07-18 10:17:06 -05:00
- When creating an issue, upload the selected rendered agent file as an issue asset along with screenshots and files.
- If the Ready checkbox is checked, create the issue first, upload the rendered agent file plus screenshots/files as issue assets second, and apply the `ready` label last.
2026-07-18 12:49:15 -05:00
- Open Issues owns issue browsing and follow-up. It must list recent issues ordered by creation time, default to open issues for the active URL's linked repo, provide a checkbox to show issues across all loaded repos, and provide a status dropdown for Open, Closed, or Open + Closed.
2026-07-18 11:01:51 -05:00
- Selecting an Open Issues row must show a direct Open in Gitea link, editable issue subject/content fields, issue attachments, and comment chain, followed by a comment form that can add text, take additional screenshots, attach files, upload those files as issue assets, and submit a Gitea comment with attachment links.
2026-07-18 12:57:11 -05:00
- Saving selected issue edits must use the selected issue's repo identity from Open Issues and must never fall back to the active tab's repo.
2026-07-18 10:50:04 -05:00
- Existing issue rows must allow applying the `ready` label and deleting the issue. Existing issue attachments must be removable. Deletion must require user confirmation.
2026-07-18 11:01:51 -05:00
- Text-entry updates in Add Issue, selected issue edits, Open Issues comments, and Agents must not re-render the focused form control or blur the user while they type.
2026-07-17 16:12:51 -05:00
- Keep the Add Issue view dense; do not show the redundant view header title/description inside this view, and keep the Ready checkbox label short.
2026-07-17 15:53:31 -05:00
- The extension requests `activeTab` and `<all_urls>` host permission so screenshots can be captured from the current Chrome tab even after the side panel has stayed open across tab changes.
2026-07-17 14:08:03 -05:00
2026-07-17 14:33:11 -05:00
## Chrome Extension Management
- Use the Codex Chrome extension with the Chrome profile named `Silma` for this project.
- Do not use Chrome `Profile 1` for this project.
- Load or reload the unpacked extension from `dist/` only after running `npm run build`.
## Gitea Workflows
- `.gitea/workflows/build.yml` builds the deployable extension on pushes to `main` and pull requests.
- `.gitea/workflows/issue-opened-placeholder.yml` runs when a new issue is opened and prints `200 okay`.
2026-07-17 14:08:03 -05:00
## Coding Guidelines
- Keep the app TypeScript-first and strict.
- Prefer small, focused modules under `src/`.
- Do not commit secrets or generated build output.
- Run `npm run build` before handing off code changes.