wip: snapshot das alterações não commitadas (2026-10-20)

Origem: D:/Documents/Github/PiAgentUI/PiAgentUi Arquivos omitidos (segredos, bancos de dados, logs, >50 MB): 4
2026-10-20 00:48:28 -03:00
1 parent b3489e1ede
commit 98b5db029f
@@ -0,0 +1,97 @@
+# Spec: Tauri Pi Agent Integrated App
+
+## Objective
+
+Build PiAgentUI into a faster desktop-first Tauri app where creating a new agent session is near-instant from the user's perspective while Pi remains the authoritative runtime. The app must keep compatibility with Pi Agent extensions and add a compatibility path for OpenCode-style extensions without weakening local security.
+
+Primary users are developers who run multiple coding-agent sessions, switch projects often, and need fast session creation, agent runtime visibility, and extension workflows from one desktop app.
+
+## Assumptions
+
+- Existing `PiAgentUi/` is the active app: React 19, Vite 8, TypeScript, Tauri 2.
+- Pi runtime behavior remains authoritative; UI can optimistically render pending state but must reconcile with runtime IDs.
+- Pi extension compatibility means preserving package `pi.extensions` discovery and current `extensions/piagentui-server.ts` behavior.
+- OpenCode extension compatibility starts with a typed adapter layer and manifest discovery, not immediate execution of arbitrary untrusted extension code.
+- No dependency or lockfile changes without explicit approval.
+
+## Tech Stack
+
+- Frontend: React 19, TypeScript 5.9, Tailwind CSS v4, Vite 8.
+- Desktop: Tauri 2.
+- Local backend: Pi extension server in `extensions/piagentui-server.ts`.
+- Tests: Vitest and Testing Library.
+- Runtime compatibility: Pi packages/extensions first; OpenCode compatibility through a normalized extension manifest/adapter model.
+
+## Commands
+
+- Dev: `npm run dev`
+- Desktop dev: `npm run tauri dev`
+- Targeted test: `npx vitest run <path>`
+- Full app check: `npm run check`
+- Typecheck: `npm run typecheck && npm run typecheck:extensions`
+
+## Project Structure
+
+- `src/features/sessions/` — fast session launch UX, optimistic session draft helpers, session route behavior.
+- `src/store/` — session list/message state reconciliation.
+- `src/api/` — typed client methods to call local PiAgentUI endpoints.
+- `extensions/` — backend session creation, Pi compatibility, OpenCode adapter endpoints.
+- `src-tauri/` — desktop shell, permissions, Tauri config.
+- `docs/superpowers/specs/` — specs.
+- `docs/superpowers/plans/` — implementation plans.
+
+## Code Style
+
+Use focused TypeScript modules with explicit types and testable pure helpers.
+
+```ts
+export interface OptimisticSessionDraftInput {
+  directory?: string
+  title?: string
+  parentID?: string
+  id?: string
+  now?: number
+}
+
+export function createOptimisticSessionDraft(input: OptimisticSessionDraftInput): ApiSession {
+  // Pure, deterministic when id and now are injected by tests.
+}
+```
+
+## Testing Strategy
+
+- TDD for every new behavior.
+- Pure session/extension helpers get small Vitest unit tests.
+- React integration changes get Testing Library tests.
+- Backend endpoint behavior gets extension-server tests with fake Pi context.
+- Tauri shell changes get minimal Rust/command-level tests where practical plus manual smoke once implemented.
+
+## Boundaries
+
+- Always: keep Pi runtime authoritative; add tests before behavior; avoid lockfile changes; keep secrets backend-only.
+- Ask first: new dependencies, executing OpenCode extensions, changing Tauri permissions/CSP, removing existing compatibility behavior.
+- Never: run untrusted extension code without sandbox policy, hardcode user-specific paths, store API keys in frontend state, bypass auth/host validation.
+
+## Success Criteria
+
+- New session action gives immediate visual feedback and navigates without a blank/grey wait state.
+- Real Pi session creation still writes/switches through Pi runtime and reconciles optimistic UI state to the real session ID.
+- Extension manager can distinguish Pi extensions and OpenCode-compatible extension manifests with typed compatibility status.
+- Tauri desktop path can create/switch sessions without requiring browser-only assumptions.
+- Existing tests pass for touched modules; new behavior has tests.
+
+## Risks and Mitigations
+
+- Session ID mismatch between optimistic UI and Pi runtime: store pending sessions under a prefixed temporary ID and atomically replace on success.
+- Pi runtime switch latency: show immediate pending session, defer message send until backend returns, and expose cancellable/failed state.
+- Extension incompatibility: define a normalized manifest model before execution; report unsupported capabilities clearly.
+- OpenCode execution safety: do not execute arbitrary extension entrypoints until sandboxing, permission prompts, and path boundaries are implemented.
+- Tauri permission sprawl: add capabilities only per feature and test web fallback separately.
+- Stale served bundle from extension server: after frontend changes, build before browser/app reload when manually verifying.
+- Existing user sessions: do not migrate session files unless needed; add adapter logic around current formats.
+- Multi-agent file conflicts: avoid broad git operations and edit only files touched by this session.
+
+## Open Questions
+
+- Exact OpenCode extension manifest sources and execution semantics need confirmation before execution support.
+- Visual direction is not finalized because `.impeccable.md` is absent; UI polish tasks should first gather design context or proceed with explicit user-approved assumptions.