@specific.dev/cli 0.1.49 → 0.1.51

package/dist/docs/builds.md

@@ -16,6 +16,8 @@ build "api" {
 ## Optional fields
 
 - `command` - Build command to run after dependencies are installed (e.g., `npm run build`, `go build -o api`).
+- `root` - Working directory for build commands, relative to `specific.hcl`. Defaults to `"."`. Sets the `WORKDIR` in the generated Dockerfile. Services that reference this build inherit its root. Dependency detection (e.g., `package.json`) also looks in this directory.
+- `context` - Docker build context scope, relative to `specific.hcl`. Defaults to `"."`. Controls what files are available to `COPY` in the Dockerfile and what's included in the deployment tarball. Use this when you need to include files outside of `root` (e.g., shared libraries in a monorepo).
 - `env` - Environment variables available during the build. Supports string literals and `service.<name>.public_url` references. These are passed as Docker build args.
 
 ## Automatic dependency installation
@@ -73,6 +75,46 @@ Supported reference types:
 - String literals (e.g., `"production"`)
 - `service.<name>.public_url` - The public domain of another service
 
+## Monorepo support
+
+Use `root` to specify where build commands run in a monorepo. This sets the working directory for both the build command and dependency installation.
+
+```hcl
+build "backend" {
+  base = "node"
+  root = "packages/backend"
+  command = "npm run build"
+}
+
+build "frontend" {
+  base = "node"
+  root = "packages/frontend"
+  command = "npm run build"
+}
+```
+
+Without `root`, you would need to prefix commands with `cd packages/backend &&`, and dependency detection would look for `package.json` in the wrong directory.
+
+Services that reference a build inherit its `root` automatically, so service commands also run from the correct directory.
+
+### `root` vs `context`
+
+`root` and `context` are orthogonal:
+
+- `root` = where commands run (working directory)
+- `context` = what files are available (Docker build context / tarball scope)
+
+By default, `context` is `"."` (the `specific.hcl` directory), which includes all files in the project. You only need to set `context` when you want to widen the scope beyond the default, for example to include a parent directory:
+
+```hcl
+# specific.hcl is in apps/myapp/, but shared libs are in libs/
+build "api" {
+  base = "node"
+  root = "packages/api"
+  context = "../"          # Include parent dir so shared libs are available
+}
+```
+
 ## Dev configuration
 
 Override the build command for local development. If no `dev` block is defined, the build is skipped in development.

package/dist/docs/index.md

@@ -17,6 +17,9 @@ A full development environment can be started with `specific dev`. To deploy any
 - [Services](/services): define how to build, deploy and run the code in this project as services, both in development and production.
 - [Secrets and configuration](/secrets-config): define secrets and configuration variables that the user may or should provide. These can be injected into services through environment variables.
 - [Postgres](/postgres): define managed PostgreSQL databases that services depend on.
+<!-- beta:reshape -->
+- [Reshape](/postgres/reshape): zero-downtime database schema migrations.
+<!-- /beta:reshape -->
 - [Sync](/sync): define real-time, partial synchronisation out of PostgreSQL into frontends or other services. Should be used to implement real-time and collaborative apps.
 - [Storage](/storage): define S3-compatible object/blob storage for services to store files in.
 - [Redis](/redis): define non-durable Redis-compatible databases for caching and more.

package/dist/docs/postgres/reshape/actions.md

@@ -0,0 +1,90 @@
+<!-- beta:reshape -->
+# Reshape Actions
+
+Reshape migrations are composed of **actions** that define schema changes. Each migration file contains one or more actions that are applied together.
+
+## Available Actions
+
+Reshape supports many different actions for modifying your database schema:
+
+- `create_table` - Create a new table
+- `add_column` - Add a column to an existing table
+- `alter_column` - Modify an existing column (type, default, nullable)
+- `remove_column` - Remove a column from a table
+- `create_index` - Create an index
+- `remove_index` - Remove an index
+- `add_foreign_key` - Add a foreign key constraint
+- `remove_foreign_key` - Remove a foreign key constraint
+- `create_enum` - Create an enum type
+- `alter_enum` - Add or remove variants from an enum
+- `remove_enum` - Remove an enum type
+- `rename_table` - Rename a table
+- `remove_table` - Remove a table
+- `custom` - Run custom SQL
+
+## Action Documentation
+
+For detailed documentation on each action including all available options and examples, use the Reshape CLI directly:
+
+```bash
+# List all available actions
+reshape docs /actions
+
+# Get documentation for a specific action
+reshape docs /actions/create-table
+reshape docs /actions/add-column
+reshape docs /actions/alter-column
+reshape docs /actions/remove-column
+reshape docs /actions/create-enum
+reshape docs /actions/alter-enum
+reshape docs /actions/remove-enum
+reshape docs /actions/add-index
+reshape docs /actions/remove-index
+reshape docs /actions/add-foreign-key
+reshape docs /actions/remove-foreign-key
+reshape docs /actions/rename-table
+reshape docs /actions/remove-table
+reshape docs /actions/custom
+```
+
+## Example Migration
+
+Here's an example migration that creates a table and adds an index:
+
+```toml
+# migrations/001_create_users.toml
+
+[[actions]]
+type = "create_table"
+name = "users"
+primary_key = ["id"]
+
+  [[actions.columns]]
+  name = "id"
+  type = "INTEGER"
+  generated = "ALWAYS AS IDENTITY"
+
+  [[actions.columns]]
+  name = "email"
+  type = "TEXT"
+  nullable = false
+
+  [[actions.columns]]
+  name = "created_at"
+  type = "TIMESTAMPTZ"
+  default = "NOW()"
+
+[[actions]]
+type = "add_index"
+table = "users"
+name = "users_email_idx"
+columns = ["email"]
+unique = true
+```
+
+---
+
+Related topics:
+- Run `specific docs /postgres/reshape` for general Reshape documentation
+- Run `reshape docs /actions/{ACTION}` for detailed action documentation
+<!-- /beta:reshape -->

package/dist/docs/postgres/reshape/index.md

@@ -0,0 +1,149 @@
+<!-- beta:reshape -->
+# Reshape Migrations
+
+Zero-downtime database schema migrations using [Reshape](https://github.com/fabianlindfors/reshape).
+
+Reshape is a schema migration tool that uses a 3-phase approach to achieve zero-downtime migrations:
+
+1. **Start**: Creates new schema version with views and triggers. Both old and new schemas are available simultaneously.
+2. **Rollout**: Deploy new application code. Services use the new schema via `search_path`.
+3. **Complete**: Removes old schema and cleanup artifacts.
+
+## Enabling Reshape
+
+Add a `reshape` block to your postgres definition in `specific.hcl`:
+
+```hcl
+postgres "main" {
+  reshape {
+    enabled = true
+  }
+}
+```
+
+With a custom migrations directory:
+
+```hcl
+postgres "main" {
+  reshape {
+    enabled = true
+    migrations_dir = "db/migrations"
+  }
+}
+```
+
+The default migrations directory is `migrations/` relative to `specific.hcl`.
+
+## Automatic Migration Management
+
+When `specific dev` starts with Reshape enabled, migrations are automatically managed:
+
+1. **All migrations except the last one are completed** - These become permanent schema changes
+2. **The last migration is started but not completed** - This allows iteration during development
+3. **Completed migration files are made read-only** - Prevents accidental modification
+
+This means you can focus on writing migrations without manually running commands.
+
+### File Change Handling
+
+While `specific dev` is running:
+
+- **Modifying the last migration file**: The migration is automatically aborted and restarted. Your services continue running (no restart needed since the schema name doesn't change).
+
+- **Adding a new migration file**: The previous migration is completed (made permanent), and the new migration is started. Services are automatically restarted to use the new schema.
+
+## Connection Strings
+
+When Reshape is enabled, `postgres.<name>.url` automatically includes the correct `search_path` option. You don't need to change your service configuration:
+
+```hcl
+service "api" {
+  build = build.api
+  command = "node server.js"
+
+  env = {
+    DATABASE_URL = postgres.main.url  # Automatically includes search_path
+  }
+}
+```
+
+## Writing Migrations
+
+Place migration files in your migrations directory. Files are processed in **lexical order** (e.g., `001_first.toml` before `002_second.toml`).
+
+**IMPORTANT:** You MUST run `specific reshape check` every time you create or edit a migration file. This validates the migration syntax and catches errors before the watcher applies them. Without this step, invalid migrations will silently fail to apply.
+
+```bash
+# Validate all migration files
+specific reshape check
+
+# Validate migrations for a specific database
+specific reshape check main
+```
+
+Example migration (`migrations/001_create_users.toml`):
+
+```toml
+[[actions]]
+type = "create_table"
+name = "users"
+primary_key = ["id"]
+
+  [[actions.columns]]
+  name = "id"
+  type = "INTEGER"
+  generated = "ALWAYS AS IDENTITY"
+
+  [[actions.columns]]
+  name = "email"
+  type = "TEXT"
+  nullable = false
+```
+
+For full documentation on available actions and migration syntax, see [Actions](/postgres/reshape/actions).
+
+## Manual Migration Commands
+
+You can also manually control migrations using the `specific reshape` command:
+
+```bash
+# Validate migration files (does NOT require specific dev to be running)
+specific reshape check
+
+# Start a migration (applies new schema while keeping old one available)
+specific reshape start
+
+# Start migration on a specific database
+specific reshape start main
+
+# Check migration status
+specific reshape status main
+
+# Complete a migration (removes old schema)
+specific reshape complete main
+
+# Abort a migration (rolls back to old schema)
+specific reshape abort main
+```
+
+**Note:** Most commands require `specific dev` to be running as they need access to the database. The `check` command is an exception - it only validates migration file syntax and can be run anytime.
+
+## Development Workflow
+
+1. Write your migration file in the migrations directory
+2. Run `specific reshape check` to validate the migration syntax
+3. `specific dev` automatically applies it
+4. Iterate on the migration - run `specific reshape check` after **every** change
+5. When ready, add a new migration file to "lock in" the previous one
+
+**Remember:** Always run `specific reshape check` after any change to a migration file. This is required to catch syntax errors before they are applied.
+
+Completed migrations are made read-only to prevent accidental changes. If you need to modify a completed migration, you'll need to manually change the file permissions first.
+
+---
+
+Related topics:
+- Run `specific docs /postgres/reshape/actions` for available migration actions
+- Run `specific docs /postgres` for general PostgreSQL documentation
+- Run `specific docs /sync` for real-time data synchronization
+<!-- /beta:reshape -->

package/dist/docs/postgres.md

@@ -49,8 +49,27 @@ specific psql main -- -c "SELECT * FROM users LIMIT 5"
 specific psql main -- -c "\dt"
 ```
 
+<!-- beta:reshape -->
+## Schema Migrations
+
+For zero-downtime schema migrations, use Reshape:
+
+```hcl
+postgres "main" {
+  reshape {
+    enabled = true
+  }
+}
+```
+
+Run `specific docs /postgres/reshape` for full documentation on managing migrations.
+
+<!-- /beta:reshape -->
 ---
 
 Related topics:
+<!-- beta:reshape -->
+- Run `specific docs /postgres/reshape` for zero-downtime schema migrations
+<!-- /beta:reshape -->
 - Run `specific docs sync` for real-time data synchronization
-- Run `specific docs exec` for running migrations
+- Run `specific docs exec` for running one-off commands

package/dist/docs/services.md

@@ -46,6 +46,7 @@ service "api" {
 ```
 
 - `command` - Command to start the server
+- `root` - Working directory for service commands, relative to `specific.hcl`. Defaults to the referenced build's `root`, or `"."` if no build. In development, this sets the working directory for the spawned process. In production, the working directory is set by the build's `root` in the Dockerfile.
 - `endpoint` - Defines a network endpoint (see Endpoints below)
 - `port` - Reference to the auto-assigned port (pass this to your server)
 
@@ -190,6 +191,39 @@ service "api" {
 }
 ```
 
+## Monorepo support
+
+For monorepos, use `root` on builds to set the working directory. Services inherit the build's root, so commands like `npm start` run from the correct directory:
+
+```hcl
+build "backend" {
+  base = "node"
+  root = "packages/backend"
+  command = "npm run build"
+}
+
+service "backend" {
+  build = build.backend
+  command = "node dist/index.js"
+
+  dev {
+    command = "npm run dev"
+  }
+}
+```
+
+Dev-only services can set their own root:
+
+```hcl
+service "docs" {
+  root = "packages/docs"
+
+  dev {
+    command = "npm run dev"
+  }
+}
+```
+
 ## Workers
 
 Background processes that don't expose HTTP endpoints.

package/dist/postinstall.js

@@ -111,7 +111,7 @@ function trackEvent(event, properties) {
     event,
     properties: {
       ...properties,
-      cli_version: "0.1.49",
+      cli_version: "0.1.51",
       platform: process.platform,
       node_version: process.version,
       project_id: getProjectId(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/cli",
-  "version": "0.1.49",
+  "version": "0.1.51",
   "description": "CLI for Specific infrastructure-as-code",
   "type": "module",
   "main": "dist/cli.js",
@@ -66,4 +66,4 @@
       "esbuild"
     ]
   }
-}
+}