initial

2026-09-23 12:29:08 -03:00
commit f5d231ab8f
59 changed files with 16658 additions and 0 deletions
@@ -0,0 +1,77 @@
+---
+name: vitruvio-criar-query
+description: >
+  Use when the user wants to create a new named SQL query in a Vitruvio repository.
+  Triggers: "create query", "new query", "criar query", "nova query", "add query", "named query",
+  or any request to scaffold a queries/*.sql file and register it in vitruvio.json.
+---
+
+# Create Vitruvio Query
+
+> All messages shown to the user must be written in Portuguese.
+
+You are creating a new named SQL query inside a Vitruvio repository. Follow these steps in order.
+
+## Step 1 — Confirm you are inside a Vitruvio repo
+
+```bash
+ls vitruvio.json 2>/dev/null && echo "OK" || echo "NOT_A_VITRUVIO_REPO"
+```
+
+If `NOT_A_VITRUVIO_REPO`, stop and tell the user to `cd` into the correct repo.
+
+## Step 2 — Collect query details
+
+Ask the user (in a single message, only ask what is missing from their original request):
+
+- **Key** — kebab-case unique identifier. Used to reference this query in reports, DBTable components, and scripts.
+- **Name** — human-readable label shown in the Vitruvio UI.
+- **SQL** — the query itself, or enough context to write it.
+- **Connection** — datasource name (default: `vitruvio_producao`). Ask only if the user mentions a specific datasource.
+
+## Step 3 — Scaffold and create file
+
+```bash
+vitruvio new query <key> --name "<name>"
+```
+
+This creates `queries/<key>.sql` and registers it in `vitruvio.json` with `connection: "vitruvio_producao"`. Replace the generated SQL with the actual query. If a different datasource is needed, update `"connection"` in `vitruvio.json`.
+
+Target path: `queries/<key>.sql`
+
+Rules:
+- One `SELECT` per file. No multiple statements, no DDL, no INSERT/UPDATE/DELETE.
+- Named bind parameters use `:paramName` syntax — never concatenate user input into SQL.
+- Write ANSI SQL where possible. If DB-specific syntax is unavoidable, note it in a comment.
+- Keep Oracle and PostgreSQL compatibility in mind — avoid syntax that only works in one.
+
+```sql
+SELECT col1,
+       col2
+  FROM my_table
+ WHERE active = 1
+   AND id = :id
+ ORDER BY col1
+```
+
+## Step 4 — Update vitruvio.json entry
+
+`vitruvio new` already added the query entry. The full entry shape is:
+
+```json
+{
+  "key": "<key>",
+  "name": "<name>",
+  "source": "queries/<key>.sql",
+  "connection": "vitruvio_producao"
+}
+```
+
+Update `"connection"` only if the user specified a datasource other than `"vitruvio_producao"`.
+
+## Step 5 — Report
+
+Tell the user:
+- File created: `queries/<key>.sql`
+- Registered in `vitruvio.json` with key `<key>`
+- How it can be used: as a datasource in a report, in a DBTable component, or loaded in a script via `db.executeNamedQuery('<key>', params)`