@homemadedev/config 2.0.0 → 3.1.0

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.
package/README.md CHANGED
@@ -25,6 +25,38 @@ The module's default export must be the object returned by `config()`. It is eva
25
25
 
26
26
  `version` is optional. An explicit `version: "1.0.0"` in the config overrides everything; without one, the platform uses the `@homemadedev/config` version your repo installs in its `package.json`, and if the package isn't installed either, the latest version the platform supports. Configs newer than the platform are rejected with a clear error.
27
27
 
28
+ ### Service order and readiness
29
+
30
+ A service can wait for others with `depends_on`. It starts once each dependency is healthy (the default condition) or, with `condition: "started"`, once the dependency's terminal started. There is no time limit: a dependency that takes ten minutes to pull its image is waited for. If a dependency exits instead, the service does not start, shows as failed and its terminal says which dependency stopped; it starts once that dependency is restarted and healthy. A dependency is healthy when its `healthcheck` passes, or, without one, when something listens on its `port`. A database speaks no HTTP, so give it a `healthcheck.cmd`: exit code 0 counts as healthy.
31
+
32
+ ```ts
33
+ export default config({
34
+ services: {
35
+ db: {
36
+ cmd: "docker start -a appdb || docker run --name appdb -e POSTGRES_PASSWORD=app -p 54329:5432 postgres:17",
37
+ port: 54329,
38
+ healthcheck: { cmd: "docker exec appdb pg_isready -h 127.0.0.1 -q" },
39
+ },
40
+ web: { cmd: "pnpm db:migrate && pnpm dev", port: 3000, url: true, depends_on: { db: { condition: "healthy" } } },
41
+ },
42
+ });
43
+ ```
44
+
45
+ ### Per-VM secrets, default values and sign-in links
46
+
47
+ An `env_schema` entry can fill its key itself. `generate: true` makes a random secret once per VM (a VM env var marked secret, kept across reboots and never part of a warm snapshot). `default` is the value when nobody set the key; it may reference `${HOMEMADE_URL_<port>}`. A value set in the dashboard wins over both. A service's `signInUrl` turns them into the link the VM page shows under the service:
48
+
49
+ ```ts
50
+ export default config({
51
+ env_schema: [{ key: "APP_TOKEN", generate: true }, { key: "PUBLIC_URL", default: "${HOMEMADE_URL_3000}" }],
52
+ services: {
53
+ web: { cmd: "pnpm dev", port: 3000, url: true, signInUrl: "${HOMEMADE_URL_3000}/login#token=${APP_TOKEN}" },
54
+ },
55
+ });
56
+ ```
57
+
58
+ If you have connected GitHub, VMs you create get `GITHUB_TOKEN`, `GH_TOKEN` and `MISE_GITHUB_TOKEN` with your GitHub login, so downloads from GitHub are not rate limited. Set `GITHUB_TOKEN` yourself and yours is used instead.
59
+
28
60
  ### Create-time parameters
29
61
 
30
62
  `parameters` declares knobs a user fills in when creating a VM from this repo — rendered in the New VM dialog and delivered as `HOMEMADE_PARAM_<NAME>` env vars (name upper-cased):
@@ -1,5 +1,5 @@
1
1
  {
2
- "$id": "https://homemade.dev/schemas/2.0.0/config.json",
2
+ "$id": "https://homemade.dev/schemas/3.1.0/config.json",
3
3
  "$schema": "http://json-schema.org/draft-07/schema#",
4
4
  "type": "object",
5
5
  "properties": {
@@ -54,6 +54,15 @@
54
54
  {
55
55
  "type": "object",
56
56
  "properties": {
57
+ "default": {
58
+ "description": "Value used when no env var with this key is set (org, project or VM). May reference ${HOMEMADE_URL_<port>}. Not for secrets: it is part of the repo.",
59
+ "type": "string",
60
+ "maxLength": 4096
61
+ },
62
+ "generate": {
63
+ "description": "true: the platform makes a random secret for this key once per VM (a VM env var marked secret, kept across reboots). Never part of a warm snapshot.",
64
+ "type": "boolean"
65
+ },
57
66
  "key": {
58
67
  "type": "string",
59
68
  "minLength": 1
@@ -226,6 +235,29 @@
226
235
  "type": "string",
227
236
  "minLength": 1
228
237
  },
238
+ "depends_on": {
239
+ "description": "Services this one waits for before its `cmd` starts, by name, each with a `condition` (\"healthy\" by default, or \"started\"). Replaces sleep loops: a web service waits for its database, however long it takes. If a dependency exits, this service does not start and its terminal says why; it starts once the dependency is restarted and healthy.",
240
+ "type": "object",
241
+ "propertyNames": {
242
+ "type": "string",
243
+ "maxLength": 32,
244
+ "pattern": "^[A-Za-z][A-Za-z0-9_-]*$"
245
+ },
246
+ "additionalProperties": {
247
+ "type": "object",
248
+ "properties": {
249
+ "condition": {
250
+ "default": "healthy",
251
+ "description": "\"healthy\" (default): wait until the dependency reports healthy (its `healthcheck`, or something listening on its `port`). \"started\": wait only until its terminal started.",
252
+ "type": "string",
253
+ "enum": [
254
+ "started",
255
+ "healthy"
256
+ ]
257
+ }
258
+ }
259
+ }
260
+ },
229
261
  "displayName": {
230
262
  "description": "Human-friendly name shown instead of the service key in the dashboard.",
231
263
  "type": "string",
@@ -236,6 +268,11 @@
236
268
  "description": "Probe the service over localhost HTTP (guest-side) and report health on the `health` command / VM runtime. Success is any HTTP status below 500 — a 404 still counts as up. Requires `port`.",
237
269
  "type": "object",
238
270
  "properties": {
271
+ "cmd": {
272
+ "description": "A shell command probed instead of HTTP, run as the VM user in the workspace: exit code 0 counts as up. Needs no `port`.",
273
+ "type": "string",
274
+ "minLength": 1
275
+ },
239
276
  "interval": {
240
277
  "default": 5,
241
278
  "description": "Seconds between probes. Default 5.",
@@ -280,6 +317,10 @@
280
317
  "minimum": 1,
281
318
  "maximum": 65535
282
319
  },
320
+ "publicHost": {
321
+ "description": "By default the preview proxy hands the app each request as if it came to http://localhost:<port> (Host, Origin and Referer rewritten; redirects to localhost:<port> rewritten back to the preview URL), so dev servers' host checks (Vite allowedHosts, Django ALLOWED_HOSTS, Rails config.hosts, Next allowedDevOrigins) pass with no app config. true sends the real preview hostname with X-Forwarded-Host/Proto instead, for apps that need it (multi-tenant hosts, absolute URLs built from the request). Only meaningful when `url` is true.",
322
+ "type": "boolean"
323
+ },
283
324
  "share": {
284
325
  "default": "public",
285
326
  "description": "Who may open the service's public URL. \"public\": anyone with the link. \"authenticated\": members of the organization that owns the VM. \"owner\": only the user who created the VM (platform admins always allowed). Only meaningful when `url` is true.",
@@ -290,6 +331,12 @@
290
331
  "owner"
291
332
  ]
292
333
  },
334
+ "signInUrl": {
335
+ "description": "A per-VM sign-in or pairing link the VM page shows under the service, with copy and open buttons. A template: ${HOMEMADE_URL_<port>} is that port's VM URL, ${KEY} the value of the VM's env var KEY (e.g. one `generate: true` in env_schema). Only meaningful when `url` is true.",
336
+ "type": "string",
337
+ "minLength": 1,
338
+ "maxLength": 1024
339
+ },
293
340
  "url": {
294
341
  "default": false,
295
342
  "type": "boolean"
@@ -342,16 +389,8 @@
342
389
  ]
343
390
  },
344
391
  "sleep_after": {
345
- "anyOf": [
346
- {
347
- "type": "string",
348
- "const": "never"
349
- },
350
- {
351
- "type": "string",
352
- "pattern": "^[0-9]+(?:m|h)$"
353
- }
354
- ]
392
+ "type": "string",
393
+ "pattern": "^(?:never|[0-9]+(?:m|h))$"
355
394
  },
356
395
  "troubleshootingUrl": {
357
396
  "type": "string",
package/dist/index.d.ts CHANGED
@@ -1,5 +1,7 @@
1
- /** Per-service HTTP healthcheck. Requires `port`. */
1
+ /** Per-service healthcheck: an HTTP probe on the service's `port`, or a shell `cmd` (exit 0 = up, no port needed). */
2
2
  export interface HomemadeServiceHealthcheck {
3
+ /** Shell command probed instead of HTTP, run as the VM user in the workspace; exit 0 counts as up (e.g. `pg_isready -h 127.0.0.1`). */
4
+ cmd?: string;
3
5
  /** Seconds between probes. Default 5. */
4
6
  interval?: number;
5
7
  /** HTTP path probed on the service's own port (`http://127.0.0.1:{port}{path}`). Default "/". */
@@ -7,15 +9,22 @@ export interface HomemadeServiceHealthcheck {
7
9
  /** Consecutive failing probes before flipping unhealthy; any success flips back healthy. Default 6. */
8
10
  threshold?: number;
9
11
  }
12
+ /** One `depends_on` entry: when the dependent may start. */
13
+ export interface HomemadeServiceDependency {
14
+ /** "healthy" (default): the dependency reports healthy (its healthcheck, or something listening on its port). "started": its terminal started. */
15
+ condition?: "healthy" | "started";
16
+ }
10
17
  /** One entry of the `services` map. */
11
18
  export interface HomemadeServiceConfig {
12
19
  /** Start `cmd` automatically at boot (default true); false just documents how to run it. */
13
20
  autostart?: boolean;
14
21
  /** Command typed into a plain terminal session at boot; omit for a pure port/URL claim. */
15
22
  cmd?: string;
23
+ /** Services this one waits for before `cmd` starts, by name (e.g. `{ db: { condition: "healthy" } }`); waits as long as they take; a dependency that exits leaves it failed with the reason. */
24
+ depends_on?: Record<string, HomemadeServiceDependency>;
16
25
  /** Human-friendly name shown instead of the service key in the dashboard. */
17
26
  displayName?: string;
18
- /** Probe the service over localhost HTTP; any status below 500 counts as up (reported on the VM's runtime status). Requires `port`. */
27
+ /** Probe the service over localhost HTTP (any status below 500 counts as up; requires `port`) or with a `cmd`; reported on the VM's runtime status. */
19
28
  healthcheck?: HomemadeServiceHealthcheck;
20
29
  /** Hide from the quick-open dropdown and status panel; does not affect autostart or open tabs. */
21
30
  hidden?: boolean;
@@ -25,9 +34,14 @@ export interface HomemadeServiceConfig {
25
34
  order?: number;
26
35
  /** Routed port (1–65535). */
27
36
  port?: number;
37
+ /** true → the app sees the real preview hostname (X-Forwarded-Host/Proto). Default: requests arrive as `http://localhost:<port>` (Host/Origin/Referer rewritten, localhost redirects mapped back), so dev-server host checks pass. Only when `url` is true. */
38
+ publicHost?: boolean;
28
39
  /** Who may open the service's public URL (default "public"): "public"=anyone with link, "authenticated"=org
29
40
  * members, "owner"=creator only (admins always allowed). Only when `url` is true. */
30
41
  share?: "public" | "authenticated" | "owner";
42
+ /** A per-VM sign-in or pairing link shown under the service on the VM page. A template:
43
+ * `${HOMEMADE_URL_<port>}` is that port's VM URL, `${KEY}` the VM's env var KEY (e.g. one `generate: true` in env_schema). */
44
+ signInUrl?: string;
31
45
  /** true → the service gets a public `{project-slug}-{vm-slug}-{port}-{org-slug}` URL. Requires `port`. */
32
46
  url?: boolean;
33
47
  }
@@ -56,6 +70,12 @@ export interface HomemadeAgentConfig {
56
70
  }
57
71
  /** One `env_schema` entry in its object form. */
58
72
  export interface HomemadeEnvSchemaEntry {
73
+ /** Value used when nobody set the key (org, project or VM env var). May reference `${HOMEMADE_URL_<port>}`.
74
+ * Not for secrets. Not with `generate` or `warmup`. */
75
+ default?: string;
76
+ /** true → a random secret made once per VM (a VM env var marked secret, kept across reboots),
77
+ * never part of a warm snapshot. Not with `default` or `warmup`. */
78
+ generate?: boolean;
59
79
  /** The environment variable name. */
60
80
  key: string;
61
81
  /** Deliver value to the throwaway warmup VM before the snapshot is taken (default false; for install-time
@@ -94,13 +114,13 @@ export interface HomemadeConfig {
94
114
  /** Services supervised at runtime. Mutually exclusive with `compose`. */
95
115
  services?: Record<string, HomemadeServiceConfig>;
96
116
  /** The machine size new VMs start on: "nano" | "tiny" | "small" | "medium" | "large", or a custom
97
- * `{ vcpu, ram, disk }` shape (Enterprise only). Omitted = medium (Hobby: tiny). The New VM sheet can
117
+ * `{ vcpu, ram, disk }` shape (Enterprise only). Omitted = small (Hobby: tiny). The New VM sheet can
98
118
  * still pick another named size. */
99
119
  size?: HomemadeMachineSize | HomemadeCustomMachineSize;
100
120
  /** Build-time commands, baked into the template. Runs before repo code is copied in (only dependency
101
121
  * manifests exist yet) — commands needing source files belong in `install`. */
102
122
  setup?: string[];
103
- /** Auto-sleep countdown before suspend: a duration like "30m"/"2h" (10–1440 min), or "never". Omitted = project/plan default. */
123
+ /** Auto-sleep countdown before sleep: a duration like "30m"/"2h" (10–1440 min), or "never". Omitted = project/plan default. */
104
124
  sleep_after?: string;
105
125
  /** Project-owned runbook shown when a best-effort boot step fails. */
106
126
  troubleshootingUrl?: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@homemadedev/config",
3
- "version": "2.0.0",
3
+ "version": "3.1.0",
4
4
  "description": "Typed config() helper and JSON schema for homemade.dev project configs (.homemade/config.ts, config.js, config.jsonc or config.json)",
5
5
  "homepage": "https://homemade.dev",
6
6
  "license": "MIT",
@@ -31,6 +31,7 @@
31
31
  "build": "tsx scripts/generate-schema.ts && tsc -p tsconfig.build.json",
32
32
  "check": "tsc --noEmit",
33
33
  "prepublishOnly": "pnpm build",
34
+ "stamp": "tsx scripts/stamp.ts",
34
35
  "test": "vitest run"
35
36
  },
36
37
  "devDependencies": {