@intentius/chant-lexicon-fly 0.124.31 → 0.124.32

package/dist/teardown.js

@@ -0,0 +1,194 @@
+/**
+ * Env teardown for the fly lexicon (chant #1222) — both halves of the
+ * `teardownOwned` / `executeTeardown` capability pair, over the applier's own
+ * flaps primitives (op/activities/fly-apply.ts).
+ *
+ * Selection follows the two-tier ownership convention (#743, D2):
+ *
+ *   - Machines carry the primary marker in `config.metadata`
+ *     (`managed-by: chant` + `chant-stack` + `chant-env`), so a machine is a
+ *     candidate exactly when its own metadata reads back the requested
+ *     stack + env identity.
+ *   - The app is the boundary for everything metadata-less (volumes, IPs,
+ *     certificates, secrets). An app becomes a candidate only when it has at
+ *     least one machine and EVERY machine in it carries the requested
+ *     identity — an app also hosting a foreign or other-env machine is never
+ *     deleted whole; only its matching machines are.
+ *
+ * Enumeration lists apps via `GET /v1/apps` (mudflaps serves it as-is; real
+ * flaps wants `?org_slug=`, appended from FLY_ORG / FLY_ORG_SLUG when set)
+ * and each app's machines. An unlistable app is a hole (#1089) — unknown,
+ * never absent.
+ *
+ * Execution deletes machines first (lease → destroy → wait, the applier's
+ * `destroyMachine`) and apps last (`deleteApp`, which takes the app-scoped
+ * volumes/IPs/certs with it). Before every delete the live side is re-read
+ * and the identity re-verified; already-gone is `deleted` (teardown is
+ * idempotent), an identity mismatch is `not-prunable`, never a delete.
+ */
+import { readOwnership } from "@intentius/chant/ownership";
+import { FLY_METADATA_OWNERSHIP_KEYS } from "./ownership.js";
+import { resolveEndpoint, defaultFlyHttp, listMachines, destroyMachine, deleteApp, } from "./op/activities/fly-apply.js";
+const APP_TYPE = "Fly::Machines::App";
+const MACHINE_TYPE = "Fly::Machines::Machine";
+/** Live machine states that mean the machine is gone or on its way out. */
+const TERMINAL_STATES = new Set(["destroyed", "destroying"]);
+/** True when a machine's own metadata reads back exactly the requested identity. */
+function matchesMarker(machine, marker) {
+    const read = readOwnership(machine.config?.metadata, FLY_METADATA_OWNERSHIP_KEYS);
+    return read !== undefined && read.stack === marker.stack && read.env === marker.env;
+}
+/** Machines that are actually live — terminal ones are already gone. */
+function liveMachines(machines) {
+    return machines.filter((m) => !TERMINAL_STATES.has(m.state));
+}
+/** `GET /v1/apps`, with `?org_slug=` appended when the env names an org. */
+async function listApps(ctx, http, signal) {
+    const org = process.env.FLY_ORG || process.env.FLY_ORG_SLUG;
+    const url = `${ctx.base}/v1/apps${org ? `?org_slug=${encodeURIComponent(org)}` : ""}`;
+    const res = await http("GET", url, undefined, undefined, signal);
+    if (res.status >= 300)
+        throw new Error(`app list failed (${res.status}): ${res.text}`);
+    const body = JSON.parse(res.text);
+    return (body.apps ?? []).map((a) => a.name).filter((n) => typeof n === "string" && n.length > 0);
+}
+/**
+ * Enumerate the env's marker-matching machines and whole-app boundaries — the
+ * fly half of `chant lifecycle teardown <env>` planning.
+ */
+export async function teardownOwned(options, deps = {}) {
+    const http = deps.http ?? defaultFlyHttp();
+    const ctx = { base: resolveEndpoint({ ...(deps.endpoint ? { endpoint: deps.endpoint } : {}) }) };
+    const candidates = [];
+    const holes = [];
+    const apps = await listApps(ctx, http); // a failed app list throws — core turns it into a whole-lexicon hole
+    for (const app of apps) {
+        let machines;
+        try {
+            machines = liveMachines(await listMachines(ctx, app, http));
+        }
+        catch (err) {
+            holes.push({
+                name: app,
+                type: APP_TYPE,
+                reason: "read-failed",
+                detail: err instanceof Error ? err.message : String(err),
+            });
+            continue;
+        }
+        const matching = machines.filter((m) => matchesMarker(m, options.marker));
+        for (const m of matching) {
+            candidates.push({
+                name: `${app}/${m.name}`,
+                type: MACHINE_TYPE,
+                physicalId: m.id,
+                marker: readOwnership(m.config?.metadata, FLY_METADATA_OWNERSHIP_KEYS),
+            });
+        }
+        // The app boundary: whole-app delete only when every live machine carries
+        // the requested identity. Its marker is read back off its machines — the
+        // only channel an app has (#743).
+        if (machines.length > 0 && matching.length === machines.length) {
+            candidates.push({
+                name: app,
+                type: APP_TYPE,
+                marker: readOwnership(matching[0].config?.metadata, FLY_METADATA_OWNERSHIP_KEYS),
+            });
+        }
+    }
+    return { candidates, ...(holes.length > 0 ? { holes } : {}) };
+}
+/**
+ * Delete the handed-over candidates: machines first, apps last. One outcome
+ * per candidate, always.
+ */
+export async function executeTeardown(options, deps = {}) {
+    const http = deps.http ?? defaultFlyHttp();
+    const ctx = { base: resolveEndpoint({ ...(deps.endpoint ? { endpoint: deps.endpoint } : {}) }) };
+    const outcomes = [];
+    for (const candidate of options.candidates.filter((c) => c.type === MACHINE_TYPE)) {
+        outcomes.push(await destroyMachineCandidate(ctx, candidate, options.marker, http, deps.wait));
+    }
+    for (const candidate of options.candidates.filter((c) => c.type === APP_TYPE)) {
+        outcomes.push(await deleteAppCandidate(ctx, candidate, options.marker, http));
+    }
+    for (const candidate of options.candidates) {
+        if (candidate.type === MACHINE_TYPE || candidate.type === APP_TYPE)
+            continue;
+        outcomes.push({
+            name: candidate.name,
+            type: candidate.type,
+            outcome: "not-prunable",
+            detail: `fly teardown deletes machines and apps; ${candidate.type} is app-scoped and goes with its app`,
+        });
+    }
+    return { outcomes };
+}
+async function destroyMachineCandidate(ctx, candidate, marker, http, wait) {
+    const base = {
+        name: candidate.name,
+        type: candidate.type,
+        ...(candidate.physicalId ? { physicalId: candidate.physicalId } : {}),
+    };
+    const slash = candidate.name.indexOf("/");
+    if (slash <= 0) {
+        return { ...base, outcome: "not-prunable", detail: "machine candidate name is not app/machine-shaped" };
+    }
+    const app = candidate.name.slice(0, slash);
+    const machineName = candidate.name.slice(slash + 1);
+    let machines;
+    try {
+        machines = await listMachines(ctx, app, http);
+    }
+    catch (err) {
+        return { ...base, outcome: "failed", detail: err instanceof Error ? err.message : String(err) };
+    }
+    const live = liveMachines(machines).find((m) => candidate.physicalId ? m.id === candidate.physicalId : m.name === machineName);
+    if (!live) {
+        return { ...base, outcome: "deleted", detail: "already absent" };
+    }
+    // Re-verify right before destroying — a delete is not undoable.
+    if (!matchesMarker(live, marker)) {
+        return {
+            ...base,
+            outcome: "not-prunable",
+            detail: "the live machine no longer carries the requested marker identity",
+        };
+    }
+    try {
+        await destroyMachine(ctx, app, live.id, http, undefined, { ...(wait ?? {}), state: live.state, name: live.name });
+    }
+    catch (err) {
+        return { ...base, outcome: "failed", detail: err instanceof Error ? err.message : String(err) };
+    }
+    return { ...base, outcome: "deleted" };
+}
+async function deleteAppCandidate(ctx, candidate, marker, http) {
+    const base = { name: candidate.name, type: candidate.type };
+    const app = candidate.name;
+    // The boundary re-check: an app that (still, or again) hosts any machine
+    // outside the requested identity is not deleted whole. Machines this same
+    // execution just destroyed are gone by now — destroyMachine waits.
+    let machines;
+    try {
+        machines = liveMachines(await listMachines(ctx, app, http));
+    }
+    catch (err) {
+        return { ...base, outcome: "failed", detail: err instanceof Error ? err.message : String(err) };
+    }
+    const foreign = machines.filter((m) => !matchesMarker(m, marker));
+    if (foreign.length > 0) {
+        return {
+            ...base,
+            outcome: "not-prunable",
+            detail: `the app hosts ${foreign.length} machine(s) outside the requested identity`,
+        };
+    }
+    try {
+        const result = await deleteApp(ctx, app, http);
+        return result.deleted ? { ...base, outcome: "deleted" } : { ...base, outcome: "deleted", detail: "already absent" };
+    }
+    catch (err) {
+        return { ...base, outcome: "failed", detail: err instanceof Error ? err.message : String(err) };
+    }
+}

package/dist/types/index.d.ts

@@ -59,6 +59,10 @@ export declare class Machine {
     /** An object defining the Machine configuration */
     config?: MachineConfig;
     lease_ttl?: number;
+    /** The minimum version of the app's secrets the Machine must run with. Set it to the `version`
+returned by the endpoints that set or delete app secrets, so that the Machine is guaranteed
+to see those changes. This field belongs at the top level of the request body, not in
+`config`. If omitted, the app's current secrets version is looked up for you. */
     min_secrets_version?: number;
     /** Unique name for this Machine. If omitted, one is generated for you */
     name?: string;
@@ -338,37 +342,59 @@ export declare class MachineConfig {
   constructor(props: {
     /** Optional boolean telling the Machine to destroy itself once it’s complete (default false) */
     auto_destroy?: boolean;
+    /** A cache drive attached to the Machine */
     cache_drive?: MachineCacheDrive;
     /** An optional object that defines one or more named top-level checks. The key for each check is the check name. */
     checks?: Record<string, MachineCheck>;
-    /** Containers are a list of containers that will run in the machine. Currently restricted to
-only specific organizations. */
+    /** Containers are a list of containers that will run in the machine, each from its own image. */
     containers?: ContainerConfig[];
     /** Deprecated: use Service.Autostart instead */
     disable_machine_autostart?: boolean;
+    /** DNS settings for the Machine */
     dns?: DNSConfig;
     /** An object filled with key/value pairs to be set as environment variables */
     env?: Record<string, string>;
+    /** Files to write into the Machine, from either a raw value or an app secret */
     files?: File[];
+    /** The resources (CPUs, memory, etc.) allocated to the Machine */
     guest?: MachineGuest;
     /** The docker image to run */
     image?: string;
+    /** Arguments for init, Fly.io's footprint inside the Machine, which controls how your own code is run */
     init?: MachineInit;
+    /** Key/value pairs of Machine metadata. Fly.io uses metadata internally for routing, process groups, and clusters */
     metadata?: Record<string, string>;
+    /** An optional metrics endpoint for Prometheus on Fly.io to scrape */
     metrics?: MachineMetrics;
+    /** Persistent volumes to mount in the Machine. A Machine can mount at most one volume, which must be on
+the same host. The mounted volume cannot be changed by updating the Machine */
     mounts?: MachineMount[];
+    /** Multiple processes to run within this one Machine, all from the Machine's image. Unrelated to the
+process groups in fly.toml, which run on separate Machines. To run processes from different
+images, use containers instead */
     processes?: MachineProcess[];
+    /** Whether and how the Machine is restarted after its main process exits */
     restart?: MachineRestart;
+    /** The size of the Machine's root filesystem and whether it persists */
     rootfs?: MachineRootfs;
+    /** Run the Machine at an interval: one of hourly, daily, weekly or monthly. The interval starts when
+the Machine is created */
     schedule?: string;
+    /** Network services that Fly Proxy routes traffic to */
     services?: MachineService[];
     /** Deprecated: use Guest instead */
     size?: string;
+    /** Spot pricing settings for the Machine */
     spot?: MachineSpot;
     /** Standbys enable a machine to be a standby for another. In the event of a hardware failure,
 the standby machine will be started. */
     standbys?: string[];
+    /** Static files to serve under a URL prefix. Fly Proxy routes matching requests to a file server
+inside the Machine, bypassing your application's own process; the Machine must be running. The
+files are read either from a path inside the Machine or from a Tigris bucket that belongs to the
+app; no bucket is created for you */
     statics?: Static[];
+    /** How the Machine is shut down gracefully: the signal sent to it and how long to wait before a hard shutdown */
     stop_config?: StopConfig;
   });
 }
@@ -578,9 +604,14 @@ export declare class ReplayCache {
 
 export declare class Static {
   constructor(props: {
+    /** The path inside the Machine, or inside tigris_bucket when set, where the files to serve are located */
     guest_path: string;
+    /** The URL prefix under which the files are served */
     url_prefix: string;
+    /** The document served for requests to the URL prefix or any of its subfolders. Only works with tigris_bucket */
     index_document?: string;
+    /** An existing Tigris bucket belonging to the app to read the files from, instead of the Machine's
+filesystem. The files are still served through the Machine */
     tigris_bucket?: string;
   });
 }

package/dist/validate-cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env tsx
+import { validate } from "./validate.js";
+import { printValidationResult } from "@intentius/chant/codegen/validate";
+printValidationResult(await validate());

package/dist/validate.js

@@ -0,0 +1,33 @@
+/**
+ * Validate generated lexicon-fly artifacts.
+ *
+ * Thin wrapper around the core validation framework
+ * with fly-specific configuration.
+ */
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { validateLexiconArtifacts } from "@intentius/chant/codegen/validate";
+/**
+ * The curated top-level Machines API resources (#741). A regeneration that
+ * loses one — an upstream rename, a spec fetch that returned a partial
+ * document — must fail validation rather than ship a lexicon missing a kind.
+ */
+const REQUIRED_NAMES = [
+    "App",
+    "Machine",
+    "Volume",
+    "IPAddress",
+    "Certificate",
+    "Secret",
+];
+/**
+ * Validate the generated lexicon-fly artifacts.
+ */
+export async function validate(opts) {
+    const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+    return validateLexiconArtifacts({
+        lexiconJsonFilename: "lexicon-fly.json",
+        requiredNames: REQUIRED_NAMES,
+        basePath,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-fly",
-  "version": "0.124.31",
+  "version": "0.124.32",
   "type": "module",
   "files": [
     "src/",
@@ -13,37 +13,37 @@
     ".": {
       "development": "./src/index.ts",
       "types": "./dist/index.d.ts",
-      "default": "./src/index.ts"
+      "default": "./dist/index.js"
     },
     "./*": {
       "development": "./src/*.ts",
       "types": "./dist/*.d.ts",
-      "default": "./src/*.ts"
+      "default": "./dist/*.js"
     },
     "./detect": {
       "development": "./src/detect.ts",
       "types": "./dist/detect.d.ts",
-      "default": "./src/detect.ts"
+      "default": "./dist/detect.js"
     },
     "./components": {
       "development": "./src/components/index.ts",
       "types": "./dist/components/index.d.ts",
-      "default": "./src/components/index.ts"
+      "default": "./dist/components/index.js"
     },
     "./op/activities": {
       "development": "./src/op/activities/index.ts",
       "types": "./dist/op/activities/index.d.ts",
-      "default": "./src/op/activities/index.ts"
+      "default": "./dist/op/activities/index.js"
     },
     "./op/activity-contracts": {
       "development": "./src/op/activity-contracts.ts",
       "types": "./dist/op/activity-contracts.d.ts",
-      "default": "./src/op/activity-contracts.ts"
+      "default": "./dist/op/activity-contracts.js"
     },
     "./lint/post-synth": {
       "development": "./src/lint/post-synth/index.ts",
       "types": "./dist/lint/post-synth/index.d.ts",
-      "default": "./src/lint/post-synth/index.ts"
+      "default": "./dist/lint/post-synth/index.js"
     },
     "./manifest": "./dist/manifest.json",
     "./meta": "./dist/meta.json",
@@ -55,10 +55,10 @@
     "validate": "tsx src/validate-cli.ts",
     "docs": "tsx src/codegen/docs-cli.ts",
     "prepack": "npm run generate && npm run bundle && npm run validate && npm run build",
-    "build": "../../scripts/tsc7.sh -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name \"*.js\" -o -name \"*.js.map\" \\) -delete"
+    "build": "../../scripts/tsc7.sh -p tsconfig.build.json --sourceMap false && tsc-alias -p tsconfig.build.json"
   },
   "dependencies": {
-    "@intentius/chant-lexicon-otel": "^0.124.31",
+    "@intentius/chant-lexicon-otel": "^0.124.32",
     "ws": "^8.18.0"
   },
   "devDependencies": {
@@ -69,7 +69,7 @@
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.31",
+    "@intentius/chant": "^0.124.32",
     "zod": "^4.3.6"
   },
   "description": "Fly.io Machines lexicon for chant — declarative IaC in TypeScript",

package/src/codegen/package.ts

@@ -3,7 +3,7 @@ import { generate } from "./generate";
 import { flyPlugin } from "../plugin";
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
-import { fileURLToPath } from "url";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 
 /**
  * Package the fly lexicon for distribution.
@@ -13,7 +13,7 @@ export async function packageLexicon(options?: { verbose?: boolean; force?: bool
   // relative to src/, so srcDir must be the parent of this directory.
   // Pointing it at src/codegen made collectRules glob a directory that does
   // not exist, and the bundle shipped zero rules alongside zero skills.
-  const srcDir = dirname(dirname(fileURLToPath(import.meta.url)));
+  const srcDir = dirname(moduleSourceDir(import.meta.url));
   const pkgJson = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8"));
 
   const { spec, stats } = await packagePipeline({

package/src/generated/index.d.ts

@@ -59,6 +59,10 @@ export declare class Machine {
     /** An object defining the Machine configuration */
     config?: MachineConfig;
     lease_ttl?: number;
+    /** The minimum version of the app's secrets the Machine must run with. Set it to the `version`
+returned by the endpoints that set or delete app secrets, so that the Machine is guaranteed
+to see those changes. This field belongs at the top level of the request body, not in
+`config`. If omitted, the app's current secrets version is looked up for you. */
     min_secrets_version?: number;
     /** Unique name for this Machine. If omitted, one is generated for you */
     name?: string;
@@ -338,37 +342,59 @@ export declare class MachineConfig {
   constructor(props: {
     /** Optional boolean telling the Machine to destroy itself once it’s complete (default false) */
     auto_destroy?: boolean;
+    /** A cache drive attached to the Machine */
     cache_drive?: MachineCacheDrive;
     /** An optional object that defines one or more named top-level checks. The key for each check is the check name. */
     checks?: Record<string, MachineCheck>;
-    /** Containers are a list of containers that will run in the machine. Currently restricted to
-only specific organizations. */
+    /** Containers are a list of containers that will run in the machine, each from its own image. */
     containers?: ContainerConfig[];
     /** Deprecated: use Service.Autostart instead */
     disable_machine_autostart?: boolean;
+    /** DNS settings for the Machine */
     dns?: DNSConfig;
     /** An object filled with key/value pairs to be set as environment variables */
     env?: Record<string, string>;
+    /** Files to write into the Machine, from either a raw value or an app secret */
     files?: File[];
+    /** The resources (CPUs, memory, etc.) allocated to the Machine */
     guest?: MachineGuest;
     /** The docker image to run */
     image?: string;
+    /** Arguments for init, Fly.io's footprint inside the Machine, which controls how your own code is run */
     init?: MachineInit;
+    /** Key/value pairs of Machine metadata. Fly.io uses metadata internally for routing, process groups, and clusters */
     metadata?: Record<string, string>;
+    /** An optional metrics endpoint for Prometheus on Fly.io to scrape */
     metrics?: MachineMetrics;
+    /** Persistent volumes to mount in the Machine. A Machine can mount at most one volume, which must be on
+the same host. The mounted volume cannot be changed by updating the Machine */
     mounts?: MachineMount[];
+    /** Multiple processes to run within this one Machine, all from the Machine's image. Unrelated to the
+process groups in fly.toml, which run on separate Machines. To run processes from different
+images, use containers instead */
     processes?: MachineProcess[];
+    /** Whether and how the Machine is restarted after its main process exits */
     restart?: MachineRestart;
+    /** The size of the Machine's root filesystem and whether it persists */
     rootfs?: MachineRootfs;
+    /** Run the Machine at an interval: one of hourly, daily, weekly or monthly. The interval starts when
+the Machine is created */
     schedule?: string;
+    /** Network services that Fly Proxy routes traffic to */
     services?: MachineService[];
     /** Deprecated: use Guest instead */
     size?: string;
+    /** Spot pricing settings for the Machine */
     spot?: MachineSpot;
     /** Standbys enable a machine to be a standby for another. In the event of a hardware failure,
 the standby machine will be started. */
     standbys?: string[];
+    /** Static files to serve under a URL prefix. Fly Proxy routes matching requests to a file server
+inside the Machine, bypassing your application's own process; the Machine must be running. The
+files are read either from a path inside the Machine or from a Tigris bucket that belongs to the
+app; no bucket is created for you */
     statics?: Static[];
+    /** How the Machine is shut down gracefully: the signal sent to it and how long to wait before a hard shutdown */
     stop_config?: StopConfig;
   });
 }
@@ -578,9 +604,14 @@ export declare class ReplayCache {
 
 export declare class Static {
   constructor(props: {
+    /** The path inside the Machine, or inside tigris_bucket when set, where the files to serve are located */
     guest_path: string;
+    /** The URL prefix under which the files are served */
     url_prefix: string;
+    /** The document served for requests to the URL prefix or any of its subfolders. Only works with tigris_bucket */
     index_document?: string;
+    /** An existing Tigris bucket belonging to the app to read the files from, instead of the Machine's
+filesystem. The files are still served through the Machine */
     tigris_bucket?: string;
   });
 }