@granite-js/forge-cli 2.5.1 → 2.5.3

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @granite-js/forge-cli
 
+## 2.5.3
+
+### Patch Changes
+
+- 8b04ab6: Add configurable deployment channels across Forge, deployment storage and the AWS CDN. Forge automatically
+  registers each app/channel selector in S3, so channel creation requires no per-channel infrastructure configuration.
+  Channel objects, state, history and cluster pointers are isolated under `channels/<channel>/`. Registered path
+  suffixes select channels while the legacy default and unregistered filename tags keep their existing routes.
+  Conditional selector reservations and checks against retained legacy bundles prevent tag/channel name conflicts
+  between updated publishers. Registration and rollout events invalidate service selectors, and unique invalidation
+  caller references prevent simultaneous requests from colliding. Missing channel deployments never fall back to
+  another namespace. Cluster rollouts now write the `.deploymentInfo` pointer used by readers and invalidation.
+
+  The exported `paths` helpers take one options object instead of positional arguments.
+
+- Updated dependencies [8b04ab6]
+  - @granite-js/deployment-manager@2.5.3
+  - @granite-js/plugin-core@2.5.3
+
+## 2.5.2
+
+### Patch Changes
+
+- @granite-js/deployment-manager@2.5.2
+- @granite-js/plugin-core@2.5.2
+
 ## 2.5.1
 
 ### Patch Changes

package/README.md

@@ -1,3 +1,73 @@
-# @granite-js/forge
+# @granite-js/forge-cli
 
-A CLI tool for managing Granite applications
+A CLI tool for managing Granite applications.
+
+## Deployment channels
+
+Use `--channel` to keep deployments for the same application independent. Channel names are configurable,
+case-sensitive strings containing 1–64 letters, digits, underscores or hyphens, starting with a letter or digit.
+They are not derived from the React Native version and are never normalized.
+
+```sh
+granite-forge deploy --bucket sample-bucket --channel preview
+```
+
+The app name and built bundle directory come from the Granite config. AWS credentials and region are resolved
+using the existing AWS provider chain. Both platform uploads must finish before the deployment is promoted.
+
+To inspect history, pass the same channel to `deploy-list`, together with its existing S3 options:
+
+```sh
+granite-forge deploy-list --app-name sample-app --channel preview \
+  --bucket sample-bucket --region "$AWS_REGION" \
+  --access-key-id "$AWS_ACCESS_KEY_ID" --secret-access-key "$AWS_SECRET_ACCESS_KEY"
+```
+
+Include `--session-token "$AWS_SESSION_TOKEN"` when using temporary credentials.
+
+Omitting `--channel` preserves the existing unscoped namespace. No named channel, including a channel named
+`default`, aliases that namespace. Existing objects are not moved or copied.
+
+| Scope              | Deployment state                                           | Bundle URL                  |
+| ------------------ | ---------------------------------------------------------- | --------------------------- |
+| Existing, unscoped | `deployments/sample-app/deployment_state`                  | `/ios/sample-app/1/bundle`  |
+| `preview`          | `channels/preview/deployments/sample-app/deployment_state` | `/ios/sample-app/1/preview` |
+
+Bundle objects, deployment history, stable/canary state and cluster pointers all use the same channel prefix.
+Forge automatically registers the app/channel selector in S3 before uploading bundles. No per-channel Pulumi
+configuration or Lambda redeployment is needed after installing the channel-aware infrastructure once.
+For example, deploying with `--channel next` makes `/ios/sample-app/1/next` select that app's `next` channel.
+
+A registration lives at `deployments/<app>/selectors/<channel>.json`. On first registration, Forge checks the
+app's retained legacy bundle objects for a matching filename tag. New tag uploads and channel registrations
+conditionally reserve the same selector key, so concurrent writers cannot silently change its meaning.
+An existing tag/channel name collision fails the deployment before bundle uploads or promotion.
+
+The deployment credentials need `s3:GetObject`, `s3:PutObject` and `s3:ListBucket` for these paths; listing is used
+only when creating a new channel registration. Use the updated deployment manager for legacy tagged uploads
+before enabling channel creation, because older tag publishers do not participate in selector reservations.
+
+`bundle` remains reserved for the legacy default. Unregistered suffixes retain their filename-tag meaning.
+A registered channel with no deployment returns 404 and never falls back to a legacy bundle. Registrations are
+kept after failed deployments; retry with the same channel to finish publishing. Channels serve default bundle
+filenames; query parameters do not select channels. See the [CDN contract](../pulumi-aws/README.md#deployment-channels).
+
+## Native runtime selection
+
+Configure the channel in the native app build that owns the runtime, then use it for every remote bundle request,
+including the shared bundle and app bundles. Keep older binaries on their existing URLs while newer binaries
+use their configured channel. A JS deployment cannot change the channel chosen by the native binary.
+
+Deploy only bundles compatible with the native runtime assigned to that channel. Channels isolate delivery;
+they do not compile bundles, infer runtime compatibility or validate the bytecode ABI. Release tooling must keep
+the native build configuration and `--channel` value aligned.
+
+Install and verify the channel-aware Lambda and S3 notifications before enabling channel URLs in native clients.
+The old Lambda interprets trailing channel names as filename tags. Registration and rollout events invalidate
+the affected app selectors asynchronously; wait for invalidation to finish before enabling new native clients.
+With the updated handler, a missing deployment in a named channel returns 404 without falling back to the legacy
+namespace or another channel. Native clients should handle that failure using their own compatible embedded
+bundle or error handling.
+
+See [the CDN documentation](../pulumi-aws/README.md#deployment-channels) for URL routing, cache isolation and
+shared-bundle bootstrapping.

package/dist/index.js

@@ -3,7 +3,7 @@ import path from "path";
 import { fromNodeProviderChain } from "@aws-sdk/credential-providers";
 import { loadSharedConfigFiles } from "@aws-sdk/shared-ini-file-loader";
 import * as p from "@clack/prompts";
-import { DeployManager, NoSuchKey, S3Client } from "@granite-js/deployment-manager";
+import { DeployManager, NoSuchKey, S3Client, validateChannel } from "@granite-js/deployment-manager";
 import { loadConfig } from "@granite-js/plugin-core";
 import * as v from "valibot";
 import { v7 } from "uuid";
@@ -50,7 +50,9 @@ function promptErrorHandler(error) {
 //#region src/operations/deploy.ts
 const deploy$1 = handlePrompts("Start deployment", deployImpl);
 async function deployImpl({ androidBundle, iosBundle, appName, tag }, context) {
-	const { s3Client } = context;
+	if (context.channel !== void 0) validateChannel(context.channel);
+	const deploymentTarget = `${appName} (channel: ${context.channel ?? "legacy / unscoped"})`;
+	p.log.info(`Deployment target: ${deploymentTarget}`);
 	const gzippedAndroidBundle = `${androidBundle}.gz`;
 	const gzippedIosBundle = `${iosBundle}.gz`;
 	await Promise.all([gzipFile({
@@ -64,7 +66,7 @@ async function deployImpl({ androidBundle, iosBundle, appName, tag }, context) {
 	const deployedAt = /* @__PURE__ */ new Date();
 	let spinner = p.spinner();
 	spinner.start("Fetching current deployment state...");
-	const currentDeploymentState = await DeployManager.readDeploymentState(appName, { s3Client }).catch(handleReadDeploymentStateError);
+	const currentDeploymentState = await DeployManager.readDeploymentState(appName, context).catch(handleReadDeploymentStateError);
 	spinner.stop("Successfully fetched current deployment state");
 	let newDeploymentState;
 	if (currentDeploymentState != null) {
@@ -90,12 +92,16 @@ async function deployImpl({ androidBundle, iosBundle, appName, tag }, context) {
 		};
 	}
 	if (process.stdin.isTTY) {
-		const confirmed = await p.confirm({ message: `Are you sure you want to deploy ${appName}?` });
+		const confirmed = await p.confirm({ message: `Are you sure you want to deploy ${deploymentTarget}?` });
 		if (!confirmed || p.isCancel(confirmed)) {
 			p.outro("Deployment cancelled");
 			process.exit(0);
 		}
 	}
+	if (context.channel !== void 0) await DeployManager.registerChannel({
+		appName,
+		channel: context.channel
+	}, context);
 	await p.tasks([{
 		bundlePath: gzippedAndroidBundle,
 		platform: "android"
@@ -112,7 +118,7 @@ async function deployImpl({ androidBundle, iosBundle, appName, tag }, context) {
 				tag,
 				deploymentId,
 				deployedAt
-			}, { s3Client });
+			}, context);
 			return "Bundle uploaded";
 		}
 	})));
@@ -124,14 +130,14 @@ async function deployImpl({ androidBundle, iosBundle, appName, tag }, context) {
 			deployedAt: deployedAt.getTime(),
 			deploymentId
 		}
-	}, { s3Client });
+	}, context);
 	spinner.stop("Bundle list updated");
 	spinner = p.spinner();
 	spinner.start(`Deploying ${appName}@${deploymentId}...`);
 	await DeployManager.rollout({
 		state: newDeploymentState,
 		appName
-	}, { s3Client });
+	}, context);
 	spinner.stop(`Deployed successfully! (Deployment ID: ${deploymentId})`);
 	p.outro("Done");
 }
@@ -150,7 +156,7 @@ const envSchema = v.object({
 });
 const awsCredentialsProvider = fromNodeProviderChain();
 function deploy() {
-	return new Command("deploy").description("Deploy a Granite application").requiredOption("--bucket <BUCKET>", "AWS bucket").action(async (options) => {
+	return new Command("deploy").description("Deploy a Granite application").requiredOption("--bucket <BUCKET>", "AWS bucket").option("--channel <CHANNEL>", "Deployment channel (omit for the legacy namespace)", validateChannel).action(async (options) => {
 		const [config, awsCredentials, region] = await Promise.all([
 			loadConfig(),
 			awsCredentialsProvider(),
@@ -175,15 +181,18 @@ function deploy() {
 			appName: config.appName,
 			iosBundle: path.join(config.outdir, `bundle.ios.hbc`),
 			androidBundle: path.join(config.outdir, `bundle.android.hbc`)
-		}, { s3Client: new S3Client({
-			region,
-			bucket: options.bucket,
-			credentials: {
-				accessKeyId: envResult.output.AWS_ACCESS_KEY_ID,
-				secretAccessKey: envResult.output.AWS_SECRET_ACCESS_KEY,
-				sessionToken: envResult.output.AWS_SESSION_TOKEN
-			}
-		}) });
+		}, {
+			channel: options.channel,
+			s3Client: new S3Client({
+				region,
+				bucket: options.bucket,
+				credentials: {
+					accessKeyId: envResult.output.AWS_ACCESS_KEY_ID,
+					secretAccessKey: envResult.output.AWS_SECRET_ACCESS_KEY,
+					sessionToken: envResult.output.AWS_SESSION_TOKEN
+				}
+			})
+		});
 	});
 }
 async function getRegion() {
@@ -208,10 +217,11 @@ function withS3Client(command) {
 //#region src/operations/deployList.ts
 const deployList$1 = handlePrompts("Deployment list", deployListImpl);
 async function deployListImpl({ appName }, context) {
-	const { s3Client } = context;
+	if (context.channel !== void 0) validateChannel(context.channel);
+	p.log.info(`Deployment target: ${appName} (channel: ${context.channel ?? "legacy / unscoped"})`);
 	const spinner = p.spinner();
 	spinner.start("Fetching deployment list...");
-	const deployments = await DeployManager.readBundleList(appName, { s3Client }).catch(handleReadBundleListError);
+	const deployments = await DeployManager.readBundleList(appName, context).catch(handleReadBundleListError);
 	spinner.stop("Successfully fetched deployment list");
 	deployments.slice(0, 20).forEach((deployment, index) => {
 		p.log.info(`${index + 1}. ${deployment.deploymentId} (Deployed at: ${new Date(deployment.deployedAt).toLocaleString()})`);
@@ -226,16 +236,19 @@ function handleReadBundleListError(error) {
 //#endregion
 //#region src/commands/deployList.ts
 function deployList() {
-	return withS3Client(new Command("deploy-list")).description("Show the deployment list of a Granite application").requiredOption("-n, --app-name <APP_NAME>", "Granite application name").action(async (options) => {
-		await deployList$1(options, { s3Client: new S3Client({
-			region: options.region,
-			bucket: options.bucket,
-			credentials: {
-				accessKeyId: options.accessKeyId,
-				secretAccessKey: options.secretAccessKey,
-				sessionToken: options.sessionToken
-			}
-		}) });
+	return withS3Client(new Command("deploy-list")).description("Show the deployment list of a Granite application").requiredOption("-n, --app-name <APP_NAME>", "Granite application name").option("--channel <CHANNEL>", "Deployment channel (omit for the legacy namespace)", validateChannel).action(async (options) => {
+		await deployList$1(options, {
+			channel: options.channel,
+			s3Client: new S3Client({
+				region: options.region,
+				bucket: options.bucket,
+				credentials: {
+					accessKeyId: options.accessKeyId,
+					secretAccessKey: options.secretAccessKey,
+					sessionToken: options.sessionToken
+				}
+			})
+		});
 	});
 }
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@granite-js/forge-cli",
   "description": "A CLI tool for managing Granite applications",
   "type": "module",
-  "version": "2.5.1",
+  "version": "2.5.3",
   "bin": {
     "granite-forge": "./bin/index.js"
   },
@@ -34,8 +34,8 @@
     "@aws-sdk/shared-ini-file-loader": "^3.374.0",
     "@clack/prompts": "^0.10.1",
     "@commander-js/extra-typings": "^14.0.0",
-    "@granite-js/deployment-manager": "2.5.1",
-    "@granite-js/plugin-core": "2.5.1",
+    "@granite-js/deployment-manager": "2.5.3",
+    "@granite-js/plugin-core": "2.5.3",
     "commander": "^14.0.0",
     "uuid": "^11.1.0",
     "valibot": "^1.1.0"