@vaharoni/devops 1.2.12 → 1.2.13

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vaharoni/devops",
   "type": "module",
-  "version": "1.2.12",
+  "version": "1.2.13",
   "description": "Devops utility",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/target-templates/lang-variants-common/python/.cursor/rules/monorepo-python.mdc

@@ -0,0 +1,56 @@
+---
+alwaysApply: true
+---
+
+# Python Monorepo
+
+This project includes a Python workspace alongside the TypeScript workspace.
+
+- **`./devops`** is for TypeScript/Node packages (package.json tree)
+- **`./devopspy`** is for Python packages (pyproject.toml tree)
+
+The Python workspace is configured through a root `pyproject.toml` using uv workspaces.
+
+## Structure
+
+Packages under `applications` depend on packages under `libs` using workspace dependencies. It makes sense to extract code to packages under `libs` when it is used in more than one application. Applications never rely on other applications.
+
+All web services found under `applications` should respond to a `GET healthz` with status 200.
+
+## Using the devopspy CLI (Python only)
+
+We use `uv` as our package manager. The `./devopspy` script is able to run scripts defined in pyproject.toml inside a workspace, run a shell process inside a workspace, and execute the tests in a project:
+
+```bash
+# Most important commands
+./devopspy run <project-name>:<script-name>
+./devopspy exec --in <project-name> <command>
+./devopspy test
+./devopspy test <project-name>
+
+# Examples
+./devopspy run my-api:dev
+./devopspy exec --in my-api uv add some-package
+./devopspy test my-service
+
+# To sync dependencies on all workspaces in the monorepo, use uv normally
+uv sync
+```
+
+Scripts are defined in pyproject.toml under `[tool.devops.scripts]`:
+
+```toml
+[tool.devops.scripts]
+dev = "python -c 'from src.my_package.scripts import dev; dev()'"
+start = "python -c 'from src.my_package.scripts import start; start()'"
+```
+
+`./devopspy` automatically loads the right env variables, so don't use python-dotenv.
+
+There is no need to `cd` into package directories. Prefer to use `./devopspy run` and `./devopspy exec`.
+
+## Testing
+
+Use pytest.
+
+**Always run tests with `./devopspy test`** to ensure the test environment is used.

package/src/target-templates/lang-variants-common/typescript/.cursor/rules/monorepo-typescript.mdc

@@ -0,0 +1,51 @@
+---
+alwaysApply: true
+---
+
+# Monorepo Structure
+
+We have a monorepo setup configured through a global package.json. There is a `./devops` script to execute commands inside typescript packages.
+
+## Structure
+
+Packages under `applications` depend on packages under `libs` using `workspace:*` notation from package.json. It makes sense to extract code to packages under `libs` when it is used in more than one application. Applications never rely on other applications.
+
+Applications are encouraged to extract private concerns to "local libs" modules. A typical use-case are persistence-related operations (getters and mutations).
+
+All web services found under `applications` should respond to a `GET healthz` with status 200.
+
+## Using the devops CLI
+
+We use `bun` as our package manager. The `./devops` script is able to run package.json scripts inside a workspace, run a shell process inside a workspace, and execute the tests in a project:
+
+```bash
+# Most important commands
+./devops run <project-name>:<script-name>
+./devops exec --in <project-name> <command>
+./devops test
+./devops test <project-name>
+
+# Examples
+./devops run my-api:dev
+./devops exec --in my-api bun add some-package
+./devops test my-service
+
+# To install dependencies on all workspaces in the monorepo, use bun normally
+bun install
+```
+
+`./devops` automatically loads the right env variables, so don't use dotenv.
+
+There is no need to `cd` into package directories. Prefer to use `./devops run` and `./devops exec`.
+
+## Testing
+
+Use vitest.
+
+**Always run tests with `./devops test`** to ensure the test environment is used.
+
+## Inter-service Communication
+
+This repo runs in kubernetes and localhost contexts, which means the endpoint URLs will be different depending on the context. To communicate between services, the package `@vaharoni/devops` exports `function getServiceEndpoint(serviceName: string): string`. This function does not return a trailing slash. The `serviceName` can be found in the `deployment.service_name` custom key of the `package.json` of the application you wish to send requests to. If this key does not exist, halt and alert the user.
+
+However, in general, importing a shared lib is preferred over crossing the wire.

package/src/target-templates/lang-variants-prisma/python/.cursor/rules/prisma-python.mdc

@@ -0,0 +1,55 @@
+---
+globs: *.prisma,*.sql
+alwaysApply: false
+---
+
+# Prisma (Python)
+
+Assume all existing prisma migrations are applied, hence never change existing migrations.
+
+NEVER reset the development database without permission.
+
+As you know, Prisma is not good at renaming, so after creating migrations automatically from schema changes always go over the migrations and make sure it captured the user intent.
+
+## Commands
+
+All prisma commands should be executed via the devopspy CLI:
+
+```bash
+./devopspy prisma <some command>
+./devopspy prisma migrate dev
+```
+
+To generate the Prisma client after schema changes:
+
+```bash
+./devopspy run db:generate
+```
+
+## DB Package
+
+The prisma schema resides in `db/prisma/schema.prisma`. To use the Prisma client from any application, add `db` as a workspace dependency in your `pyproject.toml`:
+
+```toml
+[tool.uv.sources]
+db = { workspace = true }
+```
+
+Then import as usual:
+
+```python
+from db import prisma
+```
+
+## Schema Conventions
+
+When editing Prisma schemas:
+
+- Define new models with singular PascalCase names and map them to plural snake_case table names via `@@map`.
+- All table columns should remain in snake_case using `@map` on each field when needed.
+- Default primary keys should be `String @id @default(cuid())` unless there is an explicit reason to use another strategy.
+- Add `@default(now())` + `@map("created_at")` for creation timestamps and `@default(now()) @updatedAt @map("updated_at")` for update timestamps.
+- Always create an index (`@@index`) for every relational field to keep lookups performant.
+- Prefer Prisma's default column type mapping; use `@db.*` annotations only when you truly need a non-default database type.
+- Prefer lowercase values for enums we fully control (e.g., `pending`, `completed` instead of `PENDING`, `COMPLETED`).
+- Prefer strings rather than enums for data-driven closed-lists unless the user requests otherwise.

package/src/target-templates/lang-variants-prisma/python/.cursor/rules/testing-python.mdc

@@ -0,0 +1,89 @@
+---
+alwaysApply: true
+---
+
+# Testing
+
+## Running Tests
+
+**IMPORTANT**: Always use `./devopspy test` to run tests:
+
+```bash
+# Run all tests
+./devopspy test
+
+# Run tests for a specific package
+./devopspy test <project-name>
+./devopspy test my-service
+```
+
+This command:
+
+- Sets `MONOREPO_ENV=test` to use the test database (separate from development)
+- Loads the correct environment variables from `config/.env.test`
+- Ensures test isolation
+
+**Never run tests directly with `pytest`** - this will use the development database and might pollute it with test data.
+
+## Prisma Transactional Testing
+
+We use a transactional testing pattern where each test runs inside a database transaction that is automatically rolled back after the test completes. This ensures:
+
+- Complete test isolation - tests don't affect each other
+- No cleanup code needed - the rollback handles it
+- Fast tests - no need to truncate tables between tests
+
+### Setting Up Tests for a New Package
+
+1. Create a `tests/conftest.py` in your package that imports the test fixtures:
+
+```python
+from db.db_client_test import *
+```
+
+2. Ensure `db` is in your workspace dependencies in `pyproject.toml`:
+
+```toml
+[project]
+dependencies = ["db"]
+
+[tool.uv.sources]
+db = { workspace = true }
+```
+
+### Writing Tests
+
+Tests receive a `db_connection` fixture that provides a transactional database connection:
+
+```python
+import pytest
+
+@pytest.mark.asyncio
+async def test_creates_record(db_connection):
+    # This record will be rolled back after the test
+    record = await db_connection.mymodel.create(
+        data={"name": "test"}
+    )
+    
+    assert record.id is not None
+
+@pytest.mark.asyncio
+async def test_can_use_same_data(db_connection):
+    # This test gets a clean slate - the previous test's data was rolled back
+    record = await db_connection.mymodel.create(
+        data={"name": "test"}  # same name works!
+    )
+    
+    assert record.id is not None
+```
+
+### How It Works
+
+The `db_connection` fixture in `db/db_client_test.py`:
+
+- Creates a new Prisma client and connects to the database
+- Starts a transaction and yields a `TransactionProxy` to the test
+- Raises `RollbackTransaction` after the test completes to rollback all changes
+- Disconnects from the database
+
+This means each test receives an isolated transaction that is automatically rolled back.

package/src/target-templates/lang-variants-prisma/typescript/.cursor/rules/prisma-typescript.mdc

@@ -0,0 +1,54 @@
+---
+globs: *.prisma,*.sql
+alwaysApply: false
+---
+
+# Prisma
+
+Assume all existing prisma migrations are applied, hence never change existing migrations.
+
+NEVER reset the development database without permission.
+
+As you know, Prisma is not good at renaming, so after creating migrations automatically from schema changes always go over the migrations and make sure it captured the user intent.
+
+## Commands
+
+All prisma commands should be executed via the devops CLI:
+
+```bash
+./devops prisma <some command>
+./devops prisma migrate dev
+```
+
+To generate the Prisma client after schema changes:
+
+```bash
+./devops run db:generate
+```
+
+## DB Package
+
+The prisma schema resides in `db/prisma/schema.prisma`. To connect to prisma from any application, add `"db": "workspace:*"` to the dependency list of the app's `package.json`. Then import as usual:
+
+```typescript
+import { prisma } from "db";
+```
+
+To import Prisma types corresponding to tables, import from the prisma client package:
+
+```typescript
+import { type SomeType } from "@prisma/client";
+```
+
+## Schema Conventions
+
+When editing Prisma schemas:
+
+- Define new models with singular PascalCase names and map them to plural snake_case table names via `@@map`.
+- All table columns should remain in snake_case using `@map` on each field when needed.
+- Default primary keys should be `String @id @default(cuid())` unless there is an explicit reason to use another strategy.
+- Add `@default(now())` + `@map("created_at")` for creation timestamps and `@default(now()) @updatedAt @map("updated_at")` for update timestamps.
+- Always create an index (`@@index`) for every relational field to keep lookups performant.
+- Prefer Prisma's default column type mapping; use `@db.*` annotations only when you truly need a non-default database type.
+- Prefer lowercase values for enums we fully control (e.g., `pending`, `completed` instead of `PENDING`, `COMPLETED`).
+- Prefer strings rather than enums for data-driven closed-lists unless the user requests otherwise.

package/src/target-templates/lang-variants-prisma/typescript/.cursor/rules/testing-typescript.mdc

@@ -0,0 +1,103 @@
+---
+alwaysApply: true
+---
+
+# Testing
+
+## Running Tests
+
+**IMPORTANT**: Always use `./devops test` to run tests:
+
+```bash
+# Run all tests
+./devops test
+
+# Run tests for a specific package
+./devops test <project-name>
+./devops test @local/my-service
+```
+
+This command:
+
+- Sets `MONOREPO_ENV=test` to use the test database (separate from development)
+- Loads the correct environment variables from `config/.env.test`
+- Ensures test isolation
+
+**Never run tests directly with `bun test` or `vitest`** - this will use the development database and might pollute it with test data if the transactional testing (see below) is not properly configured.
+
+## Prisma Transactional Testing
+
+We use a transactional testing pattern where each test runs inside a database transaction that is automatically rolled back after the test completes. This ensures:
+
+- Complete test isolation - tests don't affect each other
+- No cleanup code needed - the rollback handles it
+- Fast tests - no need to truncate tables between tests
+
+### Setting Up Tests for a New Package
+
+1. Add vitest as a dev dependency and a test script to your `package.json`:
+
+```json
+{
+  "devDependencies": {
+    "vitest": "^3.0.9"
+  },
+  "scripts": {
+    "test": "vitest"
+  }
+}
+```
+
+2. Create a `vitest.config.ts` in your package root:
+
+```typescript
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    setupFiles: ["../../db/prisma-setup-vitest.ts"], // adjust path based on package location
+  },
+});
+```
+
+3. Ensure `"db": "workspace:*"` is in your dependencies if you use Prisma.
+
+### Writing Tests
+
+Tests can create database records freely - they will be rolled back automatically:
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { prisma } from "db";
+
+describe("MyFeature", () => {
+  it("creates a record", async () => {
+    // This record will be rolled back after the test
+    const record = await prisma.myModel.create({
+      data: { name: "test" },
+    });
+
+    expect(record.id).toBeDefined();
+  });
+
+  it("can use the same data", async () => {
+    // This test gets a clean slate - the previous test's data was rolled back
+    const record = await prisma.myModel.create({
+      data: { name: "test" }, // same name works!
+    });
+
+    expect(record.id).toBeDefined();
+  });
+});
+```
+
+### How It Works
+
+The setup in `db/prisma-setup-vitest.ts` and `db/db-client-test.ts`:
+
+- Creates a transactional Prisma client with `$begin()` and `$rollback()` methods
+- Stores it in `globalThis.prismaGlobal` (same singleton used by `db/db-client.ts`)
+- Mocks the `"db"` module so all imports get the transactional client
+- Wraps each test in `beforeEach`/`afterEach` hooks that start and rollback transactions
+
+This means all code importing `prisma` from `"db"` - including services being tested - uses the same transactional client.

package/src/target-templates/lang-variants-prisma/typescript/db/db-client-test.ts

@@ -107,9 +107,11 @@ export const prismaClientSingleton = () => {
   return client as unknown as ExtendedTransactionClient | FlatTransactionClient;
 };
 
+// Use the same global singleton key as db-client.ts (prismaGlobal)
+// This ensures all code importing from "db" uses the same transactional client
 declare global {
   // eslint-disable-next-line no-var
-  var prismaTestGlobal:
+  var prismaGlobal:
     | ExtendedTransactionClient
     | FlatTransactionClient
     | undefined;
@@ -125,9 +127,9 @@ export type FlatTransactionClient = Prisma.TransactionClient & {
 };
 
 const prisma: ExtendedTransactionClient | FlatTransactionClient =
-  globalThis.prismaTestGlobal ?? prismaClientSingleton();
+  globalThis.prismaGlobal ?? prismaClientSingleton();
 
-globalThis.prismaTestGlobal = prisma;
+globalThis.prismaGlobal = prisma;
 
 export { prisma };