@specific.dev/cli 0.1.48 → 0.1.49

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/postgres.md

@@ -34,6 +34,21 @@ 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"
+```
+
 ---
 
 Related topics:

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.49",
+      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.49",
   "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",