@flisk-sh/flisk 0.0.0-stage → 1.3.189

package/cli/dist/utils/cache.js

@@ -0,0 +1,63 @@
+export class Cache {
+    data;
+    options;
+    constructor(options) {
+        this.data = new Map();
+        this.options = options;
+    }
+    has(key) {
+        const entry = this.data.get(key);
+        if (!entry)
+            return false;
+        const isExpired = Date.now() - entry.timestamp > this.options.ttlMs;
+        if (isExpired) {
+            this.data.delete(key);
+            return false;
+        }
+        return true;
+    }
+    get(key) {
+        if (!this.has(key)) {
+            return undefined;
+        }
+        return this.data.get(key)?.value;
+    }
+    set(key, value) {
+        this.data.set(key, {
+            value,
+            timestamp: Date.now(),
+        });
+    }
+    delete(key) {
+        this.data.delete(key);
+    }
+    clear() {
+        this.data.clear();
+    }
+    keys() {
+        const validKeys = [];
+        for (const key of this.data.keys()) {
+            if (this.has(key)) {
+                validKeys.push(key);
+            }
+        }
+        return validKeys;
+    }
+    size() {
+        return this.keys().length;
+    }
+}
+export function createCacheValidator(ttlMs) {
+    let lastUpdated = 0;
+    return {
+        isValid() {
+            return Date.now() - lastUpdated < ttlMs;
+        },
+        markUpdated() {
+            lastUpdated = Date.now();
+        },
+        reset() {
+            lastUpdated = 0;
+        },
+    };
+}

package/cli/dist/utils/cold-preflight.js

@@ -0,0 +1,257 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { checkDockerCompose, checkDockerRuntime, checkDockerVersions, checkTilt, DOCTOR_FIXES, } from "../commands/doctor.js";
+import { BUN_FLOOR_LABEL, bunMeetsFloor } from "./bun-floor.js";
+import { projectNeedsBun } from "./bun-requirement.js";
+import { PROJECT_JSON } from "./constants.js";
+import { checkNatsBroker } from "./doctor-wiring.js";
+import { getHostPortPlan } from "./host-port-config.js";
+import { findProjectRoot } from "./paths.js";
+import { discoverResourcesFromRoot } from "./services.js";
+import { findOnPath } from "./which.js";
+/** Checks that only the local runtime (starting a stack) needs. */
+export const RUNTIME_CHECK_IDS = ["docker", "compose", "tilt"];
+/** Checks that writing project configuration needs. */
+export const SCAFFOLD_CHECK_IDS = ["node", "bun", "ports"];
+/** Every check that blocks a cold start, in report order. */
+export const MACHINE_CHECK_IDS = [
+    "node",
+    ...RUNTIME_CHECK_IDS,
+    "bun",
+    "ports",
+];
+/** Converts a doctor check result into the preflight's compact display item. */
+function item(id, result) {
+    return {
+        id,
+        ok: result.didPass || Boolean(result.isSkipped),
+        message: result.message,
+        fix: result.fix,
+    };
+}
+/** Returns whether a Node version is below the CLI's 22.12 minimum. */
+export function nodeTooOld(version) {
+    const [major = 0, minor = 0] = String(version)
+        .split(".")
+        .map((part) => Number.parseInt(part, 10));
+    return (!Number.isFinite(major) || !Number.isFinite(minor) || major < 22 || (major === 22 && minor < 12));
+}
+async function safeCheck(id, check, fallback) {
+    try {
+        return item(id, await check());
+    }
+    catch {
+        return { id, ok: false, message: fallback };
+    }
+}
+/** Requires a Docker engine and Compose version check to complete successfully. */
+export function requireVerifiedDockerVersions(result) {
+    if (!result.isSkipped)
+        return result;
+    return {
+        ...result,
+        didPass: false,
+        isSkipped: false,
+        message: `Could not verify Docker Engine/Compose minimum versions: ${result.message}`,
+        fix: result.fix ?? "Start Docker and ensure Docker Engine 25+ and Compose 2.20.2+ are installed.",
+    };
+}
+function usesPrisma(projectRoot) {
+    try {
+        return discoverResourcesFromRoot(projectRoot).some((resource) => {
+            return resource.config?.featuresEnabled?.includes("prisma") ?? false;
+        });
+    }
+    catch {
+        return false;
+    }
+}
+export async function runColdPreflight(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const scope = opts.scope ?? "runtime";
+    const projectRoot = findProjectRoot(cwd);
+    const inProject = Boolean(projectRoot);
+    const items = [];
+    const nodeVersion = process.versions.node;
+    items.push({
+        id: "node",
+        ok: !nodeTooOld(nodeVersion),
+        message: nodeVersion,
+        fix: nodeTooOld(nodeVersion)
+            ? `Install Node.js 22.12+ (current: ${nodeVersion}). https://nodejs.org`
+            : undefined,
+    });
+    // The runtime executables are only probed when the command actually starts a
+    // stack. Scaffolding a project must not depend on a running Docker daemon.
+    if (scope === "runtime") {
+        items.push(await safeCheck("docker", checkDockerRuntime, "Docker daemon is not running"));
+        items.push(await safeCheck("compose", async () => {
+            const [compose, versions] = await Promise.all([
+                checkDockerCompose(),
+                checkDockerVersions(),
+            ]);
+            if (!compose.didPass)
+                return compose;
+            return requireVerifiedDockerVersions(versions);
+        }, "Docker Engine or Compose version check failed"));
+        items.push(await safeCheck("tilt", checkTilt, "Tilt CLI not found"));
+    }
+    // Outside a project Bun stays required: `flisk project` is about to create services that need it.
+    const bunNeeded = projectRoot ? projectNeedsBun(discoverResourcesFromRoot(projectRoot)) : true;
+    let bun = false;
+    const bunPath = bunNeeded ? findOnPath("bun") : undefined;
+    if (bunPath) {
+        try {
+            const version = execFileSync(bunPath, ["--version"], {
+                encoding: "utf-8",
+                timeout: 3000,
+            }).trim();
+            bun = bunMeetsFloor(version);
+        }
+        catch {
+            /* reported as a failed runtime check */
+        }
+    }
+    items.push(bunNeeded
+        ? {
+            id: "bun",
+            ok: bun,
+            message: bun
+                ? `Bun ${BUN_FLOOR_LABEL} is available on PATH`
+                : `Bun ${BUN_FLOOR_LABEL} not found on PATH`,
+            fix: bun ? undefined : "curl -fsSL https://bun.sh/install | bash",
+        }
+        : { id: "bun", ok: true, message: "Bun not needed: no generated JS services" });
+    try {
+        // Scaffolding must not talk to Docker at all, so the port plan is planned
+        // from the host ports alone.
+        const plan = await getHostPortPlan(projectRoot ?? cwd, scope === "scaffold" ? { inspectDocker: false } : {});
+        items.push({
+            id: "ports",
+            ok: true,
+            message: `HTTP ${plan.ingressHttp}, HTTPS ${plan.ingressHttps}, Postgres ${plan.postgres}`,
+        });
+    }
+    catch (error) {
+        items.push({
+            id: "ports",
+            ok: false,
+            message: error instanceof Error ? error.message : String(error),
+            fix: "Set TDK_HTTP_PORT, TDK_HTTPS_PORT, or TDK_POSTGRES_PORT to available host ports.",
+        });
+    }
+    // Project wiring (NATS, Prisma database) describes a running stack, so it is
+    // only probed for the runtime scope.
+    if (projectRoot && scope === "runtime") {
+        const nats = await safeCheck("nats", () => checkNatsBroker(projectRoot), "NATS broker check failed");
+        if (!nats.ok)
+            items.push(nats);
+        if (usesPrisma(projectRoot)) {
+            let dbUp = false;
+            try {
+                const config = JSON.parse(readFileSync(join(projectRoot, ".tdk", PROJECT_JSON), "utf-8"));
+                const projectName = String(config?.project?.name ?? "").replace(/-/g, "_");
+                if (projectName) {
+                    const running = execFileSync(findOnPath("docker") ?? "docker", [
+                        "ps",
+                        "--filter",
+                        `label=com.docker.compose.project=${projectName}`,
+                        "--filter",
+                        "label=com.docker.compose.service=postgres",
+                        "--filter",
+                        "health=healthy",
+                        "--format",
+                        "{{.Names}}",
+                    ], { encoding: "utf-8", timeout: 3000 }).trim();
+                    dbUp = running.length > 0;
+                }
+            }
+            catch {
+                /* Docker unavailable is already represented by the machine checks. */
+            }
+            if (!dbUp)
+                items.push({
+                    id: "prisma",
+                    ok: false,
+                    message: "A Prisma resource is configured, but the project Postgres service is not healthy",
+                    fix: "Run `flisk up` to start the bundled Postgres, then check `flisk doctor`.",
+                });
+        }
+    }
+    const failures = items.filter((check) => !check.ok).slice(0, 8);
+    const blockingIds = scope === "scaffold" ? SCAFFOLD_CHECK_IDS : MACHINE_CHECK_IDS;
+    const machineFailed = failures.some((check) => blockingIds.includes(check.id));
+    const bunFailed = failures.some((check) => check.id === "bun");
+    const header = failures.length
+        ? machineFailed
+            ? scope === "scaffold"
+                ? bunFailed
+                    ? `Project setup blocked. Bun ${BUN_FLOOR_LABEL} must be installed on PATH.\nFix the machine checks below.`
+                    : "Project setup blocked. Fix the machine checks below."
+                : bunFailed
+                    ? `Cold start blocked. Bun ${BUN_FLOOR_LABEL} must be installed on PATH.\nPrisma/NATS configuration is project-specific and generated after \`flisk project\`. Fix the machine checks below.`
+                    : "Cold start blocked. Bun/Prisma/NATS are not the first failure.\nThey are generated after `flisk project`. Fix the machine checks below."
+            : "Machine is ready. Project wiring is not."
+        : "";
+    const footer = failures.length
+        ? ""
+        : inProject
+            ? "Environment ready for Flisk"
+            : "This machine is ready for Flisk.\nNext: flisk project --yes";
+    return { ok: failures.length === 0, inProject, items: failures, header, footer };
+}
+/** Formats only failed preflight checks and the applicable readiness message. */
+export function formatColdPreflight(result, options = {}) {
+    const lines = [result.header];
+    for (const check of result.items) {
+        lines.push(`FAIL ${check.id.padEnd(7)} ${check.message}`);
+        if (check.fix)
+            lines.push(`  ${check.fix}`);
+    }
+    if (result.footer && (options.includeSuccessFooter ?? true))
+        lines.push(result.footer);
+    return lines.filter(Boolean).join("\n");
+}
+/** Exits before machine-dependent command work when any machine check fails. */
+export async function assertMachineReadyOrExit(opts = {}) {
+    const scope = opts.scope ?? "runtime";
+    const result = await runColdPreflight({ scope });
+    const blockingIds = scope === "scaffold" ? SCAFFOLD_CHECK_IDS : MACHINE_CHECK_IDS;
+    const machineFailure = result.items.some((check) => blockingIds.includes(check.id));
+    if (machineFailure) {
+        console.error(formatColdPreflight(result));
+        process.exit(1);
+    }
+}
+/**
+ * Reports which runtime executables are installed.
+ *
+ * It only looks at `PATH`: no Docker daemon is contacted, so a machine without
+ * Docker still gets a usable answer.
+ */
+export function detectRuntimePrerequisites(find = findOnPath) {
+    return {
+        hasDockerCli: Boolean(find("docker")),
+        hasTiltCli: Boolean(find("tilt")),
+    };
+}
+/**
+ * Builds the next-step lines shown after project setup.
+ *
+ * Docker and Tilt are only needed to start the stack, so a missing runtime is
+ * reported as a hint instead of a failure.
+ */
+export function formatRuntimeNextSteps(status) {
+    const lines = [];
+    if (!status.hasDockerCli) {
+        lines.push(`Docker is not installed. ${DOCTOR_FIXES.dockerMissing}`);
+    }
+    if (!status.hasTiltCli) {
+        lines.push(`Tilt is not installed. ${DOCTOR_FIXES.tiltMissing}`);
+    }
+    lines.push("Docker and Tilt are only needed to start the stack: start them, then run `flisk doctor` (readiness) and `flisk up`.");
+    return lines;
+}

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

@@ -0,0 +1,57 @@
+import { showErrorAndExit } from "./errors.js";
+import { showCancelled } from "./formatting.js";
+import { promptConfirm } from "./prompt.js";
+export const YES_OPTION_FLAGS = "-y, --yes";
+export const YES_OPTION_DESCRIPTION = "Skip prompts and confirmations; use defaults";
+/**
+ * Registers the standard `-y, --yes` flag on a Commander command with shared help text.
+ */
+export function addYesOption(command, description = YES_OPTION_DESCRIPTION) {
+    return command.option(YES_OPTION_FLAGS, description, false);
+}
+export async function confirmAction(message, defaultValue = true) {
+    const confirm = await promptConfirm({ message, initial: defaultValue });
+    if (!confirm) {
+        showCancelled();
+    }
+    return confirm;
+}
+export function assertValid(validation, exitCode = 1) {
+    if (!validation.valid) {
+        showErrorAndExit(validation.error ?? "Validation failed", exitCode);
+    }
+}
+/**
+ * Early return for `--dry-run`. Prints the standard `Dry run - ...` / `Would run: ...` pair, or, when the command
+ * has a plan of its own to show (a list of files, say), calls `printPlan` instead. Returns true when it handled the run.
+ */
+export function handleDryRun(options, description, command, printPlan) {
+    if (options.dryRun) {
+        if (printPlan) {
+            printPlan();
+        }
+        else {
+            console.log(`Dry run - ${description}`);
+            console.log(`Would run: ${command}`);
+        }
+        return true;
+    }
+    return false;
+}
+/**
+ * Prompt for confirmation with cancellation handling.
+ * Displays a confirmation prompt and exits/cancels if user declines.
+ * @param message - The confirmation message to display
+ * @param onCancel - Optional callback when user cancels (defaults to returning false)
+ * @returns Promise<boolean> - true if confirmed, false if cancelled (with callback)
+ */
+export async function confirmOrCancel(message, onCancel) {
+    const confirmed = await confirmAction(message, true);
+    if (!confirmed) {
+        if (onCancel) {
+            onCancel();
+        }
+        return false;
+    }
+    return true;
+}

package/cli/dist/utils/constants.js

@@ -0,0 +1,160 @@
+// Name of the doctor check that verifies a container runtime is reachable.
+// It is looked up by name in doctor-report.ts, so both sides must use this
+// constant instead of a bare string literal.
+export const CONTAINER_RUNTIME_CHECK = "Container Runtime";
+// Resource type id for services the user brings themselves. Referenced by
+// value in several modules, so a typo in one copy would compile and silently
+// stop matching. `types/index.ts` keeps its own literal: it is the leaf module
+// that defines ResourceType, so importing this file back would be circular.
+// Typed as the literal (not the wider ResourceType union): computed keys built
+// from it stay narrow enough to satisfy Record<ResourceType, ...>.
+export const BRING_YOUR_OWN_TYPE = "bring-your-own";
+// Compile-time check that the literal above really is a ResourceType member.
+const _bringYourOwnIsResourceType = BRING_YOUR_OWN_TYPE;
+// Stack feature id for the shared platform database.
+export const DATABASE_MANAGEMENT_FEATURE = "database-management";
+// Root .tiltignore written by the generator and checked by doctor drift.
+export const TILTIGNORE_FILE = ".tiltignore";
+// Manifest file name for a resource, used by discovery and the resource command.
+export const SERVICE_JSON = "service.json";
+// Compose file name for service resources and platform features.
+export const DOCKER_COMPOSE_FILE = "docker-compose.yml";
+// Directory where generated manifests, configs, and Dockerfiles live within each resource.
+export const AUTOGENERATED_DIR = ".autogenerated";
+export const TECH_STACK_FILE = "TILT_TECH_STACK.star";
+export const RESOURCE_DEFAULTS_FILE = "TILT_RESOURCE_DEFAULTS.star";
+// Flisk project manifest file name. The canonical project config lives at
+// `<project-root>/.tdk/project.json` — discovery, doctor, generator, config
+// edits, and stack-features all read/write it. Referenced by value across
+// these modules, so a typo in one copy would compile and silently stop
+// matching (or worse, read a different file). Keep the literal here and
+// import it everywhere it's needed.
+export const PROJECT_JSON = "project.json";
+// Manifest file name for Node / JavaScript packages and root workspace.
+export const PACKAGE_JSON = "package.json";
+export const MASTER_CONFIG_FILES = [
+    TECH_STACK_FILE,
+    RESOURCE_DEFAULTS_FILE,
+    "spec.master",
+];
+export const VALID_RESOURCE_TYPES = [
+    "backend",
+    "frontend",
+    "library",
+    "sdk",
+    "worker",
+    "migrator",
+    "mcp",
+    "agent",
+    BRING_YOUR_OWN_TYPE,
+];
+// Frontend/library/sdk services are served statically or consumed as
+// packages, so they never need a "start" script - only backend/worker/
+// migrator processes are run in production via `<runtime> run start`.
+// bring-your-own doesn't generate application code, so no scripts required.
+export const REQUIRED_PACKAGE_SCRIPTS = {
+    backend: ["dev", "build", "start"],
+    worker: ["dev", "build", "start"],
+    migrator: ["dev", "build", "start"],
+    mcp: ["dev", "build", "start"],
+    agent: ["dev", "build", "start"],
+    frontend: ["dev", "build"],
+    library: ["dev", "build"],
+    sdk: ["dev", "build"],
+    [BRING_YOUR_OWN_TYPE]: [],
+};
+// Version specifiers that pin nothing at all - a fresh `bun install`/`npm install`
+// can pull a different (possibly breaking) version on every run.
+export const UNPINNED_DEPENDENCY_VERSIONS = new Set(["latest", "*"]);
+export const OPTIONAL_INFRA_SERVICES = [
+    "monitoring",
+    "elk",
+    "debezium",
+    "golden_image",
+    "verdaccio",
+];
+export const PORT_RANGES = {
+    frontend: { base: 3000, min: 3000, max: 3999, range: "3000-3999" },
+    backend: { base: 4000, min: 4000, max: 4999, range: "4000-4999" },
+    // An MCP server is an HTTP service, so it shares the backend-compatible range with bring-your-own.
+    mcp: { base: 4000, min: 4000, max: 5999, range: "4000-5999" },
+    // An agent serves /health and /ready over HTTP (see agent-runtimes/custom.ts), so it shares the same range.
+    agent: { base: 4000, min: 4000, max: 5999, range: "4000-5999" },
+    [BRING_YOUR_OWN_TYPE]: { base: 4000, min: 4000, max: 5999, range: "4000-5999" },
+    worker: { base: 6000, min: 6000, max: 6999, range: "6000-6999" },
+    health: { base: 5000, min: 5000, max: 5999, range: "5000-5999" },
+    migrator: { base: 7000, min: 7000, max: 7999, range: "7000-7999" },
+};
+export const STANDARD_PORTS = {
+    tiltUi: 10350,
+    traefik: 8080,
+};
+export const QUICKSTART_DOCS_URL = "https://tdk-landscape.github.io/tdk-website/docs/quickstart/";
+export const BASE_DOMAIN_DEFAULT = "tdk-project.localhost";
+export const APP_SUBDOMAIN_PREFIX = "app";
+export const API_SUBDOMAIN_PREFIX = "api";
+export function getBaseDomain() {
+    const override = process.env.TDK_SERVICE_BASE_URL ?? process.env.TDK_PUBLIC_HOST;
+    if (override) {
+        try {
+            const u = new URL(override.includes("://") ? override : `http://${override}`);
+            return u.hostname;
+        }
+        catch {
+            return override.replace(/^https?:\/\//, "").split("/")[0];
+        }
+    }
+    return BASE_DOMAIN_DEFAULT;
+}
+export function frontendBaseUrl(protocol = "http") {
+    return `${protocol}://${APP_SUBDOMAIN_PREFIX}.${getBaseDomain()}`;
+}
+export function apiBaseUrl(protocol = "http") {
+    return `${protocol}://${API_SUBDOMAIN_PREFIX}.${getBaseDomain()}`;
+}
+export const SKIP_DIRECTORIES = [
+    "node_modules",
+    ".git",
+    ".tilt",
+    ".tilt-engine",
+    "dist",
+    "build",
+    ".prisma",
+    ".turbo",
+    "coverage",
+    "tmp",
+    "temp",
+    "__tests__",
+    "test",
+    "tests",
+    ".github",
+    ".vscode",
+    "docs",
+];
+export const AUTOGENERATED_FILE_PATTERNS = [
+    "Dockerfile",
+    DOCKER_COMPOSE_FILE,
+    "docker-compose.yaml",
+    "Tiltfile",
+    "vite.config.ts",
+    "tsconfig.json",
+    "tsconfig.build.json",
+];
+// Stack emojis - generic, no hardcoded service names
+// Users can add their own stack emojis via project config
+const STACK_EMOJIS = {
+    infra: "🏗️",
+    core: "🔧",
+    api: "⚡",
+    app: "🎨",
+    orchestrator: "⚙️",
+};
+export function getStackEmoji(stackName) {
+    const lowerName = stackName.toLowerCase();
+    for (const [key, emoji] of Object.entries(STACK_EMOJIS)) {
+        if (lowerName.includes(key)) {
+            return emoji;
+        }
+    }
+    return "📦";
+}

package/cli/dist/utils/discovery-context.js

@@ -0,0 +1,71 @@
+import { findProjectRoot } from "./paths.js";
+import { discoverResources, discoverResourcesWithProblems, discoverStacks, getAllStacks, warnAboutSkippedFiles, } from "./services.js";
+const cachedContexts = new Map();
+/**
+ * Invalidate cached discovery contexts.
+ *
+ * Lifetime and invalidation contract:
+ * Discovery contexts are cached per `projectRoot` for the duration of a command invocation
+ * or process to eliminate repeated recursive filesystem traversals.
+ *
+ * Mutation contract:
+ * Any command that creates, mutates, or removes service manifests (`service.json`) or project
+ * templates (e.g. `flisk resource`, `flisk project example`, `flisk config migrate`) MUST call
+ * `clearDiscoveryCache()` so that subsequent discovery operations within the same process
+ * observe the updated filesystem state.
+ *
+ * @param projectRoot Optional project root to invalidate. If omitted, all cached contexts are cleared.
+ */
+export function clearDiscoveryCache(projectRoot) {
+    if (projectRoot !== undefined) {
+        cachedContexts.delete(projectRoot);
+    }
+    else {
+        cachedContexts.clear();
+    }
+}
+/**
+ * Create or retrieve the cached discovery context for the current project root.
+ *
+ * Caches discovery results (resources, problems, stacks, etc.) per project root to prevent
+ * redundant disk scans during multi-phase command lifecycles (e.g. `flisk up`).
+ *
+ * Different project roots maintain separate cache entries and never cross project boundaries.
+ *
+ * @param forceRefresh When true, bypasses any cached entry and forces a fresh filesystem scan.
+ */
+export function createDiscoveryContext(forceRefresh = false) {
+    const projectRoot = findProjectRoot();
+    const cacheKey = projectRoot ?? "";
+    if (!forceRefresh) {
+        const cached = cachedContexts.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+    }
+    const { resources, problems } = projectRoot
+        ? discoverResourcesWithProblems(projectRoot)
+        : { resources: discoverResources(), problems: [] };
+    const stacks = discoverStacks(resources);
+    const stackNames = getAllStacks(resources);
+    warnAboutSkippedFiles(problems);
+    const unassignedResources = resources.filter((r) => !r.stack);
+    const resourcesByStack = new Map();
+    for (const resource of resources) {
+        if (resource.stack) {
+            const stackResources = resourcesByStack.get(resource.stack) || [];
+            stackResources.push(resource);
+            resourcesByStack.set(resource.stack, stackResources);
+        }
+    }
+    const context = {
+        resources,
+        problems,
+        stacks,
+        stackNames,
+        unassignedResources,
+        resourcesByStack,
+    };
+    cachedContexts.set(cacheKey, context);
+    return context;
+}