@empire-builder-kit/nx 1.0.0-rc.4 → 1.0.0-rc.40

package/src/generators/preset/workspace-files-thin-docs.d.ts

@@ -0,0 +1,7 @@
+import { type DeploymentProfile } from '../../repository-policy/index.js';
+export declare function renderThinLifecycleDocumentation(options: {
+    deliveryLane?: 'protected-pair' | 'trunk';
+    productionApprovalMode?: 'promotion-pr' | 'environment-reviewer' | 'trunk-promotion';
+    deploymentProfile: DeploymentProfile;
+    name: string;
+}): Readonly<Record<string, string>>;

package/src/generators/preset/workspace-files-thin-docs.js

@@ -0,0 +1,352 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderThinLifecycleDocumentation = renderThinLifecycleDocumentation;
+const index_js_1 = require("../../repository-policy/index.js");
+const tool_versions_js_1 = require("./tool-versions.js");
+function renderThinLifecycleDocumentation(options) {
+    const stages = (0, index_js_1.activeDeploymentStages)(options.deploymentProfile);
+    const stageList = stages.join(', ');
+    const rehearsalStage = (0, index_js_1.productionRehearsalStage)(options.deploymentProfile);
+    return {
+        'README.md': `# ${options.name}
+
+This repository follows the Empire Builder Kit thin SST paved road. Nx owns
+generation, ordering, identity checks, migrations, smoke tests, and receipts;
+SST 4.17.1 owns application bootstrap, state, locks, previews, deployment,
+refresh, removal, and provider diagnostics.
+
+The committed \`${options.deploymentProfile}\` profile activates: ${stageList}.
+
+For ordinary feature work, run affected tests, typecheck, lint, and ownership
+checks. Run \`pnpm verify\` at a milestone, not before each development edit.
+Configure the exact temporary AWS profile and stage deployment role described
+in \`docs/stage-deployment-authority.md\` before deploying development through
+\`ebk deploy development --profile=<profile> --expectedRoleArn=<role-arn>\`
+(the root \`deploy-local\` target). Do not invoke SST directly.
+
+Standard Slices include a Python infrastructure provisioner: install \`uv\`
+${tool_versions_js_1.WORKSPACE_UV_VERSION} (Python 3.12 or newer) on PATH before \`ebk dev up\` or
+\`ebk deploy\`. Each Standard Slice stops before its SST child starts when
+\`uv --version\` fails; a full \`ebk deploy\` may already have deployed
+Foundation.
+Source-only feature checks do not require it. Slice \`verify\` runs
+\`test-integration\`, which needs a running Docker engine for DynamoDB Local (and
+PostgreSQL when SQL is declared).
+`,
+        'docs/git-workflow.md': `# Protected Git workflow
+
+${options.deliveryLane === 'trunk'
+            ? `Trunk delivery lane: \`main\` is the only protected branch. Ordinary work
+opens a pull request to \`main\` from an up-to-date branch, and every merged
+\`main\` push is a production delivery through the generated Verify and deploy
+workflows. There is no \`develop\` branch, promotion pull request, or sync-back.
+Switch to the protected pair with
+\`pnpm nx g @empire-builder-kit/nx:repository-policy --deliveryLane=protected-pair --apply\`
+followed by the managed upgrade when the team needs a staged promotion.`
+            : `Ordinary work targets \`develop\`; production promotion is an exact reviewed
+\`develop\` to \`main\` merge followed by the managed sync-back.`} Keep the
+generated branch rules, CODEOWNER review, resolved-conversation requirement,
+merge-only history, and read-only default workflow permissions.
+
+The managed \`Deploy\` workflow is the single protected infrastructure path.
+It derives the canonical stage deployment-role ARN from committed account,
+stage, Region-partition, and naming policy; the GitHub environment supplies no
+deployment-role secret. It invokes the same root Nx lifecycle used locally,
+runs migrations and Slice smoke checks after each successful native SST
+deployment, and retains one bounded deployment receipt.
+For isolated profiles, the protected-branch \`Verify\` run calls the reusable
+\`Deploy\` workflow only after acceptance and its immutable candidate succeed.
+The call binds the exact source commit, branch ref, run, and attempt, consumes
+artifacts from that same run, and rechecks the live protected-branch tip before
+AWS authority. A verified history-only sync skips both candidate creation and
+the deployment call. Manual recovery remains an explicit workflow dispatch.
+There is no second deployed-smoke workflow, staging-evidence workflow,
+reliability-read workflow, preview approval artifact, or plan role.
+
+For \`starter\`, GitHub deployment is optional. \`production-isolated\` permits
+local staging, but its protected production promotion requires the candidate
+receipt from a successful managed GitHub staging deployment. \`fully-isolated\`
+uses GitHub for staging and production. Isolated production restores the exact
+candidate recorded by the successful staging deployment.
+${options.deliveryLane === 'trunk'
+            ? `In the trunk lane every merged \`main\` push calls the deploy workflow for
+production; development stays a local stage.`
+            : `When \`starter\` uses its optional manual workflow, \`develop\` routes to
+development and \`main\` routes to production; starter has no automatic caller.`}
+${options.productionApprovalMode === 'trunk-promotion'
+            ? `Trunk promotion (\`productionApproval.mode: trunk-promotion\`): a successful
+staging lifecycle on \`develop\` continues in the same run. \`promote-production\`
+binds that run's staging deployment receipt and release candidate and promotes
+the reviewed OCI indexes into production, \`execute-production\` deploys
+production from the same candidate under the production environment, and
+\`record-main\` fast-forwards \`main\` to the deployed commit with the production
+environment secret \`EBK_RECORD_MAIN_TOKEN\`, refusing any non-fast-forward
+update. \`main\` keeps deletion, non-fast-forward, and status-check rules but no
+pull-request rule; the develop ruleset keeps CODEOWNER review. A \`main\` push
+verifies only and there is no sync-back. Switch back with
+\`pnpm nx g @empire-builder-kit/nx:repository-policy --productionApprovalMode=promotion-pr --apply\`
+followed by the managed upgrade and a GitHub bootstrap apply.
+`
+            : ''}Every protected job checks out an immutable commit, validates managed source,
+and assumes the derived stage role through the matching GitHub environment.
+The reusable Verify caller delegates job-scoped \`id-token: write\`; each
+credential-bearing job proves both the configured canonical ARN and terminal
+STS assumed-role caller immediately before OCI or lifecycle mutation.
+
+Run GitHub bootstrap in report mode first to obtain the repository's canonical
+slug and immutable owner/repository IDs. It configures repository and environment
+policy but never creates AWS credentials, secrets, or roles. For an existing
+repository, keep its current OIDC subject active while you render and apply the
+stage AWS trust for the reported immutable subject, then read back and simulate
+that effective trust. Only after AWS accepts the immutable subject should you
+rerun GitHub bootstrap with \`--apply\` and the exact
+\`--immutableOidcTrustAcknowledgement=aws-trust-ready:<repositoryIdentity.subjectPrefix>\`
+reported by the same inspection. A missing, wrong, or stale acknowledgement
+blocks the subject cutover before any GitHub setting is changed.
+This AWS-trust-first order prevents protected deployment from being stranded.
+Place the exact account and Region in their protected stage environment.
+Isolated production additionally keeps its exact staging promotion-pull role
+secret; do not add repository-scope fallbacks.
+`,
+        'docs/repository-operating-policy.md': `# Repository Operating Policy
+
+## Production capacity
+
+Foundation provisions Aurora only when SQL is declared. DynamoDB remains the framework core.
+Aurora has three capacity profiles, independent of deployment topology:
+- \`cost-optimized\`: 0–2 ACUs, five-minute idle auto-pause; default for all new deployment profiles.
+- \`balanced\`: 0.5–4 ACUs, always warm.
+- \`standard\`: 2–16 ACUs, always warm.
+
+Existing explicit capacity choices survive upgrades. Provisioned production Aurora
+retains 30-day backups, deletion protection and encryption in all three profiles.
+Undeclared SQL does not provision Aurora or SQL-only networking.
+Pause can delay first requests (typically 15 seconds, sometimes 30 seconds or
+longer); open connections or polling can prevent it. Storage/NAT still cost money.
+Validate cold-resume retries, migration timeouts, and the shared capacity ceiling.
+Choose balanced when measured cold-resume latency is unacceptable; choose standard
+when measured capacity and concurrency justify the larger warm range. Capacity
+selection never changes background-work cadence or an explicit maintenance pause.
+
+Existing warm \`cost-optimized\` users must use the new generator to report
+\`pnpm nx g @empire-builder-kit/nx:repository-policy --profile=balanced\`, then
+repeat with \`--apply\` before managed upgrade or deployment. This preserves
+0.5–4 ACUs. After upgrade, deliberately select \`--profile=cost-optimized --apply\`
+only to accept scale-to-zero. These commands change policy, not AWS resources.
+
+The committed \`ebk.repository-policy.json\` selects the
+\`${options.deploymentProfile}\` deployment profile and its active stages:
+${stageList}. Inactive stages are rejected by planning, deployment, refresh,
+removal, unlock, discovery, and secret resolution.
+
+## Native lifecycle
+
+Use \`ebk deploy development --profile=<profile> --expectedRoleArn=<role-arn>\`.
+Add Slice names, for example \`ebk deploy development billing\` with the same
+authority options, for focused deployment after Foundation. Other Slices are
+not redeployed; required peers must already exist. Omit Slice names for the
+complete stage. Explicit selection is local-only and its \`selectedSlices\`
+receipt is not full-stage acceptance or a protected affected-deployment baseline.
+\`ebk deploy --help\` lists options; it preserves native TTY/output and does not
+accept arbitrary Nx/SST flags or a noninteractive confirmation.
+
+The root \`${options.name}:deploy-local\` target orders Foundation before every
+eligible Product Slice. Each project runs its public Nx \`deploy\` target, which
+uses pinned native \`sst deploy\`; successful Slice infrastructure is followed
+by its governed migration and smoke checks. Native stdout and stderr are
+streamed unchanged. The first failed child ends the invocation and accepted
+deployment evidence is not written.
+
+\`infrastructure-plan\` is an optional advisory pass-through to native
+\`sst diff\`. It is never replayed and never authorizes mutation. Refresh,
+remove, and unlock are explicit per-project Nx operations using native SST.
+Every local SST-bearing operation derives the exact stage deployment role from
+committed policy and gives SST an invocation-private temporary profile rather
+than the operator's Identity Center profile chain.
+
+Governed AWS infrastructure planning and mutation are supported on macOS,
+Linux, and WSL2. Native Windows can run local verification, but native-Windows
+task Fleet (\`ebk dev\`) is not validated in this prerelease; use WSL2 or a
+macOS/Linux host for Fleet development and for \`deploy-local\`,
+\`infrastructure-plan\`, \`refresh\`, \`remove\`, and \`unlock\`. Generated
+protected GitHub AWS jobs continue to run on Ubuntu.
+
+Development may deploy a dirty working tree without a prompt. Its receipt binds
+the exact HEAD and working-tree digest. Local staging requires a clean commit
+and the exact TTY acknowledgement
+\`approve:deploy:staging:<source-commit>\`. Starter production requires a clean
+commit, a real TTY, and
+\`deploy:production:<account>:<region>:<source-commit>\`.
+
+GitHub deploys immutable commits through one canonical stage-scoped OIDC role
+whose ARN is derived from committed policy. The
+starter workflow is optional; isolated profiles require GitHub for the stages
+declared by their profile. Direct user SST invocation is outside the supported
+paved road.
+
+## AWS authority
+
+Each active stage has one stable deployment role and one runtime permission
+boundary. SST/Pulumi creates workload roles inside the application stack; a
+Pulumi transform applies the exact stage path and boundary. Authority is not
+candidate-bound. See \`stage-deployment-authority.md\`.
+
+The deployment role is a temporary bounded infrastructure administrator. IAM
+cannot inspect the initial trust document on \`CreateRole\`; reviewed generated
+source is therefore the create-time trust control, while later trust-policy
+mutation remains denied. EBK does not claim a postdeployment trust attestor. In
+commercial AWS, CloudFront, CloudFront-scope WAF, edge WAF log delivery, and
+edge ACM use the us-east-1 control plane. CloudWatch Logs cannot scope the
+generated WAF \`PutResourcePolicy\` payload through IAM; reviewed generated
+source and the edge Region are its controls. This prerelease does not claim Router edge support in noncommercial
+partitions: CloudFront is unavailable in GovCloud, and the China-partition edge
+control plane is not yet proven.
+
+Stages that share one AWS account retain separate application resources, data,
+runtime roles, secrets, and discovery, but their native SST deployment roles
+are not a hard IAM boundary from each other. The deployment role must reconcile
+SST's account-shared bootstrap state and assets; tag and name denies are defense
+in depth. Select \`production-isolated\` when production needs an AWS-enforced
+deployment blast-radius boundary from nonproduction.
+
+Native SST initializes a clean account on first deployment. EBK does not run a
+pre-bootstrap state command or require a bootstrap record before SST can create
+it. Post-deployment evidence may attest the native bootstrap resources.
+`,
+        'packages/foundation/README.md': `# Standard Foundation
+
+Foundation owns shared Router/WAF, Cognito, events, observability, and
+configuration resources for each active canonical stage. It provisions Aurora
+only when SQL is declared; network and container-compute resources depend on
+declared workloads. The \`${options.deploymentProfile}\` profile activates:
+${stageList}.
+
+Deploy it through the workspace root \`deploy-local\` target or the protected
+GitHub workflow. Nx always orders Foundation before Product Slices, while
+pinned SST owns native planning, state, locking, and deployment. Do not invoke
+SST directly.
+
+Before a nonproduction deployment, add the operator/probe CIDRs required by the
+stage's \`security/router-waf.json\` entry. Production remains public by default
+behind managed rules and rate limiting and requires its blocking rehearsal.
+The resolved ${rehearsalStage} stage is rehearsed with
+\`pnpm nx run foundation:router-waf-rehearsal -- --probeUrl=https://<router>/<slice>/api/health --profile=<temporary-profile>\`.
+`,
+        'packages/foundation/docs/runbooks.md': `# Foundation lifecycle runbook
+
+## Local deployment
+
+Use temporary IAM Identity Center credentials and the stable stage deployment
+role. Development accepts a dirty tree and requires no acknowledgement:
+
+\`ebk deploy development --profile=<profile> --expectedRoleArn=<role-arn>\`
+
+Local staging, when active, requires a clean commit and an interactive
+\`approve:deploy:staging:<source-commit>\` response. Starter production requires
+a clean commit and one exact response entered at the real terminal prompt:
+
+\`deploy:production:<account>:<region>:<source-commit>\`
+
+The internal adapter converts the selected Identity Center chain into one
+invocation-private temporary profile, verifies the exact caller, and removes it
+on every exit path. Native SST diagnostics are not normalized or hidden.
+
+## Advisory planning and recovery
+
+Run \`<project>:infrastructure-plan\` for an advisory native diff when useful.
+The diff is not a transaction token. Use the explicit \`refresh\`, \`unlock\`,
+or \`remove\` Nx target for recovery. Refresh and removal never continue into a
+deployment. Development recovery requires no prompt. Local staging or
+production recovery requires a clean commit and the exact interactive
+\`approve:<action>:<stage>:<source-commit>\` response. The executor derives the
+committed stage role, refreshes its invocation-private temporary credentials
+immediately before SST, and removes them on every exit. A failed child stops
+immediately.
+
+After all Slice registrations are absent, \`foundation:remove\` runs native
+SST removal directly, without a separate refresh or local retry checkpoint.
+Temporary smoke admission uses a separate, normally empty Cloud Control IP set;
+the baseline allowlist identities and addresses remain untouched. Its AWS service
+handler resolves the current WAF lock token during deletion. A failed or
+interrupted removal remains failed. Resolve its native diagnostic and any lock
+through the governed unlock target, then retry the same remove target, including
+from a fresh checkout. Ownership, caller and production removal safeguards run
+on every invocation. Refresh stays separate and never continues into removal or
+deployment; do not bypass its diagnostics, edit state, or use deprecated SST
+components.
+
+For an older deployment whose smoke helper edited the baseline IP set, reconcile
+that existing provider state with an explicit governed refresh while Foundation
+is intact. The new smoke set does not retroactively repair old lock tokens.
+Partially removed old stacks require an evidence-backed recovery assessment;
+do not redeploy a maintenance-held stage merely to apply this upgrade.
+
+## Router WAF rehearsal
+
+${options.deploymentProfile === 'starter'
+            ? ''
+            : `Isolated profiles rehearse through the managed \`Deploy\` dispatch: with both
+\`security/router-waf-live-evidence.json\` and
+\`security/router-waf-blocking-rehearsal.json\` at their pending seeds on
+\`develop\`, dispatch \`Deploy\` with \`action: rehearse\` and \`probe_url\` set to
+the staging Router health URL. The \`rehearse\` job assumes the staging
+deployment role, performs the non-allowlisted probe before the runner is
+admitted, performs the managed-rule probe and the rate rehearsal inside the
+same temporary allowlist admission that private smoke uses, proves the
+admission removed, retains the sealed files as a run artifact, and opens a
+pull request to \`develop\` carrying them. The \`Verify\` caller job carries
+\`contents: write\` and \`pull-requests: write\` only as the ceiling that
+GitHub validates nested jobs against; every nested job keeps its own
+least-privilege permissions. Merging that pull request satisfies
+the production Router WAF gate for the exact policy digest. Any policy change,
+including an allowlist edit, changes the digest and requires a new rehearsal
+after resetting both seeds. The manual path below remains for operators who
+rehearse from an allowlisted address.
+
+`}Count-mode tuning is optional. Restore ${rehearsalStage} to blocking mode,
+record the bounded allowlist and managed-rule probe results in
+\`security/router-waf-live-evidence.json\`, then run:
+
+\`pnpm nx run foundation:router-waf-rehearsal -- --probeUrl=https://<router>/<slice>/api/health --profile=<temporary-profile>\`
+
+The target derives stage, account, Region, and deployment role from the
+committed repository policy. Retained evidence must name that exact account,
+Region, deployment-role ARN, workspace, and deterministic WAF contract digest;
+the 40- or 64-character source commit remains in the evidence digest. Before
+traffic the target verifies the caller, the exact enabled CloudFront
+non-staging distribution and Web ACL attachment, their exact identity tags, the
+full ordered generated rule/IP-set/logging inventory, metrics/sampling, and the
+EBK policy/stage/workspace/ownership tags, then requires a successful health GET.
+The managed-rule and nonallowlisted operator records must first correlate by
+marker, method, path, and time to exact sampled BLOCK requests and owning rules.
+The public rate threshold is bounded from 100 through
+2,159; the default remains 2,000. The target uses concurrency 16 for a bounded
+burst and reserves 40 five-second follow-ups for AWS WAF's delayed evaluation.
+It sends at most 2,199 rate-probe requests so the baseline GET keeps the whole
+invocation at or below 2,200 HTTP requests, and never treats an upstream HTTP 429 as WAF
+proof. The receipt seals only after HTTP 403 correlates to the exact nonce- and
+sequence-marked \`GET /<slice>/api/health\` request in an exact \`RateLimitPerIP\`
+\`BLOCK\` sample and the same-minute \`AWS/WAFV2\` \`BlockedRequests\` metric;
+retained evidence contains only the marker digest. Run this rate probe last:
+AWS WAF can continue blocking the source IP for several minutes. The sealed
+receipt binds the derived account and Region.
+
+## Production safeguards
+
+Production keeps WAF blocking rehearsal and application smoke checks. When SQL
+is declared, production also keeps the committed Aurora capacity profile,
+30-day backup retention, deletion protection, and migration preflight. Any
+change to these controls must be a committed policy change and must remain
+permitted by the stage authority's explicit guardrails. AWS exposes SNS topic
+and SQS queue policy updates through the same Set*Attributes actions required
+during native creation and provides no
+attribute-name IAM condition. The stable stage role therefore contains those
+calls by exact account, Region, and generated stage-name pattern; hard stage
+separation requires an isolated profile. CloudFront KeyValueStore data-plane
+ARNs likewise expose account and store identity but no stage condition key, so
+the Router's exact six key operations are account-scoped; use an isolated
+profile when that boundary must be enforced by AWS accounts.
+`,
+    };
+}
+//# sourceMappingURL=workspace-files-thin-docs.js.map

package/src/generators/preset/workspace-files-thin-release.d.ts

@@ -0,0 +1,14 @@
+export declare const RETIRED_THIN_LIFECYCLE_PATHS: readonly [".github/workflows/deployed-smoke.yml", ".github/workflows/reliability-read.yml", ".github/workflows/release-rollout.yml", ".github/workflows/staging-evidence.yml", "tools/verify-staging-evidence.mjs"];
+export interface ThinReleaseWorkflowPlan {
+    files: Readonly<Record<string, string>>;
+    obsoletePaths: typeof RETIRED_THIN_LIFECYCLE_PATHS;
+}
+/**
+ * Protected release promotion now occurs through the one native deploy
+ * workflow. The former rollout, post-deploy smoke, staging-evidence, and
+ * reliability-read workflows reconstructed preview-era deployment authority
+ * from artifacts that the thin lifecycle no longer emits. Native deployment
+ * runs each Slice smoke target before sealing its receipt, so retaining that
+ * parallel graph would be both redundant and permanently red.
+ */
+export declare function renderThinReleaseWorkflowPlan(): ThinReleaseWorkflowPlan;

package/src/generators/preset/workspace-files-thin-release.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RETIRED_THIN_LIFECYCLE_PATHS = void 0;
+exports.renderThinReleaseWorkflowPlan = renderThinReleaseWorkflowPlan;
+exports.RETIRED_THIN_LIFECYCLE_PATHS = Object.freeze([
+    '.github/workflows/deployed-smoke.yml',
+    '.github/workflows/reliability-read.yml',
+    '.github/workflows/release-rollout.yml',
+    '.github/workflows/staging-evidence.yml',
+    'tools/verify-staging-evidence.mjs',
+]);
+/**
+ * Protected release promotion now occurs through the one native deploy
+ * workflow. The former rollout, post-deploy smoke, staging-evidence, and
+ * reliability-read workflows reconstructed preview-era deployment authority
+ * from artifacts that the thin lifecycle no longer emits. Native deployment
+ * runs each Slice smoke target before sealing its receipt, so retaining that
+ * parallel graph would be both redundant and permanently red.
+ */
+function renderThinReleaseWorkflowPlan() {
+    return {
+        files: {},
+        obsoletePaths: exports.RETIRED_THIN_LIFECYCLE_PATHS,
+    };
+}
+//# sourceMappingURL=workspace-files-thin-release.js.map