dockit

Imported from geek-fun/dockit (AGENTS.md). Install upstream with npx skills add geek-fun/dockit. Copyright stays with the author.

DocKit - AI Agent Guidelines

⚠️ Git: Never commit or push unless the user explicitly asks

• Do NOT commit any change unless the user says "commit", "push", "create a PR", or similar explicit instruction.
• Stack changes in the working tree. Batch related fixes together. Let the user decide when to commit.
• Multiple small commits on a PR create noise and make review harder.
• If you're unsure whether a change is commit-worthy, discuss it with the user first.

Project Overview

DocKit is a Tauri v2 + Vue 3 + TypeScript desktop client for NoSQL databases (Elasticsearch, OpenSearch, DynamoDB).

Tech Stack: Tauri v2 (Rust backend), Vue 3 (Composition API), TypeScript, Monaco Editor, shadcn-vue + UnoCSS (styling).

Key Directories:

• src/ - Vue frontend application
• src-tauri/ - Rust backend (Tauri)
• src/composables/ - Vue composables (reusable logic)
• src/views/ - Page-level components
• src/components/ - Shared UI components
• src/components/ui/ - shadcn-vue components

Coding/Architecture Guidelines

Functional TypeScript

• Define functions as const xxx = (...) => .... Prefer functional decomposition over OOP.
• Avoid classes unless strictly necessary.

Declarative/Functional Collection Handling

• Replace for/while loops with map, filter, find, some, every, reduce, flatMap (and sort when appropriate).
• Favor pipeline-style transformations over step-by-step imperative logic.

Immutability

• Avoid in-place mutation (push, splice, mutating objects/arrays, shared mutable state).
• Instead, return new arrays/objects and model changes as explicit state-transform functions (e.g., reducers).

Pure Functions

• Keep functions small, composable, and side-effect-free where possible.
• If effects are required (I/O, logging), isolate them at the boundaries and keep core logic pure.

Types

• Prefer type/enum over interface where possible.
• Use type when it can fully replace an interface.

Module Boundaries

• Each module should export only via its index.ts.
• Avoid deep imports (e.g., import from src/composables/useKeyboardShortcuts → use src/composables).

Export Discipline

• Only export functions/types/constants that are used outside the module.

Provider-Agnostic Design

• Keep provider-agnostic abstractions and follow clean separation of concerns.

Comments and Documentation

• Use as few inline comments as possible.
• Behavior should be clear from tests and naming.

Styling Conventions

• UnoCSS for utility-first atomic CSS (loaded via virtual:uno.css)
• shadcn-vue for UI components (Radix Vue-based, headless)
• Theme tokens via CSS variables in src/assets/styles/index.css
• See uno.config.ts for UnoCSS presets and theme configuration

Code Quality Tools

• ESLint: npm run lint:check (check violations), npm run lint:fix (auto-fix)
• TypeScript: Strict mode enabled (noUnusedLocals, noUnusedParameters, noFallthroughCasesInSwitch)
• Prettier: Single quotes, 100 char width, 2-space indent, semicolons, arrow parens avoid

Build Commands

npm install        # Install dependencies
npm run tauri dev  # Compile and run (development)
npm run lint:check # Check ESLint violations
npm run lint:fix   # Auto-fix ESLint issues
npx tsc --noEmit   # TypeScript type check

Shared Utilities — Impact Analysis Required

Modifying any of these requires the systemic impact analysis defined in the global AGENTS.md (Rule 5). Before changing, trace all call sites and verify no silent regressions.

Rust (src-tauri/)

TypeScript (src/)

Typical Caller Counts

When in doubt, grep the project for the symbol name. If a function has 3+ callers across 2+ files, apply the impact table rule. Rust utilities like create_http_client (10 callers) and TypeScript configs like PROVIDER_PRESETS (consumed by the entire provider pipeline) are the highest-risk categories.

Pipeline Tracing — Required Before Any Bug Fix

Before implementing any fix, trace the FULL pipeline end-to-end. Document each layer.

Common Dockit Pipelines

ChatPanel Scroll Behavior

The ChatPanel component (src/components/chat-panel.vue) implements a specific scroll contract that must be preserved:

Key variables in the component:

• stickToBottom (Ref<boolean>) — controls whether auto-scroll is active
• lastScrollTop (number) — previous viewport scrollTop, used by decideStickOnScroll to detect genuine upward scroll
• scrollRafId — rAF batching guard, prevents redundant scroll calls within one frame
• statusDoneTimer (ReturnType<typeof setTimeout>) — 300ms delayed re-scroll after status → 'done', cleared in onBeforeUnmount
• virtualizerRef — ref to virtua's Virtualizer component, exposes scrollToIndex(index) for reliable scroll-to-last-item (used in scrollToLastMessage and forceScrollToBottom)

Scroll decision logic lives in src/common/scrollStickiness.ts (pure functions: isNearBottom, decideStickOnScroll, shouldRestickOnLengthChange, computeStreamingSignature, isStatusDoneTransition; constants STICKY_THRESHOLD_PX = 32, SCROLL_UP_THRESHOLD_PX = 2), unit-tested in tests/common/scrollStickiness.test.ts. The component contains only thin DOM/rAF/Virtualizer wiring. A browser harness at tests/manual/scroll-harness.html (served via npx vite) exercises the same module against a real scrollable DOM for manual QA.

When modifying this behavior:

• Never remove the scroll event listener ('scroll' on viewport element) — it's the only mechanism that detects user scroll-up
• Never remove the stickToBottom guard in scrollToBottomBatched() — without it, the panel would jump to bottom while user is reading history
• Always call forceScrollToBottom() before emit('send', ...) in send/continue handlers — this ensures the user's action overrides any scroll-up state
• forceScrollToBottom(), onMounted and the append watcher use scrollToLastMessage() (Virtualizer scrollToIndex API) for scroll-to-bottom — do NOT revert to DOM scrollTop = scrollHeight for mount/force/append scroll. The Virtualizer computes scrollHeight asynchronously and DOM scroll is unreliable before item sizes are measured (an appended message scrolled by DOM scrollHeight lands short of the new message).
• Streaming scroll (scrollToBottomBatched) uses DOM scrollTop = scrollHeight — this works during streaming because virtua has already rendered the items and updates scrollHeight incrementally
• Keep the pure decision functions in src/common/scrollStickiness.ts — do not re-inline threshold/decision logic into the component (it would lose unit-test coverage)

Known Failure Modes (from real bugs)