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

package/cli/src/utils/port-assignment.ts

@@ -0,0 +1,106 @@
+import { spawn } from "node:child_process";
+import { createConnection } from "node:net";
+import type { DiscoveredResource, PortAssignableResourceType } from "../types/index.js";
+import { PORT_RANGES } from "./constants.js";
+
+function isPortAvailable(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const server = createConnection({ port, host: "127.0.0.1" }, () => {
+      server.destroy();
+      resolve(false);
+    });
+
+    server.on("error", () => {
+      resolve(true);
+    });
+
+    // A connect that neither accepts nor refuses means something is holding
+    // the port (e.g. a firewall drop) - treat it as taken rather than wait.
+    server.setTimeout(1000, () => {
+      server.destroy();
+      resolve(false);
+    });
+  });
+}
+
+export async function checkPortStatus(port: number): Promise<"running" | "stopped" | "unknown"> {
+  return new Promise((resolve) => {
+    const child = spawn("lsof", ["-Pi", `:${port}`, "-sTCP:LISTEN"], {
+      timeout: 3000,
+      stdio: "pipe",
+    });
+
+    let hasOutput = false;
+
+    child.stdout?.on("data", () => {
+      hasOutput = true;
+    });
+
+    child.on("close", (code) => {
+      // lsof returns 0 if it found something, 1 if nothing found
+      if (code === 0) {
+        resolve("running");
+      } else {
+        resolve(hasOutput ? "running" : "stopped");
+      }
+    });
+
+    child.on("error", () => {
+      resolve("unknown");
+    });
+  });
+}
+
+export async function findAvailablePort(
+  basePort: number,
+  maxAttempts: number = 10,
+): Promise<number | null> {
+  for (let i = 0; i < maxAttempts; i++) {
+    const port = basePort + i;
+    if (await isPortAvailable(port)) {
+      return port;
+    }
+  }
+  return null;
+}
+
+export function getUsedPorts(resources: DiscoveredResource[]): Set<number> {
+  const usedPorts = new Set<number>();
+  for (const r of resources) {
+    if (r.port && r.port > 0) {
+      usedPorts.add(r.port);
+    }
+  }
+  return usedPorts;
+}
+
+function findNextAvailablePort(
+  usedPorts: Set<number>,
+  range: { base: number; min: number; max: number },
+): number | null {
+  for (let port = range.base; port <= range.max; port++) {
+    if (!usedPorts.has(port)) {
+      return port;
+    }
+  }
+  return null;
+}
+
+export function assignPort(
+  resourceType: PortAssignableResourceType,
+  existingResources: DiscoveredResource[],
+): number {
+  const usedPorts = getUsedPorts(existingResources);
+  const portRange = PORT_RANGES[resourceType];
+
+  const assignedPort = findNextAvailablePort(usedPorts, portRange);
+
+  if (assignedPort === null) {
+    throw new Error(
+      `No available ports in range ${portRange.base}-${portRange.max}. ` +
+        "Check TILT_RESOURCE_DEFAULTS.star for port configuration.",
+    );
+  }
+
+  return assignedPort;
+}

package/cli/src/utils/project-features.ts

@@ -0,0 +1,118 @@
+/**
+ * Project-Level Features
+ *
+ * These are infrastructure and optional services enabled at the project level.
+ * They are available to all resources and are configured in project.json stacks.
+ *
+ * Default: All CORE features enabled in pre_alpha stack
+ * Optional/premium: disabled by default (can be enabled in optional_infra)
+ */
+
+export interface ProjectFeature {
+  name: string;
+  description: string;
+  category: "core" | "optional" | "premium";
+  phase: "pre_alpha" | "alpha" | "beta";
+  enabled_by_default: boolean;
+  dependsOn?: string[];
+}
+
+export const PROJECT_FEATURES: Record<string, ProjectFeature> = {
+  // ============================================================================
+  // CORE INFRASTRUCTURE (always enabled in pre_alpha)
+  // ============================================================================
+  proxy: {
+    name: "proxy",
+    description: "Traefik reverse proxy and API gateway for routing all services",
+    category: "core",
+    phase: "pre_alpha",
+    enabled_by_default: true,
+    dependsOn: [],
+  },
+
+  // Key/name must be the literal Tilt resource name (PlatformDockerConstants.VERDACCIO_RESOURCE_NAME
+  // in tdk-cli-extensions), since project.json's services list is copied verbatim into
+  // PRE_ALPHA_RESOURCES and matched against that name by should_enable(). "registry" would
+  // silently fail to enable Verdaccio.
+  verdaccio: {
+    name: "verdaccio",
+    description:
+      "Verdaccio npm registry for package management and local publishing (Premium - requires TDK_LICENSE_KEY)",
+    category: "premium",
+    phase: "pre_alpha",
+    enabled_by_default: false,
+    dependsOn: [],
+  },
+
+  "database-management": {
+    name: "database-management",
+    description: "PostgreSQL database for data persistence and SQL operations",
+    category: "core",
+    phase: "pre_alpha",
+    enabled_by_default: true,
+    dependsOn: [],
+  },
+
+  // ============================================================================
+  // OPTIONAL INFRASTRUCTURE (disabled by default, enable in optional_infra)
+  // ============================================================================
+  monitoring: {
+    name: "monitoring",
+    description: "SigNoz or SkyWalking observability platform for monitoring and tracing",
+    category: "optional",
+    phase: "pre_alpha",
+    enabled_by_default: false,
+    dependsOn: ["database-management"],
+  },
+
+  elk: {
+    name: "elk",
+    description: "Elasticsearch, Logstash, Kibana stack for log aggregation and analysis",
+    category: "optional",
+    phase: "pre_alpha",
+    enabled_by_default: false,
+    dependsOn: [],
+  },
+
+  debezium: {
+    name: "debezium",
+    description: "Change Data Capture for real-time data streaming from databases",
+    category: "optional",
+    phase: "pre_alpha",
+    enabled_by_default: false,
+    dependsOn: ["database-management"],
+  },
+
+  "golden-image": {
+    name: "golden-image",
+    description: "Pre-built Docker image layer for faster builds and smaller deployments",
+    category: "optional",
+    phase: "pre_alpha",
+    enabled_by_default: true,
+    dependsOn: [],
+  },
+};
+
+/**
+ * Get all enabled project features
+ */
+export function getEnabledProjectFeatures(optional_infra?: Record<string, boolean>): string[] {
+  const enabled: string[] = [];
+
+  for (const [key, feature] of Object.entries(PROJECT_FEATURES)) {
+    if (feature.enabled_by_default) {
+      enabled.push(key);
+    }
+  }
+
+  // Add optional features if enabled
+  if (optional_infra) {
+    for (const [key, isEnabled] of Object.entries(optional_infra)) {
+      if (isEnabled && PROJECT_FEATURES[key]) {
+        enabled.push(key);
+      }
+    }
+  }
+
+  return enabled;
+}

package/cli/src/utils/project-templates.ts

@@ -0,0 +1,28 @@
+export interface ProjectTemplate {
+  repo: string;
+  description: string;
+}
+
+/** Starter projects `tdk project <name>` can clone. Keep in sync with the public tdk-landscape examples. */
+export const PROJECT_TEMPLATES: Record<string, ProjectTemplate> = {
+  restaurant: {
+    repo: "https://github.com/tdk-landscape/tdk-restaurant-example.git",
+    description: "Restaurant ops: reservations, kitchen, floor control (Hono + Vite + Bun)",
+  },
+  saas: {
+    repo: "https://github.com/tdk-landscape/tdk-saas-starter.git",
+    description: "SaaS starter: account dashboard and a working checkout button (Hono + Vite + Bun)",
+  },
+  erp: {
+    repo: "https://github.com/tdk-landscape/tdk-erp-system.git",
+    description: "Enterprise ERP: 100 microservices across 7 business domains",
+  },
+  "user-management": {
+    repo: "https://github.com/tdk-landscape/tdk-user-management.git",
+    description: "User/auth management services",
+  },
+  example: {
+    repo: "https://github.com/tdk-landscape/tdk-example.git",
+    description: "Minimal Project-Stack-Resource (PSR) demonstration",
+  },
+};

package/cli/src/utils/prompt.ts

@@ -0,0 +1,123 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+type ValidationResult = true | string;
+
+interface TextPromptOptions {
+  message: string;
+  initial?: string;
+  validate?: (input: string) => ValidationResult;
+}
+
+interface ConfirmPromptOptions {
+  message: string;
+  initial?: boolean;
+}
+
+interface Choice<T extends string> {
+  title: string;
+  value: T;
+  selected?: boolean;
+}
+
+interface ChoicePromptOptions<T extends string> {
+  message: string;
+  choices: Choice<T>[];
+}
+
+interface MultiSelectPromptOptions<T extends string> extends ChoicePromptOptions<T> {
+  validate?: (input: T[]) => ValidationResult;
+}
+
+async function question(prompt: string): Promise<string> {
+  const rl = createInterface({ input, output });
+  try {
+    return (await rl.question(prompt)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+export async function promptText(options: TextPromptOptions): Promise<string> {
+  const suffix = options.initial ? ` (${options.initial})` : "";
+
+  while (true) {
+    const answer = await question(`${options.message}${suffix} `);
+    const value = answer || options.initial || "";
+    const validation = options.validate?.(value) ?? true;
+
+    if (validation === true) {
+      return value;
+    }
+
+    console.log(validation);
+  }
+}
+
+export async function promptConfirm(options: ConfirmPromptOptions): Promise<boolean> {
+  const defaultValue = options.initial ?? true;
+  const suffix = defaultValue ? "Y/n" : "y/N";
+
+  while (true) {
+    const answer = (await question(`${options.message} (${suffix}) `)).toLowerCase();
+    if (!answer) return defaultValue;
+    if (["y", "yes"].includes(answer)) return true;
+    if (["n", "no"].includes(answer)) return false;
+    console.log("Please answer yes or no.");
+  }
+}
+
+export async function promptSelect<T extends string>(
+  options: ChoicePromptOptions<T>,
+): Promise<T> {
+  console.log(options.message);
+  options.choices.forEach((choice, index) => {
+    console.log(`  ${index + 1}. ${choice.title}`);
+  });
+
+  while (true) {
+    const answer = await question("Choose one: ");
+    const selectedIndex = Number.parseInt(answer, 10) - 1;
+    const selected = options.choices[selectedIndex];
+
+    if (selected) {
+      return selected.value;
+    }
+
+    console.log(`Enter a number from 1 to ${options.choices.length}.`);
+  }
+}
+
+export async function promptMultiSelect<T extends string>(
+  options: MultiSelectPromptOptions<T>,
+): Promise<T[]> {
+  const defaults = options.choices
+    .map((choice, index) => (choice.selected ? index + 1 : null))
+    .filter((index): index is number => index !== null);
+  const defaultHint = defaults.length > 0 ? ` [${defaults.join(",")}]` : "";
+
+  console.log(options.message);
+  options.choices.forEach((choice, index) => {
+    const marker = choice.selected ? "*" : " ";
+    console.log(` ${marker} ${index + 1}. ${choice.title}`);
+  });
+
+  while (true) {
+    const answer = await question(`Choose one or more numbers, comma-separated${defaultHint}: `);
+    const rawIndexes = answer
+      ? answer.split(",").map((value) => Number.parseInt(value.trim(), 10))
+      : defaults;
+
+    const selected = Array.from(new Set(rawIndexes))
+      .map((index) => options.choices[index - 1])
+      .filter((choice): choice is Choice<T> => Boolean(choice))
+      .map((choice) => choice.value);
+
+    const validation = options.validate?.(selected) ?? true;
+    if (validation === true) {
+      return selected;
+    }
+
+    console.log(validation);
+  }
+}

package/cli/src/utils/resource-features.ts

@@ -0,0 +1,209 @@
+/**
+ * Resource-Level Features
+ *
+ * These are code generators and configurations that run per-service/resource.
+ * They are controlled via the featuresEnabled: [] array in each service.json file.
+ *
+ * Frontend services: api-client, env-config, api-index (enabled by default)
+ * Backend services: prisma (enabled by default)
+ */
+
+export type ResourceType = "frontend" | "backend" | "worker" | "migrator" | "sdk";
+
+export interface ResourceFeature {
+  name: string;
+  description: string;
+  applies_to: ResourceType[];
+  enabled_by_default: boolean;
+  generator_file: string;
+  output_file: string;
+  category?: "core" | "optional" | "premium";
+}
+
+export const RESOURCE_FEATURES: Record<string, ResourceFeature> = {
+  // ============================================================================
+  // FRONTEND GENERATORS
+  // ============================================================================
+  "api-client": {
+    name: "api-client",
+    description: "Pre-configured API client for backend communication (createApiClient wrapper)",
+    applies_to: ["frontend"],
+    enabled_by_default: true,
+    generator_file: "engine/topologies/tilt/resources/orchestrator/generators/frontend.star",
+    output_file: ".autogenerated/api-client.ts",
+  },
+
+  "env-config": {
+    name: "env-config",
+    description: "Environment constants and configuration (Vite env vars)",
+    applies_to: ["frontend"],
+    enabled_by_default: true,
+    generator_file: "engine/topologies/tilt/resources/orchestrator/generators/frontend.star",
+    output_file: ".autogenerated/env.ts",
+  },
+
+  "api-index": {
+    name: "api-index",
+    description: "Barrel export for clean API client imports",
+    applies_to: ["frontend"],
+    enabled_by_default: true,
+    generator_file: "engine/topologies/tilt/resources/orchestrator/generators/frontend.star",
+    output_file: ".autogenerated/api-index.ts",
+  },
+
+  // ============================================================================
+  // BACKEND GENERATORS
+  // ============================================================================
+  prisma: {
+    name: "prisma",
+    description: "Prisma CLI configuration for migrations and database client generation",
+    applies_to: ["backend", "worker", "migrator"],
+    enabled_by_default: true,
+    generator_file: "engine/topologies/tilt/generators/typescript/prisma_config.star",
+    output_file: ".autogenerated/prisma.config.autogenerated.ts",
+  },
+
+  // ============================================================================
+  // BUILD CONFIGURATION GENERATORS (always enabled, not listed in features)
+  // ============================================================================
+  // Note: These always run regardless of features array. They are core to the build.
+  // Listed here for reference only.
+
+  vite: {
+    name: "vite",
+    description: "Vite configuration for frontend/backend/SDK builds",
+    applies_to: ["frontend", "backend", "sdk"],
+    enabled_by_default: true, // Always enabled
+    generator_file: "engine/topologies/tilt/generators/vite_config.star",
+    output_file: ".autogenerated/vite.config.*.ts",
+  },
+
+  tsconfig: {
+    name: "tsconfig",
+    description: "TypeScript configuration (local and Docker variants)",
+    applies_to: ["frontend", "backend", "worker", "migrator", "sdk"],
+    enabled_by_default: true, // Always enabled
+    generator_file: "engine/topologies/tilt/generators/typescript/",
+    output_file: ".autogenerated/tsconfig.*.json",
+  },
+
+  dockerfile: {
+    name: "dockerfile",
+    description: "Docker container configuration for production builds",
+    applies_to: ["frontend", "backend", "worker", "migrator", "sdk"],
+    enabled_by_default: true, // Always enabled
+    generator_file: "engine/topologies/tilt/resources/orchestrator/generators/manifest_resource.star",
+    output_file: ".autogenerated/Dockerfile.app",
+  },
+
+  npmrc: {
+    name: "npmrc",
+    description: "NPM registry configuration for package installation",
+    applies_to: ["frontend", "backend", "worker", "migrator", "sdk"],
+    enabled_by_default: true, // Always enabled
+    generator_file: "engine/topologies/tilt/generators/npmrc.star",
+    output_file: ".autogenerated/.npmrc*",
+  },
+
+  bunfig: {
+    name: "bunfig",
+    description: "Bun runtime configuration for package management",
+    applies_to: ["frontend", "backend", "worker", "migrator", "sdk"],
+    enabled_by_default: true, // Always enabled
+    generator_file: "engine/topologies/tilt/generators/npmrc.star",
+    output_file: ".autogenerated/bunfig.toml*",
+  },
+
+  nginx: {
+    name: "nginx",
+    description: "Nginx configuration for static file serving (frontend only)",
+    applies_to: ["frontend"],
+    enabled_by_default: true, // Always enabled
+    generator_file: "engine/topologies/tilt/generators/nginx_conf.star",
+    output_file: ".autogenerated/nginx.conf",
+  },
+
+  env: {
+    name: "env",
+    description: "Backend environment file configuration",
+    applies_to: ["backend", "worker", "migrator"],
+    enabled_by_default: true, // Always enabled
+    generator_file: "engine/topologies/tilt/resources/orchestrator/generators/env.star",
+    output_file: ".autogenerated/.env*",
+  },
+
+  playwright: {
+    name: "playwright",
+    description: "Playwright test configuration (if playwright: true in manifest)",
+    applies_to: ["frontend", "backend"],
+    enabled_by_default: false, // Only if explicitly enabled in manifest
+    generator_file: "engine/topologies/tilt/generators/typescript/playwright_config.star",
+    output_file: ".autogenerated/playwright.config.ts",
+  },
+
+  "agents-md": {
+    name: "agents-md",
+    description:
+      "AI agent guard rails for .autogenerated/ folder (paid TDK feature - free tier writes a stub notice; see extension-fetch.ts KNOWN_RESOURCES)",
+    applies_to: ["frontend", "backend", "worker", "migrator", "sdk"],
+    enabled_by_default: true, // Always attempted; real content is license-gated
+    generator_file: "engine/topologies/tilt/generators/agents_md.star",
+    output_file: ".autogenerated/AGENTS.md",
+  },
+
+  ddd: {
+    name: "ddd",
+    description:
+      "Domain-driven design folder structure (domain/application/infrastructure/presentation) " +
+      "and matching @domain/@application/@infrastructure/@presentation/@test path aliases " +
+      "(Premium - requires TDK_LICENSE_KEY; see hasDddLicense() in extension-fetch.ts)",
+    applies_to: ["backend", "worker", "migrator"],
+    enabled_by_default: false,
+    category: "premium",
+    generator_file:
+      "engine/topologies/tilt/generators/vite/helpers.star, engine/topologies/tilt/generators/typescript/backend_tsconfig.star",
+    output_file: ".autogenerated/vite.config.*.ts, .autogenerated/tsconfig.*.json",
+  },
+
+  sablier: {
+    name: "sablier",
+    description:
+      "On-demand scaling: stop this resource when idle, wake it on the next request via a " +
+      "`sablier: {enable: true}` manifest block (not the featuresEnabled array) " +
+      "(Premium - requires TDK_LICENSE_KEY; free tier writes a disabled stub; see " +
+      "hasSablierLicense() in extension-fetch.ts KNOWN_RESOURCES/PREMIUM_PATH_MAP)",
+    applies_to: ["backend", "frontend"],
+    enabled_by_default: false,
+    category: "premium",
+    generator_file:
+      "engine/topologies/platform/docker/networking/sablier_container_cycle.star (stub; real generator in tdk-cli-extensions/premium/networking/), engine/topologies/platform/docker/networking/traefik.star",
+    output_file: "(Traefik + Sablier Docker labels on the resource's own compose service, no autogenerated file)",
+  },
+};
+
+/**
+ * Get default features for a resource type
+ */
+export function getDefaultFeaturesForResourceType(appType: ResourceType): string[] {
+  const defaults: string[] = [];
+
+  for (const [key, feature] of Object.entries(RESOURCE_FEATURES)) {
+    if (
+      feature.enabled_by_default &&
+      feature.applies_to.includes(appType) &&
+      // Only include if it's something users control via features array
+      ["api-client", "env-config", "api-index", "prisma"].includes(key)
+    ) {
+      defaults.push(key);
+    }
+  }
+
+  return defaults;
+}
+
+/**
+ * Get all generators for a resource type (for documentation)
+ */
+export function getGeneratorsForResourceType(appType: ResourceType): ResourceFeature[] {
+  return Object.values(RESOURCE_FEATURES).filter((f) => f.applies_to.includes(appType));
+}