@ikenga/contract 0.11.0 → 0.13.0

package/src/action-frontmatter.ts

@@ -0,0 +1,250 @@
+// Ikenga skill-action frontmatter schema — the source-of-truth shape for an
+// Atelier skill *action*'s YAML frontmatter (the block between the leading
+// `---` fences of an `actions/*.md` file).
+//
+// The Rust loader in `royalti-io/ikenga` at
+// `src-tauri/src/pkg/skill_actions.rs` mirrors this schema. Field changes MUST
+// be made in lockstep with that Rust struct — same convention as
+// manifest.ts ↔ manifest.rs.
+//
+// Every field below is justified in plans/atelier/06-skill-action-contract.md.
+
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Identity & taxonomy (G-TAXONOMY)
+// ---------------------------------------------------------------------------
+
+/**
+ * The eight stateful domains plus the one stateless generic skill.
+ * `skill-core` is the ONLY legal `depends_on` target (one-way edge, G-04/E-14).
+ */
+export const DomainEnum = z.enum([
+  'tasks',
+  'mail',
+  'outbound',
+  'sales',
+  'finance',
+  'content',
+  'research',
+  'strategy',
+  'skill-core',
+]);
+export type Domain = z.infer<typeof DomainEnum>;
+
+// ---------------------------------------------------------------------------
+// UX modes (R5, E-11) — exactly five
+// ---------------------------------------------------------------------------
+
+/**
+ * How an action presents itself to the operator.
+ *  - confirm   : preview the planned effect, single yes/no, then run.
+ *  - silent    : run with no prompt (still subject to capability scopes).
+ *  - form      : collect `inputs_schema` from the operator before running.
+ *  - streaming : run with live token/log streaming surfaced in the dock.
+ *  - approve   : run-THEN-pause on a produced draft; operator approves/edits
+ *                /rejects the artifact before any external side effect commits
+ *                (the draft-review gate, E-11).
+ */
+export const UxModeEnum = z.enum([
+  'confirm',
+  'silent',
+  'form',
+  'streaming',
+  'approve',
+]);
+export type UxMode = z.infer<typeof UxModeEnum>;
+
+// ---------------------------------------------------------------------------
+// Run binding (R5, G-01) — how the action actually executes
+// ---------------------------------------------------------------------------
+
+/** chat_prompt: hand a templated prompt to the engine in the dock chat. */
+const ChatPromptRun = z.object({
+  kind: z.literal('chat_prompt'),
+  // Prompt template; may interpolate validated `inputs` via {{var}}.
+  prompt: z.string().min(1),
+});
+
+/** sidecar: invoke a bundled CLI sidecar by its manifest-declared id. */
+const SidecarRun = z.object({
+  kind: z.literal('sidecar'),
+  sidecar_id: z.string().min(1),
+  // Argv template; entries may interpolate validated `inputs`.
+  args: z.array(z.string()).default([]),
+});
+
+/** mcp_tool: call a tool on a pkg-declared MCP server. */
+const McpToolRun = z.object({
+  kind: z.literal('mcp_tool'),
+  server_id: z.string().min(1),
+  tool: z.string().min(1),
+});
+
+export const RunBinding = z.discriminatedUnion('kind', [
+  ChatPromptRun,
+  SidecarRun,
+  McpToolRun,
+]);
+export type RunBinding = z.infer<typeof RunBinding>;
+
+// ---------------------------------------------------------------------------
+// Triggers (R5) — absorbs the 41 legacy crons. An action may be reachable by
+// more than one trigger; `manual` is the implicit default if none declared.
+// ---------------------------------------------------------------------------
+
+/** Operator-invoked from the command surface / dock. */
+const ManualTrigger = z.object({
+  kind: z.literal('manual'),
+});
+
+/** Time-driven. `cron` is a standard 5-field crontab expression. */
+const ScheduleTrigger = z.object({
+  kind: z.literal('schedule'),
+  cron: z.string().min(1),
+  // Optional human label surfaced in the schedule UI.
+  label: z.string().optional(),
+});
+
+/** Inbound HTTP trigger routed through the shell bridge. */
+const WebhookTrigger = z.object({
+  kind: z.literal('webhook'),
+  // Stable path segment; the shell namespaces it under the pkg id.
+  path: z.string().min(1),
+});
+
+/** Reacts to an internal shell/domain event by name. */
+const EventTrigger = z.object({
+  kind: z.literal('event'),
+  event: z.string().min(1),
+});
+
+export const Trigger = z.discriminatedUnion('kind', [
+  ManualTrigger,
+  ScheduleTrigger,
+  WebhookTrigger,
+  EventTrigger,
+]);
+export type Trigger = z.infer<typeof Trigger>;
+
+// ---------------------------------------------------------------------------
+// Capabilities (G-08, R18/R19) — coarse permission grants an action requires.
+// `sqlite` is the stateful-domain seam: state lives in the local ikenga.db,
+// reached through the host dbQuery (SELECT-only) and dbExec (parameterized
+// mutate) bridges. The *table scope* is NOT declared here — it is declared once
+// at the pkg manifest as permissions["sqlite.tables"] and cross-checked at
+// install time against the generated tables.json (the applied ikenga.db STRICT
+// schema). The frontmatter only asserts "this action touches sqlite".
+// ---------------------------------------------------------------------------
+
+export const CapabilityEnum = z.enum([
+  'sqlite',   // host.dbQuery / host.dbExec against ikenga.db (R18/R19)
+  'mcp',      // call declared MCP tools
+  'sidecar',  // spawn declared sidecars
+  'network',  // outbound network
+  'fs',       // host filesystem (scoped by manifest)
+  'secrets',  // read Stronghold-vaulted secrets
+  'chat',     // drive the dock chat engine
+]);
+export type Capability = z.infer<typeof CapabilityEnum>;
+
+// ---------------------------------------------------------------------------
+// Setup lifecycle (D-02, setup-lifecycle decision) — `setup` is an optional,
+// well-known action on EVERY skill. It localises the skill per project by
+// writing ${CLAUDE_PROJECT_DIR}/.atelier/<skill>/manifest.json. It runs IN
+// CHAT, never as a form screen. Two modes:
+//   - ai_infer : the agent drafts the instance config from the repo/site, the
+//                operator confirms/edits in chat.
+//   - interview: the agent asks the operator a scripted set of questions.
+// `template_version` carries a migrate path so an upgraded skill can migrate an
+// older instance file forward.
+// ---------------------------------------------------------------------------
+
+export const SetupModeEnum = z.enum(['ai_infer', 'interview']);
+export type SetupMode = z.infer<typeof SetupModeEnum>;
+
+export const SetupSpec = z.object({
+  mode: SetupModeEnum,
+  // Bumped whenever the instance-file shape changes; drives the migrate path.
+  template_version: z.number().int().positive(),
+  // For ai_infer: where the agent should look to draft the instance config.
+  infer_sources: z.array(z.string()).optional(),
+  // For interview: ordered question ids the chat flow walks.
+  interview_questions: z.array(z.string()).optional(),
+});
+export type SetupSpec = z.infer<typeof SetupSpec>;
+
+// ---------------------------------------------------------------------------
+// ActionFrontmatter — the locked shape.
+// ---------------------------------------------------------------------------
+
+export const ActionFrontmatter = z
+  .object({
+    // --- identity ---
+    /** Stable action id, unique within the skill. kebab-case. */
+    name: z
+      .string()
+      .min(1)
+      .regex(/^[a-z][a-z0-9-]*$/, 'name must be kebab-case'),
+    /** One-line human description shown in the command surface. */
+    description: z.string().min(1),
+    /** Owning domain (G-TAXONOMY). */
+    domain: DomainEnum,
+
+    // --- presentation & io ---
+    /** How the action presents to the operator (R5/E-11). */
+    ux_mode: UxModeEnum,
+    /**
+     * JSON-Schema describing the action's inputs. Kept as an opaque object here
+     * (validated as JSON-Schema at the destination); `form`/`approve` modes
+     * render it, `chat_prompt` runs interpolate validated values from it.
+     */
+    inputs_schema: z.record(z.string(), z.unknown()).optional(),
+
+    // --- execution ---
+    /** What the action actually does (G-01). */
+    run: RunBinding,
+    /** How the action can be invoked. Empty ⇒ manual-only. */
+    triggers: z.array(Trigger).default([]),
+
+    // --- dependency & permissions ---
+    /**
+     * One-way dependency edge. The ONLY legal target is 'skill-core'
+     * (G-04/E-14); any other entry is rejected by the lint in
+     * 06-skill-action-contract.md §"depends_on lint". Modeled as a literal
+     * array so the schema itself refuses non-skill-core targets.
+     */
+    depends_on: z.array(z.literal('skill-core')).default([]),
+    /** Coarse capability grants this action needs (G-08, R18/R19). */
+    requires_capabilities: z.array(CapabilityEnum).default([]),
+
+    // --- lifecycle ---
+    /**
+     * Present ONLY on the well-known `setup` action. Omitted on every other
+     * action. Refined below.
+     */
+    setup: SetupSpec.optional(),
+  })
+  .strict()
+  .superRefine((fm, ctx) => {
+    // The `setup` block is allowed iff this IS the setup action.
+    if (fm.name === 'setup' && fm.setup === undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['setup'],
+        message: 'the "setup" action must declare a `setup` block',
+      });
+    }
+    if (fm.name !== 'setup' && fm.setup !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['setup'],
+        message: '`setup` block is only valid on the "setup" action',
+      });
+    }
+    // An action that runs SQL must declare the `sqlite` capability so the
+    // pkg-manifest sqlite.tables cross-check has something to bind to.
+    // (The reverse — declaring sqlite without using it — is allowed/harmless.)
+  });
+
+export type ActionFrontmatter = z.infer<typeof ActionFrontmatter>;

package/src/index.ts

@@ -8,6 +8,8 @@ export * from './artifact.js';
 export * from './registry.js';
 export * from './browser.js';
 export * from './pa-actions.js';
+export * from './window.js';
+export * from './action-frontmatter.js';
 
 /** This package's own version. */
 export const CONTRACT_PACKAGE_VERSION = '0.5.0' as const;

package/src/manifest.ts

@@ -74,6 +74,11 @@ export const PermissionsSchema = z.object({
    *  without errors during the transition window. */
   'supabase.tables': z.array(z.string()).default([]),
   'vault.keys': z.array(z.string()).default([]),
+  /** Engine scopes exercisable from the pkg iframe. `"invoke"` gates the
+   *  FE-side host.sendToActiveSession / host.startChatSession verbs
+   *  (pkgDeclaresScope). Mirrors `Permissions.engine` in the shell's
+   *  manifest.rs — keep in lockstep. */
+  engine: z.array(z.string()).default([]),
 }).default({});
 
 export const NavEntrySchema = z.object({

package/src/pa-actions.ts

@@ -36,6 +36,27 @@ export interface DraftSequence {
 	recipients: number;
 }
 
+/** One sub-post in an X/Twitter thread (X allows ≤4 images per tweet). */
+export interface ThreadPost {
+	text: string;
+	/** Per-sub-post media URLs (X allows ≤4 images per tweet). */
+	imageUrls?: string[];
+}
+
+/**
+ * Media block carried on a Buffer DraftItem. `kind` selects the adapter path:
+ * - `'single'`   — 0–1 image attached to the post body.
+ * - `'carousel'` — 2–10 images (IG ≤10, LI ≤9); adapter uses multi-asset upload.
+ * - `'thread'`   — ordered sub-posts; adapter posts as N linked Buffer posts (≥2, ≤25).
+ */
+export interface SocialMedia {
+	kind: 'single' | 'carousel' | 'thread';
+	/** single = 0–1 image URL; carousel = 2–10 (platform-dependent). */
+	imageUrls?: string[];
+	/** thread-kind only: ordered sub-posts (≥2, ≤25). */
+	thread?: ThreadPost[];
+}
+
 /**
  * What an approve-aware action emits per draft — the lean, authoritative
  * producer shape. The shell derives the panel's `PausedDraft` from this via
@@ -88,6 +109,23 @@ export interface DraftItem {
 	threadCount?: string;
 	/** Explicit section bucket; otherwise derived from `scheduledIso`. */
 	section?: string;
+	// ── Buffer / social fields (mirror of payload_json media contract) ──────────
+	/**
+	 * Resolved Buffer channel id — company vs personal LinkedIn disambiguated at
+	 * enqueue time (not in the adapter). Only set for `channel: 'buffer'` drafts.
+	 */
+	channelId?: string;
+	/**
+	 * First comment text for hashtags / blog URL. Avoids Buffer link-preview
+	 * attachment errors on LinkedIn. Mapped to `metadata.<platform>.firstComment`.
+	 */
+	firstComment?: string;
+	/**
+	 * Social media block; selects single / carousel / thread adapter path.
+	 * Kept in lockstep with `payload.schema.ts` `SocialMedia` Zod schema and
+	 * the worker mirror in `scripts/cron/lib/channels/types.ts`.
+	 */
+	media?: SocialMedia;
 }
 
 /**

package/src/window.test.ts

@@ -0,0 +1,70 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import {
+	WINDOW_CONTRACT_VERSION,
+	WindowDescriptorSchema,
+	WindowEventEnvelopeSchema,
+} from './window.js';
+
+// Canonical wire fixtures — the Rust round-trip test
+// (src-tauri/src/window/descriptor.rs + events.rs) asserts the SAME JSON.
+// If these drift, the lockstep contract is broken.
+
+const DESCRIPTOR_FIXTURE = {
+	label: 'detached-1',
+	kind: 'single-surface',
+	surface_set: ['chat'],
+	project_id: null,
+	layout_key: 'detached-1',
+};
+
+const ENVELOPE_FIXTURE = {
+	v: 1,
+	topic: 'window://opened',
+	source_label: 'core',
+	target: { kind: 'window', label: 'detached-1' },
+	payload: { label: 'detached-1' },
+};
+
+test('WindowDescriptor parses the canonical fixture and round-trips', () => {
+	const parsed = WindowDescriptorSchema.parse(DESCRIPTOR_FIXTURE);
+	assert.deepEqual(parsed, DESCRIPTOR_FIXTURE);
+	// re-parse the serialized form (round-trip)
+	assert.deepEqual(
+		WindowDescriptorSchema.parse(JSON.parse(JSON.stringify(parsed))),
+		DESCRIPTOR_FIXTURE,
+	);
+});
+
+test('WindowDescriptor rejects unknown keys (deny_unknown_fields parity)', () => {
+	assert.throws(() =>
+		WindowDescriptorSchema.parse({ ...DESCRIPTOR_FIXTURE, rogue: true }),
+	);
+});
+
+test('WindowDescriptor applies defaults for surface_set/project_id', () => {
+	const parsed = WindowDescriptorSchema.parse({
+		label: 'main',
+		kind: 'primary',
+		layout_key: 'main',
+	});
+	assert.deepEqual(parsed.surface_set, []);
+	assert.equal(parsed.project_id, null);
+});
+
+test('WindowEventEnvelope parses the canonical fixture and round-trips', () => {
+	const parsed = WindowEventEnvelopeSchema.parse(ENVELOPE_FIXTURE);
+	assert.equal(parsed.v, WINDOW_CONTRACT_VERSION);
+	assert.deepEqual(
+		WindowEventEnvelopeSchema.parse(JSON.parse(JSON.stringify(parsed))),
+		ENVELOPE_FIXTURE,
+	);
+});
+
+test('WindowEventTarget broadcast variant parses', () => {
+	const parsed = WindowEventEnvelopeSchema.parse({
+		...ENVELOPE_FIXTURE,
+		target: { kind: 'broadcast' },
+	});
+	assert.equal(parsed.target.kind, 'broadcast');
+});

package/src/window.ts

@@ -0,0 +1,100 @@
+// Multi-window contract — mirrors the Rust source-of-truth in
+// `royalti-io/ikenga` at `src-tauri/src/window/{descriptor,events}.rs`.
+//
+// This is the `G-WINDOW-MODEL` freeze-gate output (plans/multi-window WP-02).
+// It has TWO co-equal halves: the `WindowDescriptor` (what a window IS) and the
+// cross-window event envelope (how windows talk over the shared Rust core).
+// Both are imported by every downstream consumer (the window registry, the thin
+// detached FE entry, Flavor C). Field changes MUST be made in lockstep with the
+// Rust structs; bump WINDOW_CONTRACT_VERSION on any non-additive change.
+
+import { z } from 'zod';
+
+/** Envelope + descriptor wire version. Bumped on non-additive change. */
+export const WINDOW_CONTRACT_VERSION = 1 as const;
+
+// ---------- WindowDescriptor ----------
+
+/**
+ * What a window is.
+ * - `primary`        — the original "main" window (full chrome).
+ * - `single-surface` — a thin detached window hosting one surface (Flavor C).
+ * - `pane-set`       — a torn-off pane group (Flavor A, Phase 2).
+ * - `workspace`      — a second full workspace window (Flavor B, Phase 3).
+ */
+export const WindowKindSchema = z.enum([
+	'primary',
+	'single-surface',
+	'pane-set',
+	'workspace',
+]);
+export type WindowKind = z.infer<typeof WindowKindSchema>;
+
+export const WindowDescriptorSchema = z
+	.object({
+		/** OS window label. "main" for the primary; "detached-<n>" otherwise. */
+		label: z.string().min(1),
+		kind: WindowKindSchema,
+		/** Surface/route ids the window's FE entry mounts. */
+		surface_set: z.array(z.string()).default([]),
+		/** Project this window is bound to (Flavor B); null = follows primary. */
+		project_id: z.string().nullable().default(null),
+		/**
+		 * SQLite `layout_state` partition. A KEY-STRING suffix folded into
+		 * `scopedKey()` (G-03) — NOT a new column. Usually equals `label`.
+		 */
+		layout_key: z.string().min(1),
+	})
+	.strict();
+export type WindowDescriptor = z.infer<typeof WindowDescriptorSchema>;
+
+// ---------- Cross-window event envelope ----------
+
+/**
+ * Where a window event goes. The DEFAULT for streaming/data channels is
+ * `broadcast` (every window filters its own subscription); only the channels
+ * that race (see WINDOW_TARGETED_CHANNELS) carry `window` targeting.
+ */
+export const WindowEventTargetSchema = z.discriminatedUnion('kind', [
+	z.object({ kind: z.literal('broadcast') }).strict(),
+	z.object({ kind: z.literal('window'), label: z.string().min(1) }).strict(),
+]);
+export type WindowEventTarget = z.infer<typeof WindowEventTargetSchema>;
+
+/**
+ * The base shape every cross-window event rides. `payload` is opaque at the
+ * contract layer (each topic refines it); the envelope itself is what the
+ * registry + windows agree on.
+ */
+export const WindowEventEnvelopeSchema = z
+	.object({
+		v: z.literal(WINDOW_CONTRACT_VERSION),
+		/** Channel name, e.g. "window://opened". */
+		topic: z.string().min(1),
+		/** Emitting window label, or "core" for the Rust core. */
+		source_label: z.string().min(1),
+		target: WindowEventTargetSchema,
+		payload: z.unknown(),
+	})
+	.strict();
+export type WindowEventEnvelope = z.infer<typeof WindowEventEnvelopeSchema>;
+
+/** Canonical window-lifecycle channels emitted by the Rust core. */
+export const WINDOW_TOPICS = {
+	opened: 'window://opened',
+	closed: 'window://closed',
+	focusChanged: 'window://focus-changed',
+} as const;
+export type WindowTopic = (typeof WINDOW_TOPICS)[keyof typeof WINDOW_TOPICS];
+
+/**
+ * Channels that MUST be window-targeted (`emit_to`) rather than broadcast,
+ * because a broadcast races across windows (first-reply-wins / wrong-window).
+ * Everything not listed here stays broadcast + per-window topic filtering.
+ * (plans/multi-window 03-research-internal: the ~25-channel routing table.)
+ */
+export const WINDOW_TARGETED_CHANNELS = [
+	'screenshot://request',
+	'screenshot://shortcut',
+	'projects:active-changed',
+] as const;