@molecule/api-deploy-rollout-fly 0.0.0-stage → 0.0.1-stage

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,316 @@
-# Temporary Holding Version
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-10-19T18:05:45.688Z
+-->
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @molecule/api-deploy-rollout-fly
+
+Fly Machines provider bonds for the deploy-rollout core.
+
+In-place (restart the same Machines one at a time, with a restore path) and
+grow-then-shrink (clone a Machine beside the old set, retire the old one when the
+new one serves). Commands run through an injected runner, so tests need no Fly
+account.
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+## Quick Start
+
+```typescript
+import { runInPlaceRollout, setProvider } from '@molecule/api-deploy-rollout'
+import { provider } from '@molecule/api-deploy-rollout-default'
+import { createFlyInPlaceProvider } from '@molecule/api-deploy-rollout-fly'
+
+setProvider(provider)
+await runInPlaceRollout({
+  provider: createFlyInPlaceProvider({
+    app: 'molecule-api',
+    isServing: (id) => probeMachine(id),
+    restore: (id) => clearPatchAndRestart(id),
+  }),
+  policy: { soakMs: 30_000 },
+})
+```
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/api-deploy-rollout-fly @molecule/api-deploy-rollout
+```
+
+## API
+
+### Interfaces
+
+#### `FlyMachine`
+
+One Fly Machine, as the rollout needs to see it.
+
+```typescript
+interface FlyMachine extends RolloutInstance {
+  /** The Machine's Fly state (`started`, `stopped`, …). */
+  state: string
+  /** The image the Machine runs, tag or digest form. */
+  imageRef: string | null
+  /** The Machine's configuration version (`instance_id`/`version`). */
+  version: string | null
+  /**
+   * The longest service-check grace period the Machine declares, in milliseconds.
+   *
+   * Fly reports a check inside its grace window as PASSING and can route traffic
+   * to a Machine that has not booted; a rolling restart must know the number to
+   * refuse it. Zero when the Machine's checks have no grace.
+   */
+  gracePeriodMs: number
+}
+```
+
+#### `FlyCommandResult`
+
+The result of one flyctl invocation.
+
+```typescript
+interface FlyCommandResult {
+  /** Exit status, or `null` when the process did not exit normally. */
+  status: number | null
+  /** Standard output. */
+  stdout: string
+  /** Standard error. */
+  stderr?: string
+}
+```
+
+#### `FlyMachinesOptions`
+
+Where and how the adapter reaches one Fly app.
+
+```typescript
+interface FlyMachinesOptions {
+  /** The Fly app name. */
+  app: string
+  /** The runner; defaults to spawning the local `flyctl`. */
+  run?: FlyCommandRunner
+}
+```
+
+#### `FlyInPlaceOptions`
+
+What an in-place Fly rollout supplies that Fly itself does not know.
+
+The adapter knows how to list, restart and start a Machine. Whether a Machine is
+SERVING, what "replace" means (a patch volume swap, a new image) and how to undo it
+are properties of the app being deployed, so the caller states them.
+
+```typescript
+interface FlyInPlaceOptions extends FlyMachinesOptions {
+  /** Whether a Machine answers its readiness probe right now. */
+  isServing: (machineId: string) => Promise<boolean>
+  /**
+   * Change one Machine to the new build and leave it serving. Defaults to a restart
+   * that waits for the Machine to reach `started`.
+   */
+  replace?: (machineId: string) => Promise<void>
+  /** Put one Machine back on the old build. */
+  restore?: (machineId: string) => Promise<void>
+  /** How long a restart may take to reach `started`. Defaults to 6 minutes. */
+  restartBudgetMs?: number
+  /** Sleep between state polls. Defaults to 5000 ms. */
+  pollMs?: number
+}
+```
+
+#### `FlyInstanceOptions`
+
+What a grow-then-shrink Fly rollout supplies that Fly itself does not know.
+
+`launch` builds the Machine (image, volume, env, mounts) — that is the app's
+deployment recipe. `join`/`leave` change whatever edge routes to the app; Fly's own
+proxy balances by service, not by a caller-held set.
+
+```typescript
+interface FlyInstanceOptions extends FlyMachinesOptions {
+  /** Create the Machine for `index` and resolve once it exists. */
+  launch: (index: number) => Promise<FlyMachine>
+  /** Whether a Machine answers its readiness probe right now. */
+  isServing: (machine: FlyMachine) => Promise<boolean>
+  /** Add a ready Machine to the caller's routable set. */
+  join?: (machine: FlyMachine) => Promise<void>
+  /** Remove a Machine from the caller's routable set. */
+  leave?: (machine: FlyMachine) => Promise<void>
+  /** How long `machine stop` may take. Defaults to 60 s. */
+  stopBudgetMs?: number
+}
+```
+
+### Types
+
+#### `FlyCommandRunner`
+
+Runs one flyctl command (without the leading `flyctl`).
+
+```typescript
+type FlyCommandRunner = (args: string[]) => Promise<FlyCommandResult>
+```
+
+### Functions
+
+#### `flyctlRunner(options)`
+
+A runner that spawns the local `flyctl`.
+
+```typescript
+function flyctlRunner(options?: { cwd?: string }): FlyCommandRunner
+```
+
+- `options` — The working directory flyctl should see.
+
+**Returns:** The runner.
+
+#### `parseFlyDurationMs(value)`
+
+Parse a Fly duration (`500ms`, `5s`, `1m0s`, `1h30m`) into milliseconds.
+
+```typescript
+function parseFlyDurationMs(value: unknown): number
+```
+
+- `value` — The configured value.
+
+**Returns:** Milliseconds; 0 when absent or not a duration.
+
+#### `serviceCheckGraceMs(machine)`
+
+The longest service-check grace period any of a Machine's checks declares.
+
+```typescript
+function serviceCheckGraceMs(machine: unknown): number
+```
+
+- `machine` — One entry from `flyctl machine list --json`.
+
+**Returns:** Milliseconds; 0 when the Machine's checks have no grace.
+
+#### `parseFlyMachineList(json)`
+
+Parse `flyctl machine list --app <app> --json` into the facts a rollout needs.
+
+```typescript
+function parseFlyMachineList(json: string): FlyMachine[]
+```
+
+- `json` — The command's stdout.
+
+**Returns:** Every Machine, in the order Fly listed them.
+
+#### `assertHomogeneousFlyMachines(machines)`
+
+Validate a Machine list as a rollout target set and return what to act on.
+
+Every Machine must be started (a stopped one cannot be reached over SSH, and its
+patch volume would keep an older build), and all must run the SAME image and
+configuration version: a mixed set is a deploy in flight, and changing half of it
+would record a binding that is already stale on the other half.
+
+```typescript
+function assertHomogeneousFlyMachines(machines: readonly FlyMachine[]): {
+  ids: string[]
+  imageRef: string
+  version: string
+}
+```
+
+- `machines` — Parsed Machines.
+
+**Returns:** The target set's ids, image ref and configuration version.
+
+#### `listFlyMachines(options)`
+
+List one Fly app's Machines.
+
+```typescript
+function listFlyMachines(options: FlyMachinesOptions): Promise<FlyMachine[]>
+```
+
+- `options` — The app and the runner.
+
+**Returns:** Every Machine the app has.
+
+#### `restartFlyMachine(options, machineId)`
+
+Restart one Machine and wait until it is `started` again.
+
+A Machine that comes back `stopped` or `suspended` is started explicitly — Fly
+occasionally parks one after a restart, and a role that leaves it parked turns a
+successful roll into an outage.
+
+```typescript
+function restartFlyMachine(
+  options: FlyMachinesOptions & { restartBudgetMs?: number; pollMs?: number },
+  machineId: string,
+): Promise<boolean>
+```
+
+- `options` — The app, the runner and the waits.
+- `machineId` — The Machine to restart.
+
+**Returns:** Whether it reached `started` inside the budget.
+
+#### `createFlyInPlaceProvider(options)`
+
+Create an in-place Fly Machines provider for the rollout core.
+
+```typescript
+function createFlyInPlaceProvider(options: FlyInPlaceOptions): InPlaceInstanceProvider<FlyMachine>
+```
+
+- `options` — The app, the runner, the readiness probe and the restore path.
+
+**Returns:** An `InPlaceInstanceProvider` over Fly Machines.
+
+#### `createFlyInstanceProvider(options)`
+
+Create a grow-then-shrink Fly Machines provider for the rollout core.
+
+`create` delegates to the caller's `launch`; `drain` asks Fly to stop the Machine
+(a SIGTERM with a bounded wait), and `destroy` removes it.
+
+```typescript
+function createFlyInstanceProvider(options: FlyInstanceOptions): InstanceProvider<FlyMachine>
+```
+
+- `options` — The app, the runner and the app-specific operations.
+
+**Returns:** An `InstanceProvider` over Fly Machines.
+
+## Core Interface
+
+Implements `@molecule/api-deploy-rollout` interface.
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-deploy-rollout` ^1.0.0
+
+### Runtime Dependencies
+
+- `@molecule/api-deploy-rollout`
+
+- **`parseFlyMachineList` is the only JSON the adapter trusts.** A Machine list
+  that is not an array is an error, never an empty set.
+- **A mixed set is refused.** `assertHomogeneousFlyMachines` rejects Machines on
+  different images or configuration versions: that is a deploy in flight, and
+  changing half of it records a binding that is already stale on the other half.
+- **A restart that parks is started explicitly.** A Machine that comes back
+  `stopped`/`suspended` after a restart is started, not left parked.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-deploy-rollout-fly` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-deploy-rollout-fly is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/fly.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Fly Machines adapter for the deploy-rollout core.
+ *
+ * Two shapes, because Fly supports both deployment topologies:
+ *
+ * - {@link createFlyInPlaceProvider} — the same Machines restarted onto a new build
+ *   one at a time, with a restore path. This is what the platform's own deploy tools
+ *   do today (a patch volume, an image deploy).
+ * - {@link createFlyInstanceProvider} — a new Machine cloned beside the old set and
+ *   retired when it is serving. Used when the deployment changes its instance count.
+ *
+ * The commands are executed through an injected {@link FlyCommandRunner}, so tests
+ * need no Fly account and a caller can decide how flyctl is reached (a checkout
+ * directory, a remote builder, a wrapper). What the adapter owns is the Fly-specific
+ * part: the command arguments and the `machine list --json` parse.
+ *
+ * @module
+ */
+import type { InPlaceInstanceProvider, InstanceProvider, RolloutInstance } from '@molecule/api-deploy-rollout';
+/** One Fly Machine, as the rollout needs to see it. */
+export interface FlyMachine extends RolloutInstance {
+    /** The Machine's Fly state (`started`, `stopped`, …). */
+    state: string;
+    /** The image the Machine runs, tag or digest form. */
+    imageRef: string | null;
+    /** The Machine's configuration version (`instance_id`/`version`). */
+    version: string | null;
+    /**
+     * The longest service-check grace period the Machine declares, in milliseconds.
+     *
+     * Fly reports a check inside its grace window as PASSING and can route traffic
+     * to a Machine that has not booted; a rolling restart must know the number to
+     * refuse it. Zero when the Machine's checks have no grace.
+     */
+    gracePeriodMs: number;
+}
+/** The result of one flyctl invocation. */
+export interface FlyCommandResult {
+    /** Exit status, or `null` when the process did not exit normally. */
+    status: number | null;
+    /** Standard output. */
+    stdout: string;
+    /** Standard error. */
+    stderr?: string;
+}
+/** Runs one flyctl command (without the leading `flyctl`). */
+export type FlyCommandRunner = (args: string[]) => Promise<FlyCommandResult>;
+/**
+ * A runner that spawns the local `flyctl`.
+ *
+ * @param options - The working directory flyctl should see.
+ * @returns The runner.
+ */
+export declare const flyctlRunner: (options?: {
+    cwd?: string;
+}) => FlyCommandRunner;
+/**
+ * Parse a Fly duration (`500ms`, `5s`, `1m0s`, `1h30m`) into milliseconds.
+ *
+ * @param value - The configured value.
+ * @returns Milliseconds; 0 when absent or not a duration.
+ */
+export declare function parseFlyDurationMs(value: unknown): number;
+/**
+ * The longest service-check grace period any of a Machine's checks declares.
+ *
+ * @param machine - One entry from `flyctl machine list --json`.
+ * @returns Milliseconds; 0 when the Machine's checks have no grace.
+ */
+export declare function serviceCheckGraceMs(machine: unknown): number;
+/**
+ * Parse `flyctl machine list --app <app> --json` into the facts a rollout needs.
+ *
+ * @param json - The command's stdout.
+ * @returns Every Machine, in the order Fly listed them.
+ * @throws {Error} When the output is not a JSON array.
+ */
+export declare const parseFlyMachineList: (json: string) => FlyMachine[];
+/**
+ * Validate a Machine list as a rollout target set and return what to act on.
+ *
+ * Every Machine must be started (a stopped one cannot be reached over SSH, and its
+ * patch volume would keep an older build), and all must run the SAME image and
+ * configuration version: a mixed set is a deploy in flight, and changing half of it
+ * would record a binding that is already stale on the other half.
+ *
+ * @param machines - Parsed Machines.
+ * @returns The target set's ids, image ref and configuration version.
+ * @throws {Error} A plain, operator-readable refusal.
+ */
+export declare const assertHomogeneousFlyMachines: (machines: readonly FlyMachine[], options?: {
+    appName?: string;
+}) => {
+    ids: string[];
+    imageRef: string;
+    version: string;
+};
+/** Where and how the adapter reaches one Fly app. */
+export interface FlyMachinesOptions {
+    /** The Fly app name. */
+    app: string;
+    /** The runner; defaults to spawning the local `flyctl`. */
+    run?: FlyCommandRunner;
+}
+/**
+ * List one Fly app's Machines.
+ *
+ * @param options - The app and the runner.
+ * @returns Every Machine the app has.
+ * @throws {Error} When flyctl refuses or its output is unreadable.
+ */
+export declare const listFlyMachines: (options: FlyMachinesOptions) => Promise<FlyMachine[]>;
+/**
+ * What an in-place Fly rollout supplies that Fly itself does not know.
+ *
+ * The adapter knows how to list, restart and start a Machine. Whether a Machine is
+ * SERVING, what "replace" means (a patch volume swap, a new image) and how to undo it
+ * are properties of the app being deployed, so the caller states them.
+ */
+export interface FlyInPlaceOptions extends FlyMachinesOptions {
+    /** Whether a Machine answers its readiness probe right now. */
+    isServing: (machineId: string) => Promise<boolean>;
+    /**
+     * Change one Machine to the new build and leave it serving. Defaults to a restart
+     * that waits for the Machine to reach `started`.
+     */
+    replace?: (machineId: string) => Promise<void>;
+    /** Put one Machine back on the old build. */
+    restore?: (machineId: string) => Promise<void>;
+    /** How long a restart may take to reach `started`. Defaults to 6 minutes. */
+    restartBudgetMs?: number;
+    /** Sleep between state polls. Defaults to 5000 ms. */
+    pollMs?: number;
+}
+/**
+ * Restart one Machine and wait until it is `started` again.
+ *
+ * A Machine that comes back `stopped` or `suspended` is started explicitly — Fly
+ * occasionally parks one after a restart, and a role that leaves it parked turns a
+ * successful roll into an outage.
+ *
+ * @param options - The app, the runner and the waits.
+ * @param machineId - The Machine to restart.
+ * @returns Whether it reached `started` inside the budget.
+ */
+export declare const restartFlyMachine: (options: FlyMachinesOptions & {
+    restartBudgetMs?: number;
+    pollMs?: number;
+}, machineId: string) => Promise<boolean>;
+/**
+ * Create an in-place Fly Machines provider for the rollout core.
+ *
+ * @param options - The app, the runner, the readiness probe and the restore path.
+ * @returns An `InPlaceInstanceProvider` over Fly Machines.
+ */
+export declare const createFlyInPlaceProvider: (options: FlyInPlaceOptions) => InPlaceInstanceProvider<FlyMachine>;
+/**
+ * What a grow-then-shrink Fly rollout supplies that Fly itself does not know.
+ *
+ * `launch` builds the Machine (image, volume, env, mounts) — that is the app's
+ * deployment recipe. `join`/`leave` change whatever edge routes to the app; Fly's own
+ * proxy balances by service, not by a caller-held set.
+ */
+export interface FlyInstanceOptions extends FlyMachinesOptions {
+    /** Create the Machine for `index` and resolve once it exists. */
+    launch: (index: number) => Promise<FlyMachine>;
+    /** Whether a Machine answers its readiness probe right now. */
+    isServing: (machine: FlyMachine) => Promise<boolean>;
+    /** Add a ready Machine to the caller's routable set. */
+    join?: (machine: FlyMachine) => Promise<void>;
+    /** Remove a Machine from the caller's routable set. */
+    leave?: (machine: FlyMachine) => Promise<void>;
+    /** How long `machine stop` may take. Defaults to 60 s. */
+    stopBudgetMs?: number;
+}
+/**
+ * Create a grow-then-shrink Fly Machines provider for the rollout core.
+ *
+ * `create` delegates to the caller's `launch`; `drain` asks Fly to stop the Machine
+ * (a SIGTERM with a bounded wait), and `destroy` removes it.
+ *
+ * @param options - The app, the runner and the app-specific operations.
+ * @returns An `InstanceProvider` over Fly Machines.
+ */
+export declare const createFlyInstanceProvider: (options: FlyInstanceOptions) => InstanceProvider<FlyMachine>;
+//# sourceMappingURL=fly.d.ts.map

package/dist/fly.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fly.d.ts","sourceRoot":"","sources":["../src/fly.ts"],"names":[],"mappings":"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"}

package/dist/fly.js

@@ -0,0 +1,281 @@
+/**
+ * Fly Machines adapter for the deploy-rollout core.
+ *
+ * Two shapes, because Fly supports both deployment topologies:
+ *
+ * - {@link createFlyInPlaceProvider} — the same Machines restarted onto a new build
+ *   one at a time, with a restore path. This is what the platform's own deploy tools
+ *   do today (a patch volume, an image deploy).
+ * - {@link createFlyInstanceProvider} — a new Machine cloned beside the old set and
+ *   retired when it is serving. Used when the deployment changes its instance count.
+ *
+ * The commands are executed through an injected {@link FlyCommandRunner}, so tests
+ * need no Fly account and a caller can decide how flyctl is reached (a checkout
+ * directory, a remote builder, a wrapper). What the adapter owns is the Fly-specific
+ * part: the command arguments and the `machine list --json` parse.
+ *
+ * @module
+ */
+import { execFile } from 'node:child_process';
+/**
+ * A runner that spawns the local `flyctl`.
+ *
+ * @param options - The working directory flyctl should see.
+ * @returns The runner.
+ */
+export const flyctlRunner = (options = {}) => {
+    return async (args) => {
+        return new Promise((resolve) => {
+            execFile('flyctl', args, { cwd: options.cwd, maxBuffer: 32 * 1024 * 1024, timeout: 300_000 }, (error, stdout, stderr) => {
+                resolve({
+                    status: error ? (error.code ?? null) : 0,
+                    stdout: String(stdout ?? ''),
+                    stderr: String(stderr ?? ''),
+                });
+            });
+        });
+    };
+};
+/**
+ * Parse a Fly duration (`500ms`, `5s`, `1m0s`, `1h30m`) into milliseconds.
+ *
+ * @param value - The configured value.
+ * @returns Milliseconds; 0 when absent or not a duration.
+ */
+export function parseFlyDurationMs(value) {
+    if (typeof value !== 'string')
+        return 0;
+    let total = 0;
+    let matched = false;
+    for (const match of value.matchAll(/(\d+)(ms|s|m|h)/g)) {
+        matched = true;
+        const scale = { ms: 1, s: 1_000, m: 60_000, h: 3_600_000 }[match[2] ?? ''] ?? 0;
+        total += Number(match[1] ?? 0) * scale;
+    }
+    return matched ? total : 0;
+}
+/**
+ * The longest service-check grace period any of a Machine's checks declares.
+ *
+ * @param machine - One entry from `flyctl machine list --json`.
+ * @returns Milliseconds; 0 when the Machine's checks have no grace.
+ */
+export function serviceCheckGraceMs(machine) {
+    let longest = 0;
+    const services = machine?.config?.services ?? [];
+    for (const service of services) {
+        const checks = service?.checks ?? [];
+        for (const check of checks) {
+            longest = Math.max(longest, parseFlyDurationMs(check?.grace_period));
+        }
+    }
+    return longest;
+}
+/**
+ * Parse `flyctl machine list --app <app> --json` into the facts a rollout needs.
+ *
+ * @param json - The command's stdout.
+ * @returns Every Machine, in the order Fly listed them.
+ * @throws {Error} When the output is not a JSON array.
+ */
+export const parseFlyMachineList = (json) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (error) {
+        throw new Error(`could not parse 'flyctl machine list --json': ${error.message}`, {
+            cause: error,
+        });
+    }
+    if (!Array.isArray(parsed))
+        throw new Error('flyctl machine list did not return an array');
+    return parsed.map((machine) => {
+        const config = machine?.config;
+        // `config.image` is the live shape; `image_ref` is what older flyctl output
+        // (and the fixtures) carry at the top level.
+        const image = config?.image ?? machine?.image_ref;
+        let imageRef = null;
+        if (typeof image === 'string')
+            imageRef = image;
+        else if (image && typeof image.digest === 'string') {
+            // A Machine deployed BY DIGEST reports no tag; the tag form would be
+            // `…:undefined`, which never matches the Machine's real FLY_IMAGE_REF.
+            const ref = image;
+            imageRef = `${String(ref.registry)}/${String(ref.repository)}@${String(ref.digest)}`;
+        }
+        else if (image) {
+            const ref = image;
+            imageRef = `${String(ref.registry)}/${String(ref.repository)}:${String(ref.tag)}`;
+        }
+        const id = typeof machine?.id === 'string' ? machine.id : '';
+        const version = typeof (machine?.instance_id ?? machine?.version) === 'string'
+            ? (machine.instance_id ?? machine.version)
+            : null;
+        return {
+            id,
+            upstreamUrl: undefined,
+            state: typeof machine?.state === 'string' ? machine.state : '',
+            imageRef,
+            version,
+            gracePeriodMs: serviceCheckGraceMs(machine),
+        };
+    });
+};
+/**
+ * Validate a Machine list as a rollout target set and return what to act on.
+ *
+ * Every Machine must be started (a stopped one cannot be reached over SSH, and its
+ * patch volume would keep an older build), and all must run the SAME image and
+ * configuration version: a mixed set is a deploy in flight, and changing half of it
+ * would record a binding that is already stale on the other half.
+ *
+ * @param machines - Parsed Machines.
+ * @returns The target set's ids, image ref and configuration version.
+ * @throws {Error} A plain, operator-readable refusal.
+ */
+export const assertHomogeneousFlyMachines = (machines, options = {}) => {
+    const app = options.appName ?? 'the app';
+    if (machines.length === 0)
+        throw new Error(`${app} has no Machines`);
+    const stopped = machines.filter((machine) => machine.state !== 'started');
+    if (stopped.length > 0) {
+        throw new Error(`${app} machine(s) ${stopped.map((m) => `${m.id} (${m.state})`).join(', ')} are not ` +
+            'started — start them before rolling so every Machine gets the change');
+    }
+    for (const machine of machines) {
+        if (!/^[0-9a-f]{14}$/.test(machine.id)) {
+            throw new Error(`unexpected machine id from flyctl: ${JSON.stringify(machine.id)}`);
+        }
+        if (!machine.imageRef) {
+            throw new Error(`machine ${machine.id} has no readable image ref — a change that cannot name its image ` +
+                'would outlive it');
+        }
+        if (!machine.version) {
+            throw new Error(`machine ${machine.id} has no configuration version (instance_id/version) — a change ` +
+                'bound only to the image ref survives a same-tag redeploy');
+        }
+    }
+    const imageRefs = [...new Set(machines.map((machine) => machine.imageRef))];
+    const versions = [...new Set(machines.map((machine) => machine.version))];
+    if (imageRefs.length > 1 || versions.length > 1) {
+        throw new Error(`${app} Machines are running MIXED builds ` +
+            `(images: ${imageRefs.join(', ')}; versions: ${versions.join(', ')}) — a deploy is in ` +
+            'flight or a Machine was started separately. Wait for it to settle, then re-run.');
+    }
+    return {
+        ids: machines.map((machine) => machine.id),
+        imageRef: imageRefs[0],
+        version: versions[0],
+    };
+};
+/**
+ * List one Fly app's Machines.
+ *
+ * @param options - The app and the runner.
+ * @returns Every Machine the app has.
+ * @throws {Error} When flyctl refuses or its output is unreadable.
+ */
+export const listFlyMachines = async (options) => {
+    const run = options.run ?? flyctlRunner();
+    const result = await run(['machine', 'list', '--app', options.app, '--json']);
+    if (result.status !== 0) {
+        throw new Error(`flyctl machine list failed for ${options.app}: ${(result.stderr ?? '').trim().slice(0, 300)}`);
+    }
+    return parseFlyMachineList(result.stdout);
+};
+/**
+ * Restart one Machine and wait until it is `started` again.
+ *
+ * A Machine that comes back `stopped` or `suspended` is started explicitly — Fly
+ * occasionally parks one after a restart, and a role that leaves it parked turns a
+ * successful roll into an outage.
+ *
+ * @param options - The app, the runner and the waits.
+ * @param machineId - The Machine to restart.
+ * @returns Whether it reached `started` inside the budget.
+ */
+export const restartFlyMachine = async (options, machineId) => {
+    const run = options.run ?? flyctlRunner();
+    const budgetMs = Math.max(0, options.restartBudgetMs ?? 6 * 60_000);
+    const pollMs = Math.max(1, options.pollMs ?? 5_000);
+    await run(['machine', 'restart', machineId, '--app', options.app]);
+    for (let waited = 0; waited <= budgetMs; waited += pollMs) {
+        const state = (await listFlyMachines({ app: options.app, run })).find((machine) => machine.id === machineId)?.state;
+        if (state === 'started')
+            return true;
+        if (state === 'stopped' || state === 'suspended') {
+            await run(['machine', 'start', machineId, '--app', options.app]);
+        }
+        await new Promise((resolve) => {
+            setTimeout(resolve, pollMs);
+        });
+    }
+    return false;
+};
+/**
+ * Create an in-place Fly Machines provider for the rollout core.
+ *
+ * @param options - The app, the runner, the readiness probe and the restore path.
+ * @returns An `InPlaceInstanceProvider` over Fly Machines.
+ */
+export const createFlyInPlaceProvider = (options) => {
+    const run = options.run ?? flyctlRunner();
+    return {
+        name: `fly:${options.app}`,
+        list: () => listFlyMachines({ app: options.app, run }),
+        isServing: (machine) => options.isServing(machine.id),
+        replace: async (machine) => {
+            if (options.replace)
+                return options.replace(machine.id);
+            const started = await restartFlyMachine({ app: options.app, run, restartBudgetMs: options.restartBudgetMs, pollMs: options.pollMs }, machine.id);
+            if (!started)
+                throw new Error(`machine ${machine.id} did not reach started after a restart`);
+        },
+        restore: async (machine) => {
+            if (!options.restore) {
+                throw new Error('Fly in-place rollout has no restore path — pass options.restore');
+            }
+            return options.restore(machine.id);
+        },
+    };
+};
+/**
+ * Create a grow-then-shrink Fly Machines provider for the rollout core.
+ *
+ * `create` delegates to the caller's `launch`; `drain` asks Fly to stop the Machine
+ * (a SIGTERM with a bounded wait), and `destroy` removes it.
+ *
+ * @param options - The app, the runner and the app-specific operations.
+ * @returns An `InstanceProvider` over Fly Machines.
+ */
+export const createFlyInstanceProvider = (options) => {
+    const run = options.run ?? flyctlRunner();
+    return {
+        name: `fly:${options.app}`,
+        list: () => listFlyMachines({ app: options.app, run }),
+        create: (index) => options.launch(index),
+        waitReady: async (machine) => options.isServing(machine),
+        isServing: (machine) => options.isServing(machine),
+        join: async (machine) => options.join?.(machine),
+        leave: async (machine) => options.leave?.(machine),
+        drain: async (machine, drainMs) => {
+            await run(['machine', 'stop', machine.id, '--app', options.app]);
+            const budget = Math.min(drainMs, options.stopBudgetMs ?? 60_000);
+            const pollMs = 2_000;
+            for (let waited = 0; waited <= budget; waited += pollMs) {
+                const state = (await listFlyMachines({ app: options.app, run })).find((candidate) => candidate.id === machine.id)?.state;
+                if (state === 'stopped' || state === 'destroyed' || state === undefined)
+                    return;
+                await new Promise((resolve) => {
+                    setTimeout(resolve, pollMs);
+                });
+            }
+            // The stop is best-effort by design: a Machine that will not stop is still
+            // destroyed next, and the rollout must not hang on it.
+        },
+        destroy: async (machine) => {
+            await run(['machine', 'destroy', machine.id, '--app', options.app, '--force']);
+        },
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Fly Machines provider bonds for the deploy-rollout core.
+ *
+ * In-place (restart the same Machines one at a time, with a restore path) and
+ * grow-then-shrink (clone a Machine beside the old set, retire the old one when the
+ * new one serves). Commands run through an injected runner, so tests need no Fly
+ * account.
+ *
+ * @example
+ * ```typescript
+ * import { runInPlaceRollout, setProvider } from '@molecule/api-deploy-rollout'
+ * import { provider } from '@molecule/api-deploy-rollout-default'
+ * import { createFlyInPlaceProvider } from '@molecule/api-deploy-rollout-fly'
+ *
+ * setProvider(provider)
+ * await runInPlaceRollout({
+ *   provider: createFlyInPlaceProvider({
+ *     app: 'molecule-api',
+ *     isServing: (id) => probeMachine(id),
+ *     restore: (id) => clearPatchAndRestart(id),
+ *   }),
+ *   policy: { soakMs: 30_000 },
+ * })
+ * ```
+ *
+ * @remarks
+ * - **`parseFlyMachineList` is the only JSON the adapter trusts.** A Machine list
+ *   that is not an array is an error, never an empty set.
+ * - **A mixed set is refused.** `assertHomogeneousFlyMachines` rejects Machines on
+ *   different images or configuration versions: that is a deploy in flight, and
+ *   changing half of it records a binding that is already stale on the other half.
+ * - **A restart that parks is started explicitly.** A Machine that comes back
+ *   `stopped`/`suspended` after a restart is started, not left parked.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './fly.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,UAAU,CAAA"}

package/dist/index.js

@@ -0,0 +1,38 @@
+/**
+ * Fly Machines provider bonds for the deploy-rollout core.
+ *
+ * In-place (restart the same Machines one at a time, with a restore path) and
+ * grow-then-shrink (clone a Machine beside the old set, retire the old one when the
+ * new one serves). Commands run through an injected runner, so tests need no Fly
+ * account.
+ *
+ * @example
+ * ```typescript
+ * import { runInPlaceRollout, setProvider } from '@molecule/api-deploy-rollout'
+ * import { provider } from '@molecule/api-deploy-rollout-default'
+ * import { createFlyInPlaceProvider } from '@molecule/api-deploy-rollout-fly'
+ *
+ * setProvider(provider)
+ * await runInPlaceRollout({
+ *   provider: createFlyInPlaceProvider({
+ *     app: 'molecule-api',
+ *     isServing: (id) => probeMachine(id),
+ *     restore: (id) => clearPatchAndRestart(id),
+ *   }),
+ *   policy: { soakMs: 30_000 },
+ * })
+ * ```
+ *
+ * @remarks
+ * - **`parseFlyMachineList` is the only JSON the adapter trusts.** A Machine list
+ *   that is not an array is an error, never an empty set.
+ * - **A mixed set is refused.** `assertHomogeneousFlyMachines` rejects Machines on
+ *   different images or configuration versions: that is a deploy in flight, and
+ *   changing half of it records a binding that is already stale on the other half.
+ * - **A restart that parks is started explicitly.** A Machine that comes back
+ *   `stopped`/`suspended` after a restart is started, not left parked.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './fly.js';

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@molecule/api-deploy-rollout-fly",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1-stage",
+  "description": "Fly Machines provider bond for @molecule/api-deploy-rollout: in-place restarts with a restore path and grow-then-shrink clones, over an injected flyctl runner.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "molecule",
+    "deploy",
+    "rollout",
+    "fly",
+    "fly machines"
+  ],
+  "author": "Molecule Dev, Inc. (https://molecule.dev)",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@molecule/api-deploy-rollout": "^1.0.0"
+  },
+  "devDependencies": {
+    "@molecule/api-deploy-rollout": "1.0.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/bonds/deploy-rollout/fly"
+  },
+  "homepage": "https://www.molecule.dev/packages/api-deploy-rollout-fly",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}