@hyprcart/app-manifest 1.0.0

package/README.md

@@ -0,0 +1,5 @@
+# @hyprcart/app-manifest
+
+Manifest schema and validation helpers for standalone Hyprcart apps.
+
+This package is part of the public Hyprcart app tooling release. It is intended for app projects generated by `create-hyprcart-app` and for CI validation workflows.

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+declare const supportedSurfaces: readonly ["storefront_block", "admin_surface", "checkout_ui", "checkout_function", "pixel", "event", "flow", "mcp"];
+type AppSurfaceKind = (typeof supportedSurfaces)[number];
+type LocaleMessages = Record<string, string>;
+interface AppManifestSurface {
+    id: string;
+    type: AppSurfaceKind;
+    entry: string;
+    label: Record<string, string>;
+    settings?: unknown[];
+    scopes?: string[];
+    deployable?: boolean;
+}
+interface AppManifest {
+    id?: string;
+    name: string;
+    version: string;
+    manifestVersion: string;
+    sdkVersion: string;
+    platformCompatibility: string;
+    surfaces: AppManifestSurface[];
+    scopes: string[];
+    translations: Record<string, LocaleMessages>;
+    egress?: string[];
+    resources?: {
+        bundleSizeBytes?: number;
+        cpuMs?: number;
+        memoryMb?: number;
+    };
+}
+declare const defaultRequiredLocales: readonly ["en", "de"];
+declare function isSupportedSurface(value: string): value is AppSurfaceKind;
+
+type ValidationSeverity = "info" | "warning" | "error" | "blocker";
+interface ValidationIssue {
+    code: string;
+    severity: ValidationSeverity;
+    path: string;
+    message: string;
+    suggestedFix?: string;
+    docsUrl?: string;
+}
+interface ScopeImpact {
+    scope: string;
+    action: "added" | "removed" | "unchanged";
+    dataClass: string;
+    approvalRequired: boolean;
+    reason: string;
+}
+interface TranslationGap {
+    locale: string;
+    key: string;
+    surface: AppSurfaceKind;
+}
+interface TranslationStatus {
+    requiredLocales: string[];
+    completeLocales: string[];
+    missing: TranslationGap[];
+}
+interface ValidationResult {
+    status: "valid" | "warning" | "invalid";
+    manifestHash: string;
+    issues: ValidationIssue[];
+    scopeImpact: ScopeImpact[];
+    translationStatus: TranslationStatus;
+}
+interface ValidationOptions {
+    requiredLocales?: string[];
+    maxBundleSizeBytes?: number;
+    supportedSdkMajor?: number;
+}
+declare function validateManifest(manifest: AppManifest, options?: ValidationOptions): ValidationResult;
+declare function getTranslationStatus(manifest: AppManifest, requiredLocales: string[]): TranslationStatus;
+
+interface GeneratedContractFile {
+    path: string;
+    content: string;
+    purpose: string;
+}
+interface ContractGenerationResult {
+    manifestHash: string;
+    schemaVersion: string;
+    sdkVersion: string;
+    files: GeneratedContractFile[];
+}
+declare function generateContracts(manifest: AppManifest, schemaVersion?: string): ContractGenerationResult;
+
+interface CompatibilityResult {
+    ok: boolean;
+    code?: string;
+    message?: string;
+    docsUrl?: string;
+}
+declare function checkCompatibility(input: {
+    cliVersion?: string;
+    sdkVersion: string;
+    platformVersion: string;
+    requiredSdkMajor?: number;
+}): CompatibilityResult;
+
+declare function generateIdeMetadata(manifest: AppManifest): {
+    schemaVersion: string;
+    platformVersion: string;
+    surfaceContracts: {
+        surface: "storefront_block" | "admin_surface" | "checkout_ui" | "checkout_function" | "pixel" | "event" | "flow" | "mcp";
+        inputTypeName: string;
+        outputTypeName: string;
+        fixtureTypeName: string;
+        scopes: string[];
+    }[];
+    scopeWarnings: ScopeImpact[];
+    translationRequirements: TranslationStatus;
+    docsUrls: string[];
+};
+
+declare const developerToolingOperationMetadata: readonly [{
+    readonly operationName: "validateAppProject";
+    readonly scopes: readonly ["app.validation:run"];
+    readonly dataClass: "developer_app";
+    readonly costClass: "standard";
+    readonly idempotent: true;
+    readonly lifecycleEvents: readonly ["developer_tooling.validation_requested"];
+    readonly docsStatus: "public";
+    readonly stability: "preview";
+}, {
+    readonly operationName: "requestDeveloperDeployment";
+    readonly scopes: readonly ["app.deployment:write"];
+    readonly dataClass: "developer_app";
+    readonly costClass: "elevated";
+    readonly idempotent: true;
+    readonly lifecycleEvents: readonly ["developer_tooling.deployment_requested"];
+    readonly docsStatus: "public";
+    readonly stability: "preview";
+}];
+
+export { type AppManifest, type AppManifestSurface, type AppSurfaceKind, type CompatibilityResult, type ContractGenerationResult, type GeneratedContractFile, type LocaleMessages, type ScopeImpact, type TranslationGap, type TranslationStatus, type ValidationIssue, type ValidationOptions, type ValidationResult, type ValidationSeverity, checkCompatibility, defaultRequiredLocales, developerToolingOperationMetadata, generateContracts, generateIdeMetadata, getTranslationStatus, isSupportedSurface, supportedSurfaces, validateManifest };

package/dist/index.js

@@ -0,0 +1,280 @@
+// src/schema.ts
+var supportedSurfaces = [
+  "storefront_block",
+  "admin_surface",
+  "checkout_ui",
+  "checkout_function",
+  "pixel",
+  "event",
+  "flow",
+  "mcp"
+];
+var defaultRequiredLocales = ["en", "de"];
+function isSupportedSurface(value) {
+  return supportedSurfaces.includes(value);
+}
+
+// src/validation.ts
+var riskyDependencyPatterns = [/child_process/i, /node:fs/i, /eval\(/i];
+function validateManifest(manifest, options = {}) {
+  const requiredLocales = options.requiredLocales ?? [...defaultRequiredLocales];
+  const maxBundleSizeBytes = options.maxBundleSizeBytes ?? 512 * 1024;
+  const supportedSdkMajor = options.supportedSdkMajor ?? 1;
+  const issues = [];
+  if (!manifest.name?.trim()) {
+    issues.push(issue("manifest.name.missing", "blocker", "name", "App name is required."));
+  }
+  if (!manifest.manifestVersion?.trim()) {
+    issues.push(issue("manifest.version.missing", "blocker", "manifestVersion", "Manifest version is required."));
+  }
+  if (!manifest.sdkVersion?.trim()) {
+    issues.push(issue("sdk.version.missing", "blocker", "sdkVersion", "SDK version is required."));
+  } else if (!isCompatibleSdk(manifest.sdkVersion, supportedSdkMajor)) {
+    issues.push(
+      issue(
+        "sdk.version.unsupported",
+        "blocker",
+        "sdkVersion",
+        `SDK version ${manifest.sdkVersion} is not compatible with this platform.`,
+        "Upgrade the app SDK and regenerate contracts.",
+        "https://developer.hyprcart.com/docs/app-platform/sdk"
+      )
+    );
+  }
+  if (!Array.isArray(manifest.surfaces) || manifest.surfaces.length === 0) {
+    issues.push(issue("surfaces.missing", "blocker", "surfaces", "At least one app surface is required."));
+  }
+  manifest.surfaces?.forEach((surface, index) => {
+    const basePath = `surfaces.${index}`;
+    if (!surface.id?.trim()) {
+      issues.push(issue("surface.id.missing", "error", `${basePath}.id`, "Surface id is required."));
+    }
+    if (!isSupportedSurface(surface.type)) {
+      issues.push(issue("surface.type.unsupported", "blocker", `${basePath}.type`, `Unsupported surface type: ${surface.type}`));
+    }
+    if (!surface.entry?.trim()) {
+      issues.push(issue("surface.entry.missing", "error", `${basePath}.entry`, "Surface entry file is required."));
+    }
+    if (surface.deployable === false) {
+      issues.push(
+        issue(
+          "surface.deferred",
+          "warning",
+          `${basePath}.deployable`,
+          "This surface is marked as preview-only and will not be deployed.",
+          "Remove the surface or mark it deployable when the platform supports it."
+        )
+      );
+    }
+  });
+  const translationStatus = getTranslationStatus(manifest, requiredLocales);
+  for (const gap of translationStatus.missing) {
+    issues.push(
+      issue(
+        "validation.translation.missing",
+        gap.surface === "storefront_block" ? "error" : "warning",
+        `translations.${gap.locale}.${gap.key}`,
+        `Missing ${gap.locale} translation for ${gap.key}.`,
+        "Add the missing locale key before deployment.",
+        "https://developer.hyprcart.com/docs/app-platform/translations"
+      )
+    );
+  }
+  if ((manifest.resources?.bundleSizeBytes ?? 0) > maxBundleSizeBytes) {
+    issues.push(
+      issue(
+        "bundle.size.exceeded",
+        "blocker",
+        "resources.bundleSizeBytes",
+        `Bundle size exceeds ${maxBundleSizeBytes} bytes.`,
+        "Remove unused dependencies or split the app surface."
+      )
+    );
+  }
+  for (const domain of manifest.egress ?? []) {
+    if (!domain.startsWith("https://")) {
+      issues.push(issue("egress.domain.invalid", "blocker", "egress", "Egress domains must use https."));
+    }
+    if (riskyDependencyPatterns.some((pattern) => pattern.test(domain))) {
+      issues.push(issue("egress.domain.risky", "blocker", "egress", "Egress declaration contains risky content."));
+    }
+  }
+  const blocker = issues.some((entry) => entry.severity === "blocker" || entry.severity === "error");
+  const warning = issues.some((entry) => entry.severity === "warning");
+  return {
+    status: blocker ? "invalid" : warning ? "warning" : "valid",
+    manifestHash: hashObject(manifest),
+    issues,
+    scopeImpact: (manifest.scopes ?? []).map((scope) => ({
+      scope,
+      action: "added",
+      dataClass: classifyScope(scope),
+      approvalRequired: scope.includes("write") || scope.includes("customer"),
+      reason: "Declared by app manifest."
+    })),
+    translationStatus
+  };
+}
+function getTranslationStatus(manifest, requiredLocales) {
+  const missing = [];
+  const completeLocales = [];
+  for (const locale of requiredLocales) {
+    const messages = manifest.translations?.[locale] ?? {};
+    const before = missing.length;
+    for (const surface of manifest.surfaces ?? []) {
+      const labelKey = `${surface.id}.label`;
+      if (!messages[labelKey]) {
+        missing.push({ locale, key: labelKey, surface: surface.type });
+      }
+    }
+    if (missing.length === before) {
+      completeLocales.push(locale);
+    }
+  }
+  return { requiredLocales, completeLocales, missing };
+}
+function issue(code, severity, path, message, suggestedFix, docsUrl) {
+  return { code, severity, path, message, suggestedFix, docsUrl };
+}
+function classifyScope(scope) {
+  if (scope.includes("customer")) return "customer";
+  if (scope.includes("order")) return "order";
+  if (scope.includes("product")) return "product";
+  return "standard";
+}
+function isCompatibleSdk(version, supportedMajor) {
+  const major = Number(version.split(".")[0]);
+  return Number.isFinite(major) && major === supportedMajor;
+}
+function hashObject(value) {
+  const json = JSON.stringify(value, Object.keys(value).sort());
+  let hash = 0;
+  for (let index = 0; index < json.length; index += 1) {
+    hash = hash * 31 + json.charCodeAt(index) >>> 0;
+  }
+  return `mf_${hash.toString(16).padStart(8, "0")}`;
+}
+
+// src/contract-generation.ts
+function generateContracts(manifest, schemaVersion = "2026-06-06") {
+  const surfaces = manifest.surfaces.map(renderSurfaceContract).join("\n\n");
+  const content = [
+    "/* Generated by Hyprcart app tooling. */",
+    `export const schemaVersion = ${JSON.stringify(schemaVersion)};`,
+    `export const sdkVersion = ${JSON.stringify(manifest.sdkVersion)};`,
+    surfaces
+  ].join("\n");
+  return {
+    manifestHash: stableHash(JSON.stringify(manifest)),
+    schemaVersion,
+    sdkVersion: manifest.sdkVersion,
+    files: [
+      {
+        path: "generated/hyprcart.contracts.ts",
+        content,
+        purpose: "typed surface contracts"
+      }
+    ]
+  };
+}
+function renderSurfaceContract(surface) {
+  const name = toPascalCase(surface.id);
+  return [
+    `export interface ${name}Input {`,
+    `  surface: ${JSON.stringify(surface.type)};`,
+    "  context: Record<string, unknown>;",
+    "}",
+    `export interface ${name}Output {`,
+    "  html?: string;",
+    "  data?: Record<string, unknown>;",
+    "  events?: Array<Record<string, unknown>>;",
+    "}",
+    `export const ${name}Contract = {`,
+    `  id: ${JSON.stringify(surface.id)},`,
+    `  type: ${JSON.stringify(surface.type)},`,
+    `  entry: ${JSON.stringify(surface.entry)},`,
+    `  scopes: ${JSON.stringify(surface.scopes ?? [])}`,
+    "} as const;"
+  ].join("\n");
+}
+function toPascalCase(value) {
+  return value.replace(/[^a-zA-Z0-9]+/g, " ").split(" ").filter(Boolean).map((part) => `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`).join("");
+}
+function stableHash(value) {
+  let hash = 5381;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = hash * 33 ^ value.charCodeAt(index);
+  }
+  return `ct_${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+
+// src/compatibility.ts
+function checkCompatibility(input) {
+  const requiredSdkMajor = input.requiredSdkMajor ?? 1;
+  const sdkMajor = Number(input.sdkVersion.split(".")[0]);
+  if (!Number.isFinite(sdkMajor) || sdkMajor !== requiredSdkMajor) {
+    return {
+      ok: false,
+      code: "sdk.version.unsupported",
+      message: `SDK ${input.sdkVersion} is not compatible with platform ${input.platformVersion}.`,
+      docsUrl: "https://developer.hyprcart.com/docs/app-platform/sdk"
+    };
+  }
+  return { ok: true };
+}
+
+// src/ide-metadata.ts
+function generateIdeMetadata(manifest) {
+  const validation = validateManifest(manifest);
+  const contracts = generateContracts(manifest);
+  return {
+    schemaVersion: contracts.schemaVersion,
+    platformVersion: manifest.platformCompatibility,
+    surfaceContracts: manifest.surfaces.map((surface) => ({
+      surface: surface.type,
+      inputTypeName: `${surface.id}Input`,
+      outputTypeName: `${surface.id}Output`,
+      fixtureTypeName: `${surface.id}Fixture`,
+      scopes: surface.scopes ?? []
+    })),
+    scopeWarnings: validation.scopeImpact,
+    translationRequirements: validation.translationStatus,
+    docsUrls: ["https://developer.hyprcart.com/docs/app-platform/manifest"]
+  };
+}
+
+// src/operation-metadata.ts
+var developerToolingOperationMetadata = [
+  {
+    operationName: "validateAppProject",
+    scopes: ["app.validation:run"],
+    dataClass: "developer_app",
+    costClass: "standard",
+    idempotent: true,
+    lifecycleEvents: ["developer_tooling.validation_requested"],
+    docsStatus: "public",
+    stability: "preview"
+  },
+  {
+    operationName: "requestDeveloperDeployment",
+    scopes: ["app.deployment:write"],
+    dataClass: "developer_app",
+    costClass: "elevated",
+    idempotent: true,
+    lifecycleEvents: ["developer_tooling.deployment_requested"],
+    docsStatus: "public",
+    stability: "preview"
+  }
+];
+export {
+  checkCompatibility,
+  defaultRequiredLocales,
+  developerToolingOperationMetadata,
+  generateContracts,
+  generateIdeMetadata,
+  getTranslationStatus,
+  isSupportedSurface,
+  supportedSurfaces,
+  validateManifest
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts","../src/validation.ts","../src/contract-generation.ts","../src/compatibility.ts","../src/ide-metadata.ts","../src/operation-metadata.ts"],"sourcesContent":["export const supportedSurfaces = [\n  \"storefront_block\",\n  \"admin_surface\",\n  \"checkout_ui\",\n  \"checkout_function\",\n  \"pixel\",\n  \"event\",\n  \"flow\",\n  \"mcp\",\n] as const;\n\nexport type AppSurfaceKind = (typeof supportedSurfaces)[number];\n\nexport type LocaleMessages = Record<string, string>;\n\nexport interface AppManifestSurface {\n  id: string;\n  type: AppSurfaceKind;\n  entry: string;\n  label: Record<string, string>;\n  settings?: unknown[];\n  scopes?: string[];\n  deployable?: boolean;\n}\n\nexport interface AppManifest {\n  id?: string;\n  name: string;\n  version: string;\n  manifestVersion: string;\n  sdkVersion: string;\n  platformCompatibility: string;\n  surfaces: AppManifestSurface[];\n  scopes: string[];\n  translations: Record<string, LocaleMessages>;\n  egress?: string[];\n  resources?: {\n    bundleSizeBytes?: number;\n    cpuMs?: number;\n    memoryMb?: number;\n  };\n}\n\nexport const defaultRequiredLocales = [\"en\", \"de\"] as const;\n\nexport function isSupportedSurface(value: string): value is AppSurfaceKind {\n  return supportedSurfaces.includes(value as AppSurfaceKind);\n}\n","import {\n  defaultRequiredLocales,\n  type AppManifest,\n  type AppSurfaceKind,\n  isSupportedSurface,\n} from \"./schema\";\n\nexport type ValidationSeverity = \"info\" | \"warning\" | \"error\" | \"blocker\";\n\nexport interface ValidationIssue {\n  code: string;\n  severity: ValidationSeverity;\n  path: string;\n  message: string;\n  suggestedFix?: string;\n  docsUrl?: string;\n}\n\nexport interface ScopeImpact {\n  scope: string;\n  action: \"added\" | \"removed\" | \"unchanged\";\n  dataClass: string;\n  approvalRequired: boolean;\n  reason: string;\n}\n\nexport interface TranslationGap {\n  locale: string;\n  key: string;\n  surface: AppSurfaceKind;\n}\n\nexport interface TranslationStatus {\n  requiredLocales: string[];\n  completeLocales: string[];\n  missing: TranslationGap[];\n}\n\nexport interface ValidationResult {\n  status: \"valid\" | \"warning\" | \"invalid\";\n  manifestHash: string;\n  issues: ValidationIssue[];\n  scopeImpact: ScopeImpact[];\n  translationStatus: TranslationStatus;\n}\n\nexport interface ValidationOptions {\n  requiredLocales?: string[];\n  maxBundleSizeBytes?: number;\n  supportedSdkMajor?: number;\n}\n\nconst riskyDependencyPatterns = [/child_process/i, /node:fs/i, /eval\\(/i];\n\nexport function validateManifest(\n  manifest: AppManifest,\n  options: ValidationOptions = {},\n): ValidationResult {\n  const requiredLocales = options.requiredLocales ?? [...defaultRequiredLocales];\n  const maxBundleSizeBytes = options.maxBundleSizeBytes ?? 512 * 1024;\n  const supportedSdkMajor = options.supportedSdkMajor ?? 1;\n  const issues: ValidationIssue[] = [];\n\n  if (!manifest.name?.trim()) {\n    issues.push(issue(\"manifest.name.missing\", \"blocker\", \"name\", \"App name is required.\"));\n  }\n\n  if (!manifest.manifestVersion?.trim()) {\n    issues.push(issue(\"manifest.version.missing\", \"blocker\", \"manifestVersion\", \"Manifest version is required.\"));\n  }\n\n  if (!manifest.sdkVersion?.trim()) {\n    issues.push(issue(\"sdk.version.missing\", \"blocker\", \"sdkVersion\", \"SDK version is required.\"));\n  } else if (!isCompatibleSdk(manifest.sdkVersion, supportedSdkMajor)) {\n    issues.push(\n      issue(\n        \"sdk.version.unsupported\",\n        \"blocker\",\n        \"sdkVersion\",\n        `SDK version ${manifest.sdkVersion} is not compatible with this platform.`,\n        \"Upgrade the app SDK and regenerate contracts.\",\n        \"https://developer.hyprcart.com/docs/app-platform/sdk\",\n      ),\n    );\n  }\n\n  if (!Array.isArray(manifest.surfaces) || manifest.surfaces.length === 0) {\n    issues.push(issue(\"surfaces.missing\", \"blocker\", \"surfaces\", \"At least one app surface is required.\"));\n  }\n\n  manifest.surfaces?.forEach((surface, index) => {\n    const basePath = `surfaces.${index}`;\n    if (!surface.id?.trim()) {\n      issues.push(issue(\"surface.id.missing\", \"error\", `${basePath}.id`, \"Surface id is required.\"));\n    }\n    if (!isSupportedSurface(surface.type)) {\n      issues.push(issue(\"surface.type.unsupported\", \"blocker\", `${basePath}.type`, `Unsupported surface type: ${surface.type}`));\n    }\n    if (!surface.entry?.trim()) {\n      issues.push(issue(\"surface.entry.missing\", \"error\", `${basePath}.entry`, \"Surface entry file is required.\"));\n    }\n    if (surface.deployable === false) {\n      issues.push(\n        issue(\n          \"surface.deferred\",\n          \"warning\",\n          `${basePath}.deployable`,\n          \"This surface is marked as preview-only and will not be deployed.\",\n          \"Remove the surface or mark it deployable when the platform supports it.\",\n        ),\n      );\n    }\n  });\n\n  const translationStatus = getTranslationStatus(manifest, requiredLocales);\n  for (const gap of translationStatus.missing) {\n    issues.push(\n      issue(\n        \"validation.translation.missing\",\n        gap.surface === \"storefront_block\" ? \"error\" : \"warning\",\n        `translations.${gap.locale}.${gap.key}`,\n        `Missing ${gap.locale} translation for ${gap.key}.`,\n        \"Add the missing locale key before deployment.\",\n        \"https://developer.hyprcart.com/docs/app-platform/translations\",\n      ),\n    );\n  }\n\n  if ((manifest.resources?.bundleSizeBytes ?? 0) > maxBundleSizeBytes) {\n    issues.push(\n      issue(\n        \"bundle.size.exceeded\",\n        \"blocker\",\n        \"resources.bundleSizeBytes\",\n        `Bundle size exceeds ${maxBundleSizeBytes} bytes.`,\n        \"Remove unused dependencies or split the app surface.\",\n      ),\n    );\n  }\n\n  for (const domain of manifest.egress ?? []) {\n    if (!domain.startsWith(\"https://\")) {\n      issues.push(issue(\"egress.domain.invalid\", \"blocker\", \"egress\", \"Egress domains must use https.\"));\n    }\n    if (riskyDependencyPatterns.some((pattern) => pattern.test(domain))) {\n      issues.push(issue(\"egress.domain.risky\", \"blocker\", \"egress\", \"Egress declaration contains risky content.\"));\n    }\n  }\n\n  const blocker = issues.some((entry) => entry.severity === \"blocker\" || entry.severity === \"error\");\n  const warning = issues.some((entry) => entry.severity === \"warning\");\n\n  return {\n    status: blocker ? \"invalid\" : warning ? \"warning\" : \"valid\",\n    manifestHash: hashObject(manifest),\n    issues,\n    scopeImpact: (manifest.scopes ?? []).map((scope) => ({\n      scope,\n      action: \"added\",\n      dataClass: classifyScope(scope),\n      approvalRequired: scope.includes(\"write\") || scope.includes(\"customer\"),\n      reason: \"Declared by app manifest.\",\n    })),\n    translationStatus,\n  };\n}\n\nexport function getTranslationStatus(manifest: AppManifest, requiredLocales: string[]): TranslationStatus {\n  const missing: TranslationGap[] = [];\n  const completeLocales: string[] = [];\n\n  for (const locale of requiredLocales) {\n    const messages = manifest.translations?.[locale] ?? {};\n    const before = missing.length;\n    for (const surface of manifest.surfaces ?? []) {\n      const labelKey = `${surface.id}.label`;\n      if (!messages[labelKey]) {\n        missing.push({ locale, key: labelKey, surface: surface.type });\n      }\n    }\n    if (missing.length === before) {\n      completeLocales.push(locale);\n    }\n  }\n\n  return { requiredLocales, completeLocales, missing };\n}\n\nfunction issue(\n  code: string,\n  severity: ValidationSeverity,\n  path: string,\n  message: string,\n  suggestedFix?: string,\n  docsUrl?: string,\n): ValidationIssue {\n  return { code, severity, path, message, suggestedFix, docsUrl };\n}\n\nfunction classifyScope(scope: string): string {\n  if (scope.includes(\"customer\")) return \"customer\";\n  if (scope.includes(\"order\")) return \"order\";\n  if (scope.includes(\"product\")) return \"product\";\n  return \"standard\";\n}\n\nfunction isCompatibleSdk(version: string, supportedMajor: number): boolean {\n  const major = Number(version.split(\".\")[0]);\n  return Number.isFinite(major) && major === supportedMajor;\n}\n\nfunction hashObject(value: unknown): string {\n  const json = JSON.stringify(value, Object.keys(value as Record<string, unknown>).sort());\n  let hash = 0;\n  for (let index = 0; index < json.length; index += 1) {\n    hash = (hash * 31 + json.charCodeAt(index)) >>> 0;\n  }\n  return `mf_${hash.toString(16).padStart(8, \"0\")}`;\n}\n","import type { AppManifest, AppManifestSurface } from \"./schema\";\n\nexport interface GeneratedContractFile {\n  path: string;\n  content: string;\n  purpose: string;\n}\n\nexport interface ContractGenerationResult {\n  manifestHash: string;\n  schemaVersion: string;\n  sdkVersion: string;\n  files: GeneratedContractFile[];\n}\n\nexport function generateContracts(manifest: AppManifest, schemaVersion = \"2026-06-06\"): ContractGenerationResult {\n  const surfaces = manifest.surfaces.map(renderSurfaceContract).join(\"\\n\\n\");\n  const content = [\n    \"/* Generated by Hyprcart app tooling. */\",\n    `export const schemaVersion = ${JSON.stringify(schemaVersion)};`,\n    `export const sdkVersion = ${JSON.stringify(manifest.sdkVersion)};`,\n    surfaces,\n  ].join(\"\\n\");\n\n  return {\n    manifestHash: stableHash(JSON.stringify(manifest)),\n    schemaVersion,\n    sdkVersion: manifest.sdkVersion,\n    files: [\n      {\n        path: \"generated/hyprcart.contracts.ts\",\n        content,\n        purpose: \"typed surface contracts\",\n      },\n    ],\n  };\n}\n\nfunction renderSurfaceContract(surface: AppManifestSurface): string {\n  const name = toPascalCase(surface.id);\n  return [\n    `export interface ${name}Input {`,\n    `  surface: ${JSON.stringify(surface.type)};`,\n    \"  context: Record<string, unknown>;\",\n    \"}\",\n    `export interface ${name}Output {`,\n    \"  html?: string;\",\n    \"  data?: Record<string, unknown>;\",\n    \"  events?: Array<Record<string, unknown>>;\",\n    \"}\",\n    `export const ${name}Contract = {`,\n    `  id: ${JSON.stringify(surface.id)},`,\n    `  type: ${JSON.stringify(surface.type)},`,\n    `  entry: ${JSON.stringify(surface.entry)},`,\n    `  scopes: ${JSON.stringify(surface.scopes ?? [])}`,\n    \"} as const;\",\n  ].join(\"\\n\");\n}\n\nfunction toPascalCase(value: string): string {\n  return value\n    .replace(/[^a-zA-Z0-9]+/g, \" \")\n    .split(\" \")\n    .filter(Boolean)\n    .map((part) => `${part[0]?.toUpperCase() ?? \"\"}${part.slice(1)}`)\n    .join(\"\");\n}\n\nfunction stableHash(value: string): string {\n  let hash = 5381;\n  for (let index = 0; index < value.length; index += 1) {\n    hash = (hash * 33) ^ value.charCodeAt(index);\n  }\n  return `ct_${(hash >>> 0).toString(16).padStart(8, \"0\")}`;\n}\n","export interface CompatibilityResult {\n  ok: boolean;\n  code?: string;\n  message?: string;\n  docsUrl?: string;\n}\n\nexport function checkCompatibility(input: {\n  cliVersion?: string;\n  sdkVersion: string;\n  platformVersion: string;\n  requiredSdkMajor?: number;\n}): CompatibilityResult {\n  const requiredSdkMajor = input.requiredSdkMajor ?? 1;\n  const sdkMajor = Number(input.sdkVersion.split(\".\")[0]);\n\n  if (!Number.isFinite(sdkMajor) || sdkMajor !== requiredSdkMajor) {\n    return {\n      ok: false,\n      code: \"sdk.version.unsupported\",\n      message: `SDK ${input.sdkVersion} is not compatible with platform ${input.platformVersion}.`,\n      docsUrl: \"https://developer.hyprcart.com/docs/app-platform/sdk\",\n    };\n  }\n\n  return { ok: true };\n}\n","import type { AppManifest } from \"./schema\";\nimport { generateContracts } from \"./contract-generation\";\nimport { validateManifest } from \"./validation\";\n\nexport function generateIdeMetadata(manifest: AppManifest) {\n  const validation = validateManifest(manifest);\n  const contracts = generateContracts(manifest);\n\n  return {\n    schemaVersion: contracts.schemaVersion,\n    platformVersion: manifest.platformCompatibility,\n    surfaceContracts: manifest.surfaces.map((surface) => ({\n      surface: surface.type,\n      inputTypeName: `${surface.id}Input`,\n      outputTypeName: `${surface.id}Output`,\n      fixtureTypeName: `${surface.id}Fixture`,\n      scopes: surface.scopes ?? [],\n    })),\n    scopeWarnings: validation.scopeImpact,\n    translationRequirements: validation.translationStatus,\n    docsUrls: [\"https://developer.hyprcart.com/docs/app-platform/manifest\"],\n  };\n}\n","export const developerToolingOperationMetadata = [\n  {\n    operationName: \"validateAppProject\",\n    scopes: [\"app.validation:run\"],\n    dataClass: \"developer_app\",\n    costClass: \"standard\",\n    idempotent: true,\n    lifecycleEvents: [\"developer_tooling.validation_requested\"],\n    docsStatus: \"public\",\n    stability: \"preview\",\n  },\n  {\n    operationName: \"requestDeveloperDeployment\",\n    scopes: [\"app.deployment:write\"],\n    dataClass: \"developer_app\",\n    costClass: \"elevated\",\n    idempotent: true,\n    lifecycleEvents: [\"developer_tooling.deployment_requested\"],\n    docsStatus: \"public\",\n    stability: \"preview\",\n  },\n] as const;\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@hyprcart/app-manifest",
+  "version": "1.0.0",
+  "description": "Manifest schema and validation helpers for Hyprcart apps.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.18",
+    "@repo/typescript-config": "0.0.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}