@gambi97/keel-cli 0.2.1 → 0.3.0

package/README.md

@@ -163,12 +163,12 @@ local tooling or production credentials.
 
 **Phase A: bootstrap (the CLI, via APIs, after your confirmation)**
 
-| Where        | What                                                                                                                                                                                                                                                   |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Your machine | The generated repo: Terraform, workflows, README, initial git commit                                                                                                                                                                                   |
-| Scaleway     | One Object Storage bucket for Terraform state (versioned, with native state locking, restricted by a bucket policy to the identity behind your API key)                                                                                                |
-| GitHub       | Repository (public or private) pushed to `main`; encrypted Actions secrets; Actions variables; one deployment environment per selected environment (`production` gated by manual approval); branch protection on `main`                                |
-| Infisical    | A project with one environment per selected environment, seeded with `BASIC_AUTH_USER` / `BASIC_AUTH_PASSWORD` (non-production, random password), a `DATABASE_URL` placeholder per environment, and `S3_*` placeholders when Object Storage is enabled |
+| Where        | What                                                                                                                                                                                                                                                              |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Your machine | The generated repo: Terraform, workflows, README, initial git commit                                                                                                                                                                                              |
+| Scaleway     | One Object Storage bucket for Terraform state (versioned, with native state locking, restricted by a bucket policy to the identity behind your API key)                                                                                                           |
+| GitHub       | Repository (public or private) pushed to `main`; encrypted Actions secrets; Actions variables; one deployment environment per selected environment (`production` gated by manual approval); branch protection on `main`                                           |
+| Infisical    | A project with one environment per selected environment, seeded with `BASIC_AUTH_USER` / `BASIC_AUTH_PASSWORD` (non-production, random password), `DATABASE_URL` / `APP_URL` placeholders per environment, and `S3_*` placeholders when Object Storage is enabled |
 
 **Phase B: first deploy (Terraform in GitHub Actions, on push to `main`)**
 
@@ -192,6 +192,7 @@ my-app/
 │   ├── terraform-plan.yml       # PR: fmt + validate + plan (every environment)
 │   ├── terraform-apply.yml      # main: apply each env in order; production gated
 │   └── terraform-drift.yml      # weekly: read-only plan, opens an issue on drift
+├── .keel/manifest.json          # committed record: keel version, contract version, options
 ├── versions.tf · providers.tf · backend.tf
 ├── backend.hcl.example          # state bucket coordinates (backend.hcl is git-ignored)
 ├── variables.tf · main.tf · outputs.tf
@@ -203,15 +204,16 @@ Environments are separated with **Terraform workspaces**: same code, one
 independent state per environment in one bucket, differences confined to the
 per-environment `<env>.tfvars` files.
 
-| Data                                | Lives in                 | Why                                                                  |
-| ----------------------------------- | ------------------------ | -------------------------------------------------------------------- |
-| Scaleway API keys                   | GitHub encrypted secrets | CI needs them to run Terraform                                       |
-| Infisical machine identity          | GitHub encrypted secrets | Lets Terraform read app secrets at plan/apply                        |
-| Basic Auth user/password            | Infisical (non-prod)     | App secret, injected into the container, rotatable                   |
-| Database connection string          | Infisical (each env)     | Complete, ready-to-use value synced by the pipeline after each apply |
-| Object Storage coordinates (opt-in) | Infisical (each env)     | `S3_*` values synced by the pipeline after each apply                |
-| Bucket, region, Infisical project   | GitHub variables         | Non-sensitive wiring, editable in one place                          |
-| Project name, scaling, image        | Committed tfvars         | Reviewable configuration, no secrets                                 |
+| Data                                | Lives in                 | Why                                                                                  |
+| ----------------------------------- | ------------------------ | ------------------------------------------------------------------------------------ |
+| Scaleway API keys                   | GitHub encrypted secrets | CI needs them to run Terraform                                                       |
+| Infisical machine identity          | GitHub encrypted secrets | Lets Terraform read app secrets at plan/apply                                        |
+| Basic Auth user/password            | Infisical (non-prod)     | App secret, injected into the container, rotatable                                   |
+| Database connection string          | Infisical (each env)     | Complete, ready-to-use value synced by the pipeline after each apply                 |
+| App public URL (`APP_URL`)          | Infisical (each env)     | Synced by the pipeline once a container exists; for links, OAuth callbacks, webhooks |
+| Object Storage coordinates (opt-in) | Infisical (each env)     | `S3_*` values synced by the pipeline after each apply                                |
+| Bucket, region, Infisical project   | GitHub variables         | Non-sensitive wiring, editable in one place                                          |
+| Project name, scaling, image        | Committed tfvars         | Reviewable configuration, no secrets                                                 |
 
 ## After the bootstrap
 
@@ -378,6 +380,15 @@ Auth by default. To add one to an existing repo later: add a `<env>.tfvars`
 the repo root automatically), an Infisical environment with the same slug, and
 a chained job in `terraform-apply.yml`.
 
+**Can I extend the generated repo with my own Terraform?**
+Yes, and additions never edit generated files: drop a new `.tf` file at the
+repo root (Terraform merges all root files), put per-env values in the
+existing tfvars, and expose an output named `infisical_secrets_<name>` if your
+module produces secrets the app should read — the pipeline collects every
+output matching that prefix and syncs it to Infisical automatically. The
+committed `.keel/manifest.json` records the contract version your repo was
+generated with.
+
 **Can I store files, not just rows?**
 Yes, opt in with `--object-storage` (or answer yes interactively). Each
 environment gets its own Object Storage bucket and a dedicated credential; the

package/dist/bootstrap/infisical.js

@@ -1,5 +1,5 @@
 import { randomBytes } from 'node:crypto';
-import { S3_SECRET_KEYS } from '../contracts.js';
+import { BASE_SYNCED_KEYS, BASIC_AUTH_SECRET_KEYS, S3_SECRET_KEYS } from '../contracts.js';
 export class InfisicalError extends Error {
     field;
     constructor(message, field = 'credentials') {
@@ -130,10 +130,13 @@ export async function bootstrapInfisical(answers) {
     const placeholder = 'placeholder-updated-by-pipeline-after-first-apply';
     for (const env of answers.environments) {
         if (env.basicAuth) {
-            await seedSecret(host, token, project.id, env.slug, 'BASIC_AUTH_USER', env.slug);
-            await seedSecret(host, token, project.id, env.slug, 'BASIC_AUTH_PASSWORD', randomBytes(18).toString('base64url'));
+            const [userKey, passwordKey] = BASIC_AUTH_SECRET_KEYS;
+            await seedSecret(host, token, project.id, env.slug, userKey, env.slug);
+            await seedSecret(host, token, project.id, env.slug, passwordKey, randomBytes(18).toString('base64url'));
+        }
+        for (const key of BASE_SYNCED_KEYS) {
+            await seedSecret(host, token, project.id, env.slug, key, placeholder);
         }
-        await seedSecret(host, token, project.id, env.slug, 'DATABASE_URL', placeholder);
         if (answers.objectStorage) {
             for (const key of S3_SECRET_KEYS) {
                 await seedSecret(host, token, project.id, env.slug, key, placeholder);

package/dist/config.js

@@ -189,6 +189,11 @@ export function resolveEnvironments(slugs, basicAuth, overrides) {
     return slugs.map((slug) => {
         const def = ENV_DEFAULTS[slug];
         const ov = overrides[slug] ?? {};
+        const minScale = validateScale(ov.minScale ?? def.minScale, `${slug} min scale`);
+        const maxScale = validateScale(ov.maxScale ?? def.maxScale, `${slug} max scale`);
+        if (minScale > maxScale) {
+            throw new ConfigError(`Invalid ${slug} scaling: min scale (${minScale}) cannot exceed max scale (${maxScale}).`);
+        }
         return {
             slug,
             displayName: def.displayName,
@@ -197,8 +202,8 @@ export function resolveEnvironments(slugs, basicAuth, overrides) {
             gated: def.gated,
             // Basic Auth is a non-production safety net; production is never gated by it.
             basicAuth: def.production ? false : basicAuth,
-            minScale: validateScale(ov.minScale ?? def.minScale, `${slug} min scale`),
-            maxScale: validateScale(ov.maxScale ?? def.maxScale, `${slug} max scale`),
+            minScale,
+            maxScale,
         };
     });
 }

package/dist/contracts.js

@@ -15,8 +15,42 @@
 export function planStatusCheckContext(environment) {
     return `plan (${environment})`;
 }
-/** Root Terraform output consumed by .github/scripts/sync-secrets.sh. */
+/**
+ * Version of the docking contract between keel and the generated repository
+ * (output naming, manifest schema, tfvars conventions). Recorded in the
+ * committed .keel/manifest.json; future tooling that extends a generated
+ * repo checks it before touching anything.
+ */
+export const CONTRACT_VERSION = 1;
+/** Base Terraform output consumed by .github/scripts/sync-secrets.sh. */
 export const INFISICAL_SECRETS_OUTPUT = 'infisical_secrets';
+/**
+ * Regex (verbatim in sync-secrets.sh) matching the base output plus any
+ * module-contributed "infisical_secrets_<name>" output. A module added to a
+ * generated repo exposes its own map under that name and the pipeline syncs
+ * it — no edit to outputs.tf needed (file-additive extension).
+ */
+export const INFISICAL_SECRETS_OUTPUT_PATTERN = '^infisical_secrets(_[a-z0-9_]+)?$';
+/**
+ * Keys always present in the synced map: seeded as placeholders by the CLI,
+ * produced by the root outputs, overwritten by the pipeline after each apply.
+ */
+export const BASE_SYNCED_KEYS = ['DATABASE_URL', 'APP_URL'];
+/**
+ * Basic Auth crosses the boundary in three places: the CLI seeds these two
+ * secrets in Infisical (non-production), the generated app_stack injects the
+ * flag below, and the user's app enforces it. [user, password] in this order.
+ */
+export const BASIC_AUTH_SECRET_KEYS = ['BASIC_AUTH_USER', 'BASIC_AUTH_PASSWORD'];
+export const BASIC_AUTH_FLAG = 'BASIC_AUTH_ENABLED';
+/**
+ * Naming convention for per-environment resources (registry, namespaces,
+ * database, buckets…): mirrored by `local.name` in the app_stack template,
+ * which contracts.test.ts pins against this function.
+ */
+export function resourceName(projectName, envSlug) {
+    return `${projectName}-${envSlug}`;
+}
 /**
  * Object Storage coordinates: seeded as placeholders by the CLI, produced by
  * the infisical_secrets output, synced to Infisical by the pipeline.

package/dist/generate.js

@@ -2,9 +2,33 @@ import { spawnSync } from 'node:child_process';
 import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { CONTRACT_VERSION } from './contracts.js';
+import { toolVersion } from './meta.js';
 import { STATE_FILE } from './state.js';
 export class GenerateError extends Error {
 }
+/**
+ * Machine-readable record of how the repository was generated. Unlike the
+ * git-ignored .keel.json resume file, the manifest is committed: future
+ * tooling that extends a generated repo (e.g. `keel add`) reads it from a
+ * fresh clone to know which contract it is docking onto.
+ */
+export const MANIFEST_FILE = '.keel/manifest.json';
+function renderManifest(answers) {
+    const manifest = {
+        keelVersion: toolVersion(),
+        contractVersion: CONTRACT_VERSION,
+        generatedAt: new Date().toISOString(),
+        projectName: answers.projectName,
+        region: answers.region,
+        environments: answers.environments.map((e) => e.slug),
+        options: {
+            objectStorage: answers.objectStorage,
+            basicAuth: answers.basicAuth,
+        },
+    };
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}
 /** Files whose real name would confuse npm packaging are stored renamed. */
 const RENAMES = {
     _gitignore: '.gitignore',
@@ -127,6 +151,10 @@ export function generateProject(answers, options = {}) {
     const applyDestRel = '.github/workflows/terraform-apply.yml';
     writeFileSync(join(target, applyDestRel), renderApplyWorkflow(source, answers, tokens));
     written.push(applyDestRel);
+    // Committed manifest recording generator version, contract and options.
+    mkdirSync(join(target, '.keel'), { recursive: true });
+    writeFileSync(join(target, MANIFEST_FILE), renderManifest(answers));
+    written.push(MANIFEST_FILE);
     // backend.hcl (git-ignored) so local terraform runs work out of the box.
     cpSync(join(target, 'backend.hcl.example'), join(target, 'backend.hcl'));
     if (options.git !== false) {

package/dist/index.js

@@ -2,10 +2,10 @@
 import { readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { parseArgs } from 'node:util';
-import { fileURLToPath } from 'node:url';
 import { ConfigError, finalizeAnswers, fromEnv, mergeAnswers, missingRequired, parseEnvironments, } from './config.js';
-import { CI_SECRET_NAMES, CI_VARIABLE_NAMES } from './contracts.js';
+import { CI_SECRET_NAMES, CI_VARIABLE_NAMES, resourceName } from './contracts.js';
 import { generateProject, GenerateError } from './generate.js';
+import { toolVersion } from './meta.js';
 import { confirmSummary, fillMissing } from './prompts.js';
 import { isDone, loadState, markDone, STATE_FILE, stepData, } from './state.js';
 import { cancel, intro, log, outro, renderNextSteps, renderSummary, withSpinner } from './ui.js';
@@ -211,15 +211,6 @@ function normalizeConfigFile(raw) {
         scaling: (obj.scaling ?? {}),
     });
 }
-function toolVersion() {
-    try {
-        const pkg = JSON.parse(readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'));
-        return pkg.version;
-    }
-    catch {
-        return '0.0.0';
-    }
-}
 function checkEnvironment() {
     const [major] = process.versions.node.split('.');
     if (Number(major) < 18) {
@@ -239,7 +230,7 @@ function printDryRunPlan(answers) {
         `  - Infisical: ${answers.infisical.projectId
             ? `reuse project ${answers.infisical.projectId}`
             : `create/reuse project "${answers.infisical.projectName}"`}, environments ${envList},`,
-        '    seed BASIC_AUTH_USER/BASIC_AUTH_PASSWORD (non-prod) and DATABASE_URL placeholders' +
+        '    seed BASIC_AUTH_USER/BASIC_AUTH_PASSWORD (non-prod) and DATABASE_URL/APP_URL placeholders' +
             (answers.objectStorage ? ' and S3_* placeholders' : ''),
         `  - GitHub: create ${answers.github.repoPrivate ? 'private' : 'public'} repo "${answers.github.repoName}", push, set ${CI_SECRET_NAMES.length} encrypted secrets,`,
         `    ${CI_VARIABLE_NAMES.length} variables, ${ghEnvs} environments and main branch protection`,
@@ -389,7 +380,7 @@ async function main() {
         return;
     }
     const repoUrl = await runBootstrap(answers, state, { preValidated: interactive });
-    outro(renderNextSteps(answers, repoUrl, `rg.${answers.region}.scw.cloud/${answers.projectName}-${answers.environments[0].slug}`));
+    outro(renderNextSteps(answers, repoUrl, `rg.${answers.region}.scw.cloud/${resourceName(answers.projectName, answers.environments[0].slug)}`));
 }
 main().catch((error) => {
     if (error instanceof ConfigError || error instanceof GenerateError) {

package/dist/meta.js

@@ -0,0 +1,12 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+/** Version of the running keel package (dist/ sits next to package.json). */
+export function toolVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'));
+        return pkg.version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gambi97/keel-cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "One command from zero to a production-shaped serverless infrastructure on Scaleway (Terraform + GitHub Actions + Infisical). Only Node required.",
   "keywords": [
     "keel",

package/templates/.github/scripts/sync-secrets.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Pushes the secrets Terraform produced to Infisical, so the application reads
-# them at runtime: always DATABASE_URL (dedicated IAM credential included), plus
-# the S3_* Object Storage coordinates when that feature is enabled.
+# them at runtime: always DATABASE_URL and APP_URL, plus the S3_* Object
+# Storage coordinates when that feature is enabled.
 # Usage: sync-secrets.sh <environment>
 # Expects: INFISICAL_HOST, INFISICAL_CLIENT_ID, INFISICAL_CLIENT_SECRET,
 #          INFISICAL_PROJECT_ID in the environment; terraform init already run.
@@ -9,8 +9,17 @@ set -euo pipefail
 
 ENVIRONMENT="${1:?usage: sync-secrets.sh <environment>}"
 
-SECRETS_JSON="$(terraform output -json infisical_secrets)"
-if [ -z "$SECRETS_JSON" ] || [ "$SECRETS_JSON" = "null" ] || [ "$SECRETS_JSON" = "{}" ]; then
+# Collect the base "infisical_secrets" output plus any module-contributed
+# "infisical_secrets_<name>" output, merged into one map. A module added to
+# this repo contributes secrets by exposing its own output under that prefix:
+# nothing here or in outputs.tf needs editing.
+SECRETS_JSON="$(terraform output -json | jq -c '
+  [to_entries[]
+    | select(.key | test("^infisical_secrets(_[a-z0-9_]+)?$"))
+    | select(.value.value | type == "object")
+    | .value.value]
+  | add // {}')"
+if [ "$SECRETS_JSON" = "{}" ] || [ "$SECRETS_JSON" = "null" ]; then
   echo "No secrets to sync."
   exit 0
 fi

package/templates/README.md

@@ -49,8 +49,8 @@ merge/push main   -> apply each environment in order; any gated environment (pro
 - After each apply, the pipeline syncs the secrets Terraform produced to
   Infisical for that environment: a ready-to-use Postgres `DATABASE_URL`
   (whose credential is a dedicated IAM application that can only read/write
-  the database, not your main API key) and, when Object Storage is enabled,
-  the `S3_*` coordinates.
+  the database, not your main API key), the app's public `APP_URL` and, when
+  Object Storage is enabled, the `S3_*` coordinates.
 - State is locked during applies (S3-native locking, `use_lockfile`), so
   concurrent runs cannot corrupt it.
 - A scheduled **drift detection** workflow (Monday 06:00 UTC, or manual via
@@ -84,6 +84,7 @@ merge/push main   -> apply each environment in order; any gated environment (pro
    | Variable | Where | Notes |
    |---|---|---|
    | `DATABASE_URL` | every environment | Complete connection string, auto-updated by the pipeline after each apply. No action needed |
+   | `APP_URL` | every environment | Public URL of the app, auto-updated by the pipeline once a container exists. Useful for links, OAuth callbacks, webhooks |
    | `BASIC_AUTH_USER` / `BASIC_AUTH_PASSWORD` | non-production | The app must enforce these when `BASIC_AUTH_ENABLED=true` |
    | `S3_BUCKET` / `S3_ENDPOINT` / `S3_REGION` / `S3_ACCESS_KEY` / `S3_SECRET_KEY` | every environment (if Object Storage enabled) | Auto-updated by the pipeline after each apply |
 
@@ -125,6 +126,26 @@ environment enables it is the `enable_basic_auth` flag in its `<env>.tfvars`.
   generated `.terraform.lock.hcl` so CI resolves the exact same provider
   builds on every run.
 
+## Extending this repo with your own module
+
+The layout is designed so additions never edit generated files:
+
+1. Put your Terraform in a **new file at the repo root** (e.g. `jobs.tf`,
+   optionally with a `modules/<name>/` directory) — Terraform merges all root
+   `.tf` files automatically. Reach the app stack only through its outputs,
+   never into its internals.
+2. Per-environment configuration goes into the existing `<env>.tfvars` files
+   (append new variables; declare them in your own `.tf` file).
+3. If your module produces secrets the app should read, expose them as an
+   output named `infisical_secrets_<name>` (a map of string, marked
+   `sensitive`). The pipeline collects every output matching that prefix and
+   syncs it to Infisical after each apply — no edit to `outputs.tf` or the
+   workflows required.
+
+`.keel/manifest.json` (committed) records the keel version, the contract
+version and the generation options this repo was created with, so tooling and
+future you know exactly what it is built on.
+
 ## Running Terraform locally (optional)
 
 CI is the source of truth, but plans can be run locally (replace `<env>` with

package/templates/_gitignore

@@ -19,7 +19,7 @@ override.tf.json
 .env
 .env.*
 
-# Bootstrap resume file
+# Bootstrap resume file (machine-local; .keel/manifest.json IS committed)
 .keel.json
 
 # Editors / OS

package/templates/modules/app_stack/main.tf

@@ -1,4 +1,7 @@
 locals {
+  # <project>-<env>: the naming convention every per-environment resource
+  # shares with the CLI (which builds registry hints from it) — do not change
+  # one side without the other; contracts.test.ts pins them together.
   name = "${var.project_name}-${var.environment}"
 }
 

package/templates/outputs.tf

@@ -24,13 +24,22 @@ output "object_bucket_name" {
   value       = module.app_stack.object_bucket_name
 }
 
-# The complete set of secrets the pipeline pushes to Infisical after each apply:
-# always DATABASE_URL, plus the S3_* coordinates when Object Storage is enabled.
+# The secrets the pipeline pushes to Infisical after each apply: always
+# DATABASE_URL and APP_URL, plus the S3_* coordinates when Object Storage is
+# enabled. A module added to this repo can contribute its own secrets by
+# exposing an output named "infisical_secrets_<name>" (a map of string): the
+# pipeline collects every output matching that prefix, so extending never
+# requires editing this file.
 output "infisical_secrets" {
   description = "Secrets synced to Infisical after each apply."
   sensitive   = true
   value = merge(
-    { DATABASE_URL = module.app_stack.database_url },
+    {
+      DATABASE_URL = module.app_stack.database_url
+      # Public URL of the app; null until a container image is deployed (the
+      # pipeline skips null values and syncs it on the first apply after).
+      APP_URL = module.app_stack.container_url
+    },
     var.enable_object_storage ? {
       S3_BUCKET     = module.app_stack.object_bucket_name
       S3_ENDPOINT   = module.app_stack.object_bucket_endpoint

package/templates/variables.tf

@@ -46,6 +46,11 @@ variable "min_scale" {
   description = "Minimum number of container instances."
   type        = number
   default     = 0
+
+  validation {
+    condition     = var.min_scale <= var.max_scale
+    error_message = "min_scale cannot exceed max_scale."
+  }
 }
 
 variable "max_scale" {