@ankhorage/devtools 1.12.0 → 1.13.0

package/README.md

@@ -188,7 +188,7 @@ The canonical workflow, VS Code, and skill files are packaged with `@ankhorage/d
 
 ## Managed agent instructions
 
-`ankh devtools agents sync` owns the repository-root `AGENTS.md`. The shared instructions are intentionally small and stable. The target repository's package name and description are rendered from `package.json`; the remaining content defines the unconditional current-architecture policy and directs structural work to the managed project-structure skill.
+`ankh devtools agents sync` owns the repository-root `AGENTS.md`. The shared instructions are intentionally small and stable. The target repository's package name and description are rendered from `package.json`; the remaining content defines the unconditional current-architecture policy, directs structural work to the managed project-structure skill, and requires the canonical build, type, lint, Knip, Changeset, and formatting commands before pull request creation.
 
 Only the current Ankhorage architecture is supported. Managed instructions reject deprecated APIs, compatibility aliases, shims, dual old/new paths, historical-state fallbacks, and migrations whose sole purpose is obsolete state. A canonical cross-package change requires affected repositories to update to the latest released public API.
 

package/dist/tools/agents/index.js

@@ -39,6 +39,19 @@ For directory ownership, package boundaries, architectural profiles, ports and a
 entrypoints, or cross-repository structural work, load and follow
 \`.agents/skills/ankhorage-project-structure/SKILL.md\`.
 
+## Pull requests
+
+Before creating a pull request, run all of these commands in this order and resolve every failure:
+
+\`\`\`sh
+bun run build
+bun run check-types
+bun run lint
+bun run knip:test
+bun run changeset
+bun run format
+\`\`\`
+
 ## Skill scripts
 
 Scripts inside an Agent Skill must always be TypeScript files with the \`.ts\` extension.

package/dist/tools/skills/assets/ankhorage-project-structure/SKILL.md

@@ -76,6 +76,7 @@ src/
       utils/
   types/
     <topic>.ts
+  constants.ts
   utils/
 ```
 
@@ -154,6 +155,26 @@ For example, `selectRoute.ts` can own a non-exported `SelectRouteInput` directly
 Types used by several local navigation operations belong together in `src/types/navigation.ts`.
 A navigation binding exchanged by Studio and Navigator belongs in `@ankhorage/contracts/navigator`.
 
+## Constant ownership
+
+Constants are static declarations, not utility implementations. Do not create one exported
+constant per constant-named file under `utils/`.
+
+1. **Used by one implementation module:** keep the constant private in the module that owns it.
+2. **Reused only inside a feature:** group related constants in that feature's `constants.ts`.
+3. **Shared across features in one package:** group related package metadata, static policy values,
+   and other constants in `src/constants.ts`.
+
+A `constants.ts` module may export multiple related constants. Keep it cohesive by ownership and
+purpose; it is not a package-wide catch-all. Split constants when they have different owners, not
+merely to create one file per export.
+
+For example, Navigator's
+[`src/utils/NAVIGATOR_PACKAGE_METADATA.ts`](https://github.com/ankhorage/navigator/blob/main/src/utils/NAVIGATOR_PACKAGE_METADATA.ts)
+and
+[`src/utils/NAVIGATOR_ROUTER_POLICY.ts`](https://github.com/ankhorage/navigator/blob/main/src/utils/NAVIGATOR_ROUTER_POLICY.ts)
+belong together in `ankhorage/navigator/src/constants.ts`.
+
 ## Utilities
 
 `utils/` is the only utility directory name. Do not create `shared/`, `helper/`, `helpers/`,

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.0",
+  "version": "1.13.0",
   "description": "Shared development tools and repository standards for Ankhorage",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",