@intentius/chant-lexicon-fly 0.16.0

package/src/op/activities/index.ts

@@ -0,0 +1,48 @@
+/**
+ * fly Op activities — resolved by the core activity registry when a project's
+ * `chant.config.ts` lists the `fly` lexicon. Contributes the native flaps
+ * applier (`flyApply`), which speaks the Fly Machines REST API directly (no
+ * flyctl, no state file), and the mudflaps emulator lifecycle it is tested
+ * against.
+ */
+export {
+  flyApply,
+  flyDelete,
+  applyApp,
+  applyMachine,
+  destroyMachine,
+  deleteApp,
+  listMachines,
+  pruneMachines,
+  waitForMachine,
+  acquireLease,
+  releaseLease,
+  withLease,
+  resolveEndpoint,
+  parsePlan,
+  isAppRequest,
+  isMachineRequest,
+  machineAppSegment,
+  resolveApp,
+  appNameFromRequest,
+  isChantOwned,
+  configEqual,
+  isLeaseConflict,
+  defaultFlyHttp,
+  DEFAULT_FLAPS_BASE_URL,
+  LEASE_NONCE_HEADER,
+} from "./fly-apply";
+export type { FlyApplyArgs, FlyPlan, FlapsRequest, FlapsMachine, FlyHttp, WaitOpts, ApplyCtx } from "./fly-apply";
+
+// mudflaps (Fly Machines API emulator) lifecycle — boots/tears down the local
+// flaps target flyApply is exercised against.
+export {
+  flapsUp,
+  flapsDown,
+  flapsRunCommand,
+  flapsRmCommand,
+  flapsExistsCommand,
+  flapsHealthUrl,
+  flapsEndpoint,
+} from "./flaps";
+export type { FlapsUpArgs, FlapsDownArgs } from "./flaps";

package/src/ownership.ts

@@ -0,0 +1,32 @@
+/**
+ * The fly lexicon's ownership convention (#743, decision D2), declared here so
+ * core carries no fly-specific branch — the #686 seam: each lexicon owns its key
+ * names; core keeps only the generic stamp/detect logic
+ * (@intentius/chant/ownership), the same way aws declares `AWS_TAG_OWNERSHIP_KEYS`
+ * and azure `AZURE_TAG_OWNERSHIP_KEYS`.
+ *
+ * The convention is two-tier, because flaps resources differ in what they can
+ * carry:
+ *
+ *   1. Primary marker — machine `config.metadata`. Machines carry a flat
+ *      `Record<string, string>`, so chant stamps `managed-by: chant` (+ stack/env)
+ *      there. This is the k8s-label / AWS-tag analogue and the basis for
+ *      owned-only machine prune (a metadata filter — a foreign machine survives).
+ *      The serializer stamps it (see serializer.ts); the applier reads it via
+ *      `isChantOwned` → core `hasOwnershipMarker(..., FLY_METADATA_OWNERSHIP_KEYS)`.
+ *
+ *   2. Secondary boundary — the app. Volumes, secrets, certs, and IPs carry no
+ *      arbitrary metadata, so for them the Fly app is the ownership boundary
+ *      (like a CloudFormation stack): chant owns the app's declared-type
+ *      resources and prunes owned orphans within app scope. See the app-scoped
+ *      prune block in op/activities/fly-apply.ts for the limitation this leaves.
+ */
+
+import type { ChannelKeys } from "@intentius/chant/ownership";
+
+/** Machine `config.metadata` keys for chant's ownership markers (tier 1, D2). */
+export const FLY_METADATA_OWNERSHIP_KEYS: ChannelKeys = {
+  managedBy: "managed-by",
+  stack: "chant-stack",
+  env: "chant-env",
+};

package/src/package-cli.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env tsx
+/**
+ * Thin entry point for `npm run bundle` in lexicon-fly.
+ * Generates src/generated/ files and writes dist/ bundle.
+ *
+ * NOTE: Uses top-level await (matching AWS/Azure pattern) to avoid
+ * event loop references from async wrappers keeping the process alive.
+ */
+import { packageLexicon } from "./codegen/package";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(fileURLToPath(import.meta.url));
+const distDir = join(pkgDir, "..", "dist");
+
+const verbose = process.argv.includes("--verbose") || !process.argv.includes("--quiet");
+const force = process.argv.includes("--force");
+
+const { spec, stats } = await packageLexicon({ verbose, force });
+writeBundleSpec(spec, distDir);
+
+console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules`);
+console.error(`dist/ written to ${distDir}`);

package/src/plugin.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { flyPlugin } from "./plugin";
+import { isLexiconPlugin } from "@intentius/chant/lexicon";
+
+describe("fly plugin", () => {
+  it("is a valid LexiconPlugin", () => {
+    expect(isLexiconPlugin(flyPlugin)).toBe(true);
+  });
+
+  it("has the correct name", () => {
+    expect(flyPlugin.name).toBe("fly");
+  });
+
+  it("has a serializer", () => {
+    expect(flyPlugin.serializer).toBeDefined();
+  });
+});

package/src/plugin.ts

@@ -0,0 +1,285 @@
+import type { LexiconPlugin, SkillDefinition, IntrinsicDef, InitTemplateSet } from "@intentius/chant/lexicon";
+import type { LintRule } from "@intentius/chant/lint/rule";
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+import type { CompletionContext, CompletionItem, HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import type { McpToolContribution, McpResourceContribution } from "@intentius/chant/mcp/types";
+import { createSkillsLoader } from "@intentius/chant/lexicon-plugin-helpers";
+import type { TemplateParser } from "@intentius/chant/import/parser";
+import type { TypeScriptGenerator } from "@intentius/chant/import/generator";
+import { flySerializer } from "./serializer";
+import { rules } from "./lint/rules";
+import { postSynthChecks } from "./lint/post-synth";
+import { completions } from "./lsp/completions";
+import { hover } from "./lsp/hover";
+import { detectTemplate as detectFlyTemplate } from "./detect";
+import { FlyParser } from "./import/parser";
+import { FlyGenerator } from "./import/generator";
+
+/**
+ * fly lexicon plugin.
+ *
+ * Implements all required LexiconPlugin lifecycle methods.
+ */
+export const flyPlugin: LexiconPlugin = {
+  name: "fly",
+  serializer: flySerializer,
+
+  // ── Required lifecycle methods ────────────────────────────────
+
+  async generate(options?: { verbose?: boolean }): Promise<void> {
+    const { generate } = await import("./codegen/generate");
+    await generate(options);
+  },
+
+  async validate(options?: { verbose?: boolean }): Promise<void> {
+    const { validate } = await import("./validate");
+    const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+    const result = await validate();
+    printValidationResult(result);
+  },
+
+  async coverage(options?: { verbose?: boolean; minOverall?: number }): Promise<void> {
+    // TODO: Implement coverage analysis
+    console.error("Coverage analysis not yet implemented");
+  },
+
+  async package(options?: { verbose?: boolean; force?: boolean }): Promise<void> {
+    const { packageLexicon } = await import("./codegen/package");
+    const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+    const { join, dirname } = await import("path");
+    const { fileURLToPath } = await import("url");
+
+    const { spec, stats } = await packageLexicon(options);
+    const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    writeBundleSpec(spec, join(pkgDir, "dist"));
+
+    console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+  },
+
+  // ── Optional extensions ────────────────────────────────────
+
+  lintRules() {
+    return rules;
+  },
+
+  postSynthChecks() {
+    return postSynthChecks;
+  },
+
+  skills: createSkillsLoader(import.meta.url, [
+    {
+      file: "chant-fly.md",
+      name: "chant-fly",
+      description: "Author, lint, and deploy Fly apps and machines from a chant project, applied straight to the Machines API",
+      triggers: [
+        { type: "file-pattern" as const, value: "*.fly.ts" },
+        { type: "context" as const, value: "fly" },
+        { type: "context" as const, value: "fly.io" },
+      ],
+      parameters: [
+        {
+          name: "resourceType",
+          type: "string",
+          description: "Fly resource type to work with (App, Machine, Volume, IPAddress, Certificate, Secret)",
+        },
+      ],
+      examples: [
+        {
+          title: "Author an App and a Machine",
+          output: "new App({ name: \"my-app\" });\nnew Machine({ region: \"iad\", config: new MachineConfig({ image: \"flyio/hellofly:latest\" }) })",
+        },
+        {
+          title: "Deploy against mudflaps offline",
+          input: "Apply the App + Machine without a Fly account",
+          output: "cd examples/local-fly && chant run fly",
+        },
+      ],
+    },
+    {
+      file: "chant-fly-patterns.md",
+      name: "chant-fly-patterns",
+      description: "Volumes and mounts, IP assignments, certificates, apply-only secrets, and the app-boundary ownership model for Fly",
+      triggers: [
+        { type: "context" as const, value: "fly volumes" },
+        { type: "context" as const, value: "fly secrets" },
+        { type: "context" as const, value: "fly certificates" },
+      ],
+      parameters: [],
+      examples: [
+        {
+          title: "Machine with a mounted volume",
+          input: "Attach a volume to a machine",
+          output: "new Volume({ name: \"data\", region: \"iad\", size_gb: 10 });\nnew Machine({ config: new MachineConfig({ mounts: [{ volume: \"data\", path: \"/data\" }] }) })",
+        },
+      ],
+    },
+    {
+      file: "chant-fly-ops.md",
+      name: "chant-fly-ops",
+      description: "Operate a live Fly deploy — wait on stuck machines, resolve lease conflicts, prune safely, and target a real org versus the emulator",
+      triggers: [
+        { type: "context" as const, value: "fly apply" },
+        { type: "context" as const, value: "fly prune" },
+        { type: "context" as const, value: "flaps lease" },
+      ],
+      parameters: [],
+      examples: [
+        {
+          title: "Deploy to a real Fly org",
+          input: "Point the same code at a real org",
+          output: "export FLY_API_TOKEN=... && chant run fly",
+        },
+      ],
+    },
+  ]),
+
+  mcpTools() {
+    return []; // TODO: Implement MCP tools
+  },
+
+  mcpResources() {
+    return []; // TODO: Implement MCP resources
+  },
+
+  detectTemplate(data: unknown) {
+    return detectFlyTemplate(data);
+  },
+
+  templateParser(): TemplateParser {
+    return new FlyParser();
+  },
+
+  templateGenerator(): TypeScriptGenerator {
+    return new FlyGenerator();
+  },
+
+  pseudoParameters(): string[] {
+    return [
+      "Fly::Region",
+      "Fly::OrgSlug",
+      "Fly::AppName",
+    ];
+  },
+
+  initTemplates(template?: string): InitTemplateSet {
+    if (template === "volume") {
+      return {
+        src: {
+          "infra.ts": `import { App, Machine, MachineConfig, MachineGuest, MachineMount, Volume, Fly } from "@intentius/chant-lexicon-fly";
+
+// An app, a persistent volume, and a machine that mounts it. The serializer
+// (#738) turns these into the flaps create bodies flyApply POSTs. The region
+// comes from Fly.Region (resolved from FLY_REGION, defaulting to "iad").
+const app = new App({ name: "my-app", org_slug: Fly.OrgSlug });
+
+const data = new Volume({
+  name: "data",
+  region: Fly.Region,
+  size_gb: 10,
+});
+
+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 }),
+    mounts: [new MachineMount({ volume: "data", path: "/data" })],
+  }),
+});
+
+export { app, data, web };
+`,
+        },
+      };
+    }
+
+    if (template === "service") {
+      return {
+        src: {
+          "infra.ts": `import { App, Machine, MachineConfig, MachineGuest, MachineService, MachinePort, Fly } from "@intentius/chant-lexicon-fly";
+
+// An app and a machine exposing a public HTTPS service on port 443 to internal
+// 8080. The region comes from Fly.Region (resolved from FLY_REGION, defaulting
+// to "iad").
+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 }),
+    services: [
+      new MachineService({
+        protocol: "tcp",
+        internal_port: 8080,
+        ports: [new MachinePort({ port: 443, handlers: ["tls", "http"] })],
+      }),
+    ],
+  }),
+});
+
+export { app, web };
+`,
+        },
+      };
+    }
+
+    // Default: one app and one machine — the smallest complete deploy.
+    return {
+      src: {
+        "infra.ts": `import { App, Machine, MachineConfig, MachineGuest, Fly } from "@intentius/chant-lexicon-fly";
+
+// One Fly app and one machine — the smallest complete deploy. The serializer
+// (#738) turns these into the flaps create bodies flyApply POSTs. The region
+// comes from Fly.Region (resolved from FLY_REGION, defaulting to "iad").
+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 };
+`,
+      },
+    };
+  },
+
+  completionProvider(ctx: CompletionContext) {
+    return completions(ctx);
+  },
+
+  hoverProvider(ctx: HoverContext) {
+    return hover(ctx);
+  },
+
+  async docs(options?) {
+    const { generateDocs } = await import("./codegen/docs");
+    return generateDocs(options);
+  },
+
+  // State: the read-back seam for plan + drift (#767). Lists live Fly resources
+  // over flaps, keyed by chant entity name, with an ownership verdict core's
+  // change set reads. Endpoint + auth reuse the applier (FLY_FLAPS_BASE_URL /
+  // FLY_API_TOKEN), so it reads the same target flyApply writes.
+  async describeResources(options) {
+    const { describeResources } = await import("./describe-resources");
+    return describeResources(options);
+  },
+
+  // Live export (cloud → code): read live flaps state and regenerate App/Machine
+  // TypeScript. Strips server-written fields to the authored shape; honors the
+  // `owned` filter (machine marker; app-boundary inference for the marker-less
+  // app, logged per the seam contract). Reuses the applier's endpoint/auth and
+  // listMachines so it reads the same target flyApply writes.
+  async exportResources(options) {
+    const { exportResources } = await import("./export-resources");
+    return exportResources(options);
+  },
+};

package/src/pseudo.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { Fly, Region, OrgSlug, AppName, PseudoParameter } from "./pseudo";
+
+describe("fly pseudo-parameters", () => {
+  it("Region toJSON returns Ref object", () => {
+    expect(Region.toJSON()).toEqual({ Ref: "Fly::Region" });
+  });
+
+  it("OrgSlug toJSON returns Ref object", () => {
+    expect(OrgSlug.toJSON()).toEqual({ Ref: "Fly::OrgSlug" });
+  });
+
+  it("AppName toJSON returns Ref object", () => {
+    expect(AppName.toJSON()).toEqual({ Ref: "Fly::AppName" });
+  });
+
+  it("Region toString returns interpolation syntax", () => {
+    expect(Region.toString()).toBe("${Fly::Region}");
+  });
+
+  it("all pseudo-parameters are instances of PseudoParameter", () => {
+    expect(Region).toBeInstanceOf(PseudoParameter);
+    expect(OrgSlug).toBeInstanceOf(PseudoParameter);
+    expect(AppName).toBeInstanceOf(PseudoParameter);
+  });
+
+  it("Fly namespace contains all pseudo-parameters", () => {
+    expect(Fly.Region).toBe(Region);
+    expect(Fly.OrgSlug).toBe(OrgSlug);
+    expect(Fly.AppName).toBe(AppName);
+  });
+});

package/src/pseudo.ts

@@ -0,0 +1,29 @@
+import { PseudoParameter, createPseudoParameters } from "@intentius/chant/pseudo-parameter";
+
+export { PseudoParameter };
+
+/**
+ * Fly pseudo-parameters — environment-resolved values a project references
+ * without hard-coding. Each serializes to a `{ Ref: "Fly::..." }` marker that
+ * the serializer resolves from an environment variable at build time (see
+ * PSEUDO_ENV_MAP in ./serializer.ts), mirroring gcp's `GCP.Region` /
+ * `GCP.ProjectId`.
+ *
+ *   - Region  → the target Fly region (FLY_REGION), e.g. `iad`.
+ *   - OrgSlug → the owning org slug (FLY_ORG / FLY_ORG_SLUG).
+ *   - AppName → the target app name (FLY_APP_NAME).
+ */
+export const { Region, OrgSlug, AppName } = createPseudoParameters({
+  Region: "Fly::Region",
+  OrgSlug: "Fly::OrgSlug",
+  AppName: "Fly::AppName",
+});
+
+/**
+ * Fly namespace containing all pseudo-parameters.
+ */
+export const Fly = {
+  Region,
+  OrgSlug,
+  AppName,
+} as const;