@flisk-sh/flisk 0.0.0-stage → 1.3.190

package/cli/dist/utils/down-cleanup.js

@@ -0,0 +1,125 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { execFileSync } from "node:child_process";
+const run = (command, args) => execFileSync(command, args, { encoding: "utf-8", stdio: "pipe", windowsHide: true });
+/** Network names the engine creates per project (see engine/.../docker/constants.star and init-networks). */
+const PROJECT_NETWORK_SUFFIXES = [
+    "traefik-public",
+    "traefik-private",
+    "backend",
+    "database",
+    "infisical-network",
+    "verdaccio-network",
+    "proxy",
+];
+/** The engine prefixes networks with the project name, hyphens turned into underscores. */
+export function projectNetworkNames(projectName) {
+    const prefix = projectName.replace(/-/g, "_");
+    return PROJECT_NETWORK_SUFFIXES.map((suffix) => `${prefix}_${suffix}`);
+}
+/**
+ * Prefixes of Flisk projects among `networkNames`, from the networks the engine creates. Generic suffixes such as
+ * `backend` also occur in non-Flisk compose projects, so a prefix counts only if it has a Traefik network, which
+ * only Flisk creates.
+ */
+export function tdkNetworkPrefixes(networkNames) {
+    const prefixes = new Set();
+    for (const name of networkNames) {
+        for (const marker of ["traefik-public", "traefik-private"]) {
+            if (name.endsWith(`_${marker}`))
+                prefixes.add(name.slice(0, -(marker.length + 1)));
+        }
+    }
+    return prefixes;
+}
+/** The Flisk project prefix a network belongs to (`umami` for `umami_backend`), or null. */
+export function tdkNetworkOwner(name, prefixes) {
+    for (const suffix of PROJECT_NETWORK_SUFFIXES) {
+        if (name.endsWith(`_${suffix}`)) {
+            const prefix = name.slice(0, -(suffix.length + 1));
+            if (prefixes.has(prefix))
+                return prefix;
+        }
+    }
+    return null;
+}
+/**
+ * Remove this project's own networks. Only the exact names the engine creates are touched, and `docker network rm`
+ * itself refuses a network that still has containers attached, so another project's networks and in-use networks
+ * are never removed.
+ */
+export function pruneProjectNetworks(projectName, commandRunner = run) {
+    const existing = new Set(commandRunner("docker", ["network", "ls", "--format", "{{.Name}}"])
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean));
+    const result = { removed: [], kept: [] };
+    for (const name of projectNetworkNames(projectName)) {
+        if (!existing.has(name))
+            continue;
+        try {
+            commandRunner("docker", ["network", "rm", name]);
+            result.removed.push(name);
+        }
+        catch (err) {
+            const stderr = String(err.stderr ?? err).trim();
+            result.kept.push({ name, reason: stderr.split(/\r?\n/)[0] ?? "" });
+        }
+    }
+    return result;
+}
+/**
+ * PIDs of `tilt up` processes started for this project's Tiltfile. Matching on the Tiltfile path keeps another
+ * project's Tilt (or a Tilt the user started by hand) untouched.
+ */
+export function findProjectTiltUpPids(tiltfilePath, platform = process.platform, commandRunner = run) {
+    if (platform === "win32")
+        return [];
+    let output;
+    try {
+        output = commandRunner("ps", ["-axo", "pid=,command="]);
+    }
+    catch {
+        return [];
+    }
+    const pids = [];
+    for (const line of output.split(/\r?\n/)) {
+        const match = /^\s*(\d+)\s+(.*)$/.exec(line);
+        if (!match)
+            continue;
+        const command = match[2] ?? "";
+        const exe = (command.split(/\s+/)[0] ?? "").split("/").at(-1);
+        const target = ` -f ${tiltfilePath}`;
+        const at = command.indexOf(target);
+        const boundary = command[at + target.length];
+        if (exe === "tilt" &&
+            /^\S+\s+up\s/.test(command) &&
+            at > 0 &&
+            (boundary === undefined || boundary === " ")) {
+            pids.push(Number(match[1]));
+        }
+    }
+    return pids;
+}
+export function stopProjectTiltUp(tiltfilePath, platform = process.platform, commandRunner = run) {
+    const pids = findProjectTiltUpPids(tiltfilePath, platform, commandRunner);
+    for (const pid of pids) {
+        try {
+            commandRunner("kill", ["-TERM", String(pid)]);
+        }
+        catch {
+            // Already gone.
+        }
+    }
+    return pids;
+}
+/** Wait (up to `timeoutMs`) for the `tilt up` processes to exit after TERM, so `tilt down` does not race a live Tilt. */
+export async function waitForTiltUpExit(tiltfilePath, timeoutMs = 8000, findPids = findProjectTiltUpPids) {
+    const deadline = Date.now() + timeoutMs;
+    while (findPids(tiltfilePath).length > 0) {
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    return true;
+}

package/cli/dist/utils/env-validator.js

@@ -0,0 +1,266 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeTextFileAtomic } from "./atomic-write.js";
+const REQUIRED_ENV_VARS = [
+    {
+        name: "VERDACCIO_URL_DOCKER",
+        description: "Docker-internal URL of the private npm registry (Verdaccio, a paid feature)",
+        // Verdaccio is a premium, off-by-default service, so a free project must not need its URL.
+        required: false,
+        default: "http://verdaccio:4873",
+        example: "http://verdaccio:4873",
+    },
+    {
+        name: "VERDACCIO_URL",
+        description: "Local URL of the private npm registry (Verdaccio, a paid feature)",
+        required: false,
+        default: "http://localhost:4873",
+    },
+    {
+        name: "TILT_ENV",
+        description: "Tilt environment name",
+        required: true,
+        default: "dev",
+        example: "dev",
+        complete: true,
+    },
+    {
+        name: "DATABASE_URL",
+        description: "PostgreSQL connection string (uses the generated DB_PASSWORD below)",
+        required: false,
+        // Built from DB_PASSWORD in generateEnvFile(); there is no shared literal password.
+    },
+    {
+        name: "DB_PASSWORD",
+        description: "PostgreSQL superuser password (docker-compose POSTGRES_PASSWORD)",
+        required: true,
+        // No static default: a shared password across every generated project is a
+        // credential leak waiting to happen. generateEnvFile() fills this one in with
+        // a fresh random value per project instead.
+        example: "postgres",
+        complete: true,
+    },
+    {
+        name: "JWT_SECRET",
+        description: "Secret that signs local-jwt tokens (generated once per project; never shared between projects)",
+        // Not required for `flisk doctor`: `flisk up` adds it to an older project's .env before starting anything.
+        required: false,
+        complete: true,
+    },
+];
+const generateDbPassword = () => randomBytes(16).toString("hex");
+const generateJwtSecret = () => randomBytes(32).toString("hex");
+function generatedValue(name, password) {
+    if (name === "DB_PASSWORD")
+        return password;
+    if (name === "JWT_SECRET")
+        return generateJwtSecret();
+    if (name === "DATABASE_URL")
+        return `postgresql://postgres:${password}@postgres:5432/app_dev`;
+    return REQUIRED_ENV_VARS.find((v) => v.name === name)?.default ?? "";
+}
+function parseEnvValue(raw) {
+    const value = raw.trim();
+    const quote = value[0];
+    if (quote === '"' || quote === "'") {
+        let escaped = false;
+        for (let index = 1; index < value.length; index += 1) {
+            const char = value[index];
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (char === "\\") {
+                escaped = true;
+                continue;
+            }
+            if (char === quote) {
+                const quoted = value.slice(1, index);
+                if (quote === '"') {
+                    const escapes = {
+                        n: "\n",
+                        r: "\r",
+                        t: "\t",
+                        '"': '"',
+                        "\\": "\\",
+                        $: "$",
+                    };
+                    return quoted.replace(/\\([nrt"\\$])/g, (_match, escapedChar) => escapes[escapedChar] ?? escapedChar);
+                }
+                return quoted.replace(/\\'/g, "'");
+            }
+        }
+        return value;
+    }
+    const commentIndex = raw.search(/\s#/);
+    return (commentIndex === -1 ? raw : raw.slice(0, commentIndex)).trim();
+}
+/** Parses the Compose-compatible subset used by Flisk for project environment files. */
+export function parseEnv(content) {
+    const result = new Map();
+    const normalized = content.startsWith("\uFEFF") ? content.slice(1) : content;
+    for (const rawLine of normalized.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const assignment = line.startsWith("export ") ? line.slice("export ".length).trim() : line;
+        const equals = assignment.indexOf("=");
+        if (equals <= 0)
+            continue;
+        const name = assignment.slice(0, equals).trim();
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+            continue;
+        result.set(name, parseEnvValue(assignment.slice(equals + 1)));
+    }
+    return result;
+}
+function describe(envVar) {
+    const lines = [`# ${envVar.description}`];
+    if (envVar.required)
+        lines.push("# Required (the value below is a working default)");
+    if (envVar.example)
+        lines.push(`# Example: ${envVar.example}`);
+    return lines;
+}
+export function generateEnvFile() {
+    const password = generateDbPassword();
+    const lines = [
+        "# 🔧 Flisk Environment Configuration",
+        "# Generated by `flisk project`. The defaults work as-is; edit only to change them.",
+        "# Keep this file out of git: it holds a generated database password and JWT secret.",
+        "#",
+        "# After editing, run: flisk config regenerate && flisk up",
+        "",
+    ];
+    for (const envVar of REQUIRED_ENV_VARS) {
+        lines.push(...describe(envVar));
+        lines.push(`${envVar.name}=${generatedValue(envVar.name, password)}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/** The password a postgres-style URL carries, or undefined when there is none or it is a variable reference. */
+function urlPassword(url) {
+    const match = url.match(/^[a-z][a-z0-9+.-]*:\/\/[^:/@\s]+:([^@\s]*)@/i);
+    if (!match || match[1].includes("$"))
+        return undefined;
+    return match[1];
+}
+export function validateEnvFile(projectRoot) {
+    const envPath = join(projectRoot, ".env");
+    const result = {
+        missing: [],
+        invalid: [],
+        warnings: [],
+    };
+    if (!existsSync(envPath)) {
+        return {
+            missing: REQUIRED_ENV_VARS.filter((v) => v.required).map((v) => v.name),
+            invalid: [],
+            warnings: [".env file not found - will be auto-generated"],
+        };
+    }
+    const env = parseEnv(readFileSync(envPath, "utf-8"));
+    for (const envVar of REQUIRED_ENV_VARS) {
+        if (envVar.required && !env.has(envVar.name)) {
+            result.missing.push(envVar.name);
+        }
+        if (env.has(envVar.name) && !(env.get(envVar.name) ?? "").trim()) {
+            result.invalid.push(`${envVar.name} is set but empty`);
+        }
+    }
+    const databaseUrl = env.get("DATABASE_URL");
+    const dbPassword = env.get("DB_PASSWORD");
+    if (databaseUrl && dbPassword) {
+        const inUrl = urlPassword(databaseUrl);
+        if (inUrl !== undefined && inUrl !== dbPassword) {
+            result.warnings.push("DATABASE_URL carries a different password than DB_PASSWORD; the database container uses DB_PASSWORD");
+        }
+    }
+    return result;
+}
+/**
+ * Replaces the value in one parsed assignment while preserving its prefix, inline comment, and line ending.
+ * The caller only uses this for assignments whose parsed value is empty or whitespace.
+ */
+function replaceEmptyEnvValue(line, name, value) {
+    const parsed = parseEnv(line);
+    if (!parsed.has(name))
+        return line;
+    const equalsIndex = line.indexOf("=");
+    if (equalsIndex < 0)
+        return line;
+    const rawValue = line.slice(equalsIndex + 1);
+    const commentIndex = rawValue.search(/\s#/);
+    const comment = commentIndex < 0 ? "" : rawValue.slice(commentIndex);
+    return line.slice(0, equalsIndex + 1) + value + comment;
+}
+/**
+ * Appends missing keys a newer CLI expects and fills empty generated keys in place.
+ * Non-empty values are not changed. Creates the file when it is missing.
+ *
+ * @returns the names that were added or filled in, empty when the file was already complete
+ */
+export function completeEnvFile(projectRoot) {
+    const envPath = join(projectRoot, ".env");
+    if (!existsSync(envPath)) {
+        writeFileSync(envPath, generateEnvFile(), { mode: 0o600 });
+        return REQUIRED_ENV_VARS.map((v) => v.name);
+    }
+    const existing = readFileSync(envPath, "utf-8");
+    const env = parseEnv(existing);
+    const toComplete = REQUIRED_ENV_VARS.filter((v) => {
+        if (!v.complete)
+            return false;
+        if (!env.has(v.name))
+            return true;
+        return !(env.get(v.name) ?? "").trim();
+    });
+    if (toComplete.length === 0)
+        return [];
+    const toAdd = toComplete.filter((v) => !env.has(v.name));
+    const toRepair = toComplete.filter((v) => env.has(v.name));
+    // Anything generated from the password must use the project's existing non-empty value.
+    const existingPassword = env.get("DB_PASSWORD");
+    const password = existingPassword?.trim() ? existingPassword : generateDbPassword();
+    const lines = existing.split(/(\r\n|\n|\r)/);
+    for (const envVar of toRepair) {
+        let lineIndex = -1;
+        for (let index = 0; index < lines.length; index += 2) {
+            if (parseEnv(lines[index]).has(envVar.name))
+                lineIndex = index;
+        }
+        if (lineIndex < 0) {
+            throw new Error(`Could not locate empty .env assignment for ${envVar.name}`);
+        }
+        lines[lineIndex] = replaceEmptyEnvValue(lines[lineIndex], envVar.name, generatedValue(envVar.name, password));
+    }
+    let updated = lines.join("");
+    if (toAdd.length > 0) {
+        const addedLines = [
+            "",
+            "# Added by Flisk: keys this version expects. Existing values above were not changed.",
+            "",
+        ];
+        for (const envVar of toAdd) {
+            addedLines.push(...describe(envVar));
+            addedLines.push(`${envVar.name}=${generatedValue(envVar.name, password)}`);
+            addedLines.push("");
+        }
+        const separator = updated.endsWith("\n") || updated.endsWith("\r") ? "" : "\n";
+        updated += separator + addedLines.join("\n");
+    }
+    writeTextFileAtomic(envPath, updated);
+    return toComplete.map((v) => v.name);
+}
+export function ensureEnvFile(projectRoot) {
+    const envPath = join(projectRoot, ".env");
+    if (!existsSync(envPath)) {
+        writeFileSync(envPath, generateEnvFile(), { mode: 0o600 });
+        return true;
+    }
+    return false;
+}

package/cli/dist/utils/errors.js

@@ -0,0 +1,175 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import chalk from "chalk";
+import { QUICKSTART_DOCS_URL } from "./constants.js";
+import { getContainerRuntimeStatus } from "./docker.js";
+import { findProjectRoot } from "./paths.js";
+import { suggestClosest } from "./suggestions.js";
+import { isTiltAvailable } from "./tilt.js";
+export function getErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export function logVerbose(message, err) {
+    if (process.env.TDK_VERBOSE) {
+        const errMsg = err !== undefined ? `: ${getErrorMessage(err)}` : "";
+        console.warn(chalk.gray(`${message}${errMsg}`));
+    }
+}
+export class TdkError extends Error {
+    suggestions;
+    exitCode;
+    constructor(message, suggestions = [], exitCode = 1) {
+        super(message);
+        this.name = "TdkError";
+        this.suggestions = suggestions;
+        this.exitCode = exitCode;
+    }
+    display() {
+        showError(this.message, undefined, this.suggestions);
+    }
+    /** Display this error and exit the process with its exit code. */
+    exit() {
+        this.display();
+        process.exit(this.exitCode);
+    }
+}
+/**
+ * Thrown by the `process.exit` test double so the stack unwinds at an intentional exit.
+ * `runCommand` rethrows it instead of formatting it as a command failure.
+ */
+export class ProcessExitError extends Error {
+    code;
+    constructor(code = 1) {
+        super(`process.exit(${code})`);
+        this.name = "ProcessExitError";
+        this.code = code;
+    }
+}
+function closestNameSuggestions(names, candidates, includeInput = false) {
+    const suggestions = new Set();
+    for (const name of names) {
+        const closest = suggestClosest(name, candidates);
+        if (closest) {
+            suggestions.add(includeInput ? `Did you mean "${closest}" for "${name}"?` : `Did you mean "${closest}"?`);
+        }
+    }
+    return [...suggestions];
+}
+export const errorFactories = {
+    tiltNotInstalled: () => new TdkError("Tilt CLI is not installed", [
+        "Install Tilt: `brew install tilt` (macOS)",
+        "Or download from: https://docs.tilt.dev/install.html",
+        "Verify with: `tilt version`",
+        `Setup guide: ${QUICKSTART_DOCS_URL}`,
+    ]),
+    dockerNotAvailable: () => new TdkError("Docker (or a compatible container runtime) is not running", [
+        "Start Docker Desktop, then verify with: `docker ps`",
+        "Or start Colima: `colima start`",
+        "Or start the Docker service on Linux: `sudo systemctl start docker`",
+        `Setup guide: ${QUICKSTART_DOCS_URL}`,
+    ]),
+    dockerNotResponding: () => new TdkError("Docker is running but not responding (`docker ps` hung for 10s)", [
+        "Quit and reopen Docker Desktop, or run `colima restart`",
+        "Then verify with: `docker ps`",
+    ]),
+    stackNotFound: (name, stackNames = []) => new TdkError(`Stack "${name}" not found`, [
+        ...closestNameSuggestions([name], stackNames),
+        "Run `flisk stacks` to see available stacks",
+        "Run `flisk stack` to assign resources to a stack",
+    ]),
+    resourceNotFound: (name, resourceNames = []) => new TdkError(`Resource "${name}" not found`, [
+        ...closestNameSuggestions([name], resourceNames),
+        "Run `flisk resources` to list all resources",
+        "Check the resource name spelling",
+    ]),
+    unknownServices: (names, validNames) => {
+        // Service selectors are Tilt resource names, so share the resource suggestion path.
+        const suggestions = closestNameSuggestions(names, validNames, names.length > 1);
+        return new TdkError(`Unknown service ${names.join(", ")}. Valid names: ${validNames.join(", ")}`, suggestions, 2);
+    },
+    directoryExists: (path) => new TdkError(`Directory already exists: ${path}`, [
+        "Use `--path` to specify a different location",
+        "Remove the existing directory if no longer needed",
+    ]),
+    invalidPath: (path) => new TdkError(`Invalid path: ${path}`, [
+        "Path must be within the project directory",
+        'Path cannot contain special characters like <>:"|?*',
+    ]),
+    notInProject: () => new TdkError("Could not find project root (no .tdk/project.json found)", [
+        "Run this from within a Flisk project",
+        "Run `flisk project --yes` to initialize a new project",
+    ]),
+};
+export function requireProjectRoot() {
+    const projectRoot = findProjectRoot();
+    if (!projectRoot) {
+        return errorFactories.notInProject().exit();
+    }
+    return projectRoot;
+}
+function handleCommandError(err) {
+    if (err instanceof TdkError) {
+        err.exit();
+    }
+    showError(getErrorMessage(err));
+    process.exit(1);
+}
+export async function runCommand(action, options) {
+    try {
+        return await action();
+    }
+    catch (err) {
+        if (err instanceof ProcessExitError) {
+            throw err;
+        }
+        if (options?.verbose && err instanceof Error && err.stack) {
+            console.error(chalk.gray(err.stack));
+        }
+        return handleCommandError(err);
+    }
+}
+export async function withTiltCheck(action, options) {
+    const problems = [];
+    const runtime = getContainerRuntimeStatus();
+    if (runtime === "unresponsive") {
+        problems.push(errorFactories.dockerNotResponding());
+    }
+    else if (runtime === "missing") {
+        problems.push(errorFactories.dockerNotAvailable());
+    }
+    if (!(await isTiltAvailable())) {
+        problems.push(errorFactories.tiltNotInstalled());
+    }
+    if (problems.length > 0) {
+        console.error(chalk.red(`\nFlisk can't start - missing prerequisites:\n`));
+        problems.forEach((problem, i) => {
+            if (i > 0)
+                console.error("");
+            problem.display();
+        });
+        console.error(chalk.gray(`\nRun \`flisk doctor\` for a full environment check.`));
+        process.exit(1);
+    }
+    return runCommand(action, options);
+}
+export function showErrorAndExit(message, exitCode = 1, suggestions) {
+    showError(message, undefined, suggestions);
+    process.exit(exitCode);
+}
+/** Display a formatted error message. Does NOT exit. */
+export function showError(message, context, suggestions) {
+    console.error(chalk.red(`❌ ${message}`));
+    if (context) {
+        console.error(chalk.gray(`   ${context}`));
+    }
+    if (suggestions && suggestions.length > 0) {
+        console.error(chalk.yellow("\n💡 Suggestions:"));
+        for (const s of suggestions) {
+            console.error(chalk.cyan(`   → ${s}`));
+        }
+    }
+}
+export function handleTiltFailure(command, exitCode) {
+    console.error(chalk.red(`\ntilt ${command} failed with exit code ${exitCode}`));
+    process.exit(exitCode);
+}

package/cli/dist/utils/exec-async.js

@@ -0,0 +1,31 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { exec, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { findOnPath } from "./which.js";
+const execPromise = promisify(exec);
+export const execAsync = async (command, timeoutMs) => {
+    if (process.platform === "win32") {
+        // Doctor commands are simple executable/argument invocations. Tokenize
+        // their quoted arguments and bypass cmd.exe/PowerShell entirely.
+        const parts = command.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+        const [parsedFile, ...args] = parts.map((part) => part.startsWith('"') || part.startsWith("'") ? part.slice(1, -1) : part);
+        if (!parsedFile)
+            throw new Error("Command is empty");
+        const file = findOnPath(parsedFile) ?? parsedFile;
+        const { stdout } = await promisify(execFile)(file, args, {
+            encoding: "utf-8",
+            timeout: timeoutMs,
+            windowsHide: true,
+            shell: false,
+        });
+        return stdout;
+    }
+    const { stdout } = await execPromise(command, { encoding: "utf-8", timeout: timeoutMs });
+    return stdout;
+};
+/** `exec` kills a timed-out child and sets `killed`; `execSync` reports ETIMEDOUT. */
+export function isExecTimeout(err) {
+    const e = err;
+    return e?.code === "ETIMEDOUT" || e?.killed === true;
+}