puls-dev 0.3.5 → 0.3.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +165 -54
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,27 +1,26 @@
1
1
  # Pulsdev.io
2
2
 
3
- **Intent-driven infrastructure-as-code. Describe what you want - Puls figures out create, update, or skip.**
3
+ **Intent-driven infrastructure-as-code. Describe what you want — Puls figures out create, update, or skip.**
4
4
 
5
- [Live Documentation](https://pulsdev.io/) | Matrix|Gitter: **pulsdev.io** ([Join](https://matrix.to/#/#pulsdevio:gitter.im))
5
+ [Live Documentation](https://pulsdev.io/) | [GitHub Actions](docs/github-actions.md) | Matrix|Gitter: **pulsdev.io** ([Join](https://matrix.to/#/#pulsdevio:gitter.im))
6
6
 
7
7
  > [!IMPORTANT]
8
8
  > **Active Pre-1.0 Development**
9
- > `pulsdev.io` is currently undergoing **active development**. While the framework features exhaustive 100% test coverage and strict production safety locks (such as dry-run planning and protected resource decorators), APIs and features are actively evolving.
10
- > We are aggressively rolling out new resources and provider integrations. We welcome your feedback, bug reports, and contributions!
9
+ > `pulsdev.io` is under active development. APIs and features are evolving — we welcome feedback, bug reports, and contributions!
11
10
 
12
11
  ```typescript
13
12
  @Deploy({ proxmox: CONFIG.STAGING })
14
13
  class GameInfra extends Stack {
15
- server = Proxmox.VM("example-vm")
14
+ server = Proxmox.VM("ix-app01")
16
15
  .image(OS.UBUNTU_24_04)
17
16
  .cores(4).memory(8192)
18
- .ip("1.1.1.1").vlan(2010)
17
+ .ip("10.8.10.51").vlan(2010)
19
18
  .sshKey(KEYS)
20
19
  .provision("config/default.yaml");
21
20
  }
22
21
  ```
23
22
 
24
- No state files. No plan step. Runs against real APIs - idempotent by default.
23
+ No state files. No plan step. Runs against real APIs — idempotent by default.
25
24
 
26
25
  ---
27
26
 
@@ -35,20 +34,52 @@ Declare resource → Discovery fires immediately (async)
35
34
  → deploy() awaits discovery, diffs, acts
36
35
  ```
37
36
 
38
- Running the same stack twice is always safe - existing resources are detected and skipped.
37
+ Running the same stack twice is always safe — existing resources are detected and skipped or updated in place.
39
38
 
40
39
  ---
41
40
 
42
- ## Providers
41
+ ## Install
42
+
43
+ ```bash
44
+ npm install puls-dev
45
+ ```
46
+
47
+ **One-time shell setup** — so you never have to type `npx puls` again:
48
+
49
+ ```bash
50
+ npx puls install-shell
51
+ ```
52
+
53
+ This adds a `puls` launcher to `~/.puls/bin` and wires it into your shell config (`~/.zshrc`, `~/.bashrc`, or Fish). Open a new terminal and `puls` works everywhere.
43
54
 
44
- | Provider | Resources | Status |
45
- |----------|-----------|--------|
46
- | [Google Cloud Platform (GCP)](docs/providers/gcp.md) | Cloud Run, Cloud SQL, Secret Manager, Pub/Sub, Cloud DNS, IAM (Service Accounts & Bindings) | **Completed** |
47
- | [AWS](docs/providers/aws.md) | Route53, ACM (wildcard SSL), CloudFront, S3 | **Completed** |
48
- | [Firebase](docs/providers/firebase.md) | Hosting, Functions, Firestore (Indexes & Rules), Storage (Rules/CORS), Auth, Remote Config, App Check | **Completed** |
49
- | [DigitalOcean](docs/providers/digitalocean.md) | Droplet, Domain, Firewall, Certificate, LoadBalancer | **Completed** |
50
- | [Proxmox](docs/providers/proxmox.md) | VM (clone, cloud-init, provision, cluster-aware node selection, replace) | **Completed** |
55
+ ---
56
+
57
+ ## CLI
58
+
59
+ ```bash
60
+ puls plan infra/stack.ts # dry-run — prints what would change, no API writes
61
+ puls deploy infra/stack.ts # apply the stack
62
+ puls destroy infra/stack.ts # tear down the stack
63
+ puls diff infra/stack.ts # compare declared intent vs live cloud state
64
+ puls diff infra/stack.ts --fail-on-drift # exit 1 if anything has drifted
65
+
66
+ puls install-shell # one-time shell setup
67
+ puls uninstall-shell # remove shell integration
68
+ ```
69
+
70
+ Always run `plan` before `deploy` — it activates dry-run mode automatically.
71
+
72
+ ---
73
+
74
+ ## Providers
51
75
 
76
+ | Provider | Resources |
77
+ |----------|-----------|
78
+ | **AWS** | EC2, RDS, Lambda, ECS/Fargate, API Gateway, S3, CloudFront, Route53, ACM, SQS, SNS, IAM, CloudWatch, SecretsManager |
79
+ | **DigitalOcean** | Droplet, Domain (full DNS), Firewall, Certificate, LoadBalancer, Database, App Platform, VPC, Spaces |
80
+ | **GCP** | Compute VM, Cloud Run, Cloud SQL, Secret Manager, Pub/Sub, Cloud DNS, IAM |
81
+ | **Firebase** | Hosting, Functions, Firestore, Storage, Auth, RemoteConfig, App Check |
82
+ | **Proxmox** | VM (clone, cloud-init, provision, cluster-aware scheduling), Templates (golden images) |
52
83
 
53
84
  ---
54
85
 
@@ -57,11 +88,13 @@ Running the same stack twice is always safe - existing resources are detected an
57
88
  ### DigitalOcean
58
89
 
59
90
  ```typescript
91
+ import "dotenv/config";
60
92
  import { Stack, Deploy } from "puls-dev";
61
93
  import { DO, SIZE, REGION } from "puls-dev/do";
62
94
 
63
95
  @Deploy({ token: process.env.DO_TOKEN! })
64
96
  class Production extends Stack {
97
+ db = DO.Database("prod-db").engine("pg").size("db-s-2vcpu-2gb").nodes(2);
65
98
  web = DO.Droplet("prod-web").size(SIZE.MEDIUM).region(REGION.FRA).allowPublicWeb();
66
99
  dns = DO.Domain("example.com").pointer("@", this.web).withSSL();
67
100
  }
@@ -70,47 +103,132 @@ class Production extends Stack {
70
103
  ### AWS
71
104
 
72
105
  ```typescript
106
+ import "dotenv/config";
73
107
  import { Stack, Deploy } from "puls-dev";
74
- import { AWS, DISTRO, BUCKET, DOMAIN_REGISTER, REGION } from "puls-dev/aws";
108
+ import { AWS, REGION, RUNTIME, DB } from "puls-dev/aws";
75
109
 
76
- @Deploy({ region: REGION.US_EAST_1 })
77
- class CDNStack extends Stack {
78
- domain = AWS.Route53().randomDomain().register(DOMAIN_REGISTER).withWildcardSSL();
110
+ @Deploy({ region: REGION.EU_CENTRAL_1 })
111
+ class AppStack extends Stack {
112
+ db = AWS.RDS("app-db").engine(DB.POSTGRES_16).size("db.t3.micro");
113
+ api = AWS.Lambda("app-api").code("./functions/api").runtime(RUNTIME.NODEJS_20);
114
+ cdn = AWS.S3("app-assets").staticSite().allowFrom(this.api);
115
+ }
116
+ ```
117
+
118
+ ### GCP
79
119
 
80
- cdn = AWS.CloudFront(`CDN-${this.domain.zoneName.slice(0, 8)}`)
81
- .copyFrom(DISTRO.CDN)
82
- .forDomain(this.domain, ["ec", "nc"]);
120
+ ```typescript
121
+ import "dotenv/config";
122
+ import { Stack, Deploy } from "puls-dev";
123
+ import { GCP } from "puls-dev/gcp";
83
124
 
84
- bucket = AWS.S3(BUCKET.NLC_GAMES_UREG)
85
- .allowFrom(this.cdn)
86
- .region(REGION.EU_WEST_1);
125
+ @Deploy({})
126
+ class CloudStack extends Stack {
127
+ secret = GCP.Secret("db-password").value(process.env.DB_PASS!);
128
+ api = GCP.CloudRun("app-api").image("gcr.io/my-project/api:latest").port(8080).public();
129
+ db = GCP.CloudSQL("app-db").engine("postgres").version("16").tier("db-f1-micro");
87
130
  }
88
131
  ```
89
132
 
90
133
  ### Proxmox
91
134
 
92
135
  ```typescript
136
+ import "dotenv/config";
93
137
  import { Stack, Deploy, Protected } from "puls-dev";
94
138
  import { Proxmox, CONFIG, OS, KEYS } from "puls-dev/proxmox";
95
139
 
96
140
  @Deploy({ proxmox: CONFIG.STAGING })
97
141
  class StagingInfra extends Stack {
98
142
  @Protected
99
- db = Proxmox.VM("ix-sto1-db01")
100
- .image(OS.UBUNTU_24_04)
101
- .cores(2).memory(4096)
102
- .ip("1.1.1.1").vlan(2010)
103
- .sshKey(KEYS);
143
+ db = Proxmox.VM("ix-db01").image(OS.UBUNTU_24_04).cores(2).memory(4096)
144
+ .ip("10.8.10.50").vlan(2010).sshKey(KEYS);
104
145
 
105
- app = Proxmox.VM("ix-sto1-app01")
106
- .image(OS.UBUNTU_24_04)
107
- .cores(4).memory(8192)
108
- .ip("1.1.1.1").vlan(2010)
109
- .sshKey(KEYS)
110
- .provision("config/default.yaml");
146
+ app = Proxmox.VM("ix-app01").image(OS.UBUNTU_24_04).cores(4).memory(8192)
147
+ .ip("10.8.10.51").vlan(2010).sshKey(KEYS)
148
+ .provision("config/default.yaml");
149
+ }
150
+ ```
151
+
152
+ ---
153
+
154
+ ## Key features
155
+
156
+ ### Drift detection
157
+
158
+ `Stack.diff()` compares every declared resource against its live cloud state — no API writes, structured output:
159
+
160
+ ```bash
161
+ puls diff infra/production.ts
162
+ ```
163
+
164
+ ```
165
+ 🔍 Diff: Production
166
+
167
+ db prod-db ⚠️ drift
168
+ └─ size db-s-1vcpu-1gb → db-s-2vcpu-2gb
169
+ └─ nodes 1 → 2
170
+ web prod-web ✅ in-sync
171
+ dns example.com ✅ in-sync
172
+
173
+ ⚠️ 1 drifted out of 3 resources.
174
+ ```
175
+
176
+ ### Resource adoption
177
+
178
+ Bring existing cloud infrastructure under Puls management without recreating it:
179
+
180
+ ```typescript
181
+ db = DO.Database("prod-db")
182
+ .adoptId("existing-cluster-uuid")
183
+ .adoptOutput("host", "db.internal.example.com")
184
+ .adoptOutput("uri", "postgres://...");
185
+ ```
186
+
187
+ ### GitHub Actions integration
188
+
189
+ Post plan output as a PR comment automatically. Add to your repo:
190
+
191
+ ```yaml
192
+ # .github/workflows/puls-plan.yml
193
+ - uses: puls-dev/puls-dev@v1
194
+ with:
195
+ command: plan
196
+ stack-file: infra/production.ts
197
+ env:
198
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
199
+ DO_TOKEN: ${{ secrets.DO_TOKEN }}
200
+ ```
201
+
202
+ Every PR that touches infra files gets a comment showing exactly what would change. See [docs/github-actions.md](docs/github-actions.md) for deploy and drift-check workflows.
203
+
204
+ ### Stack outputs & cross-stack wiring
205
+
206
+ ```typescript
207
+ @Deploy({ proxmox: CONFIG.STAGING, token: process.env.DO_TOKEN })
208
+ class Infra extends Stack {
209
+ vm = Proxmox.VM("ix-app01").cores(4).memory(8192).ip("10.8.10.51").vlan(2010);
210
+ dns = DO.Domain("example.com").pointer("app", this.vm.out.ip); // Output<string>
111
211
  }
112
212
  ```
113
213
 
214
+ Outputs resolve lazily — downstream resources unblock the moment their dependency finishes deploying.
215
+
216
+ ### Dry run / plan
217
+
218
+ ```typescript
219
+ @Deploy({ dryRun: true, proxmox: CONFIG.STAGING })
220
+ class MyStack extends Stack { ... }
221
+ ```
222
+
223
+ Or via the CLI: `puls plan infra/stack.ts` — no config change required.
224
+
225
+ ### Protected resources
226
+
227
+ ```typescript
228
+ @Protected
229
+ db = Proxmox.VM("ix-db01")...; // Puls will refuse to modify or destroy this
230
+ ```
231
+
114
232
  ---
115
233
 
116
234
  ## Decorators
@@ -120,29 +238,19 @@ class StagingInfra extends Stack {
120
238
  | `@Deploy({ ... })` | Deploy all resources in the stack |
121
239
  | `@Deploy({ dryRun: true })` | Print plan without making changes |
122
240
  | `@Destroy` | Tear down all resources in the stack |
123
- | `@Destroy({ proxmox: CONFIG.STAGING })` | Tear down with provider credentials |
124
241
  | `@DryRun` | Shorthand for `@Deploy({ dryRun: true })` |
125
- | `@Protected` (property) | Block changes/destruction of that resource |
126
-
127
- See [docs/decorators.md](docs/decorators.md) for full reference.
242
+ | `@Protected` | Block changes/destruction of that resource |
243
+ | `@Check` | Inventory query — lists all live resources across providers |
128
244
 
129
245
  ---
130
246
 
131
- ## Running
247
+ ## .env
132
248
 
133
249
  ```bash
134
- npm install puls-dev
135
- npx tsx your-stack.ts
136
- ```
137
-
138
- Requires Node 20+.
139
-
140
- **.env**
141
- ```
142
250
  # DigitalOcean
143
251
  DO_TOKEN=
144
252
 
145
- # AWS (standard SDK env vars)
253
+ # AWS
146
254
  AWS_ACCESS_KEY_ID=
147
255
  AWS_SECRET_ACCESS_KEY=
148
256
  AWS_REGION=us-east-1
@@ -151,8 +259,11 @@ AWS_REGION=us-east-1
151
259
  PROXMOX_URL=https://pve.example.com:8006
152
260
  PROXMOX_USER=root@pam
153
261
  PROXMOX_TOKEN_NAME=puls
154
- PROXMOX_TOKEN_SECRET=some-super-secret
262
+ PROXMOX_TOKEN_SECRET=
155
263
  PROXMOX_NODES=pve1,pve2
156
- PROXMOX_DNS_DOMAIN=nolimit.int
157
- PROXMOX_DNS_SERVERS=1.1.1.1,2.2.2.2
264
+
265
+ # GCP / Firebase
266
+ GCP_SA=./service-account.json
158
267
  ```
268
+
269
+ Requires Node 20+.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "puls-dev",
3
- "version": "0.3.5",
3
+ "version": "0.3.6",
4
4
  "description": "Intent-driven infrastructure-as-code with eager discovery and no state files.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",