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

package/src/developer-agent/git-inspection.d.ts

@@ -26,6 +26,10 @@ export interface GitInspectionCommandResult {
 }
 export type GitInspectionExecFile = (executable: string, args: readonly string[], options: GitInspectionExecFileOptions) => GitInspectionCommandResult | Promise<GitInspectionCommandResult>;
 export interface InspectDeveloperAgentGitOptions {
+    /** Orientation only; strict commit-bound callers leave this disabled. */
+    allowUnborn?: boolean;
+    /** Only an absent fully qualified implicit ref may have a null binding. */
+    allowMissingDefaultBase?: boolean;
     /**
      * Base and head are accepted only as a pair. They must be literal safe refs
      * or full object IDs, never arbitrary revision expressions.
@@ -44,7 +48,7 @@ export interface DeveloperAgentGitUpstream {
 }
 export interface DeveloperAgentLinkedWorktree {
     branch: string | null;
-    commit: string;
+    commit: string | null;
     detached: boolean;
     dirtyPaths: readonly string[];
     locked: boolean;
@@ -84,7 +88,7 @@ export interface DeveloperAgentGitInspection {
     concurrentChangeInspectionComplete: boolean;
     concurrentChanges: readonly DeveloperAgentConcurrentPathChange[];
     defaultBase?: {
-        commit: string;
+        commit: string | null;
         ref: string;
     };
     kind: 'developer-agent-git-inspection';

package/src/developer-agent/git-inspection.js

@@ -126,6 +126,18 @@ function assertDeveloperAgentReadOnlyGitInvocation(args) {
             '--short',
             'HEAD',
         ]) ||
+        (args.length === 5 &&
+            args[1] === 'symbolic-ref' &&
+            args[2] === '--quiet' &&
+            args[3] === '--no-recurse' &&
+            (args[4] === 'HEAD' ||
+                (args[4]?.startsWith('refs/') === true && safeRef(args[4])))) ||
+        (args.length === 5 &&
+            args[1] === 'show-ref' &&
+            args[2] === '--verify' &&
+            args[3] === '--quiet' &&
+            args[4]?.startsWith('refs/') === true &&
+            safeRef(args[4])) ||
         sameArgs(args, [
             NO_OPTIONAL_LOCKS,
             ...DISABLE_FS_MONITOR,
@@ -499,6 +511,41 @@ async function resolveCommit(git, ref, cwd) {
     ], { cwd });
     return requireCommit(result.stdout, `Git ref ${ref}`);
 }
+async function exactRefExists(git, ref, cwd) {
+    const result = await git.run([NO_OPTIONAL_LOCKS, 'show-ref', '--verify', '--quiet', ref], {
+        allowedExitCodes: [0, 1],
+        cwd,
+    });
+    if (result.stdout !== '' || result.stderr !== '') {
+        return fail('git-output-invalid', 'Git ref existence returned unexpected output.');
+    }
+    if (result.exitCode === 0)
+        return true;
+    // show-ref also reports a dangling symbolic ref as absent. Check the ref
+    // itself without following it before admitting absence. Corrupt object refs
+    // fail show-ref above; symbolic refs remain present and must resolve normally.
+    const symbolic = await git.run([NO_OPTIONAL_LOCKS, 'symbolic-ref', '--quiet', '--no-recurse', ref], { allowedExitCodes: [0, 1], cwd });
+    if (symbolic.stderr !== '' ||
+        (symbolic.exitCode === 1 && symbolic.stdout !== '')) {
+        return fail('git-output-invalid', 'Git symbolic ref existence returned unexpected output.');
+    }
+    if (symbolic.exitCode === 0) {
+        const target = singleSafeLine(symbolic.stdout, 'Git symbolic ref target');
+        if (!target.startsWith('refs/') || !safeRef(target)) {
+            return fail('git-output-invalid', 'Git symbolic ref target is invalid.');
+        }
+        return true;
+    }
+    return false;
+}
+async function resolveDefaultBase(git, ref, cwd, allowMissing) {
+    if (allowMissing &&
+        ref.startsWith('refs/') &&
+        !(await exactRefExists(git, ref, cwd))) {
+        return null;
+    }
+    return resolveCommit(git, ref, cwd);
+}
 async function resolveDirectory(git, kind, cwd) {
     const result = await git.run([NO_OPTIONAL_LOCKS, 'rev-parse', '--path-format=absolute', kind], { cwd });
     return requireAbsoluteDirectoryOutput(result.stdout, kind === '--show-toplevel' ? 'Git worktree root' : 'Git common directory', kind === '--show-toplevel'
@@ -521,16 +568,32 @@ async function resolveBranch(git, cwd) {
     }
     return { branch, detached: false };
 }
-async function verifyWorktree(git, commonDirectory, worktree, budget) {
+async function verifyWorktree(git, commonDirectory, worktree, budget, allowUnborn) {
     const discoveredRoot = await resolveDirectory(git, '--show-toplevel', worktree.realRoot);
     const discoveredCommon = await resolveDirectory(git, '--git-common-dir', worktree.realRoot);
     if (discoveredRoot !== worktree.realRoot ||
         discoveredCommon !== commonDirectory) {
         return fail('git-worktree-ambiguous', 'Linked worktree identity does not match the inspected repository.');
     }
-    const commit = await resolveCommit(git, 'HEAD', worktree.realRoot);
+    let commit;
+    if (allowUnborn && /^0{40}(?:0{24})?$/.test(worktree.head)) {
+        if (!worktree.branchRef || worktree.detached) {
+            return fail('git-output-invalid', 'Unborn worktree must have one symbolic local branch.');
+        }
+        const symbolic = await git.run([NO_OPTIONAL_LOCKS, 'symbolic-ref', '--quiet', '--no-recurse', 'HEAD'], { cwd: worktree.realRoot });
+        if (symbolic.stderr !== '' ||
+            singleSafeLine(symbolic.stdout, 'Unborn HEAD branch') !==
+                worktree.branchRef ||
+            (await exactRefExists(git, worktree.branchRef, worktree.realRoot))) {
+            return fail('git-worktree-ambiguous', 'Unborn HEAD does not match an absent exact local branch.');
+        }
+        commit = null;
+    }
+    else {
+        commit = await resolveCommit(git, 'HEAD', worktree.realRoot);
+    }
     const branchState = await resolveBranch(git, worktree.realRoot);
-    if (commit !== worktree.head ||
+    if ((commit !== null && commit !== worktree.head) ||
         branchState.branch !== worktree.branch ||
         branchState.detached !== worktree.detached) {
         return fail('git-worktree-ambiguous', 'Linked worktree state changed during inspection.');
@@ -555,7 +618,7 @@ async function verifyWorktree(git, commonDirectory, worktree, budget) {
     };
 }
 async function inspectUpstream(git, current) {
-    if (!current.branch)
+    if (!current.branch || current.commit === null)
         return undefined;
     const upstreamResult = await git.run([
         NO_OPTIONAL_LOCKS,
@@ -662,6 +725,10 @@ async function inspectConcurrentChanges(git, current, worktrees, budget) {
             continue;
         for (const path of worktree.dirtyPaths)
             record(path, worktree.root, 'dirty');
+        if (worktree.commit === null || current.commit === null) {
+            complete = false;
+            continue;
+        }
         if (worktree.commit === current.commit)
             continue;
         const mergeBase = await git.run([
@@ -723,6 +790,11 @@ function validateInput(options) {
     if ((options.base === undefined) !== (options.head === undefined)) {
         return fail('invalid-input', 'Git comparison requires both explicit base and head refs.');
     }
+    for (const value of [options.allowUnborn, options.allowMissingDefaultBase]) {
+        if (value !== undefined && typeof value !== 'boolean') {
+            return fail('invalid-input', 'Git orientation allowances must be explicit booleans.');
+        }
+    }
     if (options.base !== undefined && options.head !== undefined) {
         return {
             base: requireSafeRef(options.base, 'Git comparison base'),
@@ -754,7 +826,7 @@ async function inspectDeveloperAgentGit(options) {
     const budget = { count: 0 };
     const linkedWorktrees = [];
     for (const worktree of prepared) {
-        linkedWorktrees.push(await verifyWorktree(git, commonDirectory, worktree, budget));
+        linkedWorktrees.push(await verifyWorktree(git, commonDirectory, worktree, budget, options.allowUnborn === true));
     }
     const current = linkedWorktrees.find(({ root }) => root === currentRoot);
     if (!current) {
@@ -763,7 +835,7 @@ async function inspectDeveloperAgentGit(options) {
     const upstream = await inspectUpstream(git, current);
     const defaultBase = comparisonInput.defaultBase !== undefined
         ? {
-            commit: await resolveCommit(git, comparisonInput.defaultBase, currentRoot),
+            commit: await resolveDefaultBase(git, comparisonInput.defaultBase, currentRoot, options.allowMissingDefaultBase === true),
             ref: comparisonInput.defaultBase,
         }
         : undefined;

package/src/developer-agent/model.d.ts

@@ -159,10 +159,12 @@ export interface DeveloperAgentGitContext {
     baseCommit?: string;
     behind: number;
     branch?: string;
-    commit: string;
+    /** Null means a verified unborn symbolic branch, never a placeholder SHA. */
+    commit: string | null;
     concurrentChangeInspectionComplete: boolean;
     concurrentChanges: readonly DeveloperAgentConcurrentChangeContext[];
-    defaultBaseCommit: string;
+    /** An implicit base may be absent during local first-use orientation. */
+    defaultBaseCommit: string | null;
     defaultBaseRef: string;
     dirty: boolean;
     headCommit?: string;
@@ -176,7 +178,7 @@ export interface DeveloperAgentPolicyField {
 export interface DeveloperAgentEffectivePolicyDecision {
     action: DeveloperAgentPolicyLifecycleAction;
     allowed: boolean;
-    effectiveProductionProfile?: 'cost-optimized' | 'standard';
+    effectiveProductionProfile?: 'cost-optimized' | 'balanced' | 'standard';
     projects: readonly string[];
     reasons: readonly string[];
     stage: DeveloperAgentCanonicalStage;

package/src/developer-agent/model.js

@@ -15,10 +15,10 @@ exports.DEVELOPER_AGENT_RESULT_KIND = 'developer-agent-result';
 exports.DEVELOPER_AGENT_HANDOFF_KIND = 'developer-agent-handoff';
 exports.DEVELOPER_AGENT_GENERATOR_PREVIEW_KIND = 'developer-agent-generator-preview';
 exports.DEVELOPER_AGENT_GENERATOR_PREVIEW_RECEIPT_KIND = 'developer-agent-generator-preview-receipt';
-// Context is nested inside the 128 KiB agent CLI result envelope. Retain 32 KiB
-// for the envelope and failure metadata while accommodating the real Standard
-// workspace's authenticated operation inventory.
-exports.DEVELOPER_AGENT_CONTEXT_MAX_BYTES = 96 * 1024;
+// Context is nested inside the 160 KiB agent CLI result envelope. Retain 32 KiB
+// for the envelope and failure metadata while accommodating the measured
+// five-project Standard workspace's authenticated operation inventory.
+exports.DEVELOPER_AGENT_CONTEXT_MAX_BYTES = 128 * 1024;
 exports.DEVELOPER_AGENT_MAX_PROJECT_NAMES = 128;
 exports.DEVELOPER_AGENT_PLAN_MAX_BYTES = 64 * 1024;
 exports.DEVELOPER_AGENT_RESULT_MAX_BYTES = 64 * 1024;

package/src/developer-agent/operation-registry.d.ts

@@ -7,8 +7,12 @@ export interface DeveloperAgentTargetInput {
     targetName: string;
 }
 export interface DeveloperAgentOperationRegistryOptions {
+    /** Full graph Slice inventory; a bounded selection cannot authorize root `all`. */
+    allSliceProjectNames?: readonly string[];
     exposedProjectNames?: readonly string[];
     externalOwnedProjectNames: readonly string[];
+    /** Diagnostic only: incomplete history retains the same conservative authority. */
+    externalOwnershipHistoryComplete?: boolean;
     namedInputDefinitions: readonly unknown[];
     reviewedExternalVerification?: readonly DeveloperAgentReviewedExternalVerification[];
 }
@@ -30,6 +34,16 @@ export declare class DeveloperAgentOperationRegistryError extends Error {
     readonly classification: "unsupported-operation";
     constructor();
 }
+/**
+ * Non-plannable local targets name their real owner. Each string states only
+ * behaviour that exists: none of them promises a Developer-Agent plan entry.
+ */
+export declare const DEPLOY_LOCAL_OWNER_RATIONALE = "Development deployment is owned by ebk deploy development [slice]: run that command directly with the saved development --profile and the policy-derived --expectedRoleArn. This root target is its Nx implementation, not a separate entry point.";
+export declare const DOCKER_BUILD_OWNER_RATIONALE = "Local workload image builds use the host Docker daemon outside any bounded owner. Verify workload source with its build, test and typecheck targets; ebk deploy development <slice> builds the deployable image.";
+export declare const WORKLOAD_DEV_OWNER_RATIONALE = "A hot workload process started outside the ebk dev Fleet has no owned port, lifecycle or cleanup. Verify Service and Job source with its test, typecheck and build targets and exercise it through ebk deploy development <slice>.";
+export declare const FORMAT_WRITE_OWNER_RATIONALE = "Formatting rewrites source files only: run pnpm nx format:write directly as part of a source edit, then rerun the required verification.";
+export declare const GRAPH_INTERACTIVE_RATIONALE = "nx graph starts an interactive browser server and is not a bounded operation; use ebk agent context for the read-only project inventory.";
+export declare const ROUTER_WAF_REHEARSAL_OWNER_RATIONALE = "The Router WAF rehearsal requires an exact --probeUrl that planning cannot derive: run it directly through its Nx target with that option after a development deployment.";
 /**
  * Authority classes are not a severity list. In particular, development
  * mutation plus protected proposal crosses authority domains and therefore
@@ -39,6 +53,7 @@ export declare class DeveloperAgentOperationRegistryError extends Error {
 export declare function joinDeveloperAgentAuthorityClasses(left: DeveloperAgentAuthorityClass, right: DeveloperAgentAuthorityClass): DeveloperAgentAuthorityClass | undefined;
 export declare function createDeveloperAgentOperationRegistry(projects: readonly {
     context: DeveloperAgentProjectContext;
+    localDev?: unknown;
     targets: Readonly<Record<string, TargetConfiguration>>;
 }[], options: DeveloperAgentOperationRegistryOptions): DeveloperAgentOperationRegistry;
 export declare function requireDeveloperAgentOperation(registry: DeveloperAgentOperationRegistry, id: string): DeveloperAgentSupportedOperation;