@ankhorage/infra 0.2.1 → 0.3.1

package/src/metadata/index.ts

@@ -0,0 +1,7 @@
+export {
+  INFRA_CAPABILITIES,
+  INFRA_COMMAND_CATEGORY,
+  INFRA_PACKAGE_METADATA,
+  INFRA_PACKAGE_NAME,
+  INFRA_PACKAGE_VERSION,
+} from '../packageMetadata.js';

package/src/package.test.ts

@@ -0,0 +1,27 @@
+import type { AnkhPackageMetadata } from '@ankhorage/contracts/cli';
+import { describe, expect, test } from 'bun:test';
+
+import packageJson from '../package.json';
+
+describe('package metadata', () => {
+  test('publishes the expected Ankh metadata and bin entry', () => {
+    const expectedAnkhMetadata = {
+      category: 'infra',
+      provider: './dist/cli/index.js',
+      capabilities: ['infra.validate', 'infra.generate', 'infra.status', 'infra.up', 'infra.down'],
+    } as const satisfies AnkhPackageMetadata;
+
+    expect(packageJson.name).toBe('@ankhorage/infra');
+    expect(packageJson.type).toBe('module');
+    expect(packageJson.bin).toEqual({
+      'ankhorage-infra': './dist/cli.js',
+    });
+    expect(packageJson.ankh).toEqual(expectedAnkhMetadata);
+    expect(JSON.parse(JSON.stringify(expectedAnkhMetadata))).toEqual(expectedAnkhMetadata);
+
+    const capabilityText = JSON.stringify(packageJson.ankh.capabilities);
+    expect(capabilityText).not.toContain('portForward');
+    expect(capabilityText).not.toContain('port-forward');
+    expect(capabilityText).not.toContain('port.forward');
+  });
+});

package/src/packageMetadata.ts

@@ -0,0 +1,24 @@
+import type {
+  AnkhCapabilityId,
+  AnkhCommandCategory,
+  AnkhPackageMetadata,
+} from '@ankhorage/contracts/cli';
+
+import packageJson from '../package.json';
+
+export const INFRA_PACKAGE_NAME = packageJson.name;
+export const INFRA_PACKAGE_VERSION = packageJson.version;
+export const INFRA_COMMAND_CATEGORY = 'infra' as const satisfies AnkhCommandCategory;
+export const INFRA_CAPABILITIES = [
+  'infra.validate',
+  'infra.generate',
+  'infra.status',
+  'infra.up',
+  'infra.down',
+] as const satisfies readonly AnkhCapabilityId[];
+
+export const INFRA_PACKAGE_METADATA = {
+  category: INFRA_COMMAND_CATEGORY,
+  provider: './dist/ankh.provider.js',
+  capabilities: INFRA_CAPABILITIES,
+} as const satisfies AnkhPackageMetadata;

package/src/project.test.ts

@@ -0,0 +1,218 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { promises as fs } from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { resolveInfraProject } from './project.js';
+import { createAppManifest, createWorkspaceFixture } from './testSupport.js';
+
+const tempRoots = new Set<string>();
+
+afterEach(async () => {
+  await Promise.all(
+    [...tempRoots].map((rootPath) => fs.rm(rootPath, { force: true, recursive: true })),
+  );
+  tempRoots.clear();
+});
+
+describe('resolveInfraProject', () => {
+  test('resolves an explicit project id from the workspace root', async () => {
+    const fixture = await createWorkspaceFixture();
+    tempRoots.add(fixture.rootPath);
+
+    const project = await resolveInfraProject({
+      cwd: fixture.rootPath,
+      projectId: fixture.projectId,
+    });
+
+    expect(project.projectId).toBe('shop');
+    expect(project.projectPath).toBe(fixture.projectPath);
+    expect(project.workspaceRoot).toBe(fixture.rootPath);
+  });
+
+  test('infers the project id from cwd inside apps/<project>', async () => {
+    const fixture = await createWorkspaceFixture();
+    tempRoots.add(fixture.rootPath);
+
+    const nestedPath = path.join(fixture.projectPath, 'src', 'modules');
+    await fs.mkdir(nestedPath, { recursive: true });
+
+    const project = await resolveInfraProject({
+      cwd: nestedPath,
+    });
+
+    expect(project.projectId).toBe('shop');
+    expect(project.projectPath).toBe(fixture.projectPath);
+  });
+
+  test('loads the fallback manifest when ankh.config.json is missing', async () => {
+    const fixture = await createWorkspaceFixture({
+      manifestFile: 'missing',
+    });
+    tempRoots.add(fixture.rootPath);
+
+    const project = await resolveInfraProject({
+      cwd: fixture.rootPath,
+      projectId: fixture.projectId,
+    });
+
+    expect(project.manifest.metadata.name).toBe('shop');
+    expect(project.manifest.metadata.slug).toBe('shop');
+    expect(project.manifest.infra.plugins).toEqual([]);
+  });
+
+  test('rejects malformed manifest JSON', async () => {
+    const fixture = await createWorkspaceFixture({
+      manifestFile: 'invalid-json',
+    });
+    tempRoots.add(fixture.rootPath);
+
+    await expectRejectMessage(
+      resolveInfraProject({
+        cwd: fixture.rootPath,
+        projectId: fixture.projectId,
+      }),
+      'Project manifest is not valid JSON',
+    );
+  });
+
+  test('rejects traversal project ids', async () => {
+    const fixture = await createWorkspaceFixture();
+    tempRoots.add(fixture.rootPath);
+
+    await expectRejectMessage(
+      resolveInfraProject({
+        cwd: fixture.rootPath,
+        projectId: '../shop',
+      }),
+      'Invalid project id:',
+    );
+  });
+
+  test('rejects explicit project ids with nested traversal segments', async () => {
+    const fixture = await createWorkspaceFixture();
+    tempRoots.add(fixture.rootPath);
+
+    await expectRejectMessage(
+      resolveInfraProject({
+        cwd: fixture.rootPath,
+        projectId: 'shop/../other',
+      }),
+      'Invalid project id:',
+    );
+  });
+
+  test('rejects explicit absolute project ids', async () => {
+    const fixture = await createWorkspaceFixture();
+    tempRoots.add(fixture.rootPath);
+
+    await expectRejectMessage(
+      resolveInfraProject({
+        cwd: fixture.rootPath,
+        projectId: '/tmp/shop',
+      }),
+      'Invalid project id:',
+    );
+  });
+
+  test('rejects explicit dot project ids', async () => {
+    const fixture = await createWorkspaceFixture();
+    tempRoots.add(fixture.rootPath);
+
+    await expectRejectMessage(
+      resolveInfraProject({
+        cwd: fixture.rootPath,
+        projectId: '.',
+      }),
+      'Invalid project id:',
+    );
+  });
+
+  test('rejects explicit dot-dot project ids', async () => {
+    const fixture = await createWorkspaceFixture();
+    tempRoots.add(fixture.rootPath);
+
+    await expectRejectMessage(
+      resolveInfraProject({
+        cwd: fixture.rootPath,
+        projectId: '..',
+      }),
+      'Invalid project id:',
+    );
+  });
+
+  test('rejects explicit empty project ids', async () => {
+    const fixture = await createWorkspaceFixture();
+    tempRoots.add(fixture.rootPath);
+
+    await expectRejectMessage(
+      resolveInfraProject({
+        cwd: fixture.rootPath,
+        projectId: '',
+      }),
+      'Invalid project id:',
+    );
+  });
+
+  test('rejects explicit blank project ids', async () => {
+    const fixture = await createWorkspaceFixture();
+    tempRoots.add(fixture.rootPath);
+
+    await expectRejectMessage(
+      resolveInfraProject({
+        cwd: fixture.rootPath,
+        projectId: '   ',
+      }),
+      'Invalid project id:',
+    );
+  });
+
+  test('fails when no workspace root can be found', async () => {
+    const rootPath = await fs.mkdtemp(path.join(os.tmpdir(), 'infra-no-root-'));
+    tempRoots.add(rootPath);
+
+    await expectRejectMessage(
+      resolveInfraProject({
+        cwd: rootPath,
+        projectId: 'shop',
+      }),
+      'Could not find an Ankh workspace root',
+    );
+  });
+
+  test('reads a valid project manifest', async () => {
+    const manifest = createAppManifest('cards', {
+      deployment: {
+        monitoring: false,
+        target: 'minikube',
+      },
+      plugins: [],
+    });
+    const fixture = await createWorkspaceFixture({
+      manifest,
+      projectId: 'cards',
+    });
+    tempRoots.add(fixture.rootPath);
+
+    const project = await resolveInfraProject({
+      cwd: fixture.rootPath,
+      projectId: 'cards',
+    });
+
+    expect(project.manifest.metadata.name).toBe('cards');
+    expect(project.manifest.infra.deployment?.target).toBe('minikube');
+  });
+});
+
+async function expectRejectMessage(promise: Promise<unknown>, text: string): Promise<void> {
+  let didReject = false;
+
+  try {
+    await promise;
+  } catch (error) {
+    didReject = true;
+    expect(error instanceof Error ? error.message : String(error)).toContain(text);
+  }
+
+  expect(didReject).toBe(true);
+}

package/src/project.ts

@@ -0,0 +1,270 @@
+import type { AppManifest, AuthFlowConfig, NavigatorSpec } from '@ankhorage/contracts';
+import { promises as fs } from 'fs';
+import path from 'path';
+
+export interface ResolvedInfraProject {
+  readonly appsRoot: string;
+  readonly manifest: AppManifest;
+  readonly manifestPath: string;
+  readonly projectId: string;
+  readonly projectPath: string;
+  readonly workspaceRoot: string;
+}
+
+export async function resolveInfraProject(options: {
+  readonly cwd: string;
+  readonly projectId?: string;
+}): Promise<ResolvedInfraProject> {
+  const workspaceRoot = await findWorkspaceRoot(options.cwd);
+  if (workspaceRoot === null) {
+    throw new Error(`Could not find an Ankh workspace root from cwd: ${options.cwd}`);
+  }
+
+  const appsRoot = path.join(workspaceRoot, 'apps');
+  const projectId =
+    options.projectId === undefined
+      ? inferProjectId(options.cwd, appsRoot)
+      : validateExplicitProjectId(options.projectId);
+  if (projectId === null) {
+    throw new Error(
+      'Could not infer a project from cwd. Pass a project id or run the command inside apps/<project>.',
+    );
+  }
+
+  const projectPath = resolveProjectPath(appsRoot, projectId);
+  if (!(await pathExists(projectPath))) {
+    throw new Error(`Project '${projectId}' not found.`);
+  }
+
+  const manifestPath = path.join(projectPath, 'ankh.config.json');
+  const manifest = await readProjectManifest({
+    manifestPath,
+    projectId,
+    projectPath,
+  });
+
+  return {
+    appsRoot,
+    manifest,
+    manifestPath,
+    projectId,
+    projectPath,
+    workspaceRoot,
+  };
+}
+
+function resolveProjectPath(appsRoot: string, projectId: string): string {
+  const projectPath = path.resolve(appsRoot, projectId);
+  const appsRootPath = `${path.resolve(appsRoot)}${path.sep}`;
+
+  if (!projectPath.startsWith(appsRootPath)) {
+    throw new Error('Security check failed while resolving the project path.');
+  }
+
+  return projectPath;
+}
+
+function createFallbackManifest(projectId: string): AppManifest {
+  return {
+    metadata: {
+      name: projectId,
+      slug: projectId,
+      version: '0.0.0',
+      themeId: 'default',
+    },
+    themes: [],
+    activeThemeId: 'default',
+    infra: {
+      plugins: [],
+    },
+    navigator: {
+      type: 'stack',
+      routes: [{ name: 'index', screenId: 'index' }],
+    },
+    screens: {},
+    settings: {
+      localization: {
+        defaultLocale: 'en',
+        locales: ['en'],
+      },
+      authFlow: {
+        signInRoute: '/sign-in',
+        signOutRoute: '/sign-out',
+        postSignInRoute: '/',
+        unauthorizedRoute: '/sign-in',
+      },
+    },
+  };
+}
+
+async function readProjectManifest(args: {
+  readonly manifestPath: string;
+  readonly projectId: string;
+  readonly projectPath: string;
+}): Promise<AppManifest> {
+  if (!(await pathExists(args.manifestPath))) {
+    return createFallbackManifest(args.projectId);
+  }
+
+  const rawManifest = await fs.readFile(args.manifestPath, 'utf8');
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawManifest);
+  } catch (error) {
+    throw new Error(
+      `Project manifest is not valid JSON: ${args.manifestPath}: ${getErrorMessage(error)}`,
+      { cause: error },
+    );
+  }
+
+  if (!isAppManifest(parsed)) {
+    throw new Error(`Project manifest has an invalid shape: ${args.manifestPath}`);
+  }
+
+  return parsed;
+}
+
+async function findWorkspaceRoot(startPath: string): Promise<string | null> {
+  let currentPath = path.resolve(startPath);
+
+  for (;;) {
+    const appsRoot = path.join(currentPath, 'apps');
+    if (await isDirectory(appsRoot)) {
+      return currentPath;
+    }
+
+    const parentPath = path.dirname(currentPath);
+    if (parentPath === currentPath) {
+      return null;
+    }
+
+    currentPath = parentPath;
+  }
+}
+
+function inferProjectId(cwd: string, appsRoot: string): string | null {
+  const relativePath = path.relative(path.resolve(appsRoot), path.resolve(cwd));
+  if (relativePath === '' || relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+    return null;
+  }
+
+  const [projectId] = relativePath.split(path.sep);
+  return projectId === undefined || projectId.length === 0 ? null : path.basename(projectId);
+}
+
+function validateExplicitProjectId(projectId: string): string {
+  if (projectId.trim().length === 0) {
+    throw new Error('Invalid project id: expected a single safe project segment.');
+  }
+
+  if (
+    projectId === '.' ||
+    projectId === '..' ||
+    path.isAbsolute(projectId) ||
+    projectId.includes('/') ||
+    projectId.includes('\\')
+  ) {
+    throw new Error(`Invalid project id: ${projectId}. Expected a single safe project segment.`);
+  }
+
+  return projectId;
+}
+
+function isAppManifest(value: unknown): value is AppManifest {
+  if (!isRecord(value)) {
+    return false;
+  }
+
+  return (
+    isAppManifestMetadata(value.metadata) &&
+    Array.isArray(value.themes) &&
+    typeof value.activeThemeId === 'string' &&
+    isInfraManifestRecord(value.infra) &&
+    isNavigatorSpec(value.navigator) &&
+    isRecord(value.screens) &&
+    isSettingsRecord(value.settings)
+  );
+}
+
+function isAppManifestMetadata(value: unknown): value is AppManifest['metadata'] {
+  return (
+    isRecord(value) &&
+    typeof value.name === 'string' &&
+    typeof value.slug === 'string' &&
+    typeof value.version === 'string' &&
+    typeof value.themeId === 'string' &&
+    (value.created === undefined || typeof value.created === 'string') &&
+    (value.updated === undefined || typeof value.updated === 'string')
+  );
+}
+
+function isInfraManifestRecord(value: unknown): value is AppManifest['infra'] {
+  return isRecord(value) && Array.isArray(value.plugins);
+}
+
+function isNavigatorSpec(value: unknown): value is NavigatorSpec {
+  return (
+    isRecord(value) &&
+    typeof value.type === 'string' &&
+    Array.isArray(value.routes) &&
+    (value.initialRouteName === undefined || typeof value.initialRouteName === 'string')
+  );
+}
+
+function isSettingsRecord(value: unknown): value is AppManifest['settings'] {
+  return (
+    isRecord(value) &&
+    (value.apiBaseUrl === undefined || typeof value.apiBaseUrl === 'string') &&
+    isLocalizationRecord(value.localization) &&
+    isAuthFlowConfig(value.authFlow)
+  );
+}
+
+function isLocalizationRecord(value: unknown): value is AppManifest['settings']['localization'] {
+  return (
+    isRecord(value) &&
+    typeof value.defaultLocale === 'string' &&
+    Array.isArray(value.locales) &&
+    value.locales.every((locale) => typeof locale === 'string')
+  );
+}
+
+function isAuthFlowConfig(value: unknown): value is AuthFlowConfig {
+  return (
+    isRecord(value) &&
+    typeof value.signInRoute === 'string' &&
+    typeof value.postSignInRoute === 'string' &&
+    (value.signUpRoute === undefined || typeof value.signUpRoute === 'string') &&
+    (value.signOutRoute === undefined || typeof value.signOutRoute === 'string') &&
+    (value.forgotPasswordRoute === undefined || typeof value.forgotPasswordRoute === 'string') &&
+    (value.otpRoute === undefined || typeof value.otpRoute === 'string') &&
+    (value.unauthorizedRoute === undefined || typeof value.unauthorizedRoute === 'string')
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+async function isDirectory(filePath: string): Promise<boolean> {
+  try {
+    const stat = await fs.stat(filePath);
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}