@intentius/chant-lexicon-fly 0.89.0 → 0.91.0

package/src/op/builders.ts

@@ -28,11 +28,27 @@
 
 import { activity, type NamedActivityStep, type WithStepRefs } from "@intentius/chant/op";
 import type { ActivityStep } from "@intentius/chant/op";
-import type { SpriteCreateArgs, SpriteExecArgs, SpriteCheckpointArgs, SpriteRestoreArgs, ListCheckpointsArgs, SpriteDestroyArgs } from "./activities/sprites";
+import type { SpriteCreateArgs, SpriteExecArgs, SpriteCheckpointArgs, SpriteRestoreArgs, ListCheckpointsArgs, SpriteDestroyArgs, SpriteDeleteArgs, SpriteUrlArgs } from "./activities/sprites";
 import type { SpriteWriteFileArgs, SpriteReadFileArgs, SpriteListDirArgs, SpriteRemoveArgs } from "./activities/sprite-fs";
 import type { SpriteApplyNetworkPolicyArgs, SpriteApplyServicesArgs } from "./activities/sprite-config";
+import type {
+  SpriteServiceCreateArgs,
+  SpriteServiceGetArgs,
+  SpriteServiceListArgs,
+  SpriteServiceStartArgs,
+  SpriteServiceStopArgs,
+  SpriteServiceDeleteArgs,
+  SpriteServiceLogsArgs,
+} from "./activities/sprite-services";
 import type { SpriteTaskCreateArgs, SpriteTaskRefreshArgs, SpriteTaskReleaseArgs } from "./activities/sprite-tasks";
 import type { SpritesUpArgs, SpritesDownArgs } from "./activities/sprites-emulator";
+import type {
+  FlyMachineReleaseArgs,
+  FlyMachineExecArgs,
+  FlyMachineStateArgs,
+  FlyMachineVerifyArgs,
+  FlyMachineRestoreArgs,
+} from "./activities/machine-release";
 
 type StepOpts = { profile?: ActivityStep["profile"] };
 
@@ -75,6 +91,10 @@ export const spriteRestore = spriteStep<SpriteRestoreArgs>("spriteRestore", "lon
 export const listCheckpoints = spriteStep<ListCheckpointsArgs>("listCheckpoints", "fastIdempotent");
 /** Destroy a sprite — the fully typed twin of core's `spriteDestroy`. Defaults to the `fastIdempotent` profile. */
 export const spriteDestroy = spriteStep<SpriteDestroyArgs>("spriteDestroy", "fastIdempotent");
+/** Delete a sprite (#2711; alias of `spriteDestroy`). Defaults to the `fastIdempotent` profile. */
+export const spriteDelete = spriteStep<SpriteDeleteArgs>("spriteDelete", "fastIdempotent");
+/** Resolve a sprite's URL, optionally waiting until a path on it answers (#2711). Defaults to the `fastIdempotent` profile. */
+export const spriteUrl = spriteStep<SpriteUrlArgs>("spriteUrl", "fastIdempotent");
 /** Write a file into a sprite — the fully typed twin of core's `spriteWriteFile`. Defaults to the `fastIdempotent` profile. */
 export const spriteWriteFile = spriteStep<SpriteWriteFileArgs>("spriteWriteFile", "fastIdempotent");
 /** Read a file from a sprite — the fully typed twin of core's `spriteReadFile`. Defaults to the `fastIdempotent` profile. */
@@ -87,6 +107,20 @@ export const spriteRemove = spriteStep<SpriteRemoveArgs>("spriteRemove", "fastId
 export const spriteApplyNetworkPolicy = spriteStep<SpriteApplyNetworkPolicyArgs>("spriteApplyNetworkPolicy", "fastIdempotent");
 /** Reconcile a sprite's background services — the fully typed twin of core's `spriteApplyServices`. Defaults to the `fastIdempotent` profile. */
 export const spriteApplyServices = spriteStep<SpriteApplyServicesArgs>("spriteApplyServices", "fastIdempotent");
+/** Create-and-start one background service (#2711) — the single-service primitive underneath `spriteApplyServices`. Defaults to the `longInfra` profile (the create+start NDJSON round trip). */
+export const spriteServiceCreate = spriteStep<SpriteServiceCreateArgs>("spriteServiceCreate", "longInfra");
+/** Get one background service's definition and live state (#2711). Defaults to the `fastIdempotent` profile. */
+export const spriteServiceGet = spriteStep<SpriteServiceGetArgs>("spriteServiceGet", "fastIdempotent");
+/** List a sprite's background services (#2711). Defaults to the `fastIdempotent` profile. */
+export const spriteServiceList = spriteStep<SpriteServiceListArgs>("spriteServiceList", "fastIdempotent");
+/** Start a stopped background service (#2711). Defaults to the `longInfra` profile (the NDJSON round trip). */
+export const spriteServiceStart = spriteStep<SpriteServiceStartArgs>("spriteServiceStart", "longInfra");
+/** Stop a running background service (#2711). Defaults to the `fastIdempotent` profile. */
+export const spriteServiceStop = spriteStep<SpriteServiceStopArgs>("spriteServiceStop", "fastIdempotent");
+/** Delete a background service, idempotent (#2711). Defaults to the `fastIdempotent` profile. */
+export const spriteServiceDelete = spriteStep<SpriteServiceDeleteArgs>("spriteServiceDelete", "fastIdempotent");
+/** Read a background service's log tail (#2711). Defaults to the `fastIdempotent` profile. */
+export const spriteServiceLogs = spriteStep<SpriteServiceLogsArgs>("spriteServiceLogs", "fastIdempotent");
 /** Create a keep-alive task — the fully typed twin of core's `spriteTaskCreate`. Defaults to the `fastIdempotent` profile. */
 export const spriteTaskCreate = spriteStep<SpriteTaskCreateArgs>("spriteTaskCreate", "fastIdempotent");
 /** Refresh a keep-alive task's expiry — the fully typed twin of core's `spriteTaskRefresh`. Defaults to the `fastIdempotent` profile. */
@@ -100,3 +134,21 @@ export const spritesUp = (args: WithStepRefs<SpritesUpArgs> & StepOpts = {}): Na
 /** Stop and remove the local spritzer container — the fully typed twin of core's `spritesDown`. Defaults to the `fastIdempotent` profile. */
 export const spritesDown = (args: WithStepRefs<SpritesDownArgs> & StepOpts = {}): NamedActivityStep =>
   spriteStep<SpritesDownArgs>("spritesDown", "fastIdempotent")(args);
+
+// ── Machines release activities (#2736, ws-056) ──────────────────────────────
+// The site steps as Op steps: upload and start, a migration inside the
+// Machine, restart, stop, verify and restore. Wrap a migration's
+// `flyMachineExec` in `effect()` so it fires once per environment.
+
+/** Apply the plan with the Machine serving a release (its digest in the Machine's metadata). Defaults to the `longInfra` profile. */
+export const flyMachineRelease = spriteStep<FlyMachineReleaseArgs>("flyMachineRelease", "longInfra");
+/** Run a command inside a Machine (a migration). Defaults to the `atMostOnce` profile: chant cannot know the command is safe to repeat. */
+export const flyMachineExec = spriteStep<FlyMachineExecArgs>("flyMachineExec", "atMostOnce");
+/** Restart a Machine under a lease and wait for it to be started. Defaults to the `longInfra` profile. */
+export const flyMachineRestart = spriteStep<FlyMachineStateArgs>("flyMachineRestart", "longInfra");
+/** Stop a Machine under a lease. Defaults to the `longInfra` profile. */
+export const flyMachineStop = spriteStep<FlyMachineStateArgs>("flyMachineStop", "longInfra");
+/** Check a Machine is started with a release, and its health endpoint answers. Defaults to the `longInfra` profile. */
+export const flyMachineVerify = spriteStep<FlyMachineVerifyArgs>("flyMachineVerify", "longInfra");
+/** Put a recorded Machine config back (restore, rollback). Defaults to the `longInfra` profile. */
+export const flyMachineRestore = spriteStep<FlyMachineRestoreArgs>("flyMachineRestore", "longInfra");

package/src/release-metadata.ts

@@ -0,0 +1,72 @@
+/**
+ * The release a Fly Machine serves, as its metadata records it (#2736, ws-056).
+ *
+ * Pure: the keys, a reader, and a writer over a Machine config. The Machines
+ * activities (./op/activities/machine-release.ts) stamp these on a release,
+ * `describeResources` (./describe-resources.ts) reads them back, and
+ * `chant components status --live` compares the digest with the release
+ * ledger.
+ */
+
+/**
+ * The Machine metadata keys that say which release it serves. Fly metadata is
+ * a string map, so each field is its own key.
+ *
+ * - `digest`: the release's digest, the release ledger's join key.
+ * - `gitSha`: the commit the release was built from.
+ * - `release`: an optional human label (a tag, a release id).
+ * - `previousDigest`: the release this one replaced when it first shipped, so
+ *   a rollback knows where to go back to with no history of its own.
+ */
+export const RELEASE_METADATA_KEYS = {
+  digest: "chant-release-digest",
+  gitSha: "chant-release-git-sha",
+  release: "chant-release",
+  previousDigest: "chant-release-previous-digest",
+} as const;
+
+/** A release, as a Machine's metadata records it. */
+export interface MachineRelease {
+  /** The release's digest (`sha256:...`): what the release ledger records. */
+  digest: string;
+  /** The commit it was built from. */
+  gitSha?: string;
+  /** A human label for it. */
+  release?: string;
+  /** The digest of the release it replaced, when there was one. */
+  previousDigest?: string;
+}
+
+export type MachineConfig = Record<string, unknown> & { metadata?: Record<string, string>; env?: Record<string, string> };
+
+/** The release a Machine's metadata names, or undefined when it names none. Pure. */
+export function readMachineRelease(metadata: Record<string, string> | null | undefined): MachineRelease | undefined {
+  const digest = metadata?.[RELEASE_METADATA_KEYS.digest];
+  if (!digest) return undefined;
+  const gitSha = metadata?.[RELEASE_METADATA_KEYS.gitSha];
+  const release = metadata?.[RELEASE_METADATA_KEYS.release];
+  const previousDigest = metadata?.[RELEASE_METADATA_KEYS.previousDigest];
+  return {
+    digest,
+    ...(gitSha ? { gitSha } : {}),
+    ...(release ? { release } : {}),
+    ...(previousDigest ? { previousDigest } : {}),
+  };
+}
+
+/**
+ * A Machine config serving `release`: a copy of `config` with the release's
+ * metadata keys set (and any it does not carry removed). Pure.
+ */
+export function withReleaseMetadata(config: MachineConfig | undefined, release: MachineRelease): MachineConfig {
+  const out = structuredClone(config ?? {}) as MachineConfig;
+  const metadata = { ...(out.metadata ?? {}) };
+  for (const key of Object.values(RELEASE_METADATA_KEYS)) delete metadata[key];
+  metadata[RELEASE_METADATA_KEYS.digest] = release.digest;
+  if (release.gitSha) metadata[RELEASE_METADATA_KEYS.gitSha] = release.gitSha;
+  if (release.release) metadata[RELEASE_METADATA_KEYS.release] = release.release;
+  if (release.previousDigest) metadata[RELEASE_METADATA_KEYS.previousDigest] = release.previousDigest;
+  out.metadata = metadata;
+  return out;
+}
+

package/src/release-store.ts

@@ -0,0 +1,70 @@
+/**
+ * Where a Fly release's Machine config is kept, so a rollback can put it back
+ * (#2736, ws-056).
+ *
+ * The Machine's metadata says which release it serves and which one it
+ * replaced; the config that earlier release applied is kept on the
+ * `chant/lifecycle` branch beside the release ledger, one file per release at
+ * `<env>/fly/<app>/<machine>/<digest>.json`. It is written through core's
+ * ledger plumbing, so a workspace member's copy lands under its own prefix,
+ * and every checkout that fetches the branch can roll back.
+ *
+ * Not exported from the package entry point: it spawns git, which stays off
+ * the build path. The `fly-release` and `fly-rollback` capabilities import it.
+ */
+
+import { readBlobFromPath, writeBlobToPath } from "@intentius/chant/lifecycle/git";
+
+/** Which Machine and release a config belongs to. */
+export interface MachineConfigRef {
+  app: string;
+  machine: string;
+  digest: string;
+}
+
+/** A store of the Machine config each release applied. */
+export interface MachineConfigStore {
+  read(ref: MachineConfigRef): Promise<Record<string, unknown> | undefined>;
+  write(ref: MachineConfigRef, config: Record<string, unknown>): Promise<void>;
+}
+
+const safe = (s: string) => s.replace(/[^a-zA-Z0-9_.-]/g, "_");
+
+/** The file a release's Machine config is kept in, under the environment's ledger directory. */
+export function machineConfigFile(ref: MachineConfigRef): string {
+  return `fly/${safe(ref.app)}/${safe(ref.machine)}/${safe(ref.digest.replace(/^sha256:/, ""))}.json`;
+}
+
+/** The lifecycle-branch store for `environment`. */
+export function lifecycleMachineConfigStore(environment: string, opts?: { cwd?: string }): MachineConfigStore {
+  return {
+    async read(ref) {
+      const content = await readBlobFromPath(environment, machineConfigFile(ref), opts);
+      return content === null ? undefined : (JSON.parse(content) as Record<string, unknown>);
+    },
+    async write(ref, config) {
+      await writeBlobToPath(
+        environment,
+        machineConfigFile(ref),
+        `${JSON.stringify(config, null, 2)}\n`,
+        `Fly release config ${ref.app}/${ref.machine} ${ref.digest}`,
+        opts,
+      );
+    },
+  };
+}
+
+/** An in-memory store, for tests and for a caller with nowhere to keep configs. */
+export function memoryMachineConfigStore(): MachineConfigStore & { entries: Map<string, Record<string, unknown>> } {
+  const entries = new Map<string, Record<string, unknown>>();
+  return {
+    entries,
+    async read(ref) {
+      const found = entries.get(machineConfigFile(ref));
+      return found ? structuredClone(found) : undefined;
+    },
+    async write(ref, config) {
+      entries.set(machineConfigFile(ref), structuredClone(config));
+    },
+  };
+}

package/src/skills/chant-fly-ops.md

@@ -53,3 +53,36 @@ Each prune logs the resource and endpoint it removed, so a prune run is auditabl
 ## Re-applying is safe
 
 A re-apply of an unchanged stack is a no-op per resource: machines whose config is structurally equal to live are skipped, volumes and certificates that already exist are skipped, and an IP of an already-present family is skipped. Only apply-only secrets are always re-set, because flaps exposes no value to diff against.
+
+## Releases on a Machine
+
+A component can deploy to Fly with this lexicon alone. It declares an `App` and the `Machine` that serves, builds them with `chant build --lexicon fly -o dist/fly.json`, and deploys with the `fly-release` step. Here a `Publish` phase (`publish-image`, elided) pushes the image, and the release serves it by digest:
+
+```ts
+import { phase, type Component } from "@intentius/chant/components";
+
+export const web: Component = {
+  name: "web",
+  deploy: [
+    phase("Publish", [/* publish-image */]),
+    phase("Release", [
+      {
+        kind: "fly-release",
+        plan: "dist/fly.json",
+        digest: "@Publish.digest",
+        image: "@Publish.uri",
+        migrations: [{ name: "001_init.sql", command: "node migrate.js 001_init.sql" }],
+        verify: { url: "https://web.example.com", healthPath: "/health" },
+      },
+    ]),
+  ],
+};
+```
+
+The step updates the Machine in place with the release in its `config.metadata`: `chant-release-digest`, `chant-release-git-sha` (the commit, `git rev-parse HEAD` unless given), and `chant-release-previous-digest` (the release it replaced). Each migration then runs inside the Machine through the Machines API's exec, once per environment: its receipt is kept on `chant/lifecycle` at `<env>/receipts/`, and a migration fires again only when its `sha` (or command) changes. After a migration fires, the Machine restarts, and the step checks that it is started with this release and, given a `url`, that its health endpoint answers with this commit or digest. If anything fails after the Machine changed, the step puts back the config the Machine served before (on a first release, it stops the Machine) and fails.
+
+The step's output carries `uri` and `digest`, so `chant run --components web --env prod` records the release in the ledger. `chant components status prod --live` reads the Machine's metadata back and compares its digest with the ledger's: the row is `reconciled` when they agree and `drifted` when the Machine serves something the ledger does not name. The component joins the Machine by name: name the component after the Machine entity, or list it in `liveNames`.
+
+Each release's Machine config is kept on `chant/lifecycle` at `<env>/fly/<app>/<machine>/<digest>.json`. `fly-rollback` puts back the config of the release the serving one replaced (or the digest given as `to`), checks it, and outputs that digest so the ledger records it again. `fly-release`'s own saga compensation does the same.
+
+The steps are also Op activities, for an Op that composes them itself: `flyMachineRelease`, `flyMachineExec`, `flyMachineRestart`, `flyMachineStop`, `flyMachineVerify` and `flyMachineRestore`. Wrap a migration's `flyMachineExec` in `effect()` so it fires once.

package/src/skills/chant-fly-sprites.md

@@ -78,7 +78,7 @@ When the `Run` phase's command exits non-zero, `spriteExec` throws, the phase fa
 
 ## Targeting the emulator or real Sprites
 
-The activities resolve their endpoint in this order: an explicit `endpoint` arg, then `SPRITES_BASE_URL`, then the real Sprites base. The same Op targets an emulator or real Sprites with no code change. The default `fetch` client adds `Authorization: Bearer ${SPRITES_API_TOKEN}` when a token is set; the emulator ignores it.
+The activities resolve their endpoint in this order: an explicit `endpoint` arg, then `SPRITES_BASE_URL`, then its alias `SPRITES_API_URL` (the name the studio and wisp's own docs use), then the real Sprites base. The same Op targets an emulator or real Sprites with no code change. The default `fetch` client adds `Authorization: Bearer <token>` when a token is set — `SPRITES_API_TOKEN`, or its alias `SPRITE_TOKEN` — the emulator ignores it. Either alias is read only when the original name is unset, so an existing deployment using `SPRITES_BASE_URL`/`SPRITES_API_TOKEN` is unaffected.
 
 ```bash
 # Point at a self-hosted or in-process emulator.
@@ -105,9 +105,11 @@ The same lexicon ships more Sprite primitives, all imported from `@intentius/cha
 |--------|-----------|-----|
 | Filesystem (#848) | `spriteWriteFile` / `spriteReadFile` / `spriteListDir` / `spriteRemove` | stage an input file and read a result out without shelling `spriteExec` + `cat` |
 | Config reconcile (#849) | `spriteApplyNetworkPolicy` / `spriteApplyServices` | reconcile a Sprite's egress allowlist and background services against typed config (validated before any HTTP; a whole-object replace for policy, create-or-update by name for services) |
+| Services (#2711) | `spriteServiceCreate` / `spriteServiceGet` / `spriteServiceList` / `spriteServiceStart` / `spriteServiceStop` / `spriteServiceDelete` / `spriteServiceLogs` | the single-service primitives underneath `spriteApplyServices` — create-and-start one long-lived service (a box's door, hud or chud), inspect or list what's running, stop/start or delete one by name, read its log tail |
+| Sprite URL / delete (#2711) | `spriteUrl` / `spriteDelete` | resolve a Sprite's URL, optionally waiting until a path on it answers; delete the Sprite (`spriteDelete` is `spriteDestroy` under the name spritzer/wisp and the other lexicons' delete activities use — same call, either name) |
 | Keep-alive (#847) | `spriteTaskCreate` / `spriteTaskRefresh` / `spriteTaskRelease` | hold a Sprite active for a session so it will not pause; a session past the 1-hour task cap refreshes on an interval |
 
-These are still runtime-orchestration primitives, not declarable resources — a Sprite has no desired-state create body to reconcile.
+These are still runtime-orchestration primitives, not declarable resources — a Sprite has no desired-state create body to reconcile. Services created directly with `spriteServiceCreate` are what a box's `spritzer` preset provisions door/hud/chud on (arugula-salad/studio#27) — the same wire surface as `sprite-env services` inside the sprite, spritzer 0.6.0's container mode, and wisp.
 
 ## Where it fits