razzou-harness 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 The notable changes in each release of razzou-harness. Before 1.0, a new minor version
 may change how a project is set up, and its notes say how.
 
+## 0.4.3 (2026-11-08)
+
+**Upgrading from 0.4.2:** install the new version, then rebuild the agents' image with
+`harness doctor --build-images`: its tag follows the harness's version.
+
+- **`harness setup` writes the Terraform scaffold** your bootstrap expects, when you
+  answer its AWS questions, and on any later run: a partial `backend "s3" {}` block in
+  `iac/versions.tf`, `iac/backend-configs/staging.hcl` with the state bucket and the
+  project's key, read from the GitHub variables the bootstrap set, `iac/env/staging.tfvars`
+  with the account, the region and the repository's ids, and the variables and provider
+  they feed. Only missing files are written, a backend block of the project's own is
+  kept, and the files are committed with setup's others. The backend config sets no
+  encryption, so the bucket's default, its KMS key, applies. Until now the doctor
+  required these files and nothing wrote them.
+
 ## 0.4.2 (2026-11-08)
 
 **Upgrading from 0.4.1:** upgrade OpenShell to 0.1.7 first, from its Debian package

package/README.md

@@ -140,7 +140,8 @@ gateway key. In order, it logs you in to `gh`; creates
 the repository on GitHub if the project has no remote; creates the App from its
 manifest when this machine has none, and waits for you to install it; writes the
 harness's files; asks the questions and writes `harness/config.json`, with the
-`staging` environment and the variables on GitHub for AWS; commits the files it wrote,
+`staging` environment and the variables on GitHub for AWS, and the Terraform scaffold in
+`iac/` that your bootstrap expects; commits the files it wrote,
 and only those, with your git once you agree, and pushes them when you are on `main`;
 runs `harness doctor` and fixes what it can (starts the OpenShell gateway, builds the
 agents' image, imports the Claude profile and creates the provider with your token,
@@ -433,7 +434,7 @@ through an `Arch:` pull request, or a commit of your own on `main`.
 
 ```json
 {
-  "harnessVersion": "0.4.2",
+  "harnessVersion": "0.4.3",
   "project": { "name": "shop", "repo": "<org>/shop", "bot": "<org>-harness[bot]" },
   "roles": {
     "architect": { "model": "claude-opus-5-5", "effort": "max" },
@@ -554,7 +555,8 @@ and Terraform applies only in CI, after you merge.
    `harness-*` roles and to the gateway user, so your project's own Terraform can't widen
    the agents' access.
 
-**Then, in the project:**
+**Then, in the project** (`harness setup` does steps 1 to 3 when you answer its AWS
+questions):
 1. In `harness/config.json`, add `aws` and `terraform`:
 
    ```json
@@ -570,6 +572,13 @@ and Terraform applies only in CI, after you merge.
    ([NVIDIA/OpenShell#5375](https://github.com/NVIDIA/OpenShell/issues/5375)). Keep the `terraform` paths
    as they are: the CI workflow uses the same ones. `harness github-setup` then requires
    `tf-plan` as well.
+
+   In `iac/`, the Terraform scaffold: a partial `backend "s3" {}` block, the backend
+   config with the state bucket, the project's key, the region and `use_lockfile = true`,
+   and the variables file. `harness setup` writes whatever of it is missing, from the
+   variables your bootstrap set on GitHub. Its backend config sets no encryption, so the
+   bucket's default, your KMS key, applies: `encrypt = true` without `kms_key_id` would
+   replace it with SSE-S3.
 2. Set the repository variables the workflow reads: `AWS_REGION_STAGING`,
    `AWS_ROLE_PLAN_ARN_STAGING` and `AWS_ROLE_APPLY_ARN_STAGING`.
 3. `harness doctor` creates the OpenShell AWS provider: it asks for the view role's ARN,

package/dist/setup/doctor.js

@@ -218,7 +218,7 @@ async function project(options, config, report) {
     if (config.terraform) {
         const tf = config.terraform;
         for (const file of [tf.backendConfig, tf.varFile]) {
-            report(existsSync(join(options.projectDir, tf.dir, file)) ? ok('Terraform', `${tf.dir}/${file}`) : fail('Terraform', `${tf.dir}/${file} is missing`, 'see harness/config.json under terraform'));
+            report(existsSync(join(options.projectDir, tf.dir, file)) ? ok('Terraform', `${tf.dir}/${file}`) : fail('Terraform', `${tf.dir}/${file} is missing`, '`harness setup` writes the missing Terraform scaffold, or see the README\'s AWS section'));
         }
     }
 }

package/dist/setup/setup.js

@@ -7,6 +7,7 @@ import { applyRepositoryRules, checkApp, createApp, installCi } from '../github/
 import { run, sha256 } from '../util.js';
 import { doctor, granted } from './doctor.js';
 import { appBot, githubRepo, init } from './init.js';
+import { writeTerraformScaffold } from './terraform.js';
 export function fixFor(check) {
     if (check.status === 'ok' || check.status === 'skip')
         return undefined;
@@ -214,6 +215,7 @@ async function askSettings(options) {
     const written = [];
     let changed = false;
     let viewRole;
+    let account;
     if (!config.aws && /^y/i.test(await ask('Does this project deploy to AWS with Terraform? [y/N] '))) {
         say('The roles come from your bootstrap (see the README\'s AWS section); the key is asked for later, at a hidden prompt.');
         const region = (await ask('AWS region (like eu-west-1): ')).trim();
@@ -231,6 +233,28 @@ async function askSettings(options) {
             const repo = config.project?.repo;
             if (repo)
                 await configureGitHubForAws(options, repo, { region, plan, apply });
+            account = /^arn:aws:iam::(\d{12}):/.exec(view)[1];
+        }
+    }
+    // The Terraform scaffold the bootstrap expects, which the doctor checks: whatever of it is
+    // missing, on this run or a later one. A later run reads the account from the plan role
+    // this one stored on GitHub.
+    if (config.aws?.region && config.terraform) {
+        const repo = config.project?.repo;
+        account ??= /^arn:aws:iam::(\d{12}):/.exec((await githubVariable(repo, 'AWS_ROLE_PLAN_ARN_STAGING')) ?? '')?.[1];
+        if (account) {
+            const layout = { dir: 'iac', backendConfig: 'backend-configs/staging.hcl', varFile: 'env/staging.tfvars', ...config.terraform };
+            // As the schema reads it: `iac`, `./iac` and `iac/` are one folder. Slashes are trimmed by hand: a regex would take quadratic time on a long run of them.
+            let dir = layout.dir;
+            while (dir.startsWith('./') || dir.startsWith('/'))
+                dir = dir.slice(dir.startsWith('./') ? 2 : 1);
+            while (dir.endsWith('/'))
+                dir = dir.slice(0, -1);
+            layout.dir = dir || 'iac';
+            const scaffold = writeTerraformScaffold(projectDir, layout, await terraformFacts(repo, String(config.project?.name ?? 'project'), String(config.aws.region), account));
+            if (scaffold.length > 0)
+                say(`Terraform: wrote ${scaffold.join(', ')}.`);
+            written.push(...scaffold);
         }
     }
     if (changed) {
@@ -254,6 +278,30 @@ async function askSettings(options) {
     }
     return { written, ...(viewRole ? { viewRole } : {}) };
 }
+/**
+ * Where the project's state lives, and its repository's numeric ids: read from GitHub, where
+ * the bootstrap's configure-github.sh set TF_STATE_BUCKET_STAGING and TF_STATE_KEY_STAGING,
+ * or else by the bootstrap's naming, `tf-state-staging-<account>` and
+ * `staging/<repository>/terraform.tfstate`.
+ */
+async function terraformFacts(repo, name, region, account) {
+    const bucket = await githubVariable(repo, 'TF_STATE_BUCKET_STAGING');
+    const key = await githubVariable(repo, 'TF_STATE_KEY_STAGING');
+    const ids = (await ghApi(repo, `repos/${repo}`, '"\\(.owner.id) \\(.id)"'))?.split(' ');
+    return {
+        region,
+        account,
+        bucket: bucket ?? `tf-state-staging-${account}`,
+        key: key ?? `staging/${repo ? repo.split('/')[1] : name}/terraform.tfstate`,
+        ...(repo && ids?.length === 2 ? { github: { repo, ownerId: ids[0], repoId: ids[1] } } : {}),
+    };
+}
+/** What the owner's gh reads at `path`, through `jq`; undefined without a repository, or on any failure. */
+async function ghApi(repo, path, jq) {
+    const result = repo ? await run('gh', ['api', path, '--jq', jq]).catch(() => undefined) : undefined;
+    return result?.code === 0 && result.stdout.trim() ? result.stdout.trim() : undefined;
+}
+const githubVariable = (repo, name) => ghApi(repo, `repos/${repo}/actions/variables/${name}`, '.value');
 /** The staging environment, restricted to main, and the variables the workflow reads, with the owner's gh. */
 async function configureGitHubForAws(options, repo, aws) {
     const gh = async (args, body) => {

package/dist/setup/terraform.js

@@ -0,0 +1,86 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/**
+ * Writes the Terraform scaffold the bootstrap expects in the layout's folder: a partial
+ * `backend "s3"` block in `versions.tf`, the backend config and the variables file, and the
+ * variables and provider those values feed. Only what is missing is written: an existing
+ * file, or a backend block in any of the folder's `.tf` files, is the project's own. The
+ * backend config sets no encryption, so the bucket's default, the bootstrap's KMS key,
+ * applies: `encrypt = true` without `kms_key_id` would replace it with SSE-S3. Every file
+ * is as `terraform fmt` writes it, which CI checks. Returns the paths written, from the
+ * project's root.
+ */
+export function writeTerraformScaffold(projectDir, layout, values) {
+    const { dir } = layout;
+    const written = [];
+    const write = (path, content) => {
+        const file = join(projectDir, dir, path);
+        if (existsSync(file))
+            return false;
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, content);
+        written.push(`${dir}/${path}`);
+        return true;
+    };
+    const folder = join(projectDir, dir);
+    const hasBackend = existsSync(folder)
+        && readdirSync(folder).filter((f) => f.endsWith('.tf')).some((f) => /^\s*backend\s+"/m.test(readFileSync(join(folder, f), 'utf8')));
+    if (!hasBackend) {
+        write('versions.tf', [
+            'terraform {',
+            '  required_version = ">= 1.10"',
+            '',
+            '  required_providers {',
+            '    aws = {',
+            '      source  = "hashicorp/aws"',
+            '      version = "~> 6.65"',
+            '    }',
+            '  }',
+            '',
+            `  # Partial configuration: the values are in ${layout.backendConfig}, for`,
+            `  #   terraform init -backend-config=${layout.backendConfig}`,
+            '  backend "s3" {}',
+            '}',
+            '',
+        ].join('\n'));
+    }
+    write(layout.backendConfig, [
+        ...assignments([['bucket', values.bucket], ['key', values.key], ['region', values.region]]),
+        '',
+        "# No encrypt or kms_key_id: the bucket's default encryption, its KMS key, applies.",
+        '# encrypt = true without kms_key_id would replace it with SSE-S3.',
+        'use_lockfile = true',
+        '',
+    ].join('\n'));
+    const github = values.github;
+    const variables = [
+        ['env', 'staging', 'The environment.'],
+        ['aws_account_id', values.account, 'The AWS account the environment is in.'],
+        ['aws_region', values.region, 'The AWS region the environment is in.'],
+        ...(github ? [
+            ['github_repo', github.repo, 'The GitHub repository, as owner/name.'],
+            ['github_owner_id', github.ownerId, "The repository owner's numeric id, which OIDC trust policies pin."],
+            ['github_repo_id', github.repoId, "The repository's numeric id, which OIDC trust policies pin."],
+        ] : []),
+    ];
+    const tfvars = [
+        ...assignments(variables.slice(0, 3).map(([name, value]) => [name, value])),
+        ...(github ? ['', ...assignments(variables.slice(3).map(([name, value]) => [name, value]))] : []),
+        '',
+    ].join('\n');
+    // The variables follow the values: a tfvars file of the project's own sets its own.
+    if (write(layout.varFile, tfvars)) {
+        write('variables.tf', variables.map(([name, , description]) => [
+            `variable "${name}" {`,
+            ...assignments([['description', description], ['type', 'string']], ['type']).map((line) => `  ${line}`),
+            '}',
+        ].join('\n')).join('\n\n') + '\n');
+        write('providers.tf', ['provider "aws" {', '  region = var.aws_region', '}', ''].join('\n'));
+    }
+    return written;
+}
+/** `name = "value"` lines with their equals signs aligned, as `terraform fmt` aligns them; `bare` names take an expression, unquoted. */
+function assignments(pairs, bare = []) {
+    const width = Math.max(...pairs.map(([name]) => name.length));
+    return pairs.map(([name, value]) => `${name.padEnd(width)} = ${bare.includes(name) ? value : JSON.stringify(value)}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "razzou-harness",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Your AI dev team, with you in charge: sandboxed Claude Code agents design, build and review your project, and you merge.",
   "license": "MIT",
   "author": "razzou",