@flisk-sh/flisk 1.4.2 → 1.4.6

package/cli/dist/utils/native-up.js

@@ -0,0 +1,156 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import chalk from "chalk";
+import { readEnvFileValues } from "./env-selection.js";
+import { showError } from "./errors.js";
+import { formatCount } from "./formatting.js";
+import { dependencyWaves, findMissingPrograms, formatPrefix, isPortListening, isProcessAlive, NATIVE_DIR, NativeSupervisor, nativeRunStatePath, planNativeRun, readNativeRunState, stopNativeRun, } from "./native-runtime.js";
+import { findPortOccupant } from "./port-occupant.js";
+/** Variables `${VAR}` in a service's env may reference: the env file of the run, overridden by the shell. */
+function runVariables(projectRoot, envFilePath) {
+    const path = envFilePath ?? join(projectRoot, ".env");
+    const fromFile = existsSync(path) ? Object.fromEntries(readEnvFileValues(path)) : {};
+    const fromShell = Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined));
+    return { ...fromFile, ...fromShell };
+}
+/**
+ * `flisk up` for a selection where every service declares `command`: no Docker, no Compose, no Tilt and no generated files.
+ * Resolves only when the run ends (Ctrl+C, `flisk down`, or a failed start, which exits 1).
+ */
+export async function runNativeUp(input) {
+    const { projectRoot, selected, emit } = input;
+    const exit = input.exit ?? ((code) => process.exit(code));
+    const quiet = Boolean(input.quiet);
+    const fail = (code, message, data = {}) => {
+        emit?.({ ok: false, runtime: "native", ...data }, [{ code, message }]);
+        showError(message);
+        return exit(1);
+    };
+    const vars = runVariables(projectRoot, input.envFilePath);
+    const plan = planNativeRun(selected, vars);
+    if (plan.errors.length > 0)
+        fail("INVALID_SERVICE_CONFIG", plan.errors.join("\n"));
+    if (plan.missingVars.length > 0 && !quiet) {
+        console.warn(chalk.yellow(`Unset variables expanded to an empty value: ${plan.missingVars.join(", ")}. Set them in .env or the shell.`));
+    }
+    const missing = findMissingPrograms(plan.services);
+    if (missing.length > 0) {
+        fail("NATIVE_COMMAND_NOT_FOUND", missing
+            .map(({ name, program }) => `service "${name}" runs ${program}, which is not installed (not found on PATH). Install it, or change "command" in its service.json.`)
+            .join("\n"));
+    }
+    const serviceNames = plan.services.map((service) => service.name);
+    const startOrder = dependencyWaves(plan.services);
+    const description = input.only
+        ? `${formatCount(input.only.length, "requested service")}${input.dependencies.length > 0 ? ` plus ${input.dependencies.join(", ")}` : ""}`
+        : input.stackName
+            ? `stack "${input.stackName}"`
+            : formatCount(serviceNames.length, "service");
+    if (!quiet) {
+        console.log(chalk.blue(`${input.dryRun ? "Would start" : "Starting"} ${description} as local processes (no Docker, no Tilt)...`));
+        for (const service of plan.services) {
+            const after = service.dependsOn.length > 0 ? ` (after ${service.dependsOn.join(", ")})` : "";
+            console.log(chalk.gray(`  - ${service.name}: ${service.command}${after}`));
+        }
+    }
+    if (input.dryRun) {
+        emit?.({
+            ok: true,
+            dryRun: true,
+            runtime: "native",
+            stack: input.stackName ?? null,
+            services: serviceNames,
+            ...(input.only ? { requested: input.only, declaredDependencies: input.dependencies } : {}),
+            startOrder,
+        });
+        if (!quiet)
+            console.log(chalk.yellow("Dry run: not starting services"));
+        return;
+    }
+    const running = readNativeRunState(projectRoot);
+    if (running && running.pid !== process.pid && isProcessAlive(running.pid)) {
+        if (!input.force) {
+            const message = `This project is already running as local processes (flisk up, pid ${running.pid}).`;
+            emit?.({ ok: true, alreadyRunning: true, runtime: "native", pid: running.pid });
+            if (!quiet) {
+                console.log(chalk.green(message));
+                console.log(chalk.gray("Stop it with flisk down, or pass --force to restart it."));
+            }
+            return;
+        }
+    }
+    if (running) {
+        // A previous run that was replaced (--force) or killed without cleaning up: stop whatever it left behind.
+        await stopNativeRun(projectRoot);
+    }
+    for (const service of plan.services) {
+        if (service.port !== undefined && (await isPortListening(service.port))) {
+            const occupant = findPortOccupant(service.port);
+            fail("PORT_IN_USE", `Port ${service.port} for service "${service.name}" is already in use${occupant ? ` by ${occupant.command} (pid ${occupant.pid})` : ""}. Stop it, or change "port" in the service.json.`);
+        }
+    }
+    const width = Math.max(...serviceNames.map((name) => name.length));
+    const prefix = (name) => formatPrefix(name, serviceNames.indexOf(name), width);
+    const supervisor = new NativeSupervisor(projectRoot, plan.services, {
+        onLine: quiet ? undefined : (name, line) => console.log(`${prefix(name)}${line}`),
+        onNote: quiet
+            ? undefined
+            : (name, message) => console.log(`${prefix(name)}${chalk.gray(`[flisk] ${message}`)}`),
+    }, { readyTimeoutMs: input.readyTimeoutMs, baseEnv: vars });
+    let stopping;
+    const stopAndExit = (code) => {
+        stopping ??= (async () => {
+            if (!quiet)
+                console.log(chalk.gray("\nStopping local processes..."));
+            await supervisor.stop();
+            exit(code);
+        })();
+    };
+    for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+        process.on(signal, () => stopAndExit(0));
+    }
+    // If every service exits for good, nothing keeps `flisk up` alive; it ends and must not leave a run.json behind.
+    process.once("exit", () => {
+        if (readNativeRunState(projectRoot)?.pid === process.pid) {
+            rmSync(nativeRunStatePath(projectRoot), { force: true });
+        }
+    });
+    const failures = await supervisor.start();
+    if (stopping)
+        return;
+    if (failures.length > 0) {
+        const message = [
+            "Local processes did not start:",
+            ...failures.map((failure) => `  ✗ ${failure.name}: ${failure.reason}`),
+            `Output of every service: ${join(NATIVE_DIR, "logs")}/<service>.log`,
+        ].join("\n");
+        emit?.({ ok: false, runtime: "native", failures }, [{ code: "UP_RESOURCE_FAILED", message }]);
+        showError(message);
+        await supervisor.stop();
+        exit(1);
+        return;
+    }
+    emit?.({
+        ok: true,
+        runtime: "native",
+        stack: input.stackName ?? null,
+        services: serviceNames,
+        ...(input.only ? { requested: input.only, dependencies: input.dependencies } : {}),
+        urls: Object.fromEntries(plan.services.flatMap((service) => (service.url ? [[service.name, service.url]] : []))),
+    });
+    if (!quiet) {
+        const lines = ["Flisk is up (local processes, no Docker).", "Services:"];
+        for (const service of plan.services) {
+            const health = service.healthUrl ? ` (health: ${service.healthUrl})` : "";
+            lines.push(`  ✓ ${service.name}${service.url ? ` → ${service.url}` : ""}${health}`);
+        }
+        lines.push("Stop: Ctrl+C here, or flisk down from another terminal");
+        lines.push(`Logs: flisk logs --service <name>, or ${join(NATIVE_DIR, "logs")}/<service>.log`);
+        for (const line of lines)
+            console.log(chalk.blue(line));
+    }
+    // The services keep the process alive; `flisk up` ends when it is stopped.
+    await new Promise(() => { });
+}

package/cli/dist/utils/platform.js

@@ -33,7 +33,7 @@ export function binaryAssetNameFor(platformName, architecture) {
         return null;
     if (osName === "windows" && archName !== "amd64")
         return null;
-    const base = `tdk-${osName}-${archName}`;
+    const base = `flisk-${osName}-${archName}`;
     return osName === "windows" ? `${base}.exe` : base;
 }
 export function binaryAssetName() {

package/cli/dist/utils/port-conflict-fix.js

@@ -1,25 +1,27 @@
-// Copyright (c) 2026 Flisk Landscape contributors
-// SPDX-License-Identifier: MIT
 /** The env var that moves each host port Flisk publishes. Services publish no host ports, so only these conflict. */
 const PORT_ENV_VARS = {
     "80": "FLISK_HTTP_PORT",
     "443": "FLISK_HTTPS_PORT",
     "5432": "FLISK_POSTGRES_PORT",
 };
-/**
- * The next step for a host port another process already holds. The occupant is not named: finding it needs the OS, so
- * the command that finds it is given instead.
- */
-export function portConflictFix(message) {
+/** The host port a conflict message is about, or null when the message is not a port conflict. */
+export function conflictPort(message) {
     // The raw Docker error can reach the report when the readiness check fails before the summary runs.
     const match = message.match(/^host port (\d+) is already allocated$/) ??
         message.match(/Bind for [^ ]+:(\d+) failed: port is already allocated/i);
-    if (!match)
+    return match ? Number(match[1]) : null;
+}
+/**
+ * The next step for a host port another process already holds. When the occupant is known it is named; otherwise the
+ * command that finds it is given instead.
+ */
+export function portConflictFix(message, occupant = null) {
+    const port = conflictPort(message);
+    if (port === null)
         return null;
-    const port = match[1];
-    const find = `find it with: lsof -nP -iTCP:${port} -sTCP:LISTEN`;
-    const envVar = PORT_ENV_VARS[port];
-    if (!envVar)
-        return `Fix: stop the process using port ${port} (${find})`;
-    return `Fix: stop the process using port ${port} (${find}), or set ${envVar} to a free port and run flisk up`;
+    const envVar = PORT_ENV_VARS[String(port)];
+    const body = occupant
+        ? `Fix: port ${port} is held by ${occupant.command} (pid ${occupant.pid}). Stop it`
+        : `Fix: stop the process using port ${port} (find it with: lsof -nP -iTCP:${port} -sTCP:LISTEN)`;
+    return envVar ? `${body}, or set ${envVar} to a free port and run flisk up` : body;
 }

package/cli/dist/utils/port-occupant.js

@@ -0,0 +1,35 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { execFileSync } from "node:child_process";
+import { basename } from "node:path";
+const run = (command, args) => execFileSync(command, args, {
+    encoding: "utf-8",
+    stdio: "pipe",
+    timeout: 5000,
+    windowsHide: true,
+});
+/**
+ * The process listening on `port`, or null when it cannot be told (no lsof, Windows, nothing listens, or the process
+ * exited before ps could read it). Callers must treat null as "unknown", not as "free".
+ */
+export function findPortOccupant(port, platform = process.platform, commandRunner = run) {
+    if (platform === "win32")
+        return null;
+    try {
+        const [first] = commandRunner("lsof", ["-nP", "-t", `-iTCP:${port}`, "-sTCP:LISTEN"])
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean);
+        if (!first)
+            return null;
+        const pid = Number(first);
+        const name = commandRunner("ps", ["-p", first, "-o", "comm="]).trim();
+        if (!Number.isInteger(pid) || !name)
+            return null;
+        return { pid, command: basename(name) };
+    }
+    catch {
+        // lsof exits 1 when nothing listens, and may be missing.
+        return null;
+    }
+}

package/cli/dist/utils/project-features.js

@@ -70,22 +70,13 @@ export const PROJECT_FEATURES = {
     },
 };
 /**
- * Get all enabled project features
+ * Get all enabled project features: those on by default plus those switched
+ * on in `optional_infra`. Each feature appears once, in `PROJECT_FEATURES`
+ * order. Names that are not features are ignored, and `false` does not turn
+ * off a feature that is on by default.
  */
 export function getEnabledProjectFeatures(optional_infra) {
-    const enabled = [];
-    for (const [key, feature] of Object.entries(PROJECT_FEATURES)) {
-        if (feature.enabled_by_default) {
-            enabled.push(key);
-        }
-    }
-    // Add optional features if enabled
-    if (optional_infra) {
-        for (const [key, isEnabled] of Object.entries(optional_infra)) {
-            if (isEnabled && PROJECT_FEATURES[key]) {
-                enabled.push(key);
-            }
-        }
-    }
-    return enabled;
+    return Object.entries(PROJECT_FEATURES)
+        .filter(([key, feature]) => feature.enabled_by_default || optional_infra?.[key] === true)
+        .map(([key]) => key);
 }

package/cli/dist/utils/project-templates.js

@@ -1,37 +1,37 @@
 /** Public starter repositories plus the bundled default product example. */
 export const PROJECT_TEMPLATES = {
     demo: {
-        repo: "https://github.com/flisk-sh/tdk-restaurant-example.git",
+        repo: "https://github.com/flisk-sh/flisk-restaurant-example.git",
         description: "The demo stack: restaurant ops with reservations, kitchen and floor control",
         fixedDir: "flisk-demo",
     },
     restaurant: {
-        repo: "https://github.com/flisk-sh/tdk-restaurant-example.git",
+        repo: "https://github.com/flisk-sh/flisk-restaurant-example.git",
         description: "Restaurant ops: reservations, kitchen, floor control (Hono + Vite + Bun)",
     },
     saas: {
-        repo: "https://github.com/flisk-sh/tdk-saas-starter.git",
+        repo: "https://github.com/flisk-sh/flisk-saas-starter.git",
         description: "SaaS starter: account dashboard and a working checkout button (Hono + Vite + Bun)",
     },
     erp: {
-        repo: "https://github.com/flisk-sh/tdk-erp-system.git",
+        repo: "https://github.com/flisk-sh/flisk-erp-system.git",
         description: "Enterprise ERP: 100 microservices across 7 business domains",
     },
     "user-management": {
-        repo: "https://github.com/flisk-sh/tdk-user-management.git",
+        repo: "https://github.com/flisk-sh/flisk-user-management.git",
         description: "User/auth management services",
     },
     ecommerce: {
-        repo: "https://github.com/flisk-sh/tdk-ecommerce-example.git",
+        repo: "https://github.com/flisk-sh/flisk-ecommerce-example.git",
         description: "Vue 3 storefront and Hono catalog API (needs Flisk 1.3.75+ for --framework vue)",
     },
     example: {
-        repo: "https://github.com/flisk-sh/tdk-example.git",
-        bundledPath: "examples/tdk-example",
+        repo: "https://github.com/flisk-sh/flisk-example.git",
+        bundledPath: "examples/flisk-example",
         description: "Hono + Postgres + NATS worker + Vite example with a routed write path",
     },
     "agent-stack": {
-        repo: "https://github.com/flisk-sh/tdk-agent-stack.git",
+        repo: "https://github.com/flisk-sh/flisk-agent-stack.git",
         description: "AI agent stack: Bun agent + MCP tool server + Postgres + NATS",
     },
 };

package/cli/dist/utils/resource-features.js

@@ -160,15 +160,15 @@ export const RESOURCE_FEATURES = {
 /**
  * Get default features for a resource type
  */
-export function getDefaultFeaturesForResourceType(appType) {
+export function getDefaultFeaturesForResourceType(resourceType) {
     // bring-your-own doesn't generate application code, so no features
-    if (appType === BRING_YOUR_OWN_TYPE) {
+    if (resourceType === BRING_YOUR_OWN_TYPE) {
         return [];
     }
     const defaults = [];
     for (const [key, feature] of Object.entries(RESOURCE_FEATURES)) {
         if (feature.enabled_by_default &&
-            feature.applies_to.includes(appType) &&
+            feature.applies_to.includes(resourceType) &&
             // Only include if it's something users control via features array
             ["api-client", "env-config", "api-index", "prisma"].includes(key)) {
             defaults.push(key);
@@ -179,6 +179,6 @@ export function getDefaultFeaturesForResourceType(appType) {
 /**
  * Get all generators for a resource type (for documentation)
  */
-export function getGeneratorsForResourceType(appType) {
-    return Object.values(RESOURCE_FEATURES).filter((f) => f.applies_to.includes(appType));
+export function getGeneratorsForResourceType(resourceType) {
+    return Object.values(RESOURCE_FEATURES).filter((f) => f.applies_to.includes(resourceType));
 }

package/cli/dist/utils/service-manifest.js

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 Flisk Landscape contributors
 // SPDX-License-Identifier: MIT
 import { existsSync, readFileSync } from "node:fs";
+import { declaresCommand, validateNativeServiceFields } from "./native-service.js";
 import { validateSmoke } from "./smoke.js";
 export const SERVICE_MANIFEST_SCHEMA_VERSION = 1;
 export const SERVICE_MANIFEST_SCHEMA_URL = "https://flisk.sh/schema.service.json";
@@ -24,12 +25,14 @@ const KNOWN_SERVICE_FIELDS = new Set([
     "basePath",
     "build",
     "buildContext",
+    "command",
     "databaseName",
     "dependencies",
     "dev",
     "dependsOn",
     "dockerfile",
     "enabled",
+    "env",
     "exposeViaProxy",
     "featuresEnabled",
     "framework",
@@ -87,6 +90,7 @@ const GENERATED_STRING_FIELDS = [
         pattern: /^[A-Za-z0-9._/:@-]+$/,
         expected: "an image reference such as ghcr.io/acme/app:1.0",
     },
+    { path: ["basePath"], pattern: /^\/[a-z0-9/-]*$/, expected: "a path such as /storefront" },
 ];
 /**
  * Errors for generated-output fields whose values could change the generated YAML. The value itself is not echoed, because it may
@@ -182,9 +186,21 @@ export function validateServiceManifest(value, displayPath) {
     }
     const manifest = value;
     const errors = [];
-    for (const field of ["appName", "appType", "stack", "schemaVersion"]) {
-        if (!(field in manifest))
-            errors.push(`${displayPath}.${field}: required field is missing`);
+    // A `command` service needs only a name and schemaVersion: it runs as a local process, so it has no app type, stack or
+    // generated output to describe (the minimal contract in utils/native-service.ts). Every other service keeps the full set.
+    if (declaresCommand(manifest)) {
+        if (!("appName" in manifest) && typeof manifest.name !== "string") {
+            errors.push(`${displayPath}.name: required field is missing`);
+        }
+        if (!("schemaVersion" in manifest)) {
+            errors.push(`${displayPath}.schemaVersion: required field is missing`);
+        }
+    }
+    else {
+        for (const field of ["appName", "appType", "stack", "schemaVersion"]) {
+            if (!(field in manifest))
+                errors.push(`${displayPath}.${field}: required field is missing`);
+        }
     }
     for (const field of ["appName", "appType", "stack"]) {
         if (field in manifest && typeof manifest[field] !== "string") {
@@ -205,6 +221,7 @@ export function validateServiceManifest(value, displayPath) {
         errors.push(`${displayPath}.dev.liveReload: expected true or false`);
     }
     errors.push(...validateGeneratedStringFields(manifest, displayPath));
+    errors.push(...validateNativeServiceFields(manifest).map((error) => `${displayPath}: ${error}`));
     if ("smoke" in manifest) {
         for (const message of validateSmoke(manifest.smoke))
             errors.push(`${displayPath}.${message}`);

package/cli/dist/utils/service-urls.js

@@ -64,6 +64,17 @@ export function resolveServicePath(resource) {
     }
     return resource.config?.basePath ?? `/${resource.name}`;
 }
+/**
+ * The ingress URL of one service (no /health suffix), or undefined for services with no Traefik route. This is where the service
+ * answers, unlike the Tilt UI port, which serves its own page for any path.
+ */
+export function resolveServiceUrl(resource, ingressPort) {
+    const appType = resource.config?.appType;
+    if (appType !== "frontend" && !isApiServiceType(appType))
+        return undefined;
+    const { appBase, apiBase } = resolveSubdomainBases(ingressPort);
+    return `${appType === "frontend" ? appBase : apiBase}${resolveServicePath(resource)}`;
+}
 /**
  * Health URLs for every routable service, matching what `flisk up` prints.
  * Workers, libraries, SDKs and migrators have no Traefik route, so they are

package/cli/dist/utils/services.js

@@ -3,9 +3,10 @@
 import fs, { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { Cache, createCacheValidator } from "./cache.js";
-import { AUTOGENERATED_FILE_PATTERNS, DOCKER_COMPOSE_FILE, PACKAGE_JSON, SERVICE_JSON, SKIP_DIRECTORIES, } from "./constants.js";
+import { AUTOGENERATED_FILE_PATTERNS, BRING_YOUR_OWN_TYPE, DOCKER_COMPOSE_FILE, PACKAGE_JSON, SERVICE_JSON, SKIP_DIRECTORIES, } from "./constants.js";
 import { errorFactories } from "./errors.js";
 import { formatCount } from "./formatting.js";
+import { declaresCommand, validateNativeServiceFields } from "./native-service.js";
 import { findProjectRoot } from "./paths.js";
 import { getInvalidServiceRoutePathFields, validateGeneratedStringFields, validateServiceManifest, } from "./service-manifest.js";
 import { deriveStackStatus } from "./stack-status.js";
@@ -40,6 +41,10 @@ function isValidResourceConfig(value) {
     if (!value || typeof value !== "object")
         return false;
     const config = value;
+    // A `command` service (the minimal contract) needs only a name, as appName or name.
+    if (declaresCommand(config)) {
+        return typeof config.appName === "string" || typeof config.name === "string";
+    }
     // Accept runtime, appType, or type (for backward compatibility with existing service.json files)
     const hasRuntimeOrAppType = typeof config.runtime === "string" ||
         typeof config.appType === "string" ||
@@ -81,6 +86,9 @@ function parseResource(serviceJsonPath) {
     if (!isValidResourceConfig(parsed)) {
         throw new InvalidServiceJsonError("missing required fields (appName, runtime or appType)");
     }
+    const nativeErrors = validateNativeServiceFields(parsed);
+    if (nativeErrors.length > 0)
+        throw new InvalidServiceJsonError(nativeErrors.join("; "));
     const invalidRoutePathFields = getInvalidServiceRoutePathFields(parsed);
     if (invalidRoutePathFields.length > 0) {
         throw new InvalidServiceJsonError(invalidRoutePathFields.map((field) => `${field}: expected a string`).join("; "));
@@ -98,8 +106,13 @@ function parseResource(serviceJsonPath) {
     }
     const config = {
         ...parsedConfig,
+        appName: parsedConfig.appName ?? String(parsedConfig.name),
+        // A `command` service without a type is the user's own program, like a bring-your-own container.
         appType: (parsedConfig.appType ||
-            parsedConfig.type),
+            parsedConfig.type ||
+            (declaresCommand(parsedConfig)
+                ? BRING_YOUR_OWN_TYPE
+                : undefined)),
     };
     const resourceDir = dirname(serviceJsonPath);
     return {

package/cli/dist/utils/startup-report.js

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 Flisk Landscape contributors
 // SPDX-License-Identifier: MIT
 import { parseTiltResourceFailures, summarizeTiltBuildError } from "./doctor-runtime.js";
-import { portConflictFix } from "./port-conflict-fix.js";
+import { conflictPort, portConflictFix } from "./port-conflict-fix.js";
 import { effectiveRuntimeStatus, isTiltResourcePending } from "./tilt-resource-state.js";
 import { onlyEnabledResources } from "./up-readiness.js";
 export function transitiveDependencies(name, dependsOn) {
@@ -52,11 +52,12 @@ export function isStartupStalled(jsonText, dependsOn, deferred = new Set()) {
     const report = buildStartupReport(jsonText, dependsOn, deferred);
     return report.failed.length > 0 && report.starting.length === 0;
 }
-export function formatStartupReport(report, timedOut) {
+export function formatStartupReport(report, timedOut, occupantOf) {
     const lines = [];
     for (const { name, message } of report.failed) {
         lines.push(`✗ ${name} failed: ${message}`);
-        const fix = portConflictFix(message);
+        const port = conflictPort(message);
+        const fix = portConflictFix(message, port !== null && occupantOf ? occupantOf(port) : null);
         if (fix)
             lines.push(`  ${fix}`);
     }

package/cli/dist/utils/tar.js

@@ -7,40 +7,45 @@ import { join } from "node:path";
 /**
  * Extracts a gzipped tarball (as an in-memory buffer) into destDir.
  * Shells out to the system `tar` binary rather than pulling in a JS tar
- * implementation - available by default on macOS and Linux.
+ * implementation - available by default on macOS and Linux. On Windows it
+ * runs `tar.exe`, which ships with Windows 10 (1803) and later; see
+ * docs/windows-hardware.md.
  */
 export function extractTarball(data, destDir) {
     const tempDir = mkdtempSync(join(tmpdir(), "flisk-ext-"));
-    const tmpFile = join(tempDir, "bundle.tar.gz");
-    writeFileSync(tmpFile, data);
-    mkdirSync(destDir, { recursive: true });
-    const tarBin = process.platform === "win32" ? "tar.exe" : "tar";
-    const result = spawnSync(tarBin, ["xzf", tmpFile, "-C", destDir, "--strip-components=1"], {
-        stdio: "pipe",
-        windowsHide: true,
-    });
-    if (result.status !== 0) {
-        const fallbackDir = join(tempDir, "fallback");
-        mkdirSync(fallbackDir, { recursive: true });
-        const fallback = spawnSync(tarBin, ["xzf", tmpFile, "-C", fallbackDir], {
+    try {
+        const tmpFile = join(tempDir, "bundle.tar.gz");
+        writeFileSync(tmpFile, data);
+        mkdirSync(destDir, { recursive: true });
+        const tarBin = process.platform === "win32" ? "tar.exe" : "tar";
+        const result = spawnSync(tarBin, ["xzf", tmpFile, "-C", destDir, "--strip-components=1"], {
             stdio: "pipe",
             windowsHide: true,
         });
-        if (fallback.status !== 0) {
-            rmSync(tempDir, { recursive: true, force: true });
-            throw new Error(`tar extraction failed: ${fallback.stderr?.toString() || result.stderr?.toString() || "unknown error"}`);
-        }
-        const entries = readdirSync(fallbackDir);
-        const [only] = entries;
-        const sourceDir = entries.length === 1 &&
-            only !== undefined &&
-            existsSync(join(fallbackDir, only)) &&
-            statSync(join(fallbackDir, only)).isDirectory()
-            ? join(fallbackDir, only)
-            : fallbackDir;
-        for (const entry of readdirSync(sourceDir)) {
-            renameSync(join(sourceDir, entry), join(destDir, entry));
+        if (result.status !== 0) {
+            const fallbackDir = join(tempDir, "fallback");
+            mkdirSync(fallbackDir, { recursive: true });
+            const fallback = spawnSync(tarBin, ["xzf", tmpFile, "-C", fallbackDir], {
+                stdio: "pipe",
+                windowsHide: true,
+            });
+            if (fallback.status !== 0) {
+                throw new Error(`tar extraction failed: ${fallback.stderr?.toString() || result.stderr?.toString() || "unknown error"}`);
+            }
+            const entries = readdirSync(fallbackDir);
+            const [only] = entries;
+            const sourceDir = entries.length === 1 &&
+                only !== undefined &&
+                existsSync(join(fallbackDir, only)) &&
+                statSync(join(fallbackDir, only)).isDirectory()
+                ? join(fallbackDir, only)
+                : fallbackDir;
+            for (const entry of readdirSync(sourceDir)) {
+                renameSync(join(sourceDir, entry), join(destDir, entry));
+            }
         }
     }
-    rmSync(tempDir, { recursive: true, force: true });
+    finally {
+        rmSync(tempDir, { recursive: true, force: true });
+    }
 }

package/cli/dist/utils/tilt-logs.js

@@ -26,6 +26,14 @@ export function isValidSince(value) {
     }
     return total <= MAX_DURATION_NANOSECONDS;
 }
+/** A valid --since duration in milliseconds, for logs Flisk reads itself (local processes) rather than through Tilt. */
+export function sinceMilliseconds(value) {
+    let total = 0;
+    for (const [, amount, unit] of value.matchAll(/(\d+(?:\.\d+)?)(ns|us|µs|ms|s|m|h)/g)) {
+        total += Number(amount) * (NANOSECONDS[unit] ?? 0);
+    }
+    return total / 1e6;
+}
 export function isValidPort(value) {
     return /^[1-9]\d{0,4}$/.test(value) && Number(value) <= 65535;
 }

package/cli/dist/utils/tilt-process.js

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 Flisk Landscape contributors
 // SPDX-License-Identifier: MIT
 import { execFileSync } from "node:child_process";
+import { FliskError } from "./errors.js";
 const run = (command, args) => execFileSync(command, args, { encoding: "utf-8", stdio: "pipe", windowsHide: true });
 /** Refuse to target arbitrary listeners: only stop a Tilt process on the requested UI port. */
 export function findTiltProcessIdsOnPort(port, platform = process.platform, commandRunner = run) {
@@ -15,7 +16,7 @@ export function findTiltProcessIdsOnPort(port, platform = process.platform, comm
                 .filter((pid) => Number.isInteger(pid) && pid > 0);
         }
         catch {
-            throw new Error(`Unable to inspect Tilt listeners on port ${port} with PowerShell.`);
+            throw new FliskError(`Unable to inspect Tilt listeners on port ${port} with PowerShell.`, ["Ensure PowerShell is available and accessible"], 1);
         }
     }
     let pids;
@@ -30,7 +31,7 @@ export function findTiltProcessIdsOnPort(port, platform = process.platform, comm
         const stderr = commandErr.stderr?.toString().trim();
         if (commandErr?.status === 1 && !stderr)
             return [];
-        throw new Error(`Unable to inspect listeners on port ${port}. Install lsof or resolve the lsof error before using --force.`, { cause: commandErr });
+        throw new FliskError(`Unable to inspect listeners on port ${port}. Install lsof or resolve the lsof error before using --force.`, ["Install lsof or verify permissions before running with --force"], 1);
     }
     return pids.filter((pid) => {
         try {
@@ -38,7 +39,7 @@ export function findTiltProcessIdsOnPort(port, platform = process.platform, comm
             return name.split(/[\\/]/).at(-1) === "tilt";
         }
         catch (err) {
-            throw new Error(`Unable to identify the process listening on port ${port}.`, { cause: err });
+            throw new FliskError(`Unable to identify the process listening on port ${port}.`, ["Check process inspection permissions"], 1);
         }
     });
 }