@tdk-landscape/tdk-cli-core 1.3.91 → 1.3.92

package/cli/dist/utils/env-validator.js

@@ -5,7 +5,8 @@ const REQUIRED_ENV_VARS = [
     {
         name: "VERDACCIO_URL_DOCKER",
         description: "Docker-internal URL of the private npm registry (Verdaccio, a paid feature)",
-        required: true,
+        // Verdaccio is a premium, off-by-default service, so a free project must not need its URL.
+        required: false,
         default: "http://verdaccio:4873",
         example: "http://verdaccio:4873",
     },
@@ -21,12 +22,13 @@ const REQUIRED_ENV_VARS = [
         required: true,
         default: "dev",
         example: "dev",
+        complete: true,
     },
     {
         name: "DATABASE_URL",
-        description: "PostgreSQL connection string",
+        description: "PostgreSQL connection string (uses the generated DB_PASSWORD below)",
         required: false,
-        default: "postgresql://postgres:postgres@postgres:5432/app_dev",
+        // Built from DB_PASSWORD in generateEnvFile(); there is no shared literal password.
     },
     {
         name: "DB_PASSWORD",
@@ -36,34 +38,88 @@ const REQUIRED_ENV_VARS = [
         // credential leak waiting to happen. generateEnvFile() fills this one in with
         // a fresh random value per project instead.
         example: "postgres",
+        complete: true,
+    },
+    {
+        name: "JWT_SECRET",
+        description: "Secret that signs local-jwt tokens (generated once per project; never shared between projects)",
+        // Not required for `tdk doctor`: `tdk up` adds it to an older project's .env before starting anything.
+        required: false,
+        complete: true,
     },
 ];
-function generateDbPassword() {
-    return randomBytes(16).toString("hex");
+const generateDbPassword = () => randomBytes(16).toString("hex");
+const generateJwtSecret = () => randomBytes(32).toString("hex");
+function generatedValue(name, password) {
+    if (name === "DB_PASSWORD")
+        return password;
+    if (name === "JWT_SECRET")
+        return generateJwtSecret();
+    if (name === "DATABASE_URL")
+        return `postgresql://postgres:${password}@postgres:5432/app_dev`;
+    return REQUIRED_ENV_VARS.find((v) => v.name === name)?.default ?? "";
+}
+/** Strips one layer of matching quotes, like a dotenv parser would. */
+function unquote(raw) {
+    const value = raw.trim();
+    if (value.length >= 2) {
+        const first = value[0];
+        if ((first === '"' || first === "'") && value[value.length - 1] === first) {
+            return value.slice(1, -1);
+        }
+    }
+    return value;
+}
+/** Parses the assignments in a dotenv file: `NAME=value` and `export NAME=value`, ignoring comments and blank lines. */
+export function parseEnv(content) {
+    const result = new Map();
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const assignment = line.startsWith("export ") ? line.slice("export ".length).trim() : line;
+        const equals = assignment.indexOf("=");
+        if (equals <= 0)
+            continue;
+        const name = assignment.slice(0, equals).trim();
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+            continue;
+        result.set(name, unquote(assignment.slice(equals + 1)));
+    }
+    return result;
 }
-export function generateEnvFile(_projectRoot) {
+function describe(envVar) {
+    const lines = [`# ${envVar.description}`];
+    if (envVar.required)
+        lines.push("# Required (the value below is a working default)");
+    if (envVar.example)
+        lines.push(`# Example: ${envVar.example}`);
+    return lines;
+}
+export function generateEnvFile() {
+    const password = generateDbPassword();
     const lines = [
         "# 🔧 TDK Environment Configuration",
         "# Generated by `tdk project`. The defaults work as-is; edit only to change them.",
-        "# Keep this file out of git (it holds a generated database password).",
+        "# Keep this file out of git: it holds a generated database password and JWT secret.",
         "#",
         "# After editing, run: tdk config regenerate && tdk up",
         "",
     ];
     for (const envVar of REQUIRED_ENV_VARS) {
-        lines.push(`# ${envVar.description}`);
-        if (envVar.required) {
-            lines.push("# Required (the value below is a working default)");
-        }
-        if (envVar.example) {
-            lines.push(`# Example: ${envVar.example}`);
-        }
-        const value = envVar.name === "DB_PASSWORD" ? generateDbPassword() : envVar.default || "";
-        lines.push(`${envVar.name}=${value}`);
+        lines.push(...describe(envVar));
+        lines.push(`${envVar.name}=${generatedValue(envVar.name, password)}`);
         lines.push("");
     }
     return lines.join("\n");
 }
+/** The password a postgres-style URL carries, or undefined when there is none or it is a variable reference. */
+function urlPassword(url) {
+    const match = url.match(/^[a-z][a-z0-9+.-]*:\/\/[^:/@\s]+:([^@\s]*)@/i);
+    if (!match || match[1].includes("$"))
+        return undefined;
+    return match[1];
+}
 export function validateEnvFile(projectRoot) {
     const envPath = join(projectRoot, ".env");
     const result = {
@@ -78,30 +134,62 @@ export function validateEnvFile(projectRoot) {
             warnings: [".env file not found - will be auto-generated"],
         };
     }
-    const envContent = readFileSync(envPath, "utf-8");
-    const envVars = new Set(envContent
-        .split("\n")
-        .filter((line) => !line.startsWith("#") && line.includes("="))
-        .map((line) => line.split("=")[0])
-        .filter((name) => name.length > 0));
+    const env = parseEnv(readFileSync(envPath, "utf-8"));
     for (const envVar of REQUIRED_ENV_VARS) {
-        if (envVar.required && !envVars.has(envVar.name)) {
+        if (envVar.required && !env.has(envVar.name)) {
             result.missing.push(envVar.name);
         }
-        if (envVars.has(envVar.name)) {
-            const match = envContent.match(new RegExp(`^${envVar.name}=(.*)$`, "m"));
-            const value = match ? match[1] : "";
-            if (!value.trim()) {
-                result.invalid.push(`${envVar.name} is set but empty`);
-            }
+        if (env.has(envVar.name) && !(env.get(envVar.name) ?? "").trim()) {
+            result.invalid.push(`${envVar.name} is set but empty`);
+        }
+    }
+    const databaseUrl = env.get("DATABASE_URL");
+    const dbPassword = env.get("DB_PASSWORD");
+    if (databaseUrl && dbPassword) {
+        const inUrl = urlPassword(databaseUrl);
+        if (inUrl !== undefined && inUrl !== dbPassword) {
+            result.warnings.push("DATABASE_URL carries a different password than DB_PASSWORD; the database container uses DB_PASSWORD");
         }
     }
     return result;
 }
+/**
+ * Appends the keys a newer CLI expects to an existing .env, without touching or rotating anything already there (an existing
+ * DB_PASSWORD must survive, or the database volume stops accepting it). Creates the file when it is missing.
+ *
+ * @returns the names that were added, empty when the file was already complete
+ */
+export function completeEnvFile(projectRoot) {
+    const envPath = join(projectRoot, ".env");
+    if (!existsSync(envPath)) {
+        writeFileSync(envPath, generateEnvFile(), { mode: 0o600 });
+        return REQUIRED_ENV_VARS.map((v) => v.name);
+    }
+    const existing = readFileSync(envPath, "utf-8");
+    const env = parseEnv(existing);
+    const toAdd = REQUIRED_ENV_VARS.filter((v) => v.complete && !env.has(v.name));
+    if (toAdd.length === 0)
+        return [];
+    // Anything generated from the password must use the project's existing one.
+    const password = env.get("DB_PASSWORD") || generateDbPassword();
+    const lines = [
+        "",
+        "# Added by TDK: keys this version expects. Existing values above were not changed.",
+        "",
+    ];
+    for (const envVar of toAdd) {
+        lines.push(...describe(envVar));
+        lines.push(`${envVar.name}=${generatedValue(envVar.name, password)}`);
+        lines.push("");
+    }
+    const separator = existing.endsWith("\n") ? "" : "\n";
+    writeFileSync(envPath, `${existing}${separator}${lines.join("\n")}`);
+    return toAdd.map((v) => v.name);
+}
 export function ensureEnvFile(projectRoot) {
     const envPath = join(projectRoot, ".env");
     if (!existsSync(envPath)) {
-        writeFileSync(envPath, generateEnvFile(projectRoot));
+        writeFileSync(envPath, generateEnvFile(), { mode: 0o600 });
         return true;
     }
     return false;

package/cli/dist/utils/resource-kind.js

@@ -0,0 +1,8 @@
+/**
+ * True for a resource that runs as an HTTP API service behind the Traefik API host: a backend, or an `mcp` server (a Model Context
+ * Protocol endpoint, which the engine builds, routes and health-checks exactly like a backend).
+ */
+export function isApiServiceType(appType) {
+    return appType === "backend" || appType === "mcp";
+}
+//# sourceMappingURL=resource-kind.js.map

package/cli/dist/utils/service-manifest.js

@@ -1,6 +1,16 @@
 import { existsSync, readFileSync } from "node:fs";
+import { validateSmoke } from "./smoke.js";
 export const SERVICE_MANIFEST_SCHEMA_VERSION = 1;
 export const SERVICE_MANIFEST_SCHEMA_URL = "https://tdk-landscape.github.io/schema.service.json";
+/**
+ * Fields that are still read, or still tolerated, but should not be used. The warning says what replaces each one. `jwtSecret` is
+ * ignored outright: a secret must not be committed (see docs/environment.md).
+ */
+const DEPRECATED_FIELDS = {
+    dependencies: "deprecated, use dependsOn (still read for now)",
+    envVars: "deprecated, use params (still read when params is absent)",
+    jwtSecret: "ignored. A secret must not be committed: remove it and set JWT_SECRET in the project .env",
+};
 const KNOWN_SERVICE_FIELDS = new Set([
     "$schema",
     "apiBasePath",
@@ -32,6 +42,7 @@ const KNOWN_SERVICE_FIELDS = new Set([
     "sablier",
     "schemaVersion",
     "secrets",
+    "smoke",
     "stack",
     "syncs",
     "traefik",
@@ -55,9 +66,18 @@ export function validateServiceManifest(value, displayPath) {
     if ("schemaVersion" in manifest && manifest.schemaVersion !== SERVICE_MANIFEST_SCHEMA_VERSION) {
         errors.push(`${displayPath}.schemaVersion: unsupported version ${String(manifest.schemaVersion)} (supported: ${SERVICE_MANIFEST_SCHEMA_VERSION})`);
     }
-    const warnings = Object.keys(manifest)
-        .filter((field) => !KNOWN_SERVICE_FIELDS.has(field))
-        .map((field) => `${displayPath}.${field}: unknown field is preserved`);
+    if ("smoke" in manifest) {
+        for (const message of validateSmoke(manifest.smoke))
+            errors.push(`${displayPath}.${message}`);
+    }
+    const warnings = Object.keys(manifest).flatMap((field) => {
+        const deprecation = DEPRECATED_FIELDS[field];
+        if (deprecation)
+            return [`${displayPath}.${field}: ${deprecation}`];
+        if (!KNOWN_SERVICE_FIELDS.has(field))
+            return [`${displayPath}.${field}: unknown field is preserved`];
+        return [];
+    });
     return { errors, warnings, manifest };
 }
 export function validateServiceManifestFile(filePath, displayPath) {

package/cli/dist/utils/service-urls.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { findProjectRoot } from "./paths.js";
+import { isApiServiceType } from "./resource-kind.js";
 export function getProjectName() {
     const root = findProjectRoot();
     if (root) {
@@ -47,7 +48,7 @@ export function appendHealthPath(path) {
 }
 /** The route `tdk up` advertises for a service, without the /health suffix. */
 export function resolveServicePath(resource) {
-    if (resource.config?.appType === "backend") {
+    if (isApiServiceType(resource.config?.appType)) {
         const servicePathName = resource.name.replace(/-api$/, "");
         return resource.config?.apiPath ?? `/api/${servicePathName}`;
     }
@@ -61,9 +62,9 @@ export function resolveServicePath(resource) {
 export function buildHealthTargets(resources, ingressPort) {
     const { appBase, apiBase } = resolveSubdomainBases(ingressPort);
     return resources
-        .filter((resource) => resource.config?.appType === "frontend" || resource.config?.appType === "backend")
+        .filter((resource) => resource.config?.appType === "frontend" || isApiServiceType(resource.config?.appType))
         .map((resource) => {
-        const base = resource.config.appType === "backend" ? apiBase : appBase;
+        const base = isApiServiceType(resource.config.appType) ? apiBase : appBase;
         return {
             name: resource.name,
             appType: resource.config.appType,

package/cli/dist/utils/services.js

@@ -50,7 +50,8 @@ function parseResource(serviceJsonPath) {
     }
     const parsedConfig = parsed;
     for (const warning of validateServiceManifest(parsed, serviceJsonPath).warnings) {
-        console.warn(`⚠️  Unknown service.json field: ${warning}`);
+        // The warning names the file and field and says what is wrong (unknown, deprecated, ignored), so do not prefix it.
+        console.warn(`⚠️  ${warning}`);
     }
     const config = {
         ...parsedConfig,

package/cli/dist/utils/smoke.js

@@ -0,0 +1,225 @@
+import { isApiServiceType } from "./resource-kind.js";
+import { resolveServicePath, resolveSubdomainBases } from "./service-urls.js";
+export const DEFAULT_SMOKE_TIMEOUT_SECONDS = 60;
+const RETRY_DELAY_MS = 1000;
+const REQUEST_TIMEOUT_MS = 10_000;
+const BODY_SNIPPET_CHARS = 200;
+/** Statuses a proxy answers while a route or its upstream is not up yet. Anything else is the service's real answer. */
+const NOT_READY_STATUSES = new Set([404, 502, 503, 504]);
+/** Error codes that prove the request never left this machine, so repeating even a write is safe. */
+const PRE_SEND_ERROR_CODES = new Set([
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+]);
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A thrown request error is retried for safe methods, and for others only when its code shows the request was never sent. */
+function shouldRetryRequestError(err, method) {
+    if (SAFE_METHODS.has(method))
+        return true;
+    if (!isRecord(err))
+        return false;
+    const cause = isRecord(err.cause) ? err.cause : undefined;
+    const code = err.code ?? cause?.code;
+    return typeof code === "string" && PRE_SEND_ERROR_CODES.has(code);
+}
+export function validateSmoke(smoke) {
+    if (!isRecord(smoke))
+        return ['smoke: must be an object with "via" and "steps"'];
+    const errors = [];
+    if (smoke.via !== "proxy") {
+        errors.push('smoke.via: only "proxy" is supported (the check must go through the public URL)');
+    }
+    if (smoke.timeoutSeconds !== undefined &&
+        !(typeof smoke.timeoutSeconds === "number" && smoke.timeoutSeconds > 0)) {
+        errors.push("smoke.timeoutSeconds: must be a number greater than 0");
+    }
+    if (!Array.isArray(smoke.steps) || smoke.steps.length === 0) {
+        errors.push("smoke.steps: needs at least one step");
+        return errors;
+    }
+    smoke.steps.forEach((step, index) => {
+        const at = `smoke.steps[${index}]`;
+        if (!isRecord(step)) {
+            errors.push(`${at}: must be an object`);
+            return;
+        }
+        const path = step.path;
+        if (typeof path !== "string" || !path.startsWith("/") || path.startsWith("//")) {
+            errors.push(`${at}.path: must start with "/" and is appended to the public URL; a full URL or relative path would skip the proxy`);
+        }
+        if (step.expect !== undefined &&
+            !(typeof step.expect === "number" &&
+                Number.isInteger(step.expect) &&
+                step.expect >= 100 &&
+                step.expect <= 599)) {
+            errors.push(`${at}.expect: must be an HTTP status between 100 and 599`);
+        }
+        if (step.bodyContains !== undefined && typeof step.bodyContains !== "string") {
+            errors.push(`${at}.bodyContains: must be a string`);
+        }
+        if (step.save !== undefined) {
+            const ok = isRecord(step.save) &&
+                Object.values(step.save).every((v) => typeof v === "string" && v.startsWith("$."));
+            if (!ok)
+                errors.push(`${at}.save: must map names to paths such as "$.id"`);
+        }
+    });
+    return errors;
+}
+/** One plan per routable service that declares `smoke`. Workers and BYO with exposeViaProxy false have no public route. */
+export function buildSmokePlans(resources, ingressPort) {
+    const { appBase, apiBase } = resolveSubdomainBases(ingressPort);
+    const plans = [];
+    for (const resource of resources) {
+        const config = resource.config;
+        if (!config?.smoke)
+            continue;
+        const appType = config.appType;
+        const isApi = isApiServiceType(appType) || appType === "bring-your-own";
+        if (!isApi && appType !== "frontend")
+            continue;
+        if (config.exposeViaProxy === false)
+            continue;
+        const base = isApi ? apiBase : appBase;
+        plans.push({
+            name: resource.name,
+            baseUrl: `${base}${resolveServicePath(resource).replace(/\/+$/, "")}`,
+            smoke: config.smoke,
+        });
+    }
+    return plans;
+}
+function readPath(value, path) {
+    const parts = path.replace(/^\$\.?/, "").match(/[^.[\]]+/g) ?? [];
+    let current = value;
+    for (const part of parts) {
+        if (current === null || current === undefined)
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+function fill(template, saved) {
+    return template.replace(/\{\{(\w+)\}\}/g, (match, key) => saved[key] ?? match);
+}
+function fillBody(body, saved) {
+    if (typeof body === "string")
+        return fill(body, saved);
+    if (Array.isArray(body))
+        return body.map((item) => fillBody(item, saved));
+    if (isRecord(body)) {
+        return Object.fromEntries(Object.entries(body).map(([k, v]) => [k, fillBody(v, saved)]));
+    }
+    return body;
+}
+function snippet(text) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > BODY_SNIPPET_CHARS ? `${flat.slice(0, BODY_SNIPPET_CHARS)}...` : flat;
+}
+/** Runs the steps in order. A not-ready answer (connection error, 404, 502-504) is retried until the timeout; a real wrong answer fails at once. */
+export async function runSmokePlan(plan, deps = {}) {
+    const doFetch = deps.fetch ?? ((url, init) => fetch(url, init));
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const deadline = now() + (plan.smoke.timeoutSeconds ?? DEFAULT_SMOKE_TIMEOUT_SECONDS) * 1000;
+    const saved = {};
+    // A manifest with errors is still loaded, so a malformed block must fail the check, not throw out of `tdk up`.
+    const invalid = validateSmoke(plan.smoke);
+    if (invalid.length > 0) {
+        return {
+            name: plan.name,
+            ok: false,
+            failure: `${plan.name}: invalid smoke block: ${invalid.join("; ")}`,
+        };
+    }
+    for (const [index, step] of plan.smoke.steps.entries()) {
+        const label = step.name ?? `step ${index + 1}`;
+        const method = (step.method ?? "GET").toUpperCase();
+        const url = `${plan.baseUrl}${fill(step.path, saved)}`;
+        const expected = step.expect ?? 200;
+        const hasBody = step.body !== undefined;
+        let status;
+        let text = "";
+        let error;
+        for (;;) {
+            error = undefined;
+            status = undefined;
+            let retryableError = false;
+            try {
+                const response = await doFetch(url, {
+                    method,
+                    headers: hasBody ? { "content-type": "application/json" } : undefined,
+                    body: hasBody ? JSON.stringify(fillBody(step.body, saved)) : undefined,
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                });
+                status = response.status;
+                text = await response.text();
+            }
+            catch (err) {
+                retryableError = shouldRetryRequestError(err, method);
+                error = err instanceof Error ? err.message : String(err);
+            }
+            const notReady = (error !== undefined && retryableError) ||
+                (status !== undefined && status !== expected && NOT_READY_STATUSES.has(status));
+            if (!notReady || now() >= deadline)
+                break;
+            await sleep(RETRY_DELAY_MS);
+        }
+        const where = `${plan.name}: ${label}: ${method} ${url}`;
+        if (error !== undefined)
+            return { name: plan.name, ok: false, failure: `${where} never answered (${error})` };
+        if (status !== expected) {
+            return {
+                name: plan.name,
+                ok: false,
+                failure: `${where} returned ${status}, expected ${expected}${text ? `: ${snippet(text)}` : ""}`,
+            };
+        }
+        if (step.bodyContains !== undefined && !text.includes(step.bodyContains)) {
+            return {
+                name: plan.name,
+                ok: false,
+                failure: `${where} returned ${status} but the body does not contain "${step.bodyContains}": ${snippet(text)}`,
+            };
+        }
+        if (step.save) {
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                return {
+                    name: plan.name,
+                    ok: false,
+                    failure: `${where} returned a body that is not JSON, cannot save: ${snippet(text)}`,
+                };
+            }
+            for (const [key, path] of Object.entries(step.save)) {
+                const value = readPath(parsed, path);
+                if (value === undefined || value === null || typeof value === "object") {
+                    return {
+                        name: plan.name,
+                        ok: false,
+                        failure: `${where} response has no ${path} to save as {{${key}}}: ${snippet(text)}`,
+                    };
+                }
+                saved[key] = String(value);
+            }
+        }
+    }
+    return { name: plan.name, ok: true };
+}
+export function formatSmokeFailure(result) {
+    return `Smoke check failed: ${result.failure}`;
+}
+/** Runs every plan side by side; each plan keeps its own timeout. */
+export async function runSmokePlans(plans, deps = {}) {
+    return Promise.all(plans.map((plan) => runSmokePlan(plan, deps)));
+}
+//# sourceMappingURL=smoke.js.map

package/cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tdk-cli-internal",
   "private": true,
-  "version": "1.3.91",
+  "version": "1.3.92",
   "description": "TDK CLI — start services on your laptop.",
   "keywords": [
     "tdk",