refactor(core): enforce the resource boundary and make two branches reachable

Layering is now a declared allow-list rather than an unwritten convention:
projects may reach environments, deployments and git because creating a
project genuinely creates all three, and nothing else may reach anything.
The check covers test files too, which is where the last two edges hid.

Both crossings are gone. The command and its test import through the
resource that owns the composition, and core's test asserts the api
surface's contract instead of a resource's concrete class.

Two paths could not be covered as written. The retry loop had no exit
condition, so its closing brace was unreachable; it is now bounded, with a
final attempt after the last delay. The listen-failure mapping was a
ternary reachable only through a real socket error, so it is now a function
both of whose branches are tested directly, and serve returns the server it
already had.

#claude_code#
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: naeem-shakh-cs

src/commands/launch/projects/create.test.ts

@@ -1,6 +1,8 @@
-import { DEPLOYMENT_WAIT_TIMEOUT_MS } from '../../../deployments/deployment.watcher';
-import { ProjectCreator } from '../../../projects/project.create';
-import { serverCommandFrameworkGate } from '../../../environments/environment.inputs';
+import {
+  DEPLOYMENT_WAIT_TIMEOUT_MS,
+  ProjectCreator,
+  serverCommandFrameworkGate,
+} from '../../../projects/project.create';
 import ProjectsCreate from './create';
 
 function commandUnderTest(resolved: Record<string, unknown>, dataDir = '/tmp/site') {

src/commands/launch/projects/create.ts

@@ -1,8 +1,6 @@
 import { LaunchCommand } from '../../../core/launch-command';
 import { flagsFor, inputs } from '../../../core/inputs';
-import { defaultWatchTiming } from '../../../deployments/deployment.watcher';
-import { serverCommandFrameworkGate } from '../../../environments/environment.inputs';
-import { ProjectCreator } from '../../../projects/project.create';
+import { ProjectCreator, defaultWatchTiming, serverCommandFrameworkGate } from '../../../projects/project.create';
 
 const createInputs = inputs({
   org: { required: true },

src/core/layering.test.ts

@@ -1,29 +1,81 @@
 import { readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, relative, sep } from 'node:path';
 
 const SRC = join(__dirname, '..');
 const LAYERS = ['core', 'transport'];
 const RESOURCES = ['projects', 'functions', 'environments', 'deployments', 'git'];
 
+const RESOURCE_EDGES: Record<string, string[]> = {
+  projects: ['environments', 'deployments', 'git'],
+  functions: [],
+  environments: [],
+  deployments: [],
+  git: [],
+};
+
+function filesUnder(directory: string): string[] {
+  return readdirSync(join(SRC, directory), { withFileTypes: true }).flatMap((entry) => {
+    const child = join(directory, entry.name);
+
+    if (entry.isDirectory()) {
+      return filesUnder(child);
+    }
+
+    return entry.name.endsWith('.ts') ? [child] : [];
+  });
+}
+
 function sourceFilesIn(layer: string): string[] {
-  return readdirSync(join(SRC, layer))
-    .filter((entry) => entry.endsWith('.ts') && !entry.endsWith('.test.ts'))
-    .map((entry) => join(layer, entry));
+  return filesUnder(layer).filter((path) => !path.endsWith('.test.ts'));
 }
 
 function importedPaths(relativePath: string): string[] {
   const contents = readFileSync(join(SRC, relativePath), 'utf8');
   return [...contents.matchAll(/from '([^']+)'/g)].map((match) => match[1]);
 }
 
+function resourceOf(specifier: string, fromDirectory: string): string | undefined {
+  if (!specifier.startsWith('.')) {
+    return undefined;
+  }
+
+  const resolved = relative(SRC, join(SRC, fromDirectory, specifier));
+  const head = resolved.split(sep)[0];
+
+  return RESOURCES.includes(head) ? head : undefined;
+}
+
+function directoryOf(relativePath: string): string {
+  const parts = relativePath.split(sep);
+  return parts.slice(0, -1).join(sep);
+}
+
+function crossResourceEdges(relativePath: string): string[] {
+  const directory = directoryOf(relativePath);
+  const owner = directory.split(sep)[0];
+
+  return importedPaths(relativePath)
+    .map((specifier) => resourceOf(specifier, directory))
+    .filter((target): target is string => target !== undefined && target !== owner);
+}
+
+function commandEdges(relativePath: string): string[] {
+  const owner = relativePath.split(sep)[2];
+  const directory = directoryOf(relativePath);
+
+  return importedPaths(relativePath)
+    .map((specifier) => resourceOf(specifier, directory))
+    .filter((target): target is string => target !== undefined && target !== owner);
+}
+
 function resourceImports(relativePath: string): string[] {
   return importedPaths(relativePath).filter((specifier) =>
     RESOURCES.some((resource) => specifier.startsWith(`../${resource}/`) || specifier === `../${resource}`),
   );
 }
 
 describe('layering', () => {
-  it.each(LAYERS.flatMap((layer) => sourceFilesIn(layer)))('%s imports no resource directly', (relativePath) => {
+  it.each(LAYERS.flatMap((layer) => filesUnder(layer)))('%s imports no resource directly', (relativePath) => {
     expect(resourceImports(relativePath)).toEqual([]);
   });
 
@@ -32,17 +84,91 @@ describe('layering', () => {
     expect(sourceFilesIn('transport').length).toBeGreaterThan(0);
   });
 
+  it('checks the test files in core and transport too, not only the production ones', () => {
+    const checked = LAYERS.flatMap((layer) => filesUnder(layer));
+
+    expect(checked).toContain(join('core', 'layering.test.ts'));
+    expect(checked.filter((path) => path.endsWith('.test.ts')).length).toBeGreaterThan(0);
+  });
+
   it('reports a resource import when one is present, so the check cannot pass vacuously', () => {
     const contrived = importedPaths(join('projects', 'project.inputs.ts'));
 
     expect(contrived).toContain('../core/resolution');
-    expect(
-      contrived.filter((specifier) => RESOURCES.some((resource) => specifier.startsWith(`../${resource}/`))),
-    ).toEqual([]);
     expect(
       ['../projects/types', './types'].filter((specifier) =>
         RESOURCES.some((resource) => specifier.startsWith(`../${resource}/`)),
       ),
     ).toEqual(['../projects/types']);
   });
 });
+
+describe('layering between resources', () => {
+  it.each(RESOURCES.flatMap((resource) => filesUnder(resource)))(
+    '%s reaches only the resources its allow-list names',
+    (relativePath) => {
+      const owner = relativePath.split(sep)[0];
+
+      expect(RESOURCE_EDGES[owner]).toBeDefined();
+      for (const target of crossResourceEdges(relativePath)) {
+        expect(RESOURCE_EDGES[owner]).toContain(target);
+      }
+    },
+  );
+
+  it('declares an allow-list entry for every resource and invents none', () => {
+    expect(Object.keys(RESOURCE_EDGES).sort()).toEqual([...RESOURCES].sort());
+    for (const targets of Object.values(RESOURCE_EDGES)) {
+      for (const target of targets) {
+        expect(RESOURCES).toContain(target);
+      }
+    }
+  });
+
+  it('records the edges POST /projects really creates, and no others', () => {
+    expect(RESOURCE_EDGES.projects).toEqual(['environments', 'deployments', 'git']);
+    expect(crossResourceEdges(join('projects', 'project.create.ts')).sort()).toEqual([
+      'deployments',
+      'deployments',
+      'deployments',
+      'deployments',
+      'deployments',
+      'environments',
+      'environments',
+      'environments',
+      'environments',
+      'git',
+    ]);
+  });
+
+  it('reports a disallowed edge rather than passing vacuously', () => {
+    const owner = 'git';
+
+    expect(crossResourceEdges(join('projects', 'project.create.ts')).length).toBeGreaterThan(0);
+    expect(RESOURCE_EDGES[owner]).not.toContain('projects');
+    expect(resourceOf('../projects/types', 'git')).toBe('projects');
+  });
+});
+
+describe('layering of the command files', () => {
+  it.each(filesUnder(join('commands', 'launch')).filter((path) => path.split(sep).length > 3))(
+    '%s reaches its own resource and no other',
+    (relativePath) => {
+      expect(commandEdges(relativePath)).toEqual([]);
+    },
+  );
+
+  it('finds the command files it claims to be checking', () => {
+    const checked = filesUnder(join('commands', 'launch')).filter((path) => path.split(sep).length > 3);
+
+    expect(checked).toContain(join('commands', 'launch', 'projects', 'create.ts'));
+    expect(checked).toContain(join('commands', 'launch', 'functions', 'serve.ts'));
+  });
+
+  it('reports a command reaching another resource rather than passing vacuously', () => {
+    expect(resourceOf('../../../deployments/deployment.watcher', join('commands', 'launch', 'projects'))).toBe(
+      'deployments',
+    );
+    expect(resourceOf('../../../projects/project.create', join('commands', 'launch', 'projects'))).toBe('projects');
+  });
+});

src/core/service-context.test.ts

@@ -2,7 +2,6 @@ import { randomUUID } from 'node:crypto';
 
 import { HttpClient, authHandler, configHandler } from '@contentstack/cli-utilities';
 
-import { ProjectsApi } from '../projects/projects.api';
 import { SessionExpiredError, UnauthenticatedError } from './errors';
 import { UxLike } from './render';
 import { buildServiceContext } from './service-context';
@@ -66,7 +65,8 @@ describe('buildServiceContext', () => {
       isTTY: true,
     });
 
-    expect(built.api.projects).toBeInstanceOf(ProjectsApi);
+    expect(typeof built.api.projects.list).toBe('function');
+    expect(typeof built.api.projects.get).toBe('function');
     expect(built.ux).toBe(UX);
     expect(built.isTTY).toBe(true);
     configSpy.mockRestore();

src/functions/cloud-functions.test.ts

@@ -6,7 +6,7 @@ import { AddressInfo } from 'net';
 import { tmpdir } from 'os';
 import { dirname, join } from 'path';
 
-import { CloudFunctions } from './cloud-functions';
+import { CloudFunctions, listenFailure } from './cloud-functions';
 import { PortInUseError } from './function.errors';
 import { loadDataURL } from './load-data-url';
 
@@ -347,6 +347,41 @@ describe('CloudFunctions serve failures', () => {
     expect((failure as Error).message).toContain('--port');
   });
 
+  it('maps a port clash to a port-in-use error naming the port', () => {
+    const clash = Object.assign(new Error('listen EADDRINUSE'), { code: 'EADDRINUSE' });
+
+    const mapped = listenFailure(clash, 4321);
+
+    expect(mapped).toBeInstanceOf(PortInUseError);
+    expect(mapped.message).toContain('4321');
+  });
+
+  it('passes a listen failure that is not a port clash through untouched', () => {
+    const other = Object.assign(new Error('listen EACCES'), { code: 'EACCES' });
+
+    const mapped = listenFailure(other, 4321);
+
+    expect(mapped).toBe(other);
+    expect(mapped).not.toBeInstanceOf(PortInUseError);
+  });
+
+  it('logs an error raised after the server is already listening rather than rejecting', async () => {
+    writeFunctionFile('hello.js', 'export default function hello(request, response) { response.send("hi"); }');
+    const logged: unknown[] = [];
+    const errorSpy = jest.spyOn(console, 'error').mockImplementation((value: unknown) => {
+      logged.push(value);
+    });
+    const server = (await new CloudFunctions(workspace).serve(await freePort())) as Server;
+    const late = new Error('late failure');
+
+    server.emit('error', late);
+
+    expect(logged).toEqual([late]);
+
+    errorSpy.mockRestore();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  });
+
   it('propagates a listen failure that is not a port clash', async () => {
     writeFunctionFile('hello.js', 'export default function hello(request, response) { response.send("hi"); }');
 

src/functions/cloud-functions.ts

@@ -23,6 +23,10 @@ import commonjs from '@rollup/plugin-commonjs';
 import json from '@rollup/plugin-json';
 import { loadDataURL } from './load-data-url';
 
+export function listenFailure(error: NodeJS.ErrnoException, servingPort: number): Error {
+  return error.code === 'EADDRINUSE' ? new PortInUseError(servingPort) : error;
+}
+
 export class CloudFunctions {
   private cloudFunctionsDirectoryPath: string;
   private pathToSourceCode: string;
@@ -35,7 +39,7 @@ export class CloudFunctions {
     this.pathToSourceCode = pathToSourceCode;
   }
 
-  async serve(servingPort: number): Promise<void> {
+  async serve(servingPort: number): Promise<Server | undefined> {
     const directoryExists = checkIfDirectoryExists(
       this.cloudFunctionsDirectoryPath
     );
@@ -68,7 +72,7 @@ export class CloudFunctions {
 
     dotenv.config({ path: path.join(this.pathToSourceCode, ENV_FILE_NAME) });
 
-    await this.startServer(app, servingPort);
+    return this.startServer(app, servingPort);
   }
 
   private startServer(app: Express, servingPort: number): Promise<Server> {
@@ -87,7 +91,7 @@ export class CloudFunctions {
           return;
         }
 
-        reject(error.code === 'EADDRINUSE' ? new PortInUseError(servingPort) : error);
+        reject(listenFailure(error, servingPort));
       });
     });
   }

src/projects/project.create.ts

@@ -22,6 +22,9 @@ import { PROJECT_TYPE_BY_CHOICE, PROJECT_TYPE_CHOICES, ProjectTypeChoice, projec
 import { uploadArchive } from './project.upload';
 import type { CreateProjectInput, DetectedFramework, Project } from './types';
 
+export { DEPLOYMENT_WAIT_TIMEOUT_MS, defaultWatchTiming } from '../deployments/deployment.watcher';
+export { serverCommandFrameworkGate } from '../environments/environment.inputs';
+
 export const DEFAULT_OUTPUT_DIRECTORY = './';
 export const NO_DEPLOYMENT_STATUS = 'NONE';
 export const FIRST_LOOKUP_ATTEMPTS = 3;
@@ -170,15 +173,17 @@ export class ProjectCreator {
   }
 
   private async appearing<T>(lookup: () => Promise<T | undefined>): Promise<T | undefined> {
-    for (let attempt = 1; ; attempt += 1) {
+    for (let attempt = 1; attempt < FIRST_LOOKUP_ATTEMPTS; attempt += 1) {
       const found = await lookup();
 
-      if (found !== undefined || attempt >= FIRST_LOOKUP_ATTEMPTS) {
+      if (found !== undefined) {
         return found;
       }
 
       await this.timing.sleep(this.timing.pollDelayMs);
     }
+
+    return lookup();
   }
 
   private async follow(org: string, project: Project, envName: string): Promise<void> {