@ankhorage/contracts 1.18.3 → 1.19.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @ankhorage/contracts
 
+## 1.19.1
+
+### Patch Changes
+
+- 37105b0: Add published ankh package metadata and document capability naming conventions.
+
+## 1.19.0
+
+### Minor Changes
+
+- b618979: Add `@ankhorage/contracts/cli` metadata contracts for Ankh package discovery.
+
 ## 1.18.3
 
 ### Patch Changes

package/README.md

@@ -22,6 +22,7 @@ Shared public contracts for Ankhorage packages and standalone provider packages.
 ```ts
 import type { AppManifest } from '@ankhorage/contracts';
 import type { AuthAdapter } from '@ankhorage/contracts/auth';
+import type { AnkhCommandProviderManifest, AnkhPackageMetadata } from '@ankhorage/contracts/cli';
 import type { DbAdapter } from '@ankhorage/contracts/db';
 import type { StorageAdapter } from '@ankhorage/contracts/storage';
 ```
@@ -71,6 +72,91 @@ export function createSupabaseAuthAdapter(): AuthAdapter {
 }
 ```
 
+## CLI discovery contracts
+
+`@ankhorage/contracts/cli` contains metadata-only discovery contracts for Ankh
+packages and command providers.
+
+```ts
+import type { AnkhCommandProviderManifest, AnkhPackageMetadata } from '@ankhorage/contracts/cli';
+```
+
+Provider packages expose `package.json.ankh` metadata using a package-relative
+provider module path:
+
+```json
+{
+  "ankh": {
+    "category": "infra",
+    "provider": "./dist/ankh.provider.js",
+    "capabilities": ["infra.up", "infra.status"]
+  }
+}
+```
+
+Metadata-only packages use `null` for `provider`:
+
+```json
+{
+  "ankh": {
+    "category": "contracts",
+    "provider": null,
+    "capabilities": ["contracts.cli"]
+  }
+}
+```
+
+`@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`
+- `category: "dev"` with `path: ["android", "scan"]` maps to `ankh dev android scan`
+
+This subpath contains contracts only. It must not depend on `commander`,
+`@ankhorage/ankh`, provider implementations, or runtime CLI execution logic.
+
+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
 
 Auth providers own identity records. App-facing profile data should be modeled separately, usually in an app table such as `profiles`.

package/dist/cli.d.ts

@@ -0,0 +1,23 @@
+export type AnkhCommandCategory = string;
+export type AnkhProviderReference = `./${string}`;
+export type AnkhCapabilityId = `${string}.${string}`;
+export interface AnkhCommandDescriptor {
+    readonly path: readonly [string, ...string[]];
+    readonly summary: string;
+    readonly capability: AnkhCapabilityId;
+    readonly aliases?: readonly string[];
+    readonly examples?: readonly string[];
+}
+export interface AnkhCommandProviderManifest {
+    readonly id: string;
+    readonly category: AnkhCommandCategory;
+    readonly version: string;
+    readonly capabilities: readonly AnkhCapabilityId[];
+    readonly commands: readonly AnkhCommandDescriptor[];
+}
+export interface AnkhPackageMetadata {
+    readonly category: AnkhCommandCategory;
+    readonly provider: AnkhProviderReference | null;
+    readonly capabilities: readonly AnkhCapabilityId[];
+}
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC,MAAM,MAAM,qBAAqB,GAAG,KAAK,MAAM,EAAE,CAAC;AAElD,MAAM,MAAM,gBAAgB,GAAG,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC;AAErD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACnD,QAAQ,CAAC,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACrD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,YAAY,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACpD"}

package/dist/cli.js

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

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"","sourcesContent":["export type AnkhCommandCategory = string;\n\nexport type AnkhProviderReference = `./${string}`;\n\nexport type AnkhCapabilityId = `${string}.${string}`;\n\nexport interface AnkhCommandDescriptor {\n  readonly path: readonly [string, ...string[]];\n  readonly summary: string;\n  readonly capability: AnkhCapabilityId;\n  readonly aliases?: readonly string[];\n  readonly examples?: readonly string[];\n}\n\nexport interface AnkhCommandProviderManifest {\n  readonly id: string;\n  readonly category: AnkhCommandCategory;\n  readonly version: string;\n  readonly capabilities: readonly AnkhCapabilityId[];\n  readonly commands: readonly AnkhCommandDescriptor[];\n}\n\nexport interface AnkhPackageMetadata {\n  readonly category: AnkhCommandCategory;\n  readonly provider: AnkhProviderReference | null;\n  readonly capabilities: readonly AnkhCapabilityId[];\n}\n"]}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './auth';
 export * from './bindings';
+export * from './cli';
 export * from './data';
 export * from './db';
 export * from './nutrition';

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,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,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,MAAM,CAAC"}

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from './auth';
 export * from './bindings';
+export * from './cli';
 export * from './data';
 export * from './db';
 export * from './nutrition';

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,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 './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,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"]}

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "@ankhorage/contracts",
-  "version": "1.18.3",
+  "version": "1.19.1",
   "main": "./dist/index.js",
+  "ankh": {
+    "category": "contracts",
+    "provider": null,
+    "capabilities": [
+      "contracts.cli"
+    ]
+  },
   "dependencies": {
     "@ankhorage/color-theory": "^0.0.7"
   },
@@ -25,6 +32,10 @@
       "types": "./dist/bindings.d.ts",
       "default": "./dist/bindings.js"
     },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
+    },
     "./data": {
       "types": "./dist/data/index.d.ts",
       "default": "./dist/data/index.js"

package/src/cli.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'bun:test';
+
+import type {
+  AnkhCapabilityId,
+  AnkhCommandDescriptor,
+  AnkhCommandProviderManifest,
+  AnkhPackageMetadata,
+} from './index';
+
+describe('cli contracts', () => {
+  it('accepts provider package metadata and provider manifests', () => {
+    const packageMetadata = {
+      category: 'infra',
+      provider: './dist/ankh.provider.js',
+      capabilities: ['infra.up', 'infra.status'],
+    } as const satisfies AnkhPackageMetadata;
+
+    const upCommand = {
+      path: ['up'],
+      summary: 'Bring project infrastructure up',
+      capability: 'infra.up',
+      aliases: ['start'],
+      examples: ['ankh infra up shop'],
+    } as const satisfies AnkhCommandDescriptor;
+
+    const manifest = {
+      id: '@ankhorage/infra',
+      category: 'infra',
+      version: '1.0.0',
+      capabilities: ['infra.up', 'infra.status'],
+      commands: [upCommand],
+    } as const satisfies AnkhCommandProviderManifest;
+
+    expect(JSON.parse(JSON.stringify(packageMetadata))).toEqual(packageMetadata);
+    expect(JSON.parse(JSON.stringify(manifest))).toEqual(manifest);
+    expect(manifest.id).toBe('@ankhorage/infra');
+    expect(manifest.category).toBe('infra');
+    expect(manifest.commands[0].path).toEqual(['up']);
+  });
+
+  it('accepts metadata-only packages without a provider module', () => {
+    const packageMetadata = {
+      category: 'contracts',
+      provider: null,
+      capabilities: ['contracts.cli'],
+    } as const satisfies AnkhPackageMetadata;
+
+    expect(JSON.parse(JSON.stringify(packageMetadata))).toEqual(packageMetadata);
+    expect(packageMetadata.provider).toBeNull();
+  });
+
+  it('keeps command paths relative to the provider category', () => {
+    const androidScanCommand = {
+      path: ['android', 'scan'],
+      summary: 'Scan an Android target',
+      capability: 'dev.android.scan',
+      examples: ['ankh dev android scan'],
+    } as const satisfies AnkhCommandDescriptor;
+
+    const manifest = {
+      id: '@ankhorage/dev',
+      category: 'dev',
+      version: '1.0.0',
+      capabilities: ['dev.android.scan'],
+      commands: [androidScanCommand],
+    } as const satisfies AnkhCommandProviderManifest;
+
+    expect(manifest.category).toBe('dev');
+    expect(manifest.commands[0].path).toEqual(['android', 'scan']);
+    expect(manifest.commands[0].path[0]).not.toBe(manifest.category);
+  });
+
+  it('accepts dot-separated capability ids for discovery metadata', () => {
+    const capabilities = [
+      'infra.up',
+      'templates.list',
+      'board.web.import',
+      'contracts.cli',
+    ] as const satisfies readonly AnkhCapabilityId[];
+
+    expect(capabilities).toEqual([
+      'infra.up',
+      'templates.list',
+      'board.web.import',
+      'contracts.cli',
+    ]);
+  });
+});

package/src/cli.ts

@@ -0,0 +1,27 @@
+export type AnkhCommandCategory = string;
+
+export type AnkhProviderReference = `./${string}`;
+
+export type AnkhCapabilityId = `${string}.${string}`;
+
+export interface AnkhCommandDescriptor {
+  readonly path: readonly [string, ...string[]];
+  readonly summary: string;
+  readonly capability: AnkhCapabilityId;
+  readonly aliases?: readonly string[];
+  readonly examples?: readonly string[];
+}
+
+export interface AnkhCommandProviderManifest {
+  readonly id: string;
+  readonly category: AnkhCommandCategory;
+  readonly version: string;
+  readonly capabilities: readonly AnkhCapabilityId[];
+  readonly commands: readonly AnkhCommandDescriptor[];
+}
+
+export interface AnkhPackageMetadata {
+  readonly category: AnkhCommandCategory;
+  readonly provider: AnkhProviderReference | null;
+  readonly capabilities: readonly AnkhCapabilityId[];
+}

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,
@@ -56,6 +57,26 @@ 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 }>;
+    };
+
+    expect(packageJson.exports?.['./cli']).toEqual({
+      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', () => {
     expect(NAVIGATOR_TYPES).toEqual(['stack', 'tabs', 'drawer']);
     expect(APP_CATEGORIES).toEqual([
@@ -213,7 +234,7 @@ describe('contracts', () => {
 
   it('ThemeModeConfig.harmony accepts all ColorHarmony values', () => {
     for (const harmony of COLOR_HARMONIES) {
-      const config: ThemeModeConfig = { primaryColor: '#ff0000', harmony };
+      const config = { primaryColor: '#ff0000', harmony } satisfies ThemeModeConfig;
       expect(config.harmony).toBe(harmony);
     }
   });

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './auth';
 export * from './bindings';
+export * from './cli';
 export * from './data';
 export * from './db';
 export * from './nutrition';