@specific.dev/cli 0.1.175 → 0.1.176

package/dist/admin/workflows/index.txt

@@ -14,11 +14,11 @@ f:"$Sreact.suspense"
 11:I[15478,["/_next/static/chunks/b2b4aada246f4749.js","/_next/static/chunks/7c2bbd09e9922443.js"],"ViewportBoundary"]
 13:I[15478,["/_next/static/chunks/b2b4aada246f4749.js","/_next/static/chunks/7c2bbd09e9922443.js"],"MetadataBoundary"]
 15:I[47541,[],"default"]
-:HL["/_next/static/chunks/f11bf31415d76903.css","style"]
+:HL["/_next/static/chunks/25ac6c65cd7c74e2.css","style"]
 :HL["/_next/static/media/797e433ab948586e-s.p.29207c2f.woff2","font",{"crossOrigin":"","type":"font/woff2"}]
 :HL["/_next/static/media/83afe278b6a6bb3c-s.p.3a6ba036.woff2","font",{"crossOrigin":"","type":"font/woff2"}]
 :HL["/_next/static/media/caa3a2e1cccd8315-s.p.3b6cae6d.woff2","font",{"crossOrigin":"","type":"font/woff2"}]
-0:{"P":null,"b":"4p_gKX-ebPN5Vy0IhSe2O","c":["","workflows",""],"q":"","i":false,"f":[[["",{"children":["(default)",{"children":["workflows",{"children":["__PAGE__",{}]}]}]},"$undefined","$undefined",true],[["$","$1","c",{"children":[[["$","link","0",{"rel":"stylesheet","href":"/_next/static/chunks/f11bf31415d76903.css","precedence":"next","crossOrigin":"$undefined","nonce":"$undefined"}],["$","script","script-0",{"src":"/_next/static/chunks/c52b2ebc474a0535.js","async":true,"nonce":"$undefined"}]],["$","html",null,{"lang":"en","className":"inter_b2991b2-module__9mH_6q__variable","suppressHydrationWarning":true,"children":["$","body",null,{"className":"geist_a71539c9-module__T19VSG__variable geist_mono_8d43a2aa-module__8Li5zG__variable antialiased","children":["$","$L2",null,{"attribute":"class","defaultTheme":"system","enableSystem":true,"disableTransitionOnChange":true,"children":["$","$L3",null,{"children":["$","$L4",null,{"parallelRouterKey":"children","error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L5",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":[[["$","title",null,{"children":"404: This page could not be found."}],["$","div",null,{"style":{"fontFamily":"system-ui,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif,\"Apple Color Emoji\",\"Segoe UI Emoji\"","height":"100vh","textAlign":"center","display":"flex","flexDirection":"column","alignItems":"center","justifyContent":"center"},"children":["$","div",null,{"children":[["$","style",null,{"dangerouslySetInnerHTML":{"__html":"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}"}}],["$","h1",null,{"className":"next-error-h1","style":{"display":"inline-block","margin":"0 20px 0 0","padding":"0 23px 0 0","fontSize":24,"fontWeight":500,"verticalAlign":"top","lineHeight":"49px"},"children":404}],["$","div",null,{"style":{"display":"inline-block"},"children":["$","h2",null,{"style":{"fontSize":14,"fontWeight":400,"lineHeight":"49px","margin":0},"children":"This page could not be found."}]}]]}]}]],[]],"forbidden":"$undefined","unauthorized":"$undefined"}]}]}]}]}]]}],{"children":[["$","$1","c",{"children":[[["$","script","script-0",{"src":"/_next/static/chunks/21d31e8f6bca9c4d.js","async":true,"nonce":"$undefined"}],["$","script","script-1",{"src":"/_next/static/chunks/b44581875c51fcd8.js","async":true,"nonce":"$undefined"}],["$","script","script-2",{"src":"/_next/static/chunks/65e3cacf9bc29c63.js","async":true,"nonce":"$undefined"}],["$","script","script-3",{"src":"/_next/static/chunks/dc5c264e3262a84a.js","async":true,"nonce":"$undefined"}]],["$","$L6",null,{"children":[["$","$L7",null,{}],["$","$L8",null,{"className":"overflow-hidden","children":["$","$L9",null,{"children":["$","$L4",null,{"parallelRouterKey":"children","error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L5",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":[[["$","title",null,{"children":"404: This page could not be found."}],["$","div",null,{"style":"$0:f:0:1:0:props:children:1:props:children:props:children:props:children:props:children:props:notFound:0:1:props:style","children":["$","div",null,{"children":[["$","style",null,{"dangerouslySetInnerHTML":{"__html":"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}"}}],["$","h1",null,{"className":"next-error-h1","style":"$0:f:0:1:0:props:children:1:props:children:props:children:props:children:props:children:props:notFound:0:1:props:children:props:children:1:props:style","children":404}],["$","div",null,{"style":"$0:f:0:1:0:props:children:1:props:children:props:children:props:children:props:children:props:notFound:0:1:props:children:props:children:2:props:style","children":["$","h2",null,{"style":"$0:f:0:1:0:props:children:1:props:children:props:children:props:children:props:children:props:notFound:0:1:props:children:props:children:2:props:children:props:style","children":"This page could not be found."}]}]]}]}]],[]],"forbidden":"$undefined","unauthorized":"$undefined"}]}]}]]}]]}],{"children":[["$","$1","c",{"children":[null,["$","$L4",null,{"parallelRouterKey":"children","error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L5",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","forbidden":"$undefined","unauthorized":"$undefined"}]]}],{"children":[["$","$1","c",{"children":[["$","$La",null,{"Component":"$b","serverProvidedParams":{"searchParams":{},"params":{},"promises":["$@c","$@d"]}}],[["$","script","script-0",{"src":"/_next/static/chunks/e3baf0c708c5b9ae.js","async":true,"nonce":"$undefined"}]],["$","$Le",null,{"children":["$","$f",null,{"name":"Next.MetadataOutlet","children":"$@10"}]}]]}],{},null,false,false]},null,false,false]},null,false,false]},null,false,false],["$","$1","h",{"children":[null,["$","$L11",null,{"children":"$L12"}],["$","div",null,{"hidden":true,"children":["$","$L13",null,{"children":["$","$f",null,{"name":"Next.Metadata","children":"$L14"}]}]}],["$","meta",null,{"name":"next-size-adjust","content":""}]]}],false]],"m":"$undefined","G":["$15",[]],"S":true}
+0:{"P":null,"b":"6iTWj5ZOTS6kNmEbXOCUs","c":["","workflows",""],"q":"","i":false,"f":[[["",{"children":["(default)",{"children":["workflows",{"children":["__PAGE__",{}]}]}]},"$undefined","$undefined",true],[["$","$1","c",{"children":[[["$","link","0",{"rel":"stylesheet","href":"/_next/static/chunks/25ac6c65cd7c74e2.css","precedence":"next","crossOrigin":"$undefined","nonce":"$undefined"}],["$","script","script-0",{"src":"/_next/static/chunks/c52b2ebc474a0535.js","async":true,"nonce":"$undefined"}]],["$","html",null,{"lang":"en","className":"inter_b2991b2-module__9mH_6q__variable","suppressHydrationWarning":true,"children":["$","body",null,{"className":"geist_a71539c9-module__T19VSG__variable geist_mono_8d43a2aa-module__8Li5zG__variable antialiased","children":["$","$L2",null,{"attribute":"class","defaultTheme":"system","enableSystem":true,"disableTransitionOnChange":true,"children":["$","$L3",null,{"children":["$","$L4",null,{"parallelRouterKey":"children","error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L5",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":[[["$","title",null,{"children":"404: This page could not be found."}],["$","div",null,{"style":{"fontFamily":"system-ui,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif,\"Apple Color Emoji\",\"Segoe UI Emoji\"","height":"100vh","textAlign":"center","display":"flex","flexDirection":"column","alignItems":"center","justifyContent":"center"},"children":["$","div",null,{"children":[["$","style",null,{"dangerouslySetInnerHTML":{"__html":"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}"}}],["$","h1",null,{"className":"next-error-h1","style":{"display":"inline-block","margin":"0 20px 0 0","padding":"0 23px 0 0","fontSize":24,"fontWeight":500,"verticalAlign":"top","lineHeight":"49px"},"children":404}],["$","div",null,{"style":{"display":"inline-block"},"children":["$","h2",null,{"style":{"fontSize":14,"fontWeight":400,"lineHeight":"49px","margin":0},"children":"This page could not be found."}]}]]}]}]],[]],"forbidden":"$undefined","unauthorized":"$undefined"}]}]}]}]}]]}],{"children":[["$","$1","c",{"children":[[["$","script","script-0",{"src":"/_next/static/chunks/21d31e8f6bca9c4d.js","async":true,"nonce":"$undefined"}],["$","script","script-1",{"src":"/_next/static/chunks/b44581875c51fcd8.js","async":true,"nonce":"$undefined"}],["$","script","script-2",{"src":"/_next/static/chunks/65e3cacf9bc29c63.js","async":true,"nonce":"$undefined"}],["$","script","script-3",{"src":"/_next/static/chunks/dc5c264e3262a84a.js","async":true,"nonce":"$undefined"}]],["$","$L6",null,{"children":[["$","$L7",null,{}],["$","$L8",null,{"className":"overflow-hidden","children":["$","$L9",null,{"children":["$","$L4",null,{"parallelRouterKey":"children","error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L5",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":[[["$","title",null,{"children":"404: This page could not be found."}],["$","div",null,{"style":"$0:f:0:1:0:props:children:1:props:children:props:children:props:children:props:children:props:notFound:0:1:props:style","children":["$","div",null,{"children":[["$","style",null,{"dangerouslySetInnerHTML":{"__html":"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}"}}],["$","h1",null,{"className":"next-error-h1","style":"$0:f:0:1:0:props:children:1:props:children:props:children:props:children:props:children:props:notFound:0:1:props:children:props:children:1:props:style","children":404}],["$","div",null,{"style":"$0:f:0:1:0:props:children:1:props:children:props:children:props:children:props:children:props:notFound:0:1:props:children:props:children:2:props:style","children":["$","h2",null,{"style":"$0:f:0:1:0:props:children:1:props:children:props:children:props:children:props:children:props:notFound:0:1:props:children:props:children:2:props:children:props:style","children":"This page could not be found."}]}]]}]}]],[]],"forbidden":"$undefined","unauthorized":"$undefined"}]}]}]]}]]}],{"children":[["$","$1","c",{"children":[null,["$","$L4",null,{"parallelRouterKey":"children","error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L5",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","forbidden":"$undefined","unauthorized":"$undefined"}]]}],{"children":[["$","$1","c",{"children":[["$","$La",null,{"Component":"$b","serverProvidedParams":{"searchParams":{},"params":{},"promises":["$@c","$@d"]}}],[["$","script","script-0",{"src":"/_next/static/chunks/e3baf0c708c5b9ae.js","async":true,"nonce":"$undefined"}]],["$","$Le",null,{"children":["$","$f",null,{"name":"Next.MetadataOutlet","children":"$@10"}]}]]}],{},null,false,false]},null,false,false]},null,false,false]},null,false,false],["$","$1","h",{"children":[null,["$","$L11",null,{"children":"$L12"}],["$","div",null,{"hidden":true,"children":["$","$L13",null,{"children":["$","$f",null,{"name":"Next.Metadata","children":"$L14"}]}]}],["$","meta",null,{"name":"next-size-adjust","content":""}]]}],false]],"m":"$undefined","G":["$15",[]],"S":true}
 c:{}
 d:"$0:f:0:1:1:children:1:children:1:children:0:props:children:0:props:serverProvidedParams:params"
 12:[["$","meta","0",{"charSet":"utf-8"}],["$","meta","1",{"name":"viewport","content":"width=device-width, initial-scale=1"}]]

package/dist/cli.js

@@ -368588,8 +368588,19 @@ function parseVolumes(fieldObj) {
     return volumes;
   }
   if (!Array.isArray(volumeData)) {
-    for (const [name] of Object.entries(volumeData)) {
-      volumes.push({ name });
+    for (const [name, fieldsArray] of Object.entries(volumeData)) {
+      const volume = { name };
+      const fields = Array.isArray(fieldsArray) ? fieldsArray[0] : fieldsArray;
+      if (fields && typeof fields === "object" && !Array.isArray(fields)) {
+        const resetCommand = fields.reset_command;
+        if (resetCommand !== void 0) {
+          if (typeof resetCommand !== "string" || resetCommand.trim() === "") {
+            throw new Error(`Volume "${name}" has an invalid "reset_command" value. Must be a non-empty string.`);
+          }
+          volume.reset_command = resetCommand;
+        }
+      }
+      volumes.push(volume);
     }
   }
   return volumes;
@@ -374729,7 +374740,7 @@ function trackEvent(event, properties) {
     event,
     properties: {
       ...properties,
-      cli_version: "0.1.175",
+      cli_version: "0.1.176",
       platform: process.platform,
       node_version: process.version,
       project_id: getProjectId()
@@ -375591,8 +375602,19 @@ function parseVolumes2(fieldObj) {
     return volumes;
   }
   if (!Array.isArray(volumeData)) {
-    for (const [name] of Object.entries(volumeData)) {
-      volumes.push({ name });
+    for (const [name, fieldsArray] of Object.entries(volumeData)) {
+      const volume = { name };
+      const fields = Array.isArray(fieldsArray) ? fieldsArray[0] : fieldsArray;
+      if (fields && typeof fields === "object" && !Array.isArray(fields)) {
+        const resetCommand = fields.reset_command;
+        if (resetCommand !== void 0) {
+          if (typeof resetCommand !== "string" || resetCommand.trim() === "") {
+            throw new Error(`Volume "${name}" has an invalid "reset_command" value. Must be a non-empty string.`);
+          }
+          volume.reset_command = resetCommand;
+        }
+      }
+      volumes.push(volume);
     }
   }
   return volumes;
@@ -376898,6 +376920,7 @@ function formatErrorCode(code) {
     deploy_failed: "Service failed to deploy",
     health_check_failed: "Health check failed",
     post_deploy_failed: "Post-deploy hook failed",
+    volume_reset_failed: "Volume reset failed",
     internal_error: "Internal error"
   };
   return labels[code] || code;
@@ -379092,7 +379115,7 @@ function compareVersions(a, b) {
   return 0;
 }
 async function checkForUpdate() {
-  const currentVersion = "0.1.175";
+  const currentVersion = "0.1.176";
   const response = await fetch(`${BINARIES_BASE_URL}/latest?t=${Date.now()}`);
   if (!response.ok) {
     throw new Error(`Failed to check for updates: HTTP ${response.status}`);
@@ -379772,7 +379795,7 @@ async function domainAddCommand(service, domain, options2) {
 var program = new Command();
 var env = "production";
 var envLabel = env !== "production" ? `[${env.toUpperCase()}] ` : "";
-program.name("specific").description(`${envLabel}Infrastructure-as-code for coding agents`).version("0.1.175").enablePositionalOptions();
+program.name("specific").description(`${envLabel}Infrastructure-as-code for coding agents`).version("0.1.176").enablePositionalOptions();
 program.command("init").description("Initialize project for use with a coding agent").option("--agent <name...>", "Agents to configure (cursor, claude, codex, other)").addHelpText("after", `
 Examples:
   $ specific init

package/dist/docs/index.md

@@ -28,6 +28,7 @@ After deploying, the user can manage their project from the Specific Dashboard a
 - [Volumes](/volumes): define persistent storage volumes for services to store files in.
 - [Temporal](/temporal): managed durable workflow engine for background tasks, AI agents and more.
 - [Observability](/observability): query logs and metrics from running environments using `specific query` for debugging and analytics.
+- [Preview environments](/previews): ephemeral copies of an environment created per pull request, with the parent's databases branched, object storage forked, and volumes cloned. Covers resetting cloned volume state for stateful services.
 <!-- beta:mail -->
 - [Mail](/mail): managed email sending via SMTP for transactional emails.
 <!-- /beta:mail -->

package/dist/docs/previews.md

@@ -0,0 +1,57 @@
+# Preview Environments
+
+A preview environment is a temporary, fully isolated copy of an existing environment. It runs the same services with their own URLs and their own network namespace, on top of its own copy of the parent's stateful data — so a change can be tested end to end without touching the parent.
+
+## How previews are created
+
+- **Per pull request** — with the GitHub integration connected, Specific creates a preview environment for each open pull request, keeps it up to date as new commits are pushed, and posts its URL back on the PR.
+- **Manually** — previews can also be created on demand.
+
+Preview environments are ephemeral: pull-request previews are removed when the PR is closed or merged, and a preview can be given an expiry, after which Specific cleans it up automatically.
+
+Run `specific status` to list every environment and its `env_…` ID, including preview environments. Target a preview with `--environment` on commands that take one (see `specific docs observability`).
+
+## What's copied from the parent
+
+A preview branches off a parent environment and starts from its data. Each resource is forked in the way that's fastest for that service:
+
+- **Postgres** databases are branched (an instant, copy-on-write branch).
+- **Object storage** buckets are forked.
+- **Volumes** are cloned — a byte-for-byte copy of the parent volume's contents.
+
+The preview gets its own isolated database, buckets, and volumes; writing to them never affects the parent.
+
+## Volumes in previews
+
+Because a volume is copied byte for byte, a preview's service starts on an exact replica of the parent's on-disk data. For most volumes (uploads, caches, plain database files) that is exactly what you want, and no extra configuration is needed.
+
+But some stateful services store their **node or cluster identity inside the volume**, and a cloned instance that inherits the parent's identity can fail to start. The clearest example is **Typesense**, which keeps its raft consensus state — its node identity and peer list — under `state/` in the data directory. On a clone, the new node finds a cluster configuration that belongs to the parent and can't elect itself, so it crash-loops.
+
+For services like this, set `reset_command` on the volume. Specific runs it **once** against the freshly cloned volume — before the service starts, in the service's image, with the volume mounted at `/volumes/<name>` — so the service can scrub state that must not be inherited:
+
+```hcl
+service "search" {
+  image   = "typesense/typesense:30.1"
+  command = "typesense-server --data-dir=/volumes/data --api-port=$PORT --api-address=0.0.0.0"
+
+  volume "data" {
+    reset_command = "rm -rf /volumes/data/state"
+  }
+
+  env = {
+    PORT = port
+  }
+}
+```
+
+- It runs **only** on cloned volumes in preview environments — never in production, and never on a freshly provisioned volume.
+- A non-zero exit fails the deploy, so a botched reset never starts the service on bad data.
+- Most services need no `reset_command` — reach for it only when a service stores node or cluster identity inside its volume.
+
+---
+
+Related topics:
+
+- Run `specific docs volumes` for declaring persistent volumes
+- Run `specific docs services` for service configuration
+- Run `specific docs observability` for querying a preview's logs and metrics

package/dist/docs/services.md

@@ -560,3 +560,5 @@ Related topics:
 - Run `specific docs crons` for scheduled jobs (a service that runs on a schedule)
 - Run `specific docs exec` for running one-off commands during development
 - Run `specific docs postgres` for database configuration
+- Run `specific docs volumes` for persistent storage volumes
+- Run `specific docs previews` for preview environments (and resetting cloned volume state)

package/dist/docs/volumes.md

@@ -61,3 +61,30 @@ 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");
 ```
+
+## Preview environments
+
+Preview environments clone each volume's contents byte for byte from the parent environment. For most volumes (uploads, caches, plain database files) that's exactly what you want, and no extra configuration is needed.
+
+Some stateful services store node or cluster identity inside the volume and crash-loop when a clone inherits the parent's identity — for example Typesense keeps its raft consensus state under `state/`. For those, set `reset_command` on the volume to scrub that state once, on the freshly cloned volume, before the service starts in a preview:
+
+```hcl
+service "search" {
+  image   = "typesense/typesense:30.1"
+  command = "typesense-server --data-dir=/volumes/data --api-port=$PORT --api-address=0.0.0.0"
+
+  volume "data" {
+    reset_command = "rm -rf /volumes/data/state"
+  }
+
+  env = {
+    PORT = port
+  }
+}
+```
+
+- It runs **only** on cloned volumes in preview environments — never in production, and never on a freshly provisioned volume.
+- A non-zero exit fails the deploy.
+- Most services need no `reset_command` — reach for it only when a service stores node or cluster identity inside its volume.
+
+See `specific docs previews` for how preview environments work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/cli",
-  "version": "0.1.175",
+  "version": "0.1.176",
   "description": "CLI for Specific infrastructure-as-code",
   "type": "module",
   "main": "dist/cli.js",