@intentius/chant-lexicon-fly 0.124.31 → 0.124.33

package/dist/lint/rules/guest-sizing.js

@@ -0,0 +1,92 @@
+import { ts } from "@intentius/chant/lint/typescript";
+/**
+ * Fly guest presets, per `cpu_kind`.
+ *
+ * `cpus` is the set of valid CPU counts; `memory_mb` must be a multiple of 256
+ * within [minPerCpu * cpus, maxPerCpu * cpus]. Values mirror Fly's published
+ * guest presets (shared-cpu-Nx / performance-Nx): shared allows 256–2048 MB per
+ * CPU, performance allows 2048–8192 MB per CPU. The 256 MB step is the loosest
+ * safe multiple, so a valid config is never flagged; only clearly-invalid combos
+ * are. fly-go was not vendored in this tree to cross-check against, so this table
+ * is a documented representative set (a limitation, widen if Fly changes presets).
+ */
+const GUEST_PRESETS = {
+    shared: { cpus: new Set([1, 2, 4, 8]), minPerCpu: 256, maxPerCpu: 2048 },
+    performance: { cpus: new Set([1, 2, 4, 8, 16]), minPerCpu: 2048, maxPerCpu: 8192 },
+};
+const MEMORY_STEP_MB = 256;
+/** Read a numeric property from an object literal, if present as a plain number literal. */
+function numberProp(obj, key, sf) {
+    for (const prop of obj.properties) {
+        if (ts.isPropertyAssignment(prop) && prop.name.getText(sf) === key && ts.isNumericLiteral(prop.initializer)) {
+            return Number(prop.initializer.text);
+        }
+    }
+    return undefined;
+}
+/** Read a string property from an object literal, if present as a plain string literal. */
+function stringProp(obj, key, sf) {
+    for (const prop of obj.properties) {
+        if (ts.isPropertyAssignment(prop) && prop.name.getText(sf) === key && ts.isStringLiteral(prop.initializer)) {
+            return prop.initializer.text;
+        }
+    }
+    return undefined;
+}
+/**
+ * FLY002: Sane guest sizing
+ *
+ * A guest's `cpu_kind`, `cpus`, and `memory_mb` must be a valid combination per
+ * Fly's guest presets. An invalid combination is rejected at apply time.
+ */
+export const guestSizingRule = {
+    id: "FLY002",
+    severity: "error",
+    category: "correctness",
+    description: "A guest's cpu_kind, cpus and memory_mb must be a valid Fly combination",
+    check(context) {
+        const { sourceFile } = context;
+        const diagnostics = [];
+        function report(node, message) {
+            const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+            diagnostics.push({
+                file: sourceFile.fileName,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "FLY002",
+                severity: "error",
+                message,
+            });
+        }
+        function visit(node) {
+            // A guest is any object literal carrying a cpu_kind property (new MachineGuest({...})
+            // or an inline guest object).
+            if (ts.isObjectLiteralExpression(node)) {
+                const cpuKind = stringProp(node, "cpu_kind", sourceFile);
+                if (cpuKind !== undefined) {
+                    const preset = GUEST_PRESETS[cpuKind];
+                    if (!preset) {
+                        report(node, `Invalid guest cpu_kind "${cpuKind}". Use "shared" or "performance".`);
+                    }
+                    else {
+                        const cpus = numberProp(node, "cpus", sourceFile);
+                        const memoryMb = numberProp(node, "memory_mb", sourceFile);
+                        if (cpus !== undefined && !preset.cpus.has(cpus)) {
+                            report(node, `Invalid guest sizing: cpu_kind "${cpuKind}" does not allow ${cpus} cpus (valid: ${[...preset.cpus].join(", ")}).`);
+                        }
+                        else if (cpus !== undefined && memoryMb !== undefined) {
+                            const min = preset.minPerCpu * cpus;
+                            const max = preset.maxPerCpu * cpus;
+                            if (memoryMb % MEMORY_STEP_MB !== 0 || memoryMb < min || memoryMb > max) {
+                                report(node, `Invalid guest sizing: ${cpuKind}/${cpus} cpu requires memory_mb between ${min} and ${max} in steps of ${MEMORY_STEP_MB}, got ${memoryMb}.`);
+                            }
+                        }
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(sourceFile);
+        return diagnostics;
+    },
+};

package/dist/lint/rules/index.js

@@ -0,0 +1,12 @@
+import { validRegionRule } from "./valid-region.js";
+import { guestSizingRule } from "./guest-sizing.js";
+import { noSecretLiteralsRule } from "./no-secret-literals.js";
+export { validRegionRule } from "./valid-region.js";
+export { guestSizingRule } from "./guest-sizing.js";
+export { noSecretLiteralsRule } from "./no-secret-literals.js";
+/** All lint rules provided by the fly lexicon. */
+export const rules = [
+    validRegionRule,
+    guestSizingRule,
+    noSecretLiteralsRule,
+];

package/dist/lint/rules/no-secret-literals.js

@@ -0,0 +1,58 @@
+import { ts } from "@intentius/chant/lint/typescript";
+/**
+ * Property names that carry a credential. Kept conservative on purpose — an
+ * inline value under one of these keys is very likely a real secret.
+ */
+const SECRET_KEY_PATTERN = /(?:^|[_-])(?:password|passwd|secret|token|api[_-]?key|apikey|access[_-]?key|secret[_-]?key|private[_-]?key|client[_-]?secret|credential|auth[_-]?token)(?:$|[_-])/i;
+/**
+ * Values that are references or placeholders, not literal secrets:
+ * shell/interpolation references ($FOO, ${FOO}), the OpenTelemetry
+ * Collector's environment substitution (${env:FOO}), and secret-manager
+ * style references. These are skipped so a `secrets` reference is never
+ * flagged.
+ */
+const REFERENCE_VALUE_PATTERN = /^(?:\$\{?(?:env:)?[A-Za-z0-9_]+\}?|(?:secret|ref|env|vault):\S+)$/;
+/**
+ * FLY004: No secret literals in machine config
+ *
+ * Flags secret values written inline in config (e.g. an env value under a
+ * credential-looking key). Secrets belong in `secrets` (apply-only) or a
+ * reference. The heuristic is conservative: it fires only when the property
+ * name looks like a credential AND the value is a plain string literal that is
+ * not a reference/placeholder, so a `secrets` reference (an identifier or
+ * `$FOO` placeholder) is not flagged.
+ */
+export const noSecretLiteralsRule = {
+    id: "FLY004",
+    severity: "warning",
+    category: "security",
+    description: "Secret values must not be written inline — use secrets or a reference",
+    check(context) {
+        const { sourceFile } = context;
+        const diagnostics = [];
+        function visit(node) {
+            if (ts.isPropertyAssignment(node)) {
+                const rawName = node.name.getText(sourceFile).replace(/^["']|["']$/g, "");
+                const init = node.initializer;
+                const literal = ts.isStringLiteral(init) || ts.isNoSubstitutionTemplateLiteral(init) ? init.text : undefined;
+                if (literal !== undefined &&
+                    literal.length >= 4 &&
+                    SECRET_KEY_PATTERN.test(rawName) &&
+                    !REFERENCE_VALUE_PATTERN.test(literal.trim())) {
+                    const { line, character } = sourceFile.getLineAndCharacterOfPosition(init.getStart(sourceFile));
+                    diagnostics.push({
+                        file: sourceFile.fileName,
+                        line: line + 1,
+                        column: character + 1,
+                        ruleId: "FLY004",
+                        severity: "warning",
+                        message: `Possible inline secret under "${rawName}". Move the value to \`secrets\` (apply-only) or use a reference instead of an inline literal.`,
+                    });
+                }
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(sourceFile);
+        return diagnostics;
+    },
+};

package/dist/lint/rules/valid-region.js

@@ -0,0 +1,52 @@
+import { ts } from "@intentius/chant/lint/typescript";
+/**
+ * Known Fly.io region codes.
+ *
+ * Sourced from the representative region list mudflaps serves at
+ * `GET /v1/platform/regions` (mudflaps `internal/server/regions.go`), which
+ * mirrors fly-go's `GetRegions` wire shape. The generated Fly types (#737)
+ * type `region` as a plain `string`, so there is no generated enum to import;
+ * this static set is the closest stable list a unit test can check without a
+ * live platform. It is representative, not exhaustive — add codes as Fly adds
+ * regions.
+ */
+const KNOWN_REGIONS = new Set([
+    "ams", "atl", "bog", "bos", "cdg", "den", "dfw", "ewr", "fra", "gru",
+    "hkg", "iad", "jnb", "lax", "lhr", "mad", "mia", "nrt", "ord", "scl",
+    "sea", "sin", "sjc", "syd", "yyz",
+]);
+/**
+ * FLY001: Valid Fly region
+ *
+ * A machine (or volume/IP) `region` must be a known Fly region code. An unknown
+ * region is rejected at apply time; catch it at build with a clearer message.
+ */
+export const validRegionRule = {
+    id: "FLY001",
+    severity: "error",
+    category: "correctness",
+    description: "A region must be a known Fly region code",
+    check(context) {
+        const { sourceFile } = context;
+        const diagnostics = [];
+        function visit(node) {
+            if (ts.isPropertyAssignment(node) && node.name.getText(sourceFile) === "region") {
+                const init = node.initializer;
+                if (ts.isStringLiteral(init) && init.text.length > 0 && !KNOWN_REGIONS.has(init.text)) {
+                    const { line, character } = sourceFile.getLineAndCharacterOfPosition(init.getStart(sourceFile));
+                    diagnostics.push({
+                        file: sourceFile.fileName,
+                        line: line + 1,
+                        column: character + 1,
+                        ruleId: "FLY001",
+                        severity: "error",
+                        message: `Unknown Fly region "${init.text}". Use a known region code, e.g. iad, lhr, sjc, fra, syd.`,
+                    });
+                }
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(sourceFile);
+        return diagnostics;
+    },
+};

package/dist/lsp/completions.js

@@ -0,0 +1,12 @@
+// import { LexiconIndex, lexiconCompletions } from "@intentius/chant/lsp/lexicon-providers";
+/**
+ * Provide LSP completions for fly resources.
+ *
+ * TODO: Build a LexiconIndex from your generated lexicon data
+ * and delegate to lexiconCompletions().
+ */
+export function completions(ctx) {
+    // const index = new LexiconIndex(lexiconData);
+    // return lexiconCompletions(ctx, index, "fly resource");
+    return [];
+}

package/dist/lsp/hover.js

@@ -0,0 +1,12 @@
+// import { LexiconIndex, lexiconHover } from "@intentius/chant/lsp/lexicon-providers";
+/**
+ * Provide LSP hover information for fly resources.
+ *
+ * TODO: Build a LexiconIndex from your generated lexicon data
+ * and delegate to lexiconHover().
+ */
+export function hover(ctx) {
+    // const index = new LexiconIndex(lexiconData);
+    // return lexiconHover(ctx, index, myCustomHoverFormatter);
+    return undefined;
+}

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "fly",
-  "version": "0.124.31",
+  "version": "0.124.33",
   "chantVersion": ">=0.1.0",
   "namespace": "Fly"
 }

package/dist/mcp/context-tools.js

@@ -0,0 +1,113 @@
+/**
+ * Read-only MCP tools that expose what `chant build` already computes about a
+ * Fly deploy — its apps and machines, the flaps create bodies, image pinning,
+ * and the lexicon's findings — so an agent can ask about a change *before it
+ * runs* (#804).
+ *
+ * Every tool builds from source and returns data. None touch a live Fly org,
+ * read run history, or write anything — the same context-producer boundary the
+ * AWS/GitLab context tools hold.
+ */
+import { build } from "@intentius/chant/build";
+import { runPostSynthChecks, getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+import { postSynthChecks } from "../lint/post-synth/index.js";
+import { flySerializer } from "../serializer.js";
+import { parsePlan, isAppRequest, isMachineRequest } from "../op/activities/fly-apply.js";
+const PATH_INPUT = {
+    type: "object",
+    properties: {
+        path: { type: "string", description: "Path to the chant project directory (default: current directory)" },
+    },
+};
+/** Build the project and parse the flaps plan the serializer emits. */
+async function buildFly(path) {
+    const result = await build(path || ".", [flySerializer]);
+    const output = result.outputs.get("fly");
+    let plan = {};
+    if (output) {
+        try {
+            plan = parsePlan(getPrimaryOutput(output));
+        }
+        catch {
+            // not a parseable fly plan — leave empty
+        }
+    }
+    return { plan, result, output };
+}
+const machineImage = (req) => {
+    const config = req.body.config;
+    return typeof config?.image === "string" ? config.image : undefined;
+};
+/** A container image reference is pinned when it names a digest, not a tag. */
+export function imagePinned(image) {
+    return image.includes("@sha256:");
+}
+export function flyContextTools() {
+    return [
+        {
+            name: "fly:app",
+            description: "Build the project and summarize the declared Fly apps and machines — regions, images, guest sizing — from source. Read-only; never touches a live Fly org.",
+            inputSchema: PATH_INPUT,
+            async handler(params) {
+                const { plan } = await buildFly(String(params.path ?? "."));
+                const apps = [];
+                const machines = [];
+                for (const [name, req] of Object.entries(plan)) {
+                    if (isAppRequest(req)) {
+                        apps.push({ name: String(req.body.app_name ?? name), org_slug: req.body.org_slug ?? null });
+                    }
+                    else if (isMachineRequest(req)) {
+                        machines.push({
+                            name: String(req.body.name ?? name),
+                            region: req.body.region ?? null,
+                            image: machineImage(req) ?? null,
+                            guest: req.body.config?.guest ?? null,
+                        });
+                    }
+                }
+                return { apps, machines };
+            },
+        },
+        {
+            name: "fly:checks",
+            description: "Build the project and return the fly lexicon's post-synth findings (machine requires an image, a mount references a declared Volume) as JSON. Read-only.",
+            inputSchema: PATH_INPUT,
+            async handler(params) {
+                const { output, result } = await buildFly(String(params.path ?? "."));
+                if (!output)
+                    return { findings: [], note: "no Fly plan produced from this project" };
+                const scoped = { ...result, outputs: new Map([["fly", output]]) };
+                const diags = runPostSynthChecks(postSynthChecks, scoped);
+                return {
+                    findings: diags.map((d) => ({ id: d.checkId, severity: d.severity, entity: d.entity ?? null, message: d.message })),
+                };
+            },
+        },
+        {
+            name: "fly:references",
+            description: "Build the project and list each machine's container image and whether it is pinned to a digest (vs a floating tag). Read-only.",
+            inputSchema: PATH_INPUT,
+            async handler(params) {
+                const { plan } = await buildFly(String(params.path ?? "."));
+                const images = [];
+                for (const [name, req] of Object.entries(plan)) {
+                    if (!isMachineRequest(req))
+                        continue;
+                    const image = machineImage(req);
+                    if (image)
+                        images.push({ machine: String(req.body.name ?? name), image, pinned: imagePinned(image) });
+                }
+                return images;
+            },
+        },
+        {
+            name: "fly:plan",
+            description: "Build the project and return the flaps create bodies the serializer emits — exactly what flyApply would POST to the Machines API. Read-only.",
+            inputSchema: PATH_INPUT,
+            async handler(params) {
+                const { plan } = await buildFly(String(params.path ?? "."));
+                return plan;
+            },
+        },
+    ];
+}

package/dist/okf/types/Machine.md

@@ -12,7 +12,7 @@ resource_type: Fly::Machines::Machine
 
 - `config` (`MachineConfig`, optional): An object defining the Machine configuration
 - `lease_ttl` (`number`, optional)
-- `min_secrets_version` (`number`, optional)
+- `min_secrets_version` (`number`, optional): 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.
 - `name` (`string`, optional): Unique name for this Machine. If omitted, one is generated for you
 - `region` (`string`, optional): The target region. Omitting this param launches in the same region as your WireGuard peer connection (somewhere near you).
 - `skip_launch` (`boolean`, optional)

package/dist/op/activities/box-services.js

@@ -0,0 +1,88 @@
+/**
+ * A box's declared services (#2880), read for the activities that take
+ * `box: true`: `spriteServicesObserve`, `spriteServiceRestart` and
+ * `spriteApplyServices`.
+ *
+ * The list is the `services` of the box block of the workspace member whose
+ * directory holds the working directory, read with core's declaration reader
+ * (`@intentius/chant/workspace/box-services`), so it is checked the way
+ * `chant workspace check` checks it. The module is imported when a step
+ * runs, since a core older than the field has no such module.
+ */
+/** The box block's services for the member whose directory holds `cwd`, in file order. */
+export async function boxServices(cwd = process.cwd()) {
+    let mod;
+    try {
+        mod = await import("@intentius/chant/workspace/box-services");
+    }
+    catch (err) {
+        const why = err instanceof Error ? err.message.split("\n")[0] : String(err);
+        throw new Error(`box: true reads the box block through @intentius/chant 0.95.0 or newer, and the chant installed here has no workspace/box-services module (${why})`);
+    }
+    return mod.readBoxServices(cwd).services.map((s) => ({
+        name: s.name,
+        cmd: s.cmd,
+        needs: [...s.needs],
+        httpPort: s.httpPort,
+        duration: s.duration,
+        health: s.health,
+        optional: s.optional,
+    }));
+}
+/**
+ * A service's command with each `${VAR}` replaced from `env`. Throws naming
+ * the first variable `env` does not set, so no service is defined with an
+ * empty path in it. Pure.
+ */
+export function expandServiceCommand(name, cmd, env = process.env) {
+    return cmd.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, v) => {
+        const value = env[v];
+        if (value === undefined)
+            throw new Error(`service ${name}'s cmd names \${${v}}, which is not set in this process's environment`);
+        return value;
+    });
+}
+/**
+ * A service's command as the supervisor runs it: the executable and its
+ * arguments. The declared `cmd` is split on whitespace, with no quoting or
+ * other shell syntax (a command that needs it belongs in a script), and each
+ * word is then expanded by {@link expandServiceCommand}, so a variable whose
+ * value has a space stays one word. sprite-env takes the arguments as one
+ * comma-separated `--args`, so an argument with a comma in it is refused
+ * here rather than split there. Pure.
+ */
+export function serviceCommandArgv(name, cmd, env = process.env) {
+    const words = cmd.trim().split(/\s+/).filter((w) => w !== "");
+    if (words.length === 0)
+        throw new Error(`service ${name}'s cmd is empty`);
+    const argv = words.map((w) => expandServiceCommand(name, w, env));
+    const comma = argv.slice(1).find((a) => a.includes(","));
+    if (comma !== undefined) {
+        throw new Error(`service ${name}'s cmd has the argument ${JSON.stringify(comma)}, and sprite-env's --args is comma-separated, so it can't carry a comma; run the command from a script`);
+    }
+    return argv;
+}
+/**
+ * The services in an order each one's `needs` come before it, and in file
+ * order otherwise. The list is one the declaration reader accepted, so every
+ * `needs` is declared and none forms a cycle. Pure.
+ */
+export function inStartOrder(services) {
+    const byName = new Map(services.map((s) => [s.name, s]));
+    const done = new Set();
+    const out = [];
+    const visit = (s) => {
+        if (done.has(s.name))
+            return;
+        done.add(s.name);
+        for (const n of s.needs) {
+            const dep = byName.get(n);
+            if (dep)
+                visit(dep);
+        }
+        out.push(s);
+    };
+    for (const s of services)
+        visit(s);
+    return out;
+}

package/dist/op/activities/emulator-images.js

@@ -0,0 +1,32 @@
+/**
+ * Single source of truth for the Fly emulator image pins (#808 T2).
+ *
+ * mudflaps (Machines API) and spritzer (Sprites API) are the local fakes fly's
+ * activities are exercised against. These tags were previously duplicated across
+ * flaps.ts, sprites-emulator.ts, the fly-deploy composite, and tests — and had
+ * already drifted (the composite's docstring said mudflaps 0.3.0 while the
+ * activity pinned 0.3.1). Pin each here so a bump touches one line and the
+ * emulator-freshness check (#808 T2) has a single target to compare against the
+ * latest GHCR release.
+ *
+ * Bump policy (#808): move these only when a consuming test needs a newer
+ * emulator (a fidelity fix the activities exercise), not on every emulator
+ * release. For new upstream API surface the emulator leads, then fly bumps here.
+ */
+/** Pinned mudflaps (Fly Machines / flaps emulator) image. */
+export const MUDFLAPS_IMAGE = "ghcr.io/intentius/mudflaps:0.4.1";
+/** Pinned spritzer (Fly Sprites emulator) image. */
+export const SPRITZER_IMAGE = "ghcr.io/intentius/spritzer:0.4.1";
+/**
+ * Pinned spritzer image for container exec mode (`SPRITZER_EXEC=container`,
+ * #2711 / INTENTIUS/spritzer#22) — the Services CRUD activities
+ * (`./sprite-services.ts`) and `spriteUrl` only exist in this mode (real
+ * processes, a real sprite URL); the default `SPRITZER_IMAGE` above stays on
+ * the interpreter-mode pin everything else is tested against. 0.6.0 is the
+ * first release with container mode at all, so this can't move to a shared
+ * pin until interpreter mode also needs 0.6.1 for something else (#808 bump
+ * policy). 0.6.1 fixes `POST /policy/network` to answer 204 with no body, as
+ * the real Sprites API and every official SDK expect (#2719,
+ * INTENTIUS/spritzer#26/#27) — a fidelity fix the activities exercise.
+ */
+export const SPRITZER_CONTAINER_IMAGE = "ghcr.io/intentius/spritzer:0.6.1";

package/dist/op/activities/flaps.js

@@ -0,0 +1,34 @@
+import { emulatorLifecycle } from "@intentius/chant/op";
+import { MUDFLAPS_IMAGE } from "./emulator-images.js";
+// mudflaps is a stateful fake of the Fly Machines API (flaps) — a plain 200 on
+// its health endpoint means ready. The local target for flyApply; point it there
+// with FLY_FLAPS_BASE_URL. Shared lifecycle: emulatorLifecycle (#746).
+export const MUDFLAPS_SPEC = {
+    name: "chant-mudflaps",
+    image: MUDFLAPS_IMAGE,
+    containerPort: 4280,
+    healthPath: "/_mudflaps/health",
+    upstream: { repo: "intentius/mudflaps" },
+};
+/**
+ * The Machines half of fly's emulator capability (#1345).
+ *
+ * fly ships two emulators, and `LexiconPlugin.emulator` held exactly one until
+ * #1345 widened it — so neither was declared and `chant emulator` reported fly
+ * as having none, while the tutorials booted mudflaps through `chant run`.
+ */
+export const MUDFLAPS_EMULATOR = {
+    spec: MUDFLAPS_SPEC,
+    env: (endpoint) => ({ FLY_FLAPS_BASE_URL: endpoint }),
+};
+const flaps = emulatorLifecycle(MUDFLAPS_SPEC);
+export const flapsExistsCommand = flaps.existsCommand;
+export const flapsRmCommand = flaps.rmCommand;
+export const flapsHealthUrl = flaps.healthUrl;
+/** The flaps endpoint URL (what `flyApply`'s `FLY_FLAPS_BASE_URL`/`endpoint` points at). */
+export const flapsEndpoint = flaps.endpoint;
+export const flapsRunCommand = (args = {}) => flaps.runCommand(args);
+/** Boot a local mudflaps (Fly Machines API emulator) in Docker and return its endpoint. */
+export const flapsUp = (args = {}, signal) => flaps.up(args, signal);
+/** Stop and remove the local mudflaps container (no-op if already gone). */
+export const flapsDown = (args = {}, signal) => flaps.down(args, signal);