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

package/src/generators/preset/workspace-files-ci-install.d.ts

@@ -0,0 +1,2 @@
+/** Verification-only setup: repository code, never an additional authority. */
+export declare function renderWorkspaceCiInstallFiles(): Readonly<Record<string, string>>;

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.d.ts

@@ -1,8 +1,10 @@
+import type { DeploymentProfile } from '../../repository-policy/index.js';
 export declare const DEVELOPER_AGENT_RUNBOOK_PATH: "docs/developer-agent.md";
 export declare const DEVELOPER_AGENT_HANDOFF_TEMPLATE_PATH: "docs/developer-agent-handoff.template.json";
 export declare const DEVELOPER_AGENT_ADAPTER_EVALUATION_PATH: "docs/developer-agent-adapters.md";
 export declare const DEVELOPER_AGENT_WORKSPACE_SEEDED_PATHS: readonly ["docs/developer-agent.md", "docs/developer-agent-handoff.template.json", "docs/developer-agent-adapters.md"];
 export interface DeveloperAgentWorkspaceFileOptions {
+    deploymentProfile: DeploymentProfile;
     frameworkVersion: string;
     name: string;
 }

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';
@@ -19,8 +20,25 @@ const HANDOFF_STATE_DESCRIPTIONS = {
     'failed-recovery-or-cleanup-required': 'Execution failed and named recovery or cleanup work is still required.',
     'proposal-or-research-only': 'The record contains no implementation or mutation claim.',
 };
-function renderAgentsAppendix(name) {
-    return `## Developer-Agent workflow
+function deploymentAuthorityGuidance(deploymentProfile) {
+    switch (deploymentProfile) {
+        case 'starter':
+            return `Development and production mutation may run locally only through the matching
+authenticated Nx lifecycle and committed Repository Operating Policy. GitHub deployment
+remains optional. Never invoke SST directly.`;
+        case 'production-isolated':
+            return `Development and staging mutation may run locally only through the matching
+authenticated Nx lifecycle and committed Repository Operating Policy. Production mutation
+belongs to the protected GitHub environment and OIDC workflow. Never invoke SST directly.`;
+        case 'fully-isolated':
+            return `Development mutation may run locally only through the matching authenticated Nx
+lifecycle and committed Repository Operating Policy. Staging and production mutation belongs
+to the matching protected GitHub environment and OIDC workflow. Never invoke SST directly.`;
+    }
+}
+function renderAgentsAppendix(name, deploymentProfile) {
+    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.
@@ -41,18 +59,36 @@ reported after that commit remain authenticated local-source Nx targets and reta
 documented same-user installed-toolchain boundary.
 
 Begin and hand off implementation work with
-\`pnpm nx run ${name}:work-markers\`. Verify the affected owner target, then run
-\`pnpm nx run ${name}:verify\` and the workspace \`pnpm verify\` barrier before claiming
-implemented-and-verified.
+\`pnpm nx run ${name}:work-markers\`. For ordinary feature completion, run the
+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 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.
+
+If a Slice, Service, or Job generator reports a retained post-generation install, rerun
+that same generator with the exact scoped prefix
+\`pnpm --config.verify-deps-before-run=warn nx generate\`. This is the sole exception to
+the workspace's fail-closed dependency-state check: it lets Nx reach EBK's bound recovery
+callback, which owns the install. Never run \`pnpm install\` while the retained marker exists.
 
 Use one topic branch and linked worktree per independent change. Stop on stale base,
 overlapping paths or shared external state, ownership or generated drift, invalid policy,
 blocking markers, missing prerequisites, or unknown authority; never merge, rebase, discard,
 or overwrite another worktree automatically.
 
-Local agents may inspect and propose protected work, but staging and production mutation
-belongs to the matching protected GitHub environment and OIDC workflow. Secret values remain
-a human-only TTY ceremony; agents may use only value-blind metadata, status, and verification.
+${deploymentAuthorityGuidance(deploymentProfile)} Human-supplied secret values remain a
+human-only TTY ceremony. Agents may use value-blind metadata, status, verification, and the
+exact generated-secret initializer; the initializer accepts and returns no plaintext value.
 
 Read \`docs/developer-agent.md\`, \`docs/developer-agent-handoff.template.json\`,
 \`docs/developer-agent-adapters.md\`, \`docs/git-workflow.md\`, and
@@ -62,7 +98,7 @@ Read \`docs/developer-agent.md\`, \`docs/developer-agent-handoff.template.json\`
 function renderHandoffStates() {
     return model_js_1.DEVELOPER_AGENT_HANDOFF_STATES.map((state) => `- \`${state}\`: ${HANDOFF_STATE_DESCRIPTIONS[state]}`).join('\n');
 }
-function renderRunbook(name) {
+function renderRunbook(name, deploymentProfile) {
     return `# Developer-Agent runbook
 
 This is the vendor-neutral Developer-Agent contract for the ${name} repository. The
@@ -84,21 +120,32 @@ 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. Verify the affected project or owner target, rerun
-   \`pnpm nx run ${name}:work-markers\`, run \`pnpm nx run ${name}:verify\`, and complete
-   \`pnpm verify\` before claiming completion.
+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 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.
 6. Fill an adopter-owned copy of the seeded template, then run
    \`ebk agent handoff <handoff.json>\` to validate exact resumable state. A different actor
    uses \`ebk agent resume <handoff.json>\` and must re-inspect current state rather than
@@ -138,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
@@ -211,19 +262,23 @@ 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.
 
-For development mutation, name the cleanup and recovery owner before execution. For staging or
-production, a local agent stops at report or proposal: mutation belongs only to the matching
-protected GitHub environment and OIDC workflow. Destructive work additionally requires an exact
-target, explicit approval, retained recovery proof, and completed cleanup.
+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.
 
-Secret values are entered only through the human TTY ceremony. Agents and CI are limited to
-value-blind secret metadata, status, and verification.
+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.
+
+Human-supplied secret values are entered only through the human TTY ceremony. Agents and CI
+may use value-blind metadata, status, verification, and the exact generated-secret initializer;
+the initializer accepts and returns no plaintext value.
 
 ## Handoff and resumption
 
@@ -238,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()}
@@ -467,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.
 
@@ -499,9 +561,9 @@ canonical Developer-Agent contract.
 function renderDeveloperAgentWorkspaceFilePlan(options) {
     const template = createHandoffTemplate(options);
     return {
-        agentsAppendix: renderAgentsAppendix(options.name),
+        agentsAppendix: renderAgentsAppendix(options.name, options.deploymentProfile),
         files: {
-            [exports.DEVELOPER_AGENT_RUNBOOK_PATH]: renderRunbook(options.name),
+            [exports.DEVELOPER_AGENT_RUNBOOK_PATH]: renderRunbook(options.name, options.deploymentProfile),
             [exports.DEVELOPER_AGENT_HANDOFF_TEMPLATE_PATH]: `${JSON.stringify(template, null, 2)}\n`,
             [exports.DEVELOPER_AGENT_ADAPTER_EVALUATION_PATH]: renderAdapterEvaluation(),
         },

package/src/generators/preset/workspace-files-ecr-inspector.d.ts

@@ -0,0 +1,18 @@
+import type { DeploymentProfile } from '../../repository-policy/index.js';
+export declare const THIN_ECR_INSPECTOR_WORKFLOW_PATH: ".github/workflows/ecr-inspector-evidence.yml";
+interface EcrInspectorWorkflowOptions {
+    actionPins: {
+        checkout: string;
+        configureAwsCredentials: string;
+        downloadArtifact: string;
+        pnpmSetup: string;
+        setupNode: string;
+        uploadArtifact: string;
+    };
+    deploymentProfile: DeploymentProfile;
+    name: string;
+    nodeVersion: string;
+}
+/** Render the postdeploy scanner against the thin lifecycle receipt artifact. */
+export declare function renderThinEcrInspectorWorkflow(options: EcrInspectorWorkflowOptions): Readonly<Record<typeof THIN_ECR_INSPECTOR_WORKFLOW_PATH, string>>;
+export {};