@specific.dev/cli 0.1.37

package/dist/docs/secrets-config.md

@@ -0,0 +1,141 @@
+# Secrets and Configuration
+
+Secrets and config let you parameterize values that services need. Use them to avoid hardcoding values in your `specific.hcl`.
+
+## When to use which
+
+- **Secrets** - For sensitive information that should never be committed to version control: API keys, database passwords, signing keys, etc.
+- **Config** - For non-sensitive values that may vary between environments: log levels, feature flags, URLs, etc.
+
+## Secrets
+
+Declare secrets that your application needs. Values are stored separately from configuration in `specific.secrets` (gitignored).
+
+```hcl
+secret "stripe_api_key" {}
+
+secret "jwt_secret" {
+  generated = true
+}
+
+service "api" {
+  build = build.api
+  command = "./api"
+
+  endpoint {
+    public = true
+  }
+
+  env = {
+    STRIPE_API_KEY = secret.stripe_api_key
+    JWT_SECRET = secret.jwt_secret
+  }
+}
+```
+
+### Secret fields
+
+- `generated` - When `true`, auto-generates a random 64-character string if not manually set. Useful for internal secrets like JWT signing keys.
+- `length` - Custom length for generated secrets (default: 64). Only applies when `generated = true`.
+
+### Setting secret values
+
+For local development with `specific dev` or `specific exec`, use the CLI:
+
+```bash
+specific secrets set stripe_api_key
+```
+
+This prompts for the value interactively and stores it in `specific.secrets`. Production secrets are configured separately during deployment.
+
+### Generated vs manual secrets
+
+- **Manual secrets** (no `generated` flag) - Must be set via `specific secrets set`. Error on startup if missing.
+- **Generated secrets** (`generated = true`) - Auto-created on first run if not set. You can still override manually.
+
+## Config
+
+Parameterize non-sensitive configuration values across environments.
+
+```hcl
+config "log_level" {
+  default = "info"
+}
+
+service "api" {
+  build = build.api
+  command = "./api"
+
+  endpoint {
+    public = true
+  }
+
+  env = {
+    LOG_LEVEL = config.log_level
+  }
+}
+```
+
+### Config fields
+
+- `default` - Default value used if not overridden by an environment.
+
+### Environment overrides
+
+Override config values per environment:
+
+```hcl
+config "log_level" {
+  default = "info"
+}
+
+environment "production" {
+  config = {
+    log_level = "warn"
+  }
+}
+
+environment "staging" {
+  config = {
+    log_level = "debug"
+  }
+}
+```
+
+## Example
+
+```hcl
+# External API key - must be set manually, sensitive
+secret "stripe_api_key" {}
+
+# Internal signing key - auto-generate, sensitive
+secret "jwt_secret" {
+  generated = true
+}
+
+# Log level - not sensitive, varies by environment
+config "log_level" {
+  default = "info"
+}
+
+service "api" {
+  build = build.api
+  command = "./api"
+
+  endpoint {
+    public = true
+  }
+
+  env = {
+    STRIPE_API_KEY = secret.stripe_api_key
+    JWT_SECRET = secret.jwt_secret
+    LOG_LEVEL = config.log_level
+  }
+}
+
+environment "production" {
+  config = {
+    log_level = "warn"
+  }
+}
+```

package/dist/docs/services.md

@@ -0,0 +1,325 @@
+# Services
+
+Services define how to run the code and connect it to other parts of the infrastructure, both in production and in local development. All configuration for the app is handled through environment variables, which the code should read from.
+
+## Dynamic services
+
+Run a server process exposed via HTTP. TLS is handled automatically.
+
+```hcl
+build "api" {
+  base = "go"
+  command = "go build -o api"
+}
+
+service "api" {
+  build = build.api
+  command = "./api"
+
+  endpoint {
+    public = true
+  }
+
+  env = {
+    PORT = port
+  }
+}
+```
+
+- `command` - Command to start the server
+- `endpoint` - Defines a network endpoint (see Endpoints below)
+- `port` - Reference to the auto-assigned port (pass this to your server)
+
+## Endpoints
+
+Endpoints define how a service is accessible over the network.
+
+### Single endpoint (most common)
+
+```hcl
+service "api" {
+  build = build.api
+  command = "./api"
+
+  endpoint {
+    public = true
+  }
+
+  env = {
+    PORT = port
+  }
+}
+```
+
+- `public = true` - Makes the endpoint publicly accessible via HTTPS
+- Omitting `public` (or `public = false`) keeps the endpoint internal-only
+
+### Multiple named endpoints
+
+A service can expose multiple endpoints on different ports:
+
+```hcl
+service "api" {
+  build = build.api
+  command = "./api"
+
+  endpoint "main" {
+    public = true
+  }
+
+  endpoint "admin" {}
+
+  env = {
+    MAIN_PORT = endpoint.main.port
+    ADMIN_PORT = endpoint.admin.port
+  }
+}
+```
+
+When using multiple endpoints, you must use `endpoint.<name>.port` instead of `port` to reference each endpoint's port.
+
+### Implicit endpoints
+
+If a service uses `port` in its env vars but has no explicit endpoint blocks, an implicit internal endpoint is created:
+
+```hcl
+service "worker" {
+  build = build.worker
+  command = "./worker"
+
+  env = {
+    PORT = port  # Creates an implicit internal endpoint
+  }
+}
+```
+
+## Inter-service communication
+
+Services can reference other services' endpoints to communicate with each other:
+
+```hcl
+service "api" {
+  build = build.api
+  command = "./api"
+
+  endpoint {
+    public = true
+  }
+
+  env = {
+    PORT = port
+  }
+}
+
+service "worker" {
+  build = build.worker
+  command = "./worker"
+
+  env = {
+    API_URL = service.api.url  # http://localhost:PORT in dev, http://api:80 in prod
+  }
+}
+```
+
+Available service reference attributes:
+
+- `service.<name>.url` - Full URL (e.g., `http://localhost:3000`)
+- `service.<name>.host` - Host only (e.g., `localhost`)
+- `service.<name>.port` - Port only (e.g., `3000`)
+
+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
+}
+```
+
+## Workers
+
+Background processes that don't expose HTTP endpoints.
+
+```hcl
+build "worker" {
+  base = "node"
+  command = "npm run build"
+}
+
+service "worker" {
+  build = build.worker
+  command = "npm run worker"
+}
+```
+
+## Environment variables
+
+```hcl
+service "api" {
+  build = build.api
+  command = "./api"
+
+  endpoint {
+    public = true
+  }
+
+  env = {
+    PORT = port
+    NODE_ENV = "production"
+    DATABASE_URL = postgres.main.url
+  }
+}
+```
+
+## Service dev configuration
+
+Override how a service runs in development. If the referenced build has no `dev` block, it is skipped.
+
+```hcl
+build "nextjs" {
+  base = "node"
+  command = "npm run build"
+  # No dev block = skipped in development
+}
+
+service "web" {
+  build = build.nextjs
+  command = "npm start"
+
+  endpoint {
+    public = true
+  }
+
+  env = {
+    PORT = port
+  }
+
+  dev {
+    command = "npm run dev"  # Handles building + serving with hot reload
+  }
+}
+```
+
+## Dev-only services
+
+Services that only run during local development, not deployed to production. Useful for running local versions of external cloud services like Temporal, LocalStack, or mock servers.
+
+A service is dev-only if it has a `dev.command` but no top-level `command`:
+
+```hcl
+service "temporal" {
+  dev {
+    command = "temporal server start-dev"
+  }
+}
+
+service "worker" {
+  build = build.worker
+  command = "node worker.js"
+
+  env = {
+    TEMPORAL_URL = secret.temporal_url  # Production URL from secret
+  }
+
+  dev {
+    command = "node --watch worker.js"
+    env = {
+      TEMPORAL_URL = service.temporal.url  # Override with local URL in dev
+    }
+  }
+}
+
+secret "temporal_url" {}
+```
+
+Dev-only services:
+- Cannot have a `build` reference (they run arbitrary commands)
+- Are automatically excluded from production deployment
+- Can define endpoints that other services reference during development
+
+## Deploy hooks
+
+Run commands before or after deploying a service.
+
+**Database migrations should use `pre_deploy` hooks.** This ensures migrations complete before the new code starts, and if they fail, the deployment is automatically aborted.
+
+```hcl
+build "api" {
+  base = "node"
+  command = "npm run build"
+}
+
+service "api" {
+  build = build.api
+  command = "node dist/index.js"
+
+  endpoint {
+    public = true
+  }
+
+  env = {
+    PORT = port
+    DATABASE_URL = postgres.main.url
+  }
+
+  pre_deploy {
+    command = "npm run db:migrate"
+  }
+
+  post_deploy {
+    command = "npm run cache:warm"
+  }
+}
+
+postgres "main" {}
+```
+
+- `pre_deploy` - Runs before the service is deployed (e.g., database migrations)
+- `post_deploy` - Runs after the service is deployed (e.g., cache warming)
+
+Hooks run as Kubernetes Jobs using the same container and environment variables as the service. If a hook fails, the deployment is aborted.
+
+### Database migrations
+
+Always add a `pre_deploy` hook for database migrations. The hook runs **before** new service instances start, ensuring:
+
+- The database schema is updated before new code runs
+- If migrations fail, the deployment is aborted (no broken state)
+- Migrations have access to `DATABASE_URL` and other service env vars
+
+In development, use `specific exec ...` to run migrations/push database changes whenever the schema is changed. Do so automatically unless the user instructs otherwise. For example: `specific exec api -- npm run db:push`.
+
+## Serving static files
+
+To serve static files, run a web server as a dynamic service. For example, using `npx serve`:
+
+```hcl
+build "spa" {
+  base = "node"
+  command = "npm run build"
+}
+
+service "frontend" {
+  build = build.spa
+  command = "npx serve dist -l $PORT"
+
+  endpoint {
+    public = true
+  }
+
+  env = {
+    PORT = port
+  }
+
+  dev {
+    command = "npm run dev"  # Use your framework's dev server
+  }
+}
+```
+
+---
+
+Related topics:
+- Run `specific docs builds` for build configuration
+- Run `specific docs exec` for running one-off commands during development
+- Run `specific docs postgres` for database configuration

package/dist/docs/storage.md

@@ -0,0 +1,62 @@
+# Storage (S3-compatible)
+
+Managed S3-compatible object storage.
+
+```hcl
+storage "uploads" {}
+
+storage "assets" {}
+```
+
+Reference storage attributes in env blocks:
+
+```hcl
+service "api" {
+  build = build.api
+  command = "./api"
+
+  endpoint {
+    public = true
+  }
+
+  env = {
+    S3_ENDPOINT   = storage.uploads.endpoint
+    S3_ACCESS_KEY = storage.uploads.access_key
+    S3_SECRET_KEY = storage.uploads.secret_key
+    S3_BUCKET     = storage.uploads.bucket
+  }
+}
+
+storage "uploads" {}
+```
+
+## Available storage attributes
+
+- `endpoint` - S3-compatible endpoint URL (e.g., `http://127.0.0.1:5000`)
+- `access_key` - Access key for authentication
+- `secret_key` - Secret key for authentication
+- `bucket` - Bucket name
+
+## Example using AWS SDK (JavaScript)
+
+```javascript
+import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
+
+const s3 = new S3Client({
+  endpoint: process.env.S3_ENDPOINT,
+  region: "us-east-1", // Required but ignored locally
+  credentials: {
+    accessKeyId: process.env.S3_ACCESS_KEY,
+    secretAccessKey: process.env.S3_SECRET_KEY,
+  },
+  forcePathStyle: true, // Required for local S3-compatible servers
+});
+
+await s3.send(
+  new PutObjectCommand({
+    Bucket: process.env.S3_BUCKET,
+    Key: "myfile.txt",
+    Body: "Hello, world!",
+  })
+);
+```

package/dist/docs/sync.md

@@ -0,0 +1,66 @@
+# Real-time Sync
+
+For Postgres databases, you can enable real-time data synchronization. This enables building real-time and local-first applications.
+
+Sync is powered by Electric, a sync engine that streams changes from Postgres to clients using a plain HTTP API. It uses a proxy-based architecture where your backend proxies requests after handling authentication and authorization.
+
+## Enabling sync
+
+Reference `sync.url` and `sync.secret` in your service env:
+
+```hcl
+postgres "main" {}
+
+service "api" {
+  command = "node index.js"
+
+  endpoint {
+    public = true
+  }
+
+  env = {
+    DATABASE_URL         = postgres.main.url
+    DATABASE_SYNC_URL    = postgres.main.sync.url
+    DATABASE_SYNC_SECRET = postgres.main.sync.secret
+  }
+}
+```
+
+When these references are present, Specific automatically starts a sync engine connected to your Postgres database during `specific dev`.
+
+## Available sync attributes
+
+- `sync.url` - Sync engine HTTP endpoint URL (e.g., `http://127.0.0.1:5133`)
+- `sync.secret` - Secret for authenticating requests to the sync engine. This should be passed as the `secret` query parameter from the backend to the Electric API.
+
+## How sync works
+
+The sync engine streams "shapes" of data from Postgres to clients:
+
+1. Your backend proxies shape requests to the sync engine (handles auth/authz)
+2. The sync engine streams the initial data and subsequent changes
+3. Clients receive real-time updates over HTTP
+
+For implementation details, see the Electric documentation:
+
+- Authentication and proxying: https://electric-sql.com/docs/guides/auth
+- Shapes and client usage: https://electric-sql.com/docs/guides/shapes
+- Handling writes: https://electric-sql.com/docs/guides/writes
+
+## Using the Electric TypeScript SDK
+
+When using `ShapeStream` from the Electric TypeScript SDK, a full URL is required (not a relative URL). In browsers, derive the full URL from `window.location.origin` instead of using a relative one:
+
+```typescript
+import { ShapeStream } from "@electric-sql/client";
+
+const stream = new ShapeStream({
+  url: `${window.location.origin}/api/sync/items`,
+});
+```
+
+This ensures the client works correctly regardless of the deployment environment.
+
+---
+
+Run `specific docs postgres` for database configuration.

package/dist/lib/dev/database-manager.d.ts

@@ -0,0 +1,17 @@
+import type { Database } from "@specific/config";
+export interface DatabaseInstance {
+    name: string;
+    engine: "postgres" | "redis" | "object_store";
+    port: number;
+    url: string;
+    host: string;
+    user: string;
+    password: string;
+    dbName: string;
+    endpoint?: string;
+    accessKey?: string;
+    secretKey?: string;
+    stop(): Promise<void>;
+}
+export declare function startDatabase(db: Database, port: number, dataDir?: string): Promise<DatabaseInstance>;
+//# sourceMappingURL=database-manager.d.ts.map

package/dist/lib/dev/database-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-manager.d.ts","sourceRoot":"","sources":["../../../src/lib/dev/database-manager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,GAAG,OAAO,GAAG,cAAc,CAAC;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IAEf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,wBAAsB,aAAa,CACjC,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,MAAyB,GACjC,OAAO,CAAC,gBAAgB,CAAC,CAQ3B"}