@roku-sdk/ai 0.0.0-stage → 2.19.0

package/src/router.ts

@@ -0,0 +1,147 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/**
+ * @module router
+ * Trigger router + collision detection.
+ *
+ * `buildRouter()`/`route()` map a query keyword to the skill that owns it and
+ * guarantee triggers are unique. `findCollisionsAcross()` checks for the same
+ * trigger being claimed by skills from more than one manifest, and is reused by
+ * tooling discovery when merging manifests. This module is pure — no filesystem
+ * or network.
+ *
+ * Triggers are treated as case-insensitive keywords: routing and collision
+ * detection both normalize to lowercase.
+ */
+
+import type { SkillManifest } from "./manifest";
+
+/**
+ * A single trigger owned by more than one skill.
+ */
+export interface TriggerCollision {
+    /** The normalized (lowercased) trigger keyword. */
+    trigger: string;
+    /** Names of the skills that claim this trigger, in first-seen order. */
+    skills: string[];
+}
+
+/**
+ * Resolves a query keyword to the skill that owns it.
+ */
+export interface Router {
+    /** Returns the owning skill name for a query, or `null` when no trigger matches. */
+    route(query: string): string | null;
+    /** The full normalized trigger → skill-name map. */
+    entries(): ReadonlyMap<string, string>;
+}
+
+/**
+ * Thrown by {@link buildRouter} when a trigger is claimed by more than one skill.
+ *
+ * `@roku-sdk/ai` has no dependency on `@roku-sdk/tooling`, so this extends the
+ * native `Error`; tooling may wrap it to attach a shell exit code.
+ */
+export class TriggerCollisionError extends Error {
+    /** Semantic code for logging / consumers. */
+    readonly code = "TRIGGER_COLLISION";
+    /** The collisions that caused the failure. */
+    readonly collisions: TriggerCollision[];
+
+    constructor(collisions: TriggerCollision[]) {
+        const detail = collisions.map(c => `  - "${c.trigger}" claimed by: ${c.skills.join(", ")}`).join("\n");
+        super(`Trigger collisions detected:\n${detail}`);
+        this.name = "TriggerCollisionError";
+        this.collisions = collisions;
+    }
+}
+
+function normalizeTrigger(trigger: string): string {
+    return trigger.trim().toLowerCase();
+}
+
+/**
+ * Detect triggers claimed by more than one skill across any number of manifests.
+ *
+ * Used both for a single manifest ({@link findCollisions}) and when tooling
+ * discovery merges manifests from several installed packages.
+ */
+export function findCollisionsAcross(manifests: SkillManifest[]): TriggerCollision[] {
+    // normalized trigger -> ordered, de-duplicated list of owning skill names
+    const owners = new Map<string, string[]>();
+
+    for (const manifest of manifests) {
+        for (const skill of manifest.skills) {
+            const seenForSkill = new Set<string>();
+            for (const rawTrigger of skill.triggers) {
+                const trigger = normalizeTrigger(rawTrigger);
+                // A skill listing the same trigger twice is not a cross-skill collision.
+                if (seenForSkill.has(trigger)) {
+                    continue;
+                }
+                seenForSkill.add(trigger);
+
+                const list = owners.get(trigger) ?? [];
+                if (!list.includes(skill.name)) {
+                    list.push(skill.name);
+                }
+                owners.set(trigger, list);
+            }
+        }
+    }
+
+    const collisions: TriggerCollision[] = [];
+    for (const [trigger, skills] of owners) {
+        if (skills.length > 1) {
+            collisions.push({ trigger, skills });
+        }
+    }
+    return collisions;
+}
+
+/**
+ * Detect triggers claimed by more than one skill within a single manifest.
+ */
+export function findCollisions(manifest: SkillManifest): TriggerCollision[] {
+    return findCollisionsAcross([manifest]);
+}
+
+/**
+ * Build a {@link Router} from a manifest.
+ *
+ * @throws {TriggerCollisionError} when any trigger is claimed by more than one skill.
+ */
+export function buildRouter(manifest: SkillManifest): Router {
+    const collisions = findCollisions(manifest);
+    if (collisions.length > 0) {
+        throw new TriggerCollisionError(collisions);
+    }
+
+    const map = new Map<string, string>();
+    for (const skill of manifest.skills) {
+        for (const rawTrigger of skill.triggers) {
+            map.set(normalizeTrigger(rawTrigger), skill.name);
+        }
+    }
+
+    return {
+        route(query: string): string | null {
+            return map.get(normalizeTrigger(query)) ?? null;
+        },
+        entries(): ReadonlyMap<string, string> {
+            return map;
+        }
+    };
+}
+
+/**
+ * Convenience: build a router for `manifest` and route `query` in one call.
+ *
+ * Prefer {@link buildRouter} when routing many queries against one manifest.
+ *
+ * @throws {TriggerCollisionError} when the manifest has trigger collisions.
+ */
+export function route(manifest: SkillManifest, query: string): string | null {
+    return buildRouter(manifest).route(query);
+}

package/src/snippets.ts

@@ -0,0 +1,212 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/**
+ * @module snippets
+ * TypeScript code samples embedded in a `SKILL.md`.
+ *
+ * A skill's sample is the part an agent copies, so it is the part that has to
+ * stay in step with the SDK. Extraction lives here, in the package that owns
+ * the skill format; the checking lives in internal tooling, because it needs
+ * the TypeScript compiler and the workspace layout and this package must stay
+ * dependency-free.
+ *
+ * Line numbers are absolute against the original file, so a diagnostic can be
+ * reported against the `SKILL.md` an author actually edits.
+ *
+ * This module is pure — no filesystem or network access.
+ */
+
+/**
+ * How thoroughly a snippet is checked.
+ *
+ * - `default` — imports must resolve and every identifier must be imported.
+ * - `complete` — additionally typechecks, for fences that are whole modules.
+ * - `no-check` — skipped, for deliberate anti-examples.
+ */
+export type SnippetMode = "complete" | "default" | "no-check";
+
+/** One TypeScript code fence from a `SKILL.md`. */
+export interface SkillSnippet {
+    /** Fence language tag, lowercased: `ts` or `tsx`. */
+    lang: "ts" | "tsx";
+    mode: SnippetMode;
+    /** Fence body, excluding the delimiter lines. */
+    text: string;
+    /** 1-based line of the first body line in the source file. */
+    startLine: number;
+}
+
+/** Closed set of extraction failures, so a consumer can map every one of them. */
+export type SnippetExtractionCode = "SNIPPET_FENCE_UNCLOSED" | "SNIPPET_MARKER_INVALID";
+
+/**
+ * Thrown by {@link extractSnippets} for markdown it cannot split into fences.
+ *
+ * `@roku-sdk/ai` has no dependency on `@roku-sdk/tooling`, so this extends the
+ * native `Error`; tooling may wrap it to attach a shell exit code.
+ */
+export abstract class SnippetExtractionError extends Error {
+    /** Semantic code for logging / consumers. */
+    abstract readonly code: SnippetExtractionCode;
+    /** 1-based line of the fence's opening delimiter. */
+    readonly line: number;
+
+    constructor(message: string, line: number) {
+        super(`${message} (line ${line})`);
+        this.line = line;
+    }
+}
+
+/**
+ * Thrown by {@link extractSnippets} for a fence marker it cannot interpret.
+ *
+ * A marker that is present but unreadable must not degrade to the default
+ * mode: an author writing `rsg-skill=skip` is asking for the snippet to be
+ * exempt, and silently checking it instead would leave them arguing with a
+ * diagnostic they thought they had turned off.
+ */
+export class SnippetMarkerError extends SnippetExtractionError {
+    readonly code = "SNIPPET_MARKER_INVALID";
+
+    constructor(message: string, line: number) {
+        super(message, line);
+        this.name = "SnippetMarkerError";
+    }
+}
+
+/**
+ * Thrown by {@link extractSnippets} for a fence that is never closed.
+ *
+ * An unterminated fence has no end, so every line after it belongs to it:
+ * prose, headings and later fences all land in one snippet. Reporting that as
+ * syntax errors would point an author at their markdown, and when the open
+ * fence is not a TypeScript one it is worse than noisy — an unclosed `bash`
+ * fence swallows the `tsx` fences below it, and a file whose samples have all
+ * vanished is a file that passes.
+ */
+export class UnclosedFenceError extends SnippetExtractionError {
+    readonly code = "SNIPPET_FENCE_UNCLOSED";
+
+    constructor(delimiter: string, line: number) {
+        // Spelled out rather than quoted: a backtick delimiter inside backticks
+        // prints as a row of five, which reads as noise in a terminal.
+        const character = delimiter.startsWith("~") ? "tildes" : "backticks";
+        super(`Code fence opened with ${delimiter.length} ${character} is never closed`, line);
+        this.name = "UnclosedFenceError";
+    }
+}
+
+/** Opening delimiter at column 0: three or more backticks or tildes. */
+const OPENING = /^(`{3,}|~{3,})\s*(.*)$/;
+
+/** The token that carries the mode, e.g. `tsx rsg-skill=complete`. */
+const MARKER = "rsg-skill";
+
+const MODES_BY_MARKER_VALUE: Readonly<Record<string, SnippetMode>> = {
+    complete: "complete",
+    "no-check": "no-check"
+};
+
+/**
+ * The mode a fence's info string asks for.
+ *
+ * Only the language is lowercased. Marker values are matched exactly so that
+ * the accepted spellings stay a closed set of two; `rsg-skill=Complete` is
+ * reported rather than accepted, because a second accepted spelling is a
+ * second thing to keep working forever.
+ */
+function modeFromInfoWords(words: readonly string[], line: number): SnippetMode {
+    const markers = words.filter(word => word === MARKER || word.startsWith(`${MARKER}=`));
+    if (markers.length === 0) {
+        return "default";
+    }
+    if (markers.length > 1) {
+        throw new SnippetMarkerError(`Fence carries more than one \`${MARKER}\` marker: ${markers.join(" ")}`, line);
+    }
+
+    const accepted = Object.keys(MODES_BY_MARKER_VALUE)
+        .map(value => `${MARKER}=${value}`)
+        .join(", ");
+    const [marker] = markers;
+    if (marker === MARKER) {
+        throw new SnippetMarkerError(`Fence marker \`${MARKER}\` needs a value; expected one of ${accepted}`, line);
+    }
+
+    const mode = MODES_BY_MARKER_VALUE[marker.slice(MARKER.length + 1)];
+    if (mode === undefined) {
+        throw new SnippetMarkerError(`Unrecognised fence marker \`${marker}\`; expected one of ${accepted}`, line);
+    }
+    return mode;
+}
+
+/**
+ * Index of the closing delimiter, or `lines.length` when there is none. A
+ * closing fence uses the same character and is at least as long as the opening
+ * one.
+ */
+function findClosing(lines: readonly string[], from: number, char: string, minLength: number): number {
+    const closing = new RegExp(`^\\${char}{${minLength},}\\s*$`);
+    for (let index = from; index < lines.length; index += 1) {
+        if (closing.test(lines[index])) {
+            return index;
+        }
+    }
+    return lines.length;
+}
+
+/**
+ * Split a `SKILL.md` into its TypeScript code fences.
+ *
+ * A fence must start at column 0, which excludes indented code blocks, inline
+ * code spans, and fences quoted inside a blockquote — none of which are the
+ * copyable sample this exists to check.
+ *
+ * Frontmatter is deliberately not stripped: `startLine` only means anything if
+ * it counts from the top of the real file, and a `---` block cannot be
+ * mistaken for a fence.
+ *
+ * Every fence must close, including the ones whose language this ignores: an
+ * open fence of any language consumes the fences below it, so tolerating one
+ * would mean returning fewer snippets than the file appears to hold.
+ *
+ * @param markdown Full file text.
+ * @throws {SnippetMarkerError} for a fence marker that cannot be interpreted.
+ * @throws {UnclosedFenceError} for a fence with no closing delimiter.
+ */
+export function extractSnippets(markdown: string): SkillSnippet[] {
+    const lines = markdown.split("\n");
+    const snippets: SkillSnippet[] = [];
+
+    let index = 0;
+    while (index < lines.length) {
+        const opening = OPENING.exec(lines[index]);
+        if (opening === null) {
+            index += 1;
+            continue;
+        }
+
+        const [, delimiter, infoString] = opening;
+        const closingIndex = findClosing(lines, index + 1, delimiter[0], delimiter.length);
+        if (closingIndex === lines.length) {
+            throw new UnclosedFenceError(delimiter, index + 1);
+        }
+
+        const words = infoString.trim().split(/\s+/).filter(Boolean);
+        const lang = words[0]?.toLowerCase();
+
+        if (lang === "ts" || lang === "tsx") {
+            snippets.push({
+                lang,
+                mode: modeFromInfoWords(words.slice(1), index + 1),
+                text: lines.slice(index + 1, closingIndex).join("\n"),
+                // Lines are 1-based and the body starts after the delimiter.
+                startLine: index + 2
+            });
+        }
+
+        index = closingIndex + 1;
+    }
+
+    return snippets;
+}