@tdk-landscape/tdk-cli-core 1.3.96 → 1.3.97

package/CHANGELOG.md

@@ -4,6 +4,7 @@ Notable changes to the `tdk` CLI. Versions match [npm](https://www.npmjs.com/pac
 
 ## Unreleased
 
+- `tdk up` keeps each smoke step's status and response body under `.tdk/smoke/<service>/<step>/` (`latest.json` and `body.txt`, body capped at 64 KiB), plus `last-success.json` and `last-success-body.txt` that a later failure never overwrites, so a regression can be diffed against the last good response. The failure line ends with the record path, and `tdk project` gitignores `.tdk/smoke/`. A new `smoke-e2e` workflow runs `scripts/verify-smoke.sh` and uploads the records. Before its first step a smoke check now waits for the service's health path (`healthCheckPath`, default `/health` for backends) with GETs until it answers something other than a connection error, 404 or 5xx, so a write is no longer the first request to hit a service that is still building; write retry rules are unchanged.
 - Add an opt-in Python backend: `tdk resource <name> --type backend --language python` scaffolds a FastAPI service (`pyproject.toml`, `src/main.py`, a pytest smoke test) and TDK generates its Docker image (`python:3.12-slim`, with `test` and `production` stages). The choice is saved as `language` in `service.json` only when you pass the flag; omitting it keeps the existing Bun + Hono output byte for byte. Unknown ids and `--language` on non-backend types fail before any file is written. A runnable example is in `examples/one-backend-python`, and the provider contract is in `docs/backend-language-providers.md`. Node.js is not included.
 - `tdk doctor` no longer reports "resource without a package.json" for a Python backend, and a Python service missing `pyproject.toml` or `src/main.py` now fails early with the missing file named.
 - Live reload now works: Tilt `live_update` sync paths were relative to the project root while Tilt resolves them against `.tdk/.tdk-out`, so they never matched and every source edit rebuilt the image ("Found file(s) not matching any sync"). An edit under `src/` is now copied into the running container without a rebuild, for Bun and Python services. Dependency file changes (`package.json`, `pyproject.toml`) still rebuild the image.

package/cli/dist/cli.js

@@ -22,6 +22,7 @@ import { upCommand } from "./commands/up.js";
 import { upgradeCommand } from "./commands/upgrade.js";
 import { versionCommand } from "./commands/version.js";
 import { formatColdPreflight, runColdPreflight } from "./utils/cold-preflight.js";
+import { unknownHelpTarget } from "./utils/help-command.js";
 const program = new Command();
 program
     .name("tdk")
@@ -69,5 +70,12 @@ if (process.argv.length === 3 && ["-h", "--help", "help"].includes(process.argv[
     showHelp();
     process.exit(0);
 }
+const unknownHelp = unknownHelpTarget(process.argv.slice(2), program.commands);
+if (unknownHelp) {
+    program.error(`error: unknown command '${unknownHelp}'`, {
+        exitCode: 1,
+        code: "commander.unknownCommand",
+    });
+}
 program.parse();
 //# sourceMappingURL=cli.js.map

package/cli/dist/commands/__tests__/project-e2e-helpers.js

@@ -0,0 +1,35 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { expect } from "vitest";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const repoRoot = resolve(__dirname, "../../../..");
+export const cliBin = join(repoRoot, "cli", "bin", "tdk.js");
+export function runTdk(args, cwd, input) {
+    return execFileSync(process.execPath, [cliBin, ...args], {
+        cwd,
+        encoding: "utf-8",
+        input,
+        env: {
+            ...process.env,
+            TDK_EXTENSION_SOURCE: repoRoot,
+        },
+    });
+}
+/** `tdk doctor` exits non-zero on machines without Docker, so read its output either way. */
+export function runTdkAllowFailure(args, cwd) {
+    const result = spawnSync(process.execPath, [cliBin, ...args], {
+        cwd,
+        encoding: "utf-8",
+        env: { ...process.env, TDK_EXTENSION_SOURCE: repoRoot },
+    });
+    return `${result.stdout}${result.stderr}`;
+}
+export function starlarkSection(content, name) {
+    const start = content.indexOf(`${name} = {`);
+    expect(start).toBeGreaterThanOrEqual(0);
+    const end = content.indexOf("\n}", start);
+    expect(end).toBeGreaterThan(start);
+    return content.slice(start, end + 2);
+}
+//# sourceMappingURL=project-e2e-helpers.js.map

package/cli/dist/commands/resource.js

@@ -5,7 +5,7 @@ import { Command } from "commander";
 import { resolveBackendFramework } from "../backend-frameworks/registry.js";
 import { getBackendIndexTemplate } from "../backend-languages/bun.js";
 import { resolveBackendLanguage } from "../backend-languages/registry.js";
-import { resolveFrontendFramework } from "../frontend-frameworks/registry.js";
+import { DEFAULT_FRONTEND_FRAMEWORK, listFrontendFrameworks, resolveFrontendFramework, } from "../frontend-frameworks/registry.js";
 import { hasDddLicense } from "../generator/extension-fetch.js";
 import { CREATABLE_RESOURCE_TYPES } from "../types/index.js";
 import { assertValid, confirmOrCancel } from "../utils/command-helpers.js";
@@ -18,7 +18,7 @@ import { promptSelect, promptText } from "../utils/prompt.js";
 import { getDefaultFeaturesForResourceType } from "../utils/resource-features.js";
 import { SERVICE_MANIFEST_SCHEMA_URL, SERVICE_MANIFEST_SCHEMA_VERSION, } from "../utils/service-manifest.js";
 import { discoverResources } from "../utils/services.js";
-import { createKebabCaseValidator, isPathSafe, validateResourceName } from "../utils/validation.js";
+import { createKebabCaseValidator, isPathSafe, validateResourceName, validateStackName, } from "../utils/validation.js";
 export const BASE_TEMPLATE = {
     port: 0, // Will be assigned
     // `dependsOn` is the current name; `dependencies` is deprecated and `tdk doctor` warns about it, so a fresh scaffold must not write it.
@@ -308,11 +308,21 @@ describe('${name}', () => {
 });
 `;
 }
+/** Resource types `tdk resource --type` accepts; `byo` is an alias of `bring-your-own`. */
+export function parseResourceType(type) {
+    const normalized = type === "byo" ? "bring-your-own" : type;
+    const validTypes = [...CREATABLE_RESOURCE_TYPES, "sdk"];
+    if (!validTypes.includes(normalized)) {
+        throw new TdkError(`Unknown resource type "${type}". Supported types: ${validTypes.join(", ")}.`, [`Use one of: ${validTypes.join(", ")}`, "Omit --type to create a backend"]);
+    }
+    return normalized;
+}
 export const resourceCommand = new Command("resource")
     .description("Create a new resource (service) from scratch, or register an existing one")
     .argument("[name]", "Resource name (kebab-case)")
     .option("-t, --type <type>", "Resource type: backend, frontend, worker, mcp, bring-your-own, sdk", "backend")
-    .option("--framework <id>", "Framework: frontend react (default), vue, svelte, preact, lit, solid, qwik, vanilla, tanstack-router; backend hono (default), express, elysia, fastify, nestjs, koa, h3")
+    .option("--framework <id>", "Framework: frontend react (default), vue, svelte, preact, lit, solid, qwik, vanilla, tanstack-router (see --frameworks); backend hono (default), express, elysia, fastify, nestjs, koa, h3")
+    .option("--frameworks", "List registered frontend frameworks and exit")
     .option("--language <id>", "Backend language: bun (default), python, go, rust")
     .option("-s, --stack <stack>", "Stack to assign resource to", "default")
     .option("-p, --path <path>", "Custom path for resource directory")
@@ -327,6 +337,12 @@ export const resourceCommand = new Command("resource")
     .option("--image <name>", "Docker image name instead of building from Dockerfile (for bring-your-own)")
     .option("--port <port>", "Port number (default: next free in 4000-5999)")
     .action(async (name, options) => {
+    if (options.frameworks) {
+        for (const f of listFrontendFrameworks()) {
+            console.log(`${f.id}\t${f.label}\t${f.kind}\t${f.verified ? "verified" : "unverified"}\t${f.command}`);
+        }
+        return;
+    }
     await runCommand(async () => {
         const projectRoot = requireProjectRoot();
         // Support --resource-path as alias for --path
@@ -347,36 +363,26 @@ export const resourceCommand = new Command("resource")
         else {
             assertValid(validateResourceName(resourceName));
         }
-        // Support sdk type for registering existing SDKs
-        let resourceType;
-        const validTypes = [...CREATABLE_RESOURCE_TYPES, "sdk"];
-        // Normalize bring-your-own aliases
-        const normalizedType = options.type === "byo" || options.type === "bring-your-own"
-            ? "bring-your-own"
-            : options.type;
-        if (!validTypes.includes(normalizedType)) {
-            const selectedType = await promptSelect({
-                message: "Resource type:",
-                choices: [
-                    { title: "backend - API service with HTTP endpoints", value: "backend" },
-                    { title: "frontend - Web application/UI", value: "frontend" },
-                    { title: "worker - Background job processor", value: "worker" },
-                    { title: "mcp - Model Context Protocol server (HTTP)", value: "mcp" },
-                    {
-                        title: "bring-your-own - Wrap an existing service. No app scaffold. Needs Dockerfile or --image.",
-                        value: "bring-your-own",
-                    },
-                    { title: "sdk - Library/SDK (register existing)", value: "sdk" },
-                ],
+        const resourceType = parseResourceType(options.type);
+        let frameworkOption = options.framework;
+        if (resourceType === "frontend" &&
+            frameworkOption === undefined &&
+            !options.yes &&
+            process.stdin.isTTY) {
+            frameworkOption = await promptSelect({
+                message: "Frontend framework:",
+                choices: listFrontendFrameworks()
+                    .map((f) => ({ title: f.label, value: f.id }))
+                    .sort((a, b) => a.value === DEFAULT_FRONTEND_FRAMEWORK
+                    ? -1
+                    : b.value === DEFAULT_FRONTEND_FRAMEWORK
+                        ? 1
+                        : 0),
             });
-            resourceType = selectedType;
-        }
-        else {
-            resourceType = normalizedType;
         }
-        const frontendFramework = resolveFrontendFramework(resourceType, options.framework);
+        const frontendFramework = resolveFrontendFramework(resourceType, frameworkOption, resourceName);
         const backendLanguage = resolveBackendLanguage(resourceType, options.language);
-        const backendFramework = resolveBackendFramework(resourceType, options.framework, backendLanguage);
+        const backendFramework = resolveBackendFramework(resourceType, frameworkOption, backendLanguage);
         // The id passed on to the file generators. An mcp resource has one fixed scaffold and no `framework` setting, so it passes none
         // (its provider is selected by the resource type itself).
         const scaffoldFrameworkId = resourceType === "mcp" ? undefined : (frontendFramework?.id ?? backendFramework?.id);
@@ -394,6 +400,7 @@ export const resourceCommand = new Command("resource")
                 dddEnabled = true;
             }
         }
+        assertValid(validateStackName(options.stack));
         let stackName = options.stack;
         if (stackName === "default") {
             const existingResources = allResources;

package/cli/dist/commands/stack.js

@@ -1,13 +1,13 @@
 import { readFileSync } from "node:fs";
 import chalk from "chalk";
 import { Command } from "commander";
-import { confirmOrCancel } from "../utils/command-helpers.js";
+import { assertValid, confirmOrCancel } from "../utils/command-helpers.js";
 import { clearDiscoveryCache, createDiscoveryContext } from "../utils/discovery-context.js";
 import { requireProjectRoot, runCommand } from "../utils/errors.js";
 import { writeJsonFile } from "../utils/file-helpers.js";
 import { formatCount, showAllSatisfyCondition, showCommandHeader, showDetail, showSuccess, } from "../utils/formatting.js";
 import { promptMultiSelect, promptText } from "../utils/prompt.js";
-import { createKebabCaseValidator } from "../utils/validation.js";
+import { createKebabCaseValidator, validateStackName } from "../utils/validation.js";
 export const stackCommand = new Command("stack")
     .description("Organize resources into stacks (groups)")
     .argument("[stack-name]", "Stack name to assign to resources")
@@ -42,6 +42,8 @@ export const stackCommand = new Command("stack")
             }
             return;
         }
+        if (stackName)
+            assertValid(validateStackName(stackName));
         let targetStack = stackName;
         if (!targetStack) {
             const name = await promptText({

package/cli/dist/commands/status.js

@@ -14,6 +14,8 @@ export const statusCommand = new Command("status")
     .option("--tilt", "Show tilt resource status", false)
     .action(async (options) => {
     const action = async () => {
+        // Discover first: outside a project this fails before any status line is printed.
+        const discovery = createDiscoveryContext();
         let tiltAvailable = false;
         try {
             tiltAvailable = await isTiltAvailable();
@@ -30,7 +32,6 @@ export const statusCommand = new Command("status")
             }
             console.log();
         }
-        const discovery = createDiscoveryContext();
         let tiltResources = null;
         let queryError = null;
         if (options.json && options.tilt && tiltAvailable) {

package/cli/dist/commands/ui.js

@@ -8,7 +8,7 @@ import { findProjectRoot } from "../utils/paths.js";
 import { clearMetadataCache, discoverResources, discoverStacks, getResourceMetadata, getStackMetadata, } from "../utils/services.js";
 import { isTiltAvailable } from "../utils/tilt.js";
 // biome-ignore lint/correctness/noUnusedFunctionParameters: reserved callback prop kept in the component API
-const HelpPanel = ({ onClose }) => (_jsxs(Box, { borderStyle: "single", borderColor: "cyan", paddingX: 2, paddingY: 1, flexDirection: "column", width: 60, children: [_jsx(Text, { bold: true, color: "cyan", children: "Keyboard Shortcuts" }), _jsxs(Box, { marginY: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, underline: true, children: "Navigation" }), _jsx(Text, { children: " \u2191/\u2193 Navigate list items" }), _jsx(Text, { children: " Enter Select item / Open detail" }), _jsx(Text, { children: " Space Toggle expand (tree view)" }), _jsx(Text, { children: " Tab Next tab" }), _jsx(Text, { children: " 1-5 Direct tab access" }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { bold: true, underline: true, children: "Actions" }) }), _jsx(Text, { children: " a Toggle all/pre-alpha services" }), _jsx(Text, { children: " m Toggle mouse support" }), _jsx(Text, { children: " t Toggle tooltips" }), _jsx(Text, { children: " e Toggle enabled/disabled services" }), _jsx(Text, { children: " r Refresh data" }), _jsx(Text, { children: " / Search/filter" }), _jsx(Text, { children: " ? Show this help" }), _jsx(Text, { children: " q/Esc Quit / Back" })] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", dimColor: true, children: "Press any key to close..." }) })] }));
+const HelpPanel = ({ onClose }) => (_jsxs(Box, { borderStyle: "single", borderColor: "cyan", paddingX: 2, paddingY: 1, flexDirection: "column", width: 60, children: [_jsx(Text, { bold: true, color: "cyan", children: "Keyboard Shortcuts" }), _jsxs(Box, { marginY: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, underline: true, children: "Navigation" }), _jsx(Text, { children: " \u2191/\u2193 Navigate list items" }), _jsx(Text, { children: " Enter Select item / Open detail" }), _jsx(Text, { children: " Space Toggle expand (tree view)" }), _jsx(Text, { children: " Tab Next tab" }), _jsx(Text, { children: " 1-5 Direct tab access" }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { bold: true, underline: true, children: "Actions" }) }), _jsx(Text, { children: " m Toggle mouse support" }), _jsx(Text, { children: " t Toggle tooltips" }), _jsx(Text, { children: " e Toggle enabled/disabled services" }), _jsx(Text, { children: " r Refresh data" }), _jsx(Text, { children: " / Search/filter" }), _jsx(Text, { children: " ? Show this help" }), _jsx(Text, { children: " q/Esc Quit / Back" })] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", dimColor: true, children: "Press any key to close..." }) })] }));
 const LoadingScreen = ({ progress, message }) => (_jsxs(Box, { flexDirection: "column", padding: 2, children: [_jsx(Text, { bold: true, color: "cyan", children: "\u2593\u2592\u2591 TDK NEON EDITION \u2591\u2592\u2593" }), _jsx(Box, { marginY: 1 }), _jsxs(Text, { children: ["Loading: ", message] }), _jsxs(Box, { marginY: 1, borderStyle: "single", borderColor: "gray", width: 50, children: [_jsx(Box, { width: progress / 2, backgroundColor: "cyan", children: _jsx(Text, { children: " ".repeat(progress / 2) }) }), _jsxs(Text, { children: [" ", progress, "%"] })] })] }));
 // biome-ignore lint/correctness/noUnusedFunctionParameters: reserved callback prop kept in the component API
 const ErrorScreen = ({ error, onRetry }) => (_jsxs(Box, { flexDirection: "column", padding: 2, alignItems: "center", children: [_jsx(Text, { bold: true, color: "red", children: "Could Not Load Services" }), _jsx(Box, { marginY: 1 }), _jsxs(Text, { color: "red", children: ["\u2717 ", error] }), _jsx(Box, { marginY: 1 }), _jsx(Text, { color: "gray", children: "Troubleshooting:" }), _jsx(Text, { color: "gray", children: " 1. Check that every service.json is valid JSON" }), _jsx(Text, { color: "gray", children: " 2. Run tdk from your project (the folder with the Tiltfile)" }), _jsx(Text, { color: "gray", children: " 3. Try: tdk status --verbose" }), _jsx(Box, { marginY: 1 }), _jsx(Text, { color: "cyan", children: "Press [r] to retry or [q] to quit" })] }));
@@ -418,7 +418,7 @@ const TUIApp = () => {
     return (_jsxs(Box, { flexDirection: "column", height: stdout.rows || 24, children: [_jsx(Box, { paddingX: 1, paddingY: 0, children: _jsxs(Text, { children: [_jsx(Text, { color: "cyan", bold: true, children: "\u2593\u2592\u2591 TDK NEON EDITION \u2591\u2592\u2593" }), _jsx(Text, { color: "gray", children: " \u2502 " }), _jsx(Text, { color: "white", children: projectRoot }), _jsx(Text, { color: "gray", children: " \u2502 " }), _jsxs(Text, { color: "green", children: [services.length, " services ready"] })] }) }), _jsx(Box, { paddingX: 1, children: _jsx(Text, { color: "gray", children: "─".repeat(compact ? 60 : Math.min(terminalWidth - 4, 100)) }) }), isSearching && (_jsx(Box, { paddingX: 1, height: 1, children: _jsxs(Text, { color: "yellow", children: ["Search: ", searchQuery, "_"] }) })), !isSearching && message && (_jsx(Box, { paddingX: 1, height: 1, children: _jsxs(Text, { color: "cyan", children: ["\u2593\u2592\u2591 ", message, " \u2591\u2592\u2593"] }) })), !isSearching && !message && showTooltips && !showHelp && (_jsx(Box, { paddingX: 1, height: 1, children: _jsx(Text, { color: "gray", dimColor: true, children: activeTab === "overview" && selectedStack
                         ? `Stack "${selectedStack}" selected. [Enter] view │ [Esc] back │ [e] ${showEnabledOnly ? "show all" : "enabled only"} │ [?] help`
                         : activeTab === "overview" && !selectedStack
-                            ? `[↑/↓] Navigate │ [Enter] Select │ [a] Pre-alpha │ [e] ${showEnabledOnly ? "show all" : "enabled only"} │ [?] help`
+                            ? `[↑/↓] Navigate │ [Enter] Select │ [e] ${showEnabledOnly ? "show all" : "enabled only"} │ [?] help`
                             : activeTab === "resources"
                                 ? `[Tab] Tabs │ [r] Refresh │ [/] Search │ [e] ${showEnabledOnly ? "show all" : "enabled only"} │ [?] help`
                                 : activeTab === "events"

package/cli/dist/commands/up.js

@@ -1,4 +1,5 @@
 import { connect } from "node:net";
+import { join } from "node:path";
 import chalk from "chalk";
 import { Command } from "commander";
 import { ensureProjectRuntimeAssets } from "../generator/template-engine.js";
@@ -210,7 +211,9 @@ export const upCommand = new Command("up")
                 if (!options.quiet) {
                     console.log(chalk.gray(`Smoke check: ${smokePlans.map((p) => p.name).join(", ")}`));
                 }
-                const results = await runSmokePlans(smokePlans);
+                const results = await runSmokePlans(smokePlans, {
+                    recordDir: join(projectRoot, ".tdk", "smoke"),
+                });
                 for (const smokeResult of results) {
                     if (smokeResult.ok) {
                         if (!options.quiet)

package/cli/dist/frontend-frameworks/registry.js

@@ -20,16 +20,54 @@ export const FRONTEND_FRAMEWORKS = {
     vanilla: vanillaFrontendProvider,
     "tanstack-router": tanstackRouterFrontendProvider,
 };
-export function getFrontendFramework(frameworkId) {
+// Frameworks that own their own server or build config. They are never scaffolded as Vite SPA providers; they go through
+// `tdk resource <name> --type bring-your-own` instead.
+export const META_FRAMEWORK_IDS = [
+    "next",
+    "nuxt",
+    "sveltekit",
+    "astro",
+    "angular",
+    "remix",
+    "tanstack-start",
+];
+// Providers that have passed scripts/verify-frontend-frameworks.sh (that script's default list must match this).
+export const VERIFIED_FRONTEND_FRAMEWORKS = [
+    "react",
+    "vue",
+    "svelte",
+    "preact",
+    "lit",
+    "solid",
+    "qwik",
+    "vanilla",
+    "tanstack-router",
+];
+export function listFrontendFrameworks() {
+    return Object.entries(FRONTEND_FRAMEWORKS).map(([id, provider]) => ({
+        id,
+        label: provider.label,
+        kind: "vite-spa",
+        verified: VERIFIED_FRONTEND_FRAMEWORKS.includes(id),
+        command: `tdk resource <name> --type frontend --framework ${id}`,
+    }));
+}
+export function getFrontendFramework(frameworkId, resourceName) {
     const id = (frameworkId ?? DEFAULT_FRONTEND_FRAMEWORK).trim().toLowerCase();
     const provider = Object.hasOwn(FRONTEND_FRAMEWORKS, id) ? FRONTEND_FRAMEWORKS[id] : undefined;
     if (!provider) {
         const supportedIds = Object.keys(FRONTEND_FRAMEWORKS).join(", ");
-        throw new TdkError(`Unknown frontend framework "${frameworkId}". Supported frameworks: ${supportedIds}.`, [`Use one of: ${supportedIds}`, `Omit --framework to use ${DEFAULT_FRONTEND_FRAMEWORK}`]);
+        const isMeta = META_FRAMEWORK_IDS.includes(id);
+        const byo = `tdk resource ${resourceName ?? "<name>"} --type bring-your-own`;
+        throw new TdkError(`${isMeta ? `"${frameworkId}" is not a Vite SPA provider` : `Unknown frontend framework "${frameworkId}"`}. Supported frameworks: ${supportedIds}.`, [
+            `Use one of: ${supportedIds}`,
+            `Omit --framework to use ${DEFAULT_FRONTEND_FRAMEWORK}`,
+            ...(isMeta ? [`Create the app with ${id}'s own CLI, then register it: ${byo}`] : []),
+        ]);
     }
     return provider;
 }
-export function resolveFrontendFramework(resourceType, frameworkId) {
+export function resolveFrontendFramework(resourceType, frameworkId, resourceName) {
     if (resourceType !== "frontend") {
         // Backends take their own framework ids (see backend-frameworks/registry.ts).
         if (frameworkId !== undefined && resourceType !== "backend") {
@@ -39,6 +77,6 @@ export function resolveFrontendFramework(resourceType, frameworkId) {
         }
         return undefined;
     }
-    return getFrontendFramework(frameworkId);
+    return getFrontendFramework(frameworkId, resourceName);
 }
 //# sourceMappingURL=registry.js.map

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

@@ -43,7 +43,13 @@ export function ensureDirectory(dirPath) {
     }
 }
 /** 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/"];
+const GITIGNORE_ENTRIES = [
+    ".env",
+    ".tdk/.tdk-out/",
+    ".tdk/.project-id",
+    ".tdk/smoke/",
+    "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

package/cli/dist/utils/help-command.js

@@ -0,0 +1,12 @@
+/**
+ * `tdk help <name>` should fail for a name that is not a command or alias, like `tdk <name>` does.
+ * Returns the unknown name, or undefined when the arguments are not `help <name>` or the name is known.
+ */
+export function unknownHelpTarget(args, commands) {
+    const [first, target] = args;
+    if (first !== "help" || !target || target.startsWith("-"))
+        return undefined;
+    const known = commands.some((command) => command.name() === target || command.aliases().includes(target));
+    return known ? undefined : target;
+}
+//# sourceMappingURL=help-command.js.map

package/cli/dist/utils/services.js

@@ -42,6 +42,12 @@ function isValidResourceConfig(value) {
         typeof config.type === "string";
     return typeof config.appName === "string" && hasRuntimeOrAppType;
 }
+// Discovery parses every service.json more than once per command (resources, then stacks),
+// so remember what was already printed and show each warning once.
+const printedWarnings = new Set();
+export function resetPrintedServiceWarnings() {
+    printedWarnings.clear();
+}
 function parseResource(serviceJsonPath) {
     const content = readFileSync(serviceJsonPath, "utf-8");
     const parsed = JSON.parse(content);
@@ -51,6 +57,9 @@ function parseResource(serviceJsonPath) {
     const parsedConfig = parsed;
     for (const warning of validateServiceManifest(parsed, serviceJsonPath).warnings) {
         // The warning names the file and field and says what is wrong (unknown, deprecated, ignored), so do not prefix it.
+        if (printedWarnings.has(warning))
+            continue;
+        printedWarnings.add(warning);
         console.warn(`⚠️  ${warning}`);
     }
     const config = {

package/cli/dist/utils/smoke.js

@@ -1,9 +1,13 @@
+import { copyFileSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 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;
+/** Largest response body kept in a smoke record. */
+export const SMOKE_RECORD_BODY_MAX_BYTES = 64 * 1024;
 /** 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. */
@@ -87,9 +91,12 @@ export function buildSmokePlans(resources, ingressPort) {
         if (config.exposeViaProxy === false)
             continue;
         const base = isApi ? apiBase : appBase;
+        // The container healthcheck path (default /health for APIs) is the one request that is safe to repeat while the route comes up.
+        const readyPath = config.healthCheckPath || (isApi && appType !== "bring-your-own" ? "/health" : undefined);
         plans.push({
             name: resource.name,
             baseUrl: `${base}${resolveServicePath(resource).replace(/\/+$/, "")}`,
+            ...(readyPath?.startsWith("/") ? { readyPath } : {}),
             smoke: config.smoke,
         });
     }
@@ -122,12 +129,65 @@ function snippet(text) {
     const flat = text.replace(/\s+/g, " ").trim();
     return flat.length > BODY_SNIPPET_CHARS ? `${flat.slice(0, BODY_SNIPPET_CHARS)}...` : flat;
 }
+function slug(text) {
+    return (text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "step");
+}
+/** Two steps whose names slug the same (`read back`, `read-back`) must not share a record directory. */
+function stepKey(seen, label) {
+    const base = slug(label);
+    const n = (seen.get(base) ?? 0) + 1;
+    seen.set(base, n);
+    return n === 1 ? base : `${base}-${n}`;
+}
+/** Writes latest.json (+ body.txt) for a step; a passing step also replaces the last-success pair. Returns the latest.json path. */
+function writeStepRecord(recordDir, stepKey, record, body, passed) {
+    try {
+        const dir = join(recordDir, slug(record.service), stepKey);
+        mkdirSync(dir, { recursive: true });
+        const latest = join(dir, "latest.json");
+        const bodyPath = join(dir, "body.txt");
+        if (body === undefined) {
+            rmSync(bodyPath, { force: true });
+        }
+        else {
+            writeFileSync(bodyPath, body);
+        }
+        writeFileSync(latest, `${JSON.stringify({ ...record, bodyPath: body === undefined ? null : "body.txt" }, null, 2)}\n`);
+        if (passed) {
+            copyFileSync(latest, join(dir, "last-success.json"));
+            if (body === undefined)
+                rmSync(join(dir, "last-success-body.txt"), { force: true });
+            else
+                copyFileSync(bodyPath, join(dir, "last-success-body.txt"));
+        }
+        return latest;
+    }
+    catch {
+        // The record is a diagnostic aid; failing to write it must not change the smoke result.
+        return undefined;
+    }
+}
+/** Caps a body at SMOKE_RECORD_BODY_MAX_BYTES of UTF-8 without splitting a character. */
+function capBody(text) {
+    const buf = Buffer.from(text, "utf8");
+    if (buf.length <= SMOKE_RECORD_BODY_MAX_BYTES)
+        return { body: text, truncated: false, bytes: buf.length };
+    const body = buf
+        .subarray(0, SMOKE_RECORD_BODY_MAX_BYTES)
+        .toString("utf8")
+        .replace(/\uFFFD$/, "");
+    return { body, truncated: true, bytes: Buffer.byteLength(body, "utf8") };
+}
 /** 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 budgetMs = (plan.smoke.timeoutSeconds ?? DEFAULT_SMOKE_TIMEOUT_SECONDS) * 1000;
+    let deadline = now() + budgetMs;
     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);
@@ -138,6 +198,33 @@ export async function runSmokePlan(plan, deps = {}) {
             failure: `${plan.name}: invalid smoke block: ${invalid.join("; ")}`,
         };
     }
+    // `tdk up` starts the check once Tilt's UI is up, while images may still be building. Traefik then resets or 404s early requests.
+    // A write must not be repeated after a reset (it may have reached the service), so wait for readiness with GETs instead.
+    // If the service never answers, fall through: the first step then fails with its own record.
+    if (plan.readyPath) {
+        const readyUrl = `${plan.baseUrl}${plan.readyPath}`;
+        for (;;) {
+            try {
+                const response = await doFetch(readyUrl, {
+                    method: "GET",
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                });
+                await response.text();
+                // A 5xx from the health path (migrations running, database not up) is still "not ready"; 401 or 3xx means something answered.
+                if (!NOT_READY_STATUSES.has(response.status) && response.status < 500)
+                    break;
+            }
+            catch {
+                // not accepting connections yet
+            }
+            if (now() >= deadline)
+                break;
+            await sleep(RETRY_DELAY_MS);
+        }
+    }
+    // The steps get their own `timeoutSeconds`; a slow build must not eat the first step's budget.
+    deadline = now() + budgetMs;
+    const stepKeys = new Map();
     for (const [index, step] of plan.smoke.steps.entries()) {
         const label = step.name ?? `step ${index + 1}`;
         const method = (step.method ?? "GET").toUpperCase();
@@ -147,8 +234,10 @@ export async function runSmokePlan(plan, deps = {}) {
         let status;
         let text = "";
         let error;
+        let errorCode;
         for (;;) {
             error = undefined;
+            errorCode = undefined;
             status = undefined;
             let retryableError = false;
             try {
@@ -164,6 +253,10 @@ export async function runSmokePlan(plan, deps = {}) {
             catch (err) {
                 retryableError = shouldRetryRequestError(err, method);
                 error = err instanceof Error ? err.message : String(err);
+                const code = isRecord(err)
+                    ? (err.code ?? (isRecord(err.cause) ? err.cause.code : undefined))
+                    : undefined;
+                errorCode = typeof code === "string" ? code : undefined;
             }
             const notReady = (error !== undefined && retryableError) ||
                 (status !== undefined && status !== expected && NOT_READY_STATUSES.has(status));
@@ -172,21 +265,38 @@ export async function runSmokePlan(plan, deps = {}) {
             await sleep(RETRY_DELAY_MS);
         }
         const where = `${plan.name}: ${label}: ${method} ${url}`;
+        // Every step that ran leaves a record. A step is "passed" for last-success only if status and bodyContains both match.
+        let recordPath;
+        if (deps.recordDir) {
+            const capped = status === undefined ? undefined : capBody(text);
+            const passed = error === undefined &&
+                status === expected &&
+                (step.bodyContains === undefined || text.includes(step.bodyContains));
+            recordPath = writeStepRecord(deps.recordDir, stepKey(stepKeys, label), {
+                service: plan.name,
+                step: label,
+                method,
+                url,
+                expectedStatus: expected,
+                status: status ?? null,
+                ...(error === undefined ? {} : { error: errorCode ?? error }),
+                truncated: capped?.truncated ?? false,
+                bodyBytes: capped?.bytes ?? 0,
+            }, capped?.body, passed);
+        }
+        const fail = (failure) => ({
+            name: plan.name,
+            ok: false,
+            failure,
+            recordPath,
+        });
         if (error !== undefined)
-            return { name: plan.name, ok: false, failure: `${where} never answered (${error})` };
+            return fail(`${where} never answered (${error})`);
         if (status !== expected) {
-            return {
-                name: plan.name,
-                ok: false,
-                failure: `${where} returned ${status}, expected ${expected}${text ? `: ${snippet(text)}` : ""}`,
-            };
+            return fail(`${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)}`,
-            };
+            return fail(`${where} returned ${status} but the body does not contain "${step.bodyContains}": ${snippet(text)}`);
         }
         if (step.save) {
             let parsed;
@@ -194,20 +304,12 @@ export async function runSmokePlan(plan, deps = {}) {
                 parsed = JSON.parse(text);
             }
             catch {
-                return {
-                    name: plan.name,
-                    ok: false,
-                    failure: `${where} returned a body that is not JSON, cannot save: ${snippet(text)}`,
-                };
+                return fail(`${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)}`,
-                    };
+                    return fail(`${where} response has no ${path} to save as {{${key}}}: ${snippet(text)}`);
                 }
                 saved[key] = String(value);
             }
@@ -216,7 +318,7 @@ export async function runSmokePlan(plan, deps = {}) {
     return { name: plan.name, ok: true };
 }
 export function formatSmokeFailure(result) {
-    return `Smoke check failed: ${result.failure}`;
+    return `Smoke check failed: ${result.failure}${result.recordPath ? ` (record: ${result.recordPath})` : ""}`;
 }
 /** Runs every plan side by side; each plan keeps its own timeout. */
 export async function runSmokePlans(plans, deps = {}) {

package/cli/dist/utils/validation.js

@@ -3,29 +3,34 @@ export const KEBAB_CASE_REGEX = /^[a-z0-9-]+$/;
 function isKebabCase(value) {
     return KEBAB_CASE_REGEX.test(value);
 }
+const KEBAB_RULE = "Use lowercase letters, numbers, and hyphens only";
+function invalidNameMessage(label, value) {
+    const example = label === "Resource name" ? "my-service" : "my-stack";
+    return `${label} "${value}" is not valid. ${KEBAB_RULE}, e.g. "${example}".`;
+}
 export function validateResourceName(name) {
     if (!name.trim()) {
         return { valid: false, error: "Resource name is required" };
     }
     if (!isKebabCase(name)) {
-        return {
-            valid: false,
-            error: "Use lowercase letters, numbers, and hyphens only",
-        };
+        return { valid: false, error: invalidNameMessage("Resource name", name) };
+    }
+    return { valid: true };
+}
+export function validateStackName(name) {
+    if (!name.trim()) {
+        return { valid: false, error: "Stack name is required" };
+    }
+    if (!isKebabCase(name)) {
+        return { valid: false, error: invalidNameMessage("Stack name", name) };
     }
     return { valid: true };
 }
 export function createKebabCaseValidator(context) {
+    const validate = context === "resource" ? validateResourceName : validateStackName;
     return (input) => {
-        if (!input.trim()) {
-            return context === "resource" ? "Resource name is required" : "Stack name is required";
-        }
-        if (!isKebabCase(input)) {
-            return context === "resource"
-                ? "Use lowercase letters, numbers, and hyphens only"
-                : "Use kebab-case (lowercase, numbers, hyphens only)";
-        }
-        return true;
+        const result = validate(input);
+        return result.valid ? true : (result.error ?? "Invalid name");
     };
 }
 export function validateOptionalInfraService(service) {

package/cli/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tdk-landscape/tdk-cli-core",
-  "version": "1.3.96",
+  "version": "1.3.97",
   "description": "TDK CLI — start services on your laptop.",
   "homepage": "https://tdk-landscape.github.io/tdk-website",
   "repository": {