@specific.dev/cli 0.1.48 → 0.1.50

package/dist/docs/builds.md

@@ -16,6 +16,7 @@ build "api" {
 ## Optional fields
 
 - `command` - Build command to run after dependencies are installed (e.g., `npm run build`, `go build -o api`).
+- `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
 
@@ -51,6 +52,27 @@ For **go**, **rust**, and **java**, a multi-stage build is used:
 - **rust**: Only `target/release` is copied to the working directory in the runtime image.
 - **java**: JAR files from `target/*.jar` or `build/libs/*.jar` are copied to `app.jar` in the working directory.
 
+## Build-time environment variables
+
+Use `env` to pass environment variables during the build step. This is useful for frameworks like Next.js that inline environment variables at build time.
+
+```hcl
+build "web" {
+  base    = "node"
+  command = "npm run build"
+
+  env = {
+    NEXT_PUBLIC_API_URL = service.api.public_url
+    NODE_ENV            = "production"
+  }
+}
+```
+
+Supported reference types:
+
+- String literals (e.g., `"production"`)
+- `service.<name>.public_url` - The public domain of another service
+
 ## 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

@@ -34,8 +34,42 @@ postgres "main" {}
 - `password` - Database password
 - `name` - Database name
 
+## Querying the database
+
+Use `specific psql` to connect to a development database. This will start the database if it's not already running.
+
+```sh
+# Interactive session
+specific psql main
+
+# Run a single query (useful for coding agents)
+specific psql main -- -c "SELECT * FROM users LIMIT 5"
+
+# List tables
+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

@@ -4,9 +4,28 @@ Services define how to run the code and connect it to other parts of the infrast
 
 ## Dynamic services
 
-Run a server process exposed via HTTP. TLS is handled automatically.
+Example of running publicly exposed API and frontend web services:
 
 ```hcl
+build "web" {
+  base = "node"
+  command = "npm run build"
+}
+
+service "web" {
+  build = build.web
+  command = "npm start"
+
+  endpoint {
+    public = true
+  }
+
+  env = {
+    PORT = port
+    API_URL = service.api.public_url
+  }
+}
+
 build "api" {
   base = "go"
   command = "go build -o api"
@@ -93,9 +112,9 @@ service "worker" {
 }
 ```
 
-## Inter-service communication
+## Private inter-service communication
 
-Services can reference other services' endpoints to communicate with each other:
+Services can reference other services' endpoints using `private_url` to communicate with each other over a private network:
 
 ```hcl
 service "api" {
@@ -116,23 +135,58 @@ service "worker" {
   command = "./worker"
 
   env = {
-    API_URL = service.api.url  # localhost:PORT in dev, api:80 in prod
+    API_URL = service.api.private_url
   }
 }
 ```
 
 Available service reference attributes:
 
-- `service.<name>.url` - Full URL without scheme (e.g., `localhost:3000`)
+- `service.<name>.private_url` - Internal URL without scheme (host and port)
 - `service.<name>.host` - Host only (e.g., `localhost`)
 - `service.<name>.port` - Port only (e.g., `3000`)
+- `service.<name>.public_url` - Public URL without scheme (host and port). Only available for endpoints with `public = true`. Served over HTTPS.
 
 For services with multiple named endpoints, you must specify the endpoint:
 
 ```hcl
 env = {
-  MAIN_URL = service.api.endpoint.main.url
-  ADMIN_URL = service.api.endpoint.admin.url
+  MAIN_URL = service.api.endpoint.main.private_url
+  ADMIN_URL = service.api.endpoint.admin.private_url
+  PUBLIC_API = service.api.endpoint.main.public_url
+}
+```
+
+### Public inter-service communication
+
+The private communication does not work in the case of a frontend or client service needing to speak with a backend service, as `private_url` is not externally reachable. In that case, the backend service MUST expose a public endpoint. The frontend or client service can then reference that endpoint using `public_url`:
+
+```hcl
+service "web" {
+  build = build.web
+  command = "npm start"
+
+  endpoint {
+    public = true
+  }
+
+  env = {
+    PORT = port
+  }
+}
+
+service "api" {
+  build = build.api
+  command = "./api"
+
+  endpoint {
+    public = true
+  }
+
+  env = {
+    PORT = port
+    CORS_ORIGIN = service.web.public_url
+  }
 }
 ```
 
@@ -224,7 +278,7 @@ service "worker" {
   dev {
     command = "node --watch worker.js"
     env = {
-      TEMPORAL_URL = service.temporal.url  # Override with local URL in dev
+      TEMPORAL_URL = service.temporal.private_url  # Override with local URL in dev
     }
   }
 }

package/dist/postinstall.js

@@ -0,0 +1,141 @@
+// src/lib/analytics/index.ts
+import { PostHog } from "posthog-node";
+import * as os2 from "os";
+import * as crypto from "crypto";
+
+// src/lib/project/config.ts
+import * as fs from "fs";
+import * as path from "path";
+var PROJECT_ID_FILE = ".specific/project_id";
+var ProjectNotLinkedError = class extends Error {
+  constructor() {
+    super(
+      `Project not linked to Specific.
+
+The file ${PROJECT_ID_FILE} does not exist.
+
+Run: specific deploy`
+    );
+    this.name = "ProjectNotLinkedError";
+  }
+};
+function readProjectId(projectDir = process.cwd()) {
+  const projectIdPath = path.join(projectDir, PROJECT_ID_FILE);
+  if (!fs.existsSync(projectIdPath)) {
+    throw new ProjectNotLinkedError();
+  }
+  const projectId = fs.readFileSync(projectIdPath, "utf-8").trim();
+  if (!projectId) {
+    throw new Error(`${PROJECT_ID_FILE} is empty`);
+  }
+  return projectId;
+}
+function hasProjectId(projectDir = process.cwd()) {
+  const projectIdPath = path.join(projectDir, PROJECT_ID_FILE);
+  return fs.existsSync(projectIdPath);
+}
+
+// src/lib/auth/credentials.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+import * as os from "os";
+
+// src/lib/auth/login.tsx
+import React from "react";
+import { render, Box, Text } from "ink";
+import Spinner from "ink-spinner";
+
+// src/lib/auth/credentials.ts
+function getUserCredentialsDir() {
+  return path2.join(os.homedir(), ".specific");
+}
+function getCredentialsPath() {
+  return path2.join(getUserCredentialsDir(), "credentials.json");
+}
+function readUserCredentials() {
+  const credentialsPath = getCredentialsPath();
+  if (!fs2.existsSync(credentialsPath)) {
+    return null;
+  }
+  try {
+    const content = fs2.readFileSync(credentialsPath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+function getUserId() {
+  const credentials = readUserCredentials();
+  return credentials?.userId ?? null;
+}
+
+// src/lib/analytics/index.ts
+var POSTHOG_HOST = "https://eu.i.posthog.com";
+var client = null;
+var anonymousId = null;
+function isEnabled() {
+  return true;
+}
+function getAnonymousId() {
+  if (anonymousId) return anonymousId;
+  const machineId = `${os2.hostname()}-${os2.userInfo().username}`;
+  anonymousId = crypto.createHash("sha256").update(machineId).digest("hex").slice(0, 16);
+  return anonymousId;
+}
+function getProjectId() {
+  try {
+    if (hasProjectId()) {
+      return readProjectId();
+    }
+  } catch {
+  }
+  return void 0;
+}
+function getClient() {
+  if (!isEnabled()) return null;
+  if (!client) {
+    client = new PostHog("phc_qNQCEUXh6ErdciQRRmeG2xlVvwFjkcW6A5bnOFJ8vXZ", {
+      host: POSTHOG_HOST,
+      flushAt: 1,
+      // Flush immediately for CLI
+      flushInterval: 0
+    });
+  }
+  return client;
+}
+function trackEvent(event, properties) {
+  const ph = getClient();
+  if (!ph) return;
+  ph.capture({
+    distinctId: getAnonymousId(),
+    event,
+    properties: {
+      ...properties,
+      cli_version: "0.1.50",
+      platform: process.platform,
+      node_version: process.version,
+      project_id: getProjectId(),
+      user_id: getUserId() ?? void 0
+    }
+  });
+}
+async function shutdown() {
+  if (client) {
+    await client.shutdown();
+    client = null;
+  }
+}
+
+// src/postinstall.ts
+async function main() {
+  try {
+    trackEvent("cli_installed");
+    await shutdown();
+  } catch {
+  }
+  console.log();
+  console.log("Thanks for installing Specific!");
+  console.log("Get started: https://docs.specific.dev/");
+  console.log();
+}
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/cli",
-  "version": "0.1.48",
+  "version": "0.1.50",
   "description": "CLI for Specific infrastructure-as-code",
   "type": "module",
   "main": "dist/cli.js",
@@ -16,7 +16,8 @@
     "build:staging": "NODE_ENV=staging node build.mjs && cp -r src/docs dist/",
     "link:dev": "npm run build:dev && npm link",
     "link:staging": "npm run build:staging && npm link",
-    "link:prod": "npm run build && npm link"
+    "link:prod": "npm run build && npm link",
+    "postinstall": "node dist/postinstall.js || true"
   },
   "keywords": [
     "infrastructure",