@tdk-landscape/tdk-cli-core 1.3.55 → 1.3.56

package/CHANGELOG.md

@@ -4,6 +4,11 @@ Notable changes to the `tdk` CLI. Versions match [npm](https://www.npmjs.com/pac
 
 ## Unreleased
 
+- `tdk project` adds `.env`, `.tdk/.tdk-out/`, `.tdk/.project-id` and `node_modules/` to `.gitignore`. `.env` holds a generated database password and was easy to commit by accident.
+- `tdk doctor` checks that host ports 80, 443 and 5432 are free and names what holds them (usually a local Postgres). `tdk up` prints the same warning before starting Tilt.
+- `tdk project` no longer tells you to edit `.env` first: the defaults work, and the Verdaccio variables are marked as belonging to the paid registry.
+## 1.3.55 (2026-09-27)
+
 - Dropped the `ora` dependency (only `tdk upgrade` used it) in favor of a small built-in spinner: 50 installed packages instead of 61, and no more duplicate versions of cli-cursor, restore-cursor, onetime and signal-exit.
 - `tdk doctor` outside a project checks only Docker, Compose and Tilt, and reports "This machine is ready for TDK". Before, running it right after installing (as the installer suggests) failed with "Master configs missing … Environment not ready".
 

package/README.md

@@ -26,7 +26,7 @@ tdk up shop                                             # run it with hot reload
 
 ![tdk scaffolding a backend and a frontend, then listing the stack](docs/demo.svg)
 
-**Requirements:** Docker (Desktop, OrbStack or Colima; Engine 25+, Compose 2.20+), [Tilt](https://docs.tilt.dev/install.html), [Bun](https://bun.sh) for the generated services, and Node.js 22.12+ for the CLI. macOS and Linux are supported. Windows is untested (WSL2 may work). Run `tdk doctor` to check all of it.
+**Requirements:** Docker (Desktop, OrbStack or Colima; Engine 25+, Compose 2.20+), [Tilt](https://docs.tilt.dev/install.html), [Bun](https://bun.sh) for the generated services, and Node.js 22.12+ for the CLI. Ports 80, 443 and 5432 must be free (a local Postgres is the usual conflict). macOS and Linux are supported. Windows is untested (WSL2 may work). Run `tdk doctor` to check all of it.
 
 This is the core monorepo for TDK: the `tdk` CLI, the Starlark-based Tilt orchestration engine that powers it, and the discovery system that turns a directory of services into a running local landscape.
 
@@ -144,6 +144,7 @@ TDK has no telemetry or analytics. The CLI only goes online when you ask it to:
 - `tdk upgrade` checks the latest release on GitHub.
 - With `TDK_LICENSE_KEY` set, `tdk project` and `tdk up` download the paid bundle from `tdk-extension-dist.oranguman.workers.dev` and re-check the key every 12 hours. Without a key, nothing is sent.
 - Docker and Tilt pull images and packages as they normally would.
+- Tilt, which TDK runs, has its own anonymous usage analytics. Turn them off with `tilt analytics opt out`.
 
 ## FAQ
 

package/cli/dist/commands/doctor.js

@@ -4,7 +4,7 @@ import { dirname, join, normalize } from "node:path";
 import chalk from "chalk";
 import { Command } from "commander";
 import { MASTER_CONFIG_FILES, QUICKSTART_DOCS_URL, REQUIRED_PACKAGE_SCRIPTS, } from "../utils/constants.js";
-import { checkIngressPorts, checkPrivateNpmRegistry, checkTiltResourceHealth, } from "../utils/doctor-runtime.js";
+import { checkHostPorts, checkIngressPorts, checkPrivateNpmRegistry, checkTiltResourceHealth, } from "../utils/doctor-runtime.js";
 import { validateEnvFile } from "../utils/env-validator.js";
 import { formatCount } from "../utils/formatting.js";
 import { findProjectRoot } from "../utils/paths.js";
@@ -697,6 +697,8 @@ export const doctorCommand = new Command("doctor")
         checkEnvironmentVariables,
         // Preflight: catch "port 80 already allocated" BEFORE claiming ready.
         checkIngressPorts,
+        // Preflight: a local Postgres or web server on 5432/80/443.
+        () => checkHostPorts(),
         // Preflight: Verdaccio down causes ImageBuild bun install ConnectionRefused.
         checkPrivateNpmRegistry,
         // Runtime checks: skip gracefully if the stack isn't started yet.

package/cli/dist/commands/project.js

@@ -8,7 +8,7 @@ import { generateMasterConfigs, readProjectConfig } from "../generator/template-
 import { MASTER_CONFIG_FILES } from "../utils/constants.js";
 import { ensureEnvFile, validateEnvFile } from "../utils/env-validator.js";
 import { errorFactories, runCommand, showErrorAndExit } from "../utils/errors.js";
-import { ensureDirectory, writeJsonFile } from "../utils/file-helpers.js";
+import { ensureDirectory, ensureGitignore, writeJsonFile } from "../utils/file-helpers.js";
 import { showCancelled, showCommandHeader, showDetail, showStep, showSuccess, } from "../utils/formatting.js";
 import { findProjectRoot } from "../utils/paths.js";
 import { PROJECT_FEATURES } from "../utils/project-features.js";
@@ -218,6 +218,10 @@ export const projectCommand = new Command("project")
             }
             showStep("\n📋 Regenerating master configuration files...\n");
             await generateMasterConfigs(projectRoot);
+            const ignored = ensureGitignore(projectRoot);
+            if (ignored.length > 0) {
+                showSuccess(`Added to .gitignore: ${ignored.join(", ")}`);
+            }
             console.log(chalk.green("\n✅ Project configuration regenerated!"));
             showDetail("\nGenerated in .tdk/.tdk-out/:", 0);
             for (const file of MASTER_CONFIG_FILES) {
@@ -354,8 +358,7 @@ export const projectCommand = new Command("project")
         showStep("\n🔧 Setting up environment variables...\n");
         const envCreated = ensureEnvFile(projectRoot);
         if (envCreated) {
-            showSuccess("Created: .env (with required variables)");
-            showDetail("→ Edit .env to set VERDACCIO_URL_DOCKER, TILT_ENV, etc.");
+            showSuccess("Created: .env (the defaults work as-is)");
         }
         else {
             showSuccess("Found: .env (environment already configured)");
@@ -368,6 +371,10 @@ export const projectCommand = new Command("project")
             }
             showDetail("→ Edit .env and fill in these values before running `tdk up`", 1);
         }
+        const ignored = ensureGitignore(projectRoot);
+        if (ignored.length > 0) {
+            showSuccess(`Added to .gitignore: ${ignored.join(", ")}`);
+        }
         console.log(chalk.green("\n✅ Project configuration complete!"));
         showDetail("\nGenerated files in .tdk/.tdk-out/:", 0);
         for (const file of MASTER_CONFIG_FILES) {
@@ -378,9 +385,9 @@ export const projectCommand = new Command("project")
         showDetail("\nSource file:", 0);
         showDetail("- .tdk/project.json (edit this to change project structure)");
         showDetail("\nNext steps:", 0);
-        showDetail("1. Edit .env to set required values (VERDACCIO_URL_DOCKER, TILT_ENV)");
-        showDetail("2. Run `tdk config regenerate` after editing .tdk/project.json");
-        showDetail("3. Run `tdk up` to start development");
+        showDetail("1. tdk resource api --type backend --stack app   # scaffold a service");
+        showDetail("2. tdk up app                                     # start it");
+        showDetail("\nAfter editing .tdk/project.json, run `tdk config regenerate`.", 0);
     });
 });
 //# sourceMappingURL=project.js.map

package/cli/dist/commands/up.js

@@ -3,6 +3,7 @@ import chalk from "chalk";
 import { Command } from "commander";
 import { ensureProjectRuntimeAssets } from "../generator/template-engine.js";
 import { handleDryRun } from "../utils/command-helpers.js";
+import { checkHostPorts } from "../utils/doctor-runtime.js";
 import { errorFactories, handleTiltFailure, withTiltCheck } from "../utils/errors.js";
 import { formatCount } from "../utils/formatting.js";
 import { findProjectRoot } from "../utils/paths.js";
@@ -84,6 +85,14 @@ export const upCommand = new Command("up")
         if (handleDryRun(options, "not starting services", dryRunCommand)) {
             return;
         }
+        // Warn rather than block: a stale local Postgres on 5432 makes Tilt fail
+        // halfway through startup with a bind error that's hard to read.
+        const hostPorts = await checkHostPorts();
+        if (!hostPorts.didPass && !options.quiet) {
+            console.log(chalk.yellow(`\n⚠️  ${hostPorts.message}`));
+            if (hostPorts.fix)
+                console.log(chalk.gray(`   ${hostPorts.fix}\n`));
+        }
         if (options.force && !options.quiet) {
             console.log(chalk.yellow("Force flag set - killing any existing Tilt processes..."));
             execSync("killall tilt 2>/dev/null || true", { shell: "/bin/sh", stdio: "pipe" });

package/cli/dist/utils/doctor-runtime.js

@@ -1,5 +1,6 @@
 import { execSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
+import { createServer } from "node:net";
 import { join } from "node:path";
 import { formatCount } from "./formatting.js";
 import { findProjectRoot } from "./paths.js";
@@ -322,6 +323,90 @@ export function checkIngressPorts(exec = execSync, projectName = getProjectName(
         fix: `Stop the foreign container(s), e.g. \`docker stop ${foreign[0]?.name}\`, or shut down the other TDK/Tilt project using that Traefik. Then re-run \`tdk up\`.`,
     };
 }
+/** Host ports the generated stack publishes: Traefik (80, 443) and Postgres (5432). */
+export const HOST_PORTS = { 80: "HTTP", 443: "HTTPS", 5432: "Postgres" };
+function probeAddress(port, host) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", (err) => 
+        // EACCES: ports below 1024 need root on Linux, so we can't tell.
+        resolve(err.code === "EADDRINUSE" ? "in-use" : "unknown"));
+        server.once("listening", () => server.close(() => resolve("free")));
+        server.listen(port, host);
+    });
+}
+/**
+ * Probes both the wildcard and loopback address: a Homebrew Postgres listens on
+ * 127.0.0.1 only, which a wildcard bind alone doesn't detect.
+ */
+export async function probeHostPort(port) {
+    const results = await Promise.all([
+        probeAddress(port, "0.0.0.0"),
+        probeAddress(port, "127.0.0.1"),
+    ]);
+    if (results.includes("in-use"))
+        return "in-use";
+    return results.includes("free") ? "free" : "unknown";
+}
+/**
+ * Catches host ports taken by something other than this project's containers,
+ * most often a local Postgres on 5432 or a web server on 80. Docker-held 80/443
+ * are reported by checkIngressPorts, so only 5432 is checked against other
+ * containers here.
+ */
+export async function checkHostPorts(exec = execSync, projectName = getProjectName(), probe = probeHostPort) {
+    const ports = Object.keys(HOST_PORTS).map(Number);
+    const inUse = [];
+    for (const port of ports) {
+        if ((await probe(port)) === "in-use")
+            inUse.push(port);
+    }
+    if (inUse.length === 0) {
+        return {
+            name: "Host Ports",
+            didPass: true,
+            message: `Host ports ${ports.join(", ")} are free`,
+        };
+    }
+    let dockerPs = "";
+    try {
+        dockerPs = exec("docker ps --format '{{.Names}}\\t{{.Ports}}'", {
+            stdio: "pipe",
+            encoding: "utf-8",
+            timeout: EXEC_TIMEOUT_MS,
+        });
+    }
+    catch {
+        // Can't attribute ports without Docker; treat them as held by the host.
+    }
+    const holders = parsePublishedPortHolders(dockerPs, inUse);
+    const prefix = toComposeProjectPrefix(projectName).toLowerCase();
+    const isOwn = (name) => {
+        const lower = name.toLowerCase();
+        return lower.startsWith(`${prefix}_`) || lower.startsWith(`${prefix}-`);
+    };
+    const problems = [];
+    for (const port of inUse) {
+        const holder = holders.find((h) => h.publishedPorts.includes(port));
+        if (!holder) {
+            problems.push(`${port} (${HOST_PORTS[port]}) is used by a program on this machine`);
+        }
+        else if (port === 5432 && !isOwn(holder.name)) {
+            problems.push(`${port} (${HOST_PORTS[port]}) is published by container ${holder.name}`);
+        }
+    }
+    if (problems.length === 0) {
+        return { name: "Host Ports", didPass: true, message: "Host ports are held by this project" };
+    }
+    const first = inUse.find((port) => problems.some((p) => p.startsWith(`${port} `))) ?? inUse[0];
+    return {
+        name: "Host Ports",
+        didPass: false,
+        message: `Ports TDK needs are taken:\n    ${problems.join("\n    ")}`,
+        fix: `Find what holds a port with \`lsof -nP -iTCP:${first} -sTCP:LISTEN\` and stop it ` +
+            "(for a local Postgres: `brew services stop postgresql` or quit Postgres.app), then run `tdk up`.",
+    };
+}
 /**
  * When a Tilt session is active, surface resource update errors (Traefik port
  * binds, image builds, etc.) instead of claiming the environment is ready

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

@@ -4,14 +4,14 @@ import { join } from "node:path";
 const REQUIRED_ENV_VARS = [
     {
         name: "VERDACCIO_URL_DOCKER",
-        description: "Docker-internal URL for npm registry",
+        description: "Docker-internal URL of the private npm registry (Verdaccio, a paid feature)",
         required: true,
         default: "http://verdaccio:4873",
         example: "http://verdaccio:4873",
     },
     {
         name: "VERDACCIO_URL",
-        description: "Local development URL for npm registry",
+        description: "Local URL of the private npm registry (Verdaccio, a paid feature)",
         required: false,
         default: "http://localhost:4873",
     },
@@ -44,8 +44,8 @@ function generateDbPassword() {
 export function generateEnvFile(_projectRoot) {
     const lines = [
         "# 🔧 TDK Environment Configuration",
-        "# Auto-generated by TDK CLI - edit as needed",
-        "# These variables are required for services to run",
+        "# 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).",
         "#",
         "# After editing, run: tdk config regenerate && tdk up",
         "",
@@ -53,7 +53,7 @@ export function generateEnvFile(_projectRoot) {
     for (const envVar of REQUIRED_ENV_VARS) {
         lines.push(`# ${envVar.description}`);
         if (envVar.required) {
-            lines.push(`# ⚠️  REQUIRED - set this or services will fail`);
+            lines.push("# Required (the value below is a working default)");
         }
         if (envVar.example) {
             lines.push(`# Example: ${envVar.example}`);

package/cli/dist/utils/file-helpers.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import chalk from "chalk";
 export function writeFilesWithProgress(basePath, tasks, onProgress) {
@@ -42,4 +42,25 @@ export function ensureDirectory(dirPath) {
         mkdirSync(dirPath, { recursive: true });
     }
 }
+/** Generated files that must never be committed: .env holds a generated DB password. */
+const GITIGNORE_ENTRIES = [".env", ".tdk/.tdk-out/", ".tdk/.project-id", "node_modules/"];
+/**
+ * Appends the TDK entries missing from the project's .gitignore (creating it
+ * if needed), so the first `git add .` doesn't commit .env or generated
+ * output. Returns the entries it added.
+ */
+export function ensureGitignore(projectRoot) {
+    const gitignorePath = resolve(projectRoot, ".gitignore");
+    const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf-8") : "";
+    const lines = new Set(existing.split("\n").map((line) => line.trim().replace(/\/$/, "")));
+    const missing = GITIGNORE_ENTRIES.filter((entry) => !lines.has(entry.replace(/\/$/, "")));
+    if (missing.length === 0)
+        return [];
+    const prefix = existing && !existing.endsWith("\n") ? "\n" : "";
+    const header = existing
+        ? "\n# TDK (generated files and secrets)\n"
+        : "# TDK (generated files and secrets)\n";
+    appendFileSync(gitignorePath, `${prefix}${header}${missing.join("\n")}\n`);
+    return missing;
+}
 //# sourceMappingURL=file-helpers.js.map

package/cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tdk-cli-internal",
   "private": true,
-  "version": "1.3.55",
+  "version": "1.3.56",
   "description": "TDK CLI - Tilt Development Kit command line interface",
   "keywords": [
     "tdk",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tdk-landscape/tdk-cli-core",
-  "version": "1.3.55",
+  "version": "1.3.56",
   "description": "Run 100 microservices on a 16 GB laptop without Kubernetes. Scaffold services and run them locally with hot reload, built on Tilt.",
   "homepage": "https://tdk-landscape.github.io/tdk-website",
   "repository": {