@tdk-landscape/tdk-cli-core 1.3.105 → 1.3.106

package/CHANGELOG.md

@@ -4,6 +4,7 @@ Notable changes to the `tdk` CLI. Versions match [npm](https://www.npmjs.com/pac
 
 ## Unreleased
 
+- `tdk doctor` warns when a backend or worker applies database migrations from its own start-up (a `start`/`dev` script, a Dockerfile `CMD`/`ENTRYPOINT`, a shell entrypoint or its source: Prisma, Drizzle, Knex, TypeORM, MikroORM, Sequelize, dbmate, Atlas, Alembic). It is a warning, not a failure: such services work, but migrations belong in a `migrator` resource that runs once before the services that depend on it. `migrator` and bring-your-own resources are not checked.
 - Go services can opt in to a live development loop with `"dev": { "liveReload": true }` in `service.json`: edits are copied into the running container and recompiled without an image rebuild, while `go.mod`, `go.sum` and the generated Dockerfile still rebuild the image. The watcher compiles into a staging binary while the old build keeps serving and swaps only on success, so a compile error shows in the Tilt log and the last good build keeps answering (Air, tried first, stopped the app before compiling and left it down for the whole compile; in 2 of 6 edits a Traefik health check then returned 503 for 10 s). Measured on one loaded Mac: median edit-to-ready 1.63 s for the scaffold. The default Go image (`golang:1.23`) now sets `GOTOOLCHAIN=auto`, so a `go.mod` that needs a newer Go, such as Gin 1.12 (`go 1.25`), downloads that toolchain instead of stopping with `requires go >= 1.25`. Offline or air-gapped builds of a go.mod newer than 1.23 still fail, but now at the toolchain download rather than at the version check. `scripts/e2e/go-dev-loop.sh` checks all of this through a real `tdk up`. Refs #369.
 - `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.

package/cli/dist/cli.js

@@ -9,7 +9,9 @@ import { downCommand } from "./commands/down.js";
 import { ejectCommand } from "./commands/eject.js";
 import { showHelp } from "./commands/help.js";
 import { importCommand } from "./commands/import.js";
+import { logsCommand } from "./commands/logs.js";
 import { maintainersCommand } from "./commands/maintainers.js";
+import { mcpCommand } from "./commands/mcp.js";
 import { networksCommand } from "./commands/networks.js";
 import { projectCommand } from "./commands/project.js";
 import { projectsCommand } from "./commands/projects.js";
@@ -46,6 +48,8 @@ program.addCommand(resourcesCommand);
 program.addCommand(projectsCommand);
 program.addCommand(upCommand);
 program.addCommand(downCommand);
+program.addCommand(mcpCommand);
+program.addCommand(logsCommand);
 program.addCommand(ejectCommand);
 program.addCommand(importCommand);
 program.addCommand(statusCommand);

package/cli/dist/commands/doctor.js

@@ -9,7 +9,7 @@ import { MASTER_CONFIG_FILES, REQUIRED_PACKAGE_SCRIPTS } from "../utils/constant
 import { isPathDiscovered, readDiscoveryPaths } from "../utils/discovery-paths.js";
 import { collectDoctorChecks, createDoctorReport, getDoctorExitCode, } from "../utils/doctor-report.js";
 import { checkHealthRoutes, checkIngressPorts, checkPrivateNpmRegistry, checkTiltResourceHealth, projectConfigEnablesVerdaccio, summarizeServiceProbes, } from "../utils/doctor-runtime.js";
-import { checkDockerNetworkCapacity, checkFrontendBackendUrls, checkNatsBroker, checkResourcePackageJson, checkServiceUrlPorts, checkTiltInstances, } from "../utils/doctor-wiring.js";
+import { checkDockerNetworkCapacity, checkFrontendBackendUrls, checkMigrationsInApi, checkNatsBroker, checkResourcePackageJson, checkServiceUrlPorts, checkTiltInstances, } from "../utils/doctor-wiring.js";
 import { validateEnvFile } from "../utils/env-validator.js";
 import { execAsync, isExecTimeout } from "../utils/exec-async.js";
 import { formatCount } from "../utils/formatting.js";
@@ -1106,6 +1106,7 @@ export const doctorCommand = new Command("doctor")
         () => checkServiceUrlPorts(),
         () => checkFrontendBackendUrls(),
         () => checkNatsBroker(),
+        () => checkMigrationsInApi(),
         () => checkTiltInstances(),
         checkEnvironmentVariables,
         // Preflight: Verdaccio down causes ImageBuild bun install ConnectionRefused.

package/cli/dist/commands/logs.js

@@ -0,0 +1,85 @@
+import { Command } from "commander";
+import { STANDARD_PORTS } from "../utils/constants.js";
+import { runCommand, showErrorAndExit } from "../utils/errors.js";
+import { createMachineEnvelope } from "../utils/machine-output.js";
+import { isTiltAvailable, runTilt } from "../utils/tilt.js";
+import { DEFAULT_LOG_TAIL, isTiltConnectionFailure, isValidPort, isValidSince, isValidTail, MAX_LOG_TAIL, parseTiltLogLines, } from "../utils/tilt-logs.js";
+/** Resource names Tilt knows about, or null when they cannot be listed (the logs call then reports the real error). */
+async function tiltResourceNames(port) {
+    try {
+        const result = await runTilt("get", ["uiresources", "-o", "json", "--port", port], {
+            inheritStdio: false,
+        });
+        if (result.exitCode !== 0)
+            return null;
+        const items = JSON.parse(result.stdout)
+            .items;
+        return (items ?? []).flatMap((item) => (item.metadata?.name ? [item.metadata.name] : []));
+    }
+    catch {
+        return null;
+    }
+}
+export const logsCommand = new Command("logs")
+    .description("Print a bounded snapshot of recent logs from the running stack")
+    .option("-s, --service <names...>", "Only these services (Tilt resource names)")
+    .option("--tail <n>", "Number of most recent lines to return", String(DEFAULT_LOG_TAIL))
+    .option("--since <duration>", "Only logs newer than this duration, for example 30s, 5m, 1h")
+    .option("--port <n>", "Tilt UI port (default: TILT_PORT or 10350)")
+    .option("--json", "Output one JSON object and exit", false)
+    .action(async (options) => {
+    const fail = (code, message, exitCode = 1) => {
+        if (options.json) {
+            console.log(JSON.stringify(createMachineEnvelope(null, [{ code, message }])));
+            console.error(message);
+            process.exit(exitCode);
+        }
+        return showErrorAndExit(message, exitCode);
+    };
+    if (!isValidTail(options.tail))
+        fail("USAGE", `--tail must be an integer from 1 to ${MAX_LOG_TAIL}`, 2);
+    if (options.since !== undefined && !isValidSince(options.since)) {
+        fail("USAGE", "--since must be a duration such as 30s, 5m or 1h", 2);
+    }
+    const portText = options.port ?? process.env.TILT_PORT ?? String(STANDARD_PORTS.tiltUi);
+    if (!isValidPort(portText))
+        fail("USAGE", "--port must be a valid port number", 2);
+    const tail = Number(options.tail);
+    const services = options.service ?? [];
+    const action = async () => {
+        if (!(await isTiltAvailable())) {
+            fail("TILT_MISSING", "Tilt is not installed. Run: tdk doctor");
+        }
+        if (services.length > 0) {
+            const known = await tiltResourceNames(portText);
+            const unknown = services.filter((name) => known && !known.includes(name));
+            if (unknown.length > 0) {
+                fail("UNKNOWN_SERVICE", `Unknown service ${unknown.join(", ")}. Valid names: ${(known ?? []).join(", ")}`, 2);
+            }
+        }
+        const args = ["--port", portText, "--tail", String(tail)];
+        if (options.since !== undefined)
+            args.push("--since", options.since);
+        if (options.json)
+            args.push("--json");
+        // `--` so a service name that starts with "-" is never read as a Tilt flag.
+        if (services.length > 0)
+            args.push("--", ...services);
+        const result = await runTilt("logs", args, { inheritStdio: false });
+        if (result.exitCode !== 0) {
+            const detail = result.stderr.trim();
+            if (!detail || isTiltConnectionFailure(detail)) {
+                fail("TILT_NOT_RUNNING", `Could not reach Tilt on port ${portText}: ${detail || "is the stack running? Start it with: tdk up"}`);
+            }
+            fail("TILT_LOGS_FAILED", `tilt logs failed: ${detail}`);
+        }
+        if (!options.json) {
+            process.stdout.write(result.stdout);
+            return;
+        }
+        const lines = parseTiltLogLines(result.stdout, tail);
+        console.log(JSON.stringify(createMachineEnvelope({ services, tail, since: options.since ?? null, lines })));
+    };
+    await runCommand(action);
+});
+//# sourceMappingURL=logs.js.map

package/cli/dist/commands/mcp.js

@@ -0,0 +1,24 @@
+import { createInterface } from "node:readline";
+import { Command } from "commander";
+import { createMcpServer } from "../mcp/server.js";
+import { createTdkTools } from "../mcp/tools.js";
+import { getPackageVersion } from "../utils/paths.js";
+export const mcpCommand = new Command("mcp")
+    .description("Run a Model Context Protocol server over stdio for coding agents")
+    .action(async () => {
+    const server = createMcpServer(createTdkTools(), { name: "tdk", version: getPackageVersion() });
+    // Stdout is the protocol channel. Nothing else may write to it; diagnostics go to stderr.
+    const lines = createInterface({ input: process.stdin });
+    const pending = new Set();
+    lines.on("line", (line) => {
+        const task = server.handleLine(line).then((response) => {
+            if (response)
+                process.stdout.write(`${response}\n`);
+        });
+        pending.add(task);
+        void task.finally(() => pending.delete(task));
+    });
+    await new Promise((resolve) => lines.once("close", resolve));
+    await Promise.allSettled(pending);
+});
+//# sourceMappingURL=mcp.js.map

package/cli/dist/commands/projects.js

@@ -4,21 +4,42 @@ import chalk from "chalk";
 import { Command } from "commander";
 import { MASTER_CONFIG_FILES } from "../utils/constants.js";
 import { createDiscoveryContext } from "../utils/discovery-context.js";
-import { requireProjectRoot, runCommand } from "../utils/errors.js";
+import { errorFactories, requireProjectRoot, runCommand } from "../utils/errors.js";
 import { formatCount } from "../utils/formatting.js";
+import { createMachineEnvelope, writeMachineError } from "../utils/machine-output.js";
+import { findProjectRoot } from "../utils/paths.js";
 export const projectsCommand = new Command("projects")
     .description("Show project information and configuration status")
     .alias("info")
     .option("--check", "Check if project is properly configured", false)
+    .option("--json", "Output a versioned JSON response")
     .action(async (options) => {
-    await runCommand(async () => {
-        const projectRoot = requireProjectRoot();
+    const action = async () => {
+        const projectRoot = options.json ? findProjectRoot() : requireProjectRoot();
+        if (!projectRoot) {
+            throw errorFactories.notInProject();
+        }
+        const outDir = join(projectRoot, ".tdk", ".tdk-out");
+        const missing = MASTER_CONFIG_FILES.filter((file) => !existsSync(join(outDir, file)));
+        if (options.json) {
+            const discovery = createDiscoveryContext();
+            console.log(JSON.stringify(createMachineEnvelope({
+                projectRoot,
+                configured: missing.length === 0,
+                missingFiles: missing,
+                resources: discovery.resources.length,
+                stacks: discovery.stackNames,
+                unassignedResources: discovery.unassignedResources.length,
+            }), null, 2));
+            if (options.check) {
+                process.exitCode = missing.length === 0 ? 0 : 1;
+            }
+            return;
+        }
         console.log(chalk.blue("Project Information\n"));
         console.log(chalk.bold("Project Root:"));
         console.log(chalk.gray(`  ${projectRoot}`));
         console.log();
-        const outDir = join(projectRoot, ".tdk", ".tdk-out");
-        const missing = MASTER_CONFIG_FILES.filter((file) => !existsSync(join(outDir, file)));
         console.log(chalk.bold("Master Configuration:"));
         if (missing.length === 0) {
             for (const file of MASTER_CONFIG_FILES) {
@@ -66,6 +87,16 @@ export const projectsCommand = new Command("projects")
         if (options.check) {
             process.exit(missing.length === 0 ? 0 : 1);
         }
-    });
+    };
+    if (options.json) {
+        try {
+            await action();
+        }
+        catch (error) {
+            writeMachineError(error);
+        }
+        return;
+    }
+    await runCommand(action);
 });
 //# sourceMappingURL=projects.js.map

package/cli/dist/commands/resources.js

@@ -23,6 +23,7 @@ export const resourcesCommand = new Command("resources")
             requireProjectRoot();
         }
         const discovery = createDiscoveryContext();
+        const withoutStackFilter = options.noStack || options.stack === false;
         let resources = discovery.resources;
         if (options.stack) {
             resources = discovery.resourcesByStack.get(options.stack) || [];
@@ -31,7 +32,7 @@ export const resourcesCommand = new Command("resources")
                 return;
             }
         }
-        if (options.noStack) {
+        if (withoutStackFilter) {
             resources = discovery.unassignedResources;
             if (resources.length === 0 && !options.json) {
                 showAllSatisfyCondition("resources", "assigned to a stack");
@@ -85,7 +86,7 @@ export const resourcesCommand = new Command("resources")
         const withoutStackCount = options.stack
             ? resources.filter((r) => !r.stack).length
             : discovery.unassignedResources.length;
-        if (withoutStackCount > 0 && !options.noStack && !options.stack) {
+        if (withoutStackCount > 0 && !withoutStackFilter && !options.stack) {
             console.log(chalk.yellow(`\n${formatCount(withoutStackCount, "resource")} not assigned to any stack.`));
             showDetail('Run "tdk resources --no-stack" to see them, or "tdk stack" to assign them.');
         }

package/cli/dist/commands/stacks.js

@@ -3,19 +3,36 @@ import { Command } from "commander";
 import { createDiscoveryContext } from "../utils/discovery-context.js";
 import { runCommand } from "../utils/errors.js";
 import { formatCount, showDetail, showEmptyState, showStep } from "../utils/formatting.js";
+import { createMachineEnvelope, writeMachineError } from "../utils/machine-output.js";
+import { findProjectRoot } from "../utils/paths.js";
 export const stacksCommand = new Command("stacks")
     .description("List all stacks and their resources")
     .alias("ls") // Keep 'tdk ls' as shorthand
     .option("-v, --verbose", "Show detailed information about each stack", false)
     .option("--services", "Include list of services in each stack", false)
+    .option("--json", "Output a versioned JSON stack report", false)
     .action(async (options) => {
-    await runCommand(async () => {
+    const action = async () => {
+        if (options.json && !findProjectRoot()) {
+            writeMachineError(new Error("Could not find project root (no .tdk/project.json found)"));
+        }
         const discovery = createDiscoveryContext();
+        const verbose = options.verbose || stacksCommand.parent?.opts().verbose === true;
+        if (options.json) {
+            const stacks = discovery.stacks.map((stack) => ({
+                name: stack.name,
+                resourceCount: stack.resourceCount,
+                ...(verbose ? { description: stack.description } : {}),
+                ...(options.services ? { services: stack.resources.map((service) => service.name) } : {}),
+            }));
+            console.log(JSON.stringify(createMachineEnvelope({ stacks })));
+            return;
+        }
         if (discovery.stackNames.length === 0) {
             showEmptyState("stacks");
             return;
         }
-        if (options.verbose || options.services) {
+        if (verbose || options.services) {
             showStep(`Found ${formatCount(discovery.stacks.length, "stack")}:\n`);
             for (const stack of discovery.stacks) {
                 console.log(chalk.bold(`${stack.name}`));
@@ -38,6 +55,16 @@ export const stacksCommand = new Command("stacks")
             }
             showDetail("\nRun with --verbose for more details, or --services to see all services in each stack.", 0);
         }
-    });
+    };
+    if (options.json) {
+        try {
+            await action();
+        }
+        catch (error) {
+            writeMachineError(error);
+        }
+        return;
+    }
+    await runCommand(action);
 });
 //# sourceMappingURL=stacks.js.map

package/cli/dist/commands/status.js

@@ -1,6 +1,7 @@
 import chalk from "chalk";
 import { Command } from "commander";
 import { createDiscoveryContext } from "../utils/discovery-context.js";
+import { getDeferredResourceNames } from "../utils/doctor-runtime.js";
 import { runCommand } from "../utils/errors.js";
 import { formatCount, showDetail, showStep } from "../utils/formatting.js";
 import { getHostPortPlan } from "../utils/host-port-config.js";
@@ -8,6 +9,7 @@ import { createMachineEnvelope, writeMachineError } from "../utils/machine-outpu
 import { findProjectRoot } from "../utils/paths.js";
 import { buildServicePorts, buildStackPorts } from "../utils/status-ports.js";
 import { getTiltfilePath, isTiltAvailable, runTilt } from "../utils/tilt.js";
+import { evaluateTiltReadiness, tiltGetUiResources } from "../utils/up-readiness.js";
 export const statusCommand = new Command("status")
     .description("Show status of resources and stacks")
     .option("--json", "Output a versioned JSON status report", false)
@@ -53,6 +55,21 @@ export const statusCommand = new Command("status")
                 queryError = result.stderr || "Could not retrieve Tilt resource status";
             }
         }
+        // A single look at the running Tilt, so a caller that started `tdk up` detached can poll for readiness. Null when no
+        // Tilt answers or its output cannot be read.
+        let readiness = null;
+        if (options.json && tiltAvailable) {
+            const port = Number.parseInt(process.env.TILT_PORT ?? "", 10);
+            const text = await tiltGetUiResources(Number.isInteger(port) ? port : 10350);
+            if (text) {
+                try {
+                    readiness = evaluateTiltReadiness(text, getDeferredResourceNames()).result;
+                }
+                catch {
+                    readiness = null;
+                }
+            }
+        }
         if (options.json) {
             let portPlan = null;
             try {
@@ -68,6 +85,7 @@ export const statusCommand = new Command("status")
                     available: tiltAvailable,
                     resourcesQueried: options.tilt && tiltAvailable,
                     resources: tiltResources,
+                    readiness,
                 },
                 resources: discovery.resources.map((resource) => ({
                     name: resource.name,

package/cli/dist/commands/up.js

@@ -5,6 +5,7 @@ import { Command } from "commander";
 import { ensureProjectRuntimeAssets } from "../generator/template-engine.js";
 import { DEVCONTAINER_DOCKER_FIX, detectHost, isContainerHost, WEBCONTAINER_UP_MESSAGE, } from "../utils/agent-host.js";
 import { handleDryRun } from "../utils/command-helpers.js";
+import { getDeferredResourceNames } from "../utils/doctor-runtime.js";
 import { completeEnvFile } from "../utils/env-validator.js";
 import { errorFactories, handleTiltFailure, requireProjectRoot, runCommand, showErrorAndExit, withTiltCheck, } from "../utils/errors.js";
 import { formatCount } from "../utils/formatting.js";
@@ -15,11 +16,12 @@ import { findProjectRoot } from "../utils/paths.js";
 import { findAvailablePort } from "../utils/port-assignment.js";
 import { isApiServiceType } from "../utils/resource-kind.js";
 import { appendHealthPath, resolveSubdomainBases } from "../utils/service-urls.js";
-import { discoverResources, discoverStacks, getResourcesForStack, stackExists, } from "../utils/services.js";
+import { discoverResources, discoverResourcesStrict, discoverStacks, stackExists, } from "../utils/services.js";
 import { buildSmokePlans, formatSmokeFailure, runSmokePlans } from "../utils/smoke.js";
 import { buildTiltUpArgs, runTilt } from "../utils/tilt.js";
 import { stopTiltOnPort } from "../utils/tilt-process.js";
-import { waitForTiltResourcesReady } from "../utils/up-readiness.js";
+import { findUnknownServices, resolveOnlySelection } from "../utils/up-only.js";
+import { tiltGetUiResources, waitForTiltResourcesReady } from "../utils/up-readiness.js";
 import { enableDiscoveredStacks } from "./project.js";
 export function formatUpSuccess(port, appUrls = []) {
     return [
@@ -81,6 +83,7 @@ export const upCommand = new Command("up")
     .option("-q, --quiet", "Suppress non-essential output", false)
     .option("--dry-run", "Show what would be started without starting", false)
     .option("-f, --force", "Kill existing Tilt process before starting", false)
+    .option("--only <services...>", "Start only these services plus what the Tiltfile enables for them (their dependsOn services and shared infrastructure). With a stack, names must belong to that stack; dependencies may cross stacks")
     .option("--json", "Print one JSON object on stdout when the stack is ready or the command fails; implies --quiet", false)
     .action(async (stackName, options) => {
     const emit = options.json ? createJsonEmitter("UP_FAILED", "tdk up") : undefined;
@@ -102,6 +105,21 @@ export const upCommand = new Command("up")
         const projectRoot = options.dryRun
             ? requireProjectRoot()
             : (findProjectRoot() ?? process.cwd());
+        const discoveredResources = discoverResourcesStrict();
+        // Reject a bad request before anything below can write to the project (.env, runtime assets, .tdk/project.json).
+        if (options.only) {
+            if (stackName && !stackExists(stackName))
+                errorFactories.stackNotFound(stackName).exit();
+            const candidates = stackName
+                ? discoveredResources.filter((resource) => resource.stack === stackName)
+                : discoveredResources;
+            const unknown = findUnknownServices(options.only, candidates);
+            if (unknown.length > 0) {
+                const message = `Unknown service ${unknown.join(", ")}. Valid names: ${candidates.map((s) => s.name).join(", ")}`;
+                emit?.({ ok: false }, [{ code: "UNKNOWN_SERVICE", message }]);
+                showErrorAndExit(message, 2);
+            }
+        }
         const hostPortPlan = await getHostPortPlan(projectRoot, {
             inspectDocker: !options.dryRun,
         });
@@ -127,18 +145,27 @@ export const upCommand = new Command("up")
         let stackDescription;
         let focusServiceNames = [];
         if (stackName) {
-            if (!stackExists(stackName)) {
+            servicesToStart = discoveredResources.filter((resource) => resource.stack === stackName);
+            if (servicesToStart.length === 0) {
                 errorFactories.stackNotFound(stackName).exit();
             }
-            servicesToStart = getResourcesForStack(stackName);
             focusServiceNames = servicesToStart.map((s) => s.name);
             stackDescription = `stack "${stackName}"`;
         }
         else {
-            servicesToStart = discoverResources();
-            const allStacks = discoverStacks();
+            servicesToStart = discoveredResources;
+            const allStacks = discoverStacks(discoveredResources);
             stackDescription = `all stacks (${formatCount(allStacks.length, "stack")}, ${formatCount(servicesToStart.length, "service")})`;
         }
+        let dependencyNames = [];
+        if (options.only) {
+            // Dependencies come from the whole project, not just the named stack: dependsOn may cross stacks.
+            const selection = resolveOnlySelection(options.only, discoverResources());
+            servicesToStart = selection.selected;
+            dependencyNames = selection.dependencies;
+            focusServiceNames = servicesToStart.map((s) => s.name);
+            stackDescription = `${formatCount(options.only.length, "requested service")}${dependencyNames.length > 0 ? ` plus ${dependencyNames.join(", ")}` : ""}`;
+        }
         if (options.verbose && !options.quiet) {
             console.log(chalk.gray(`Found ${formatCount(servicesToStart.length, "service")} in ${stackDescription}`));
         }
@@ -171,9 +198,14 @@ export const upCommand = new Command("up")
                 });
             }
         }
-        const dryRunCommand = stackName
-            ? `tilt up -- --focus=${stackName} ${focusServiceNames.join(" ")}`
-            : "tilt up";
+        const focusTargets = options.only ?? (stackName ? [stackName] : undefined);
+        const tiltArgs = buildTiltUpArgs(focusServiceNames, {
+            verbose: options.verbose,
+            quiet: options.quiet,
+            force: options.force,
+            focusTargets,
+        });
+        const dryRunCommand = focusTargets ? `tilt up ${tiltArgs.join(" ")}` : "tilt up";
         if (!options.quiet) {
             console.log(chalk.blue(formatHostPortPlan(hostPortPlan)));
             console.log(chalk.gray("Override with TDK_HTTP_PORT, TDK_HTTPS_PORT, or TDK_POSTGRES_PORT."));
@@ -184,6 +216,9 @@ export const upCommand = new Command("up")
                 dryRun: true,
                 stack: stackName ?? null,
                 services: serviceNames,
+                ...(options.only
+                    ? { requested: options.only, declaredDependencies: dependencyNames }
+                    : {}),
                 command: dryRunCommand,
             });
             return;
@@ -195,6 +230,27 @@ export const upCommand = new Command("up")
         writeSavedHostPortPlan(projectRoot, hostPortPlan);
         const basePort = 10350;
         let port = basePort;
+        // A second Tilt would apply a different selection to the same containers, whatever port it listens on, so `--only`
+        // looks for a Tilt that answers on the default port and on TILT_PORT before it chooses one. A listener that is not
+        // Tilt does not count: the port is then picked below as usual.
+        if (options.only) {
+            const envPort = process.env.TILT_PORT ? Number.parseInt(process.env.TILT_PORT, 10) : NaN;
+            const candidatePorts = [
+                ...new Set([basePort, ...(Number.isInteger(envPort) ? [envPort] : [])]),
+            ];
+            const running = [];
+            for (const candidate of candidatePorts) {
+                if ((await tiltGetUiResources(candidate)) !== null)
+                    running.push(candidate);
+            }
+            if (running.length > 0 && !options.force) {
+                const message = `A Tilt is already running on port ${running.join(", ")}. --only cannot change a running stack's services: run \`tdk down\` first, or pass --force to replace it.`;
+                emit?.({ ok: false }, [{ code: "TILT_ALREADY_RUNNING", message }]);
+                showErrorAndExit(message);
+            }
+            for (const runningPort of running)
+                stopTiltOnPort(runningPort);
+        }
         if (process.env.TILT_PORT) {
             port = parseInt(process.env.TILT_PORT, 10);
         }
@@ -216,12 +272,6 @@ export const upCommand = new Command("up")
             stopTiltOnPort(port);
             await new Promise((resolve) => setTimeout(resolve, 2000));
         }
-        const tiltArgs = buildTiltUpArgs(focusServiceNames, {
-            verbose: options.verbose,
-            quiet: options.quiet,
-            force: options.force,
-            focusTargets: stackName ? [stackName] : undefined,
-        });
         if (!options.quiet) {
             console.log(chalk.gray("\nRunning tilt up..."));
             console.log(chalk.gray(`Using Tiltfile: .tdk/.tdk-out/Tiltfile`));
@@ -240,10 +290,26 @@ export const upCommand = new Command("up")
             const uiReady = await waitForTiltUi(port);
             // JSON consumers get success only after every non-deferred resource is built and running, not when the UI port opens.
             let jsonReady = false;
+            let startedServices = serviceNames;
+            let startedDependencies = dependencyNames;
             if (uiReady && emit) {
-                const readiness = await waitForTiltResourcesReady(port);
+                const deferred = getDeferredResourceNames();
+                const readiness = await waitForTiltResourcesReady(port, {
+                    deferred,
+                    // Only what the caller named must be enabled. Dependencies are the Tiltfile's call (it skips some on purpose).
+                    expected: options.only
+                        ? options.only.filter((name) => !deferred.has(name))
+                        : undefined,
+                });
                 if (readiness.ready) {
                     jsonReady = true;
+                    if (options.only) {
+                        // Report what Tilt actually enabled, not the service.json closure, which can differ from the Tiltfile's expansion.
+                        const enabled = new Set(readiness.enabled);
+                        const allNames = discoverResources().map((r) => r.name);
+                        startedServices = allNames.filter((name) => enabled.has(name));
+                        startedDependencies = startedServices.filter((name) => !options.only.includes(name));
+                    }
                 }
                 else {
                     const detail = readiness.failures.map((f) => `${f.name}: ${f.message}`).join("; ");
@@ -288,7 +354,8 @@ export const upCommand = new Command("up")
                 emit?.({
                     ok: true,
                     stack: stackName ?? null,
-                    services: serviceNames,
+                    services: startedServices,
+                    ...(options.only ? { requested: options.only, dependencies: startedDependencies } : {}),
                     tiltUrl: `http://localhost:${port}`,
                 });
             }

package/cli/dist/mcp/server.js

@@ -0,0 +1,100 @@
+/**
+ * A minimal Model Context Protocol server over newline-delimited JSON-RPC 2.0 (the stdio transport). It implements only
+ * what a tools-only server needs: initialize, ping, tools/list and tools/call. Keeping it dependency-free keeps the
+ * published CLI small; the protocol surface used here is stable across the listed protocol versions.
+ */
+export const SUPPORTED_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const ERROR = {
+    parse: -32700,
+    invalidRequest: -32600,
+    methodNotFound: -32601,
+    invalidParams: -32602,
+};
+function reply(id, result) {
+    return JSON.stringify({ jsonrpc: "2.0", id, result });
+}
+function fail(id, code, message) {
+    return JSON.stringify({ jsonrpc: "2.0", id: id ?? null, error: { code, message } });
+}
+export function createMcpServer(tools, info) {
+    const byName = new Map(tools.map((tool) => [tool.name, tool]));
+    async function handle(message) {
+        const isNotification = message.id === undefined;
+        if (message.jsonrpc !== "2.0" || typeof message.method !== "string") {
+            return isNotification ? null : fail(message.id, ERROR.invalidRequest, "Invalid request");
+        }
+        switch (message.method) {
+            case "initialize": {
+                const requested = String(message.params?.protocolVersion ?? "");
+                const protocolVersion = SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
+                    ? requested
+                    : SUPPORTED_PROTOCOL_VERSIONS[0];
+                return reply(message.id, {
+                    protocolVersion,
+                    capabilities: { tools: { listChanged: false } },
+                    serverInfo: info,
+                });
+            }
+            case "ping":
+                return reply(message.id, {});
+            case "tools/list":
+                return reply(message.id, {
+                    tools: tools.map(({ name, description, inputSchema }) => ({
+                        name,
+                        description,
+                        inputSchema,
+                    })),
+                });
+            case "tools/call": {
+                const name = message.params?.name;
+                const tool = typeof name === "string" ? byName.get(name) : undefined;
+                if (!tool)
+                    return fail(message.id, ERROR.invalidParams, `Unknown tool: ${String(name)}`);
+                const args = message.params?.arguments;
+                if (args !== undefined &&
+                    (typeof args !== "object" || args === null || Array.isArray(args))) {
+                    return fail(message.id, ERROR.invalidParams, "arguments must be an object");
+                }
+                try {
+                    const result = await tool.handler((args ?? {}));
+                    return reply(message.id, {
+                        content: [{ type: "text", text: JSON.stringify(result.data) }],
+                        structuredContent: result.data,
+                        isError: result.isError,
+                    });
+                }
+                catch (error) {
+                    // A tool failure is a tool result, not a protocol error, so the model can read and react to it.
+                    const text = error instanceof Error ? error.message : String(error);
+                    return reply(message.id, {
+                        content: [{ type: "text", text }],
+                        isError: true,
+                    });
+                }
+            }
+            default:
+                // Notifications such as notifications/initialized need no reply; unknown requests do.
+                return isNotification
+                    ? null
+                    : fail(message.id, ERROR.methodNotFound, `Method not found: ${message.method}`);
+        }
+    }
+    return {
+        async handleLine(line) {
+            if (!line.trim())
+                return null;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                return fail(null, ERROR.parse, "Parse error");
+            }
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                return fail(null, ERROR.invalidRequest, "Invalid request");
+            }
+            return handle(parsed);
+        },
+    };
+}
+//# sourceMappingURL=server.js.map