@qodo/sdk 0.13.4 → 2.0.0-next.0

package/dist/skills/types.js

@@ -0,0 +1,85 @@
+/**
+ * Skills foundation types.
+ *
+ * SDK 2.0 is a thin typed wire binding to QAR (Qodo Agent Runtime); it does
+ * not execute agents. Skills here are a *consumer-side* concept: the SDK
+ * reads `SKILL.md` files from the configured sources, builds an in-memory
+ * catalog, and injects a slim `<available_skills>` index into
+ * `InlineAgentSpec.instructions` so the QAR-side model loop sees what
+ * skills exist. Runtime body loading lives in the `qodo-skills` MCP
+ * server.
+ *
+ * The frontmatter shape mirrors the Agent Skills open standard
+ * (`name` / `description` / `when_to_use` / `allowed-tools` / ...) plus
+ * Qodo extensions (`vendor`, `version`, `min_sdk_version`, `requires`).
+ * Unknown fields are preserved on `unknown_fields` so forward-compat is
+ * by silence, not error.
+ */
+/** Preprocessing config defaults — exported so tests stay in sync with the runtime. */
+export const PREPROCESS_DEFAULT_TIMEOUT_MS = 5000;
+export const PREPROCESS_DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024;
+/** Default top-K when `SkillsConfig.activation.topK` is unset. */
+export const ACTIVATION_DEFAULT_TOP_K = 8;
+/** Default minimum cosine score when `SkillsConfig.activation.minScore` is unset. */
+export const ACTIVATION_DEFAULT_MIN_SCORE = 0.35;
+/** Resolved cap defaults used when `SkillsConfig.requires` fields are absent. */
+export const REQUIRES_DEFAULT_MAX_DEPTH = 3;
+export const REQUIRES_DEFAULT_MAX_TRANSITIVE = 8;
+export const REQUIRES_DEFAULT_MAX_TRANSITIVE_TOKENS = 50 * 1024;
+// ---------------------------------------------------------------------------
+// Constants — wire defaults the renderer + parser refer to
+// ---------------------------------------------------------------------------
+/**
+ * Per-entry `description + when_to_use` cap in the slim index. Mirrors
+ * Claude Code's `SLASH_COMMAND_TOOL_CHAR_BUDGET` so OSS skills land
+ * identically.
+ */
+export const SLIM_INDEX_ENTRY_BUDGET = 1536;
+/** Default total cap on the `<available_skills>` block. */
+export const DEFAULT_INDEX_CHAR_BUDGET = 8000;
+/** Hard cap on `SKILL.md` body size — exclusion threshold. */
+export const SKILL_BODY_HARD_BYTES = 50 * 1024;
+/**
+ * Hard cap on total `SKILL.md` file size (frontmatter + body + structure)
+ * enforced *before* `fs.readFile` — files larger than this are rejected
+ * with `sdk.skill.error` severity `'error'` and never read into memory.
+ * Comfortably above `SKILL_BODY_HARD_BYTES` so a generous frontmatter
+ * fits, but tight enough to defend against a third-party `package` /
+ * `cli-fetched` source shipping multi-megabyte SKILL.md files —
+ * defense-in-depth against DoS via unbounded `fs.readFile`.
+ */
+export const SKILL_FILE_HARD_BYTES = 256 * 1024;
+/** Soft cap on `SKILL.md` body lines — emits warning, does not exclude. */
+export const SKILL_BODY_SOFT_LINES = 500;
+/** Max chars in a skill `name`. Reserved-word + character-class checks live in the validator. */
+export const SKILL_NAME_MAX_CHARS = 64;
+/** Reserved words a skill `name` cannot include (case-insensitive substring). */
+export const SKILL_NAME_RESERVED_WORDS = ['anthropic', 'claude'];
+/** Default `vendor` per source type. Frontmatter `vendor:` overrides. */
+export const SOURCE_DEFAULT_VENDORS = {
+    project: 'local',
+    config: 'local',
+    user: 'user',
+    package: '__from_package_name__', // sentinel — manager resolves to packageName
+    'cli-fetched': '__from_ref__', // sentinel — manager resolves to <vendor> portion of ref
+    bundled: 'qodo',
+};
+/** Trust tier per source type. Mirror of `SkillTrustTier` documentation. */
+export const SOURCE_TRUST_TIERS = {
+    project: 'trusted',
+    config: 'trusted',
+    bundled: 'trusted',
+    user: 'operator',
+    package: 'third-party',
+    'cli-fetched': 'third-party',
+};
+/** Default precedence (highest first). */
+export const DEFAULT_SOURCE_ORDER = [
+    'project',
+    'config',
+    'user',
+    'package',
+    'cli-fetched',
+    'bundled',
+];
+//# sourceMappingURL=types.js.map

package/dist/skills/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/skills/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA8MH,uFAAuF;AACvF,MAAM,CAAC,MAAM,6BAA6B,GAAG,IAAI,CAAC;AAClD,MAAM,CAAC,MAAM,mCAAmC,GAAG,EAAE,GAAG,IAAI,CAAC;AAe7D,kEAAkE;AAClE,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAC1C,qFAAqF;AACrF,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAI,CAAC;AAwGjD,iFAAiF;AACjF,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC;AAC5C,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC;AACjD,MAAM,CAAC,MAAM,sCAAsC,GAAG,EAAE,GAAG,IAAI,CAAC;AAkXhE,8EAA8E;AAC9E,2DAA2D;AAC3D,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAE5C,2DAA2D;AAC3D,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAC;AAE9C,8DAA8D;AAC9D,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,GAAG,IAAI,CAAC;AAE/C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,GAAG,IAAI,CAAC;AAEhD,2EAA2E;AAC3E,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAEzC,iGAAiG;AACjG,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEvC,iFAAiF;AACjF,MAAM,CAAC,MAAM,yBAAyB,GAAsB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;AAEpF,yEAAyE;AACzE,MAAM,CAAC,MAAM,sBAAsB,GAA8C;IAC/E,OAAO,EAAE,OAAO;IAChB,MAAM,EAAE,OAAO;IACf,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,uBAAuB,EAAE,6CAA6C;IAC/E,aAAa,EAAE,cAAc,EAAE,yDAAyD;IACxF,OAAO,EAAE,MAAM;CAChB,CAAC;AAEF,4EAA4E;AAC5E,MAAM,CAAC,MAAM,kBAAkB,GAAsD;IACnF,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,SAAS;IACjB,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,aAAa;IACtB,aAAa,EAAE,aAAa;CAC7B,CAAC;AAEF,0CAA0C;AAC1C,MAAM,CAAC,MAAM,oBAAoB,GAA+B;IAC9D,SAAS;IACT,QAAQ;IACR,MAAM;IACN,SAAS;IACT,aAAa;IACb,SAAS;CACV,CAAC"}

package/dist/skills/validator.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Frontmatter + body validator for skill documents.
+ *
+ * Operates on the output of `parseSkillDocument()` plus the skill's
+ * directory name (used as the default `name`) and source. Returns a typed
+ * `SkillFrontmatter` plus a list of warnings/errors so the manager can
+ * emit `sdk.skill.error` events with the appropriate severity.
+ *
+ * Rules enforced here (everything else is the manager's job — shadowing,
+ * versioning, FQN construction):
+ *
+ *   - `name` regex + reserved-word ban + length cap.
+ *   - `description` length cap (1024 chars).
+ *   - `when_to_use` length cap (1024 chars).
+ *   - `allowed-tools` normalization (string-or-array → `AllowedToolEntry[]`
+ *     with `Tool(args)` parsed).
+ *   - `arguments` normalization (string-or-object form → `SkillArgument[]`).
+ *   - `paths` shape (array of strings).
+ *   - Booleans for `disable-model-invocation`, `user-invocable`.
+ *   - `version` semver shape; defaults to `0.0.0` if absent.
+ *   - `min_sdk_version` semver shape.
+ *   - `requires` shape (array of strings).
+ *   - `effort`, `context`, `shell` enum membership.
+ *   - Body size — 50 KB hard error, 500-line warning.
+ *
+ * Unknown frontmatter fields are NOT rejected; they're preserved on
+ * `frontmatter.unknown_fields` for forward compatibility and emitted as
+ * `sdk.skill.unknown_field` debug events.
+ */
+import type { JsonValue } from '../qar/json.js';
+import type { SkillEventSeverity, SkillFrontmatter } from './types.js';
+/**
+ * One validation diagnostic emitted by `validateFrontmatter` /
+ * `validateBody`. The manager translates these into `sdk.skill.error`
+ * events with the skill's path attached.
+ */
+export interface ValidationIssue {
+    readonly severity: SkillEventSeverity;
+    readonly message: string;
+    /** When emitted from `validateFrontmatter`, the offending field. */
+    readonly field?: string;
+}
+export interface ValidatedFrontmatter {
+    readonly frontmatter: SkillFrontmatter;
+    readonly issues: readonly ValidationIssue[];
+    /** Unknown fields preserved verbatim; emit `sdk.skill.unknown_field` per entry. */
+    readonly unknownFields: readonly string[];
+}
+export interface ValidatedBody {
+    readonly issues: readonly ValidationIssue[];
+}
+/**
+ * Validate parsed frontmatter against the skill contract. Returns a typed
+ * `SkillFrontmatter` (always present — even on failure, the validator
+ * preserves whatever it could parse) plus a list of issues. Fatal issues
+ * carry `severity: 'error'`; the manager treats those as catalog
+ * exclusions.
+ */
+export declare function validateFrontmatter(raw: Readonly<Record<string, JsonValue>>, defaultName: string): ValidatedFrontmatter;
+/**
+ * Validate the body — 50 KB hard cap (error, exclude skill), 500-line soft
+ * cap (warning, include anyway).
+ */
+export declare function validateBody(body: string): ValidatedBody;
+/**
+ * Result of {@link extractBodyReferences} — one entry per `[label](path)`
+ * markdown link OR `get_skill_file(path)` reference observed in the body.
+ *
+ * Only relative paths land in the result; absolute URLs (`https://...`,
+ * `mailto:`, anchors `#section`) are filtered out — they don't reference
+ * supporting files.
+ */
+export interface BodyReference {
+    /** The link target — normalized to POSIX separators, stripped of `./`. */
+    readonly path: string;
+    /** Path-segment depth (number of `/` separators + 1). */
+    readonly depth: number;
+}
+/**
+ * Extract supporting-file references from a SKILL.md body. Two forms are
+ * recognized per `skills-progressive-disclosure.md`:
+ *
+ *   - Markdown links: `[label](path/to/file.ext)`.
+ *   - Explicit tool calls: `get_skill_file("path/to/file")` (string arg).
+ *
+ * Both must be relative; external URLs and anchors are skipped.
+ */
+export declare function extractBodyReferences(body: string): readonly BodyReference[];
+/** Compare two semver strings (`a < b`). Both must match `SEMVER_RE`. */
+export declare function semverLessThan(a: string, b: string): boolean;
+/** Return `true` iff the version strings refer to the same version. */
+export declare function semverEqual(a: string, b: string): boolean;
+/** Test helper exposed for the validator's own unit suite. */
+export declare function isValidSemver(s: string): boolean;
+//# sourceMappingURL=validator.d.ts.map

package/dist/skills/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/skills/validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAGV,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AA4CpB;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IAC5C,mFAAmF;IACnF,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,EACxC,WAAW,EAAE,MAAM,GAClB,oBAAoB,CAsKtB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAiBxD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,aAAa,EAAE,CAiC5E;AA6BD,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAa5D;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEhD"}

package/dist/skills/validator.js

@@ -0,0 +1,486 @@
+/**
+ * Frontmatter + body validator for skill documents.
+ *
+ * Operates on the output of `parseSkillDocument()` plus the skill's
+ * directory name (used as the default `name`) and source. Returns a typed
+ * `SkillFrontmatter` plus a list of warnings/errors so the manager can
+ * emit `sdk.skill.error` events with the appropriate severity.
+ *
+ * Rules enforced here (everything else is the manager's job — shadowing,
+ * versioning, FQN construction):
+ *
+ *   - `name` regex + reserved-word ban + length cap.
+ *   - `description` length cap (1024 chars).
+ *   - `when_to_use` length cap (1024 chars).
+ *   - `allowed-tools` normalization (string-or-array → `AllowedToolEntry[]`
+ *     with `Tool(args)` parsed).
+ *   - `arguments` normalization (string-or-object form → `SkillArgument[]`).
+ *   - `paths` shape (array of strings).
+ *   - Booleans for `disable-model-invocation`, `user-invocable`.
+ *   - `version` semver shape; defaults to `0.0.0` if absent.
+ *   - `min_sdk_version` semver shape.
+ *   - `requires` shape (array of strings).
+ *   - `effort`, `context`, `shell` enum membership.
+ *   - Body size — 50 KB hard error, 500-line warning.
+ *
+ * Unknown frontmatter fields are NOT rejected; they're preserved on
+ * `frontmatter.unknown_fields` for forward compatibility and emitted as
+ * `sdk.skill.unknown_field` debug events.
+ */
+import { SKILL_BODY_HARD_BYTES, SKILL_BODY_SOFT_LINES, SKILL_NAME_MAX_CHARS, SKILL_NAME_RESERVED_WORDS, } from './types.js';
+/** Description / when_to_use per-field cap. Mirrors the standard's 1024-char limit. */
+const FIELD_CHAR_CAP = 1024;
+/** Recognized top-level frontmatter keys. Anything else lands in `unknown_fields`. */
+const KNOWN_FIELDS = new Set([
+    'name',
+    'description',
+    'when_to_use',
+    'allowed-tools',
+    'disable-model-invocation',
+    'user-invocable',
+    'model',
+    'effort',
+    'context',
+    'agent',
+    'paths',
+    'arguments',
+    'argument-hint',
+    'shell',
+    'hooks',
+    'vendor',
+    'version',
+    'min_sdk_version',
+    'requires',
+]);
+const VALID_EFFORT = new Set(['low', 'medium', 'high', 'max']);
+const VALID_CONTEXT = new Set(['fork', 'inherit']);
+const VALID_SHELL = new Set(['bash', 'powershell']);
+/** Strict semver — major.minor.patch (no pre-release / build for simplicity). */
+const SEMVER_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+/** `name` shape — lowercase letters, digits, hyphens. Max length checked separately. */
+const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+/**
+ * Validate parsed frontmatter against the skill contract. Returns a typed
+ * `SkillFrontmatter` (always present — even on failure, the validator
+ * preserves whatever it could parse) plus a list of issues. Fatal issues
+ * carry `severity: 'error'`; the manager treats those as catalog
+ * exclusions.
+ */
+export function validateFrontmatter(raw, defaultName) {
+    const issues = [];
+    const unknown = {};
+    const unknownFields = [];
+    // -- name --
+    let name = defaultName;
+    const rawName = raw.name;
+    if (typeof rawName === 'string' && rawName.length > 0) {
+        name = rawName;
+    }
+    else if (rawName !== undefined && rawName !== null) {
+        issues.push({ severity: 'error', message: 'name must be a string', field: 'name' });
+    }
+    if (!NAME_RE.test(name)) {
+        issues.push({
+            severity: 'error',
+            message: `name ${JSON.stringify(name)} must match /^[a-z0-9][a-z0-9-]*$/`,
+            field: 'name',
+        });
+    }
+    if (name.length > SKILL_NAME_MAX_CHARS) {
+        issues.push({
+            severity: 'error',
+            message: `name exceeds ${SKILL_NAME_MAX_CHARS} chars`,
+            field: 'name',
+        });
+    }
+    const lowerName = name.toLowerCase();
+    for (const reserved of SKILL_NAME_RESERVED_WORDS) {
+        if (lowerName.includes(reserved)) {
+            issues.push({
+                severity: 'error',
+                message: `name uses reserved word: ${reserved}`,
+                field: 'name',
+            });
+            break;
+        }
+    }
+    // -- description / when_to_use --
+    const description = expectStringField(raw.description, 'description', issues);
+    if (description !== undefined && description.length > FIELD_CHAR_CAP) {
+        issues.push({
+            severity: 'warning',
+            message: `description exceeds ${FIELD_CHAR_CAP} chars`,
+            field: 'description',
+        });
+    }
+    const whenToUse = expectStringField(raw.when_to_use, 'when_to_use', issues);
+    if (whenToUse !== undefined && whenToUse.length > FIELD_CHAR_CAP) {
+        issues.push({
+            severity: 'warning',
+            message: `when_to_use exceeds ${FIELD_CHAR_CAP} chars`,
+            field: 'when_to_use',
+        });
+    }
+    // -- allowed-tools --
+    const allowedTools = normalizeAllowedTools(raw['allowed-tools'], issues);
+    // -- disable-model-invocation / user-invocable --
+    const disableModel = expectBooleanField(raw['disable-model-invocation'], 'disable-model-invocation', issues);
+    const userInvocable = expectBooleanField(raw['user-invocable'], 'user-invocable', issues);
+    // -- model --
+    const model = expectStringField(raw.model, 'model', issues);
+    // -- effort --
+    const effort = expectEnumField(raw.effort, 'effort', VALID_EFFORT, issues);
+    // -- context / agent --
+    const context = expectEnumField(raw.context, 'context', VALID_CONTEXT, issues);
+    const agent = expectStringField(raw.agent, 'agent', issues);
+    // -- paths --
+    const paths = normalizeStringArray(raw.paths, 'paths', issues);
+    // -- arguments --
+    const argumentsList = normalizeArguments(raw.arguments, issues);
+    const argumentHint = expectStringField(raw['argument-hint'], 'argument-hint', issues);
+    // -- shell --
+    const shell = expectEnumField(raw.shell, 'shell', VALID_SHELL, issues);
+    // -- hooks (opaque JSON, no validation beyond presence) --
+    const hooks = raw.hooks;
+    // -- vendor --
+    const vendor = expectStringField(raw.vendor, 'vendor', issues);
+    // -- version --
+    let version;
+    const rawVersion = raw.version;
+    if (rawVersion === undefined || rawVersion === null) {
+        version = undefined; // manager defaults to '0.0.0'
+    }
+    else if (typeof rawVersion === 'string' && SEMVER_RE.test(rawVersion)) {
+        version = rawVersion;
+    }
+    else {
+        issues.push({
+            severity: 'error',
+            message: `version must be semver "major.minor.patch"; got ${JSON.stringify(rawVersion)}`,
+            field: 'version',
+        });
+    }
+    // -- min_sdk_version --
+    let minSdk;
+    const rawMin = raw.min_sdk_version;
+    if (rawMin === undefined || rawMin === null) {
+        minSdk = undefined;
+    }
+    else if (typeof rawMin === 'string' && SEMVER_RE.test(rawMin)) {
+        minSdk = rawMin;
+    }
+    else {
+        issues.push({
+            severity: 'error',
+            message: `min_sdk_version must be semver; got ${JSON.stringify(rawMin)}`,
+            field: 'min_sdk_version',
+        });
+    }
+    // -- requires --
+    const requires = normalizeStringArray(raw.requires, 'requires', issues);
+    // -- unknown fields --
+    for (const key of Object.keys(raw)) {
+        if (!KNOWN_FIELDS.has(key)) {
+            unknown[key] = raw[key];
+            unknownFields.push(key);
+        }
+    }
+    // Build the typed frontmatter object.
+    const frontmatter = {
+        name,
+        ...(description !== undefined ? { description } : {}),
+        ...(whenToUse !== undefined ? { when_to_use: whenToUse } : {}),
+        ...(allowedTools !== undefined ? { 'allowed-tools': allowedTools } : {}),
+        ...(disableModel !== undefined ? { 'disable-model-invocation': disableModel } : {}),
+        ...(userInvocable !== undefined ? { 'user-invocable': userInvocable } : {}),
+        ...(model !== undefined ? { model } : {}),
+        ...(effort !== undefined ? { effort } : {}),
+        ...(context !== undefined ? { context } : {}),
+        ...(agent !== undefined ? { agent } : {}),
+        ...(paths !== undefined ? { paths } : {}),
+        ...(argumentsList !== undefined ? { arguments: argumentsList } : {}),
+        ...(argumentHint !== undefined ? { 'argument-hint': argumentHint } : {}),
+        ...(shell !== undefined ? { shell } : {}),
+        ...(hooks !== undefined ? { hooks } : {}),
+        ...(vendor !== undefined ? { vendor } : {}),
+        ...(version !== undefined ? { version } : {}),
+        ...(minSdk !== undefined ? { min_sdk_version: minSdk } : {}),
+        ...(requires !== undefined ? { requires } : {}),
+        ...(unknownFields.length > 0 ? { unknown_fields: unknown } : {}),
+    };
+    return { frontmatter, issues, unknownFields };
+}
+/**
+ * Validate the body — 50 KB hard cap (error, exclude skill), 500-line soft
+ * cap (warning, include anyway).
+ */
+export function validateBody(body) {
+    const issues = [];
+    const byteLen = Buffer.byteLength(body, 'utf-8');
+    if (byteLen > SKILL_BODY_HARD_BYTES) {
+        issues.push({
+            severity: 'error',
+            message: `body exceeds ${SKILL_BODY_HARD_BYTES} bytes hard cap`,
+        });
+    }
+    const lineCount = body.split('\n').length;
+    if (lineCount > SKILL_BODY_SOFT_LINES) {
+        issues.push({
+            severity: 'warning',
+            message: `body exceeds ${SKILL_BODY_SOFT_LINES} lines (got ${lineCount})`,
+        });
+    }
+    return { issues };
+}
+/**
+ * Extract supporting-file references from a SKILL.md body. Two forms are
+ * recognized per `skills-progressive-disclosure.md`:
+ *
+ *   - Markdown links: `[label](path/to/file.ext)`.
+ *   - Explicit tool calls: `get_skill_file("path/to/file")` (string arg).
+ *
+ * Both must be relative; external URLs and anchors are skipped.
+ */
+export function extractBodyReferences(body) {
+    const seen = new Map();
+    // Markdown link form. Match `[label](target)` with no nested brackets
+    // in the target; embedded `)` inside the target is rare in real skills
+    // and disambiguating without a full parser would be over-engineering.
+    const mdLinkRe = /\[([^\]\n]*)\]\(([^)\n]+)\)/g;
+    let m;
+    while ((m = mdLinkRe.exec(body)) !== null) {
+        const target = m[2].trim();
+        if (!isRelativePath(target))
+            continue;
+        const stripped = stripFragment(target);
+        if (stripped.length === 0)
+            continue;
+        const path = normalizeRelative(stripped);
+        if (!seen.has(path)) {
+            seen.set(path, { path, depth: path.split('/').length });
+        }
+    }
+    // `get_skill_file("path")` form. Both single- and double-quoted strings.
+    const toolCallRe = /get_skill_file\s*\(\s*["']([^"'\n]+)["']/g;
+    while ((m = toolCallRe.exec(body)) !== null) {
+        const target = m[1].trim();
+        if (!isRelativePath(target))
+            continue;
+        const stripped = stripFragment(target);
+        if (stripped.length === 0)
+            continue;
+        const path = normalizeRelative(stripped);
+        if (!seen.has(path)) {
+            seen.set(path, { path, depth: path.split('/').length });
+        }
+    }
+    return [...seen.values()];
+}
+function isRelativePath(target) {
+    if (target.length === 0)
+        return false;
+    // Absolute URLs / protocol-relative / scheme-prefixed.
+    if (/^[a-z]+:\/\//i.test(target))
+        return false;
+    if (target.startsWith('//'))
+        return false;
+    if (target.startsWith('mailto:'))
+        return false;
+    if (target.startsWith('tel:'))
+        return false;
+    // Anchor-only.
+    if (target.startsWith('#'))
+        return false;
+    // POSIX-absolute or Windows-absolute.
+    if (target.startsWith('/'))
+        return false;
+    if (/^[A-Za-z]:[\\/]/.test(target))
+        return false;
+    return true;
+}
+function stripFragment(target) {
+    const hashIdx = target.indexOf('#');
+    const trimmed = hashIdx === -1 ? target : target.slice(0, hashIdx);
+    return trimmed.split('?')[0];
+}
+function normalizeRelative(target) {
+    let out = target.replace(/\\/g, '/');
+    while (out.startsWith('./'))
+        out = out.slice(2);
+    return out;
+}
+/** Compare two semver strings (`a < b`). Both must match `SEMVER_RE`. */
+export function semverLessThan(a, b) {
+    const am = a.match(SEMVER_RE);
+    const bm = b.match(SEMVER_RE);
+    if (am === null || bm === null) {
+        throw new Error(`invalid semver: ${JSON.stringify(am === null ? a : b)}`);
+    }
+    for (let i = 1; i <= 3; i += 1) {
+        const an = Number(am[i]);
+        const bn = Number(bm[i]);
+        if (an < bn)
+            return true;
+        if (an > bn)
+            return false;
+    }
+    return false;
+}
+/** Return `true` iff the version strings refer to the same version. */
+export function semverEqual(a, b) {
+    return a === b;
+}
+/** Test helper exposed for the validator's own unit suite. */
+export function isValidSemver(s) {
+    return SEMVER_RE.test(s);
+}
+// ---------------------------------------------------------------------------
+// Field helpers
+// ---------------------------------------------------------------------------
+function expectStringField(value, field, issues) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string') {
+        issues.push({ severity: 'error', message: `${field} must be a string`, field });
+        return undefined;
+    }
+    return value;
+}
+function expectBooleanField(value, field, issues) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'boolean') {
+        issues.push({ severity: 'error', message: `${field} must be a boolean`, field });
+        return undefined;
+    }
+    return value;
+}
+function expectEnumField(value, field, allowed, issues) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string' || !allowed.has(value)) {
+        issues.push({
+            severity: 'error',
+            message: `${field} must be one of ${[...allowed].join(', ')}; got ${JSON.stringify(value)}`,
+            field,
+        });
+        return undefined;
+    }
+    return value;
+}
+function normalizeStringArray(value, field, issues) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Array.isArray(value)) {
+        issues.push({ severity: 'error', message: `${field} must be an array`, field });
+        return undefined;
+    }
+    const out = [];
+    for (const entry of value) {
+        if (typeof entry !== 'string') {
+            issues.push({
+                severity: 'error',
+                message: `${field} entries must be strings`,
+                field,
+            });
+            continue;
+        }
+        out.push(entry);
+    }
+    return out;
+}
+/**
+ * Normalize `allowed-tools` to `AllowedToolEntry[]`. Accepts the
+ * space-separated string form (`'Read Write Bash(git:*)'`) AND the YAML
+ * list form. Tool-with-args entries parse `Bash(git:*)` into
+ * `{ tool: 'Bash', args: 'git:*' }`.
+ */
+function normalizeAllowedTools(value, issues) {
+    if (value === undefined || value === null)
+        return undefined;
+    let parts;
+    if (typeof value === 'string') {
+        parts = value.split(/\s+/).filter((p) => p.length > 0);
+    }
+    else if (Array.isArray(value)) {
+        parts = [];
+        for (const entry of value) {
+            if (typeof entry !== 'string') {
+                issues.push({
+                    severity: 'error',
+                    message: 'allowed-tools entries must be strings',
+                    field: 'allowed-tools',
+                });
+                continue;
+            }
+            parts.push(entry);
+        }
+    }
+    else {
+        issues.push({
+            severity: 'error',
+            message: 'allowed-tools must be a space-separated string or array of strings',
+            field: 'allowed-tools',
+        });
+        return undefined;
+    }
+    return parts.map((p) => parseToolEntry(p));
+}
+/**
+ * Parse a single `allowed-tools` entry. `Bash(git:*)` → `{ tool: 'Bash', args: 'git:*' }`;
+ * `Read` → `{ tool: 'Read' }`.
+ */
+function parseToolEntry(entry) {
+    const openIdx = entry.indexOf('(');
+    if (openIdx === -1 || !entry.endsWith(')')) {
+        return { tool: entry };
+    }
+    const tool = entry.slice(0, openIdx);
+    const args = entry.slice(openIdx + 1, -1);
+    return { tool, args };
+}
+function normalizeArguments(value, issues) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Array.isArray(value)) {
+        issues.push({
+            severity: 'error',
+            message: 'arguments must be an array',
+            field: 'arguments',
+        });
+        return undefined;
+    }
+    const out = [];
+    for (const entry of value) {
+        if (typeof entry === 'string') {
+            out.push({ name: entry });
+            continue;
+        }
+        if (entry !== null && typeof entry === 'object' && !Array.isArray(entry)) {
+            const obj = entry;
+            const nameValue = obj.name;
+            if (typeof nameValue !== 'string' || nameValue.length === 0) {
+                issues.push({
+                    severity: 'error',
+                    message: 'arguments entry must carry a non-empty name',
+                    field: 'arguments',
+                });
+                continue;
+            }
+            const descriptionValue = obj.description;
+            const arg = {
+                name: nameValue,
+                ...(typeof descriptionValue === 'string' ? { description: descriptionValue } : {}),
+            };
+            out.push(arg);
+            continue;
+        }
+        issues.push({
+            severity: 'error',
+            message: 'arguments entry must be a string or { name, description? } object',
+            field: 'arguments',
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=validator.js.map