@ikenga/contract 0.3.0

package/src/artifact-fixtures/cfo-daily.json

@@ -0,0 +1,42 @@
+{
+  "format": "ikenga-artifact",
+  "formatVersion": "0.1",
+  "id": "cfo-daily",
+  "name": "CFO Daily",
+  "version": "0.1.0",
+  "description": "Cash position, AR aging, FX, and overnight cron status. Refresh ladder per source.",
+  "license": "BUSL-1.1",
+  "icon": { "lucide": "wallet" },
+  "dataSources": {
+    "cash": {
+      "type": "supabase",
+      "table": "v_cash_position",
+      "select": "*",
+      "refresh": { "mode": "interval", "every": "15m", "onFocus": true }
+    },
+    "ar_aging": {
+      "type": "sql",
+      "db": "ikenga.local",
+      "query": "select * from ar_aging_view",
+      "refresh": { "mode": "manual" }
+    },
+    "fx": {
+      "type": "fetch",
+      "url": "https://open.er-api.com/v6/latest/USD",
+      "refresh": { "mode": "interval", "every": "1h" }
+    },
+    "cron_status": {
+      "type": "file",
+      "path": "./data/last_run.json",
+      "refresh": { "mode": "watch" }
+    }
+  },
+  "fallback": {
+    "mode": "mock",
+    "dataTag": "ikenga-mock-data",
+    "banner": "Showing mock data — live sources unavailable."
+  },
+  "pin": { "suggested": true, "section": "finance", "label": "CFO Daily" },
+  "notes": { "enabled": true },
+  "requires": { "ikenga": ">=0.4", "bridge": "^1.0" }
+}

package/src/artifact-fixtures/hello-world.json

@@ -0,0 +1,25 @@
+{
+  "format": "ikenga-artifact",
+  "formatVersion": "0.1",
+  "id": "hello-world",
+  "name": "Hello, Artifact",
+  "version": "0.1.0",
+  "description": "Smallest valid Ikenga artifact. Lists users from a public API; falls back to mock when offline.",
+  "license": "BUSL-1.1",
+  "icon": { "lucide": "sparkles" },
+  "dataSources": {
+    "users": {
+      "type": "fetch",
+      "url": "https://jsonplaceholder.typicode.com/users",
+      "refresh": { "mode": "manual" }
+    }
+  },
+  "fallback": {
+    "mode": "mock",
+    "dataTag": "ikenga-mock-data",
+    "banner": "Showing mock data — live source unreachable."
+  },
+  "pin": { "suggested": false },
+  "notes": { "enabled": true },
+  "requires": { "ikenga": ">=0.4", "bridge": "^1.0" }
+}

package/src/artifact.test.ts

@@ -0,0 +1,44 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFile, readdir } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { ArtifactManifestSchema } from './artifact.js';
+
+const fixturesDir = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  'artifact-fixtures',
+);
+
+test('all fixtures parse against the manifest schema', async () => {
+  const files = (await readdir(fixturesDir)).filter((f) => f.endsWith('.json'));
+  assert.ok(files.length >= 3, `expected >=3 fixtures, got ${files.length}`);
+  for (const f of files) {
+    const json = JSON.parse(await readFile(path.join(fixturesDir, f), 'utf8'));
+    const result = ArtifactManifestSchema.safeParse(json);
+    assert.ok(
+      result.success,
+      `${f} failed to parse: ${
+        result.success ? '' : JSON.stringify(result.error.issues, null, 2)
+      }`,
+    );
+  }
+});
+
+test('rejects manifest with missing required fields', () => {
+  const result = ArtifactManifestSchema.safeParse({ format: 'ikenga-artifact' });
+  assert.equal(result.success, false);
+});
+
+test('rejects non-kebab-case id', () => {
+  const result = ArtifactManifestSchema.safeParse({
+    format: 'ikenga-artifact',
+    formatVersion: '0.1',
+    id: 'NotKebab',
+    name: 'X',
+    version: '0.1.0',
+    dataSources: {},
+    fallback: { mode: 'mock', dataTag: 'x' },
+  });
+  assert.equal(result.success, false);
+});

package/src/artifact.ts

@@ -0,0 +1,197 @@
+// Ikenga artifact manifest schema (v0.1).
+//
+// The artifact format is the small, agent-authorable single-file (or folder)
+// HTML doc that renders standalone in any browser AND lights up with live
+// data inside the Ikenga shell. This Zod schema is the source of truth for
+// the manifest block embedded in `<script type="application/json"
+// id="ikenga-manifest">…</script>` (single-file mode) or in
+// `manifest.json` (folder mode).
+//
+// JSON Schema is generated from this file via `pnpm generate:schemas`
+// into `schemas/artifact/v0.json` and published at:
+//   https://royalti-io.github.io/ikenga-contract/schemas/artifact/v0.json
+//
+// NOTE: this is **unrelated** to the pkg manifest in `./manifest.ts`. They
+// describe different things (pkgs are Tauri-side mini-apps; artifacts are
+// portable HTML docs). Don't conflate them.
+
+import { z } from 'zod';
+
+// ---------- Refresh modes ----------
+
+export const RefreshSchema = z.discriminatedUnion('mode', [
+  z.object({ mode: z.literal('manual') }),
+  z.object({
+    mode: z.literal('interval'),
+    /** Duration string: `<number><unit>` where unit ∈ s|m|h|d. e.g. "30s", "15m", "1h", "1d". */
+    every: z.string().regex(/^\d+\s*(s|m|h|d)$/),
+    /** When true, also refresh whenever the artifact's pane regains focus. */
+    onFocus: z.boolean().optional(),
+  }),
+  /** File / realtime sources only — bridge subscribes via fs_watch or equivalent. */
+  z.object({ mode: z.literal('watch') }),
+]);
+
+// ---------- Data sources ----------
+
+const SourceSupabase = z.object({
+  type: z.literal('supabase'),
+  table: z.string(),
+  select: z.string().optional(),
+  /** PostgREST-style filters: `[column, operator, value][]`. */
+  filter: z.array(z.tuple([z.string(), z.string(), z.unknown()])).optional(),
+  refresh: RefreshSchema,
+});
+
+const SourceSql = z.object({
+  type: z.literal('sql'),
+  /** Logical DB name (e.g. `ikenga.local`). Resolved by the host. */
+  db: z.string(),
+  query: z.string(),
+  params: z.array(z.unknown()).optional(),
+  refresh: RefreshSchema,
+});
+
+const SourceFetch = z.object({
+  type: z.literal('fetch'),
+  url: z.string().url(),
+  method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).optional(),
+  headers: z.record(z.string()).optional(),
+  refresh: RefreshSchema,
+});
+
+const SourceMcp = z.object({
+  type: z.literal('mcp'),
+  server: z.string(),
+  tool: z.string(),
+  args: z.record(z.unknown()).optional(),
+  refresh: RefreshSchema,
+});
+
+const SourceFile = z.object({
+  type: z.literal('file'),
+  path: z.string(),
+  refresh: RefreshSchema,
+});
+
+export const DataSourceSchema = z.discriminatedUnion('type', [
+  SourceSupabase,
+  SourceSql,
+  SourceFetch,
+  SourceMcp,
+  SourceFile,
+]);
+
+// ---------- Fallback ----------
+
+export const FallbackSchema = z
+  .object({
+    mode: z.literal('mock'),
+    /** Single-file mode: id of the inline `<script type="application/json">` tag carrying mock data. */
+    dataTag: z.string().optional(),
+    /** Folder mode: relative path to a JSON file with mock data. */
+    data: z.string().optional(),
+    banner: z.string().optional(),
+  })
+  .refine((v) => !!v.dataTag || !!v.data, {
+    message: "fallback must specify either 'dataTag' (single-file) or 'data' (folder mode)",
+  });
+
+// ---------- Misc top-level blocks ----------
+
+export const PinSchema = z.object({
+  suggested: z.boolean().default(false),
+  /** Free-form section name. Host fuzzy-matches against existing sections at pin time. */
+  section: z.string().optional(),
+  label: z.string().optional(),
+  icon: z.object({ lucide: z.string() }).partial().optional(),
+});
+
+export const NotesSchema = z.object({
+  enabled: z.boolean().default(true),
+});
+
+export const RequiresSchema = z.object({
+  ikenga: z.string().optional(),
+  bridge: z.string().optional(),
+});
+
+export const IconSchema = z.object({
+  lucide: z.string().optional(),
+}).partial();
+
+/**
+ * Escape-hatch capabilities block. Default behaviour is to auto-derive
+ * capabilities from `dataSources`, so most artifacts omit this entirely.
+ * Use only when narrowing below the derived set, expressing capabilities
+ * sources can't (e.g. arbitrary FS reads), or driving raw `bridge.fetch` /
+ * `bridge.mcp` calls that aren't bound to a declared source.
+ */
+export const CapabilitiesSchema = z.object({
+  network: z.object({ allow: z.array(z.string()) }).optional(),
+  supabase: z
+    .object({
+      project: z.string().optional(),
+      tables: z.array(z.string()).optional(),
+      rls: z.enum(['user', 'service']).optional(),
+    })
+    .optional(),
+  sqlite: z
+    .object({
+      db: z.string(),
+      queries: z.array(z.string()).optional(),
+    })
+    .optional(),
+  mcp: z
+    .array(
+      z.object({
+        server: z.string(),
+        tools: z.array(z.string()).optional(),
+      }),
+    )
+    .optional(),
+  fs: z
+    .object({
+      read: z.array(z.string()).optional(),
+      write: z.array(z.string()).optional(),
+    })
+    .optional(),
+});
+
+// ---------- Top-level manifest ----------
+
+export const ArtifactManifestSchema = z.object({
+  $schema: z.string().url().optional(),
+  format: z.literal('ikenga-artifact'),
+  /** Major.minor of the artifact format spec, e.g. "0.1". */
+  formatVersion: z.string(),
+
+  id: z.string().regex(/^[a-z0-9][a-z0-9-]*$/, { message: 'id must be kebab-case' }),
+  name: z.string(),
+  version: z.string(),
+  description: z.string().optional(),
+  author: z.string().optional(),
+  license: z.string().optional(),
+
+  /** Folder mode only — relative path to the entry HTML. Single-file artifacts omit this. */
+  entry: z.string().optional(),
+  icon: IconSchema.optional(),
+
+  dataSources: z.record(DataSourceSchema),
+  fallback: FallbackSchema,
+
+  pin: PinSchema.optional(),
+  notes: NotesSchema.optional(),
+  requires: RequiresSchema.optional(),
+
+  capabilities: CapabilitiesSchema.optional(),
+});
+
+export type ArtifactManifest = z.infer<typeof ArtifactManifestSchema>;
+export type DataSource = z.infer<typeof DataSourceSchema>;
+export type Refresh = z.infer<typeof RefreshSchema>;
+export type Fallback = z.infer<typeof FallbackSchema>;
+export type Capabilities = z.infer<typeof CapabilitiesSchema>;
+
+/** Format-spec version this package's schema targets. Bumped together with the JSON Schema file. */
+export const ARTIFACT_FORMAT_VERSION = '0.1' as const;

package/src/engine.ts

@@ -0,0 +1,57 @@
+// Engine adapter contract. Implementations:
+//   - engine-claude-code  (default, ships preinstalled)
+//   - engine-codex        (future)
+//   - engine-aider        (future)
+//   - engine-noop         (testing / shell-without-AI mode)
+
+export interface SessionOpts {
+  cwd?: string;
+  systemPrompt?: string;
+  toolAllowList?: string[];
+  /** Caller pkg id, used by the engine for per-pkg billing/audit. */
+  callerPkg?: string;
+}
+
+export interface Session {
+  readonly id: string;
+  /** Best-effort cancellation. Resolves once the engine has stopped streaming. */
+  cancel(): Promise<void>;
+}
+
+export type EngineEvent =
+  | { type: 'message_delta'; text: string }
+  | { type: 'tool_use'; tool: string; input: unknown; toolUseId: string }
+  | { type: 'tool_result'; toolUseId: string; output: unknown; isError?: boolean }
+  | { type: 'thinking_delta'; text: string }
+  | { type: 'usage'; inputTokens: number; outputTokens: number; cacheCreationTokens?: number; cacheReadTokens?: number }
+  | { type: 'done'; reason: 'stop' | 'cancel' | 'error'; error?: string };
+
+export interface McpServerSpec {
+  id: string;
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
+export interface Engine {
+  /** Stable identifier — matches the pkg id of the engine adapter. */
+  readonly id: string;
+
+  /** Human-readable adapter version. */
+  readonly version: string;
+
+  /** Open a new session. Sessions are cheap; create one per pkg invocation. */
+  startSession(opts: SessionOpts): Promise<Session>;
+
+  /** Send input and stream events. The iterable completes on `done`. */
+  stream(session: Session, input: string): AsyncIterable<EngineEvent>;
+
+  /** Register an MCP server with the engine. Idempotent on `id`. */
+  registerMcpServer(spec: McpServerSpec): Promise<void>;
+
+  /** Unregister an MCP server. */
+  unregisterMcpServer(id: string): Promise<void>;
+
+  /** Health check — used by the kernel before routing pkg requests. */
+  healthCheck(): Promise<{ ok: boolean; reason?: string }>;
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from './manifest.js';
+export * from './rpc.js';
+export * from './engine.js';
+export * from './scopes.js';
+export * from './iyke.js';
+export * from './artifact.js';
+
+/** This package's own version. */
+export const CONTRACT_PACKAGE_VERSION = '0.3.0' as const;

package/src/iyke.ts

@@ -0,0 +1,43 @@
+// Iyke runtime constants shared between the shell, the iyke CLI, and any
+// MCP/RPC bridge that drives the shell. These are the activity modes the
+// shell's sidebar knows about and the names of mini-app surfaces the
+// kernel exposes — runtime values, not manifest schema.
+
+/**
+ * Activity-bar sidebar modes the shell renders.
+ *
+ * - The first five (`app`, `files`, `agents`, `sessions`, `settings`) are
+ *   core modes always present on the shell.
+ * - The remaining are mini-app modes contributed by built-in pkgs.
+ *
+ * MCP / iyke clients pass these strings to `iyke_mode` to switch the
+ * sidebar. Adding a new mode is a non-breaking minor bump (consumers can
+ * still pass any of the older modes). Removing or renaming is breaking.
+ */
+export const ACTIVITY_MODES = [
+  'app',
+  'files',
+  'agents',
+  'sessions',
+  'settings',
+  'storyboard',
+  'video-engine',
+  'canvas-design',
+  'image-generator',
+] as const;
+
+export type ActivityMode = (typeof ACTIVITY_MODES)[number];
+
+/**
+ * Names of mini-app surfaces the kernel exposes via `iyke_open` with
+ * `kind: "mini-app"`. Subset of {@link ACTIVITY_MODES} that map to a
+ * full-screen mini-app surface (not a plain sidebar mode).
+ */
+export const MINI_APP_NAMES = [
+  'storyboard',
+  'video-engine',
+  'canvas-design',
+  'image-generator',
+] as const;
+
+export type MiniAppName = (typeof MINI_APP_NAMES)[number];

package/src/manifest.ts

@@ -0,0 +1,185 @@
+// Ikenga pkg manifest schema — mirrors the Rust schema in
+// `royalti-io/ikenga` at `src-tauri/src/pkg/manifest.rs`.
+//
+// Source of truth is the Rust struct. This zod schema is used by the CLI,
+// registry, and tooling for client-side parse + validation. Field changes
+// MUST be made in lockstep with the Rust struct, and IKENGA_API_VERSION
+// must be bumped if semantics change in a non-additive way.
+//
+// On disk: `<pkg-root>/manifest.json` (JSON, not TOML).
+
+import { z } from 'zod';
+
+export const IKENGA_API_VERSION = 1 as const;
+export const IKENGA_API_MIN_SUPPORTED = 1 as const;
+
+// ---------- Sub-schemas ----------
+
+export const AuthorSchema = z.object({
+  name: z.string(),
+  key: z.string().optional(),
+});
+
+export const McpServerSchema = z.object({
+  name: z.string(),
+  command: z.string(),
+  args: z.array(z.string()).default([]),
+  env: z.record(z.string()).default({}),
+  /** "per-call" (default) | "long-lived" */
+  lifecycle: z.enum(['per-call', 'long-lived']).optional(),
+});
+export type McpServer = z.infer<typeof McpServerSchema>;
+
+export const SidecarSpecSchema = z.object({
+  /** Must start with `pa-<pkg-slug>-` (slug = id with `.` → `-`). */
+  name: z.string(),
+  /** Path inside pkg dir; may contain `{target}` (host triple). */
+  bin: z.string(),
+  /** "json" (default) | "raw" */
+  stdio: z.string().default('json'),
+});
+export type SidecarSpec = z.infer<typeof SidecarSpecSchema>;
+
+export const PermissionsSchema = z.object({
+  'shell.execute': z.array(z.string()).default([]),
+  'fs.read': z.array(z.string()).default([]),
+  'fs.write': z.array(z.string()).default([]),
+  net: z.array(z.string()).default([]),
+  'supabase.tables': z.array(z.string()).default([]),
+  'vault.keys': z.array(z.string()).default([]),
+}).default({});
+
+export const NavEntrySchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  icon: z.string().optional(),
+  section: z.string().optional(),
+  route: z.string(),
+});
+
+export const UiRouteSchema = z.object({
+  path: z.string(),
+  /** "iframe" | "component" (component is builtin-only) */
+  kind: z.enum(['iframe', 'component']),
+  /** iframe: URL or pkg-relative html path. component: identifier. */
+  source: z.string(),
+});
+
+export const CommandPaletteEntrySchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  shortcut: z.string().optional(),
+  action: z.unknown(),
+});
+
+export const SidePaneViewerSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  route: z.string(),
+});
+
+export const UiBlockSchema = z.object({
+  nav: z.array(NavEntrySchema).default([]),
+  routes: z.array(UiRouteSchema).default([]),
+  command_palette: z.array(CommandPaletteEntrySchema).default([]),
+  side_pane_viewers: z.array(SidePaneViewerSchema).default([]),
+  /** Per-directive CSP overrides for the iframe content. */
+  csp: z.record(z.array(z.string())).optional(),
+  /** Per-directive Permission-Policy values. */
+  permissions: z.record(z.array(z.string())).optional(),
+}).default({});
+
+export const SettingsFieldSchema = z.object({
+  key: z.string(),
+  type: z.enum(['string', 'number', 'boolean', 'secret']),
+  label: z.string(),
+  default: z.unknown().optional(),
+  description: z.string().optional(),
+});
+export const SettingsBlockSchema = z.object({
+  schema: z.array(SettingsFieldSchema).default([]),
+});
+
+export const IykeRouteSchema = z.object({
+  method: z.enum(['GET', 'POST']),
+  /** Must start with `/pkg/<id>/`. */
+  path: z.string(),
+  /** `sidecar:<name> <sub>` | `event:<name>` */
+  handler: z.string(),
+});
+export const IykeBlockSchema = z.object({
+  routes: z.array(IykeRouteSchema).default([]),
+  events: z.array(z.string()).default([]),
+});
+
+export const CronEntrySchema = z.object({
+  id: z.string(),
+  /** 6-field cron expression: sec min hour day month dow */
+  expr: z.string(),
+  handler: z.string(),
+  env_from_settings: z.array(z.string()).default([]),
+});
+
+export const WindowBlockSchema = z.object({
+  label: z.string(),
+  url: z.string(),
+  size: z.tuple([z.number(), z.number()]).optional(),
+  decorations: z.boolean().optional(),
+  menu: z.string().optional(),
+});
+
+export const QueriesBlockSchema = z.object({
+  key_prefixes: z.array(z.string()).default([]),
+});
+
+// ---------- Manifest ----------
+
+export const ManifestSchema = z.object({
+  /** Reverse-DNS, e.g. `com.ikenga.studio`. */
+  id: z.string().regex(/^[a-z0-9]+(\.[a-z0-9-]+)+$/, 'must be reverse-DNS'),
+  name: z.string(),
+  version: z.string(),
+  /** Numeric string — host accepts versions in [MIN, CURRENT]. */
+  ikenga_api: z.string().regex(/^\d+$/),
+
+  /** Hint, not enforced: "skill" | "embedded" | "windowed" | "engine". */
+  kind: z.string().optional(),
+  author: AuthorSchema.optional(),
+  /** Rust target triples; empty = host-agnostic. */
+  targets: z.array(z.string()).default([]),
+
+  // Capability blocks (all optional — kernel walks present blocks)
+  skills: z.string().optional(),
+  commands: z.string().optional(),
+  agents: z.string().optional(),
+  mcp: z.array(McpServerSchema).default([]),
+  sidecars: z.array(SidecarSpecSchema).default([]),
+  permissions: PermissionsSchema,
+  migrations: z.string().optional(),
+  settings: SettingsBlockSchema.optional(),
+  ui: UiBlockSchema,
+  iyke: IykeBlockSchema.optional(),
+  cron: z.array(CronEntrySchema).default([]),
+  window: WindowBlockSchema.optional(),
+  queries: QueriesBlockSchema.optional(),
+});
+
+export type Manifest = z.infer<typeof ManifestSchema>;
+
+// ---------- Helpers ----------
+
+/** Convert a reverse-DNS id to a slug: `com.ikenga.studio` → `com-ikenga-studio`. */
+export function pkgSlug(id: string): string {
+  return id.replaceAll('.', '-');
+}
+
+/** Sidecar names must start with `pa-<pkg-slug>-`. */
+export function expectedSidecarPrefix(id: string): string {
+  return `pa-${pkgSlug(id)}-`;
+}
+
+export function isCompatible(api: string): boolean {
+  const n = Number.parseInt(api, 10);
+  if (Number.isNaN(n)) return false;
+  return n >= IKENGA_API_MIN_SUPPORTED && n <= IKENGA_API_VERSION;
+}