@specific.dev/cli 0.1.62 → 0.1.64

package/dist/docs/builds.md

@@ -11,11 +11,14 @@ build "api" {
 
 ## Required fields
 
-- `base` - Base environment. Supported: `"node"`, `"python"`, `"go"`, `"rust"`, `"java"`.
+One of the following is required (mutually exclusive):
+
+- `base` - Base environment. Supported: `"node"`, `"python"`, `"go"`, `"rust"`, `"java"`. If another base or customization is needed, use a custom Dockerfile instead.
+- `dockerfile` - Path to a custom Dockerfile, relative to `specific.hcl`. See [Custom Dockerfile](#custom-dockerfile) below.
 
 ## Optional fields
 
-- `command` - Build command to run after dependencies are installed (e.g., `npm run build`, `go build -o api`).
+- `command` - Build command to run after dependencies are installed (e.g., `npm run build`, `go build -o api`). Only valid with `base`, not with `dockerfile`.
 - `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.
@@ -24,17 +27,17 @@ build "api" {
 
 Specific automatically installs dependencies before running your build command. Dependencies are cached in a separate Docker layer for faster builds when only source code changes.
 
-| Base | Detected Files | Install Command |
-|------|----------------|-----------------|
-| `node` | `package-lock.json` | `npm ci` |
-| `node` | `yarn.lock` | `yarn install --frozen-lockfile` |
-| `node` | `pnpm-lock.yaml` | `pnpm install --frozen-lockfile` |
-| `node` | `package.json` only | `npm install` |
-| `python` | `requirements.txt` | `pip install -r requirements.txt` |
-| `python` | `Pipfile.lock` | `pipenv install --deploy --system` |
-| `python` | `poetry.lock` | `poetry install` |
-| `python` | `pyproject.toml` | `pip install .` |
-| `go` | `go.mod` | `go mod download` |
+| Base     | Detected Files      | Install Command                    |
+| -------- | ------------------- | ---------------------------------- |
+| `node`   | `package-lock.json` | `npm ci`                           |
+| `node`   | `yarn.lock`         | `yarn install --frozen-lockfile`   |
+| `node`   | `pnpm-lock.yaml`    | `pnpm install --frozen-lockfile`   |
+| `node`   | `package.json` only | `npm install`                      |
+| `python` | `requirements.txt`  | `pip install -r requirements.txt`  |
+| `python` | `Pipfile.lock`      | `pipenv install --deploy --system` |
+| `python` | `poetry.lock`       | `poetry install`                   |
+| `python` | `pyproject.toml`    | `pip install .`                    |
+| `go`     | `go.mod`            | `go mod download`                  |
 
 For simple projects that only need dependencies installed, you can omit the `command` field:
 
@@ -115,6 +118,49 @@ build "api" {
 }
 ```
 
+## Custom Dockerfile
+
+For full control over the Docker build, provide your own Dockerfile instead of using `base`:
+
+```hcl
+build "api" {
+  dockerfile = "Dockerfile"
+}
+```
+
+When using a custom Dockerfile:
+
+- `command` is not allowed — define build steps in the Dockerfile itself.
+- `context` still controls the Docker build context.
+- `env` vars are passed as Docker build args. Use `ARG` instructions in your Dockerfile to consume them.
+- The service `command` still overrides the container `CMD` at runtime.
+
+### Custom Dockerfile with build args
+
+```hcl
+build "web" {
+  dockerfile = "docker/Dockerfile.prod"
+  context = "."
+
+  env = {
+    NEXT_PUBLIC_API_URL = service.api.public_url
+    NODE_ENV            = "production"
+  }
+}
+```
+
+In the Dockerfile:
+
+```dockerfile
+FROM node:20-slim
+ARG NEXT_PUBLIC_API_URL
+ARG NODE_ENV
+WORKDIR /app
+COPY . .
+RUN npm ci && npm run build
+CMD ["npm", "start"]
+```
+
 ## 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

@@ -23,6 +23,10 @@ A full development environment can be started with `specific dev`. To deploy any
 - [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.
+- [Volumes](/volumes): define persistent storage volumes for services to store files in.
+<!-- beta:temporal -->
+- [Temporal](/temporal): managed durable workflow engine for background tasks, AI agents, cron jobs and more.
+<!-- /beta:temporal -->
 
 ## Common integrations
 

package/dist/docs/integrations/prisma.md

@@ -23,6 +23,7 @@ service "api" {
   env = {
     PORT = port
     DATABASE_URL = postgres.main.url
+    DIRECT_URL   = postgres.main.direct_url
   }
 
   pre_deploy {
@@ -45,8 +46,9 @@ Configure the datasource in `prisma/schema.prisma`:
 
 ```prisma
 datasource db {
-  provider = "postgresql"
-  url      = env("DATABASE_URL")
+  provider  = "postgresql"
+  url       = env("DATABASE_URL")
+  directUrl = env("DIRECT_URL")
 }
 
 generator client {

package/dist/docs/integrations/temporal.md

@@ -1,5 +1,9 @@
 # Temporal
 
+<!-- beta:temporal -->
+> **Beta**: Specific now has built-in Temporal support. See [Temporal](/temporal) for the recommended approach using the `temporal` block. The manual setup below still works but is no longer needed.
+<!-- /beta:temporal -->
+
 Temporal is a durable workflow engine. This guide covers running Temporal locally during development and connecting to Temporal Cloud in production.
 
 Temporal has extensive SDK support across many languages including TypeScript, Python, Go, Java, .NET, and PHP. See the [Temporal documentation](https://docs.temporal.io/) for language-specific guides on implementing workers, workflows, and activities. This document only covers integration with Specific.

package/dist/docs/postgres.md

@@ -33,6 +33,8 @@ postgres "main" {}
 - `user` - Database user
 - `password` - Database password
 - `name` - Database name
+- `direct_url` - Non-pooled connection string, bypassing the connection pooler. Use when you need a direct database connection (e.g., Prisma's `directUrl`).
+- `direct_host` - Non-pooled database host, bypassing the connection pooler.
 
 ## Querying the database
 

package/dist/docs/services.md

@@ -240,6 +240,48 @@ service "worker" {
 }
 ```
 
+## Pre-existing images
+
+Services can use a pre-existing container image instead of a build. This is useful for running third-party services or any pre-built container:
+
+```hcl
+service "redis" {
+  image = "redis:7"
+  command = "redis-server --port $PORT"
+
+  endpoint {}
+
+  env = {
+    PORT = port
+  }
+}
+```
+
+- `image` - Container image reference (e.g., `redis:7`, `ghcr.io/org/image:tag`)
+- `image` and `build` are mutually exclusive — use one or the other
+- Services with `image` skip the build step entirely
+- Deploy hooks (`pre_deploy`, `post_deploy`) work with image-based services
+- Use `dev.command` for local development:
+
+```hcl
+service "redis" {
+  image = "redis:7"
+  command = "redis-server --port $PORT"
+
+  endpoint {}
+
+  env = {
+    PORT = port
+  }
+
+  dev {
+    command = "redis-server --port $PORT"
+  }
+}
+```
+
+You can mix build-based and image-based services in the same project.
+
 ## Environment variables
 
 ```hcl

package/dist/docs/temporal.md

@@ -0,0 +1,98 @@
+<!-- beta:temporal -->
+# Temporal
+
+Define managed Temporal workflow engines for durable workflows, background tasks, AI agents, cron jobs, batch jobs and more.
+
+Temporal has extensive SDK support across many languages including TypeScript, Python, Go, Java, .NET, and PHP. See the [Temporal documentation](https://docs.temporal.io/) for language-specific guides on implementing workers, workflows, and activities. This document only covers integration with Specific.
+
+## Configuration
+
+Define a `temporal` block in `specific.hcl` and reference it from services:
+
+```hcl
+temporal "tasks" {}
+
+build "app" {
+  base = "node"
+}
+
+service "worker" {
+  build   = build.app
+  command = "node worker.js"
+
+  env = {
+    TEMPORAL_ADDRESS   = temporal.tasks.url
+    TEMPORAL_NAMESPACE = temporal.tasks.namespace
+    TEMPORAL_API_KEY   = temporal.tasks.api_key
+  }
+
+  dev {
+    command = "node --watch worker.js"
+  }
+}
+```
+
+## Reference attributes
+
+Each `temporal` block exposes the following reference attributes:
+
+| Attribute | Description | Dev value |
+|-----------|-------------|-----------|
+| `temporal.<name>.url` | gRPC address of the Temporal server | `localhost:<port>` |
+| `temporal.<name>.namespace` | Temporal namespace | `default` |
+| `temporal.<name>.api_key` | API key for authentication | `""` (empty, no auth in dev) |
+
+These attributes can be used in service `env` blocks, both as standalone values and inside interpolated strings.
+
+## Development
+
+Running `specific dev` automatically:
+
+1. Downloads the Temporal CLI (first run only)
+2. Starts a Temporal dev server with persistent storage
+3. Makes the Temporal Web UI available in the admin sidebar under "Workflows"
+
+Workflow data persists across dev server restarts using a SQLite database stored in `.specific/keys/<key>/data/`.
+
+The `api_key` attribute returns an empty string in dev since the Temporal dev server does not require authentication. This is safe because Temporal SDKs conditionally apply authentication based on whether a non-empty key is provided.
+
+## Production
+
+Production Temporal support is not yet available through `temporal` blocks. For production, use configs and secrets to pass Temporal Cloud credentials directly:
+
+```hcl
+temporal "tasks" {}
+
+config "temporal_address" {}
+secret "temporal_api_key" {
+  dev {
+    required = false
+  }
+}
+
+service "worker" {
+  build   = build.app
+  command = "node worker.js"
+
+  env = {
+    # Use built-in temporal block for dev
+    TEMPORAL_NAMESPACE = temporal.tasks.namespace
+
+    # Override address and API key for production via config/secret
+    TEMPORAL_ADDRESS = config.temporal_address
+    TEMPORAL_API_KEY = secret.temporal_api_key
+  }
+
+  dev {
+    command = "node --watch worker.js"
+    env = {
+      # In dev, use the local Temporal server
+      TEMPORAL_ADDRESS = temporal.tasks.url
+      TEMPORAL_API_KEY = temporal.tasks.api_key
+    }
+  }
+}
+```
+
+Set the production values with `specific secrets set` and environment config before deploying.
+<!-- /beta:temporal -->

package/dist/docs/volumes.md

@@ -0,0 +1,63 @@
+# Volumes
+
+Persistent storage volumes for services. Volumes provide a directory that persists across deployments, useful for file uploads, caches, and other data that needs to survive restarts.
+
+Volumes are defined as sub-blocks within a service. Each volume has a name and exposes a `path` attribute that resolves to the directory path.
+
+```hcl
+service "api" {
+  build = build.api
+  command = "node server.js"
+
+  volume "uploads" {}
+
+  env = {
+    UPLOADS_DIR = volume.uploads.path
+  }
+}
+```
+
+## Available volume attributes
+
+- `path` - Absolute path to the volume directory
+
+## How it works
+
+- **In production (Kubernetes):** Each volume creates a PersistentVolumeClaim. The `path` attribute resolves to `/volumes/{name}` inside the container.
+- **In development (`specific dev`):** Each volume maps to a local directory at `.specific/keys/.../data/volumes/{service}/{name}/`. The `path` attribute resolves to this local directory.
+
+Volume data persists across deployments and dev server restarts.
+
+## Multiple volumes
+
+A service can define multiple volumes:
+
+```hcl
+service "api" {
+  build = build.api
+  command = "node server.js"
+
+  volume "uploads" {}
+  volume "cache" {}
+
+  env = {
+    UPLOADS_DIR = volume.uploads.path
+    CACHE_DIR   = volume.cache.path
+  }
+}
+```
+
+## Example usage (Node.js)
+
+```javascript
+import fs from "fs";
+import path from "path";
+
+const uploadsDir = process.env.UPLOADS_DIR;
+
+// Write a file
+fs.writeFileSync(path.join(uploadsDir, "myfile.txt"), "Hello, world!");
+
+// Read it back (persists across restarts)
+const content = fs.readFileSync(path.join(uploadsDir, "myfile.txt"), "utf8");
+```

package/dist/postinstall.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/cli",
-  "version": "0.1.62",
+  "version": "0.1.64",
   "description": "CLI for Specific infrastructure-as-code",
   "type": "module",
   "main": "dist/cli.js",
@@ -35,10 +35,11 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@babel/code-frame": "^7.29.0",
     "chokidar": "^5.0.0",
+    "commander": "^14.0.2",
     "dns2": "^2.1.0",
     "hcl2-json-parser": "^1.0.1",
-    "commander": "^14.0.2",
     "http-proxy": "^1.18.1",
     "ink": "^6.5.1",
     "ink-spinner": "^5.0.0",
@@ -53,6 +54,7 @@
   "devDependencies": {
     "@specific/config": "file:../config",
     "@specific/tunnel-client": "file:../tunnel/client",
+    "@types/babel__code-frame": "^7.27.0",
     "@types/http-proxy": "^1.17.17",
     "@types/node": "^25.0.1",
     "@types/node-forge": "^1.3.11",

package/dist/admin/_next/static/chunks/144304e5f91b7ae5.js

@@ -1 +0,0 @@
-(globalThis.TURBOPACK||(globalThis.TURBOPACK=[])).push(["object"==typeof document?document.currentScript:void 0,12283,e=>{"use strict";var t=e.i(90795),r=e.i(59369);let n=(0,r.createContext)(void 0);function s({children:e}){let[s,a]=(0,r.useState)(null),[o,l]=(0,r.useState)(null),[i,c]=(0,r.useState)(!1),u=(0,r.useMemo)(()=>(function(){let e=window.location.hostname,t=".local.spcf.app";if("local.spcf.app"===e)return"default";if(e.endsWith(t)){let r=e.slice(0,-t.length);if(r&&!r.includes("."))return r}return null})(),[]),m=(0,r.useMemo)(()=>u?"default"===u?"https://__drizzle_gateway.local.spcf.app":`https://__drizzle_gateway.${u}.local.spcf.app`:null,[u]);(0,r.useEffect)(()=>{async function e(){try{let e=await fetch("/api/state");if(!e.ok)throw Error("Failed to fetch state");let t=await e.json();a(t),c(!0),l(null)}catch(e){l(e instanceof Error?e.message:"Unknown error"),c(!1)}}e();let t=setInterval(e,2e3);return()=>clearInterval(t)},[]);let d=s?.resources.some(e=>"postgres"===e.type)??!1,h=s?.projectId??null,f=(0,r.useMemo)(()=>({state:s,error:o,connected:i,instanceKey:u,hasDatabases:d,drizzleGatewayUrl:m,projectId:h}),[s,o,i,u,d,m,h]);return(0,t.jsx)(n.Provider,{value:f,children:e})}function a(){let e=(0,r.useContext)(n);if(void 0===e)throw Error("useDevState must be used within a DevStateProvider");return e}e.s(["DevStateProvider",()=>s,"useDevState",()=>a],12283)},70932,e=>{"use strict";var t=e.i(59369),r=(e,t,r,n,s,a,o,l)=>{let i=document.documentElement,c=["light","dark"];function u(t){var r;(Array.isArray(e)?e:[e]).forEach(e=>{let r="class"===e,n=r&&a?s.map(e=>a[e]||e):s;r?(i.classList.remove(...n),i.classList.add(a&&a[t]?a[t]:t)):i.setAttribute(e,t)}),r=t,l&&c.includes(r)&&(i.style.colorScheme=r)}if(n)u(n);else try{let e=localStorage.getItem(t)||r,n=o&&"system"===e?window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light":e;u(n)}catch(e){}},n=["light","dark"],s="(prefers-color-scheme: dark)",a="u"<typeof window,o=t.createContext(void 0),l={setTheme:e=>{},themes:[]},i=()=>{var e;return null!=(e=t.useContext(o))?e:l},c=e=>t.useContext(o)?t.createElement(t.Fragment,null,e.children):t.createElement(m,{...e}),u=["light","dark"],m=({forcedTheme:e,disableTransitionOnChange:r=!1,enableSystem:a=!0,enableColorScheme:l=!0,storageKey:i="theme",themes:c=u,defaultTheme:m=a?"system":"light",attribute:v="data-theme",value:y,children:g,nonce:w,scriptProps:b})=>{let[S,T]=t.useState(()=>h(i,m)),[E,C]=t.useState(()=>"system"===S?p():S),k=y?Object.values(y):c,P=t.useCallback(e=>{let t=e;if(!t)return;"system"===e&&a&&(t=p());let s=y?y[t]:t,o=r?f(w):null,i=document.documentElement,c=e=>{"class"===e?(i.classList.remove(...k),s&&i.classList.add(s)):e.startsWith("data-")&&(s?i.setAttribute(e,s):i.removeAttribute(e))};if(Array.isArray(v)?v.forEach(c):c(v),l){let e=n.includes(m)?m:null,r=n.includes(t)?t:e;i.style.colorScheme=r}null==o||o()},[w]),A=t.useCallback(e=>{let t="function"==typeof e?e(S):e;T(t);try{localStorage.setItem(i,t)}catch(e){}},[S]),L=t.useCallback(t=>{C(p(t)),"system"===S&&a&&!e&&P("system")},[S,e]);t.useEffect(()=>{let e=window.matchMedia(s);return e.addListener(L),L(e),()=>e.removeListener(L)},[L]),t.useEffect(()=>{let e=e=>{e.key===i&&(e.newValue?T(e.newValue):A(m))};return window.addEventListener("storage",e),()=>window.removeEventListener("storage",e)},[A]),t.useEffect(()=>{P(null!=e?e:S)},[e,S]);let x=t.useMemo(()=>({theme:S,setTheme:A,forcedTheme:e,resolvedTheme:"system"===S?E:S,themes:a?[...c,"system"]:c,systemTheme:a?E:void 0}),[S,A,e,E,a,c]);return t.createElement(o.Provider,{value:x},t.createElement(d,{forcedTheme:e,storageKey:i,attribute:v,enableSystem:a,enableColorScheme:l,defaultTheme:m,value:y,themes:c,nonce:w,scriptProps:b}),g)},d=t.memo(({forcedTheme:e,storageKey:n,attribute:s,enableSystem:a,enableColorScheme:o,defaultTheme:l,value:i,themes:c,nonce:u,scriptProps:m})=>{let d=JSON.stringify([s,n,l,e,c,i,a,o]).slice(1,-1);return t.createElement("script",{...m,suppressHydrationWarning:!0,nonce:"u"<typeof window?u:"",dangerouslySetInnerHTML:{__html:`(${r.toString()})(${d})`}})}),h=(e,t)=>{let r;if(!a){try{r=localStorage.getItem(e)||void 0}catch(e){}return r||t}},f=e=>{let t=document.createElement("style");return e&&t.setAttribute("nonce",e),t.appendChild(document.createTextNode("*,*::before,*::after{-webkit-transition:none!important;-moz-transition:none!important;-o-transition:none!important;-ms-transition:none!important;transition:none!important}")),document.head.appendChild(t),()=>{window.getComputedStyle(document.body),setTimeout(()=>{document.head.removeChild(t)},1)}},p=e=>(e||(e=window.matchMedia(s)),e.matches?"dark":"light");e.s(["ThemeProvider",()=>c,"useTheme",()=>i])},49311,e=>{"use strict";var t=e.i(90795),r=e.i(70932);function n({children:e,...n}){return(0,t.jsx)(r.ThemeProvider,{...n,children:e})}e.s(["ThemeProvider",()=>n])}]);