@intentius/chant-lexicon-fly 0.124.31 → 0.124.32

package/dist/codegen/docs-cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env tsx
+import { generateDocs } from "./docs.js";
+generateDocs({ verbose: true }).catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/codegen/docs.js

@@ -0,0 +1,143 @@
+/**
+ * fly (Machines API / "flaps") documentation generator.
+ *
+ * Calls the core docsPipeline with fly-specific config: service grouping and
+ * overview content. writeDocsSite puts the pages in the main docs site under
+ * docs/src/content/docs/lexicons/fly/ (chant #3993).
+ */
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+/**
+ * Group a fly resource type into a service bucket for the reference sidebar.
+ * fly type names are `Fly::Machines::<Kind>`, so the middle segment is always
+ * "Machines"; grouping by the leaf kind gives a more useful split (Apps,
+ * Machines, Storage, Networking, Secrets).
+ */
+export function serviceFromType(resourceType) {
+    const kind = resourceType.split("::")[2] ?? resourceType;
+    switch (kind) {
+        case "App":
+            return "Apps";
+        case "Machine":
+            return "Machines";
+        case "Volume":
+            return "Storage";
+        case "IPAddress":
+        case "Certificate":
+            return "Networking";
+        case "Secret":
+            return "Secrets";
+        default:
+            return "Machines";
+    }
+}
+const overview = `The **Fly Machines** lexicon defines Fly.io apps and machines using chant's declarative TypeScript syntax. Resources are serialized to the JSON create bodies the Machines API ("flaps") accepts, so the applier can POST them straight through and the mudflaps emulator can round-trip them offline.
+
+This lexicon is generated from Fly's published [Machines API OpenAPI spec](https://docs.machines.dev/openapi.json).
+
+Install it with:
+
+\`\`\`bash
+npm install --save-dev @intentius/chant-lexicon-fly
+\`\`\`
+
+## Quick Start
+
+\`\`\`typescript
+import { App, Machine, MachineConfig, MachineGuest, Fly } from "@intentius/chant-lexicon-fly";
+
+const app = new App({ name: "my-app", org_slug: Fly.OrgSlug });
+
+const web = new Machine({
+  name: "web",
+  region: Fly.Region,
+  config: new MachineConfig({
+    image: "flyio/hellofly:latest",
+    guest: new MachineGuest({ cpu_kind: "shared", cpus: 1, memory_mb: 256 }),
+  }),
+});
+
+export { app, web };
+\`\`\`
+
+\`Fly.Region\` and \`Fly.OrgSlug\` are pseudo-parameters resolved from the environment at build time (\`FLY_REGION\`, \`FLY_ORG\` / \`FLY_ORG_SLUG\`).`;
+const outputFormat = `The fly lexicon serializes resources into the JSON create bodies the Machines API ("flaps") accepts.
+
+## Building
+
+Each declared resource becomes a single flaps request keyed by its logical name:
+
+\`\`\`json
+{
+  "web": {
+    "endpoint": "/v1/apps/my-app/machines",
+    "method": "POST",
+    "body": { "name": "web", "region": "iad", "config": { ... } }
+  }
+}
+\`\`\`
+
+- An \`App\` becomes \`POST /v1/apps { app_name, org_slug? }\`.
+- A \`Machine\` becomes \`POST /v1/apps/{app}/machines\` with the full \`MachineConfig\` as \`config\`. The owning app is a URL path segment, not a body field.
+- \`Volume\`, \`IPAddress\`, \`Certificate\`, and \`Secret\` are app-scoped and POST under their app.
+
+Every serialized machine carries the \`managed-by: chant\` ownership marker in \`config.metadata\`, which the owned-only prune reads back.
+
+## Telemetry attribution
+
+Inside a workspace, the fly lexicon adds two variables to each Machine's \`config.env\`, so that its spans name the declaration that produced them ([#3060](https://github.com/INTENTIUS/chant/issues/3060), [ws-060](https://github.com/INTENTIUS/chant/blob/main/docs/design/decisions/ws-060-telemetry-attribution.md)).
+
+\`\`\`json
+"env": {
+  "PORT": "8080",
+  "OTEL_SERVICE_NAME": "notes",
+  "OTEL_RESOURCE_ATTRIBUTES": "chant.workspace=acme,chant.member=svc,chant.decl=web"
+}
+\`\`\`
+
+\`OTEL_SERVICE_NAME\` is the name of the Machine's app on Fly, or the Machine's export name when the build can't tell which app owns it. \`chant.decl\` is the Machine's export name. \`deployment.environment.name\` is added when the build has an environment (\`--env\` or \`ownership.env\`), and an image pinned by digest adds \`service.version\`. A value the Machine already sets is kept, and only the missing attributes are added. An \`App\` has no env, so only Machines are stamped. A project with no \`chant.workspace.json\` builds the same plan as before unless \`telemetry.attribution: true\` opts it in, and \`telemetry.attribution: false\` turns stamping off inside a workspace.
+
+A Machine's env values are literal strings, so the plan carries no reference to \`CHANT_RELEASE_ATTRIBUTES\` ([ws-081](https://github.com/INTENTIUS/chant/blob/main/docs/design/decisions/ws-081-release-attributes-at-deploy.md)). The \`fly-release\` step writes the release into the Machine it serves instead: on a stamped Machine, \`OTEL_RESOURCE_ATTRIBUTES\` gets \`service.version\` (the release's digest) and \`vcs.ref.head.revision\` (its commit), the same release its metadata names. A plain apply of the plan carries no release.
+
+## Applying
+
+The output is applied against flaps directly (or the mudflaps emulator offline). Endpoint and auth come from \`FLY_FLAPS_BASE_URL\` and \`FLY_API_TOKEN\`.
+
+A \`Secret\` with a \`value\` is set on every apply. A \`Secret\` with no value is one you set outside chant, for example with \`fly secrets set\`. Apply never sends it. It checks that the app has the secret, and fails with the secret's name if the app does not. The \`name\` prop sets the secret's name on the app and defaults to the export name.
+
+The applier writes its progress lines to stderr, so an Op step's stdout carries only its output.
+
+## Reading live state
+
+The helpers the applier reads live state with are exported from \`@intentius/chant-lexicon-fly/op/activities\`. \`listMachines\`, \`listVolumes\`, \`listIps\`, \`listCerts\` and \`listSecrets\` each take an \`ApplyCtx\`, an app name and a \`FlyHttp\`, and return what flaps lists for that app. \`listSecrets\` returns names only, never values. Build the context with \`resolveEndpoint\` and the client with \`defaultFlyHttp\`, as apply does:
+
+\`\`\`typescript
+import { defaultFlyHttp, listSecrets, resolveEndpoint } from "@intentius/chant-lexicon-fly/op/activities";
+
+const ctx = { base: resolveEndpoint({}) };
+const secrets = await listSecrets(ctx, "my-app", defaultFlyHttp());
+\`\`\``;
+/**
+ * Generate documentation for the fly Machines lexicon.
+ */
+export async function generateDocs(options) {
+    const config = {
+        name: "fly",
+        displayName: "Fly Machines",
+        description: "Typed constructors for Fly.io apps and machines, serialized to Machines API create bodies",
+        distDir: join(pkgDir, "dist"),
+        outDir: join(pkgDir, "docs"),
+        srcDir: join(pkgDir, "src"),
+        basePath: process.env.DOCS_BASE_PATH ?? "/chant/lexicons/fly/",
+        overview,
+        outputFormat,
+        serviceFromType,
+    };
+    const result = docsPipeline(config);
+    writeDocsSite(config, result);
+    if (options?.verbose) {
+        console.error(`Generated docs: ${result.stats.resources} resources, ${result.stats.properties} properties, ${result.stats.services} services, ${result.stats.rules} rules`);
+    }
+}

package/dist/codegen/generate-cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for fly lexicon generation.
+ */
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { generate, writeGeneratedFiles } from "./generate.js";
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+async function main() {
+    const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
+    const force = process.argv.includes("--force") || process.argv.includes("-f");
+    console.error("Generating fly lexicon...");
+    const result = await generate({ verbose, force });
+    writeGeneratedFiles(result, pkgDir);
+    console.error(`Generated ${result.resources} resources, ${result.properties} property types, ${result.enums} enums`);
+    if (result.warnings.length > 0) {
+        console.error(`${result.warnings.length} warnings:`);
+        for (const w of result.warnings) {
+            console.error(`  ${w.file}: ${w.error}`);
+        }
+    }
+}
+main().catch((err) => {
+    console.error("Generation failed:", err);
+    process.exit(1);
+});

package/dist/codegen/generate-lexicon.js

@@ -0,0 +1,38 @@
+/**
+ * Lexicon JSON generator — produces lexicon-fly.json with metadata for the
+ * fly resource and property types.
+ */
+import { flyShortName } from "../spec/parse.js";
+import { buildRegistry, serializeRegistry } from "@intentius/chant/codegen/generate-registry";
+/**
+ * Generate the lexicon-fly.json content.
+ */
+export function generateLexiconJSON(results, naming) {
+    const registryResources = results.map((r) => ({
+        typeName: r.resource.typeName,
+        attributes: r.resource.attributes,
+        properties: r.resource.properties,
+        propertyTypes: [],
+    }));
+    const entries = buildRegistry(registryResources, naming, {
+        shortName: flyShortName,
+        buildEntry: (resource, _tsName, _attrs, propConstraints) => {
+            const r = results.find((res) => res.resource.typeName === resource.typeName);
+            const entry = {
+                resourceType: resource.typeName,
+                kind: r?.isProperty ? "property" : "resource",
+                lexicon: "fly",
+            };
+            if (propConstraints && Object.keys(propConstraints).length > 0) {
+                entry.constraints = propConstraints;
+            }
+            return entry;
+        },
+        buildPropertyEntry: (resourceType, propertyType) => ({
+            resourceType: `${resourceType}.${propertyType}`,
+            kind: "property",
+            lexicon: "fly",
+        }),
+    });
+    return serializeRegistry(entries);
+}

package/dist/codegen/generate-typescript.js

@@ -0,0 +1,45 @@
+/**
+ * TypeScript declaration file generator — produces index.d.ts with the fly
+ * resource classes (App, Machine, Volume) and their property-type classes.
+ */
+import { writeResourceClass, writePropertyClass, } from "@intentius/chant/codegen/generate-typescript";
+/**
+ * Generate the complete .d.ts file content.
+ */
+export function generateTypeScriptDeclarations(results, naming) {
+    const lines = [];
+    lines.push("// Code generated by chant fly generate. DO NOT EDIT.");
+    const entries = [];
+    for (const r of results) {
+        const tsName = naming.resolve(r.resource.typeName);
+        if (!tsName)
+            continue;
+        const properties = r.resource.properties.map((p) => ({
+            name: p.name,
+            type: p.tsType,
+            required: p.required,
+            description: p.description,
+        }));
+        const attributes = r.resource.attributes.map((a) => ({ name: a.name, type: a.tsType }));
+        entries.push({ tsName, isProperty: !!r.isProperty, properties, attributes });
+    }
+    entries.sort((a, b) => a.tsName.localeCompare(b.tsName));
+    const resources = entries.filter((e) => !e.isProperty);
+    const propertyTypes = entries.filter((e) => e.isProperty);
+    if (resources.length > 0) {
+        lines.push("");
+        lines.push("// --- Fly Resource classes ---");
+        for (const re of resources) {
+            writeResourceClass(lines, re.tsName, re.properties, re.attributes);
+        }
+    }
+    if (propertyTypes.length > 0) {
+        lines.push("");
+        lines.push("// --- Property type classes ---");
+        for (const pe of propertyTypes) {
+            writePropertyClass(lines, pe.tsName, pe.properties);
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/codegen/generate.js

@@ -0,0 +1,82 @@
+/**
+ * Fly generation pipeline — uses core generatePipeline with fly-specific
+ * fetch, parse, naming, and generation callbacks.
+ */
+import { generatePipeline, writeGeneratedArtifacts, } from "@intentius/chant/codegen/generate";
+import { fetchSchemas } from "../spec/fetch.js";
+import { parseFlyOpenAPI } from "../spec/parse.js";
+import { NamingStrategy } from "./naming.js";
+import { generateLexiconJSON } from "./generate-lexicon.js";
+import { generateTypeScriptDeclarations } from "./generate-typescript.js";
+import { generateRuntimeIndex as coreGenerateRuntimeIndex, } from "@intentius/chant/codegen/generate-runtime-index";
+/**
+ * Run the full fly generation pipeline.
+ */
+export async function generate(opts = {}) {
+    // The flaps spec is a single document — parseFlyOpenAPI returns multiple
+    // results. The pipeline calls parseSchema once, so we return the first result
+    // and inject the rest via augmentResults.
+    let pendingResults = [];
+    const config = {
+        fetchSchemas: (fetchOpts) => fetchSchemas({ force: fetchOpts.force }),
+        parseSchema: (_typeName, data) => {
+            const results = parseFlyOpenAPI(data);
+            if (results.length === 0)
+                return null;
+            pendingResults = results.slice(1);
+            return results[0];
+        },
+        createNaming: (results) => new NamingStrategy(results),
+        augmentResults: (results, _opts, log) => {
+            if (pendingResults.length > 0) {
+                results.push(...pendingResults);
+                log(`Added ${pendingResults.length} additional fly schemas from OpenAPI spec`);
+                pendingResults = [];
+            }
+            log(`Total: ${results.length} fly resource/property schemas`);
+            return { results };
+        },
+        generateRegistry: (results, naming) => generateLexiconJSON(results, naming),
+        generateTypes: (results, naming) => generateTypeScriptDeclarations(results, naming),
+        generateRuntimeIndex: (results, naming) => generateRuntimeIndex(results, naming),
+    };
+    return generatePipeline(config, opts);
+}
+/**
+ * Write generated artifacts to disk.
+ */
+export function writeGeneratedFiles(result, baseDir) {
+    writeGeneratedArtifacts({
+        baseDir,
+        files: {
+            "lexicon-fly.json": result.lexiconJSON,
+            "index.d.ts": result.typesDTS,
+            "index.ts": result.indexTS,
+            "runtime.ts": `/**\n * Runtime factory constructors — re-exported from core.\n */\nexport { createResource, createProperty } from "@intentius/chant/runtime";\n`,
+        },
+    });
+}
+/**
+ * Generate the runtime index.ts with factory constructor exports.
+ */
+function generateRuntimeIndex(results, naming) {
+    const resourceEntries = [];
+    const propertyEntries = [];
+    for (const r of results) {
+        const typeName = r.resource.typeName;
+        const tsName = naming.resolve(typeName);
+        if (!tsName)
+            continue;
+        if (r.isProperty) {
+            propertyEntries.push({ tsName, resourceType: typeName });
+        }
+        else {
+            const attrs = {};
+            for (const attr of r.resource.attributes) {
+                attrs[attr.name] = attr.name;
+            }
+            resourceEntries.push({ tsName, resourceType: typeName, attrs });
+        }
+    }
+    return coreGenerateRuntimeIndex(resourceEntries, propertyEntries, { lexiconName: "fly" });
+}

package/dist/codegen/naming.js

@@ -0,0 +1,33 @@
+/**
+ * Fly naming strategy — maps Fly::Machines::{Kind} type names to
+ * user-friendly TypeScript class names.
+ */
+import { NamingStrategy as CoreNamingStrategy, } from "@intentius/chant/codegen/naming";
+import { flyShortName, flyServiceName } from "../spec/parse.js";
+export { propertyTypeName, extractDefName } from "@intentius/chant/codegen/naming";
+const flyNamingConfig = {
+    priorityNames: {
+        "Fly::Machines::App": "App",
+        "Fly::Machines::Machine": "Machine",
+        "Fly::Machines::Volume": "Volume",
+    },
+    priorityAliases: {},
+    priorityPropertyAliases: {},
+    serviceAbbreviations: {
+        Machines: "Machines",
+    },
+    shortName: flyShortName,
+    serviceName: flyServiceName,
+};
+/**
+ * Fly-specific naming strategy. Extends the core strategy with the fly config.
+ */
+export class NamingStrategy extends CoreNamingStrategy {
+    constructor(results) {
+        const inputs = results.map((r) => ({
+            typeName: r.resource.typeName,
+            propertyTypes: r.propertyTypes,
+        }));
+        super(inputs, flyNamingConfig);
+    }
+}

package/dist/codegen/package.js

@@ -0,0 +1,35 @@
+import { packagePipeline, collectSkills } from "@intentius/chant/codegen/package";
+import { generate } from "./generate.js";
+import { flyPlugin } from "../plugin.js";
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+/**
+ * Package the fly lexicon for distribution.
+ */
+export async function packageLexicon(options) {
+    // This file is src/codegen/package.ts — rules and skills are collected
+    // 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(moduleSourceDir(import.meta.url));
+    const pkgJson = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8"));
+    const { spec, stats } = await packagePipeline({
+        generate: (opts) => generate({ verbose: opts?.verbose, force: opts?.force }),
+        // chant #1067 — chantVersion/namespace/version were never populated here
+        // (a hardcoded "0.0.1", never the real package version), so
+        // `dist/manifest.json` shipped without a chantVersion at all. Matches
+        // the shape every other lexicon's codegen/package.ts already uses.
+        buildManifest: (_genResult) => ({
+            name: "fly",
+            version: pkgJson.version ?? "0.0.0",
+            chantVersion: ">=0.1.0",
+            namespace: "Fly",
+        }),
+        srcDir,
+        collectSkills: () => collectSkills(flyPlugin.skills?.() ?? []),
+    });
+    // Both callers (the plugin's package() and package-cli) print their own
+    // summary — don't double-report here.
+    return { spec, stats };
+}

package/dist/components/capability-plugin.js

@@ -0,0 +1,26 @@
+import { ownPackageVersion } from "@intentius/chant/components/capability-plugin";
+import { flyRunAgentCapability } from "./run-agent.js";
+import { flyReleaseCapability, flyRollbackCapability } from "./fly-release.js";
+export const FLY_VERB_FAMILIES = {
+    agentExecution: ["run-agent"],
+    // A release served by a Fly Machine, and going back to an earlier one (#2736).
+    apply: ["fly-release", "fly-rollback"],
+};
+export const flyCapabilityPlugin = {
+    name: "fly",
+    // The lexicon package's own version (mirrors aws/helm's #1505 fix — a
+    // getter so the package.json read happens on first access, not at import time).
+    get version() {
+        return ownPackageVersion(import.meta.url);
+    },
+    capabilities() {
+        return [
+            flyRunAgentCapability,
+            flyReleaseCapability,
+            flyRollbackCapability,
+        ];
+    },
+    families() {
+        return FLY_VERB_FAMILIES;
+    },
+};