Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions .github/instructions/javascript.instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
---
description: JavaScript development standards for the Petry Projects organization
applyTo: "**/*.js, **/*.mjs, **/*.cjs"
---

# JavaScript Development Standards

These rules extend the org-level `copilot-instructions.md` and apply to JavaScript files.

> **Prefer TypeScript.** If a file can be migrated to TypeScript without significant disruption,
> prefer the migration. JavaScript is accepted for configuration files (`eslint.config.js`,
> `vite.config.mjs`, `jest.config.js`), build scripts, and legacy code during migration.

## Style and Formatting

- **Formatter:** Prettier. Run `prettier --write` before committing.
- **Linter:** ESLint. Zero warnings, zero errors.
- Never use `var`. Use `const` for all bindings that are not reassigned; use `let` only when
reassignment is required.
- Prefer `async`/`await` over raw `.then()`/`.catch()` chains. Handle rejections — never leave
a floating promise.
- Use ES modules (`import`/`export`) in all new code. CommonJS (`require`/`module.exports`) is
acceptable only in config files that require it.
- Use destructuring assignment to extract values from objects and arrays.

## Naming Conventions

- `camelCase` for variables and functions. `PascalCase` for constructors and classes.
`SCREAMING_SNAKE_CASE` for module-level constants.
- File names match the primary export or purpose (`orderService.js`, `eslint.config.mjs`).

## Type Safety Without TypeScript

- Use JSDoc annotations (`@param`, `@returns`, `@type`) in JavaScript files that cannot yet be
migrated, to enable IDE type inference and `checkJs` validation.
- Enable `// @ts-check` at the top of critical JavaScript files to surface type errors in the
IDE without requiring full TypeScript migration.

## Error Handling

- Always handle Promise rejections — either with `try`/`catch` in `async` functions or with an
explicit `.catch()` handler.
- Never use empty catch blocks (`catch (e) {}`). At minimum, log the error with structured
fields.
- Do not use `console.log` in application or library code. Use the project's established
structured logger or audit pipeline — check the project's `AGENTS.md` for the logger in use.
`console.*` is acceptable only in CLI scripts and build tooling.

## Testing

- Follow the same TDD rules as TypeScript: write tests before implementing, never `.skip()`.
- Use Vitest as the test runner.
- Name tests as functional requirement specifications.
129 changes: 129 additions & 0 deletions .github/instructions/typescript.instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
---
description: TypeScript and TSX development standards for the Petry Projects organization
applyTo: "**/*.ts, **/*.tsx"
---

# TypeScript Development Standards

These rules extend the org-level `copilot-instructions.md`. TypeScript is the primary language
across all Petry Projects repositories.

## Compiler Configuration

Always use TypeScript in strict mode. All repositories MUST include these flags (or stricter):

```json
{
"compilerOptions": {
"strict": true,
"noUncheckedIndexedAccess": true,
"exactOptionalPropertyTypes": true,
"noImplicitOverride": true
}
}
```

Never use `// @ts-ignore` or `// @ts-expect-error` to silence type errors without a documented
reason. Fix the underlying type issue instead.

## Code Style

- **Formatter:** Prettier with `singleQuote: true`, `semi: true`, `trailingComma: 'all'`,
`printWidth: 100`, `tabWidth: 2`. Run `prettier --write` before committing.
- **Linter:** ESLint flat config (`eslint.config.mjs`). Zero warnings, zero errors.
- **Imports:** Use `import type { ... }` for type-only imports. Organize imports: external
packages first, then internal modules. No circular imports.
- **No barrel files.** Avoid `index.ts` re-export files unless the project explicitly requires
them — they increase circular dependency risk and slow down bundlers.
- **Naming:** `PascalCase` for types, interfaces, classes, and React components. `camelCase` for
variables, functions, and methods. `SCREAMING_SNAKE_CASE` for module-level constants.
File names use **kebab-case** for general TypeScript modules (`user-repository.ts`) and
**PascalCase** for React component files (`OrderSummary.tsx`).

## Type Safety

- Prefer `unknown` over `any`. When `any` is unavoidable, add a comment explaining why.
- Use branded types / nominal typing for domain identifiers and value objects:

```typescript
type UserId = string & { readonly __brand: 'UserId' };
type OrderId = string & { readonly __brand: 'OrderId' };
```

- Use discriminated unions instead of optional fields where possible.
- Avoid type assertions (`as SomeType`) at system boundaries — validate with a type guard or
schema parser (e.g., Zod) instead.
- Use `readonly` for arrays and object properties that should not be mutated.

## Domain-Driven Design Patterns

- **Ubiquitous language:** Use domain terminology from the bounded context in type names,
variable names, and method names. Never rename domain concepts to generic terms.
- **Bounded contexts:** Each context lives in its own directory (e.g., `src/orders/`,
`src/billing/`). Cross-context dependencies use well-defined interfaces or domain events —
never direct internal imports across context boundaries.
- **Aggregate roots:** External code accesses child entities only through the aggregate root.
Return domain objects from repositories, not raw database rows.
- **Value objects:** Model domain quantities, identifiers, and domain-specific strings as value
objects. Validate on construction; throw on invalid input.
- **Repository pattern:** Persistence is abstracted behind repository interfaces the domain
defines. Infrastructure implements them. Domain code never imports database drivers, ORMs, or
storage libraries.

## CQRS Naming Conventions

| Concept | Convention | Examples |
|---------|-----------|----------|
| Command | Imperative verb + noun | `PlaceOrder`, `CancelSubscription` |
| Event | Past-tense verb + noun | `OrderPlaced`, `SubscriptionCancelled` |
| Query | `Get` / `List` / `Search` + noun | `GetOrderById`, `ListActiveUsers` |
| Command handler | `Handle(cmd)` or `<Name>Handler` | `PlaceOrderHandler` |
| Projection | Noun describing the view | `OrderSummaryProjection` |

Commands MUST NOT return domain data — return the new entity ID or void. Queries MUST NOT
mutate state.

## Structured Logging

Never use `console.log`, `console.error`, or `console.warn` in application code (`console.*`
is acceptable only in CLI tools and build scripts). Use the project's established structured
logger or audit pipeline — check the project's `AGENTS.md` for the specific logger in use.

Never log variables whose names end in `password`, `secret`, `token`, `api_key`, `cookie`, or
`authorization`.

## React Guidelines

- Use functional components with hooks exclusively. No class components.
- Extract business logic into custom hooks or service functions — keep components presentational.
- Use stable `data-testid` attributes for E2E test selectors; never match on CSS classes, DOM
hierarchy, or display text.
- Props interfaces use `PascalCase`: `interface ButtonProps { ... }`. Co-locate with the
component file.
- Do not import React explicitly (JSX transform handles it). Use `React.FC` only if required by
the project — prefer plain function declarations.

## Error Handling

- Use typed `Result` patterns or typed error unions rather than throwing for recoverable errors
at domain boundaries.
- Always handle the error case explicitly — never use `.catch(() => {})` silently.
- Fail fast with a clear, descriptive error when an invariant is violated.

## Testing (Vitest)

- Name tests as functional requirement specifications:
`it("submitting a valid order creates a confirmed record with correct totals")`.
- Use `describe` blocks to group by feature or class under test.
- Mock only external I/O (databases, HTTP, file system). Never mock domain logic.
- Co-locate unit tests next to source files (`user-repository.test.ts` beside
`user-repository.ts`).
- Mutation testing (Stryker) runs in CI for repos that configure it — write meaningful
assertions, not trivial coverage padding.

## Electron-Specific (TalkTerm and desktop repos)

- Keep main-process and renderer-process code strictly separated. Never import renderer modules
in the main process or vice versa.
- Use `contextBridge` for all IPC; never expose `ipcRenderer` directly to renderer code.
- Validate all data crossing the IPC bridge as if it were external user input.
32 changes: 26 additions & 6 deletions .gitleaksignore
Original file line number Diff line number Diff line change
Expand Up @@ -36,22 +36,42 @@ e8cc0956c901e454aed61e7b10857e6a1a412881:_bmad/_config/files-manifest.csv:generi
e8cc0956c901e454aed61e7b10857e6a1a412881:_bmad/_config/files-manifest.csv:generic-api-key:409
e8cc0956c901e454aed61e7b10857e6a1a412881:_bmad/_config/files-manifest.csv:generic-api-key:433

# Commit aec934f: _bmad/_config/files-manifest.csv (lines 281, 282, 284, 300,
# 409, 433) — same false positives as e8cc0956, same justification: SHA256
# content checksums in a CSV manifest, not API keys.
# Commit aec934f9: same _bmad/_config/files-manifest.csv CSV rows as above
# (SHA256 content checksums of BMAD skill files) appearing in a later commit
# that re-introduced the same content. Same false-positive rationale applies.
aec934f92f4174b89944ee57a3d5cf68737f71c9:_bmad/_config/files-manifest.csv:generic-api-key:281
aec934f92f4174b89944ee57a3d5cf68737f71c9:_bmad/_config/files-manifest.csv:generic-api-key:282
aec934f92f4174b89944ee57a3d5cf68737f71c9:_bmad/_config/files-manifest.csv:generic-api-key:284
aec934f92f4174b89944ee57a3d5cf68737f71c9:_bmad/_config/files-manifest.csv:generic-api-key:300
aec934f92f4174b89944ee57a3d5cf68737f71c9:_bmad/_config/files-manifest.csv:generic-api-key:409
aec934f92f4174b89944ee57a3d5cf68737f71c9:_bmad/_config/files-manifest.csv:generic-api-key:433

# Commit 45b6a8ef: _bmad/_config/files-manifest.csv (lines 281, 282, 284, 300,
# 409, 433) — same false positives as e8cc0956 and aec934f, same justification:
# SHA256 content checksums in a CSV manifest, not API keys.
# Commit 45b6a8ef: same _bmad/_config/files-manifest.csv CSV rows as above
# (SHA256 content checksums of BMAD skill files) appearing in another commit.
# The CSV contains rows like "<file-path>","<sha256-hash>" where the hash
# column is a content-addressable fingerprint (not an API key). Gitleaks'
# generic-api-key rule flags high-entropy hex strings; these are file checksums.
45b6a8ef162096dae42b2a8194334f24a6576f69:_bmad/_config/files-manifest.csv:generic-api-key:281
45b6a8ef162096dae42b2a8194334f24a6576f69:_bmad/_config/files-manifest.csv:generic-api-key:282
45b6a8ef162096dae42b2a8194334f24a6576f69:_bmad/_config/files-manifest.csv:generic-api-key:284
45b6a8ef162096dae42b2a8194334f24a6576f69:_bmad/_config/files-manifest.csv:generic-api-key:300
45b6a8ef162096dae42b2a8194334f24a6576f69:_bmad/_config/files-manifest.csv:generic-api-key:409
45b6a8ef162096dae42b2a8194334f24a6576f69:_bmad/_config/files-manifest.csv:generic-api-key:433

# Commit 58a86a1: same _bmad/_config/files-manifest.csv CSV rows as above
# (SHA256 content checksums of BMAD skill files). Same false-positive rationale.
58a86a1cd7a8f64efbe0139ecb88184ddf10710a:_bmad/_config/files-manifest.csv:generic-api-key:281
58a86a1cd7a8f64efbe0139ecb88184ddf10710a:_bmad/_config/files-manifest.csv:generic-api-key:282
58a86a1cd7a8f64efbe0139ecb88184ddf10710a:_bmad/_config/files-manifest.csv:generic-api-key:284
58a86a1cd7a8f64efbe0139ecb88184ddf10710a:_bmad/_config/files-manifest.csv:generic-api-key:300
58a86a1cd7a8f64efbe0139ecb88184ddf10710a:_bmad/_config/files-manifest.csv:generic-api-key:409
58a86a1cd7a8f64efbe0139ecb88184ddf10710a:_bmad/_config/files-manifest.csv:generic-api-key:433

# Commit 146f8e14: same _bmad/_config/files-manifest.csv CSV rows as above
# (SHA256 content checksums of BMAD skill files). Same false-positive rationale.
146f8e140e166da953907450a3e10985772933ea:_bmad/_config/files-manifest.csv:generic-api-key:281
146f8e140e166da953907450a3e10985772933ea:_bmad/_config/files-manifest.csv:generic-api-key:282
146f8e140e166da953907450a3e10985772933ea:_bmad/_config/files-manifest.csv:generic-api-key:284
146f8e140e166da953907450a3e10985772933ea:_bmad/_config/files-manifest.csv:generic-api-key:300
146f8e140e166da953907450a3e10985772933ea:_bmad/_config/files-manifest.csv:generic-api-key:409
146f8e140e166da953907450a3e10985772933ea:_bmad/_config/files-manifest.csv:generic-api-key:433
Loading