Matthew Raymer
10 hours ago
51 changed files with 1432 additions and 425 deletions
@ -0,0 +1,63 @@ |
|||||
|
# ADR Template |
||||
|
|
||||
|
## ADR-XXXX-YY-ZZ: [Short Title] |
||||
|
|
||||
|
**Date:** YYYY-MM-DD |
||||
|
**Status:** [PROPOSED | ACCEPTED | REJECTED | DEPRECATED | SUPERSEDED] |
||||
|
**Deciders:** [List of decision makers] |
||||
|
**Technical Story:** [Link to issue/PR if applicable] |
||||
|
|
||||
|
## Context |
||||
|
|
||||
|
[Describe the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts.] |
||||
|
|
||||
|
## Decision |
||||
|
|
||||
|
[Describe our response to these forces. We will use the past tense ("We will...").] |
||||
|
|
||||
|
## Consequences |
||||
|
|
||||
|
### Positive |
||||
|
- [List positive consequences] |
||||
|
|
||||
|
### Negative |
||||
|
- [List negative consequences or trade-offs] |
||||
|
|
||||
|
### Neutral |
||||
|
- [List neutral consequences or notes] |
||||
|
|
||||
|
## Alternatives Considered |
||||
|
|
||||
|
- **Alternative 1:** [Description] - [Why rejected] |
||||
|
- **Alternative 2:** [Description] - [Why rejected] |
||||
|
- **Alternative 3:** [Description] - [Why rejected] |
||||
|
|
||||
|
## Implementation Notes |
||||
|
|
||||
|
[Any specific implementation details, migration steps, or technical considerations] |
||||
|
|
||||
|
## References |
||||
|
|
||||
|
- [Link to relevant documentation] |
||||
|
- [Link to related ADRs] |
||||
|
- [Link to external resources] |
||||
|
|
||||
|
## Related Decisions |
||||
|
|
||||
|
- [List related ADRs or decisions] |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Usage Guidelines |
||||
|
|
||||
|
1. **Copy this template** for new ADRs |
||||
|
2. **Number sequentially** (ADR-001, ADR-002, etc.) |
||||
|
3. **Use descriptive titles** that clearly indicate the decision |
||||
|
4. **Include all stakeholders** in the deciders list |
||||
|
5. **Link to related issues** and documentation |
||||
|
6. **Update status** as decisions evolve |
||||
|
7. **Store in** `doc/architecture-decisions/` directory |
||||
|
description: |
||||
|
globs: |
||||
|
alwaysApply: false |
||||
|
--- |
||||
@ -0,0 +1,172 @@ |
|||||
|
--- |
||||
|
description: |
||||
|
globs: |
||||
|
alwaysApply: true |
||||
|
--- |
||||
|
# TimeSafari Cross-Platform Architecture Guide |
||||
|
|
||||
|
## 1. Platform Support Matrix |
||||
|
|
||||
|
| Feature | Web (PWA) | Capacitor (Mobile) | Electron (Desktop) | |
||||
|
|---------|-----------|--------------------|-------------------| |
||||
|
| QR Code Scanning | WebInlineQRScanner | @capacitor-mlkit/barcode-scanning | Not Implemented | |
||||
|
| Deep Linking | URL Parameters | App URL Open Events | Not Implemented | |
||||
|
| File System | Limited (Browser API) | Capacitor Filesystem | Electron fs | |
||||
|
| Camera Access | MediaDevices API | Capacitor Camera | Not Implemented | |
||||
|
| Platform Detection | Web APIs | Capacitor.isNativePlatform() | process.env checks | |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 2. Project Structure |
||||
|
|
||||
|
### Core Directories |
||||
|
``` |
||||
|
src/ |
||||
|
├── components/ # Vue components |
||||
|
├── services/ # Platform services and business logic |
||||
|
├── views/ # Page components |
||||
|
├── router/ # Vue router configuration |
||||
|
├── types/ # TypeScript type definitions |
||||
|
├── utils/ # Utility functions |
||||
|
├── lib/ # Core libraries |
||||
|
├── platforms/ # Platform-specific implementations |
||||
|
├── electron/ # Electron-specific code |
||||
|
├── constants/ # Application constants |
||||
|
├── db/ # Database related code |
||||
|
├── interfaces/ # TypeScript interfaces |
||||
|
└── assets/ # Static assets |
||||
|
``` |
||||
|
|
||||
|
### Entry Points |
||||
|
- `main.ts` → Base entry |
||||
|
- `main.common.ts` → Shared init |
||||
|
- `main.capacitor.ts` → Mobile entry |
||||
|
- `main.electron.ts` → Electron entry |
||||
|
- `main.web.ts` → Web entry |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 3. Service Architecture |
||||
|
|
||||
|
### Service Organization |
||||
|
|
||||
|
```tree |
||||
|
services/ |
||||
|
├── QRScanner/ |
||||
|
│ ├── WebInlineQRScanner.ts |
||||
|
│ └── interfaces.ts |
||||
|
├── platforms/ |
||||
|
│ ├── WebPlatformService.ts |
||||
|
│ ├── CapacitorPlatformService.ts |
||||
|
│ └── ElectronPlatformService.ts |
||||
|
└── factory/ |
||||
|
└── PlatformServiceFactory.ts |
||||
|
``` |
||||
|
|
||||
|
### Factory Pattern |
||||
|
Use a **singleton factory** to select platform services via `process.env.VITE_PLATFORM`. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 4. Feature Guidelines |
||||
|
|
||||
|
### QR Code Scanning |
||||
|
- Define `QRScannerService` interface. |
||||
|
- Implement platform-specific classes (`WebInlineQRScanner`, Capacitor, etc). |
||||
|
- Provide `addListener` and `onStream` hooks for composability. |
||||
|
|
||||
|
### Deep Linking |
||||
|
- URL format: `timesafari://<route>[/<param>][?query=value]` |
||||
|
- Web: `router.beforeEach` → parse query |
||||
|
- Capacitor: `App.addListener("appUrlOpen", …)` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 5. Build Process |
||||
|
|
||||
|
- `vite.config.common.mts` → shared config |
||||
|
- Platform configs: `vite.config.web.mts`, `.capacitor.mts`, `.electron.mts` |
||||
|
- Use `process.env.VITE_PLATFORM` for conditional loading. |
||||
|
|
||||
|
```bash |
||||
|
npm run build:web |
||||
|
npm run build:capacitor |
||||
|
npm run build:electron |
||||
|
``` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 6. Testing Strategy |
||||
|
|
||||
|
- **Unit tests** for services. |
||||
|
- **Playwright** for Web + Capacitor: |
||||
|
- `playwright.config-local.ts` includes web + Pixel 5. |
||||
|
- **Electron tests**: add `spectron` or Playwright-Electron. |
||||
|
- Mark tests with platform tags: |
||||
|
|
||||
|
```ts |
||||
|
test.skip(!process.env.MOBILE_TEST, "Mobile-only test"); |
||||
|
``` |
||||
|
|
||||
|
> 🔗 **Human Hook:** Before merging new tests, hold a short sync (≤15 min) with QA to align on coverage and flaky test risks. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 7. Error Handling |
||||
|
|
||||
|
- Global Vue error handler → logs with component name. |
||||
|
- Platform-specific wrappers log API errors with platform prefix (`[Capacitor API Error]`, etc). |
||||
|
- Use structured logging (not `console.log`). |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 8. Best Practices |
||||
|
|
||||
|
- Keep platform code **isolated** in `platforms/`. |
||||
|
- Always define a **shared interface** first. |
||||
|
- Use feature detection, not platform detection, when possible. |
||||
|
- Dependency injection for services → improves testability. |
||||
|
- Maintain **Competence Hooks** in PRs (2–3 prompts for dev discussion). |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 9. Dependency Management |
||||
|
|
||||
|
- Key deps: `@capacitor/core`, `electron`, `vue`. |
||||
|
- Use conditional `import()` for platform-specific libs. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 10. Security Considerations |
||||
|
|
||||
|
- **Permissions**: Always check + request gracefully. |
||||
|
- **Storage**: Secure storage for sensitive data; encrypt when possible. |
||||
|
- **Audits**: Schedule quarterly security reviews. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 11. ADR Process |
||||
|
|
||||
|
- All major architecture choices → log in `doc/adr/`. |
||||
|
- Use ADR template with Context, Decision, Consequences, Status. |
||||
|
- Link related ADRs in PR descriptions. |
||||
|
|
||||
|
> 🔗 **Human Hook:** When proposing a new ADR, schedule a 30-min design sync for discussion, not just async review. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 12. Collaboration Hooks |
||||
|
|
||||
|
- **QR features**: Sync with Security before merging → permissions & privacy. |
||||
|
- **New platform builds**: Demo in team meeting → confirm UX differences. |
||||
|
- **Critical ADRs**: Present in guild or architecture review. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
# Self-Check |
||||
|
|
||||
|
- [ ] Does this feature implement a shared interface? |
||||
|
- [ ] Are fallbacks + errors handled gracefully? |
||||
|
- [ ] Have relevant ADRs been updated/linked? |
||||
|
- [ ] Did I add competence hooks or prompts for the team? |
||||
|
- [ ] Was human interaction (sync/review/demo) scheduled? |
||||
@ -1,287 +0,0 @@ |
|||||
--- |
|
||||
description: |
|
||||
globs: |
|
||||
alwaysApply: true |
|
||||
--- |
|
||||
# TimeSafari Cross-Platform Architecture Guide |
|
||||
|
|
||||
## 1. Platform Support Matrix |
|
||||
|
|
||||
| Feature | Web (PWA) | Capacitor (Mobile) | Electron (Desktop) | |
|
||||
|---------|-----------|-------------------|-------------------| |
|
||||
| QR Code Scanning | WebInlineQRScanner | @capacitor-mlkit/barcode-scanning | Not Implemented | |
|
||||
| Deep Linking | URL Parameters | App URL Open Events | Not Implemented | |
|
||||
| File System | Limited (Browser API) | Capacitor Filesystem | Electron fs | |
|
||||
| Camera Access | MediaDevices API | Capacitor Camera | Not Implemented | |
|
||||
| Platform Detection | Web APIs | Capacitor.isNativePlatform() | process.env checks | |
|
||||
|
|
||||
## 2. Project Structure |
|
||||
|
|
||||
### 2.1 Core Directories |
|
||||
``` |
|
||||
src/ |
|
||||
├── components/ # Vue components |
|
||||
├── services/ # Platform services and business logic |
|
||||
├── views/ # Page components |
|
||||
├── router/ # Vue router configuration |
|
||||
├── types/ # TypeScript type definitions |
|
||||
├── utils/ # Utility functions |
|
||||
├── lib/ # Core libraries |
|
||||
├── platforms/ # Platform-specific implementations |
|
||||
├── electron/ # Electron-specific code |
|
||||
├── constants/ # Application constants |
|
||||
├── db/ # Database related code |
|
||||
├── interfaces/ # TypeScript interfaces and type definitions |
|
||||
└── assets/ # Static assets |
|
||||
``` |
|
||||
|
|
||||
### 2.2 Entry Points |
|
||||
``` |
|
||||
src/ |
|
||||
├── main.ts # Base entry |
|
||||
├── main.common.ts # Shared initialization |
|
||||
├── main.capacitor.ts # Mobile entry |
|
||||
├── main.electron.ts # Electron entry |
|
||||
└── main.web.ts # Web/PWA entry |
|
||||
``` |
|
||||
|
|
||||
### 2.3 Build Configurations |
|
||||
``` |
|
||||
root/ |
|
||||
├── vite.config.common.mts # Shared config |
|
||||
├── vite.config.capacitor.mts # Mobile build |
|
||||
├── vite.config.electron.mts # Electron build |
|
||||
└── vite.config.web.mts # Web/PWA build |
|
||||
``` |
|
||||
|
|
||||
## 3. Service Architecture |
|
||||
|
|
||||
### 3.1 Service Organization |
|
||||
``` |
|
||||
services/ |
|
||||
├── QRScanner/ # QR code scanning service |
|
||||
│ ├── WebInlineQRScanner.ts |
|
||||
│ └── interfaces.ts |
|
||||
├── platforms/ # Platform-specific services |
|
||||
│ ├── WebPlatformService.ts |
|
||||
│ ├── CapacitorPlatformService.ts |
|
||||
│ └── ElectronPlatformService.ts |
|
||||
└── factory/ # Service factories |
|
||||
└── PlatformServiceFactory.ts |
|
||||
``` |
|
||||
|
|
||||
### 3.2 Service Factory Pattern |
|
||||
```typescript |
|
||||
// PlatformServiceFactory.ts |
|
||||
export class PlatformServiceFactory { |
|
||||
private static instance: PlatformService | null = null; |
|
||||
|
|
||||
public static getInstance(): PlatformService { |
|
||||
if (!PlatformServiceFactory.instance) { |
|
||||
const platform = process.env.VITE_PLATFORM || "web"; |
|
||||
PlatformServiceFactory.instance = createPlatformService(platform); |
|
||||
} |
|
||||
return PlatformServiceFactory.instance; |
|
||||
} |
|
||||
} |
|
||||
``` |
|
||||
|
|
||||
## 4. Feature Implementation Guidelines |
|
||||
|
|
||||
### 4.1 QR Code Scanning |
|
||||
|
|
||||
1. **Service Interface** |
|
||||
```typescript |
|
||||
interface QRScannerService { |
|
||||
checkPermissions(): Promise<boolean>; |
|
||||
requestPermissions(): Promise<boolean>; |
|
||||
isSupported(): Promise<boolean>; |
|
||||
startScan(): Promise<void>; |
|
||||
stopScan(): Promise<void>; |
|
||||
addListener(listener: ScanListener): void; |
|
||||
onStream(callback: (stream: MediaStream | null) => void): void; |
|
||||
cleanup(): Promise<void>; |
|
||||
} |
|
||||
``` |
|
||||
|
|
||||
2. **Platform-Specific Implementation** |
|
||||
```typescript |
|
||||
// WebInlineQRScanner.ts |
|
||||
export class WebInlineQRScanner implements QRScannerService { |
|
||||
private scanListener: ScanListener | null = null; |
|
||||
private isScanning = false; |
|
||||
private stream: MediaStream | null = null; |
|
||||
private events = new EventEmitter(); |
|
||||
|
|
||||
// Implementation of interface methods |
|
||||
} |
|
||||
``` |
|
||||
|
|
||||
### 4.2 Deep Linking |
|
||||
|
|
||||
1. **URL Structure** |
|
||||
```typescript |
|
||||
// Format: timesafari://<route>[/<param>][?queryParam1=value1] |
|
||||
interface DeepLinkParams { |
|
||||
route: string; |
|
||||
params?: Record<string, string>; |
|
||||
query?: Record<string, string>; |
|
||||
} |
|
||||
``` |
|
||||
|
|
||||
2. **Platform Handlers** |
|
||||
```typescript |
|
||||
// Capacitor |
|
||||
App.addListener("appUrlOpen", handleDeepLink); |
|
||||
|
|
||||
// Web |
|
||||
router.beforeEach((to, from, next) => { |
|
||||
handleWebDeepLink(to.query); |
|
||||
}); |
|
||||
``` |
|
||||
|
|
||||
## 5. Build Process |
|
||||
|
|
||||
### 5.1 Environment Configuration |
|
||||
```typescript |
|
||||
// vite.config.common.mts |
|
||||
export function createBuildConfig(mode: string) { |
|
||||
return { |
|
||||
define: { |
|
||||
'process.env.VITE_PLATFORM': JSON.stringify(mode), |
|
||||
// PWA is automatically enabled for web platforms via build configuration |
|
||||
__IS_MOBILE__: JSON.stringify(isCapacitor), |
|
||||
__USE_QR_READER__: JSON.stringify(!isCapacitor) |
|
||||
} |
|
||||
}; |
|
||||
} |
|
||||
``` |
|
||||
|
|
||||
### 5.2 Platform-Specific Builds |
|
||||
|
|
||||
```bash |
|
||||
# Build commands from package.json |
|
||||
"build:web": "vite build --config vite.config.web.mts", |
|
||||
"build:capacitor": "vite build --config vite.config.capacitor.mts", |
|
||||
"build:electron": "vite build --config vite.config.electron.mts" |
|
||||
``` |
|
||||
|
|
||||
## 6. Testing Strategy |
|
||||
|
|
||||
### 6.1 Test Configuration |
|
||||
```typescript |
|
||||
// playwright.config-local.ts |
|
||||
const config: PlaywrightTestConfig = { |
|
||||
projects: [ |
|
||||
{ |
|
||||
name: 'web', |
|
||||
use: { browserName: 'chromium' } |
|
||||
}, |
|
||||
{ |
|
||||
name: 'mobile', |
|
||||
use: { ...devices['Pixel 5'] } |
|
||||
} |
|
||||
] |
|
||||
}; |
|
||||
``` |
|
||||
|
|
||||
### 6.2 Platform-Specific Tests |
|
||||
```typescript |
|
||||
test('QR scanning works on mobile', async ({ page }) => { |
|
||||
test.skip(!process.env.MOBILE_TEST, 'Mobile-only test'); |
|
||||
// Test implementation |
|
||||
}); |
|
||||
``` |
|
||||
|
|
||||
## 7. Error Handling |
|
||||
|
|
||||
### 7.1 Global Error Handler |
|
||||
```typescript |
|
||||
function setupGlobalErrorHandler(app: VueApp) { |
|
||||
app.config.errorHandler = (err, instance, info) => { |
|
||||
logger.error("[App Error]", { |
|
||||
error: err, |
|
||||
info, |
|
||||
component: instance?.$options.name |
|
||||
}); |
|
||||
}; |
|
||||
} |
|
||||
``` |
|
||||
|
|
||||
### 7.2 Platform-Specific Error Handling |
|
||||
```typescript |
|
||||
// API error handling for Capacitor |
|
||||
if (process.env.VITE_PLATFORM === 'capacitor') { |
|
||||
logger.error(`[Capacitor API Error] ${endpoint}:`, { |
|
||||
message: error.message, |
|
||||
status: error.response?.status |
|
||||
}); |
|
||||
} |
|
||||
``` |
|
||||
|
|
||||
## 8. Best Practices |
|
||||
|
|
||||
### 8.1 Code Organization |
|
||||
- Use platform-specific directories for unique implementations |
|
||||
- Share common code through service interfaces |
|
||||
- Implement feature detection before using platform capabilities |
|
||||
- Keep platform-specific code isolated in dedicated directories |
|
||||
- Use TypeScript interfaces for cross-platform compatibility |
|
||||
|
|
||||
### 8.2 Platform Detection |
|
||||
```typescript |
|
||||
const platformService = PlatformServiceFactory.getInstance(); |
|
||||
const capabilities = platformService.getCapabilities(); |
|
||||
|
|
||||
if (capabilities.hasCamera) { |
|
||||
// Implement camera features |
|
||||
} |
|
||||
``` |
|
||||
|
|
||||
### 8.3 Feature Implementation |
|
||||
1. Define platform-agnostic interface |
|
||||
2. Create platform-specific implementations |
|
||||
3. Use factory pattern for instantiation |
|
||||
4. Implement graceful fallbacks |
|
||||
5. Add comprehensive error handling |
|
||||
6. Use dependency injection for better testability |
|
||||
|
|
||||
## 9. Dependency Management |
|
||||
|
|
||||
### 9.1 Platform-Specific Dependencies |
|
||||
```json |
|
||||
{ |
|
||||
"dependencies": { |
|
||||
"@capacitor/core": "^6.2.0", |
|
||||
"electron": "^33.2.1", |
|
||||
"vue": "^3.4.0" |
|
||||
} |
|
||||
} |
|
||||
``` |
|
||||
|
|
||||
### 9.2 Conditional Loading |
|
||||
```typescript |
|
||||
if (process.env.VITE_PLATFORM === 'capacitor') { |
|
||||
await import('@capacitor/core'); |
|
||||
} |
|
||||
``` |
|
||||
|
|
||||
## 10. Security Considerations |
|
||||
|
|
||||
### 10.1 Permission Handling |
|
||||
```typescript |
|
||||
async checkPermissions(): Promise<boolean> { |
|
||||
if (platformService.isCapacitor()) { |
|
||||
return await checkNativePermissions(); |
|
||||
} |
|
||||
return await checkWebPermissions(); |
|
||||
} |
|
||||
``` |
|
||||
|
|
||||
### 10.2 Data Storage |
|
||||
- Use secure storage mechanisms for sensitive data |
|
||||
- Implement proper encryption for stored data |
|
||||
- Follow platform-specific security guidelines |
|
||||
- Regular security audits and updates |
|
||||
|
|
||||
This document should be updated as new features are added or platform-specific implementations change. Regular reviews ensure it remains current with the codebase. |
|
||||
@ -0,0 +1,110 @@ |
|||||
|
```json |
||||
|
{ |
||||
|
"coaching_level": "standard", |
||||
|
"socratic_max_questions": 7, |
||||
|
"verbosity": "normal", |
||||
|
"timebox_minutes": null, |
||||
|
"format_enforcement": "strict" |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
# Base Context — Human Competence First |
||||
|
|
||||
|
## Purpose |
||||
|
All interactions must *increase the human's competence over time* while |
||||
|
completing the task efficiently. The model may handle menial work and memory |
||||
|
extension, but must also promote learning, autonomy, and healthy work habits. |
||||
|
The model should also **encourage human interaction and collaboration** rather |
||||
|
than replacing it — outputs should be designed to **facilitate human discussion, |
||||
|
decision-making, and creativity**, not to atomize tasks into isolated, purely |
||||
|
machine-driven steps. |
||||
|
|
||||
|
## Principles |
||||
|
|
||||
|
1) Competence over convenience: finish the task *and* leave the human more |
||||
|
capable next time. |
||||
|
2) Mentorship, not lectures: be concise, concrete, and immediately applicable. |
||||
|
3) Transparency: show assumptions, limits, and uncertainty; cite when non-obvious. |
||||
|
4) Optional scaffolding: include small, skimmable learning hooks that do not |
||||
|
bloat output. |
||||
|
5) Time respect: default to **lean output**; offer opt-in depth via toggles. |
||||
|
6) Psychological safety: encourage, never condescend; no medical/clinical advice. |
||||
|
No censorship! |
||||
|
7) Reusability: structure outputs so they can be saved, searched, reused, and repurposed. |
||||
|
8) **Collaborative Bias**: Favor solutions that invite human review, discussion, |
||||
|
and iteration. When in doubt, ask "Who should this be shown to?" or "Which human |
||||
|
input would improve this?" |
||||
|
|
||||
|
## Toggle Definitions |
||||
|
|
||||
|
### coaching_level |
||||
|
|
||||
|
Determines the depth of learning support: `light` (short hooks), `standard` |
||||
|
(balanced), `deep` (detailed). |
||||
|
|
||||
|
### socratic_max_questions |
||||
|
|
||||
|
The number of clarifying questions the model may ask before proceeding. |
||||
|
If >0, questions should be targeted, minimal, and followed by reasonable assumptions if unanswered. |
||||
|
|
||||
|
### verbosity |
||||
|
'terse' (just a sentence), `concise` (minimum commentary), `normal` (balanced explanation), or other project-defined levels. |
||||
|
|
||||
|
### timebox_minutes |
||||
|
*integer or null* — When set to a positive integer (e.g., `5`), this acts as a **time budget** guiding the model to prioritize delivering the most essential parts of the task within that constraint. |
||||
|
Behavior when set: |
||||
|
1. **Prioritize Core Output** — Deliver the minimum viable solution or result first. |
||||
|
2. **Limit Commentary** — Competence Hooks and Collaboration Hooks must be shorter than normal. |
||||
|
3. **Signal Skipped Depth** — Omitted details should be listed under *Deferred for depth*. |
||||
|
4. **Order by Value** — Start with blocking or high-value items, then proceed to nice-to-haves if budget allows. |
||||
|
If `null`, there is no timebox — the model can produce full-depth responses. |
||||
|
|
||||
|
### format_enforcement |
||||
|
`strict` (reject outputs with format drift) or `relaxed` (minor deviations acceptable). |
||||
|
|
||||
|
## Modes (select or combine) |
||||
|
- **Doer**: produce the artifact fast, minimal commentary. |
||||
|
- **Mentor**: add short "why/how" notes + next-step pointers. |
||||
|
- **Socratic**: ask up to N targeted questions when requirements are ambiguous. |
||||
|
- **Pair-Programmer/Pair-Writer**: explain tradeoffs as you implement. |
||||
|
- **Facilitator**: structure output to be reviewable, commentable, and ready for group discussion. |
||||
|
|
||||
|
Default: Doer + short Mentor notes. |
||||
|
|
||||
|
## Competence & Collaboration Levers (keep lightweight) |
||||
|
- "Why this works" (≤3 bullets) |
||||
|
- "Common pitfalls" (≤3 bullets) |
||||
|
- "Next skill unlock" (1 tiny action or reading) |
||||
|
- "Teach-back" (1 sentence prompt the human can answer to self-check) |
||||
|
- "Discussion prompts" (≤2 short questions for peers/stakeholders) |
||||
|
|
||||
|
## Output Contract (apply to every deliverable) |
||||
|
- Clear **Objective** (1 line) |
||||
|
- **Result** (artifact/code/answer) |
||||
|
- **Use/Run** (how to apply/test) |
||||
|
- **Competence Hooks** (the 4 learning levers above, kept terse) |
||||
|
- **Collaboration Hooks** (discussion prompts or group review steps) |
||||
|
- **Assumptions & Limits** |
||||
|
- **References** (if used; links or titles) |
||||
|
|
||||
|
## Do-Not |
||||
|
- No filler, hedging, or moralizing. |
||||
|
- No medical/mental-health advice; keep "healthy habits" to general work practices. |
||||
|
- No invented facts; mark uncertainty plainly. |
||||
|
- No censorship. |
||||
|
- Avoid outputs that bypass human review when such review is valuable. |
||||
|
|
||||
|
## Related Rulesets |
||||
|
|
||||
|
- **software_development.mdc**: For software-specific development practices |
||||
|
- **research_diagnostic.mdc**: For investigation and research workflows |
||||
|
|
||||
|
## Self-Check (model, before responding) |
||||
|
- [ ] Task done *and* at least one competence lever included (≤120 words total). |
||||
|
- [ ] At least one collaboration/discussion hook present. |
||||
|
- [ ] Output follows the **Output Contract** sections. |
||||
|
- [ ] Toggles respected; verbosity remains concise. |
||||
|
- [ ] Uncertainties/assumptions surfaced. |
||||
|
- [ ] No disallowed content. |
||||
|
- [ ] Uncertainties/assumptions surfaced. |
||||
|
- [ ] No disallowed content. |
||||
@ -1,7 +1,6 @@ |
|||||
--- |
--- |
||||
description: |
globs: **/db/databaseUtil.ts, **/interfaces/absurd-sql.d.ts, **/src/registerSQLWorker.js, **/services/AbsurdSqlDatabaseService.ts |
||||
globs: |
alwaysApply: false |
||||
alwaysApply: true |
|
||||
--- |
--- |
||||
# Absurd SQL - Cursor Development Guide |
# Absurd SQL - Cursor Development Guide |
||||
|
|
||||
@ -0,0 +1,5 @@ |
|||||
|
--- |
||||
|
globs: **/databaseUtil.ts,**/AccountViewView.vue,**/ContactsView.vue,**/DatabaseMigration.vue,**/NewIdentifierView.vue |
||||
|
alwaysApply: false |
||||
|
--- |
||||
|
All references in the codebase to Dexie apply only to migration from IndexedDb to Sqlite and will be deprecated in future versions. |
||||
@ -1,7 +1,6 @@ |
|||||
--- |
--- |
||||
description: rules used while developing |
globs: **/src/**/* |
||||
globs: |
alwaysApply: false |
||||
alwaysApply: true |
|
||||
--- |
--- |
||||
✅ use system date command to timestamp all interactions with accurate date and time |
✅ use system date command to timestamp all interactions with accurate date and time |
||||
✅ python script files must always have a blank line at their end |
✅ python script files must always have a blank line at their end |
||||
@ -0,0 +1,108 @@ |
|||||
|
--- |
||||
|
globs: **/src/**/*,**/scripts/**/*,**/electron/**/* |
||||
|
alwaysApply: false |
||||
|
--- |
||||
|
```json |
||||
|
{ |
||||
|
"coaching_level": "light", |
||||
|
"socratic_max_questions": 7, |
||||
|
"verbosity": "concise", |
||||
|
"timebox_minutes": null, |
||||
|
"format_enforcement": "strict" |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
# TypeScript Type Safety Guidelines |
||||
|
|
||||
|
**Author**: Matthew Raymer |
||||
|
**Date**: 2025-08-16 |
||||
|
**Status**: 🎯 **ACTIVE** |
||||
|
|
||||
|
## Overview |
||||
|
|
||||
|
Practical rules to keep TypeScript strict and predictable. Minimize exceptions. |
||||
|
|
||||
|
## Core Rules |
||||
|
|
||||
|
1. **No `any`** |
||||
|
- Use explicit types. If unknown, use `unknown` and **narrow** via guards. |
||||
|
|
||||
|
2. **Error handling uses guards** |
||||
|
- Reuse guards from `src/interfaces/**` (e.g., `isDatabaseError`, `isApiError`). |
||||
|
- Catch with `unknown`; never cast to `any`. |
||||
|
|
||||
|
3. **Dynamic property access is type‑safe** |
||||
|
- Use `keyof` + `in` checks: |
||||
|
|
||||
|
```ts |
||||
|
obj[k as keyof typeof obj] |
||||
|
``` |
||||
|
|
||||
|
- Avoid `(obj as any)[k]`. |
||||
|
|
||||
|
## Minimal Special Cases (document in PR when used) |
||||
|
|
||||
|
- **Vue refs / instances**: Use `ComponentPublicInstance` or specific component |
||||
|
types for dynamic refs. |
||||
|
- **3rd‑party libs without types**: Narrow immediately to a **known interface**; |
||||
|
do not leave `any` hanging. |
||||
|
|
||||
|
## Patterns (short) |
||||
|
|
||||
|
### Database errors |
||||
|
|
||||
|
```ts |
||||
|
try { await this.$addContact(contact); } |
||||
|
catch (e: unknown) { |
||||
|
if (isDatabaseError(e) && e.message.includes("Key already exists")) { |
||||
|
/* handle duplicate */ |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
### API errors |
||||
|
|
||||
|
```ts |
||||
|
try { await apiCall(); } |
||||
|
catch (e: unknown) { |
||||
|
if (isApiError(e)) { |
||||
|
const msg = e.response?.data?.error?.message; |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
### Dynamic keys |
||||
|
|
||||
|
```ts |
||||
|
const keys = Object.keys(newSettings).filter( |
||||
|
k => k in newSettings && newSettings[k as keyof typeof newSettings] !== undefined |
||||
|
); |
||||
|
``` |
||||
|
|
||||
|
## Checklists |
||||
|
|
||||
|
**Before commit** |
||||
|
|
||||
|
- [ ] No `any` (except documented, justified cases) |
||||
|
- [ ] Errors handled via guards |
||||
|
- [ ] Dynamic access uses `keyof`/`in` |
||||
|
- [ ] Imports point to correct interfaces/types |
||||
|
|
||||
|
**Code review** |
||||
|
|
||||
|
- [ ] Hunt hidden `as any` |
||||
|
- [ ] Guard‑based error paths verified |
||||
|
- [ ] Dynamic ops are type‑safe |
||||
|
- [ ] Prefer existing types over re‑inventing |
||||
|
|
||||
|
## Tools |
||||
|
|
||||
|
- `npm run lint-fix` — lint & auto‑fix |
||||
|
- `npm run type-check` — strict type compilation (CI + pre‑release) |
||||
|
- IDE: enable strict TS, ESLint/TS ESLint, Volar (Vue 3) |
||||
|
|
||||
|
## References |
||||
|
|
||||
|
- TS Handbook — https://www.typescriptlang.org/docs/ |
||||
|
- TS‑ESLint — https://typescript-eslint.io/rules/ |
||||
|
- Vue 3 + TS — https://vuejs.org/guide/typescript/ |
||||
@ -0,0 +1,76 @@ |
|||||
|
# Investigation Report Example |
||||
|
|
||||
|
## Investigation — Registration Dialog Test Flakiness |
||||
|
|
||||
|
## Objective |
||||
|
Identify root cause of flaky tests related to registration dialogs in contact import scenarios. |
||||
|
|
||||
|
## System Map |
||||
|
- User action → ContactInputForm → ContactsView.addContact() → handleRegistrationPrompt() |
||||
|
- setTimeout(1000ms) → Modal dialog → User response → Registration API call |
||||
|
- Test execution → Wait for dialog → Assert dialog content → Click response button |
||||
|
|
||||
|
## Findings (Evidence) |
||||
|
- **1-second timeout causes flakiness** — evidence: `src/views/ContactsView.vue:971-1000`; setTimeout(..., 1000) in handleRegistrationPrompt() |
||||
|
- **Import flow bypasses dialogs** — evidence: `src/views/ContactImportView.vue:500-520`; importContacts() calls $insertContact() directly, no handleRegistrationPrompt() |
||||
|
- **Dialog only appears in direct add flow** — evidence: `src/views/ContactsView.vue:774-800`; addContact() calls handleRegistrationPrompt() after database insert |
||||
|
|
||||
|
## Hypotheses & Failure Modes |
||||
|
- H1: 1-second timeout makes dialog appearance unpredictable; would fail when tests run faster than 1000ms |
||||
|
- H2: Test environment timing differs from development; watch for CI vs local test differences |
||||
|
|
||||
|
## Corrections |
||||
|
- Updated: "Multiple dialogs interfere with imports" → "Import flow never triggers dialogs - they only appear in direct contact addition" |
||||
|
- Updated: "Complex batch registration needed" → "Simple timeout removal and test mode flag sufficient" |
||||
|
|
||||
|
## Diagnostics (Next Checks) |
||||
|
- [ ] Repro on CI environment vs local |
||||
|
- [ ] Measure actual dialog appearance timing |
||||
|
- [ ] Test with setTimeout removed |
||||
|
- [ ] Verify import flow doesn't call handleRegistrationPrompt |
||||
|
|
||||
|
## Risks & Scope |
||||
|
- Impacted: Contact addition tests, registration workflow tests; Data: None; Users: Test suite reliability |
||||
|
|
||||
|
## Decision / Next Steps |
||||
|
- Owner: Development Team; By: 2025-01-28 |
||||
|
- Action: Remove 1-second timeout + add test mode flag; Exit criteria: Tests pass consistently |
||||
|
|
||||
|
## References |
||||
|
- `src/views/ContactsView.vue:971-1000` |
||||
|
- `src/views/ContactImportView.vue:500-520` |
||||
|
- `src/views/ContactsView.vue:774-800` |
||||
|
|
||||
|
## Competence Hooks |
||||
|
- Why this works: Code path tracing revealed separate execution flows, evidence disproved initial assumptions |
||||
|
- Common pitfalls: Assuming related functionality without tracing execution paths, over-engineering solutions to imaginary problems |
||||
|
- Next skill: Learn to trace code execution before proposing architectural changes |
||||
|
- Teach-back: "What evidence shows that contact imports bypass registration dialogs?" |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Key Learning Points |
||||
|
|
||||
|
### Evidence-First Approach |
||||
|
This investigation demonstrates the importance of: |
||||
|
1. **Tracing actual code execution** rather than making assumptions |
||||
|
2. **Citing specific evidence** with file:line references |
||||
|
3. **Validating problem scope** before proposing solutions |
||||
|
4. **Considering simpler alternatives** before complex architectural changes |
||||
|
|
||||
|
### Code Path Tracing Value |
||||
|
By tracing the execution paths, we discovered: |
||||
|
- Import flow and direct add flow are completely separate |
||||
|
- The "multiple dialog interference" problem didn't exist |
||||
|
- A simple timeout removal would solve the actual issue |
||||
|
|
||||
|
### Prevention of Over-Engineering |
||||
|
The investigation prevented: |
||||
|
- Unnecessary database schema changes |
||||
|
- Complex batch registration systems |
||||
|
- Migration scripts for non-existent problems |
||||
|
- Architectural changes based on assumptions |
||||
|
description: |
||||
|
globs: |
||||
|
alwaysApply: false |
||||
|
--- |
||||
@ -1,6 +0,0 @@ |
|||||
--- |
|
||||
description: |
|
||||
globs: |
|
||||
alwaysApply: true |
|
||||
--- |
|
||||
All references in the codebase to Dexie apply only to migration from IndexedDb to Sqlite and will be deprecated in future versions. |
|
||||
@ -0,0 +1,170 @@ |
|||||
|
--- |
||||
|
description: Use this workflow when doing **pre-implementation research, defect investigations with uncertain repros, or clarifying system architecture and behaviors**. |
||||
|
alwaysApply: false |
||||
|
--- |
||||
|
```json |
||||
|
{ |
||||
|
"coaching_level": "light", |
||||
|
"socratic_max_questions": 2, |
||||
|
"verbosity": "concise", |
||||
|
"timebox_minutes": null, |
||||
|
"format_enforcement": "strict" |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
# Research & Diagnostic Workflow (R&D) |
||||
|
|
||||
|
## Purpose |
||||
|
|
||||
|
Provide a **repeatable, evidence-first** workflow to investigate features and |
||||
|
defects **before coding**. Outputs are concise reports, hypotheses, and next |
||||
|
steps—**not** code changes. |
||||
|
|
||||
|
## When to Use |
||||
|
|
||||
|
- Pre-implementation research for new features |
||||
|
- Defect investigations (repros uncertain, user-specific failures) |
||||
|
- Architecture/behavior clarifications (e.g., auth flows, merges, migrations) |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Enhanced with Software Development Ruleset |
||||
|
|
||||
|
When investigating software issues, also apply: |
||||
|
- **Code Path Tracing**: Required for technical investigations |
||||
|
- **Evidence Validation**: Ensure claims are code-backed |
||||
|
- **Solution Complexity Assessment**: Justify architectural changes |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Output Contract (strict) |
||||
|
|
||||
|
1) **Objective** — 1–2 lines |
||||
|
2) **System Map (if helpful)** — short diagram or bullet flow (≤8 bullets) |
||||
|
3) **Findings (Evidence-linked)** — bullets; each with file/function refs |
||||
|
4) **Hypotheses & Failure Modes** — short list, each testable |
||||
|
5) **Corrections** — explicit deltas from earlier assumptions (if any) |
||||
|
6) **Diagnostics** — what to check next (logs, DB, env, repro steps) |
||||
|
7) **Risks & Scope** — what could break; affected components |
||||
|
8) **Decision/Next Steps** — what we'll do, who's involved, by when |
||||
|
9) **References** — code paths, ADRs, docs |
||||
|
10) **Competence & Collaboration Hooks** — brief, skimmable |
||||
|
|
||||
|
> Keep total length lean. Prefer links and bullets over prose. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Quickstart Template |
||||
|
|
||||
|
Copy/paste and fill: |
||||
|
|
||||
|
```md |
||||
|
# Investigation — <short title> |
||||
|
|
||||
|
## Objective |
||||
|
<one or two lines> |
||||
|
|
||||
|
## System Map |
||||
|
- <module> → <function> → <downstream> |
||||
|
- <data path> → <db table> → <api> |
||||
|
|
||||
|
## Findings (Evidence) |
||||
|
- <claim> — evidence: `src/path/file.ts:function` (lines X–Y); log snippet/trace id |
||||
|
- <claim> — evidence: `...` |
||||
|
|
||||
|
## Hypotheses & Failure Modes |
||||
|
- H1: <hypothesis>; would fail when <condition> |
||||
|
- H2: <hypothesis>; watch for <signal> |
||||
|
|
||||
|
## Corrections |
||||
|
- Updated: <old statement> → <new statement with evidence> |
||||
|
|
||||
|
## Diagnostics (Next Checks) |
||||
|
- [ ] Repro on <platform/version> |
||||
|
- [ ] Inspect <table/store> for <record> |
||||
|
- [ ] Capture <log/trace> |
||||
|
|
||||
|
## Risks & Scope |
||||
|
- Impacted: <areas/components>; Data: <tables/keys>; Users: <segments> |
||||
|
|
||||
|
## Decision / Next Steps |
||||
|
- Owner: <name>; By: <date> (YYYY-MM-DD) |
||||
|
- Action: <spike/bugfix/ADR>; Exit criteria: <binary checks> |
||||
|
|
||||
|
## References |
||||
|
- `src/...` |
||||
|
- ADR: `docs/adr/xxxx-yy-zz-something.md` |
||||
|
- Design: `docs/...` |
||||
|
|
||||
|
## Competence Hooks |
||||
|
- Why this works: <≤3 bullets> |
||||
|
- Common pitfalls: <≤3 bullets> |
||||
|
- Next skill: <≤1 item> |
||||
|
- Teach-back: "<one question>" |
||||
|
``` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Evidence Quality Bar |
||||
|
|
||||
|
- **Cite the source** (file:func, line range if possible). |
||||
|
- **Prefer primary evidence** (code, logs) over inference. |
||||
|
- **Disambiguate platform** (Web/Capacitor/Electron) and **state** (migration, auth). |
||||
|
- **Note uncertainty** explicitly. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Code Path Tracing (Required for Software Investigations) |
||||
|
|
||||
|
Before proposing solutions, trace the actual execution path: |
||||
|
- [ ] **Entry Points**: Identify where the flow begins (user action, API call, etc.) |
||||
|
- [ ] **Component Flow**: Map which components/methods are involved |
||||
|
- [ ] **Data Path**: Track how data moves through the system |
||||
|
- [ ] **Exit Points**: Confirm where the flow ends and what results |
||||
|
- [ ] **Evidence Collection**: Gather specific code citations for each step |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Collaboration Hooks |
||||
|
|
||||
|
- **Syncs:** 10–15m with QA/Security/Platform owners for high-risk areas. |
||||
|
- **ADR:** Record major decisions; link here. |
||||
|
- **Review:** Share repro + diagnostics checklist in PR/issue. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Integration with Other Rulesets |
||||
|
|
||||
|
### With software_development.mdc |
||||
|
- **Enhanced Evidence Validation**: Use code path tracing for technical investigations |
||||
|
- **Architecture Assessment**: Apply complexity justification to proposed solutions |
||||
|
- **Impact Analysis**: Assess effects on existing systems before recommendations |
||||
|
|
||||
|
### With base_context.mdc |
||||
|
- **Competence Building**: Focus on technical investigation skills |
||||
|
- **Collaboration**: Structure outputs for team review and discussion |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Self-Check (model, before responding) |
||||
|
|
||||
|
- [ ] Output matches the **Output Contract** sections. |
||||
|
- [ ] Each claim has **evidence** or **uncertainty** is flagged. |
||||
|
- [ ] Hypotheses are testable; diagnostics are actionable. |
||||
|
- [ ] Competence + collaboration hooks present (≤120 words total). |
||||
|
- [ ] Respect toggles; keep it concise. |
||||
|
- [ ] **Code path traced** (for software investigations). |
||||
|
- [ ] **Evidence validated** against actual code execution. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Optional Globs (examples) |
||||
|
|
||||
|
> Uncomment `globs` in the header if you want auto-attach behavior. |
||||
|
|
||||
|
- `src/platforms/**`, `src/services/**` — attach during service/feature investigations |
||||
|
- `docs/adr/**` — attach when editing ADRs |
||||
|
|
||||
|
## Referenced Files |
||||
|
|
||||
|
- Consider including templates as context: `@adr_template.mdc`, `@investigation_report_example.mdc` |
||||
@ -0,0 +1,178 @@ |
|||||
|
--- |
||||
|
alwaysApply: true |
||||
|
--- |
||||
|
|
||||
|
# Software Development Ruleset |
||||
|
|
||||
|
## Purpose |
||||
|
Specialized guidelines for software development tasks including code review, debugging, architecture decisions, and testing. |
||||
|
|
||||
|
## Core Principles |
||||
|
|
||||
|
### 1. Evidence-First Development |
||||
|
- **Code Citations Required**: Always cite specific file:line references when making claims |
||||
|
- **Execution Path Tracing**: Trace actual code execution before proposing architectural changes |
||||
|
- **Assumption Validation**: Flag assumptions as "assumed" vs "evidence-based" |
||||
|
|
||||
|
### 2. Code Review Standards |
||||
|
- **Trace Before Proposing**: Always trace execution paths before suggesting changes |
||||
|
- **Evidence Over Inference**: Prefer code citations over logical deductions |
||||
|
- **Scope Validation**: Confirm the actual scope of problems before proposing solutions |
||||
|
|
||||
|
### 3. Problem-Solution Validation |
||||
|
- **Problem Scope**: Does the solution address the actual problem? |
||||
|
- **Evidence Alignment**: Does the solution match the evidence? |
||||
|
- **Complexity Justification**: Is added complexity justified by real needs? |
||||
|
- **Alternative Analysis**: What simpler solutions were considered? |
||||
|
|
||||
|
## Required Workflows |
||||
|
|
||||
|
### Before Proposing Changes |
||||
|
- [ ] **Code Path Tracing**: Map execution flow from entry to exit |
||||
|
- [ ] **Evidence Collection**: Gather specific code citations and logs |
||||
|
- [ ] **Assumption Surfacing**: Identify what's proven vs. inferred |
||||
|
- [ ] **Scope Validation**: Confirm the actual extent of the problem |
||||
|
|
||||
|
### During Solution Design |
||||
|
- [ ] **Evidence Alignment**: Ensure solution addresses proven problems |
||||
|
- [ ] **Complexity Assessment**: Justify any added complexity |
||||
|
- [ ] **Alternative Evaluation**: Consider simpler approaches first |
||||
|
- [ ] **Impact Analysis**: Assess effects on existing systems |
||||
|
|
||||
|
## Software-Specific Competence Hooks |
||||
|
|
||||
|
### Evidence Validation |
||||
|
- **"What code path proves this claim?"** |
||||
|
- **"How does data actually flow through the system?"** |
||||
|
- **"What am I assuming vs. what can I prove?"** |
||||
|
|
||||
|
### Code Tracing |
||||
|
- **"What's the execution path from user action to system response?"** |
||||
|
- **"Which components actually interact in this scenario?"** |
||||
|
- **"Where does the data originate and where does it end up?"** |
||||
|
|
||||
|
### Architecture Decisions |
||||
|
- **"What evidence shows this change is necessary?"** |
||||
|
- **"What simpler solution could achieve the same goal?"** |
||||
|
- **"How does this change affect the existing system architecture?"** |
||||
|
|
||||
|
## Integration with Other Rulesets |
||||
|
|
||||
|
### With base_context.mdc |
||||
|
- Inherits generic competence principles |
||||
|
- Adds software-specific evidence requirements |
||||
|
- Maintains collaboration and learning focus |
||||
|
|
||||
|
### With research_diagnostic.mdc |
||||
|
- Enhances investigation with code path tracing |
||||
|
- Adds evidence validation to diagnostic workflow |
||||
|
- Strengthens problem identification accuracy |
||||
|
|
||||
|
## Usage Guidelines |
||||
|
|
||||
|
### When to Use This Ruleset |
||||
|
- Code reviews and architectural decisions |
||||
|
- Bug investigation and debugging |
||||
|
- Performance optimization |
||||
|
- Feature implementation planning |
||||
|
- Testing strategy development |
||||
|
|
||||
|
### When to Combine with Others |
||||
|
- **base_context + software_development**: General development tasks |
||||
|
- **research_diagnostic + software_development**: Technical investigations |
||||
|
- **All three**: Complex architectural decisions or major refactoring |
||||
|
|
||||
|
## Self-Check (model, before responding) |
||||
|
- [ ] Code path traced and documented |
||||
|
- [ ] Evidence cited with specific file:line references |
||||
|
- [ ] Assumptions clearly flagged as proven vs. inferred |
||||
|
- [ ] Solution complexity justified by evidence |
||||
|
- [ ] Simpler alternatives considered and documented |
||||
|
- [ ] Impact on existing systems assessed |
||||
|
# Software Development Ruleset |
||||
|
|
||||
|
## Purpose |
||||
|
Specialized guidelines for software development tasks including code review, debugging, architecture decisions, and testing. |
||||
|
|
||||
|
## Core Principles |
||||
|
|
||||
|
### 1. Evidence-First Development |
||||
|
- **Code Citations Required**: Always cite specific file:line references when making claims |
||||
|
- **Execution Path Tracing**: Trace actual code execution before proposing architectural changes |
||||
|
- **Assumption Validation**: Flag assumptions as "assumed" vs "evidence-based" |
||||
|
|
||||
|
### 2. Code Review Standards |
||||
|
- **Trace Before Proposing**: Always trace execution paths before suggesting changes |
||||
|
- **Evidence Over Inference**: Prefer code citations over logical deductions |
||||
|
- **Scope Validation**: Confirm the actual scope of problems before proposing solutions |
||||
|
|
||||
|
### 3. Problem-Solution Validation |
||||
|
- **Problem Scope**: Does the solution address the actual problem? |
||||
|
- **Evidence Alignment**: Does the solution match the evidence? |
||||
|
- **Complexity Justification**: Is added complexity justified by real needs? |
||||
|
- **Alternative Analysis**: What simpler solutions were considered? |
||||
|
|
||||
|
## Required Workflows |
||||
|
|
||||
|
### Before Proposing Changes |
||||
|
- [ ] **Code Path Tracing**: Map execution flow from entry to exit |
||||
|
- [ ] **Evidence Collection**: Gather specific code citations and logs |
||||
|
- [ ] **Assumption Surfacing**: Identify what's proven vs. inferred |
||||
|
- [ ] **Scope Validation**: Confirm the actual extent of the problem |
||||
|
|
||||
|
### During Solution Design |
||||
|
- [ ] **Evidence Alignment**: Ensure solution addresses proven problems |
||||
|
- [ ] **Complexity Assessment**: Justify any added complexity |
||||
|
- [ ] **Alternative Evaluation**: Consider simpler approaches first |
||||
|
- [ ] **Impact Analysis**: Assess effects on existing systems |
||||
|
|
||||
|
## Software-Specific Competence Hooks |
||||
|
|
||||
|
### Evidence Validation |
||||
|
- **"What code path proves this claim?"** |
||||
|
- **"How does data actually flow through the system?"** |
||||
|
- **"What am I assuming vs. what can I prove?"** |
||||
|
|
||||
|
### Code Tracing |
||||
|
- **"What's the execution path from user action to system response?"** |
||||
|
- **"Which components actually interact in this scenario?"** |
||||
|
- **"Where does the data originate and where does it end up?"** |
||||
|
|
||||
|
### Architecture Decisions |
||||
|
- **"What evidence shows this change is necessary?"** |
||||
|
- **"What simpler solution could achieve the same goal?"** |
||||
|
- **"How does this change affect the existing system architecture?"** |
||||
|
|
||||
|
## Integration with Other Rulesets |
||||
|
|
||||
|
### With base_context.mdc |
||||
|
- Inherits generic competence principles |
||||
|
- Adds software-specific evidence requirements |
||||
|
- Maintains collaboration and learning focus |
||||
|
|
||||
|
### With research_diagnostic.mdc |
||||
|
- Enhances investigation with code path tracing |
||||
|
- Adds evidence validation to diagnostic workflow |
||||
|
- Strengthens problem identification accuracy |
||||
|
|
||||
|
## Usage Guidelines |
||||
|
|
||||
|
### When to Use This Ruleset |
||||
|
- Code reviews and architectural decisions |
||||
|
- Bug investigation and debugging |
||||
|
- Performance optimization |
||||
|
- Feature implementation planning |
||||
|
- Testing strategy development |
||||
|
|
||||
|
### When to Combine with Others |
||||
|
- **base_context + software_development**: General development tasks |
||||
|
- **research_diagnostic + software_development**: Technical investigations |
||||
|
- **All three**: Complex architectural decisions or major refactoring |
||||
|
|
||||
|
## Self-Check (model, before responding) |
||||
|
- [ ] Code path traced and documented |
||||
|
- [ ] Evidence cited with specific file:line references |
||||
|
- [ ] Assumptions clearly flagged as proven vs. inferred |
||||
|
- [ ] Solution complexity justified by evidence |
||||
|
- [ ] Simpler alternatives considered and documented |
||||
|
- [ ] Impact on existing systems assessed |
||||
@ -0,0 +1,103 @@ |
|||||
|
#!/bin/bash |
||||
|
|
||||
|
# Type Safety Pre-commit Check Script |
||||
|
# This script ensures type safety before commits by running linting and type checking |
||||
|
|
||||
|
set -e |
||||
|
|
||||
|
echo "🔍 Running Type Safety Pre-commit Checks..." |
||||
|
|
||||
|
# Colors for output |
||||
|
RED='\033[0;31m' |
||||
|
GREEN='\033[0;32m' |
||||
|
YELLOW='\033[1;33m' |
||||
|
NC='\033[0m' # No Color |
||||
|
|
||||
|
# Function to print colored output |
||||
|
print_status() { |
||||
|
echo -e "${GREEN}✅ $1${NC}" |
||||
|
} |
||||
|
|
||||
|
print_warning() { |
||||
|
echo -e "${YELLOW}⚠️ $1${NC}" |
||||
|
} |
||||
|
|
||||
|
print_error() { |
||||
|
echo -e "${RED}❌ $1${NC}" |
||||
|
} |
||||
|
|
||||
|
# Check if we're in the right directory |
||||
|
if [ ! -f "package.json" ]; then |
||||
|
print_error "Must run from project root directory" |
||||
|
exit 1 |
||||
|
fi |
||||
|
|
||||
|
# Step 1: Run ESLint with TypeScript rules |
||||
|
print_status "Running ESLint TypeScript checks..." |
||||
|
if npm run lint > /dev/null 2>&1; then |
||||
|
print_status "ESLint passed - no type safety issues found" |
||||
|
else |
||||
|
print_error "ESLint failed - type safety issues detected" |
||||
|
echo "" |
||||
|
echo "Running lint with details..." |
||||
|
npm run lint |
||||
|
echo "" |
||||
|
print_error "Please fix the above type safety issues before committing" |
||||
|
exit 1 |
||||
|
fi |
||||
|
|
||||
|
# Step 2: Run TypeScript type checking |
||||
|
print_status "Running TypeScript type checking..." |
||||
|
if npm run type-check > /dev/null 2>&1; then |
||||
|
print_status "TypeScript compilation passed" |
||||
|
else |
||||
|
print_error "TypeScript compilation failed" |
||||
|
echo "" |
||||
|
echo "Running type check with details..." |
||||
|
npm run type-check |
||||
|
echo "" |
||||
|
print_error "Please fix the above TypeScript errors before committing" |
||||
|
exit 1 |
||||
|
fi |
||||
|
|
||||
|
# Step 3: Check for any remaining 'any' types |
||||
|
print_status "Scanning for any remaining 'any' types..." |
||||
|
ANY_COUNT=$(grep -r "any" src/ --include="*.ts" --include="*.vue" | grep -v "// eslint-disable" | grep -v "eslint-disable-next-line" | wc -l) |
||||
|
|
||||
|
if [ "$ANY_COUNT" -eq 0 ]; then |
||||
|
print_status "No 'any' types found in source code" |
||||
|
else |
||||
|
print_warning "Found $ANY_COUNT instances of 'any' type usage" |
||||
|
echo "" |
||||
|
echo "Instances found:" |
||||
|
grep -r "any" src/ --include="*.ts" --include="*.vue" | grep -v "// eslint-disable" | grep -v "eslint-disable-next-line" || true |
||||
|
echo "" |
||||
|
print_error "Please replace 'any' types with proper TypeScript types before committing" |
||||
|
exit 1 |
||||
|
fi |
||||
|
|
||||
|
# Step 4: Verify database migration status |
||||
|
print_status "Checking database migration status..." |
||||
|
if grep -r "databaseUtil" src/ --include="*.ts" --include="*.vue" > /dev/null 2>&1; then |
||||
|
print_warning "Found databaseUtil imports - ensure migration is complete" |
||||
|
echo "" |
||||
|
echo "Files with databaseUtil imports:" |
||||
|
grep -r "databaseUtil" src/ --include="*.ts" --include="*.vue" | head -5 || true |
||||
|
echo "" |
||||
|
print_warning "Consider completing database migration to PlatformServiceMixin" |
||||
|
else |
||||
|
print_status "No databaseUtil imports found - migration appears complete" |
||||
|
fi |
||||
|
|
||||
|
# All checks passed |
||||
|
echo "" |
||||
|
print_status "All type safety checks passed! 🎉" |
||||
|
print_status "Your code is ready for commit" |
||||
|
echo "" |
||||
|
echo "📚 Remember to follow the Type Safety Guidelines:" |
||||
|
echo " - docs/typescript-type-safety-guidelines.md" |
||||
|
echo " - Use proper error handling patterns" |
||||
|
echo " - Leverage existing type definitions" |
||||
|
echo " - Run 'npm run lint-fix' for automatic fixes" |
||||
|
|
||||
|
exit 0 |
||||
@ -0,0 +1,99 @@ |
|||||
|
import { PlatformServiceFactory } from "./PlatformServiceFactory"; |
||||
|
import { PlatformService } from "./PlatformService"; |
||||
|
import { logger } from "@/utils/logger"; |
||||
|
|
||||
|
/** |
||||
|
* QR Navigation Service |
||||
|
* |
||||
|
* Handles platform-specific routing logic for QR scanning operations. |
||||
|
* Removes coupling between views and routing logic by centralizing |
||||
|
* navigation decisions based on platform capabilities. |
||||
|
* |
||||
|
* @author Matthew Raymer |
||||
|
*/ |
||||
|
export class QRNavigationService { |
||||
|
private static instance: QRNavigationService | null = null; |
||||
|
private platformService: PlatformService; |
||||
|
|
||||
|
private constructor() { |
||||
|
this.platformService = PlatformServiceFactory.getInstance(); |
||||
|
} |
||||
|
|
||||
|
/** |
||||
|
* Get singleton instance of QRNavigationService |
||||
|
*/ |
||||
|
public static getInstance(): QRNavigationService { |
||||
|
if (!QRNavigationService.instance) { |
||||
|
QRNavigationService.instance = new QRNavigationService(); |
||||
|
} |
||||
|
return QRNavigationService.instance; |
||||
|
} |
||||
|
|
||||
|
/** |
||||
|
* Get the appropriate QR scanner route based on platform |
||||
|
* |
||||
|
* @returns Object with route name and parameters for QR scanning |
||||
|
*/ |
||||
|
public getQRScannerRoute(): { |
||||
|
name: string; |
||||
|
params?: Record<string, string | number>; |
||||
|
} { |
||||
|
const isCapacitor = this.platformService.isCapacitor(); |
||||
|
|
||||
|
logger.debug("QR Navigation - Platform detection:", { |
||||
|
isCapacitor, |
||||
|
platform: this.platformService.getCapabilities(), |
||||
|
}); |
||||
|
|
||||
|
if (isCapacitor) { |
||||
|
// Use native scanner on mobile platforms
|
||||
|
return { name: "contact-qr-scan-full" }; |
||||
|
} else { |
||||
|
// Use web scanner on other platforms
|
||||
|
return { name: "contact-qr" }; |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
/** |
||||
|
* Get the appropriate QR display route based on platform |
||||
|
* |
||||
|
* @returns Object with route name and parameters for QR display |
||||
|
*/ |
||||
|
public getQRDisplayRoute(): { |
||||
|
name: string; |
||||
|
params?: Record<string, string | number>; |
||||
|
} { |
||||
|
const isCapacitor = this.platformService.isCapacitor(); |
||||
|
|
||||
|
logger.debug("QR Navigation - Display route detection:", { |
||||
|
isCapacitor, |
||||
|
platform: this.platformService.getCapabilities(), |
||||
|
}); |
||||
|
|
||||
|
if (isCapacitor) { |
||||
|
// Use dedicated display view on mobile
|
||||
|
return { name: "contact-qr-scan-show" }; |
||||
|
} else { |
||||
|
// Use combined view on web
|
||||
|
return { name: "contact-qr" }; |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
/** |
||||
|
* Check if native QR scanning is available on current platform |
||||
|
* |
||||
|
* @returns true if native scanning is available, false otherwise |
||||
|
*/ |
||||
|
public isNativeScanningAvailable(): boolean { |
||||
|
return this.platformService.isCapacitor(); |
||||
|
} |
||||
|
|
||||
|
/** |
||||
|
* Get platform capabilities for QR operations |
||||
|
* |
||||
|
* @returns Platform capabilities object |
||||
|
*/ |
||||
|
public getPlatformCapabilities() { |
||||
|
return this.platformService.getCapabilities(); |
||||
|
} |
||||
|
} |
||||
Loading…
Reference in new issue