@empire-builder-kit/nx 1.0.0-rc.38 → 1.0.0-rc.39

package/src/generators/preset/workspace-files-ci-install.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderWorkspaceCiInstallFiles = renderWorkspaceCiInstallFiles;
+/** Verification-only setup: repository code, never an additional authority. */
+function renderWorkspaceCiInstallFiles() {
+    return {
+        'tools/ci/install.mjs': String.raw `import { spawn } from 'node:child_process';
+import { lstatSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const root = realpathSync(process.cwd());
+const hookPath = path.join(root, 'tools/ci/dependency-setup.mjs');
+const controller = new AbortController();
+let interrupted;
+const interrupt = (signal) => {
+  interrupted ??= signal;
+  controller.abort(new Error('CI dependency installation interrupted: ' + signal));
+};
+const onInt = () => interrupt('SIGINT');
+const onTerm = () => interrupt('SIGTERM');
+process.on('SIGINT', onInt);
+process.on('SIGTERM', onTerm);
+
+function install() {
+  controller.signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const child = spawn('pnpm', ['install', '--frozen-lockfile'], {
+      cwd: root,
+      stdio: 'inherit',
+      shell: false,
+      detached: process.platform !== 'win32',
+    });
+    let escalation;
+    const kill = (signal) => {
+      if (!child.pid) return;
+      try {
+        if (process.platform === 'win32') child.kill(signal);
+        else process.kill(-child.pid, signal);
+      } catch (error) {
+        if (error.code !== 'ESRCH') throw error;
+      }
+    };
+    const abort = () => {
+      kill('SIGTERM');
+      escalation = setTimeout(() => kill('SIGKILL'), 5000);
+      escalation.unref();
+    };
+    controller.signal.addEventListener('abort', abort, { once: true });
+    const finish = (error) => {
+      clearTimeout(escalation);
+      controller.signal.removeEventListener('abort', abort);
+      if (error) reject(error);
+      else resolve();
+    };
+    child.once('error', finish);
+    child.once('exit', (code, signal) => finish(
+      code === 0 && !signal && !controller.signal.aborted ? undefined :
+        new Error('pnpm frozen install failed (' + (signal ?? code) + ').'),
+    ));
+    if (controller.signal.aborted) abort();
+  });
+}
+
+let cleanup;
+let failed = false;
+try {
+  let stat;
+  try { stat = lstatSync(hookPath); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (stat) {
+    if (!stat.isFile() || stat.isSymbolicLink() || realpathSync(hookPath) !== hookPath) {
+      throw new Error('CI dependency setup must be a regular repository-local file.');
+    }
+    const hook = await import(pathToFileURL(hookPath).href);
+    if (typeof hook.setup !== 'function' || typeof hook.cleanup !== 'function') {
+      throw new Error('CI dependency setup must export setup and cleanup functions.');
+    }
+    // Register cleanup before setup: partial setup failure must also clean up.
+    cleanup = hook.cleanup;
+    await hook.setup({ workspaceRoot: root, signal: controller.signal });
+  }
+  await install();
+} catch (error) {
+  failed = true;
+  console.error('[ebk-ci-install] ' + error.message);
+} finally {
+  try {
+    // Cleanup must remain operable after the setup/install signal is aborted.
+    if (cleanup) await cleanup({ workspaceRoot: root });
+  } catch (error) {
+    failed = true;
+    console.error('[ebk-ci-install] Cleanup failed: ' + error.message);
+  }
+  process.off('SIGINT', onInt);
+  process.off('SIGTERM', onTerm);
+}
+process.exitCode = interrupted === 'SIGINT' ? 130 : interrupted ? 143 : failed ? 1 : 0;
+`,
+        'tools/ci/release-candidates.mjs': String.raw `import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export function selectReleaseCandidates(nodes, root) {
+  if (!nodes || typeof nodes !== 'object' || Array.isArray(nodes)) {
+    throw new Error('Nx project graph is invalid.');
+  }
+  const selected = [];
+  for (const [name, node] of Object.entries(nodes)) {
+    const data = node?.data;
+    if (!data || typeof data.root !== 'string' || !data.targets || typeof data.targets !== 'object') {
+      throw new Error('Nx project configuration is invalid: ' + name);
+    }
+    const projectRoot = path.resolve(root, data.root);
+    const relative = path.relative(root, projectRoot);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+      throw new Error('Project root escapes workspace: ' + name);
+    }
+    const ownershipPath = path.join(projectRoot, '.ebk/ownership.json');
+    let standard = false;
+    if (existsSync(ownershipPath)) {
+      if (!lstatSync(ownershipPath).isFile() || realpathSync(ownershipPath) !== ownershipPath) {
+        throw new Error('Project ownership is not a regular file: ' + name);
+      }
+      standard = JSON.parse(readFileSync(ownershipPath, 'utf8')).blueprint?.name ===
+        '@empire-builder-kit/blueprint-standard';
+    }
+    const targets = data.targets;
+    if ((standard || targets['release-artifacts'] || targets['container-release']) && !targets['release-candidate']) {
+      throw new Error('Application release-candidate target is missing: ' + name);
+    }
+    if (!targets['release-candidate']) continue;
+    if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(name) || data.root !== 'packages/' + name) {
+      throw new Error('Release candidate project identity is invalid: ' + name);
+    }
+    selected.push(name);
+  }
+  return selected.sort();
+}
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+  try {
+    const require = createRequire(import.meta.url);
+    // pnpm exposes this dependency to the installed EBK package, not the adopter root.
+    const frameworkRequire = createRequire(require.resolve('@empire-builder-kit/nx/package.json'));
+    const { createProjectGraphAsync } = frameworkRequire('@nx/devkit');
+    const graph = await createProjectGraphAsync();
+    process.stdout.write(selectReleaseCandidates(graph.nodes, realpathSync(process.cwd())).join(','));
+  } catch (error) {
+    console.error('[ebk-release-candidates] ' + error.message);
+    process.exitCode = 1;
+  }
+}
+`,
+        'docs/ci-dependency-setup.md': `# Verification CI dependency setup
+
+Ordinary verification CI runs the fixed command \`pnpm install --frozen-lockfile\`
+through the managed \`tools/ci/install.mjs\` wrapper. Without an extension its
+installation, package policies and native diagnostics are unchanged.
+
+For private package access or another installation prerequisite, create the
+adopter-owned \`tools/ci/dependency-setup.mjs\`. Export two async functions:
+
+\`setup({ workspaceRoot, signal })\` establishes the prerequisite **before** pnpm
+starts. \`cleanup({ workspaceRoot })\` removes only resources owned by this
+invocation. Both exports are required. Setup must support the cancellation
+signal, and cleanup must be idempotent and work after partial setup failure.
+Do not perform side effects at module import time. Use Node built-ins or
+explicitly pinned independent tooling: workspace dependencies are not installed
+yet. Do not replace the installer or relax its frozen lockfile/supply-chain rules.
+
+The extension may temporarily configure the existing root registry surface.
+It must preserve pre-existing configuration, retain exact ownership for any
+temporary process or file, and remove its temporary state before returning.
+Do not log credentials or copy authenticated configuration into artifacts.
+Failed setup prevents installation; failed install or cleanup prevents accepted
+job success. SIGINT/SIGTERM cancels the installer process group on POSIX, then
+attempts cleanup. Hard termination still requires exact owned-remnant recovery;
+neither hooks nor cleanup can be guaranteed after SIGKILL or runner loss.
+
+This is repository code executing with the verification job's existing read-only
+permissions, not a sandbox or a new credential authority. It is not installed in
+OIDC deployment workflows and cannot change protected environments, review gates
+or AWS permissions. No hook is generated by default; managed upgrades preserve
+this unclaimed adopter-owned path. Never hand-edit the managed wrapper/workflow.
+
+Infrastructure-only workspaces still run policy and source verification. With
+no application release producers, the release-candidate job reports not
+applicable and uploads no fictitious application candidate. Standard Slices and
+other projects declaring release-artifacts/container-release must retain their
+release-candidate target; declared candidates must still build and emit files.
+`,
+    };
+}
+//# sourceMappingURL=workspace-files-ci-install.js.map

package/src/generators/preset/workspace-files-developer-agent.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEVELOPER_AGENT_WORKSPACE_SEEDED_PATHS = exports.DEVELOPER_AGENT_ADAPTER_EVALUATION_PATH = exports.DEVELOPER_AGENT_HANDOFF_TEMPLATE_PATH = exports.DEVELOPER_AGENT_RUNBOOK_PATH = void 0;
 exports.renderDeveloperAgentWorkspaceFilePlan = renderDeveloperAgentWorkspaceFilePlan;
 const model_js_1 = require("../../developer-agent/model.js");
+const workspace_files_adopter_skills_js_1 = require("./workspace-files-adopter-skills.js");
 exports.DEVELOPER_AGENT_RUNBOOK_PATH = 'docs/developer-agent.md';
 exports.DEVELOPER_AGENT_HANDOFF_TEMPLATE_PATH = 'docs/developer-agent-handoff.template.json';
 exports.DEVELOPER_AGENT_ADAPTER_EVALUATION_PATH = 'docs/developer-agent-adapters.md';
@@ -36,7 +37,8 @@ to the matching protected GitHub environment and OIDC workflow. Never invoke SST
     }
 }
 function renderAgentsAppendix(name, deploymentProfile) {
-    return `## Developer-Agent workflow
+    return `${(0, workspace_files_adopter_skills_js_1.renderAdopterSkillIndex)()}
+## Developer-Agent workflow
 
 The Developer-Agent contract is bounded to the ${name} product and this repository. It does
 not grant authority over another repository, account, environment, or worktree.
@@ -62,9 +64,13 @@ affected owner's tests, typecheck, lint, and ownership checks reported by the
 Nx graph and agent context. Record exactly which checks passed and which remain
 pending. Feature verification is not release qualification.
 
-Reserve \`pnpm nx run ${name}:verify\` and the workspace \`pnpm verify\` barrier
-for an adopter milestone or coherent integration batch. Release qualification
-additionally requires the declared packed, platform, and external acceptance.
+Reserve the workspace \`pnpm verify\` source-check barrier for an adopter
+milestone or coherent integration batch. It uses \`${name}:verify-proposed\`
+and does not require an initial commit or produce protected Blueprint authority.
+The separate \`pnpm nx run ${name}:verify\` target retains protected Blueprint
+trust checks and requires real committed history and protected refs; protected
+CI continues using that target. Release qualification additionally requires
+the declared packed, platform, and external acceptance.
 An explicitly required safety or contract check is never waived by this cadence.
 Development accepts a dirty tree and needs no production confirmation or release
 artifact; protected-stage source and approval requirements remain unchanged.
@@ -114,23 +120,29 @@ CLI and Nx contract complete their live pilots.
    \`pnpm nx run ${name}:developer-context\` target is a compatibility and graph-authority
    route: its human mode emits concise prose, and \`--json\` emits only the canonical context
    byte length and digest in a bounded fingerprint.
-3. Create one bounded JSON request, then run
+3. For commit-bound advisory planning, create one bounded JSON request, then run
    \`ebk agent plan <request.json>\` for one supported operation and reviewed
    acceptance-criteria reference. The plan is advisory and grants no execution authority.
-4. Follow only the reported owner and operation:
+   On fresh or dirty source, ordinary feature work may instead use the documented
+   typed generator directly (dry-run, then apply), or edit inspected seeded/user-owned
+   feature surfaces. This does not execute a blocked plan or waive the owner's checks.
+   Do not manufacture commits or protected refs merely to develop.
+4. Follow the documented owning workflow, or the reported plan when using planning:
    - execute a typed stable Slice, Function, Service, Job, or Upgrade generator with exactly
      the structured arguments reported by the plan;
    - execute authenticated read-only, local-source, or development Nx targets;
    - execute bounded \`ebk dev\` inspection or Slice lifecycle commands;
    - execute the frozen package installation command;
-   - make an ordinary source edit only within the plan-derived adopter-owned project scope; or
+   - make an ordinary source edit within inspected seeded/user-owned extension points
+     (formal source-edit plans admit only adopter-owned paths); or
    - route protected work to the matching GitHub environment and OIDC workflow without
      receiving local command arguments.
 5. Run the affected owner's tests, typecheck, lint, and ownership checks from
    the Nx graph and agent context, then rerun \`pnpm nx run ${name}:work-markers\`.
    For ordinary feature completion, report those results without requiring the
    full workspace barrier. At an adopter milestone or coherent integration batch,
-   also run \`pnpm nx run ${name}:verify\` and \`pnpm verify\`. Release qualification
+   also run \`pnpm verify\` for current source. Protected acceptance separately
+   runs \`pnpm nx run ${name}:verify\` against genuine protected refs. Release qualification
    adds the declared packed, platform, and external acceptance. Feature verification
    is not release qualification; no explicitly required safety or contract check
    is waived, and pending external proof remains pending in the handoff.
@@ -173,9 +185,13 @@ context:
 Optional \`assumptions\` remain bounded and explicit. The CLI derives each selected path's
 \`managed\`, \`seeded\`, or \`adopter-owned\` mode from repository ownership records and
 project roots; the request cannot assert it. Cross-project selections, unknown ownership,
-managed or seeded source-edit paths, raw commands, prompts, secret values, absolute paths,
+managed or seeded source-edit plan paths, raw commands, prompts, secret values, absolute paths,
 traversal, and symlink inputs are refused.
 
+That source-edit plan restriction does not make seeded feature code immutable.
+Edit seeded handlers, tests and feature registries through the ordinary documented
+feature workflow; managed mechanics always require their owning generator.
+
 Typed generator requests add one closed \`generatorInput\` object and cannot supply
 \`selectedFiles\`. New Slice planning accepts only \`{"generator":"slice","name":"billing"}\`
 and the built-in Standard Blueprint. Function, Service, and Job planning requires exact
@@ -246,12 +262,16 @@ mutation, verification, cleanup, protected evidence, or approval occurred.
 
 ## Stop conditions
 
-Stop before mutation when the command reports invalid input, a dirty worktree, stale base,
-overlapping work, ownership conflict, generated drift, policy conflict, blocking marker,
+Stop the requested operation when its command reports invalid input, a dirty worktree
+or stale base prohibited by that operation, overlapping work, ownership conflict, generated drift, policy conflict, blocking marker,
 missing prerequisite, or required authority. Unknown targets fail closed. Do not repair managed
 output directly, silently adopt another worktree's changes, infer a protected credential, or
 broaden an operation beyond the owning tool.
 
+Dirty source alone does not block ordinary feature generation, seeded/user-owned edits,
+affected verification or local development. Commit-bound plans, upgrades and formal
+handoffs still enforce their exact source requirements; protected authority is unchanged.
+
 For every mutation, name the cleanup and recovery owner before execution.
 ${deploymentAuthorityGuidance(deploymentProfile)} Destructive work additionally requires an
 exact target, explicit approval, retained recovery proof, and completed cleanup.
@@ -273,6 +293,11 @@ stage, effective policy digest, candidate provenance, Blueprint and framework ve
 performed operation identities, marker snapshot, external resources, and required verification
 and evidence.
 
+Before a clean checkpoint exists, retain an ordinary work-in-progress note under
+\`docs/adoption/\`: exact files, package/source identity, checks, pending cleanup and
+next supported command. Another actor must re-inspect current state. Such a note is
+not a validated formal handoff or protected evidence and needs no fabricated refs.
+
 The six honest handoff states are:
 
 ${renderHandoffStates()}
@@ -502,11 +527,13 @@ function createHandoffTemplate(options) {
 function renderAdapterEvaluation() {
     return `# Optional Developer-Agent adapter evaluation
 
-Stable-v1 decision: Empire Builder Kit does not ship a skill or MCP adapter before v1. The
+Empire Builder Kit bundles six repository-local adopter skills under \`.agents/skills/\`.
+They teach the canonical workflow and can be read directly by any agent; automatic discovery
+depends on the agent host. EBK does not require a hosted agent service or ship an MCP adapter. The
 repository-local \`ebk agent context\`, \`ebk agent plan\`, \`ebk agent upgrade-preview\`,
 \`ebk agent handoff\`, \`ebk agent resume\`, and declared Nx targets are the canonical
 contract for humans and agents. Revisit an adapter only after that contract completes its
-live pilots.
+live pilots. Bundled skills remain guidance, not a separate execution or approval system.
 
 A skill or MCP adapter is optional.
 

package/src/generators/preset/workspace-files-performance-load.js

@@ -170,6 +170,14 @@ function deriveProtectedPerformanceEndpoint(input) {
             suffix: '/__ebk/performance/async-worker',
             workload: 'async-worker',
         },
+        'async-key-value-burst': {
+            suffix: '/__ebk/performance/async-worker',
+            workload: 'async-worker',
+        },
+        'database-read-write': {
+            suffix: '/__ebk/performance/database',
+            workload: 'database',
+        },
         'database-cold-resume': {
             suffix: '/__ebk/performance/database',
             workload: 'database',

package/src/generators/preset/workspace-files-stage-authority.js

@@ -9,6 +9,14 @@ Each active stage uses one stable deployment role and one runtime permission
 boundary. The authority is independent of framework package candidates and is
 updated only when the reviewed service-family contract changes.
 
+A fresh fully-isolated workspace may bind development and staging before its
+production account exists. Leave an unavailable account explicitly null; do
+not invent an ID or reuse another stage's account. The selected lower stage
+must have its exact account, and every configured account must be distinct.
+Production operations still require the complete three-account topology and
+all existing production controls. This does not relax the complete tuple
+evidence required when migrating ownership of an existing workspace.
+
 Render a stage's CloudFormation template from the committed repository policy:
 
 \`\`\`sh
@@ -71,6 +79,14 @@ edge WAF log group is ARN-contained. CloudWatch Logs exposes
 \`PutResourcePolicy\` only at account scope, with no resource or action-specific
 condition keys, so its reviewed generated payload cannot be inspected by IAM;
 the exact edge Region and reviewed generated source are the honest controls.
+The separate, normally empty Router smoke-access IP set uses the existing
+Pulumi AWS provider's Cloud Control resource lifecycle. Cloud Control
+create/update/delete require \`Resource: "*"\` and offer no resource-type
+condition key. Those orchestration actions and required reads are restricted
+to the edge Region; the service uses the caller's temporary session, with no
+service-role override. Underlying WAF calls still require the stage deployer's
+resource authority and remain subject to its explicit guardrails. Baseline WAF
+IP-set identities are preserved and smoke never edits their addresses.
 When the committed application Region is also the edge Region, ordinary log
 lifecycle mutations are admitted only for the generated stage application and
 API execution-log namespaces; unrelated and other-stage log groups remain
@@ -137,7 +153,7 @@ tags, production-name protections, and explicit protection-removal denies are
 the stable guardrails around the broader infrastructure service families. In
 commercial AWS, CloudFront, CloudFront-scope WAF, and edge ACM mutations use
 the us-east-1 control plane while application resources remain bound to the
-committed deployment Region. RC.31 does not claim Router edge support in
+committed deployment Region. This prerelease does not claim Router edge support in
 noncommercial partitions: CloudFront is unavailable inside GovCloud, and the
 China-partition CloudFront/WAF/edge-ACM control plane is not yet proven.
 
@@ -148,6 +164,29 @@ bootstrap state and assets. Tag and name denies are defense in depth, not a hard
 IAM boundary between same-account deployment roles. Choose
 \`production-isolated\` when production requires an AWS-enforced deployment
 blast-radius boundary from development and staging.
+
+Native SST 4.17.1 development uses a shared untagged AppSync Events API named
+\`sst\` and its \`sst\` namespace in the development account/Region. Development
+authority admits native discovery/creation; the runtime boundary admits only
+connect/publish/subscribe. No API-key, GraphQL, update or deletion authority is
+added. IAM cannot isolate task channel subpaths within this namespace: this is
+a shared developer control plane, not an application event bus or a boundary
+between mutually hostile tasks. Application data/events remain task-scoped.
+Task cleanup never deletes this shared transport. Protected-stage authority is
+unchanged; an incomplete or malformed native API requires investigation.
+
+Native Next.js development also assumes SST's generated web dev-server runtime
+role. Development authority admits only the \`sst-dev\` session in the committed
+Region, for roles in the reserved development workload path carrying both the
+generated \`ebk:dev-runtime=web\` purpose and a development or task-stage tag.
+Purpose does not depend on SST's potentially truncated physical names. Other role paths/accounts and
+protected-stage assumptions remain denied. Runtime roles still cannot assume
+other roles, and their mandatory boundary and task data restrictions remain.
+The owned web launcher requires SST's temporary runtime session and strips
+inherited deployment profile selectors before starting Next. If that handoff
+fails, reconcile this generated authority and inspect \`ebk dev logs <slice>\`,
+then retry \`ebk dev restart <slice>\`. Do not grant the infrastructure deployer
+direct application data access or modify generated runtime trust as a workaround.
 `,
         'docs/workspace-deployment-ownership.md': `# Workspace deployment ownership