@ankhorage/contracts 1.19.0 → 1.19.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @ankhorage/contracts
 
+## 1.19.2
+
+### Patch Changes
+
+- 20bd7b6: Add shared runtime callback contracts for node prop resolvers and callback maps.
+
+## 1.19.1
+
+### Patch Changes
+
+- 37105b0: Add published ankh package metadata and document capability naming conventions.
+
 ## 1.19.0
 
 ### Minor Changes

package/README.md

@@ -106,6 +106,19 @@ Metadata-only packages use `null` for `provider`:
 }
 ```
 
+`@ankhorage/contracts` now publishes this metadata shape directly from its own
+`package.json`:
+
+```json
+{
+  "ankh": {
+    "category": "contracts",
+    "provider": null,
+    "capabilities": ["contracts.cli"]
+  }
+}
+```
+
 Command descriptor paths are relative to the provider category:
 
 - `category: "infra"` with `path: ["up"]` maps to `ankh infra up`
@@ -113,8 +126,36 @@ Command descriptor paths are relative to the provider category:
 
 This subpath contains contracts only. It must not depend on `commander`,
 `@ankhorage/ankh`, provider implementations, or runtime CLI execution logic.
-Concrete `package.json.ankh` adoption for this package is deferred to
-`contracts#84`.
+
+Capability names are dot-separated package metadata identifiers.
+
+Preferred forms:
+
+- `<category>.<action>` for simple capabilities
+- `<category>.<resource>.<action>` for nested or domain-specific capabilities
+
+Valid examples:
+
+- `infra.up`
+- `templates.create`
+- `contracts.cli`
+- `board.web.import`
+- `doctor.repo.validate`
+- `dev.android.rebuild`
+- `expoRuntime.plan`
+
+Invalid examples:
+
+- `infra`
+- `infra-up`
+- `.status`
+- `infra.`
+- `infra..up`
+
+`AnkhCapabilityId` remains intentionally broad at the TypeScript level so
+packages can publish stable serializable metadata without embedding policy
+validation logic here. Stricter validation belongs later in
+`@ankhorage/doctor`.
 
 ## Profile contract
 

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from './data';
 export * from './db';
 export * from './nutrition';
 export * from './requirements';
+export * from './runtimeCallbacks';
 export * from './state';
 export * from './storage';
 export * from './types';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,OAAO,CAAC;AACtB,cAAc,QAAQ,CAAC;AACvB,cAAc,MAAM,CAAC;AACrB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,MAAM,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,OAAO,CAAC;AACtB,cAAc,QAAQ,CAAC;AACvB,cAAc,MAAM,CAAC;AACrB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,MAAM,CAAC"}

package/dist/index.js

@@ -5,6 +5,7 @@ export * from './data';
 export * from './db';
 export * from './nutrition';
 export * from './requirements';
+export * from './runtimeCallbacks';
 export * from './state';
 export * from './storage';
 export * from './types';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,OAAO,CAAC;AACtB,cAAc,QAAQ,CAAC;AACvB,cAAc,MAAM,CAAC;AACrB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,MAAM,CAAC","sourcesContent":["export * from './auth';\nexport * from './bindings';\nexport * from './cli';\nexport * from './data';\nexport * from './db';\nexport * from './nutrition';\nexport * from './requirements';\nexport * from './state';\nexport * from './storage';\nexport * from './types';\nexport * from './ui';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,OAAO,CAAC;AACtB,cAAc,QAAQ,CAAC;AACvB,cAAc,MAAM,CAAC;AACrB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,MAAM,CAAC","sourcesContent":["export * from './auth';\nexport * from './bindings';\nexport * from './cli';\nexport * from './data';\nexport * from './db';\nexport * from './nutrition';\nexport * from './requirements';\nexport * from './runtimeCallbacks';\nexport * from './state';\nexport * from './storage';\nexport * from './types';\nexport * from './ui';\n"]}

package/dist/runtimeCallbacks.d.ts

@@ -0,0 +1,14 @@
+import type { UiNode } from './types';
+export interface RuntimeResolveNodePropsArgs {
+    readonly node: UiNode;
+    readonly props: Record<string, unknown>;
+}
+export type RuntimeNodePropsResolver = (args: RuntimeResolveNodePropsArgs) => Record<string, unknown>;
+export interface RuntimeCallbackArgs {
+    readonly payload: unknown;
+    readonly node?: UiNode;
+    readonly resolvedPayload?: object;
+}
+export type RuntimeCallback = (args: RuntimeCallbackArgs) => Promise<void> | void;
+export type RuntimeCallbackMap = Readonly<Record<string, RuntimeCallback>>;
+//# sourceMappingURL=runtimeCallbacks.d.ts.map

package/dist/runtimeCallbacks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeCallbacks.d.ts","sourceRoot":"","sources":["../src/runtimeCallbacks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEtC,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,MAAM,MAAM,wBAAwB,GAAG,CACrC,IAAI,EAAE,2BAA2B,KAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE7B,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAClF,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC"}

package/dist/runtimeCallbacks.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runtimeCallbacks.js.map

package/dist/runtimeCallbacks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeCallbacks.js","sourceRoot":"","sources":["../src/runtimeCallbacks.ts"],"names":[],"mappings":"","sourcesContent":["import type { UiNode } from './types';\n\nexport interface RuntimeResolveNodePropsArgs {\n  readonly node: UiNode;\n  readonly props: Record<string, unknown>;\n}\n\nexport type RuntimeNodePropsResolver = (\n  args: RuntimeResolveNodePropsArgs,\n) => Record<string, unknown>;\n\nexport interface RuntimeCallbackArgs {\n  readonly payload: unknown;\n  readonly node?: UiNode;\n  readonly resolvedPayload?: object;\n}\n\nexport type RuntimeCallback = (args: RuntimeCallbackArgs) => Promise<void> | void;\nexport type RuntimeCallbackMap = Readonly<Record<string, RuntimeCallback>>;\n"]}

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "@ankhorage/contracts",
-  "version": "1.19.0",
+  "version": "1.19.2",
   "main": "./dist/index.js",
+  "ankh": {
+    "category": "contracts",
+    "provider": null,
+    "capabilities": [
+      "contracts.cli"
+    ]
+  },
   "dependencies": {
     "@ankhorage/color-theory": "^0.0.7"
   },
@@ -41,6 +48,10 @@
       "types": "./dist/nutrition/index.d.ts",
       "default": "./dist/nutrition/index.js"
     },
+    "./runtime": {
+      "types": "./dist/runtimeCallbacks.d.ts",
+      "default": "./dist/runtimeCallbacks.js"
+    },
     "./state": {
       "types": "./dist/state.d.ts",
       "default": "./dist/state.js"

package/src/contracts.test.ts

@@ -5,6 +5,7 @@ import { COLOR_HARMONIES } from '@ankhorage/color-theory';
 import { describe, expect, it } from 'bun:test';
 
 import {
+  type AnkhPackageMetadata,
   APP_CATEGORIES,
   type AppCategory,
   type AppManifest,
@@ -57,7 +58,14 @@ async function collectTypeScriptFiles(directory: string): Promise<string[]> {
 
 describe('contracts', () => {
   it('exports the cli subpath for Ankh discovery contracts', async () => {
+    const expectedAnkhMetadata = {
+      category: 'contracts',
+      provider: null,
+      capabilities: ['contracts.cli'],
+    } as const satisfies AnkhPackageMetadata;
+
     const packageJson = JSON.parse(await readFile(join(process.cwd(), 'package.json'), 'utf8')) as {
+      ankh?: unknown;
       exports?: Record<string, { default?: string; types?: string }>;
     };
 
@@ -65,6 +73,8 @@ describe('contracts', () => {
       types: './dist/cli.d.ts',
       default: './dist/cli.js',
     });
+    expect(packageJson.ankh).toEqual(expectedAnkhMetadata);
+    expect(JSON.parse(JSON.stringify(expectedAnkhMetadata))).toEqual(expectedAnkhMetadata);
   });
 
   it('exports stable platform constants', () => {

package/src/index.ts

@@ -5,6 +5,7 @@ export * from './data';
 export * from './db';
 export * from './nutrition';
 export * from './requirements';
+export * from './runtimeCallbacks';
 export * from './state';
 export * from './storage';
 export * from './types';

package/src/runtimeCallbacks.ts

@@ -0,0 +1,19 @@
+import type { UiNode } from './types';
+
+export interface RuntimeResolveNodePropsArgs {
+  readonly node: UiNode;
+  readonly props: Record<string, unknown>;
+}
+
+export type RuntimeNodePropsResolver = (
+  args: RuntimeResolveNodePropsArgs,
+) => Record<string, unknown>;
+
+export interface RuntimeCallbackArgs {
+  readonly payload: unknown;
+  readonly node?: UiNode;
+  readonly resolvedPayload?: object;
+}
+
+export type RuntimeCallback = (args: RuntimeCallbackArgs) => Promise<void> | void;
+export type RuntimeCallbackMap = Readonly<Record<string, RuntimeCallback>>;