@ankhorage/contracts 7.1.0 → 7.3.0

package/src/appManifest.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, it } from 'bun:test';
+
+import { isAppManifest, parseAppManifest } from './appManifest';
+
+function createManifest(): Record<string, unknown> {
+  return {
+    metadata: {
+      name: 'Example',
+      slug: 'example',
+      version: '1.0.0',
+      category: 'developer_tools',
+      themeId: 'default',
+    },
+    themes: [
+      {
+        id: 'default',
+        name: 'Default',
+        light: { primaryColor: '#3366ff', harmony: 'analogous' },
+        dark: { primaryColor: '#6699ff', harmony: 'analogous' },
+      },
+    ],
+    activeThemeId: 'default',
+    activeThemeMode: 'light',
+    splashScreen: {
+      image: './assets/splash.png',
+      resizeMode: 'contain',
+      backgroundColor: '#ffffff',
+      dark: { backgroundColor: '#000000' },
+    },
+    media: {
+      assets: {
+        hero: {
+          id: 'hero',
+          name: 'Hero image',
+          kind: 'image',
+          source: { kind: 'storage', bucket: 'media', path: 'studio/hero.webp' },
+        },
+      },
+    },
+    infra: {
+      deployment: { target: 'minikube', monitoring: true },
+      database: { provider: 'supabase', tier: 'dev' },
+      storage: { provider: 'auto', buckets: ['media'] },
+      state: { provider: 'legend', persistence: 'local' },
+      networking: { domain: 'example.test', cdn: false },
+      modules: ['expo-localization'],
+      modulesConfig: { localization: { defaultLocale: 'en' } },
+    },
+    navigator: {
+      type: 'stack',
+      initialRouteName: 'home',
+      routes: [
+        {
+          name: 'home',
+          path: '/',
+          screenId: 'home',
+          showInPrimaryNavigation: true,
+        },
+      ],
+    },
+    screens: {
+      home: {
+        id: 'home',
+        name: 'Home',
+        root: {
+          id: 'root',
+          type: 'Stack',
+          children: [
+            {
+              id: 'title',
+              type: 'Text',
+              repeat: { source: { kind: 'state', path: 'items' }, itemAlias: 'item' },
+            },
+          ],
+        },
+        dataLoaders: [
+          {
+            kind: 'operation',
+            id: 'load-users',
+            operation: { dataSourceId: 'external', endpointId: 'main', operationId: 'list' },
+          },
+        ],
+        requires: {
+          permissions: [{ permission: 'camera' }],
+          capabilities: [{ capability: 'barcodeScanner' }],
+        },
+      },
+    },
+    generatedApis: {
+      users: {
+        id: 'users',
+        protocol: 'rest',
+        basePath: '/users',
+        database: { id: 'primary', kind: 'database' },
+        resources: [
+          {
+            id: 'users',
+            path: '/users',
+            collection: {
+              name: 'users',
+              fields: [{ name: 'id', type: 'uuid', required: true }],
+              primaryKey: 'id',
+            },
+            operations: ['list', 'read'],
+          },
+        ],
+      },
+    },
+    dataSources: {
+      external: {
+        id: 'external',
+        kind: 'api',
+        origin: 'external',
+        protocol: 'rest',
+        baseUrl: 'https://example.test',
+        endpoints: {
+          main: {
+            id: 'main',
+            kind: 'http',
+            operations: {
+              list: { id: 'list', protocol: 'rest', intent: 'read', path: '/users' },
+            },
+          },
+        },
+      },
+    },
+    dataBindings: {
+      title: {
+        componentId: 'title',
+        props: { text: { source: { kind: 'state', path: 'title' } } },
+        events: {
+          press: [{ target: { kind: 'action', type: 'console' } }],
+        },
+      },
+    },
+    settings: {
+      apiBaseUrl: 'https://example.test/api',
+      localization: { defaultLocale: 'en', locales: ['en', 'de'] },
+    },
+  };
+}
+
+describe('AppManifest runtime parsing', () => {
+  it('accepts the canonical manifest including optional nested sections', () => {
+    const manifest = createManifest();
+
+    expect(isAppManifest(manifest)).toBe(true);
+    expect(parseAppManifest(manifest)).toEqual({ ok: true, manifest });
+  });
+
+  it('rejects missing required top-level sections', () => {
+    const manifest = createManifest();
+    delete manifest.settings;
+
+    expect(isAppManifest(manifest)).toBe(false);
+  });
+
+  it('rejects malformed nested canonical structures', () => {
+    const manifest = createManifest();
+    const themes = manifest.themes as Record<string, unknown>[];
+    const light = themes[0]?.light as Record<string, unknown>;
+    light.harmony = 'not-a-harmony';
+
+    expect(parseAppManifest(manifest)).toEqual({
+      ok: false,
+      message: 'Value is not a canonical AppManifest.',
+    });
+  });
+
+  it('rejects transient media URLs at the manifest boundary', () => {
+    const manifest = createManifest();
+    const media = manifest.media as Record<string, Record<string, Record<string, unknown>>>;
+    media.assets.hero.source = { kind: 'url', url: 'blob:https://example.test/transient' };
+
+    expect(isAppManifest(manifest)).toBe(false);
+  });
+
+  it('rejects legacy infra plugin state', () => {
+    const manifest = createManifest();
+    const infra = manifest.infra as Record<string, unknown>;
+    infra.plugins = ['legacy'];
+
+    expect(isAppManifest(manifest)).toBe(false);
+  });
+
+  it('rejects screen registries whose key disagrees with screen id', () => {
+    const manifest = createManifest();
+    const screens = manifest.screens as Record<string, unknown>;
+    screens.other = screens.home;
+    delete screens.home;
+
+    expect(isAppManifest(manifest)).toBe(false);
+  });
+
+  it('rejects invalid data-binding source kinds', () => {
+    const manifest = createManifest();
+    const bindings = manifest.dataBindings as Record<string, Record<string, unknown>>;
+    const props = bindings.title?.props as Record<string, Record<string, unknown>>;
+    props.text = { source: { kind: 'provider-specific', path: 'title' } };
+
+    expect(isAppManifest(manifest)).toBe(false);
+  });
+});

package/src/appManifest.ts

@@ -0,0 +1,89 @@
+import { isComponentDataBindingRegistry } from './appManifest/bindings';
+import { isDataSourceRegistry } from './appManifest/dataSources';
+import { isGeneratedApiRegistry } from './appManifest/generatedApis';
+import { isInfraManifest } from './appManifest/infra';
+import { isMediaManifest } from './appManifest/media';
+import {
+  isManifestMetadata,
+  isNavigatorSpec,
+  isScreenRegistry,
+  isSplashScreenSpec,
+  isThemeConfig,
+} from './appManifest/screens';
+import { isOptionalString, isRecord, isStringArray } from './appManifest/shared';
+import type { AppManifest } from './types';
+
+export type AppManifestParseResult =
+  | { readonly ok: true; readonly manifest: AppManifest }
+  | { readonly ok: false; readonly message: string };
+
+const APP_MANIFEST_KEY_POLICY = {
+  metadata: 'required',
+  themes: 'required',
+  activeThemeId: 'required',
+  activeThemeMode: 'optional',
+  splashScreen: 'optional',
+  media: 'optional',
+  infra: 'required',
+  navigator: 'required',
+  screens: 'required',
+  generatedApis: 'optional',
+  dataSources: 'optional',
+  dataBindings: 'optional',
+  settings: 'required',
+} as const satisfies Record<keyof AppManifest, 'optional' | 'required'>;
+
+/**
+ * Parse unknown JSON-compatible input at the canonical AppManifest boundary.
+ *
+ * Contracts owns structural manifest validation. Consumers may add semantic
+ * diagnostics after this parser succeeds, but should not reconstruct the
+ * AppManifest shape in their own packages.
+ */
+export function parseAppManifest(value: unknown): AppManifestParseResult {
+  return isAppManifest(value)
+    ? { ok: true, manifest: value }
+    : { ok: false, message: 'Value is not a canonical AppManifest.' };
+}
+
+/** Return whether an unknown value satisfies the canonical AppManifest shape. */
+export function isAppManifest(value: unknown): value is AppManifest {
+  return (
+    isRecord(value) &&
+    hasRequiredManifestKeys(value) &&
+    isManifestMetadata(value.metadata) &&
+    Array.isArray(value.themes) &&
+    value.themes.every(isThemeConfig) &&
+    typeof value.activeThemeId === 'string' &&
+    isActiveThemeMode(value.activeThemeMode) &&
+    (value.splashScreen === undefined || isSplashScreenSpec(value.splashScreen)) &&
+    (value.media === undefined || isMediaManifest(value.media)) &&
+    isInfraManifest(value.infra) &&
+    isNavigatorSpec(value.navigator) &&
+    isScreenRegistry(value.screens) &&
+    (value.generatedApis === undefined || isGeneratedApiRegistry(value.generatedApis)) &&
+    (value.dataSources === undefined || isDataSourceRegistry(value.dataSources)) &&
+    (value.dataBindings === undefined || isComponentDataBindingRegistry(value.dataBindings)) &&
+    isAppSettings(value.settings)
+  );
+}
+
+function hasRequiredManifestKeys(value: Record<string, unknown>): boolean {
+  return Object.entries(APP_MANIFEST_KEY_POLICY).every(
+    ([key, policy]) => policy === 'optional' || key in value,
+  );
+}
+
+function isActiveThemeMode(value: unknown): boolean {
+  return value === undefined || value === 'dark' || value === 'light';
+}
+
+function isAppSettings(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    isRecord(value.localization) &&
+    typeof value.localization.defaultLocale === 'string' &&
+    isStringArray(value.localization.locales) &&
+    isOptionalString(value.apiBaseUrl)
+  );
+}

package/src/index.ts

@@ -1,8 +1,10 @@
+export * from './appManifest';
 export * from './auth';
 export * from './bindings';
 export * from './cli';
 export * from './data';
 export * from './db';
+export * from './media';
 export * from './requirements';
 export * from './runtimeCallbacks';
 export * from './secretManifest';

package/src/media.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'bun:test';
+
+import { isMediaManifest } from './appManifest/media';
+import { isMediaAssetReference } from './media';
+
+function createMediaManifest() {
+  return {
+    assets: {
+      hero: {
+        id: 'hero',
+        name: 'Hero image',
+        kind: 'image',
+        source: { kind: 'storage', bucket: 'media', path: 'studio/hero.webp' },
+        contentType: 'image/webp',
+        metadata: { width: 1600, height: 900, sizeBytes: 42000 },
+      },
+      logo: {
+        id: 'logo',
+        name: 'Logo',
+        kind: 'image',
+        source: { kind: 'bundled', path: 'assets/logo.png' },
+      },
+      remote: {
+        id: 'remote',
+        name: 'Remote image',
+        kind: 'image',
+        source: { kind: 'url', url: 'https://example.test/image.png' },
+      },
+    },
+  };
+}
+
+describe('media contracts', () => {
+  it('accepts storage, bundled, and stable URL authoring media', () => {
+    expect(isMediaManifest(createMediaManifest())).toBe(true);
+  });
+
+  it('requires registry keys to match media asset ids', () => {
+    const media = createMediaManifest();
+    media.assets.hero.id = 'other';
+
+    expect(isMediaManifest(media)).toBe(false);
+  });
+
+  it('rejects transient or local URL schemes', () => {
+    for (const url of [
+      'blob:https://example.test/id',
+      'file:///tmp/image.png',
+      'data:image/png;base64,x',
+    ]) {
+      const media = createMediaManifest();
+      media.assets.remote.source = { kind: 'url', url };
+      expect(isMediaManifest(media)).toBe(false);
+    }
+  });
+
+  it('rejects denormalized public URLs on managed storage sources', () => {
+    const media = createMediaManifest();
+    const source = media.assets.hero.source as Record<string, unknown>;
+    source.publicUrl = 'https://example.test/public/hero.webp';
+
+    expect(isMediaManifest(media)).toBe(false);
+  });
+
+  it('validates stable media references', () => {
+    expect(isMediaAssetReference({ mediaId: 'hero' })).toBe(true);
+    expect(isMediaAssetReference({ mediaId: 'hero', url: 'blob:local' })).toBe(false);
+    expect(isMediaAssetReference({ mediaId: '' })).toBe(false);
+  });
+});

package/src/media.ts

@@ -0,0 +1,68 @@
+export const MEDIA_ASSET_KINDS = ['image', 'audio', 'video', 'font', 'file'] as const;
+
+export type MediaAssetKind = (typeof MEDIA_ASSET_KINDS)[number];
+
+export interface MediaStorageSource {
+  readonly kind: 'storage';
+  /** Optional logical storage connection identifier for future multi-storage apps. */
+  readonly storageId?: string;
+  readonly bucket: string;
+  readonly path: string;
+}
+
+export interface MediaUrlSource {
+  readonly kind: 'url';
+  /** Stable remote URL. Transient/local URL schemes are not canonical media sources. */
+  readonly url: string;
+}
+
+export interface MediaBundledSource {
+  readonly kind: 'bundled';
+  /** App-relative bundled asset path resolved by the generated/runtime host. */
+  readonly path: string;
+}
+
+export type MediaAssetSource = MediaStorageSource | MediaUrlSource | MediaBundledSource;
+
+export interface MediaAssetMetadata {
+  readonly originalFileName?: string;
+  readonly sizeBytes?: number;
+  readonly createdAt?: string;
+  readonly width?: number;
+  readonly height?: number;
+  readonly durationMs?: number;
+}
+
+/** Canonical Studio-managed authoring media entry. */
+export interface MediaAsset {
+  readonly id: string;
+  readonly name: string;
+  readonly kind: MediaAssetKind;
+  readonly source: MediaAssetSource;
+  readonly contentType?: string;
+  readonly metadata?: MediaAssetMetadata;
+}
+
+export type MediaAssetRegistry = Readonly<Record<string, MediaAsset>>;
+
+/** App-authoring media pool. Runtime/user-generated uploads do not belong here. */
+export interface MediaManifest {
+  readonly assets: MediaAssetRegistry;
+}
+
+/** Stable component/property reference to one entry in `AppManifest.media.assets`. */
+export interface MediaAssetReference {
+  readonly mediaId: string;
+}
+
+export function isMediaAssetReference(value: unknown): value is MediaAssetReference {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.keys(value).length === 1 &&
+    'mediaId' in value &&
+    typeof value.mediaId === 'string' &&
+    value.mediaId.trim().length > 0
+  );
+}

package/src/types.ts

@@ -7,6 +7,7 @@ import type {
   ScreenDataLoaderDefinition,
 } from './bindings';
 import type { DataSourceRegistry, GeneratedApiRegistry } from './data';
+import type { MediaManifest } from './media';
 import type { ScreenRequirements } from './requirements';
 import type { ThemeGlobalTokenOverrides, ThemeRecipeOverrides } from './theme';
 
@@ -398,6 +399,8 @@ export interface AppManifest {
   activeThemeId: string;
   activeThemeMode?: 'dark' | 'light';
   splashScreen?: SplashScreenSpec;
+  /** Studio-managed authoring media. Runtime/user uploads are intentionally separate. */
+  media?: MediaManifest;
   infra: InfraManifest;
   navigator: NavigatorSpec;
   screens: Record<string, ScreenSpec>;