@smbcloud / cli
Code Commits Issues Pulls Cloud Agent CI/CD
main
claude/smbcloud-github-app-k9641p development feature/apps feature/build-release feature/ci-docs feature/ci-ruby-gems feature/cicd feature/completion feature/dist-nuget feature/fix-ci-sdk-pypi-rubygem feature/fix-clippy-on-stable-channel feature/fix-deployment-script feature/github-email feature/gresiq-v1 feature/project-new-structure feature/rsync-deploy feature/ruby-runner feature/sdk-npm feature/sdk-workflows feature/smbcloud-cli-release-npm feature/smbcloud-deploy feature/wasm main release/v0.7.4
md 148 lines 4.61 KB
Rendered Raw
1 ---
2 name: smbcloud-gresiq
3 description: Use when building, debugging, or extending GresIQ, smbCloud's managed PostgreSQL service, especially the Rust crate in `crates/smbcloud-gresiq`, managed connection bootstrap, branch-aware database config, TLS-aware `tokio-postgres` setup, environment-variable loading, and future Neon or Prisma-style service capabilities such as preview branches, pooled connections, and ephemeral credentials.
4 ---
5
6 # smbCloud GresIQ
7
8 Use this skill when the task is about GresIQ, smbCloud's managed PostgreSQL service.
9
10 Applies to:
11
12 - `crates/smbcloud-gresiq/Cargo.toml`
13 - `crates/smbcloud-gresiq/src/gresiq.rs`
14 - `crates/smbcloud-gresiq/src/main.rs`
15 - `crates/smbcloud-gresiq/README.md`
16 - workspace wiring for new GresIQ dependencies
17 - managed Postgres bootstrap design, connection policy, and product-shape changes
18
19 ## Scope boundary
20
21 This skill is for the managed Postgres service layer and its Rust bootstrap crate.
22
23 Do not use it for:
24
25 - smbCloud auth flows unless the database service change directly affects auth integration
26 - generic deploy logic
27 - unrelated CLI packaging or release automation
28
29 Use the relevant smbCloud auth, deploy, or release skills when those are the actual center of gravity.
30
31 ## Source of truth
32
33 Start from these files:
34
35 - `crates/smbcloud-gresiq/src/gresiq.rs`
36 - `crates/smbcloud-gresiq/src/main.rs`
37 - `crates/smbcloud-gresiq/Cargo.toml`
38 - `crates/smbcloud-gresiq/README.md`
39 - workspace `Cargo.toml` when dependency or member wiring changes
40
41 Treat the Rust crate as the source of truth. Keep future CLI, wasm, Tauri, npm, or native wrappers thin.
42
43 ## Current service model
44
45 The current GresIQ bootstrap models:
46
47 - smbCloud environments: `development`, `preview`, `production`
48 - branch-aware database targets
49 - endpoint host, port, and SSL mode
50 - credentials and database name
51 - connection policy such as compute tier, application name, and connect timeout
52 - redacted connection-string output
53 - a connectivity health check using `tokio-postgres`
54
55 Preserve these properties unless the task explicitly changes the product model.
56
57 ## Product direction
58
59 Take inspiration from Neon, Prisma Postgres, and similar managed database products, but fit the smbCloud platform rather than copying their APIs blindly.
60
61 Good directions:
62
63 - preview branches per app environment
64 - autoscaling or burst compute defaults
65 - pooled or proxy-backed connection paths for serverless runtimes
66 - safe credential handling and redacted logs
67 - ephemeral or tenant-scoped credentials
68 - operational checks that surface actionable failures
69
70 Avoid adding speculative product features with no clear interface or storage model.
71
72 ## Implementation guidance
73
74 ### Crate shape
75
76 Prefer a library-first design:
77
78 - reusable Rust API in `src/gresiq.rs`
79 - thin binary in `src/main.rs`
80
81 If additional surfaces are added later, bind to the existing Rust API rather than duplicating logic.
82
83 ### Configuration
84
85 Make environment loading explicit and typed.
86
87 Expected config areas:
88
89 - smbCloud environment
90 - project slug
91 - branch name
92 - region
93 - host and port
94 - SSL mode
95 - username, password, and database name
96 - compute or connection policy
97
98 Do not hardcode localhost defaults except in intentionally local examples.
99
100 ### Connections
101
102 Prefer correctness over cleverness.
103
104 - use TLS when the endpoint requires it
105 - keep connection-string generation available for integration points
106 - provide a redacted form for logs and CLI output
107 - propagate errors instead of hiding them behind generic failures
108
109 If adding pooling, document whether the crate owns pooling or whether it only models direct connections.
110
111 ### Errors
112
113 Use typed error enums for:
114
115 - invalid configuration
116 - invalid environment variable values
117 - TLS setup failures
118 - PostgreSQL connection or query failures
119
120 Do not use `unwrap()` in the service path.
121
122 ## Validation
123
124 Use the smallest relevant checks first.
125
126 ### Rust
127
128 - `cargo fmt --package gresiq`
129 - `cargo check -p gresiq`
130 - `cargo test -p gresiq`
131
132 ### Runtime
133
134 If the task changes live connection behavior, validate with a real managed endpoint when credentials are available:
135
136 - set `GRESIQ_*` environment variables
137 - run `cargo run -p gresiq`
138
139 Do not claim runtime validation happened unless a real endpoint was exercised.
140
141 ## Common mistakes
142
143 - treating GresIQ like a one-off example binary instead of a reusable service crate
144 - logging raw passwords or full unredacted connection strings
145 - hardcoding insecure defaults for production-facing paths
146 - mixing up smbCloud environment semantics with database branch semantics
147 - adding platform wrappers that duplicate the Rust logic
148 - introducing pooling, proxy, or branch-management claims in the README without implementing the underlying API