@intentius/chant-lexicon-fly 0.16.0

package/src/codegen/docs.ts

@@ -0,0 +1,208 @@
+/**
+ * fly (Machines API / "flaps") documentation generator.
+ *
+ * Calls the core docsPipeline with fly-specific config: service grouping and
+ * overview content. Produces a standalone Starlight docs site at
+ * lexicons/fly/docs/, like the aws and gcp lexicons.
+ */
+
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite, type DocsConfig } from "@intentius/chant/codegen/docs";
+
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+
+/**
+ * The curated top-level fly resources (#741), in the order they read best in a
+ * reference table. Property types (MachineConfig, MachineGuest, ...) are grouped
+ * separately by the pipeline and are not repeated here.
+ */
+const RESOURCES: Array<{ className: string; resourceType: string }> = [
+  { className: "App", resourceType: "Fly::Machines::App" },
+  { className: "Machine", resourceType: "Fly::Machines::Machine" },
+  { className: "Volume", resourceType: "Fly::Machines::Volume" },
+  { className: "IPAddress", resourceType: "Fly::Machines::IPAddress" },
+  { className: "Certificate", resourceType: "Fly::Machines::Certificate" },
+  { className: "Secret", resourceType: "Fly::Machines::Secret" },
+];
+
+/**
+ * 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: string): string {
+  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";
+  }
+}
+
+/**
+ * The reference doc URL for a fly resource type. The Machines API (flaps) is
+ * documented at docs.machines.dev, tagged by resource; resources flaps does not
+ * own (public IPs, certificates) link to the matching fly.io docs page.
+ */
+export function resourceTypeUrl(resourceType: string): string {
+  const kind = resourceType.split("::")[2] ?? resourceType;
+  switch (kind) {
+    case "App":
+      return "https://docs.machines.dev/#tag/apps";
+    case "Machine":
+      return "https://docs.machines.dev/#tag/machines";
+    case "Volume":
+      return "https://docs.machines.dev/#tag/volumes";
+    case "Secret":
+      return "https://docs.machines.dev/#tag/secrets";
+    case "IPAddress":
+      return "https://fly.io/docs/networking/services/";
+    case "Certificate":
+      return "https://fly.io/docs/networking/custom-domains-with-fly/";
+    default:
+      return "https://docs.machines.dev/";
+  }
+}
+
+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.
+
+## 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\`.`;
+
+const resourcesPage = `The fly lexicon ships ${RESOURCES.length} top-level resources. Each maps to a Machines API create body; follow the reference link for the underlying API shape.
+
+| Resource | Type | Service | Machines API |
+|----------|------|---------|--------------|
+${RESOURCES.map(
+  (r) =>
+    `| \`${r.className}\` | \`${r.resourceType}\` | ${serviceFromType(r.resourceType)} | [reference](${resourceTypeUrl(r.resourceType)}) |`,
+).join("\n")}
+
+Property types such as \`MachineConfig\`, \`MachineGuest\`, \`MachineService\`, \`MachinePort\`, and \`MachineMount\` are authored inline on a resource and are documented alongside the resources they belong to.`;
+
+/**
+ * Generate documentation for the fly Machines lexicon.
+ */
+export async function generateDocs(options?: { verbose?: boolean }): Promise<void> {
+  const config: DocsConfig = {
+    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,
+    extraPages: [
+      {
+        slug: "resources",
+        title: "Resource Reference",
+        description: "The fly resource types and their Machines API documentation links",
+        content: resourcesPage,
+      },
+      {
+        slug: "pseudo-params",
+        title: "Pseudo-parameters",
+        description: "Environment-resolved values: Fly.Region, Fly.OrgSlug, Fly.AppName",
+        content: `Pseudo-parameters stand in for values that vary by environment. Reference them instead of hard-coding, and the serializer resolves each from an environment variable at build time.
+
+| Pseudo-parameter | Environment variable | Fallback |
+|------------------|----------------------|----------|
+| \`Fly.Region\` | \`FLY_REGION\` | \`iad\` |
+| \`Fly.OrgSlug\` | \`FLY_ORG\`, then \`FLY_ORG_SLUG\` | \`personal\` |
+| \`Fly.AppName\` | \`FLY_APP_NAME\` | \`app\` |
+
+\`\`\`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({
+  region: Fly.Region,
+  config: new MachineConfig({
+    image: "flyio/hellofly:latest",
+    guest: new MachineGuest({ cpu_kind: "shared", cpus: 1, memory_mb: 256 }),
+  }),
+});
+\`\`\`
+
+With \`FLY_REGION=lhr\` set, \`region\` serializes to \`"lhr"\`; unset, it falls back to \`"iad"\`.`,
+      },
+    ],
+  };
+
+  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/src/codegen/generate-cli.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for fly lexicon generation.
+ */
+
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { generate, writeGeneratedFiles } from "./generate";
+
+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/src/codegen/generate-lexicon.ts

@@ -0,0 +1,52 @@
+/**
+ * Lexicon JSON generator — produces lexicon-fly.json with metadata for the
+ * fly resource and property types.
+ */
+
+import type { PropertyConstraints } from "@intentius/chant/codegen/json-schema";
+import type { FlyParseResult } from "../spec/parse";
+import { flyShortName } from "../spec/parse";
+import type { NamingStrategy } from "./naming";
+import { buildRegistry, serializeRegistry, type RegistryResource } from "@intentius/chant/codegen/generate-registry";
+
+export interface FlyLexiconEntry {
+  resourceType: string;
+  kind: "resource" | "property";
+  lexicon: "fly";
+  constraints?: Record<string, PropertyConstraints>;
+}
+
+/**
+ * Generate the lexicon-fly.json content.
+ */
+export function generateLexiconJSON(results: FlyParseResult[], naming: NamingStrategy): string {
+  const registryResources: RegistryResource[] = results.map((r) => ({
+    typeName: r.resource.typeName,
+    attributes: r.resource.attributes,
+    properties: r.resource.properties,
+    propertyTypes: [],
+  }));
+
+  const entries = buildRegistry<FlyLexiconEntry>(registryResources, naming, {
+    shortName: flyShortName,
+    buildEntry: (resource, _tsName, _attrs, propConstraints) => {
+      const r = results.find((res) => res.resource.typeName === resource.typeName);
+      const entry: FlyLexiconEntry = {
+        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/src/codegen/generate-typescript.ts

@@ -0,0 +1,69 @@
+/**
+ * TypeScript declaration file generator — produces index.d.ts with the fly
+ * resource classes (App, Machine, Volume) and their property-type classes.
+ */
+
+import type { FlyParseResult } from "../spec/parse";
+import type { NamingStrategy } from "./naming";
+import {
+  writeResourceClass,
+  writePropertyClass,
+  type DtsProperty,
+  type DtsAttribute,
+} from "@intentius/chant/codegen/generate-typescript";
+
+interface Entry {
+  tsName: string;
+  isProperty: boolean;
+  properties: DtsProperty[];
+  attributes: DtsAttribute[];
+}
+
+/**
+ * Generate the complete .d.ts file content.
+ */
+export function generateTypeScriptDeclarations(results: FlyParseResult[], naming: NamingStrategy): string {
+  const lines: string[] = [];
+  lines.push("// Code generated by chant fly generate. DO NOT EDIT.");
+
+  const entries: Entry[] = [];
+
+  for (const r of results) {
+    const tsName = naming.resolve(r.resource.typeName);
+    if (!tsName) continue;
+
+    const properties: DtsProperty[] = r.resource.properties.map((p) => ({
+      name: p.name,
+      type: p.tsType,
+      required: p.required,
+      description: p.description,
+    }));
+    const attributes: DtsAttribute[] = 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/src/codegen/generate.ts

@@ -0,0 +1,106 @@
+/**
+ * Fly generation pipeline — uses core generatePipeline with fly-specific
+ * fetch, parse, naming, and generation callbacks.
+ */
+
+import {
+  generatePipeline,
+  writeGeneratedArtifacts,
+  type GenerateOptions,
+  type GenerateResult,
+  type GeneratePipelineConfig,
+} from "@intentius/chant/codegen/generate";
+import { fetchSchemas } from "../spec/fetch";
+import { parseFlyOpenAPI, type FlyParseResult } from "../spec/parse";
+import { NamingStrategy } from "./naming";
+import { generateLexiconJSON } from "./generate-lexicon";
+import { generateTypeScriptDeclarations } from "./generate-typescript";
+import {
+  generateRuntimeIndex as coreGenerateRuntimeIndex,
+  type RuntimeIndexEntry,
+  type RuntimeIndexPropertyEntry,
+} from "@intentius/chant/codegen/generate-runtime-index";
+
+export type { GenerateResult };
+
+/**
+ * Run the full fly generation pipeline.
+ */
+export async function generate(opts: GenerateOptions = {}): Promise<GenerateResult> {
+  // 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: FlyParseResult[] = [];
+
+  const config: GeneratePipelineConfig<FlyParseResult> = {
+    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 as NamingStrategy),
+
+    generateTypes: (results, naming) => generateTypeScriptDeclarations(results, naming as NamingStrategy),
+
+    generateRuntimeIndex: (results, naming) => generateRuntimeIndex(results, naming as NamingStrategy),
+  };
+
+  return generatePipeline(config, opts);
+}
+
+/**
+ * Write generated artifacts to disk.
+ */
+export function writeGeneratedFiles(result: GenerateResult, baseDir: string): void {
+  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: FlyParseResult[], naming: NamingStrategy): string {
+  const resourceEntries: RuntimeIndexEntry[] = [];
+  const propertyEntries: RuntimeIndexPropertyEntry[] = [];
+
+  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: Record<string, string> = {};
+      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/src/codegen/naming.ts

@@ -0,0 +1,45 @@
+/**
+ * Fly naming strategy — maps Fly::Machines::{Kind} type names to
+ * user-friendly TypeScript class names.
+ */
+
+import {
+  NamingStrategy as CoreNamingStrategy,
+  type NamingConfig,
+  type NamingInput,
+} from "@intentius/chant/codegen/naming";
+import { flyShortName, flyServiceName, type FlyParseResult } from "../spec/parse";
+
+export { propertyTypeName, extractDefName } from "@intentius/chant/codegen/naming";
+
+const flyNamingConfig: NamingConfig = {
+  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: FlyParseResult[]) {
+    const inputs: NamingInput[] = results.map((r) => ({
+      typeName: r.resource.typeName,
+      propertyTypes: r.propertyTypes,
+    }));
+    super(inputs, flyNamingConfig);
+  }
+}

package/src/codegen/package.ts

@@ -0,0 +1,25 @@
+import { packagePipeline } from "@intentius/chant/codegen/package";
+import type { PackagePipelineConfig } from "@intentius/chant/codegen/package";
+import { generate } from "./generate";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+
+/**
+ * Package the fly lexicon for distribution.
+ */
+export async function packageLexicon(options?: { verbose?: boolean; force?: boolean }) {
+  const srcDir = dirname(fileURLToPath(import.meta.url));
+
+  const { spec, stats } = await packagePipeline({
+    generate: (opts) => generate({ verbose: opts?.verbose, force: opts?.force }),
+    buildManifest: (genResult) => ({
+      name: "fly",
+      version: "0.0.1",
+    }),
+    srcDir,
+    collectSkills: () => new Map(),
+  });
+
+  console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules`);
+  return { spec, stats };
+}