@ikenga/contract 0.12.0 → 0.13.0

package/dist/action-frontmatter.d.ts

@@ -0,0 +1,389 @@
+import { z } from 'zod';
+/**
+ * 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 declare const DomainEnum: z.ZodEnum<["tasks", "mail", "outbound", "sales", "finance", "content", "research", "strategy", "skill-core"]>;
+export type Domain = z.infer<typeof DomainEnum>;
+/**
+ * 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 declare const UxModeEnum: z.ZodEnum<["confirm", "silent", "form", "streaming", "approve"]>;
+export type UxMode = z.infer<typeof UxModeEnum>;
+export declare const RunBinding: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"chat_prompt">;
+    prompt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "chat_prompt";
+    prompt: string;
+}, {
+    kind: "chat_prompt";
+    prompt: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"sidecar">;
+    sidecar_id: z.ZodString;
+    args: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    kind: "sidecar";
+    sidecar_id: string;
+    args: string[];
+}, {
+    kind: "sidecar";
+    sidecar_id: string;
+    args?: string[] | undefined;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"mcp_tool">;
+    server_id: z.ZodString;
+    tool: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "mcp_tool";
+    server_id: string;
+    tool: string;
+}, {
+    kind: "mcp_tool";
+    server_id: string;
+    tool: string;
+}>]>;
+export type RunBinding = z.infer<typeof RunBinding>;
+export declare const Trigger: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"manual">;
+}, "strip", z.ZodTypeAny, {
+    kind: "manual";
+}, {
+    kind: "manual";
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"schedule">;
+    cron: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    kind: "schedule";
+    cron: string;
+    label?: string | undefined;
+}, {
+    kind: "schedule";
+    cron: string;
+    label?: string | undefined;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"webhook">;
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    kind: "webhook";
+}, {
+    path: string;
+    kind: "webhook";
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"event">;
+    event: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "event";
+    event: string;
+}, {
+    kind: "event";
+    event: string;
+}>]>;
+export type Trigger = z.infer<typeof Trigger>;
+export declare const CapabilityEnum: z.ZodEnum<["sqlite", "mcp", "sidecar", "network", "fs", "secrets", "chat"]>;
+export type Capability = z.infer<typeof CapabilityEnum>;
+export declare const SetupModeEnum: z.ZodEnum<["ai_infer", "interview"]>;
+export type SetupMode = z.infer<typeof SetupModeEnum>;
+export declare const SetupSpec: z.ZodObject<{
+    mode: z.ZodEnum<["ai_infer", "interview"]>;
+    template_version: z.ZodNumber;
+    infer_sources: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    interview_questions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    mode: "ai_infer" | "interview";
+    template_version: number;
+    infer_sources?: string[] | undefined;
+    interview_questions?: string[] | undefined;
+}, {
+    mode: "ai_infer" | "interview";
+    template_version: number;
+    infer_sources?: string[] | undefined;
+    interview_questions?: string[] | undefined;
+}>;
+export type SetupSpec = z.infer<typeof SetupSpec>;
+export declare const ActionFrontmatter: z.ZodEffects<z.ZodObject<{
+    /** Stable action id, unique within the skill. kebab-case. */
+    name: z.ZodString;
+    /** One-line human description shown in the command surface. */
+    description: z.ZodString;
+    /** Owning domain (G-TAXONOMY). */
+    domain: z.ZodEnum<["tasks", "mail", "outbound", "sales", "finance", "content", "research", "strategy", "skill-core"]>;
+    /** How the action presents to the operator (R5/E-11). */
+    ux_mode: z.ZodEnum<["confirm", "silent", "form", "streaming", "approve"]>;
+    /**
+     * 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.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** What the action actually does (G-01). */
+    run: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"chat_prompt">;
+        prompt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "chat_prompt";
+        prompt: string;
+    }, {
+        kind: "chat_prompt";
+        prompt: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"sidecar">;
+        sidecar_id: z.ZodString;
+        args: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "sidecar";
+        sidecar_id: string;
+        args: string[];
+    }, {
+        kind: "sidecar";
+        sidecar_id: string;
+        args?: string[] | undefined;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"mcp_tool">;
+        server_id: z.ZodString;
+        tool: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "mcp_tool";
+        server_id: string;
+        tool: string;
+    }, {
+        kind: "mcp_tool";
+        server_id: string;
+        tool: string;
+    }>]>;
+    /** How the action can be invoked. Empty ⇒ manual-only. */
+    triggers: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"manual">;
+    }, "strip", z.ZodTypeAny, {
+        kind: "manual";
+    }, {
+        kind: "manual";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"schedule">;
+        cron: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "schedule";
+        cron: string;
+        label?: string | undefined;
+    }, {
+        kind: "schedule";
+        cron: string;
+        label?: string | undefined;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"webhook">;
+        path: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        kind: "webhook";
+    }, {
+        path: string;
+        kind: "webhook";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"event">;
+        event: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "event";
+        event: string;
+    }, {
+        kind: "event";
+        event: string;
+    }>]>, "many">>;
+    /**
+     * 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.ZodDefault<z.ZodArray<z.ZodLiteral<"skill-core">, "many">>;
+    /** Coarse capability grants this action needs (G-08, R18/R19). */
+    requires_capabilities: z.ZodDefault<z.ZodArray<z.ZodEnum<["sqlite", "mcp", "sidecar", "network", "fs", "secrets", "chat"]>, "many">>;
+    /**
+     * Present ONLY on the well-known `setup` action. Omitted on every other
+     * action. Refined below.
+     */
+    setup: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<["ai_infer", "interview"]>;
+        template_version: z.ZodNumber;
+        infer_sources: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        interview_questions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "ai_infer" | "interview";
+        template_version: number;
+        infer_sources?: string[] | undefined;
+        interview_questions?: string[] | undefined;
+    }, {
+        mode: "ai_infer" | "interview";
+        template_version: number;
+        infer_sources?: string[] | undefined;
+        interview_questions?: string[] | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    domain: "tasks" | "mail" | "outbound" | "sales" | "finance" | "content" | "research" | "strategy" | "skill-core";
+    ux_mode: "confirm" | "silent" | "form" | "streaming" | "approve";
+    run: {
+        kind: "chat_prompt";
+        prompt: string;
+    } | {
+        kind: "sidecar";
+        sidecar_id: string;
+        args: string[];
+    } | {
+        kind: "mcp_tool";
+        server_id: string;
+        tool: string;
+    };
+    triggers: ({
+        kind: "manual";
+    } | {
+        kind: "schedule";
+        cron: string;
+        label?: string | undefined;
+    } | {
+        path: string;
+        kind: "webhook";
+    } | {
+        kind: "event";
+        event: string;
+    })[];
+    depends_on: "skill-core"[];
+    requires_capabilities: ("sidecar" | "sqlite" | "mcp" | "network" | "fs" | "secrets" | "chat")[];
+    inputs_schema?: Record<string, unknown> | undefined;
+    setup?: {
+        mode: "ai_infer" | "interview";
+        template_version: number;
+        infer_sources?: string[] | undefined;
+        interview_questions?: string[] | undefined;
+    } | undefined;
+}, {
+    name: string;
+    description: string;
+    domain: "tasks" | "mail" | "outbound" | "sales" | "finance" | "content" | "research" | "strategy" | "skill-core";
+    ux_mode: "confirm" | "silent" | "form" | "streaming" | "approve";
+    run: {
+        kind: "chat_prompt";
+        prompt: string;
+    } | {
+        kind: "sidecar";
+        sidecar_id: string;
+        args?: string[] | undefined;
+    } | {
+        kind: "mcp_tool";
+        server_id: string;
+        tool: string;
+    };
+    inputs_schema?: Record<string, unknown> | undefined;
+    triggers?: ({
+        kind: "manual";
+    } | {
+        kind: "schedule";
+        cron: string;
+        label?: string | undefined;
+    } | {
+        path: string;
+        kind: "webhook";
+    } | {
+        kind: "event";
+        event: string;
+    })[] | undefined;
+    depends_on?: "skill-core"[] | undefined;
+    requires_capabilities?: ("sidecar" | "sqlite" | "mcp" | "network" | "fs" | "secrets" | "chat")[] | undefined;
+    setup?: {
+        mode: "ai_infer" | "interview";
+        template_version: number;
+        infer_sources?: string[] | undefined;
+        interview_questions?: string[] | undefined;
+    } | undefined;
+}>, {
+    name: string;
+    description: string;
+    domain: "tasks" | "mail" | "outbound" | "sales" | "finance" | "content" | "research" | "strategy" | "skill-core";
+    ux_mode: "confirm" | "silent" | "form" | "streaming" | "approve";
+    run: {
+        kind: "chat_prompt";
+        prompt: string;
+    } | {
+        kind: "sidecar";
+        sidecar_id: string;
+        args: string[];
+    } | {
+        kind: "mcp_tool";
+        server_id: string;
+        tool: string;
+    };
+    triggers: ({
+        kind: "manual";
+    } | {
+        kind: "schedule";
+        cron: string;
+        label?: string | undefined;
+    } | {
+        path: string;
+        kind: "webhook";
+    } | {
+        kind: "event";
+        event: string;
+    })[];
+    depends_on: "skill-core"[];
+    requires_capabilities: ("sidecar" | "sqlite" | "mcp" | "network" | "fs" | "secrets" | "chat")[];
+    inputs_schema?: Record<string, unknown> | undefined;
+    setup?: {
+        mode: "ai_infer" | "interview";
+        template_version: number;
+        infer_sources?: string[] | undefined;
+        interview_questions?: string[] | undefined;
+    } | undefined;
+}, {
+    name: string;
+    description: string;
+    domain: "tasks" | "mail" | "outbound" | "sales" | "finance" | "content" | "research" | "strategy" | "skill-core";
+    ux_mode: "confirm" | "silent" | "form" | "streaming" | "approve";
+    run: {
+        kind: "chat_prompt";
+        prompt: string;
+    } | {
+        kind: "sidecar";
+        sidecar_id: string;
+        args?: string[] | undefined;
+    } | {
+        kind: "mcp_tool";
+        server_id: string;
+        tool: string;
+    };
+    inputs_schema?: Record<string, unknown> | undefined;
+    triggers?: ({
+        kind: "manual";
+    } | {
+        kind: "schedule";
+        cron: string;
+        label?: string | undefined;
+    } | {
+        path: string;
+        kind: "webhook";
+    } | {
+        kind: "event";
+        event: string;
+    })[] | undefined;
+    depends_on?: "skill-core"[] | undefined;
+    requires_capabilities?: ("sidecar" | "sqlite" | "mcp" | "network" | "fs" | "secrets" | "chat")[] | undefined;
+    setup?: {
+        mode: "ai_infer" | "interview";
+        template_version: number;
+        infer_sources?: string[] | undefined;
+        interview_questions?: string[] | undefined;
+    } | undefined;
+}>;
+export type ActionFrontmatter = z.infer<typeof ActionFrontmatter>;
+//# sourceMappingURL=action-frontmatter.d.ts.map

package/dist/action-frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-frontmatter.d.ts","sourceRoot":"","sources":["../src/action-frontmatter.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;;GAGG;AACH,eAAO,MAAM,UAAU,+GAUrB,CAAC;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAMhD;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,kEAMrB,CAAC;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AA4BhD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAIrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAiCpD,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAKlB,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,OAAO,CAAC,CAAC;AAY9C,eAAO,MAAM,cAAc,6EAQzB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAcxD,eAAO,MAAM,aAAa,sCAAoC,CAAC;AAC/D,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEtD,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;EAQpB,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAMlD,eAAO,MAAM,iBAAiB;IAG1B,6DAA6D;;IAK7D,+DAA+D;;IAE/D,kCAAkC;;IAIlC,yDAAyD;;IAEzD;;;;OAIG;;IAIH,4CAA4C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAE5C,0DAA0D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAI1D;;;;;OAKG;;IAEH,kEAAkE;;IAIlE;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuBH,CAAC;AAEL,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/action-frontmatter.js

@@ -0,0 +1,215 @@
+// 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',
+]);
+// ---------------------------------------------------------------------------
+// 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',
+]);
+// ---------------------------------------------------------------------------
+// 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,
+]);
+// ---------------------------------------------------------------------------
+// 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,
+]);
+// ---------------------------------------------------------------------------
+// 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
+]);
+// ---------------------------------------------------------------------------
+// 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 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(),
+});
+// ---------------------------------------------------------------------------
+// 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.)
+});
+//# sourceMappingURL=action-frontmatter.js.map

package/dist/action-frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-frontmatter.js","sourceRoot":"","sources":["../src/action-frontmatter.ts"],"names":[],"mappings":"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"}