@flisk-sh/flisk-import 0.3.0 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
 # flisk import
 
-Import the services in a repo's root `docker-compose.yml` into [Flisk](https://github.com/flisk-sh/flisk) as `service.json` files. This is the Compose first tier of flisk-sh/flisk#511.
+Import the services in a repo's root `docker-compose.yml` into [Flisk](https://github.com/flisk-sh/flisk) as `service.json` files, or register the repo's own Tiltfile so `flisk up` runs it. This is the Compose first tier of flisk-sh/flisk#511.
 
 ```bash
 flisk import . --dry-run     # plan only
@@ -20,6 +20,24 @@ flisk import . --yes         # write service.json files and project setup
 
 See [docs/import.md](docs/import.md) for the full mapping and limits. `flisk import` is the core CLI command backed by this package.
 
+## Import a Tiltfile
+
+A repo that already runs on Tilt keeps its own Tiltfile. `flisk-import tiltfile` registers it in `.flisk/project.json`, so `flisk up` runs it unchanged.
+
+```bash
+flisk import tiltfile --dry-run          # plan only
+flisk import tiltfile                    # plan, then ask before writing
+flisk import tiltfile dev/Tiltfile --yes # a named file, or a folder that holds a Tiltfile
+```
+
+- **Path:** `[path]` defaults to `Tiltfile`; a folder means `<folder>/Tiltfile`. It is resolved from the current directory. The project root is the nearest folder with `.flisk/project.json`, else the current directory.
+- **Writes:** only `.flisk/project.json`, with `"orchestration": { "source": "tiltfile", "path": "<path from the project root>" }`. Every other key is kept. Without a `project.json`, it creates the same minimal one as the Compose import, with only the proxy stack. It never edits the Tiltfile.
+- **Refuses (exit 1):** a missing Tiltfile, a path inside `.flisk/` (also through a symlink), a path with a quote or control character, a `project.json` that is not a JSON object or lacks the fields `flisk up` needs, and a `project.json` that already sets `orchestration` (pass `--force` to replace it).
+- **Exit codes:** the same as the Compose import: `0` for `--dry-run` or a write, `1` for a refusal, `2` when the prompt is declined or closed (`Nothing written.`).
+- **Needs** a Flisk core that runs an imported Tiltfile ([flisk#2849](https://github.com/flisk-sh/flisk/pull/2849)). The importer does not check the core version.
+
+Plain `flisk-import [dir]` is still the Compose import. To import Compose from a folder named `tiltfile`, write `flisk-import ./tiltfile`.
+
 ```bash
 bun install && bun run build && bun run test
 ```

package/dist/cli.js

@@ -5,9 +5,10 @@ import { createInterface } from "node:readline/promises";
 import { Command } from "commander";
 import "./detectors/index.js";
 import { ImportError } from "./errors.js";
-import { MIN_CORE_VERSION } from "./flisk.js";
+import { MIN_CORE_VERSION, TILTFILE_CORE } from "./flisk.js";
 import { formatPlan } from "./format.js";
 import { buildPlan } from "./plan.js";
+import { applyTiltfileImport, formatTiltfilePlan, planTiltfileImport } from "./tiltfile.js";
 import { applyWrites, manifestRelPath, planWrites } from "./write.js";
 async function confirm(message) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -26,6 +27,8 @@ async function confirm(message) {
 const program = new Command("flisk-import")
     .version(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version)
     .description("Import services from the root docker-compose.yml into Flisk")
+    // Options after `tiltfile` belong to it, so `tiltfile --dry-run` is not read as the Compose import's --dry-run.
+    .enablePositionalOptions()
     .argument("[dir]", "Directory containing docker-compose.yml", ".")
     .option("--dry-run", "Print the plan and write nothing", false)
     .option("--yes", "Write without prompting", false)
@@ -65,6 +68,38 @@ const program = new Command("flisk-import")
         console.log(`  - Add the values listed above as missing to ${envFile}.`);
     console.log(`  - Run \`flisk up\` with Flisk core ${MIN_CORE_VERSION} or later. The import did not start anything.`);
 });
+program
+    .command("tiltfile")
+    .description("Register an existing Tiltfile in .flisk/project.json so flisk up runs it unchanged (never edits the Tiltfile)")
+    .argument("[path]", "The Tiltfile, or a directory holding one", "Tiltfile")
+    .option("--dry-run", "Print the plan and write nothing", false)
+    .option("--yes", "Write without prompting", false)
+    .option("--force", "Replace an orchestration already set in .flisk/project.json", false)
+    .action(async (path, local) => {
+    // Also honour the flags when they come before `tiltfile`, where the top-level command reads them.
+    const top = program.opts();
+    const options = {
+        dryRun: local.dryRun || top.dryRun,
+        yes: local.yes || top.yes,
+        force: local.force || top.force,
+    };
+    const plan = planTiltfileImport(path, { force: options.force });
+    console.log(formatTiltfilePlan(plan));
+    if (options.dryRun)
+        return void console.log("Dry run: nothing written.");
+    const target = plan.action === "create" ? "Create .flisk/project.json" : "Update .flisk/project.json";
+    if (!options.yes &&
+        !(await confirm(`${target} with orchestration ${plan.orchestration.path}?`))) {
+        console.log("Nothing written.");
+        process.exitCode = 2;
+        return;
+    }
+    applyTiltfileImport(plan);
+    console.log(`  wrote ${relative(process.cwd(), plan.projectJson) || ".flisk/project.json"}`);
+    console.log(`\nRegistered ${plan.orchestration.path} as the orchestration source.`);
+    console.log("\nNext:");
+    console.log(`  - Run \`flisk up\` with a Flisk core that runs an imported Tiltfile (${TILTFILE_CORE}). It runs ${plan.orchestration.path} unchanged; the import did not start anything.`);
+});
 try {
     await program.parseAsync();
 }

package/dist/flisk.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 /** Manifest constants of the Flisk service.json this tool writes. */
 export const SERVICE_MANIFEST_SCHEMA_VERSION = 1;
 export const SERVICE_MANIFEST_SCHEMA_URL = "https://flisk.sh/schema.service.json";
@@ -10,6 +10,11 @@ export const SERVICE_MANIFEST_SCHEMA_URL = "https://flisk.sh/schema.service.json
  * names, which this importer now writes. Stated, not checked: it does not read the installed version.
  */
 export const MIN_CORE_VERSION = "1.4.11";
+/**
+ * The core change that runs a registered Tiltfile (`orchestration.source: "tiltfile"`) from `flisk up`. Stated, not
+ * checked, like MIN_CORE_VERSION.
+ */
+export const TILTFILE_CORE = "flisk-sh/flisk#2849";
 /** Flisk's bring-your-own port range. */
 export const BYO_PORT_RANGE = { min: 4000, max: 5999, label: "4000-5999" };
 /**
@@ -39,3 +44,78 @@ export function findProjectRoot(start) {
         dir = parent;
     }
 }
+/**
+ * The minimal `.flisk/project.json` an import writes when the repo is not a Flisk project yet: the given stacks in
+ * Pre-Alpha, no optional infrastructure, and discovery of every `services/<stack>/<name>` folder. A copy of the minimum
+ * Flisk accepts today, so it can drift from flisk.
+ */
+export function defaultProjectConfig(projectRoot, preAlpha) {
+    return {
+        version: "1.0",
+        project: { name: basename(projectRoot), version: "1.0.0" },
+        phases: {
+            pre_alpha: { name: "Pre-Alpha", ...preAlpha },
+            alpha: { name: "Alpha", description: "", enabledStacks: [] },
+            beta: { name: "Beta", description: "", enabledStacks: [] },
+            out_of_scope: { name: "Out of Scope", description: "", enabledStacks: [] },
+        },
+        optional_infra: {
+            monitoring: false,
+            elk: false,
+            debezium: false,
+            golden_image: false,
+            verdaccio: false,
+        },
+        discovery: { paths: ["services/*/*"] },
+        overrides: {},
+    };
+}
+const isObject = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const PHASES = ["pre_alpha", "alpha", "beta", "out_of_scope"];
+const OPTIONAL_INFRA = ["monitoring", "elk", "debezium", "golden_image", "verdaccio"];
+/**
+ * The fields of an existing `.flisk/project.json` that Flisk core would refuse, missing or of the wrong type, as dotted
+ * names such as `project.name`. A whole object that is absent is named once (`optional_infra`), not field by field.
+ * Empty when `flisk up` can read the file. A copy of core's `normalizeProjectConfig` (flisk
+ * `cli/src/generator/template-engine.ts`), so it can drift from flisk.
+ */
+export function missingProjectFields(config) {
+    const missing = [];
+    if (typeof config.version !== "string")
+        missing.push("version");
+    if (!isObject(config.project))
+        missing.push("project");
+    else
+        for (const key of ["name", "version"])
+            if (typeof config.project[key] !== "string")
+                missing.push(`project.${key}`);
+    // Core also reads the older `stacks` shape, with `services` in place of `enabledStacks`.
+    const phaseGaps = (value, label, field) => {
+        if (!isObject(value))
+            return [label];
+        return PHASES.filter((phase) => {
+            const entry = value[phase];
+            return !isObject(entry) || !Array.isArray(entry[field]);
+        }).map((phase) => `${label}.${phase}.${field}`);
+    };
+    const phases = phaseGaps(config.phases, "phases", "enabledStacks");
+    if (phases.length && phaseGaps(config.stacks, "stacks", "services").length)
+        missing.push(...phases);
+    if (!isObject(config.optional_infra))
+        missing.push("optional_infra");
+    else {
+        const infra = config.optional_infra;
+        for (const key of OPTIONAL_INFRA)
+            if (typeof infra[key] !== "boolean")
+                missing.push(`optional_infra.${key}`);
+    }
+    if (!isObject(config.discovery))
+        missing.push("discovery");
+    else if (!Array.isArray(config.discovery.paths))
+        missing.push("discovery.paths");
+    if (config.capabilities !== undefined &&
+        !(isObject(config.capabilities) &&
+            Object.values(config.capabilities).every((flag) => typeof flag === "boolean")))
+        missing.push("capabilities");
+    return missing;
+}

package/dist/tiltfile.js

@@ -0,0 +1,141 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { ImportError } from "./errors.js";
+import { defaultProjectConfig, findProjectRoot, missingProjectFields } from "./flisk.js";
+const RERUN = "flisk import tiltfile <path>";
+const RECREATE = "Or recreate it with `flisk project --yes --force` (this resets .flisk/project.json), then run the import again";
+/** The refusal for a Tiltfile inside `.flisk/`; `resolved` names where a symlink leads. */
+function insideFliskError(path, resolved) {
+    const via = resolved ? ` (it resolves to ${resolved})` : "";
+    return new ImportError(`${path} is inside .flisk/${via}, where Flisk writes its generated files; import your own Tiltfile instead`, [`Point it at the Tiltfile you maintain: ${RERUN}`]);
+}
+/**
+ * Where `tiltfile` really is, relative to the real `<projectRoot>/.flisk`, when a symlink on the way leads into it.
+ * The lexical check misses `infra/Tiltfile -> ../.flisk/.flisk-out/Tiltfile`, and flisk up would then include its own
+ * generated Tiltfile. Undefined when it does not, or when there is no `.flisk/` yet.
+ */
+function linkedIntoFlisk(tiltfile, projectRoot) {
+    const fliskDir = join(projectRoot, ".flisk");
+    if (!existsSync(fliskDir))
+        return undefined;
+    const realFlisk = realpathSync(fliskDir);
+    const inside = relative(realFlisk, realpathSync(tiltfile));
+    if (inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside))
+        return undefined;
+    return [".flisk", ...inside.split(sep)].join("/");
+}
+/** Describes an `orchestration` value for a message, for example `tiltfile: Tiltfile`. */
+export function describeOrchestration(value) {
+    if (value && typeof value === "object" && "source" in value) {
+        const { source, path } = value;
+        return `${String(source)}: ${typeof path === "string" && path ? path : "default"}`;
+    }
+    return JSON.stringify(value);
+}
+/**
+ * Plans registering an existing Tiltfile as the project's orchestration source, so `flisk up` runs it unchanged.
+ * `pathArg` is a file or a directory holding `Tiltfile`, resolved from `cwd`. Nothing is written here.
+ */
+export function planTiltfileImport(pathArg = "Tiltfile", options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    // flisk up puts this path in a generated Tiltfile as a Starlark string, so refuse it before touching the disk.
+    const hasUnsafeChar = (value) => [...value].some((char) => char === '"' || char === "'" || char.charCodeAt(0) < 0x20);
+    if (hasUnsafeChar(pathArg)) {
+        throw new ImportError(`Tiltfile path ${JSON.stringify(pathArg)} has a quote or control character`, ["Rename the file or folder, then run: flisk import tiltfile <path>"]);
+    }
+    let tiltfile = resolve(cwd, pathArg);
+    if (statSync(tiltfile, { throwIfNoEntry: false })?.isDirectory())
+        tiltfile = join(tiltfile, "Tiltfile");
+    const projectRoot = findProjectRoot(cwd) ?? cwd;
+    const path = relative(projectRoot, tiltfile).split("\\").join("/");
+    if (hasUnsafeChar(path)) {
+        throw new ImportError(`Tiltfile path ${JSON.stringify(path)} has a quote or control character`, ["Rename the file or folder, then run: flisk import tiltfile <path>"]);
+    }
+    if (path === ".flisk" || path.startsWith(".flisk/"))
+        throw insideFliskError(path);
+    if (!statSync(tiltfile, { throwIfNoEntry: false })?.isFile()) {
+        throw new ImportError(`No Tiltfile found at ${pathArg}`, [
+            `Pass the path of an existing Tiltfile, or a folder that holds one: ${RERUN}`,
+        ]);
+    }
+    const resolved = linkedIntoFlisk(tiltfile, projectRoot);
+    if (resolved)
+        throw insideFliskError(path, resolved);
+    const projectJson = join(projectRoot, ".flisk", "project.json");
+    const orchestration = { source: "tiltfile", path };
+    if (!existsSync(projectJson)) {
+        const config = {
+            ...defaultProjectConfig(projectRoot, {
+                description: "Flisk proxy; flisk up runs the project's own Tiltfile",
+                enabledStacks: ["proxy"],
+            }),
+            orchestration,
+        };
+        return {
+            tiltfile,
+            projectRoot,
+            projectJson,
+            orchestration,
+            action: "create",
+            content: `${JSON.stringify(config, null, 2)}\n`,
+        };
+    }
+    let existing;
+    try {
+        existing = JSON.parse(readFileSync(projectJson, "utf8"));
+    }
+    catch (err) {
+        throw new ImportError(`Cannot read ${projectJson}: ${err instanceof Error ? err.message : String(err)}`, ["Fix the JSON in .flisk/project.json, then run the import again", RECREATE]);
+    }
+    if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
+        throw new ImportError(`${projectJson} is not a JSON object`, [
+            "Fix .flisk/project.json, then run the import again",
+            RECREATE,
+        ]);
+    }
+    const config = existing;
+    // Writing orchestration into a file flisk up cannot read would report success and then fail at flisk up.
+    const missing = missingProjectFields(config);
+    if (missing.length) {
+        throw new ImportError(`.flisk/project.json is missing fields flisk up needs, or has them with the wrong type: ${missing.join(", ")}`, [
+            `Add ${missing.length === 1 ? "it" : "them"} to .flisk/project.json, then run the import again`,
+            RECREATE,
+        ]);
+    }
+    const replaced = config.orchestration;
+    if (replaced !== undefined && !options.force) {
+        throw new ImportError(`.flisk/project.json already sets orchestration (${describeOrchestration(replaced)})`, ["Pass --force to replace it; every other key is kept"]);
+    }
+    // Spreading keeps every key, and keeps `orchestration` where it was when --force replaces it.
+    const next = { ...config, orchestration };
+    return {
+        tiltfile,
+        projectRoot,
+        projectJson,
+        orchestration,
+        action: "update",
+        ...(replaced !== undefined ? { replaced } : {}),
+        content: `${JSON.stringify(next, null, 2)}\n`,
+    };
+}
+/** Writes `.flisk/project.json`, and nothing else. The Tiltfile is never touched. */
+export function applyTiltfileImport(plan) {
+    mkdirSync(dirname(plan.projectJson), { recursive: true });
+    writeFileSync(plan.projectJson, plan.content, plan.action === "create" ? { flag: "wx" } : {});
+}
+/** The printed plan for `flisk-import tiltfile`. */
+export function formatTiltfilePlan(plan) {
+    const status = plan.action === "create"
+        ? "create Flisk project"
+        : plan.replaced !== undefined
+            ? `update, replaces orchestration (${describeOrchestration(plan.replaced)}) (--force)`
+            : "update, other keys kept";
+    return [
+        `Found ${plan.orchestration.path} in ${plan.projectRoot}`,
+        "The Tiltfile is not changed: flisk up runs it as it is.",
+        "",
+        `  .flisk/project.json  [${status}]`,
+        `    orchestration:  ${JSON.stringify(plan.orchestration)}`,
+        "",
+    ].join("\n");
+}

package/dist/write.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { ImportError } from "./errors.js";
-import { BYO_PORT_RANGE, findProjectRoot, IMAGE_PATTERN, SERVICE_MANIFEST_SCHEMA_URL, SERVICE_MANIFEST_SCHEMA_VERSION, validateName, } from "./flisk.js";
+import { BYO_PORT_RANGE, defaultProjectConfig, findProjectRoot, IMAGE_PATTERN, SERVICE_MANIFEST_SCHEMA_URL, SERVICE_MANIFEST_SCHEMA_VERSION, validateName, } from "./flisk.js";
 import { toResourceName } from "./merge.js";
 import { usedManifestPorts } from "./plan.js";
 /** Secret names the service schema accepts (`secrets.required`). */
@@ -50,29 +50,10 @@ export function planWrites(plan, force) {
         ? undefined
         : {
             path: projectConfigPath,
-            content: `${JSON.stringify({
-                version: "1.0",
-                project: { name: basename(projectRoot), version: "1.0.0" },
-                phases: {
-                    pre_alpha: {
-                        name: "Pre-Alpha",
-                        description: "Flisk proxy and imported Compose services",
-                        enabledStacks: ["proxy", stack],
-                    },
-                    alpha: { name: "Alpha", description: "", enabledStacks: [] },
-                    beta: { name: "Beta", description: "", enabledStacks: [] },
-                    out_of_scope: { name: "Out of Scope", description: "", enabledStacks: [] },
-                },
-                optional_infra: {
-                    monitoring: false,
-                    elk: false,
-                    debezium: false,
-                    golden_image: false,
-                    verdaccio: false,
-                },
-                discovery: { paths: ["services/*/*"] },
-                overrides: {},
-            }, null, 2)}\n`,
+            content: `${JSON.stringify(defaultProjectConfig(projectRoot, {
+                description: "Flisk proxy and imported Compose services",
+                enabledStacks: ["proxy", stack],
+            }), null, 2)}\n`,
         };
     const envPath = join(projectRoot, ".env");
     const envKept = readEnvKeys(envPath);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flisk-sh/flisk-import",
-  "version": "0.3.0",
-  "description": "Import services from a repository's root docker-compose.yml into Flisk service.json files.",
+  "version": "0.4.1",
+  "description": "Import a repository's root docker-compose.yml into Flisk service.json files, or register its Tiltfile.",
   "type": "module",
   "license": "MIT",
   "bin": {