@ankhorage/devtools 1.12.1 → 1.13.0

package/dist/tools/skills/assets/zora-designer/SKILL.md

@@ -42,6 +42,9 @@ types, ZORA elements, events, recipes, and version provenance. Never copy owner
 schemas, token inventories, color algorithms, action types, or manifest implementations into this
 skill.
 
+The inspection composes metadata-only descriptors from every installed `@ankhorage/zora-*` plugin;
+use those plugin elements exactly like ZORA core elements and keep their package provenance.
+
 Compile chosen values with the same helper before composing screens. Inspect both computed modes,
 including their resolved Surface themes and all owner diagnostics. Never hand-calculate a value the
 owner exposes.

package/dist/tools/skills/assets/zora-designer/references/workflow.md

@@ -18,6 +18,9 @@ navigator types, ZORA elements, or events. Resolve explicit user input before pr
 existing brief values, category recommendations, and global defaults. Record the origin of every
 resolved decision.
 
+Installed `@ankhorage/zora-*` packages contribute their metadata-only plugin descriptors to this
+same composed element catalog; do not maintain a second plugin list in the skill.
+
 ## 2. Ask in dependency order
 
 Advance through this sequence. Skip only a value already supplied or reliably discovered.

package/dist/tools/skills/assets/zora-designer/scripts/owner-api.ts

@@ -58,7 +58,7 @@ interface ZoraThemeApi extends Record<string, unknown> {
 }
 
 interface EventMetadata extends Record<string, unknown> {
-  description: string;
+  description?: string;
   eventType: string;
   label: string;
   payloadFields?: unknown;
@@ -84,6 +84,10 @@ interface RecipeMetadata extends Record<string, unknown> {
 }
 
 interface ZoraMetadataApi extends Record<string, unknown> {
+  composeZoraPluginMetadata: (plugins: readonly Record<string, unknown>[]) => {
+    componentMeta: Record<string, ComponentMetadata | undefined>;
+  };
+  ZORA_CORE_PLUGIN_METADATA: Record<string, unknown>;
   ZORA_COMPONENT_META: Record<string, ComponentMetadata | undefined>;
   ZORA_THEME_RECIPE_META: Record<string, RecipeMetadata | undefined>;
 }
@@ -119,7 +123,7 @@ const OWNER_RELEASES = {
   colorTheory: { packageName: '@ankhorage/color-theory', minimumVersion: '0.3.0' },
   contracts: { packageName: '@ankhorage/contracts', minimumVersion: '10.1.0' },
   templates: { packageName: '@ankhorage/templates', minimumVersion: '9.3.0' },
-  zora: { packageName: '@ankhorage/zora', minimumVersion: '4.2.0' },
+  zora: { packageName: '@ankhorage/zora', minimumVersion: '4.3.0' },
 };
 
 const OWNER_REQUIREMENTS = {
@@ -155,7 +159,12 @@ const OWNER_REQUIREMENTS = {
   zoraMetadata: {
     ...OWNER_RELEASES.zora,
     specifier: '@ankhorage/zora/metadata',
-    exports: ['ZORA_COMPONENT_META', 'ZORA_THEME_RECIPE_META'],
+    exports: [
+      'composeZoraPluginMetadata',
+      'ZORA_COMPONENT_META',
+      'ZORA_CORE_PLUGIN_METADATA',
+      'ZORA_THEME_RECIPE_META',
+    ],
   },
 };
 
@@ -171,27 +180,81 @@ export async function loadOwnerApis(targetDirectory = process.cwd()) {
   const templates = await loadOwnerModule(targetDirectory, OWNER_REQUIREMENTS.templates);
   const zoraTheme = await loadOwnerModule(targetDirectory, OWNER_REQUIREMENTS.zoraTheme);
   const zoraMetadata = await loadOwnerModule(targetDirectory, OWNER_REQUIREMENTS.zoraMetadata);
+  const installedPluginMetadata = await loadInstalledZoraPluginMetadata(targetDirectory);
   assertColorTheoryApi(colorTheory.module);
   assertContractsApi(contracts.module);
   assertTemplatesApi(templates.module);
   assertZoraThemeApi(zoraTheme.module);
   assertZoraMetadataApi(zoraMetadata.module);
+  const composedZoraMetadata = zoraMetadata.module.composeZoraPluginMetadata([
+    zoraMetadata.module.ZORA_CORE_PLUGIN_METADATA,
+    ...installedPluginMetadata.map((entry) => entry.metadata),
+  ]);
+  assertRecord(composedZoraMetadata, 'composed ZORA plugin metadata');
+  assertRecord(composedZoraMetadata.componentMeta, 'composed ZORA component metadata');
 
   return {
     colorTheory: colorTheory.module,
     contracts: contracts.module,
     templates: templates.module,
     zoraTheme: zoraTheme.module,
-    zoraMetadata: zoraMetadata.module,
+    zoraMetadata: {
+      ...zoraMetadata.module,
+      ZORA_COMPONENT_META: composedZoraMetadata.componentMeta,
+    },
     versions: {
       colorTheory: colorTheory.version,
       contracts: contracts.version,
       templates: templates.version,
       zora: zoraTheme.version,
+      plugins: Object.fromEntries(
+        installedPluginMetadata.map((entry) => [entry.packageName, entry.version]),
+      ),
     },
   };
 }
 
+/*** Load metadata-only descriptors for every installed ZORA plugin declared by the target package. */
+async function loadInstalledZoraPluginMetadata(
+  targetDirectory: string,
+): Promise<{ metadata: Record<string, unknown>; packageName: string; version: string }[]> {
+  const targetManifestPath = join(resolve(targetDirectory), 'package.json');
+  const targetManifest: unknown = JSON.parse(await readFile(targetManifestPath, 'utf8'));
+  assertRecord(targetManifest, 'Target package manifest');
+  const packageNames = new Set<string>();
+  if (typeof targetManifest.name === 'string') packageNames.add(targetManifest.name);
+  for (const field of ['dependencies', 'devDependencies', 'peerDependencies']) {
+    const dependencies = targetManifest[field];
+    if (!isRecord(dependencies)) continue;
+    for (const packageName of Object.keys(dependencies)) packageNames.add(packageName);
+  }
+
+  const loaded: { metadata: Record<string, unknown>; packageName: string; version: string }[] = [];
+  for (const packageName of [...packageNames].filter(isZoraPluginPackage).sort()) {
+    const minimumVersion =
+      packageName === '@ankhorage/zora-chess'
+        ? '0.2.0'
+        : packageName === '@ankhorage/zora-tabletop'
+          ? '0.1.0'
+          : '0.0.0';
+    const requirement: OwnerRequirement = {
+      packageName,
+      minimumVersion,
+      specifier: `${packageName}/metadata`,
+      exports: ['ZORA_PLUGIN_METADATA'],
+    };
+    const plugin = await loadOwnerModule(targetDirectory, requirement);
+    const metadata = plugin.module.ZORA_PLUGIN_METADATA;
+    assertRecord(metadata, `${packageName} ZORA plugin metadata`);
+    loaded.push({ metadata, packageName, version: plugin.version });
+  }
+  return loaded;
+}
+
+function isZoraPluginPackage(packageName: string): boolean {
+  return packageName.startsWith('@ankhorage/zora-') && packageName !== '@ankhorage/zora';
+}
+
 /*** Load only Contracts for tooling that runs before another owner package has been built. */
 export async function loadContractsApi(targetDirectory = process.cwd()): Promise<ContractsApi> {
   const loaded = await loadOwnerModule(targetDirectory, OWNER_REQUIREMENTS.contracts);
@@ -661,6 +724,10 @@ function assertZoraThemeApi(value: Record<string, unknown>): asserts value is Zo
 
 /*** Narrow released ZORA metadata into only the fields the orchestration needs. */
 function assertZoraMetadataApi(value: Record<string, unknown>): asserts value is ZoraMetadataApi {
+  if (typeof value.composeZoraPluginMetadata !== 'function') {
+    throw new Error('composeZoraPluginMetadata must be a function.');
+  }
+  assertRecord(value.ZORA_CORE_PLUGIN_METADATA, 'ZORA_CORE_PLUGIN_METADATA');
   assertRecord(value.ZORA_COMPONENT_META, 'ZORA_COMPONENT_META');
   for (const [name, metadata] of Object.entries(value.ZORA_COMPONENT_META)) {
     assertComponentMetadata(metadata, name);
@@ -696,7 +763,9 @@ function assertEventMetadata(value: unknown, name: string): asserts value is Eve
   assertRecord(value, `ZORA event metadata ${name}`);
   assertNonEmptyString(value.eventType, `ZORA event metadata ${name}.eventType`);
   assertNonEmptyString(value.label, `ZORA event metadata ${name}.label`);
-  assertNonEmptyString(value.description, `ZORA event metadata ${name}.description`);
+  if (value.description !== undefined) {
+    assertNonEmptyString(value.description, `ZORA event metadata ${name}.description`);
+  }
 }
 
 /*** Validate one theme recipe metadata entry and its supported fields. */

package/dist/tools/skills/zoraDesignerOwnerFixtures.d.ts

@@ -0,0 +1,6 @@
+export declare function createThemeConfig(): Record<string, unknown>;
+export declare const TEMPLATES_FIXTURE_SOURCE: string;
+export declare const COLOR_THEORY_FIXTURE_SOURCE = "\nexport const COLOR_HARMONIES = ['monochromatic', 'complementary'];\nexport const COLOR_HARMONY_CATALOG = [\n  { id: 'monochromatic', label: 'Monochromatic', description: 'One hue.' },\n  { id: 'complementary', label: 'Complementary', description: 'Opposing hues.' },\n];\n";
+export declare const CONTRACTS_FIXTURE_SOURCE = "\nexport const APP_CATEGORIES = ['business_productivity'];\nexport const NAVIGATOR_TYPES = ['stack', 'tabs', 'drawer'];\n";
+export declare const ZORA_THEME_FIXTURE_SOURCE = "\nexport const compileZoraTheme = (themeConfig) => ({\n  themeConfig,\n  light: { surfaceTheme: { mode: 'light' }, diagnostics: [] },\n  dark: { surfaceTheme: { mode: 'dark' }, diagnostics: [] },\n  diagnostics: [],\n});\n";
+export declare const ZORA_METADATA_FIXTURE_SOURCE = "\nexport const ZORA_COMPONENT_META = {\n  View: { name: 'View', directManifestNode: true, allowedChildren: ['Text', 'Box'], props: {} },\n  Box: { name: 'Box', directManifestNode: true, allowedChildren: [], props: {} },\n  Text: {\n    name: 'Text',\n    directManifestNode: true,\n    allowedChildren: [],\n    props: { text: { type: 'string' } },\n    events: {\n      press: {\n        eventType: 'text.press',\n        label: 'Press',\n        description: 'Text was pressed.',\n      },\n    },\n  },\n  MissingElement: {\n    name: 'MissingElement',\n    directManifestNode: true,\n    allowedChildren: [],\n    manifestPolicy: { kind: 'unresolved-element', availability: 'draft-only', releaseGate: 'blocked' },\n    blueprint: { defaultProps: { requestedCapability: 'Unresolved', reason: 'No exact element.' } },\n    props: {\n      requestedCapability: { type: 'string' },\n      reason: { type: 'string' },\n      evidenceId: { type: 'string' },\n    },\n  },\n};\nexport const ZORA_CORE_PLUGIN_METADATA = {\n  packageName: '@ankhorage/zora',\n  componentMeta: ZORA_COMPONENT_META,\n  extensionHosts: ['View', 'Box'],\n};\nexport const composeZoraPluginMetadata = (plugins) => {\n  const componentMeta = {};\n  const extensionHosts = new Set();\n  for (const plugin of [...plugins].sort((left, right) => left.packageName.localeCompare(right.packageName))) {\n    Object.assign(componentMeta, plugin.componentMeta);\n    for (const host of plugin.extensionHosts ?? []) extensionHosts.add(host);\n  }\n  for (const plugin of plugins) {\n    for (const placement of plugin.placements ?? []) {\n      for (const parent of placement.parents) {\n        if (!extensionHosts.has(parent)) throw new Error('Invalid extension host');\n        componentMeta[parent] = {\n          ...componentMeta[parent],\n          allowedChildren: [...componentMeta[parent].allowedChildren, placement.child],\n        };\n      }\n    }\n  }\n  return { componentMeta };\n};\nexport const ZORA_THEME_RECIPE_META = {\n  Card: {\n    name: 'Card',\n    kind: 'component',\n    fields: { variant: { type: 'choice', options: ['filled', 'outlined'] } },\n  },\n};\n";

package/dist/tools/skills/zoraDesignerOwnerFixtures.js

@@ -0,0 +1,144 @@
+export function createThemeConfig() {
+    return {
+        id: 'evidence-theme',
+        name: 'Evidence Theme',
+        light: { primaryColor: '#2563EB', harmony: 'complementary' },
+        dark: { primaryColor: '#2563EB', harmony: 'complementary' },
+    };
+}
+export const TEMPLATES_FIXTURE_SOURCE = `
+export const CATEGORY_PRESETS = {
+  business_productivity: {
+    category: 'business_productivity',
+    label: 'Business',
+    recommendedPrimaryColors: ['#2563EB'],
+    recommendedHarmonies: ['complementary'],
+    tonePairs: { light: 'jewel-on-neutral-light', dark: 'pastel-on-neutral-dark' },
+    density: 'compact',
+  },
+};
+export const TONE_PAIR_CATALOG = [];
+export const resolveTonePair = () => null;
+export const resolveCategoryDesignPreset = (category, theme = {}) => ({ category, theme });
+const themeConfig = ${JSON.stringify(createThemeConfig())};
+export const compileCategoryDesign = (category) => ({
+  category,
+  themeConfig,
+  diagnostics: [],
+  computedTheme: {
+    themeConfig,
+    light: { surfaceTheme: { mode: 'light' }, diagnostics: [] },
+    dark: { surfaceTheme: { mode: 'dark' }, diagnostics: [] },
+    diagnostics: [],
+  },
+});
+export const composeCategoryAppManifest = (input) => ({
+  manifest: {
+    metadata: {
+      name: input.name ?? 'Generated App',
+      slug: input.slug ?? 'generated-app',
+      version: input.version ?? '1.0.0',
+      category: input.category,
+      themeId: 'evidence-theme',
+    },
+    themes: [themeConfig],
+    activeThemeId: 'evidence-theme',
+    infra: { modules: input.modules ?? [] },
+    navigator: input.navigator,
+    screens: input.screens,
+    settings: { localization: { defaultLocale: 'en', locales: ['en'] } },
+  },
+  diagnostics: [],
+  status: input.authoringState === 'release' ? 'ready' : 'blocked',
+  authoringState: input.authoringState,
+});
+export const validateTemplateManifest = (manifest) => ({
+  manifest,
+  diagnostics: [],
+  status: 'ready',
+  authoringState: 'release',
+});
+export const assertTemplateManifestReady = (composition) => composition.manifest;
+`;
+export const COLOR_THEORY_FIXTURE_SOURCE = `
+export const COLOR_HARMONIES = ['monochromatic', 'complementary'];
+export const COLOR_HARMONY_CATALOG = [
+  { id: 'monochromatic', label: 'Monochromatic', description: 'One hue.' },
+  { id: 'complementary', label: 'Complementary', description: 'Opposing hues.' },
+];
+`;
+export const CONTRACTS_FIXTURE_SOURCE = `
+export const APP_CATEGORIES = ['business_productivity'];
+export const NAVIGATOR_TYPES = ['stack', 'tabs', 'drawer'];
+`;
+export const ZORA_THEME_FIXTURE_SOURCE = `
+export const compileZoraTheme = (themeConfig) => ({
+  themeConfig,
+  light: { surfaceTheme: { mode: 'light' }, diagnostics: [] },
+  dark: { surfaceTheme: { mode: 'dark' }, diagnostics: [] },
+  diagnostics: [],
+});
+`;
+export const ZORA_METADATA_FIXTURE_SOURCE = `
+export const ZORA_COMPONENT_META = {
+  View: { name: 'View', directManifestNode: true, allowedChildren: ['Text', 'Box'], props: {} },
+  Box: { name: 'Box', directManifestNode: true, allowedChildren: [], props: {} },
+  Text: {
+    name: 'Text',
+    directManifestNode: true,
+    allowedChildren: [],
+    props: { text: { type: 'string' } },
+    events: {
+      press: {
+        eventType: 'text.press',
+        label: 'Press',
+        description: 'Text was pressed.',
+      },
+    },
+  },
+  MissingElement: {
+    name: 'MissingElement',
+    directManifestNode: true,
+    allowedChildren: [],
+    manifestPolicy: { kind: 'unresolved-element', availability: 'draft-only', releaseGate: 'blocked' },
+    blueprint: { defaultProps: { requestedCapability: 'Unresolved', reason: 'No exact element.' } },
+    props: {
+      requestedCapability: { type: 'string' },
+      reason: { type: 'string' },
+      evidenceId: { type: 'string' },
+    },
+  },
+};
+export const ZORA_CORE_PLUGIN_METADATA = {
+  packageName: '@ankhorage/zora',
+  componentMeta: ZORA_COMPONENT_META,
+  extensionHosts: ['View', 'Box'],
+};
+export const composeZoraPluginMetadata = (plugins) => {
+  const componentMeta = {};
+  const extensionHosts = new Set();
+  for (const plugin of [...plugins].sort((left, right) => left.packageName.localeCompare(right.packageName))) {
+    Object.assign(componentMeta, plugin.componentMeta);
+    for (const host of plugin.extensionHosts ?? []) extensionHosts.add(host);
+  }
+  for (const plugin of plugins) {
+    for (const placement of plugin.placements ?? []) {
+      for (const parent of placement.parents) {
+        if (!extensionHosts.has(parent)) throw new Error('Invalid extension host');
+        componentMeta[parent] = {
+          ...componentMeta[parent],
+          allowedChildren: [...componentMeta[parent].allowedChildren, placement.child],
+        };
+      }
+    }
+  }
+  return { componentMeta };
+};
+export const ZORA_THEME_RECIPE_META = {
+  Card: {
+    name: 'Card',
+    kind: 'component',
+    fields: { variant: { type: 'choice', options: ['filled', 'outlined'] } },
+  },
+};
+`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.12.1",
+  "version": "1.13.0",
   "description": "Shared development tools and repository standards for Ankhorage",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",