@projectdochelp/s3te 3.1.3 → 3.1.4

package/README.md

@@ -430,19 +430,35 @@ That workflow is meant for source publishing only:
 
 Use a full `deploy` only when the infrastructure, environment config, or runtime package changes.
 
-Before the workflow can run, do this once:
-
-1. Run the first real `npx s3te deploy --env <name>` so the code bucket already exists.
-2. In AWS IAM, create an access key for a CI user that may sync only the S3TE code bucket for that environment.
-3. In GitHub open `Settings -> Secrets and variables -> Actions -> Secrets`.
-4. Add these repository secrets:
+GitHub preparation checklist:
+
+1. Push the project to GitHub together with `.github/workflows/s3te-sync.yml`.
+2. Make sure GitHub Actions are allowed for the repository or organization.
+3. Run the first real `npx s3te deploy --env <name>` so the code bucket already exists.
+4. In AWS IAM, create an access key for a CI user that may sync only the S3TE code bucket for that environment.
+5. In GitHub open `Settings -> Secrets and variables -> Actions -> Secrets`.
+6. Add these repository secrets:
    - `AWS_ACCESS_KEY_ID`
    - `AWS_SECRET_ACCESS_KEY`
-5. Open `.github/workflows/s3te-sync.yml` and adjust:
+7. Open `.github/workflows/s3te-sync.yml` and adjust:
    - the branch under `on.push.branches`
    - `aws-region`
    - `npx s3te sync --env dev` to your target environment such as `prod` or `test`
 
+No GitHub variables are required by the scaffolded workflow. The code bucket name is resolved by S3TE from `s3te.config.json`, so you do not have to store bucket names in GitHub.
+
+For projects with multiple environments such as `test` and `prod`, the simplest setup is usually one workflow file per target environment, for example:
+
+- `.github/workflows/s3te-sync-test.yml` with `npx s3te sync --env test`
+- `.github/workflows/s3te-sync-prod.yml` with `npx s3te sync --env prod`
+
+First verification in GitHub:
+
+1. Open the `Actions` tab in the repository.
+2. Select `S3TE Sync`.
+3. Start it once manually with `Run workflow`.
+4. Check that the run reaches the `Configure AWS credentials`, `Validate project`, and `Sync project sources to the S3TE code bucket` steps without error.
+
 Minimal IAM policy example for one code bucket:
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@projectdochelp/s3te",
-  "version": "3.1.3",
+  "version": "3.1.4",
   "description": "CLI, render core, AWS adapter, and testkit for S3TemplateEngine projects",
   "repository": {
     "type": "git",

package/packages/cli/src/project.mjs

@@ -32,6 +32,21 @@ function normalizePath(value) {
   return String(value).replace(/\\/g, "/");
 }
 
+function unknownEnvironmentMessage(config, environmentName) {
+  const knownEnvironments = Object.keys(config?.environments ?? {});
+  return `Unknown environment ${environmentName}. Known environments: ${knownEnvironments.length > 0 ? knownEnvironments.join(", ") : "(none)"}.`;
+}
+
+function assertKnownEnvironment(config, environmentName) {
+  if (!environmentName) {
+    return;
+  }
+
+  if (!config?.environments?.[environmentName]) {
+    throw new S3teError("CONFIG_CONFLICT_ERROR", unknownEnvironmentMessage(config, environmentName));
+  }
+}
+
 function normalizeBaseUrl(value) {
   const trimmed = String(value).trim();
   if (!trimmed) {
@@ -235,7 +250,11 @@ function schemaTemplate() {
 }
 
 function githubSyncWorkflowTemplate() {
-  return `name: S3TE Sync
+  return `# Before first use:
+# 1. Run "npx s3te deploy --env dev" once so the S3TE code bucket already exists.
+# 2. Add GitHub Actions secrets AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
+# 3. Adjust branch, aws-region, and the target environment below.
+name: S3TE Sync
 
 on:
   workflow_dispatch:
@@ -459,6 +478,18 @@ export async function loadResolvedConfig(projectDir, configPath) {
 }
 
 export async function validateProject(projectDir, config, options = {}) {
+  if (options.environment && !config?.environments?.[options.environment]) {
+    return {
+      ok: false,
+      errors: [{
+        code: "CONFIG_CONFLICT_ERROR",
+        message: unknownEnvironmentMessage(config, options.environment)
+      }],
+      warnings: [],
+      checkedTemplates: []
+    };
+  }
+
   const templateRepository = new FileSystemTemplateRepository(projectDir, config);
   const contentRepository = await loadLocalContent(projectDir, config);
   const warnings = [];
@@ -595,6 +626,7 @@ export async function scaffoldProject(projectDir, options = {}) {
 }
 
 export async function renderProject(projectDir, config, options = {}) {
+  assertKnownEnvironment(config, options.environment);
   const templateRepository = new FileSystemTemplateRepository(projectDir, config);
   const contentRepository = await loadLocalContent(projectDir, config);
   const outputRoot = path.join(projectDir, options.outputDir ?? config.rendering.outputDir);
@@ -700,6 +732,7 @@ export async function runProjectTests(projectDir) {
 }
 
 export async function packageProject(projectDir, config, options = {}) {
+  assertKnownEnvironment(config, options.environment);
   return packageAwsProject({
     projectDir,
     config,
@@ -711,6 +744,7 @@ export async function packageProject(projectDir, config, options = {}) {
 }
 
 export async function deployProject(projectDir, config, options = {}) {
+  assertKnownEnvironment(config, options.environment);
   return deployAwsProject({
     projectDir,
     config,
@@ -725,6 +759,7 @@ export async function deployProject(projectDir, config, options = {}) {
 }
 
 export async function syncProject(projectDir, config, options = {}) {
+  assertKnownEnvironment(config, options.environment);
   return syncAwsProject({
     projectDir,
     config,
@@ -767,6 +802,15 @@ export async function doctorProject(projectDir, configPath, options = {}) {
   }
 
   if (options.environment && options.config) {
+    if (!options.config.environments?.[options.environment]) {
+      checks.push({
+        name: "environment",
+        ok: false,
+        message: unknownEnvironmentMessage(options.config, options.environment)
+      });
+      return checks;
+    }
+
     try {
       await ensureAwsCredentials({
         region: options.config.environments[options.environment].awsRegion,