124 lines
8.6 KiB
Markdown
124 lines
8.6 KiB
Markdown
# Extension Management
|
|
|
|
This project builds a Chrome side panel extension from the generated `dist/` directory. Run `npm run build` before loading or reloading the unpacked extension.
|
|
|
|
## Required Chrome Profile
|
|
|
|
When an agent needs to inspect, load, reload, test, or otherwise manage this extension in Chrome, use the Codex Chrome extension with the Chrome profile named `Silma`.
|
|
|
|
Do not use `Profile 1` for this project.
|
|
|
|
This rule applies to:
|
|
|
|
- Opening Chrome for extension work.
|
|
- Loading `dist/` as an unpacked extension.
|
|
- Reloading the extension after a build.
|
|
- Inspecting extension side panel, background/service worker behavior, or permissions.
|
|
- Any browser automation that depends on extension state.
|
|
|
|
## Build Output
|
|
|
|
- Build command: `npm run build`
|
|
- Live local context command: `npm run context:serve`
|
|
- Deployable/load-unpacked directory: `dist/`
|
|
- Manifest path: `dist/manifest.json`
|
|
|
|
Do not edit `dist/` directly. Change source files and rebuild.
|
|
|
|
## Environment
|
|
|
|
Use `.env.local` for local extension configuration and secrets. Never commit real tokens.
|
|
|
|
Required variables:
|
|
|
|
- `VITE_GITEA_BASE_URL`
|
|
- `VITE_GITEA_TOKEN`
|
|
- `VITE_GITEA_REPO_OWNER`
|
|
- `VITE_GITEA_REPO_NAME`
|
|
|
|
Optional variables:
|
|
|
|
- `VITE_LOCAL_CONTEXT_URL`, defaulting to `http://127.0.0.1:23873/local-context.json`.
|
|
- `LOCAL_CONTEXT_PORT`, used by `npm run context:serve`; default `23873`.
|
|
- `WORKSPACE_FOLDER_SEARCH_ROOTS`, comma-separated roots used by local context generation and serving.
|
|
- `WORKSPACE_FOLDER_SEARCH_MAX_DEPTH`, default `3`.
|
|
|
|
## Issue Creation
|
|
|
|
- Add Issue is enabled only when the active tab's base URL is already in the URLs list and that URL is linked to a Gitea repo.
|
|
- The Add Issue view must show the Gitea repo that will receive the issue and the active URL the extension believes it is attached to.
|
|
- The Add Issue form must show a Default prompt dropdown immediately above Content. It should only list prompts whose workspace path matches the active known URL and should copy the selected prompt content into the editable Content field.
|
|
- The Add Issue form must let the user select the agent file for handoff. Agents are managed in the Agents view, persisted in `chrome.storage.local`, and the initial agent is `GLOBAL AGENT` backed by `AGENTS.md`.
|
|
- The default `GLOBAL AGENT` rules must instruct downstream agents to close the Gitea issue after pushing the implementation and to leave a Gitea issue comment when delivery is blocked, partial, or risky.
|
|
- The Add Issue view intentionally omits the redundant view header title/description.
|
|
- Add Issue and selected issue editing expose these label options: `Change Request`, `Idea`, `Tabitha`, `Orson`, `Belisarius`, `Ozymandias`, and `Ready`.
|
|
- New issues default to `Change Request` selected unless the user changes the label selection.
|
|
- Do not show the old Ready checkbox; `Ready` is now a selectable label.
|
|
- Screenshot capture uses Chrome's visible-tab capture API and requires the extension's `activeTab` permission plus `<all_urls>` host permission so capture still works after the side panel remains open across tab changes.
|
|
- Captured screenshots should appear immediately in Add Issue as thumbnail rows.
|
|
- Captured screenshots can be expanded, closed, removed, or cropped before upload. The crop UI should use a plain draggable/resizable crop box instead of shaded slider-based controls, and the preview panel should fit the available viewport without horizontal scrolling.
|
|
- File attachments are accumulated across picker selections and all selected files must be uploaded to Gitea.
|
|
- Created issue bodies must put the human-entered idea/change request under `# Requirements` and generated metadata under `# References`, including `Chrome profile: Silma` and the selected agent.
|
|
- Created issues must upload the selected rendered agent file as a Gitea issue asset. Supported template variables in agent content are `{{git}}`, `{{repo}}`, `{{workspace}}`, `{{url}}`, `{{baseUrl}}`, `{{profile}}`, and `{{issue}}`.
|
|
- Newly created issues must use the selected labels.
|
|
|
|
## Issues
|
|
|
|
- Issues owns existing issue browsing and follow-up comments.
|
|
- The primary Issues panel lists recent issues ordered by creation time.
|
|
- The `Only current repo` checkbox defaults to checked and limits the table to the active URL's linked Gitea repo.
|
|
- Turning off `Only current repo` loads recent issues from all repos already loaded in the extension.
|
|
- Status filtering uses `Open` and `Closed` checkboxes as a multiselect. The default is `Open` checked.
|
|
- The label filter defaults to empty and filters the visible issue rows by a selected known label.
|
|
- Selecting an issue shows a direct Open in Gitea link, a Send to Codex button that currently logs the selected issue payload, editable issue subject/content/label fields, issue attachments, direct attachment upload controls, comment chain, and a comment form for text, additional screenshots, and file attachments.
|
|
- Clicking the selected issue row again or clicking the detail close control closes the selected issue detail panel without deleting or changing the issue.
|
|
- Saving selected issue edits must use the repo identity from the selected Issues row, include Gitea's current issue content version when available, verify the saved subject/content with a readback before reporting success, save labels through Gitea's issue labels endpoint, and must not fall back to the active tab's repo.
|
|
- Issue comments should upload screenshots/files as issue assets first, then create a comment containing links to those attachments.
|
|
- Additional selected-issue screenshots/files can also be uploaded directly as issue assets without creating a comment.
|
|
- Existing issue attachments can be deleted from the selected issue.
|
|
- Existing issue rows can delete the issue. Issue labels are edited in the selected issue form. Deletion must require confirmation.
|
|
- Typing in Add Issue, selected issue edit fields, Issues comments, Agents editor fields, Prompts editor fields, or workspace folder search must not blur the focused control.
|
|
|
|
## Prompt Management
|
|
|
|
- Agents, Prompts, and Workspaces must be selected from a management dropdown, not separate top-level toolbar buttons.
|
|
- The Prompts view is workspace-scoped and stores prompt records in `silmaAide.prompts`.
|
|
- The Prompts view must allow adding, editing, and deleting prompts with a name, workspace path, and content.
|
|
- New prompt workspace selection should default to the active known URL's workspace/site when available.
|
|
|
|
## Workspace Management
|
|
|
|
- The Workspaces view shows generated workspaces from `workspace_Father` plus user-added workspaces from `silmaAide.userWorkspaces`.
|
|
- The Workspaces view must show only a first-row Add workspace button for creation. That button opens a modal dialog.
|
|
- User-added workspaces require an absolute local path selected from searchable generated folder candidates in `local-context.json`; do not require copy/paste path entry.
|
|
- User-added workspaces can be deleted from the side panel.
|
|
- Add URL workspace selection should include both generated and user-added workspaces.
|
|
- For live local workspace updates, run `npm run context:serve`. The side panel should prefer `VITE_LOCAL_CONTEXT_URL`, fall back to bundled `/local-context.json`, and poll live local context every 10 seconds while workspace-sensitive views or dialogs are active.
|
|
|
|
## Gitea Error Reporting
|
|
|
|
- Gitea API failures should surface the specific operation that failed, such as issue creation, label loading, attachment upload, comment creation, or repo loading.
|
|
- Network-level Gitea failures should include the configured Gitea API base URL and mention checks for `VITE_GITEA_BASE_URL`, Chrome extension host permissions, network/VPN access, token scope, and attachment size.
|
|
|
|
## URL Management
|
|
|
|
- URLs can be deleted from the URLs list.
|
|
- Add URL must live inside the URLs view as a first-row Add URL button that opens a modal dialog.
|
|
- Deleting a user-added URL removes it from `silmaAide.userUrls` in `chrome.storage.local`.
|
|
- Deleting a generated known URL stores its base URL in `silmaAide.deletedUrlBases` so it is hidden without editing generated local context.
|
|
|
|
## Agent Management
|
|
|
|
- The Agents view must allow adding, editing, and deleting agent files.
|
|
- At least one agent must remain available so Add Issue always has a handoff file.
|
|
- Agent records are persisted in `silmaAide.agents`.
|
|
- The default `GLOBAL AGENT` should remain agnostic and use template variables instead of hard-coded project paths where possible. The built-in persisted global agent should pick up required completion rules without replacing unrelated custom text.
|
|
|
|
## Agent Checklist
|
|
|
|
1. Run `npm run build`.
|
|
2. Confirm `npm run verify:dist` passes.
|
|
3. Use the `Silma` Chrome profile through the Codex Chrome extension.
|
|
4. Load or reload the `dist/` directory.
|
|
5. Avoid `Profile 1`.
|