@tdk-landscape/tdk-cli-core 1.3.44 → 1.3.48

package/cli/src/commands/down.ts

@@ -0,0 +1,37 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import { handleDryRun } from "../utils/command-helpers.js";
+import { handleTiltFailure, withTiltCheck } from "../utils/errors.js";
+import { buildTiltDownArgs, runTilt } from "../utils/tilt.js";
+
+export const downCommand = new Command("down")
+  .description("Stop all tilt resources")
+  .option("-v, --verbose", "Enable verbose output", false)
+  .option("-f, --force", "Skip confirmation", false)
+  .option("--dry-run", "Show what would be stopped without stopping", false)
+  .action(async (options) => {
+    await withTiltCheck(async () => {
+      if (handleDryRun(options, "not stopping resources", "tilt down")) {
+        return;
+      }
+
+      const tiltArgs = buildTiltDownArgs({
+        force: options.force,
+      });
+
+      console.log(chalk.blue("Stopping all tilt resources..."));
+
+      if (options.verbose) {
+        console.log(chalk.gray("Running: tilt down -f .tdk/.tdk-out/Tiltfile"));
+      }
+
+      const result = await runTilt("down", tiltArgs, {
+        verbose: options.verbose,
+        inheritStdio: true,
+      });
+
+      if (result.exitCode !== 0) {
+        handleTiltFailure("down", result.exitCode);
+      }
+    });
+  });

package/cli/src/commands/help.ts

@@ -0,0 +1,150 @@
+import chalk from "chalk";
+
+const TDK_BANNER = `
+${chalk.cyan("╔════════════════════════════════════════════════════════════╗")}
+${chalk.cyan("║")}                                                            ${chalk.cyan("║")}
+${chalk.cyan("║")}     ${chalk.bold.white("████████╗██████╗ ██╗  ██╗")}    ${chalk.bold.white("██████╗██╗     ██╗")}            ${chalk.cyan("║")}
+${chalk.cyan("║")}     ${chalk.bold.white("╚══██╔══╝██╔══██╗██║ ██╔╝")}   ${chalk.bold.white("██╔════╝██║     ██║")}            ${chalk.cyan("║")}
+${chalk.cyan("║")}        ${chalk.bold.white("██║   ██║  ██║█████╔╝")}    ${chalk.bold.white("██║     ██║     ██║")}            ${chalk.cyan("║")}
+${chalk.cyan("║")}        ${chalk.bold.white("██║   ██║  ██║██╔═██╗")}    ${chalk.bold.white("██║     ██║     ██║")}            ${chalk.cyan("║")}
+${chalk.cyan("║")}        ${chalk.bold.white("██║   ██████╔╝██║  ██╗")}${chalk.yellow("██╗")}${chalk.bold.white("╚██████╗███████╗██║")}            ${chalk.cyan("║")}
+${chalk.cyan("║")}        ${chalk.white("╚═╝   ╚═════╝ ╚═╝  ╚═╝╚═╝")} ${chalk.white("╚═════╝╚══════╝╚═╝")}            ${chalk.cyan("║")}
+${chalk.cyan("║")}                                                            ${chalk.cyan("║")}
+${chalk.cyan("║")}          ${chalk.bold.yellow("🚀 Tilt Development Kit - Local Microservices")}             ${chalk.cyan("║")}
+${chalk.cyan("║")}                                                            ${chalk.cyan("║")}
+${chalk.cyan("╚════════════════════════════════════════════════════════════╝")}
+`;
+
+const COMMAND_GROUPS = [
+  {
+    title: "🌍 Project Level",
+    emoji: "📁",
+    color: chalk.blue,
+    commands: [
+      {
+        name: "project",
+        desc: "Initialize master configs (TILT_RESOURCE_DEFAULTS.star)",
+        alias: "",
+      },
+      { name: "projects, info", desc: "Show project information and config status", alias: "" },
+    ],
+  },
+  {
+    title: "📦 Stack Level",
+    emoji: "📦",
+    color: chalk.magenta,
+    commands: [
+      { name: "stack", desc: "Organize resources into stacks (interactive)", alias: "" },
+      { name: "stacks, ls", desc: "List all stacks and their resources", alias: "" },
+    ],
+  },
+  {
+    title: "⚡ Resource Level",
+    emoji: "⚡",
+    color: chalk.yellow,
+    commands: [
+      { name: "resource", desc: "Create new resource with templates", alias: "" },
+      { name: "resources", desc: "List all resources with filtering", alias: "--stack, --ports" },
+    ],
+  },
+  {
+    title: "🔄 Lifecycle",
+    emoji: "🔄",
+    color: chalk.green,
+    commands: [
+      { name: "up, deploy", desc: "Start services (optionally by stack)", alias: "[stack-name]" },
+      { name: "down", desc: "Stop all tilt resources", alias: "" },
+      { name: "status", desc: "Show status of services and stacks", alias: "" },
+    ],
+  },
+  {
+    title: "🌐 Networking",
+    emoji: "🌐",
+    color: chalk.blueBright,
+    commands: [
+      { name: "networks, traefik", desc: "Show Traefik-routed URLs for all services", alias: "--stack, --json" },
+    ],
+  },
+  {
+    title: "🛠️ Utilities",
+    emoji: "🛠️",
+    color: chalk.cyan,
+    commands: [
+      { name: "ui, interactive", desc: "Interactive TUI for managing services", alias: "" },
+      { name: "config", desc: "Manage project configuration and regenerate master files", alias: "regenerate, verify, edit" },
+      { name: "doctor", desc: "Check environment readiness", alias: "" },
+      { name: "completion", desc: "Generate shell completions", alias: "--install --shell zsh" },
+      { name: "upgrade, update", desc: "Self-update to latest version", alias: "--force" },
+      { name: "version, -v", desc: "Display version number", alias: "" },
+      { name: "help", desc: "Show this colorful help", alias: "[command]" },
+    ],
+  },
+];
+
+function formatCommand(
+  name: string,
+  desc: string,
+  alias: string,
+  color: (text: string) => string,
+): string {
+  const nameFormatted = color(name.padEnd(20));
+  const descFormatted = chalk.white(desc);
+  const aliasFormatted = alias ? chalk.gray(` ${alias}`) : "";
+  return `  ${nameFormatted} ${descFormatted}${aliasFormatted}`;
+}
+
+export function showHelp(): void {
+  console.log(TDK_BANNER);
+
+  console.log(chalk.bold.white("\n  Project → Phase → Stack → Resource (PPSR) Model\n"));
+
+  console.log(chalk.gray("  Usage: tdk [command] [options]\n"));
+
+  console.log(chalk.bold.yellow("  Global Options:"));
+  console.log(
+    `  ${chalk.cyan("-v, --version".padEnd(20))} ${chalk.white("Display version number")}`,
+  );
+  console.log(`  ${chalk.cyan("--verbose".padEnd(20))} ${chalk.white("Enable verbose output")}`);
+  console.log(`  ${chalk.cyan("-h, --help".padEnd(20))} ${chalk.white("Show help")}`);
+  console.log();
+
+  for (const group of COMMAND_GROUPS) {
+    console.log(group.color.bold(`${group.emoji} ${group.title}`));
+    console.log(group.color(`  ${"─".repeat(50)}`));
+
+    for (const cmd of group.commands) {
+      console.log(formatCommand(cmd.name, cmd.desc, cmd.alias, group.color));
+    }
+
+    console.log();
+  }
+  console.log(chalk.bold.yellow("  🚀 Quick Start:"));
+  console.log(chalk.gray(`  ${"─".repeat(50)}`));
+  console.log(
+    chalk.white(`
+  ${chalk.cyan("1.")} Initialize project:        ${chalk.green("tdk project")}
+  ${chalk.cyan("2.")} Create a resource:         ${chalk.green("tdk resource my-api --type backend")}
+  ${chalk.cyan("3.")} Assign to stack:           ${chalk.green("tdk stack my-stack")}
+  ${chalk.cyan("4.")} Start development:         ${chalk.green("tdk up my-stack")}
+  `),
+  );
+  console.log(chalk.bold.yellow("  💡 Examples:"));
+  console.log(chalk.gray(`  ${"─".repeat(50)}`));
+  console.log(
+    chalk.white(`
+  ${chalk.cyan("$")} tdk project                          # Create master configs
+  ${chalk.cyan("$")} tdk resource api --type backend      # Create backend service
+  ${chalk.cyan("$")} tdk resource app --type frontend       # Create frontend app
+  ${chalk.cyan("$")} tdk stacks --services                  # List stacks with resources
+  ${chalk.cyan("$")} tdk up my-stack                        # Start a stack
+  ${chalk.cyan("$")} tdk networks                          # Show Traefik-routed URLs
+  ${chalk.cyan("$")} tdk doctor                           # Check environment
+  ${chalk.cyan("$")} tdk upgrade                          # Self-update
+  `),
+  );
+  console.log(chalk.gray(`  ${"═".repeat(50)}`));
+  console.log(chalk.gray(`  For more help: ${chalk.cyan("tdk help [command]}")}`));
+  console.log(chalk.gray(`  GitHub: ${chalk.cyan("https://github.com/tdk-landscape/tdk-cli-core")}`));
+  console.log();
+  console.log(chalk.green.bold("  Happy coding! 🚀\n"));
+}

package/cli/src/commands/networks-design.md

@@ -0,0 +1,80 @@
+# TDK Networks Command Design
+
+## Overview
+Display Traefik-routed URLs for all services in a clean, modern CLI format.
+
+## Design Principles
+
+### 1. Visual Hierarchy
+- Header with clear title and domain info
+- Group by stack with emoji indicators
+- Service name left-aligned, URL right-aligned
+- Status indicators (emoji) for quick scanning
+
+### 2. Layout
+```
+┌─────────────────────────────────────────────────────────┐
+│  🌐  TRAEFIK NETWORKS                                    │
+│  Domain: {project}.localhost                             │
+├─────────────────────────────────────────────────────────┤
+│                                                          │
+│  🔐 IDENTITY STACK                                       │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
+│  🟢 api-api           localhost:4004 → /api/api │
+│  🟢 api-app           localhost:3000 → /api     │
+│                                                          │
+│  📅 ORDER STACK                                          │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
+│  🟢 order-api        localhost:4001 → /order│
+│  🟢 order-app        localhost:3001 → /orders│
+│                                                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 3. Color Scheme
+- **Header**: Cyan background, white bold text
+- **Stack names**: White bold with colored emoji
+- **Service names**: Gray/white
+- **URLs**: Cyan (clickable terminals will underline)
+- **Status**: 
+  - 🟢 Green (running)
+  - 🔴 Red (stopped)
+  - ⚪ Gray (unknown)
+
+### 4. Alignment
+- Stack headers: Left-aligned, bold
+- Separator line: Full width (━ character)
+- Service name: Left-aligned, 24 chars max
+- Arrow separator: "→" in gray
+- URL: Left-aligned, cyan color
+
+### 5. Data Display
+```typescript
+interface DisplayRow {
+  status: '🟢' | '🔴' | '⚪'
+  serviceName: string      // 24 chars max
+  separator: '→'
+  port?: string           // localhost:PORT or internal:PORT
+  path: string            // /service-path
+  fullUrl: string         // http://domain/path
+}
+```
+
+### 6. Terminal Width
+- Fixed width: 60 characters
+- Truncate service names at 24 chars
+- URL always clickable (http://...)
+
+### 7. Features
+- Clickable URLs (plain http:// format)
+- Grouped by stack
+- Status indicators
+- Clean separation between stacks
+
+## Implementation Notes
+
+1. Use chalk for colors
+2. No ANSI escape codes for hyperlinks (causes issues)
+3. Plain http:// URLs are auto-detected by modern terminals
+4. Pad service names to align arrows
+5. Use box-drawing characters for clean borders

package/cli/src/commands/networks.ts

@@ -0,0 +1,332 @@
+import { execSync, spawn } from "node:child_process";
+import chalk from "chalk";
+import { Command } from "commander";
+import { readProjectConfig } from "../generator/template-engine.js";
+import type { ServiceUrl } from "../types/index.js";
+import { getStackEmoji } from "../utils/constants.js";
+import { createDiscoveryContext } from "../utils/discovery-context.js";
+import { logVerbose, requireProjectRoot } from "../utils/errors.js";
+import {
+  colorizeByStatus,
+  DEFAULT_BOX_WIDTH,
+  formatBoxLine,
+  formatPadded,
+  getStatusIcon,
+  printBoxedHeader,
+} from "../utils/formatting.js";
+import { findProjectRoot } from "../utils/paths.js";
+import { checkPortStatus } from "../utils/port-assignment.js";
+import { isValidPort, sanitizeForShell } from "../utils/validation.js";
+
+function execSafe(
+  command: string,
+  args: string[],
+  options: { encoding?: string; timeout?: number } = {},
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      timeout: options.timeout || 5000,
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout?.on("data", (data: Buffer) => {
+      stdout += data.toString();
+    });
+
+    child.stderr?.on("data", (data: Buffer) => {
+      stderr += data.toString();
+    });
+
+    child.on("close", (code: number | null) => {
+      if (code !== 0) {
+        reject(new Error(`Command failed with exit code ${code}: ${stderr}`));
+      } else {
+        resolve(stdout);
+      }
+    });
+
+    child.on("error", (err: Error) => {
+      reject(err);
+    });
+  });
+}
+
+function determineDefaultDomain(): string {
+  const projectRoot = findProjectRoot();
+  if (projectRoot) {
+    const projectConfig = readProjectConfig(projectRoot);
+    const projectName = projectConfig.project?.name;
+    if (projectName && projectName !== "tdk-project") {
+      return `${projectName}.localhost`;
+    }
+  }
+
+  const domains = new Set<string>();
+  try {
+    const traefikLabels = execSync(
+      'docker ps --filter "label=traefik.enable=true" --format "{{.Labels}}" 2>/dev/null',
+      { encoding: "utf-8" },
+    );
+
+    // Capture every Host(`...`) in a rule (multi-host rules included), avoid ReDoS with bounded classes
+    const domainRegex = /Host\(`([a-zA-Z0-9_.-]{1,100})`\)/g;
+    for (
+      let match = domainRegex.exec(traefikLabels);
+      match !== null;
+      match = domainRegex.exec(traefikLabels)
+    ) {
+      domains.add(match[1]);
+    }
+  } catch (err: unknown) {
+    console.warn(chalk.yellow("⚠️ Could not scan Traefik domains (Docker unavailable)"));
+    logVerbose("Docker scan error details", err);
+  }
+
+  // Filter out service-specific domains (ones that look like individual services)
+  // Service domains typically contain the full service name like "myapp-api-frontend.localhost"
+  const domainList = Array.from(domains);
+  const projectDomains = domainList.filter((domain) => {
+    if (/^(app|api)\.[\w-]+\.localhost$/.test(domain)) return true;
+    // Skip domains that look like specific service instances
+    // These are long, hyphen-heavy domains for individual services
+    const servicePatterns = [
+      /\w+-\w+-frontend\.localhost$/,
+      /\w+-\w+-backend\.localhost$/,
+      /\w+-\w+-worker\.localhost$/,
+      /\w+-\w+-migrator\.localhost$/,
+    ];
+    return !servicePatterns.some((pattern) => pattern.test(domain));
+  });
+
+  // Prefer project-level domains (shorter, simpler ones)
+  if (projectDomains.length > 0) {
+    // Sort by length - shortest is likely the project domain
+    projectDomains.sort((a, b) => a.length - b.length);
+    return projectDomains[0];
+  }
+
+  // If only service-specific domains found, extract base from first one
+  // e.g., "myapp-api-frontend.localhost" -> try to find "myapp.localhost"
+  if (domainList.length > 0) {
+    const firstDomain = domainList[0];
+    const localhostMatch = firstDomain.match(/([\w-]+)\.localhost$/);
+    if (localhostMatch) {
+      const _prefix = localhostMatch[1];
+      // If it looks like a service domain, try common project names
+      const commonProjects = ["tdk", "project", "app", "api", "myapp"];
+      for (const project of commonProjects) {
+        const testDomain = `${project}.localhost`;
+        if (domainList.includes(testDomain)) {
+          return testDomain;
+        }
+      }
+    }
+  }
+
+  return "localhost";
+}
+
+async function checkServiceStatus(
+  serviceName: string,
+  port?: number,
+  url?: string,
+): Promise<"running" | "stopped" | "unknown"> {
+  if (url) {
+    try {
+      const validUrl = new URL(url);
+      if (validUrl.protocol !== "http:" && validUrl.protocol !== "https:") {
+        return "stopped";
+      }
+
+      const statusCode = await execSafe(
+        "curl",
+        ["-s", "-o", "/dev/null", "-w", "%{http_code}", "--max-time", "2", validUrl.toString()],
+        { timeout: 3000 },
+      );
+
+      const code = statusCode.trim();
+
+      if (/^[23]\d\d$/.test(code)) {
+        return "running";
+      }
+
+      if (/^[45]\d\d$/.test(code)) {
+        return "stopped";
+      }
+
+      // Connection refused or other error - service not accessible
+      if (code === "000") {
+        return "stopped";
+      }
+    } catch (err: unknown) {
+      console.warn(chalk.yellow(`⚠️ Could not reach ${url} (HTTP check failed)`));
+      logVerbose(`HTTP check error details for ${url}`, err);
+      return "stopped";
+    }
+  }
+
+  if (port && isValidPort(port)) {
+    const portStatus = await checkPortStatus(port);
+    if (portStatus === "running") {
+      return "running";
+    }
+    if (portStatus === "unknown") {
+      console.warn(chalk.yellow(`⚠️ Could not check port ${port} (lsof unavailable)`));
+    }
+  }
+
+  try {
+    const containerName = sanitizeForShell(serviceName);
+    const result = await execSafe(
+      "docker",
+      ["ps", "--filter", `name=${containerName}`, "--format", "{{.Names}}"],
+      { timeout: 5000 },
+    );
+
+    if (result && result.trim().length > 0) {
+      return "running";
+    }
+  } catch (err: unknown) {
+    console.warn(chalk.yellow(`⚠️ Could not check Docker for ${serviceName}`));
+    logVerbose(`Docker check error details for ${serviceName}`, err);
+  }
+
+  return "stopped";
+}
+
+export const networksCommand = new Command("networks")
+  .description("Show Traefik-routed URLs for all services")
+  .alias("urls")
+  .alias("traefik")
+  .option("-s, --stack <stack>", "Filter by stack name")
+  .option("--json", "Output as JSON")
+  .option("--raw", "Output raw URLs only")
+  .action(async (options) => {
+    const projectRoot = requireProjectRoot();
+    const discovery = createDiscoveryContext();
+
+    const baseDomain = determineDefaultDomain();
+    const bareDomain = baseDomain.replace(/^(app|api)\./, "");
+    const appDomain = `app.${bareDomain}`;
+    const apiDomain = `api.${bareDomain}`;
+    const services = discovery.resources;
+    const servicesWithUrls: ServiceUrl[] = await Promise.all(
+      services
+        .filter(
+          (s): s is typeof s & { config: { basePath: string } } =>
+            typeof s.config?.basePath === "string",
+        )
+        .map(async (s) => {
+          const basePath = s.config.basePath.replace(/^\//, "");
+          const isBackend = (s.config as { appType?: string })?.appType === "backend";
+          const host = isBackend ? apiDomain : appDomain;
+          const url = `http://${host}/${basePath}`;
+          const port = s.config.port;
+          const status = await checkServiceStatus(s.name, port, url);
+
+          return {
+            name: s.name,
+            stack: s.stack,
+            basePath: s.config.basePath,
+            url,
+            port,
+            status,
+          };
+        }),
+    );
+
+    const filteredServices = options.stack
+      ? servicesWithUrls.filter((s) => s.stack === options.stack)
+      : servicesWithUrls;
+
+    if (filteredServices.length === 0) {
+      if (options.stack) {
+        console.log(chalk.yellow(`⚠️ No services with basePath found in stack "${options.stack}"`));
+      } else {
+        console.log(chalk.yellow("⚠️ No services with basePath found"));
+        console.log(chalk.gray("\nAdd basePath to your service.json:"));
+        console.log(chalk.gray('  "basePath": "/my-service"'));
+      }
+      process.exit(0);
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify(filteredServices, null, 2));
+      process.exit(0);
+    }
+
+    if (options.raw) {
+      for (const service of filteredServices) {
+        console.log(service.url);
+      }
+      process.exit(0);
+    }
+    printBoxedHeader("🌐  TRAEFIK NETWORKS", `Domain: http://${baseDomain}`, DEFAULT_BOX_WIDTH);
+
+    // Group services by stack using discovery context's stack names for consistent ordering
+    const stacks = new Map<string, ServiceUrl[]>();
+    for (const stackName of discovery.stackNames) {
+      const stackServices = filteredServices.filter((s) => s.stack === stackName);
+      if (stackServices.length > 0) {
+        stacks.set(stackName, stackServices);
+      }
+    }
+    // Add unstacked services to 'default' group
+    const unstackedServices = filteredServices.filter((s) => !s.stack);
+    if (unstackedServices.length > 0) {
+      stacks.set("default", unstackedServices);
+    }
+
+    let isFirstStack = true;
+    for (const [stackName, stackServices] of stacks) {
+      if (!isFirstStack) {
+        console.log();
+      }
+      isFirstStack = false;
+
+      const emoji = getStackEmoji(stackName);
+      const stackTitle = `${emoji}  ${stackName.toUpperCase()} STACK`;
+
+      console.log();
+      console.log(chalk.bold.white(stackTitle));
+      console.log(chalk.gray(formatBoxLine("━", DEFAULT_BOX_WIDTH - 4)));
+
+      for (const service of stackServices) {
+        const statusSymbol = getStatusIcon(service.status);
+        const statusEmoji = colorizeByStatus(statusSymbol, service.status);
+
+        const namePart = formatPadded(service.name, 22);
+        const urlPart =
+          service.status === "running"
+            ? chalk.cyan.underline(service.url)
+            : chalk.gray(service.url); // Gray out URL if stopped
+
+        const statusLabel = service.status !== "running" ? chalk.gray(` [${service.status}]`) : "";
+
+        console.log(`  ${statusEmoji} ${chalk.white(namePart)}  ${urlPart}${statusLabel}`);
+      }
+    }
+    console.log();
+    console.log(chalk.gray(formatBoxLine("─", DEFAULT_BOX_WIDTH - 2)));
+    console.log(chalk.gray("🖱️  Click any URL above to open in browser"));
+    console.log(
+      chalk.gray("📊 Status: ") +
+        chalk.green("✓ Running") +
+        " | " +
+        chalk.red("✗ Stopped") +
+        " | " +
+        chalk.gray("? Unknown"),
+    );
+
+    if (baseDomain === "localhost") {
+      console.log();
+      const projectConfig = readProjectConfig(projectRoot);
+      const projectName = projectConfig.project.name;
+      console.log(chalk.yellow("💡 Tip: Set custom domain with:"));
+      console.log(chalk.cyan(`   export TDK_PUBLIC_HOST=${projectName}.localhost`));
+    }
+
+    console.log();
+  });