@ikenga/contract 0.7.0 → 0.9.0

package/src/manifest.ts

@@ -11,7 +11,9 @@
 import { z } from 'zod';
 import { EngineProvidesSchema } from './engine/index.js';
 
-export const IKENGA_API_VERSION = 1 as const;
+// v2 (WP-05): added capabilities.sqlite + permissions["sqlite.tables"];
+// permissions["supabase.tables"] kept as a compat alias for api=1 manifests.
+export const IKENGA_API_VERSION = 2 as const;
 export const IKENGA_API_MIN_SUPPORTED = 1 as const;
 
 // ---------- Sub-schemas ----------
@@ -60,6 +62,12 @@ export const PermissionsSchema = z.object({
   'fs.read': z.array(z.string()).default([]),
   'fs.write': z.array(z.string()).default([]),
   net: z.array(z.string()).default([]),
+  /** Local SQLite table patterns; validated against tables.json at install time.
+   *  For api ≥ 2 manifests. Replaces `supabase.tables`. */
+  'sqlite.tables': z.array(z.string()).default([]),
+  /** @deprecated api=1 compat alias for `sqlite.tables`. New manifests should
+   *  use `sqlite.tables` instead. Kept so ikenga_api="1" manifests parse
+   *  without errors during the transition window. */
   'supabase.tables': z.array(z.string()).default([]),
   'vault.keys': z.array(z.string()).default([]),
 }).default({});
@@ -135,6 +143,46 @@ export const CronEntrySchema = z.object({
   env_from_settings: z.array(z.string()).default([]),
 });
 
+/** Local SQLite capability (api ≥ 2). Threads the logical db name into the
+ *  iframe host context so the pkg can call `db_query` without hard-coding it.
+ *  Mirrors `SqliteCapability` in `shell/src-tauri/src/pkg/manifest.rs`. */
+export const SqliteCapabilitySchema = z.object({
+  /** Logical DB name. Currently only `"ikenga.local"` is supported.
+   *  Defaults to `"ikenga.local"` when omitted. */
+  db: z.string().default('ikenga.local'),
+});
+export type SqliteCapability = z.infer<typeof SqliteCapabilitySchema>;
+
+/** Supabase capability. Mirrors `SupabaseCapability` in
+ *  `shell/src-tauri/src/pkg/manifest.rs`. */
+export const SupabaseCapabilitySchema = z.object({
+  /** When true, mint fails if the Supabase vault keys are missing; when
+   *  false/omitted, missing keys surface as `supabase: null` in host context. */
+  required: z.boolean().default(false),
+});
+export type SupabaseCapability = z.infer<typeof SupabaseCapabilitySchema>;
+
+/** Native child-webview capability. Mirrors `WebviewCapability` in
+ *  `shell/src-tauri/src/pkg/manifest.rs`. */
+export const WebviewCapabilitySchema = z.object({
+  /** Whether this pkg may create child webviews via the kernel. Required for
+   *  any `ui.routes[]` entry with `kind = "webview"` to mount. */
+  child_webviews: z.boolean().default(false),
+  /** Named cookie/data partitions; empty = the implicit "default" partition. */
+  partitions: z.array(z.string()).default([]),
+});
+export type WebviewCapability = z.infer<typeof WebviewCapabilitySchema>;
+
+/** Agent-ops host-bridge capability (api ≥ 2). Opt-in to the privileged
+ *  `host.agentOps.*` verbs (run-now / enable-disable / list-jobs) the shell
+ *  exposes for the agent-ops observability pkg — these reach the always-on
+ *  cron daemon's localhost trigger endpoint and read the daemon's config +
+ *  state files, hops an iframe cannot make itself. Presence of the block is
+ *  the gate (mirrors the `capabilities.sqlite` opt-in). Mirrors
+ *  `AgentOpsCapability` in `shell/src-tauri/src/pkg/manifest.rs`. */
+export const AgentOpsCapabilitySchema = z.object({});
+export type AgentOpsCapability = z.infer<typeof AgentOpsCapabilitySchema>;
+
 export const WindowBlockSchema = z.object({
   label: z.string(),
   url: z.string(),
@@ -159,6 +207,39 @@ export const ScreenshotSchema = z.object({
 });
 export type Screenshot = z.infer<typeof ScreenshotSchema>;
 
+/** Forward-dependency source for a `requires[]` entry. Mirrors the Rust
+ *  `RequireSource` enum (`pkg/manifest.rs`) and the registry `ProvenanceSource`
+ *  set. Optional on an entry — absent means the resolver looks the dep up in the
+ *  store registry / catalog. */
+export const RequireSourceSchema = z.enum(['git', 'npx', 'catalog', 'local']);
+export type RequireSource = z.infer<typeof RequireSourceSchema>;
+
+/**
+ * One forward-dependency edge (`requires[]` element, ADR-015 §3 / Ọba WP-11).
+ * Names a standalone Ọba primitive a pkg `requires`; the resolver (WP-13/14)
+ * installs the closure at install/enable. This is a SEPARATE graph from a
+ * skill's `SKILL.md` `depends_on` (the G-04 authoring star, `skill-core`-only):
+ * a pkg `requires` MAY reference any primitive, and the publish-time lift
+ * (WP-12) compiles `depends_on` into this field. `.strict()` mirrors the Rust
+ * `deny_unknown_fields` on `RequiresEntry`. Source of truth: the Rust struct in
+ * `shell/src-tauri/src/pkg/manifest.rs` — keep in lockstep.
+ */
+export const RequiresEntrySchema = z
+  .object({
+    /** Primitive kind: skill | agent | command | hook | mcp. Kept a string so a
+     *  future kind doesn't break old manifests. */
+    kind: z.string(),
+    /** Primitive name (e.g. `skill-core`, `@ikenga/studio-beat-detect`). */
+    name: z.string(),
+    /** Optional fetch source. */
+    source: RequireSourceSchema.optional(),
+    /** Optional git tag/branch or version pin. The shape leaves room for an
+     *  explicit semver range later without another schema break. */
+    ref: z.string().optional(),
+  })
+  .strict();
+export type RequiresEntry = z.infer<typeof RequiresEntrySchema>;
+
 // ---------- Manifest ----------
 
 export const ManifestSchema = z.object({
@@ -176,9 +257,13 @@ export const ManifestSchema = z.object({
   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(),
+  // NOTE (WP-17, ADR-015 decision 4): the `skills`/`commands`/`agents`
+  // asset-bundling fields were HARD-RETIRED (lockstep with the Rust
+  // `Manifest`). A pkg no longer embeds Claude-config assets; it only
+  // `requires` standalone Ọba primitives. The schema is `.strict()`, so a
+  // manifest still declaring any of them now FAILS validation (no deprecation
+  // window). The shell builtin `com.ikenga.iyke` places its skill/commands by
+  // convention from on-disk folders, not via a manifest field.
   mcp: z.array(McpServerSchema).default([]),
   sidecars: z.array(SidecarSpecSchema).default([]),
   permissions: PermissionsSchema,
@@ -190,6 +275,16 @@ export const ManifestSchema = z.object({
   window: WindowBlockSchema.optional(),
   queries: QueriesBlockSchema.optional(),
 
+  /** Optional capabilities the host resolves and injects at iframe-mount
+   *  time via the AppBridge `hostContext` handshake. Mirrors the Rust
+   *  `CapabilitiesBlock` in `shell/src-tauri/src/pkg/manifest.rs`. */
+  capabilities: z.object({
+    supabase: SupabaseCapabilitySchema.optional(),
+    sqlite: SqliteCapabilitySchema.optional(),
+    webview: WebviewCapabilitySchema.optional(),
+    agentOps: AgentOpsCapabilitySchema.optional(),
+  }).optional(),
+
   /**
    * Engine-adapter manifest block. Present iff this pkg is an engine-*
    * adapter. Declares the agent id, display name, capability snapshot,
@@ -205,6 +300,16 @@ export const ManifestSchema = z.object({
    * UI (engines, MCP-only servers) typically leave this empty.
    */
   screenshots: z.array(ScreenshotSchema).default([]),
+
+  /**
+   * Forward dependency declarations (ADR-015 §3 / Ọba WP-11). Each entry names a
+   * standalone primitive this pkg `requires`; the Ọba resolver installs the
+   * closure at install/enable. A SEPARATE graph from a skill's `depends_on` (the
+   * G-04 authoring star). Empty by default so pre-Phase-4 manifests are
+   * unaffected. Mirrors `requires: Vec<RequiresEntry>` on the Rust `Manifest`
+   * (`pkg/manifest.rs`) — keep in lockstep (`deny_unknown_fields`).
+   */
+  requires: z.array(RequiresEntrySchema).default([]),
 });
 
 export type Manifest = z.infer<typeof ManifestSchema>;

package/src/registry.ts

@@ -105,6 +105,15 @@ export const RegistryEntrySchema = z.object({
    * Lets the shell render a thumb without fetching the per-pkg detail file.
    */
   screenshot: z.string().url().optional(),
+  /**
+   * Catalog visibility. `"hidden"` keeps the pkg installable by exact name
+   * (CLI `add`/`update`, registry install, update detection) but omits it
+   * from the default browse/catalog surfaces — used for dev/test fixtures
+   * and scaffolds (e.g. `pkg-hello`, `pkg-engine-noop`, the cursor-agent
+   * scaffold). Absent ⇒ treated as `"public"`. Set by the publish pipeline's
+   * curation step (`ikenga-pkgs/scripts/update-registry-index.mjs`).
+   */
+  visibility: z.enum(['public', 'hidden']).optional(),
 });
 export type RegistryEntry = z.infer<typeof RegistryEntrySchema>;
 

package/src/scopes.ts

@@ -41,7 +41,7 @@ export const SCOPE_CATALOGUE: ScopeDef[] = [
   { scope: 'fs:write', description: 'Write files inside the shell-managed sandbox.', sensitive: true },
 
   // engine
-  { scope: 'engine:invoke', description: 'Start sessions and stream from the active AI engine.' },
+  { scope: 'engine:invoke', description: 'Start sessions and stream from the active AI engine.', sensitive: true },
   { scope: 'engine:register_mcp', description: 'Register additional MCP servers with the engine.', sensitive: true },
 
   // shell chrome