@roku-sdk/ai 0.0.0-stage → 2.19.0

package/src/__tests__/snippets.test.ts

@@ -0,0 +1,221 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "@jest/globals";
+import { readFileSync } from "fs";
+import { resolve } from "path";
+
+import { extractSnippets, SnippetMarkerError, UnclosedFenceError } from "../snippets";
+
+const PACKAGE_ROOT = resolve(__dirname, "..", "..");
+const FENCE = "```";
+
+/** Documents are built line-by-line so the expected `startLine` can be counted by eye. */
+function md(...lines: string[]): string {
+    return lines.join("\n");
+}
+
+describe("extractSnippets language filtering", () => {
+    it("returns ts and tsx fences", () => {
+        const doc = md(`${FENCE}ts`, "const a = 1;", FENCE, "", `${FENCE}tsx`, "const b = 2;", FENCE);
+        expect(extractSnippets(doc).map(snippet => snippet.lang)).toEqual(["ts", "tsx"]);
+    });
+
+    it("ignores fences in other languages and untagged fences", () => {
+        const doc = md(`${FENCE}bash`, "npm i", FENCE, "", `${FENCE}json`, "{}", FENCE, "", FENCE, "plain", FENCE);
+        expect(extractSnippets(doc)).toEqual([]);
+    });
+
+    it("accepts an upper-case language tag", () => {
+        expect(extractSnippets(md(`${FENCE}TSX`, "const a = 1;", FENCE))[0]?.lang).toBe("tsx");
+    });
+
+    it("returns an empty list for markdown with no fences", () => {
+        expect(extractSnippets("# Title\n\nProse mentioning `tsx` inline.\n")).toEqual([]);
+    });
+});
+
+describe("extractSnippets line offsets", () => {
+    it("points startLine at the first body line, counting frontmatter", () => {
+        const doc = md("---", "name: focus", "---", "", `${FENCE}tsx`, "const a = 1;", FENCE);
+        expect(extractSnippets(doc)[0]?.startLine).toBe(6);
+    });
+
+    it("maps a body offset onto the real file line", () => {
+        const doc = md("# Title", "", `${FENCE}tsx`, "const a = 1;", "const b = 2;", FENCE);
+        const [snippet] = extractSnippets(doc);
+        const offsetOfSecondLine = snippet.text.split("\n").indexOf("const b = 2;");
+        expect(snippet.startLine + offsetOfSecondLine).toBe(5);
+    });
+
+    it("excludes the delimiter lines from the body", () => {
+        const [snippet] = extractSnippets(md(`${FENCE}tsx`, "const a = 1;", FENCE));
+        expect(snippet.text).toBe("const a = 1;");
+    });
+
+    it("keeps offsets intact after an indented fence", () => {
+        const doc = md(
+            "- A list item:",
+            "",
+            `  ${FENCE}tsx`,
+            "  const indented = 1;",
+            `  ${FENCE}`,
+            "",
+            `${FENCE}tsx`,
+            "const real = 2;",
+            FENCE
+        );
+        const snippets = extractSnippets(doc);
+        expect(snippets).toHaveLength(1);
+        expect(snippets[0].startLine).toBe(8);
+    });
+
+    it("keeps offsets intact after a blockquoted fence", () => {
+        const doc = md(
+            `> ${FENCE}tsx`,
+            "> const quoted = 1;",
+            `> ${FENCE}`,
+            "",
+            `${FENCE}tsx`,
+            "const real = 2;",
+            FENCE
+        );
+        const snippets = extractSnippets(doc);
+        expect(snippets).toHaveLength(1);
+        expect(snippets[0].startLine).toBe(6);
+    });
+
+    it("keeps offsets intact for a file that ends with a newline", () => {
+        const doc = `${md(`${FENCE}tsx`, "const a = 1;", FENCE)}\n`;
+        expect(extractSnippets(doc)[0].startLine).toBe(2);
+    });
+
+    it("does not end a fence on a shorter delimiter inside it", () => {
+        const doc = md("````tsx", `const md = \`${FENCE}\`;`, "````", "", `${FENCE}tsx`, "const after = 1;", FENCE);
+        const snippets = extractSnippets(doc);
+        expect(snippets).toHaveLength(2);
+        expect(snippets[1].startLine).toBe(6);
+    });
+
+    it("scans tilde fences", () => {
+        expect(extractSnippets(md("~~~tsx", "const a = 1;", "~~~"))[0]?.text).toBe("const a = 1;");
+    });
+});
+
+describe("extractSnippets on a fence that never closes", () => {
+    it("reports the opening line and a stable code", () => {
+        const doc = md("# Skill", "", `${FENCE}tsx`, "const a = 1;", "", "## Notes", "Prose, not code.");
+        try {
+            extractSnippets(doc);
+            throw new Error("expected extractSnippets to throw");
+        } catch (error) {
+            expect(error).toBeInstanceOf(UnclosedFenceError);
+            expect((error as UnclosedFenceError).line).toBe(3);
+            expect((error as UnclosedFenceError).code).toBe("SNIPPET_FENCE_UNCLOSED");
+            expect((error as UnclosedFenceError).message).toContain("line 3");
+        }
+    });
+
+    // Checked for every language, not just the two this extracts: an open fence
+    // consumes the fences below it, so a `bash` one left open would cost the tsx
+    // samples after it and the file would pass on nothing.
+    it("rejects one in a language it does not check", () => {
+        expect(() => extractSnippets(md(`${FENCE}bash`, "npm i", "", "## Notes"))).toThrow(UnclosedFenceError);
+    });
+
+    it("says how long the unclosed delimiter was", () => {
+        expect(() => extractSnippets(md("~~~tsx", "const a = 1;"))).toThrow(/opened with 3 tildes/);
+    });
+
+    it("counts a longer closing delimiter as closing", () => {
+        expect(extractSnippets(md(`${FENCE}tsx`, "const a = 1;", "````"))).toHaveLength(1);
+    });
+});
+
+describe("extractSnippets modes", () => {
+    it("defaults when the fence carries no marker", () => {
+        expect(extractSnippets(md(`${FENCE}tsx`, "const a = 1;", FENCE))[0]?.mode).toBe("default");
+    });
+
+    it("reads complete and no-check from the info string", () => {
+        const doc = md(
+            `${FENCE}tsx rsg-skill=complete`,
+            "export const a = 1;",
+            FENCE,
+            "",
+            `${FENCE}ts rsg-skill=no-check`,
+            "this is deliberately wrong",
+            FENCE
+        );
+        expect(extractSnippets(doc).map(snippet => snippet.mode)).toEqual(["complete", "no-check"]);
+    });
+
+    it("ignores info-string words that are not the marker", () => {
+        expect(extractSnippets(md(`${FENCE}tsx interop`, "const a = 1;", FENCE))[0]?.mode).toBe("default");
+    });
+
+    it("still returns no-check snippets, so the caller decides what to skip", () => {
+        expect(extractSnippets(md(`${FENCE}tsx rsg-skill=no-check`, "const a = 1;", FENCE))).toHaveLength(1);
+    });
+});
+
+describe("extractSnippets marker errors", () => {
+    it("rejects an unrecognised marker value rather than defaulting", () => {
+        const doc = md("# Title", "", `${FENCE}tsx rsg-skill=skip`, "const a = 1;", FENCE);
+        expect(() => extractSnippets(doc)).toThrow(SnippetMarkerError);
+        expect(() => extractSnippets(doc)).toThrow(/rsg-skill=skip/);
+    });
+
+    it("rejects a marker with no value", () => {
+        expect(() => extractSnippets(md(`${FENCE}tsx rsg-skill`, "const a = 1;", FENCE))).toThrow(/needs a value/);
+    });
+
+    it("rejects a marker whose value differs only in case", () => {
+        expect(() => extractSnippets(md(`${FENCE}tsx rsg-skill=Complete`, "const a = 1;", FENCE))).toThrow(
+            SnippetMarkerError
+        );
+    });
+
+    it("rejects a fence carrying two markers", () => {
+        const doc = md(`${FENCE}tsx rsg-skill=complete rsg-skill=no-check`, "const a = 1;", FENCE);
+        expect(() => extractSnippets(doc)).toThrow(/more than one/);
+    });
+
+    it("reports the line of the offending fence and a stable code", () => {
+        const doc = md("# Title", "", "Prose.", "", `${FENCE}tsx rsg-skill=skip`, "const a = 1;", FENCE);
+        try {
+            extractSnippets(doc);
+            throw new Error("expected extractSnippets to throw");
+        } catch (error) {
+            expect(error).toBeInstanceOf(SnippetMarkerError);
+            expect((error as SnippetMarkerError).line).toBe(5);
+            expect((error as SnippetMarkerError).code).toBe("SNIPPET_MARKER_INVALID");
+            expect((error as SnippetMarkerError).message).toContain("line 5");
+        }
+    });
+
+    it("does not inspect markers on fences in other languages", () => {
+        expect(() => extractSnippets(md(`${FENCE}bash rsg-skill=nonsense`, "npm i", FENCE))).not.toThrow();
+    });
+});
+
+describe("extractSnippets on the shipped skills", () => {
+    // Asserted as properties of whatever the skill ships rather than as a fence
+    // count: how many samples an author writes is an authoring decision that
+    // changes with the prose, while the invariant this test exists for — a
+    // reported `startLine` that really is where the sample starts, which is what
+    // makes a snippet diagnostic navigable — holds for any number of them.
+    it("maps every sample in a shipped skill back to its real line", () => {
+        const path = resolve(PACKAGE_ROOT, "skills", "focus-management", "SKILL.md");
+        const source = readFileSync(path, "utf8");
+        const lines = source.split("\n");
+        const snippets = extractSnippets(source);
+
+        expect(snippets.length).toBeGreaterThan(0);
+        for (const snippet of snippets) {
+            expect(snippet.lang).toBe("tsx");
+            expect(lines[snippet.startLine - 1]).toBe(snippet.text.split("\n")[0]);
+        }
+        expect(snippets.map(snippet => snippet.text).join("\n")).toContain("@roku-sdk/navigation");
+    });
+});

package/src/__tests__/trigger-routing.test.ts

@@ -0,0 +1,77 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "@jest/globals";
+import { readFileSync } from "fs";
+import { resolve } from "path";
+
+import { loadManifest, type SkillManifest } from "../manifest";
+import { buildRouter, findCollisions, findCollisionsAcross, route, TriggerCollisionError } from "../router";
+
+const PACKAGE_ROOT = resolve(__dirname, "..", "..");
+
+function shippedManifest(): SkillManifest {
+    return loadManifest(JSON.parse(readFileSync(resolve(PACKAGE_ROOT, "skills-manifest.json"), "utf8")));
+}
+
+/** A synthetic entry. Routing reads only `name` and `triggers`. */
+function skill(name: string, triggers: string[]): SkillManifest["skills"][number] {
+    return { name, description: `Use when working with ${name}.`, triggers, path: `skills/${name}/SKILL.md` };
+}
+
+describe("trigger routing — shipped manifest routes cleanly", () => {
+    it("has no trigger collisions", () => {
+        expect(findCollisions(shippedManifest())).toEqual([]);
+    });
+
+    it("routes a known keyword to the expected skill", () => {
+        const router = buildRouter(shippedManifest());
+        expect(router.route("focus")).toBe("focus-management");
+        expect(router.route("FocusBoundary")).toBe("focus-management");
+    });
+
+    it("routes case-insensitively", () => {
+        expect(route(shippedManifest(), "FOCUS")).toBe("focus-management");
+    });
+
+    it("returns null for a query with no matching trigger", () => {
+        expect(buildRouter(shippedManifest()).route("nonexistent-keyword")).toBeNull();
+    });
+
+    it("exposes the normalized trigger → skill map via entries()", () => {
+        const entries = buildRouter(shippedManifest()).entries();
+        expect(entries.get("usefocusable")).toBe("focus-management");
+    });
+});
+
+describe("trigger routing — collision detection", () => {
+    const collidingManifest: SkillManifest = {
+        version: 1,
+        skills: [skill("focus-management", ["focus", "navigation"]), skill("screen-navigation", ["navigation"])]
+    };
+
+    it("reports a synthetic collision via findCollisions", () => {
+        const collisions = findCollisions(collidingManifest);
+        expect(collisions).toHaveLength(1);
+        expect(collisions[0].trigger).toBe("navigation");
+        expect(collisions[0].skills).toEqual(["focus-management", "screen-navigation"]);
+    });
+
+    it("buildRouter throws TriggerCollisionError on a synthetic collision", () => {
+        expect(() => buildRouter(collidingManifest)).toThrow(TriggerCollisionError);
+    });
+
+    it("detects collisions across multiple manifests", () => {
+        const a: SkillManifest = { version: 1, skills: [skill("focus-management", ["focus"])] };
+        const b: SkillManifest = { version: 1, skills: [skill("key-handling", ["Focus"])] };
+        const collisions = findCollisionsAcross([a, b]);
+        expect(collisions).toHaveLength(1);
+        expect(collisions[0].trigger).toBe("focus");
+        expect(collisions[0].skills).toEqual(["focus-management", "key-handling"]);
+    });
+
+    it("does not treat a repeated trigger within one skill as a collision", () => {
+        const manifest: SkillManifest = { version: 1, skills: [skill("focus-management", ["focus", "Focus"])] };
+        expect(findCollisions(manifest)).toEqual([]);
+    });
+});

package/src/index.ts

@@ -0,0 +1,36 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/**
+ * @module @roku-sdk/ai
+ * Public surface: manifest loading/validation and the trigger router.
+ */
+
+export {
+    loadManifest,
+    ManifestValidationError,
+    zSkillEntry,
+    zSkillManifest,
+    type SkillEntry,
+    type SkillManifest
+} from "./manifest";
+
+export {
+    buildRouter,
+    findCollisions,
+    findCollisionsAcross,
+    route,
+    TriggerCollisionError,
+    type Router,
+    type TriggerCollision
+} from "./router";
+
+export {
+    extractSnippets,
+    SnippetExtractionError,
+    SnippetMarkerError,
+    UnclosedFenceError,
+    type SkillSnippet,
+    type SnippetExtractionCode,
+    type SnippetMode
+} from "./snippets";

package/src/manifest.ts

@@ -0,0 +1,215 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/**
+ * @module manifest
+ * Types, zod schema, and loader for `skills-manifest.json`.
+ *
+ * The zod schema is the runtime authority; the shipped `skills-manifest.schema.json`
+ * gives editors/CI a static contract that mirrors it. This module is pure — no
+ * filesystem or network access.
+ *
+ * The mirror is deliberately one-directional about unknown keys. The JSON Schema
+ * rejects them, because an author who writes a key that does nothing wants to be
+ * told while editing. This schema ignores them, because manifests are discovered
+ * across independently-versioned `@roku-sdk/*` packages: a newer package may ship
+ * a field an older loader has never heard of, and refusing to load would fail a
+ * whole run over a field that run does not need.
+ */
+
+import { z } from "zod";
+
+/** kebab-case skill name; MUST equal the skill's directory name. */
+const NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/** POSIX path relative to the package root, resolving to a `SKILL.md`. */
+const PATH_PATTERN = /^skills\/[^/]+\/SKILL\.md$/;
+
+/**
+ * POSIX path relative to the package root, resolving to a reference document
+ * that loads on demand instead of riding in the body.
+ *
+ * Flat by design: the generated skill directory has one `references/` level, so
+ * a nested source path would either collapse two files onto one output name or
+ * force the output to mirror a hierarchy no reader benefits from.
+ */
+const REFERENCE_PATH_PATTERN = /^skills\/[^/]+\/references\/[^/]+\.md$/;
+
+/** Captures the skill directory from a `path`, to check `references` sit beside it. */
+const SKILL_DIR_PATTERN = /^skills\/([^/]+)\//;
+
+/** Matches any line break — activation descriptions must stay on one line. */
+const SINGLE_LINE_PATTERN = /[\r\n]/;
+
+/**
+ * One manifest entry per skill.
+ */
+export interface SkillEntry {
+    /** kebab-case; MUST equal the skill's directory name; unique within a manifest. */
+    name: string;
+    /**
+     * Single-line activation prose, surfaced verbatim as the generated skill's
+     * `description` frontmatter.
+     *
+     * This is the field an agent runtime matches on to decide whether to load the
+     * skill at all, so it is authored rather than derived: a description built by
+     * joining `triggers` reads as a keyword list and steers activation poorly.
+     * `triggers` remain the input to our own router, which is a separate concern.
+     */
+    description: string;
+    /** Non-empty; each trigger should be unique across all discovered manifests. */
+    triggers: string[];
+    /** POSIX path relative to the package root; MUST resolve to an existing SKILL.md. */
+    path: string;
+    /**
+     * Documents delivered alongside the body, for depth the body should not
+     * carry: the body is re-sent on every turn once the description matches,
+     * while a reference is read only when the task needs it.
+     *
+     * Declared rather than discovered from the directory, because this list is
+     * what the packaging check asserts is in the tarball and what the generator
+     * writes — a file present on disk but absent here would ship unwritten, and
+     * the body's pointer to it would resolve to nothing.
+     *
+     * Optional: a skill whose subject fits in one body declares none.
+     */
+    references?: string[];
+}
+
+/**
+ * The `skills-manifest.json` document.
+ */
+export interface SkillManifest {
+    /** Schema/format version of the manifest itself. */
+    version: 1;
+    skills: SkillEntry[];
+}
+
+export const zSkillEntry = z.object({
+    name: z.string().regex(NAME_PATTERN, "name must be kebab-case (matching the skill directory name)"),
+    // The 1024-character ceiling and the single-line rule are the Agent Skills
+    // frontmatter contract; a description violating either is rejected by the
+    // runtimes we generate for, so it is cheaper to fail here than downstream.
+    description: z
+        .string()
+        .min(1, "description is required")
+        .max(1024, "description must be at most 1024 characters")
+        .refine(value => !SINGLE_LINE_PATTERN.test(value), "description must be a single line"),
+    triggers: z
+        .array(z.string().min(1, "triggers must be non-empty strings"))
+        .nonempty("at least one trigger is required"),
+    path: z.string().regex(PATH_PATTERN, "path must be skills/<name>/SKILL.md"),
+    // Non-empty when present, matching the JSON Schema mirror: `references: []`
+    // reads as a claim the author meant to fill in and would otherwise pass here
+    // while failing an editor's validation.
+    references: z
+        .array(z.string().regex(REFERENCE_PATH_PATTERN, "each reference must be skills/<name>/references/<file>.md"))
+        .nonempty("references must not be empty when present")
+        .optional()
+});
+
+/**
+ * Report the cross-field rules on `references` that no single-field schema can
+ * express: a reference must sit beside the `SKILL.md` it belongs to, and the
+ * list must not repeat one.
+ *
+ * Both failures are otherwise silent and downstream. A reference under another
+ * skill's directory still matches the pattern, but the generator names its
+ * output from the *owning* skill, so the file would be emitted into a directory
+ * whose manifest entry never mentioned it — and pruning, which works by
+ * directory, would then fight the other skill for it. A duplicate entry plans
+ * the same write twice.
+ *
+ * Issues are raised at `skills.<i>.references.<j>` so the message reads like
+ * every other one this loader produces.
+ */
+function checkReferences(entry: z.infer<typeof zSkillEntry>, index: number, ctx: z.RefinementCtx): void {
+    const references = entry.references;
+    if (references === undefined) {
+        return;
+    }
+
+    const skillDir = SKILL_DIR_PATTERN.exec(entry.path)?.[1];
+    const seen = new Set<string>();
+
+    references.forEach((reference, refIndex) => {
+        const at = ["skills", index, "references", refIndex];
+        if (skillDir !== undefined && !reference.startsWith(`skills/${skillDir}/references/`)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: at,
+                message: `reference must sit under skills/${skillDir}/references/, beside the SKILL.md that declares it`
+            });
+        }
+        if (seen.has(reference)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: at,
+                message: `duplicate reference ${reference}`
+            });
+        }
+        seen.add(reference);
+    });
+}
+
+export const zSkillManifest = z
+    .object({
+        // Deliberately still 1, although making `description` required is a breaking
+        // change to the shape. A bump buys no compatibility: this is a strict literal,
+        // so version 2 would reject every version-1 document instead of accepting it,
+        // and there is no version-1 behavior worth preserving — an entry with no
+        // description cannot produce valid Agent Skills frontmatter, which is the only
+        // thing a manifest exists to feed. What makes that safe is the consumer set:
+        // discovery reads manifests only from installed `@roku-sdk/*` packages, so every
+        // manifest the pipeline sees ships alongside this loader and moves with it.
+        version: z.literal(1),
+        skills: z.array(zSkillEntry).nonempty("at least one skill is required")
+    })
+    .superRefine((manifest, ctx) => {
+        manifest.skills.forEach((entry, index) => checkReferences(entry, index, ctx));
+    });
+
+/**
+ * Thrown by {@link loadManifest} when the input does not satisfy the schema.
+ *
+ * Note: `@roku-sdk/ai` intentionally has no dependency on `@roku-sdk/tooling`
+ * (the dependency is strictly one-way, tooling → ai), so this error extends the
+ * native `Error` rather than tooling's `ToolingError`. Consumers in tooling may
+ * wrap it to attach a shell exit code.
+ */
+export class ManifestValidationError extends Error {
+    /** Semantic code for logging / consumers. */
+    readonly code = "MANIFEST_INVALID";
+    /** The underlying zod issues, for programmatic inspection. */
+    readonly issues: z.ZodIssue[];
+
+    constructor(message: string, issues: z.ZodIssue[]) {
+        super(message);
+        this.name = "ManifestValidationError";
+        this.issues = issues;
+    }
+}
+
+function formatIssues(issues: z.ZodIssue[]): string {
+    return issues
+        .map(issue => {
+            const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+            return `  - ${path}: ${issue.message}`;
+        })
+        .join("\n");
+}
+
+/**
+ * Validate raw JSON and return a typed {@link SkillManifest}.
+ *
+ * @throws {ManifestValidationError} with a descriptive, path-annotated message
+ *   when the input does not satisfy the schema.
+ */
+export function loadManifest(json: unknown): SkillManifest {
+    const result = zSkillManifest.safeParse(json);
+    if (!result.success) {
+        const details = formatIssues(result.error.issues);
+        throw new ManifestValidationError(`Invalid skills manifest:\n${details}`, result.error.issues);
+    }
+    return result.data;
+}