@intentius/chant-lexicon-fly 0.124.31 → 0.124.33

package/dist/import/generator.js

@@ -0,0 +1,208 @@
+/**
+ * flaps TypeScript generator.
+ *
+ * Converts import IR from {@link FlyParser} into typed chant TypeScript:
+ * `import { App, Machine, ... } from "@intentius/chant-lexicon-fly";` followed by
+ * `export const <var> = new <Class>({ ... });`.
+ *
+ * fly's nested config types (`MachineConfig`, `MachineGuest`, `MachineService`,
+ * ...) are property declarables — classes with an empty instance shape — so a
+ * bare object literal would trip TypeScript's excess-property check against the
+ * declared parameter type. Wherever a field's declared type is one of those
+ * classes, the value is wrapped in `new <Class>({ ... })` (recursively), which is
+ * the same authoring surface `chant init` scaffolds and the serializer walks back
+ * to the identical flaps body.
+ */
+/**
+ * `<OwnerClass> → { <field>: { kind, cls } }` for every field whose declared
+ * type is a fly property declarable (a class, an array of one, or a
+ * `Record<string, one>`). Mirrors the constructor parameter types in the
+ * generated resource classes (src/generated). Regenerate this map if the pinned
+ * flaps spec changes the config surface.
+ */
+const NESTED_DECLARABLES = {
+    Machine: {
+        config: { kind: "single", cls: "MachineConfig" },
+    },
+    Volume: {
+        compute: { kind: "single", cls: "MachineGuest" },
+    },
+    ContainerConfig: {
+        depends_on: { kind: "array", cls: "ContainerDependency" },
+        env_from: { kind: "array", cls: "EnvFrom" },
+        files: { kind: "array", cls: "File" },
+        healthchecks: { kind: "array", cls: "ContainerHealthcheck" },
+        restart: { kind: "single", cls: "MachineRestart" },
+        secrets: { kind: "array", cls: "MachineSecret" },
+        stop: { kind: "single", cls: "StopConfig" },
+    },
+    ContainerHealthcheck: {
+        exec: { kind: "single", cls: "ExecHealthcheck" },
+        http: { kind: "single", cls: "HTTPHealthcheck" },
+        tcp: { kind: "single", cls: "TCPHealthcheck" },
+    },
+    DNSConfig: {
+        dns_forward_rules: { kind: "array", cls: "DnsForwardRule" },
+        options: { kind: "array", cls: "DnsOption" },
+    },
+    HTTPHealthcheck: {
+        headers: { kind: "array", cls: "MachineHTTPHeader" },
+    },
+    HTTPOptions: {
+        replay_cache: { kind: "array", cls: "ReplayCache" },
+        response: { kind: "single", cls: "HTTPResponseOptions" },
+    },
+    MachineCheck: {
+        headers: { kind: "array", cls: "MachineHTTPHeader" },
+    },
+    MachineConfig: {
+        cache_drive: { kind: "single", cls: "MachineCacheDrive" },
+        checks: { kind: "record", cls: "MachineCheck" },
+        containers: { kind: "array", cls: "ContainerConfig" },
+        dns: { kind: "single", cls: "DNSConfig" },
+        files: { kind: "array", cls: "File" },
+        guest: { kind: "single", cls: "MachineGuest" },
+        init: { kind: "single", cls: "MachineInit" },
+        metrics: { kind: "single", cls: "MachineMetrics" },
+        mounts: { kind: "array", cls: "MachineMount" },
+        processes: { kind: "array", cls: "MachineProcess" },
+        restart: { kind: "single", cls: "MachineRestart" },
+        rootfs: { kind: "single", cls: "MachineRootfs" },
+        services: { kind: "array", cls: "MachineService" },
+        spot: { kind: "single", cls: "MachineSpot" },
+        statics: { kind: "array", cls: "Static" },
+        stop_config: { kind: "single", cls: "StopConfig" },
+    },
+    MachinePort: {
+        http_options: { kind: "single", cls: "HTTPOptions" },
+        proxy_proto_options: { kind: "single", cls: "ProxyProtoOptions" },
+        tls_options: { kind: "single", cls: "TLSOptions" },
+    },
+    MachineProcess: {
+        env_from: { kind: "array", cls: "EnvFrom" },
+        secrets: { kind: "array", cls: "MachineSecret" },
+    },
+    MachineService: {
+        checks: { kind: "array", cls: "MachineServiceCheck" },
+        concurrency: { kind: "single", cls: "MachineServiceConcurrency" },
+        ports: { kind: "array", cls: "MachinePort" },
+    },
+    MachineServiceCheck: {
+        headers: { kind: "array", cls: "MachineHTTPHeader" },
+    },
+};
+export class FlyGenerator {
+    generate(ir) {
+        const imports = new Set();
+        const bodyLines = [];
+        for (const resource of ir.resources) {
+            const parts = resource.type.split("::");
+            const className = parts.length >= 3 ? parts[2] : resource.type;
+            imports.add(className);
+            const varName = camelCase(resource.logicalId);
+            const props = formatProps(resource.properties, 0, className, imports);
+            bodyLines.push(`export const ${varName} = new ${className}(${props});`);
+            bodyLines.push("");
+        }
+        const lines = [];
+        if (imports.size > 0) {
+            lines.push(`import { ${[...imports].sort().join(", ")} } from "@intentius/chant-lexicon-fly";`);
+            lines.push("");
+        }
+        lines.push(...bodyLines);
+        return [{ path: "main.ts", content: lines.join("\n") + "\n" }];
+    }
+}
+function camelCase(str) {
+    return str
+        .replace(/[-_.](.)/g, (_, c) => c.toUpperCase())
+        .replace(/^(.)/, (_, c) => c.toLowerCase());
+}
+/**
+ * Format an object literal for the props of `ownerClass`. Fields whose declared
+ * type is a nested declarable are wrapped in their constructor; everything else
+ * is emitted as a plain literal.
+ */
+function formatProps(props, indent, ownerClass, imports) {
+    const entries = Object.entries(props);
+    if (entries.length === 0)
+        return "{}";
+    const pad = "  ".repeat(indent + 1);
+    const closePad = "  ".repeat(indent);
+    const nested = NESTED_DECLARABLES[ownerClass];
+    const lines = entries.map(([key, value]) => {
+        const spec = nested?.[key];
+        const rendered = spec !== undefined
+            ? formatNested(value, indent + 1, spec, imports)
+            : formatValue(value, indent + 1);
+        return `${pad}${key}: ${rendered},`;
+    });
+    return `{\n${lines.join("\n")}\n${closePad}}`;
+}
+/** Wrap a nested-declarable value in its constructor per the field's kind. */
+function formatNested(value, indent, spec, imports) {
+    const construct = (obj, at) => {
+        if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+            return formatValue(obj, at);
+        }
+        imports.add(spec.cls);
+        return `new ${spec.cls}(${formatProps(obj, at, spec.cls, imports)})`;
+    };
+    if (spec.kind === "single") {
+        return construct(value, indent);
+    }
+    if (spec.kind === "array") {
+        if (!Array.isArray(value) || value.length === 0)
+            return "[]";
+        const pad = "  ".repeat(indent + 1);
+        const closePad = "  ".repeat(indent);
+        const items = value.map((v) => `${pad}${construct(v, indent + 1)},`);
+        return `[\n${items.join("\n")}\n${closePad}]`;
+    }
+    // record: a plain object whose values are wrapped in the constructor.
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return formatValue(value, indent);
+    }
+    const record = value;
+    const recKeys = Object.entries(record);
+    if (recKeys.length === 0)
+        return "{}";
+    const pad = "  ".repeat(indent + 1);
+    const closePad = "  ".repeat(indent);
+    const items = recKeys.map(([k, v]) => `${pad}${JSON.stringify(k)}: ${construct(v, indent + 1)},`);
+    return `{\n${items.join("\n")}\n${closePad}}`;
+}
+function formatValue(value, indent) {
+    if (value === null || value === undefined)
+        return "undefined";
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return "[]";
+        const pad = "  ".repeat(indent + 1);
+        const closePad = "  ".repeat(indent);
+        const items = value.map((v) => `${pad}${formatValue(v, indent + 1)},`);
+        return `[\n${items.join("\n")}\n${closePad}]`;
+    }
+    if (typeof value === "object") {
+        return formatPlainObject(value, indent);
+    }
+    return String(value);
+}
+/** A plain object literal (no constructor wrapping) — for scalar-valued maps like env/metadata. */
+function formatPlainObject(obj, indent) {
+    const entries = Object.entries(obj);
+    if (entries.length === 0)
+        return "{}";
+    const pad = "  ".repeat(indent + 1);
+    const closePad = "  ".repeat(indent);
+    const lines = entries.map(([key, value]) => `${pad}${objectKey(key)}: ${formatValue(value, indent + 1)},`);
+    return `{\n${lines.join("\n")}\n${closePad}}`;
+}
+/** Emit a bare identifier key when it is a valid one, else a quoted key. */
+function objectKey(key) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
+}

package/dist/import/live-export.js

@@ -0,0 +1,81 @@
+/**
+ * Pure export helpers for the fly lexicon — strip live flaps state to the
+ * authored shape and build import IR from it. All flaps I/O stays in the caller
+ * (`../export-resources`); this module is deterministic and unit-testable.
+ *
+ * The strip mirrors the read-only field lists the parser drops, so a live
+ * machine/app reaches the same declared shape a user would have written. Machine
+ * ownership is a per-resource marker (`managed-by: chant` in `config.metadata`,
+ * read via `isChantOwned`); the app carries no marker, so under the `owned`
+ * filter its ownership is inferred at the app boundary (an app is chant-managed
+ * when one of its machines is), and the limitation is logged rather than
+ * silently returning everything — the seam contract, matching gcp/aws.
+ *
+ * `verbatim` is inert for fly (the core contract permits this for targets whose
+ * importable surface is already the declared shape): the App/Machine
+ * constructors accept only the writable surface, so server-written fields are
+ * not constructor parameters and cannot round-trip into the generated code. The
+ * option is accepted for signature parity.
+ */
+import { isChantOwned } from "../op/activities/fly-apply.js";
+import { FlyParser, MACHINE_SERVER_FIELDS, APP_SERVER_FIELDS, } from "./parser.js";
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Drop server-written read-only machine fields to reach the authored shape. Returns a new object. */
+export function stripMachineServerFields(machine) {
+    const clone = JSON.parse(JSON.stringify(machine));
+    for (const f of MACHINE_SERVER_FIELDS)
+        delete clone[f];
+    return clone;
+}
+/** Drop server-written read-only app fields, keeping `name`/`org_slug`. Returns a new object. */
+export function stripAppServerFields(app) {
+    const clone = JSON.parse(JSON.stringify(app));
+    // Carry the org slug down before dropping the organization object it rides on.
+    if (clone.org_slug === undefined && isRecord(clone.organization) && typeof clone.organization.slug === "string") {
+        clone.org_slug = clone.organization.slug;
+    }
+    for (const f of APP_SERVER_FIELDS)
+        delete clone[f];
+    return clone;
+}
+/**
+ * Build export IR from one app's live flaps state. Reuses {@link FlyParser} as
+ * the single wire→authoring mapping authority by feeding it a cleaned
+ * app-with-machines bundle.
+ *
+ * `opts.owned` keeps only machines carrying the chant marker, and includes the
+ * app only when it is chant-managed (a machine is). `opts.verbatim` keeps server
+ * fields. Pure: logging is delegated to `opts.onBoundaryInference`, which the
+ * I/O caller wires to a single warn.
+ */
+export function buildExportFromApp(app, machines, opts = {}) {
+    const appManaged = machines.some((m) => isChantOwned(m.config?.metadata));
+    const keptMachines = opts.owned
+        ? machines.filter((m) => isChantOwned(m.config?.metadata))
+        : machines;
+    // The app has no per-resource marker; under `owned` it rides the app boundary.
+    let keptApp = app;
+    if (opts.owned && app) {
+        opts.onBoundaryInference?.();
+        if (!appManaged)
+            keptApp = undefined;
+    }
+    // The parser maps to the writable surface regardless; the explicit strip here
+    // keeps the pure cleaning layer visible and testable. `verbatim` is inert (see
+    // module header) — server fields are not App/Machine constructor parameters.
+    const cleanMachines = keptMachines.map((m) => stripMachineServerFields(m));
+    const cleanApp = keptApp ? stripAppServerFields(keptApp) : keptApp;
+    const bundle = { ...(cleanApp ?? {}), machines: cleanMachines };
+    const ir = new FlyParser().parse(JSON.stringify(bundle));
+    const selector = opts.selector;
+    if (!selector || (selector.type === undefined && selector.name === undefined)) {
+        return ir;
+    }
+    return {
+        ...ir,
+        resources: ir.resources.filter((r) => (selector.type === undefined || r.type === selector.type) &&
+            (selector.name === undefined || r.logicalId === selector.name)),
+    };
+}

package/dist/import/parser.js

@@ -0,0 +1,157 @@
+/**
+ * flaps JSON template parser.
+ *
+ * Turns Fly Machines API ("flaps") JSON into the import IR for conversion to
+ * chant TypeScript. Three input shapes are accepted, all mapped to the authoring
+ * surface (the writable fields a user would have declared):
+ *
+ *   1. The #738 serializer plan — `{ <entity>: { endpoint, method, body } }`.
+ *      `/v1/apps` bodies become `App`s; `.../machines` bodies become `Machine`s.
+ *   2. A machines listing (an array) or an app-with-machines bundle
+ *      (`{ ...appFields, machines: [...] }`) — an `App` plus its `Machine`s.
+ *   3. A single machine (`{ name, region, config }`) or a single app
+ *      (`{ app_name }` / the `GET /v1/apps/{app}` shape).
+ *
+ * flaps wire field names are mapped back to the authoring surface: an app's
+ * `app_name` becomes the `App`'s `name`, and server-written read-only machine
+ * fields (id, state, instance_id, ...) are dropped so the IR is the declared
+ * shape. `logicalId` is the app/machine name (the generator camelCases it into a
+ * variable).
+ */
+import { BaseValueParser } from "@intentius/chant/import/base-parser";
+import { isSerializerPlan } from "../detect.js";
+export const APP_TYPE = "Fly::Machines::App";
+export const MACHINE_TYPE = "Fly::Machines::Machine";
+/** Server-written read-only machine fields — never part of the authored shape. */
+export const MACHINE_SERVER_FIELDS = [
+    "id",
+    "state",
+    "created_at",
+    "updated_at",
+    "private_ip",
+    "instance_id",
+    "nonce",
+    "checks",
+    "events",
+    "host_status",
+    "image_ref",
+    "incomplete_config",
+];
+/** Server-written read-only app fields — never part of the authored shape. */
+export const APP_SERVER_FIELDS = [
+    "id",
+    "status",
+    "machine_count",
+    "volume_count",
+    "internal_numeric_id",
+    "organization",
+];
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+export class FlyParser extends BaseValueParser {
+    dispatchIntrinsic(_key, _value, _obj) {
+        // flaps JSON has no intrinsic functions.
+        return null;
+    }
+    parse(input) {
+        const trimmed = input.trim();
+        if (!trimmed)
+            return { resources: [], parameters: [] };
+        const data = JSON.parse(trimmed);
+        const resources = [];
+        if (isSerializerPlan(data)) {
+            for (const [entityName, req] of Object.entries(data)) {
+                const r = this.resourceFromRequest(entityName, req);
+                if (r)
+                    resources.push(r);
+            }
+            return { resources, parameters: [] };
+        }
+        if (Array.isArray(data)) {
+            for (const m of data) {
+                if (isRecord(m))
+                    resources.push(this.machineResource(m));
+            }
+            return { resources, parameters: [] };
+        }
+        if (isRecord(data)) {
+            // App-with-machines bundle: top-level app fields plus a `machines` array.
+            if (Array.isArray(data.machines)) {
+                const { machines, ...appFields } = data;
+                if (this.looksLikeApp(appFields))
+                    resources.push(this.appResource(appFields));
+                for (const m of machines) {
+                    if (isRecord(m))
+                        resources.push(this.machineResource(m));
+                }
+                return { resources, parameters: [] };
+            }
+            // A single machine (has a config) wins over an app read, since a machine
+            // GET also carries a `name`.
+            if (isRecord(data.config)) {
+                resources.push(this.machineResource(data));
+                return { resources, parameters: [] };
+            }
+            if (this.looksLikeApp(data)) {
+                resources.push(this.appResource(data));
+                return { resources, parameters: [] };
+            }
+        }
+        return { resources, parameters: [] };
+    }
+    /** Map one serializer-plan request to a resource by its endpoint. */
+    resourceFromRequest(entityName, req) {
+        const endpoint = typeof req.endpoint === "string" ? req.endpoint : "";
+        const body = isRecord(req.body) ? req.body : {};
+        if (/^\/v1\/apps\/?$/.test(endpoint)) {
+            return this.appResource(body, entityName);
+        }
+        if (/^\/v1\/apps\/[^/]+\/machines\/?$/.test(endpoint)) {
+            return this.machineResource(body, entityName);
+        }
+        // Other endpoints (volumes, ip_assignments, certificates, secrets) are not
+        // part of the App/Machine import surface.
+        return null;
+    }
+    looksLikeApp(obj) {
+        return typeof obj.app_name === "string" || typeof obj.name === "string";
+    }
+    /** An `App` resource. flaps `app_name` (create body) or `name` (GET) → `name`. */
+    appResource(obj, entityName) {
+        const name = (typeof obj.app_name === "string" && obj.app_name) ||
+            (typeof obj.name === "string" && obj.name) ||
+            entityName ||
+            "app";
+        const properties = { name };
+        // org_slug either sits on the create body directly, or is carried on the GET
+        // shape under `organization.slug`.
+        if (obj.org_slug !== undefined) {
+            properties.org_slug = this.parseValue(obj.org_slug);
+        }
+        else if (isRecord(obj.organization) && typeof obj.organization.slug === "string") {
+            properties.org_slug = obj.organization.slug;
+        }
+        if (obj.network !== undefined)
+            properties.network = this.parseValue(obj.network);
+        if (obj.enable_subdomains !== undefined) {
+            properties.enable_subdomains = this.parseValue(obj.enable_subdomains);
+        }
+        return { logicalId: name, type: APP_TYPE, properties };
+    }
+    /** A `Machine` resource, stripped of server-written read-only fields. */
+    machineResource(obj, entityName) {
+        const name = (typeof obj.name === "string" && obj.name) || entityName || "machine";
+        const properties = {};
+        for (const [key, value] of Object.entries(obj)) {
+            if (MACHINE_SERVER_FIELDS.includes(key))
+                continue;
+            if (value === undefined)
+                continue;
+            properties[key] = this.parseValue(value);
+        }
+        // Always carry a name so the round-trip keeps the machine's identity.
+        properties.name = name;
+        return { logicalId: name, type: MACHINE_TYPE, properties };
+    }
+}

package/dist/index.js

@@ -0,0 +1,40 @@
+// Plugin
+export { flyPlugin } from "./plugin.js";
+// Component/release capabilities — run-agent, the sprite-lifecycle leaf
+// contributed to core's capability-plugin seam (#1942). Core loads
+// `flyCapabilityPlugin` when a project's chant.config lists this lexicon.
+export { flyCapabilityPlugin, FLY_VERB_FAMILIES } from "./components/capability-plugin.js";
+// Serializer
+export { flySerializer } from "./serializer.js";
+// Pseudo-parameters — environment-resolved values (`Fly.Region`, `Fly.OrgSlug`,
+// `Fly.AppName`) usable in place of hard-coded strings.
+export { Fly, Region, OrgSlug, AppName, PseudoParameter } from "./pseudo.js";
+// Ownership marker convention (machine config.metadata keys)
+export { FLY_METADATA_OWNERSHIP_KEYS } from "./ownership.js";
+// The release a Machine serves, in its metadata (#2736): read by
+// describeResources and compared with the release ledger by
+// `chant components status --live`.
+export { RELEASE_METADATA_KEYS, readMachineRelease, withReleaseMetadata } from "./release-metadata.js";
+// Deploy Op composite + typed step builders (#744). `flyDeploy` returns a
+// `boot → build → flyApply → wait → teardown` Op; the step builders wrap the
+// generic `activity()` so the fly activities resolve by name without a core change.
+export { flyDeploy, flapsUp, flapsDown, flyApplyStep, LOCAL_FLAPS_ENDPOINT } from "./composites/fly-deploy.js";
+// OpenTelemetry Collector on a Machine, its config declared with the otel lexicon (#2613).
+export { FlyOtelCollector } from "./composites/fly-otel-collector.js";
+// A Fly app that serves one app's releases: App, Machine, and its Volume, IP and Secrets (#2809, ws-056).
+export { FlySite } from "./composites/fly-site.js";
+// Sprite Op step builders. chant #1288 Stage 2: these author
+// `activity("spriteCreate", ...)` steps with authoring-time types derived
+// from this lexicon's own `Sprite*Args` interfaces (`./op/builders.ts`),
+// replacing the hand-restated inline types core's same-named builders used
+// to carry — same names, same import path, so an existing
+// `import { spriteCreate } from "@intentius/chant-lexicon-fly"` call site
+// gains real derived types with no change. `loadActivities(["fly"])` binds
+// the `fn` strings to the implementations in `./op/activities/sprites.ts`
+// etc. The `spritesUp`/`spritesDown` builders boot/tear down the spritzer
+// emulator as modeled steps.
+export { spriteCreate, spriteExec, spriteCheckpoint, spriteRestore, listCheckpoints, spriteDestroy, spriteDelete, spriteUrl, spriteWriteFile, spriteReadFile, spriteListDir, spriteRemove, spriteApplyNetworkPolicy, spriteApplyServices, spriteServiceCreate, spriteServiceGet, spriteServiceList, spriteServiceStart, spriteServiceStop, spriteServiceDelete, spriteServiceLogs, spriteServicesObserve, spriteServiceRestart, spriteTaskCreate, spriteTaskRefresh, spriteTaskRelease, spritesUp, spritesDown, flyMachineRelease, flyMachineExec, flyMachineRestart, flyMachineStop, flyMachineVerify, flyMachineRestore, flyRelease, flyRollback, } from "./op/builders.js";
+// Generated resources — export everything from generated index.
+// Provides `App`, `Machine`, `Volume`, and the property types
+// (`MachineConfig`, `MachineGuest`, `MachineService`, ...) for authoring.
+export * from "./generated/index.js";

package/dist/integrity.json

@@ -1,9 +1,9 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "a89985d3d10f194bc0f4b5f5bed682548ca1cde02de3a9e8a5353fcf66fa2a14",
+    "manifest.json": "4c0b65513cadb008353bf569e94010aabbd988d57482ded015f6e0cce8526054",
     "meta.json": "273f2a523b66f08ca91642dba2592c44765ab59ddf7329998884a0b08c6c3f24",
-    "types/index.d.ts": "8a3c9e7c4aa5aa61d49326b05b5b435ca3f5a9f82f3d885b66553dd74df0e49a",
+    "types/index.d.ts": "ca9b4c777e58e7ce2132f5f024e7a1b3d3f2ba4305d935aab85f6523469aed1e",
     "rules/guest-sizing.ts": "8dd2db79a47ceab3d488f84f560aed1b1e4a66b4e36bf11f3baf6a8544d6e126",
     "rules/no-secret-literals.ts": "3854307bd0e8d7a1bf6c23051b460b90f3212baa8bb2f7d4324d0e4418a69982",
     "rules/valid-region.ts": "238afb252ffb59ef131d070a705a49a1ac87b98f6a86c029a69dc82200e1aabf",
@@ -15,5 +15,5 @@
     "skills/chant-fly-ops.md": "44102f1fdf611b9262c04457258990e44026e83f9e5b19ae86b69322f3a37620",
     "skills/chant-fly-sprites.md": "3d100680422151b58d082c3a7b30a286edfc52faa4887995c9ad5553873bab95"
   },
-  "composite": "8558a0e3dde03b9a3b4c922bbf8ecaa09d3a9f67461df4998cfcf183c9f7cbe3"
+  "composite": "bbbdd32cead5547f480ccd70200d0dfca6541e2643baddd2f237400b6bc0ab22"
 }

package/dist/lint/audit-catalog.js

@@ -0,0 +1,28 @@
+/**
+ * The fly lexicon's chant audit catalog — metadata for the FLY post-synth
+ * checks, contributed via `flyPlugin.auditCatalog()` (#687).
+ *
+ * Both entries carry `yamlBased: false`: each check reads the chant model
+ * (`ctx.entities`) rather than the emitted manifest, because what they need —
+ * whether a mount's volume is declared in the same stack — lives in the typed
+ * graph and is gone by the time `fly.toml` exists. So they fire on
+ * `chant build` and cannot fire on an audit of standalone Fly config.
+ * `auditRule()` hardcodes `yamlBased: true`, so these are constructed directly
+ * (the same reasoning as fountain's catalog).
+ *
+ * Without this the two checks reached `chant audit` with no title, tier, fix
+ * kind, or category at all — `resolveAuditCatalog` contributes nothing for a
+ * lexicon that omits the method, silently (#1346).
+ */
+import { flyAuditLineage } from "./audit-lineage.js";
+import { applyLineage } from "@intentius/chant/audit/catalog";
+/** Entity-based rule: everything fly ships. */
+function rule(id, tier, category, title, remediation) {
+    return { id, tier, fixKind: "guidance", category, title, remediation, yamlBased: false };
+}
+export const flyAuditCatalog = {
+    FLY010: rule("FLY010", "merge-worthy", "correctness", "Machine config has no image", "Set `config.image` on the Machine — a Machine cannot boot without one."),
+    FLY011: rule("FLY011", "merge-worthy", "correctness", "Machine mount references an undeclared volume", "Declare the Volume in the same stack, or point the mount at one that is."),
+};
+// Prior art credits live beside the rules in ./audit-lineage.ts (see core audit/prior-art.ts).
+applyLineage(flyAuditCatalog, flyAuditLineage);

package/dist/lint/audit-lineage.js

@@ -0,0 +1,5 @@
+export const flyAuditLineage = {
+    FLY010: [
+        { tool: "fly-docs", rule: "Create a Machine: config.image required", url: "https://fly.io/docs/machines/api/machines-resource/#create-a-machine", relation: "overlaps" },
+    ],
+};

package/dist/lint/post-synth/fly-helpers.js

@@ -0,0 +1,24 @@
+/**
+ * Shared helpers for the fly post-synth checks. Not a check itself, so the
+ * generated barrel skips it (the scanner only picks up exported PostSynthChecks).
+ */
+/**
+ * Read an entity or property's constructor props. Nested Declarables
+ * (MachineConfig, MachineMount, Volume) stash their args under a non-enumerable
+ * `props`; a plain inline object carries them directly. Handle both so a check
+ * behaves the same whether the user authored `config: { image }` or
+ * `config: new MachineConfig({ image })`.
+ */
+export function readProps(value) {
+    if (value && typeof value === "object") {
+        const nested = value.props;
+        if (nested && typeof nested === "object")
+            return nested;
+        return value;
+    }
+    return {};
+}
+/** The entityType of a declarable, or undefined. */
+export function entityTypeOf(value) {
+    return value?.entityType;
+}

package/dist/lint/post-synth/fly010-machine-requires-image.js

@@ -0,0 +1,33 @@
+/**
+ * FLY010: Machine config must specify an image.
+ *
+ * A Machine cannot boot without a container image. The Machines API rejects a
+ * create request whose config omits `image`, so catch it at synth time with a
+ * clearer message.
+ */
+import { readProps, entityTypeOf } from "./fly-helpers.js";
+export const fly010 = {
+    id: "FLY010",
+    description: "Machine config must specify an image — a Machine cannot boot without one",
+    check(ctx) {
+        const diagnostics = [];
+        for (const [name, entity] of ctx.entities) {
+            if (entityTypeOf(entity) !== "Fly::Machines::Machine")
+                continue;
+            const config = readProps(entity).config;
+            if (!config)
+                continue; // no config authored — a different concern
+            const image = readProps(config).image;
+            if (typeof image !== "string" || image.length === 0) {
+                diagnostics.push({
+                    checkId: "FLY010",
+                    severity: "error",
+                    message: `Machine "${name}" config has no image — set config.image, e.g. image: "flyio/fastify-functions"`,
+                    entity: name,
+                    lexicon: "fly",
+                });
+            }
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/fly011-mount-references-declared-volume.js

@@ -0,0 +1,58 @@
+/**
+ * FLY011: A machine mount must reference a declared volume.
+ *
+ * Every machine `config.mounts[].volume` must resolve to a `Volume` declared in
+ * the stack. A mount pointing at a volume that does not exist is rejected at
+ * apply time, so catch it at synth. This is a whole-stack check: it reads all
+ * entities in the build (`ctx.entities`), so the mount and the Volume can be
+ * declared in different files.
+ */
+import { readProps, entityTypeOf } from "./fly-helpers.js";
+const MACHINE_ENTITY_TYPE = "Fly::Machines::Machine";
+const VOLUME_ENTITY_TYPE = "Fly::Machines::Volume";
+export const fly011 = {
+    id: "FLY011",
+    description: "A machine mount's volume must resolve to a Volume declared in the stack",
+    check(ctx) {
+        const diagnostics = [];
+        // A mount can name a declared volume by the Volume's `name` or by its
+        // logical (declaration) name — collect both.
+        const declaredVolumes = new Set();
+        for (const [logicalName, entity] of ctx.entities) {
+            if (entityTypeOf(entity) !== VOLUME_ENTITY_TYPE)
+                continue;
+            declaredVolumes.add(logicalName);
+            const name = readProps(entity).name;
+            if (typeof name === "string" && name.length > 0)
+                declaredVolumes.add(name);
+        }
+        for (const [machineName, entity] of ctx.entities) {
+            if (entityTypeOf(entity) !== MACHINE_ENTITY_TYPE)
+                continue;
+            const config = readProps(entity).config;
+            if (!config)
+                continue;
+            const mounts = readProps(config).mounts;
+            if (!Array.isArray(mounts))
+                continue;
+            for (const mount of mounts) {
+                const volume = readProps(mount).volume;
+                // Only a string names a volume by value. A Declarable/AttrRef is a live
+                // reference to a Volume that exists in the stack by construction, so it
+                // never dangles — skip it to avoid false positives.
+                if (typeof volume !== "string" || volume.length === 0)
+                    continue;
+                if (!declaredVolumes.has(volume)) {
+                    diagnostics.push({
+                        checkId: "FLY011",
+                        severity: "error",
+                        message: `Machine "${machineName}" mounts volume "${volume}", which is not declared as a Volume in the stack.`,
+                        entity: machineName,
+                        lexicon: "fly",
+                    });
+                }
+            }
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/index.js

@@ -0,0 +1,6 @@
+import { fly010 } from "./fly010-machine-requires-image.js";
+import { fly011 } from "./fly011-mount-references-declared-volume.js";
+export const postSynthChecks = [
+    fly010,
+    fly011,
+];