@holoscript/framework 6.0.3

package/dist/skills/index.d.cts

@@ -0,0 +1,289 @@
+/**
+ * Skill-MD Bridge — Bidirectional .hsplus <-> SKILL.md Conversion
+ *
+ * Converts HoloScript .hsplus composition skills to portable SKILL.md format
+ * (ClawHub/OpenClaw compatible) and back. Enables cross-platform skill sharing
+ * between HoloClaw's native .hsplus format and the broader agent skill ecosystem.
+ *
+ * Forward bridge: .hsplus -> SKILL.md
+ *   - Extracts composition metadata (name, description, version) as YAML frontmatter
+ *   - Converts behavior tree sequences into Markdown instruction steps
+ *   - Includes trait declarations, state schema, and runtime requirements
+ *   - Maps input_schema/output_schema to OpenClaw frontmatter fields
+ *
+ * Reverse bridge: SKILL.md -> .hsplus
+ *   - Parses YAML frontmatter into composition metadata + trait declarations
+ *   - Converts Markdown instructions into behavior tree sequence nodes
+ *   - Wraps in full composition structure with @economy, @rate_limiter, @timeout_guard
+ *   - Parses input_schema/output_schema from frontmatter into typed schemas
+ *
+ * HoloClaw Skill interop:
+ *   - toHoloClawSkill() converts ParsedSkill to the Skill interface from SkillRegistryTrait
+ *   - fromHoloClawSkill() converts Skill objects back to ParsedSkill for serialization
+ *
+ * ClawHub CLI integration: publish/install skill packages with registry URL support
+ *
+ * @version 1.1.0
+ * @see compositions/skills/*.hsplus — HoloClaw native skill format
+ * @see .claude/skills/ *\/SKILL.md — Claude Code SKILL.md format
+ * @see https://docs.openclaw.ai/tools/skills — ClawHub specification
+ *
+ * Security considerations (Corridor-inline):
+ *   - File paths are validated against path traversal
+ *   - No shell execution in the bridge itself (CLI integration uses subprocess)
+ *   - Skill content is parsed, not eval'd
+ *   - YAML frontmatter is parsed with safe subset (no !!python/exec etc.)
+ */
+/**
+ * Schema field definition for input/output schemas.
+ * Compatible with OpenClaw SKILL.md frontmatter format and HoloClaw SkillInput/SkillOutput.
+ */
+interface SchemaField {
+    /** Field name */
+    name: string;
+    /** Field type: string, number, boolean, object, array */
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    /** Whether this field is required (inputs only) */
+    required?: boolean;
+    /** Human-readable description */
+    description: string;
+    /** Default value (inputs only) */
+    default?: unknown;
+}
+/**
+ * Metadata extracted from an .hsplus composition skill or SKILL.md frontmatter.
+ * This is the canonical interchange format between the two representations.
+ */
+interface SkillMetadata {
+    /** Skill identifier (kebab-case, e.g. "code-health") */
+    name: string;
+    /** Human-readable description of what the skill does */
+    description: string;
+    /** Semantic version string */
+    version: string;
+    /** Author name or organization */
+    author: string;
+    /** Skill category for marketplace browsing */
+    category?: string;
+    /** Tags for search/discovery */
+    tags?: string[];
+    /** Input schema fields (OpenClaw input_schema frontmatter) */
+    inputSchema?: SchemaField[];
+    /** Output schema fields (OpenClaw output_schema frontmatter) */
+    outputSchema?: SchemaField[];
+    /** Minimum HoloScript CLI version required */
+    holoCliVersion?: string;
+    /** Minimum Node.js version required */
+    nodeVersion?: string;
+    /** Economy budget limit per invocation (USD) */
+    spendLimit?: number;
+    /** Whether users can invoke this skill via slash command */
+    userInvocable?: boolean;
+    /** License identifier (SPDX) */
+    license?: string;
+    /** Homepage URL */
+    homepage?: string;
+    /** Repository URL */
+    repository?: string;
+}
+/**
+ * A state variable declared in a composition skill.
+ */
+interface SkillStateVar {
+    /** Variable name */
+    name: string;
+    /** Type: string, number, boolean */
+    type: string;
+    /** Default value */
+    defaultValue: string | number | boolean;
+}
+/**
+ * A trait declaration extracted from a composition skill.
+ */
+interface SkillTraitDecl {
+    /** Trait name (e.g. "rate_limiter", "economy") */
+    name: string;
+    /** Trait configuration parameters */
+    config: Record<string, unknown>;
+}
+/**
+ * A behavior tree action step extracted from a composition skill.
+ */
+interface SkillActionStep {
+    /** Action name (e.g. "shell_exec", "diagnose") */
+    action: string;
+    /** Human-readable description of what this step does */
+    description: string;
+    /** Action parameters */
+    params: Record<string, unknown>;
+    /** BT node type: action, sequence, selector, condition */
+    nodeType: 'action' | 'sequence' | 'selector' | 'condition';
+}
+/**
+ * A test assertion extracted from a composition skill.
+ */
+interface SkillTest {
+    /** Test name */
+    name: string;
+    /** Setup expression (optional) */
+    setup?: string;
+    /** Assert expression */
+    assert: string;
+}
+/**
+ * Fully parsed skill representation — the intermediate form between .hsplus and SKILL.md.
+ */
+interface ParsedSkill {
+    metadata: SkillMetadata;
+    traits: SkillTraitDecl[];
+    state: SkillStateVar[];
+    steps: SkillActionStep[];
+    tests: SkillTest[];
+    /** Raw environment block properties (if any) */
+    environment?: Record<string, unknown>;
+    /** Raw object declarations (for complex skills with scene objects) */
+    objects?: string[];
+    /** Original source comments (leading comment block) */
+    sourceComments: string[];
+}
+/**
+ * Result of a bridge conversion operation.
+ */
+interface BridgeResult<T> {
+    success: boolean;
+    data?: T;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * ClawHub package manifest for publish/install operations.
+ */
+interface ClawHubManifest {
+    name: string;
+    version: string;
+    description: string;
+    author: string;
+    license: string;
+    /** ClawHub registry URL for distribution */
+    registryUrl: string;
+    /** Tags for registry search/discovery */
+    tags?: string[];
+    /** Homepage URL */
+    homepage?: string;
+    /** Repository URL */
+    repository?: string;
+    holoScript: {
+        format: 'hsplus';
+        minCliVersion: string;
+        traits: string[];
+        stateVars: string[];
+        testCount: number;
+        /** Input schema field names */
+        inputFields: string[];
+        /** Output schema field names */
+        outputFields: string[];
+    };
+    files: string[];
+    dependencies?: Record<string, string>;
+}
+/**
+ * Parse an .hsplus composition source string into a structured ParsedSkill.
+ * Uses regex-based extraction (not a full parser) for lightweight, dependency-free operation.
+ */
+declare function parseHsplus(source: string): BridgeResult<ParsedSkill>;
+/**
+ * Convert a ParsedSkill into a SKILL.md string (ClawHub-compatible format).
+ */
+declare function toSkillMd(skill: ParsedSkill): BridgeResult<string>;
+/**
+ * Convert an .hsplus source string directly to SKILL.md string.
+ * Convenience wrapper combining parseHsplus + toSkillMd.
+ */
+declare function hsplusToSkillMd(source: string): BridgeResult<string>;
+/**
+ * Parse a SKILL.md string into a structured ParsedSkill.
+ */
+declare function parseSkillMd(markdown: string): BridgeResult<ParsedSkill>;
+/**
+ * Convert a ParsedSkill into an .hsplus composition source string.
+ */
+declare function toHsplus(skill: ParsedSkill): BridgeResult<string>;
+/**
+ * Convert a SKILL.md string directly to .hsplus source string.
+ * Convenience wrapper combining parseSkillMd + toHsplus.
+ */
+declare function skillMdToHsplus(markdown: string): BridgeResult<string>;
+/**
+ * Generate a ClawHub package manifest from a ParsedSkill.
+ * This manifest can be used for `clawhub publish` operations.
+ */
+declare function generateClawHubManifest(skill: ParsedSkill, registryUrl?: string): ClawHubManifest;
+/**
+ * Generate the complete set of files needed for a ClawHub publish.
+ * Returns a map of filename -> content.
+ */
+declare function generateClawHubPackage(source: string): BridgeResult<Map<string, string>>;
+/**
+ * Generate a CLI command string for publishing to ClawHub.
+ * Does NOT execute the command -- returns the string for the caller to execute.
+ *
+ * @param skillName - The skill name (kebab-case)
+ * @param registry - The registry URL (default: https://registry.clawhub.com)
+ */
+declare function getPublishCommand(skillName: string, registry?: string): string;
+/**
+ * Generate a CLI command string for installing a skill from ClawHub.
+ *
+ * @param skillName - The skill name (kebab-case)
+ * @param targetDir - Target directory (default: compositions/skills)
+ * @param registry - The registry URL (default: https://registry.clawhub.com)
+ */
+declare function getInstallCommand(skillName: string, targetDir?: string, registry?: string): string;
+/**
+ * Generate a CLI command string for installing via the HoloScript CLI.
+ *
+ * @param skillName - The skill name (kebab-case)
+ */
+declare function getHsInstallCommand(skillName: string): string;
+/**
+ * HoloClaw Skill interface — mirrors SkillRegistryTrait.Skill without the
+ * execute function (which cannot be serialized). This is the shape used for
+ * registry listing and interchange.
+ */
+interface HoloClawSkill {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    author: string;
+    inputs: HoloClawSkillInput[];
+    outputs: HoloClawSkillOutput[];
+    sandbox: boolean;
+}
+interface HoloClawSkillInput {
+    name: string;
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    required: boolean;
+    description: string;
+    default?: unknown;
+}
+interface HoloClawSkillOutput {
+    name: string;
+    type: string;
+    description: string;
+}
+/**
+ * Convert a ParsedSkill (bridge intermediate) to a HoloClaw Skill object.
+ * This enables skills parsed from SKILL.md to be registered in the HoloClaw
+ * SkillRegistry runtime (minus the execute function, which must be provided
+ * separately or wired via a BT executor).
+ */
+declare function toHoloClawSkill(parsed: ParsedSkill): HoloClawSkill;
+/**
+ * Convert a HoloClaw Skill object to a ParsedSkill (bridge intermediate).
+ * This enables HoloClaw runtime skills to be serialized as SKILL.md or .hsplus
+ * for distribution via ClawHub.
+ */
+declare function fromHoloClawSkill(skill: HoloClawSkill): ParsedSkill;
+
+export { type BridgeResult, type ClawHubManifest, type HoloClawSkill, type HoloClawSkillInput, type HoloClawSkillOutput, type ParsedSkill, type SchemaField, type SkillActionStep, type SkillMetadata, type SkillStateVar, type SkillTest, type SkillTraitDecl, fromHoloClawSkill, generateClawHubManifest, generateClawHubPackage, getHsInstallCommand, getInstallCommand, getPublishCommand, hsplusToSkillMd, parseHsplus, parseSkillMd, skillMdToHsplus, toHoloClawSkill, toHsplus, toSkillMd };

package/dist/skills/index.d.ts

@@ -0,0 +1,289 @@
+/**
+ * Skill-MD Bridge — Bidirectional .hsplus <-> SKILL.md Conversion
+ *
+ * Converts HoloScript .hsplus composition skills to portable SKILL.md format
+ * (ClawHub/OpenClaw compatible) and back. Enables cross-platform skill sharing
+ * between HoloClaw's native .hsplus format and the broader agent skill ecosystem.
+ *
+ * Forward bridge: .hsplus -> SKILL.md
+ *   - Extracts composition metadata (name, description, version) as YAML frontmatter
+ *   - Converts behavior tree sequences into Markdown instruction steps
+ *   - Includes trait declarations, state schema, and runtime requirements
+ *   - Maps input_schema/output_schema to OpenClaw frontmatter fields
+ *
+ * Reverse bridge: SKILL.md -> .hsplus
+ *   - Parses YAML frontmatter into composition metadata + trait declarations
+ *   - Converts Markdown instructions into behavior tree sequence nodes
+ *   - Wraps in full composition structure with @economy, @rate_limiter, @timeout_guard
+ *   - Parses input_schema/output_schema from frontmatter into typed schemas
+ *
+ * HoloClaw Skill interop:
+ *   - toHoloClawSkill() converts ParsedSkill to the Skill interface from SkillRegistryTrait
+ *   - fromHoloClawSkill() converts Skill objects back to ParsedSkill for serialization
+ *
+ * ClawHub CLI integration: publish/install skill packages with registry URL support
+ *
+ * @version 1.1.0
+ * @see compositions/skills/*.hsplus — HoloClaw native skill format
+ * @see .claude/skills/ *\/SKILL.md — Claude Code SKILL.md format
+ * @see https://docs.openclaw.ai/tools/skills — ClawHub specification
+ *
+ * Security considerations (Corridor-inline):
+ *   - File paths are validated against path traversal
+ *   - No shell execution in the bridge itself (CLI integration uses subprocess)
+ *   - Skill content is parsed, not eval'd
+ *   - YAML frontmatter is parsed with safe subset (no !!python/exec etc.)
+ */
+/**
+ * Schema field definition for input/output schemas.
+ * Compatible with OpenClaw SKILL.md frontmatter format and HoloClaw SkillInput/SkillOutput.
+ */
+interface SchemaField {
+    /** Field name */
+    name: string;
+    /** Field type: string, number, boolean, object, array */
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    /** Whether this field is required (inputs only) */
+    required?: boolean;
+    /** Human-readable description */
+    description: string;
+    /** Default value (inputs only) */
+    default?: unknown;
+}
+/**
+ * Metadata extracted from an .hsplus composition skill or SKILL.md frontmatter.
+ * This is the canonical interchange format between the two representations.
+ */
+interface SkillMetadata {
+    /** Skill identifier (kebab-case, e.g. "code-health") */
+    name: string;
+    /** Human-readable description of what the skill does */
+    description: string;
+    /** Semantic version string */
+    version: string;
+    /** Author name or organization */
+    author: string;
+    /** Skill category for marketplace browsing */
+    category?: string;
+    /** Tags for search/discovery */
+    tags?: string[];
+    /** Input schema fields (OpenClaw input_schema frontmatter) */
+    inputSchema?: SchemaField[];
+    /** Output schema fields (OpenClaw output_schema frontmatter) */
+    outputSchema?: SchemaField[];
+    /** Minimum HoloScript CLI version required */
+    holoCliVersion?: string;
+    /** Minimum Node.js version required */
+    nodeVersion?: string;
+    /** Economy budget limit per invocation (USD) */
+    spendLimit?: number;
+    /** Whether users can invoke this skill via slash command */
+    userInvocable?: boolean;
+    /** License identifier (SPDX) */
+    license?: string;
+    /** Homepage URL */
+    homepage?: string;
+    /** Repository URL */
+    repository?: string;
+}
+/**
+ * A state variable declared in a composition skill.
+ */
+interface SkillStateVar {
+    /** Variable name */
+    name: string;
+    /** Type: string, number, boolean */
+    type: string;
+    /** Default value */
+    defaultValue: string | number | boolean;
+}
+/**
+ * A trait declaration extracted from a composition skill.
+ */
+interface SkillTraitDecl {
+    /** Trait name (e.g. "rate_limiter", "economy") */
+    name: string;
+    /** Trait configuration parameters */
+    config: Record<string, unknown>;
+}
+/**
+ * A behavior tree action step extracted from a composition skill.
+ */
+interface SkillActionStep {
+    /** Action name (e.g. "shell_exec", "diagnose") */
+    action: string;
+    /** Human-readable description of what this step does */
+    description: string;
+    /** Action parameters */
+    params: Record<string, unknown>;
+    /** BT node type: action, sequence, selector, condition */
+    nodeType: 'action' | 'sequence' | 'selector' | 'condition';
+}
+/**
+ * A test assertion extracted from a composition skill.
+ */
+interface SkillTest {
+    /** Test name */
+    name: string;
+    /** Setup expression (optional) */
+    setup?: string;
+    /** Assert expression */
+    assert: string;
+}
+/**
+ * Fully parsed skill representation — the intermediate form between .hsplus and SKILL.md.
+ */
+interface ParsedSkill {
+    metadata: SkillMetadata;
+    traits: SkillTraitDecl[];
+    state: SkillStateVar[];
+    steps: SkillActionStep[];
+    tests: SkillTest[];
+    /** Raw environment block properties (if any) */
+    environment?: Record<string, unknown>;
+    /** Raw object declarations (for complex skills with scene objects) */
+    objects?: string[];
+    /** Original source comments (leading comment block) */
+    sourceComments: string[];
+}
+/**
+ * Result of a bridge conversion operation.
+ */
+interface BridgeResult<T> {
+    success: boolean;
+    data?: T;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * ClawHub package manifest for publish/install operations.
+ */
+interface ClawHubManifest {
+    name: string;
+    version: string;
+    description: string;
+    author: string;
+    license: string;
+    /** ClawHub registry URL for distribution */
+    registryUrl: string;
+    /** Tags for registry search/discovery */
+    tags?: string[];
+    /** Homepage URL */
+    homepage?: string;
+    /** Repository URL */
+    repository?: string;
+    holoScript: {
+        format: 'hsplus';
+        minCliVersion: string;
+        traits: string[];
+        stateVars: string[];
+        testCount: number;
+        /** Input schema field names */
+        inputFields: string[];
+        /** Output schema field names */
+        outputFields: string[];
+    };
+    files: string[];
+    dependencies?: Record<string, string>;
+}
+/**
+ * Parse an .hsplus composition source string into a structured ParsedSkill.
+ * Uses regex-based extraction (not a full parser) for lightweight, dependency-free operation.
+ */
+declare function parseHsplus(source: string): BridgeResult<ParsedSkill>;
+/**
+ * Convert a ParsedSkill into a SKILL.md string (ClawHub-compatible format).
+ */
+declare function toSkillMd(skill: ParsedSkill): BridgeResult<string>;
+/**
+ * Convert an .hsplus source string directly to SKILL.md string.
+ * Convenience wrapper combining parseHsplus + toSkillMd.
+ */
+declare function hsplusToSkillMd(source: string): BridgeResult<string>;
+/**
+ * Parse a SKILL.md string into a structured ParsedSkill.
+ */
+declare function parseSkillMd(markdown: string): BridgeResult<ParsedSkill>;
+/**
+ * Convert a ParsedSkill into an .hsplus composition source string.
+ */
+declare function toHsplus(skill: ParsedSkill): BridgeResult<string>;
+/**
+ * Convert a SKILL.md string directly to .hsplus source string.
+ * Convenience wrapper combining parseSkillMd + toHsplus.
+ */
+declare function skillMdToHsplus(markdown: string): BridgeResult<string>;
+/**
+ * Generate a ClawHub package manifest from a ParsedSkill.
+ * This manifest can be used for `clawhub publish` operations.
+ */
+declare function generateClawHubManifest(skill: ParsedSkill, registryUrl?: string): ClawHubManifest;
+/**
+ * Generate the complete set of files needed for a ClawHub publish.
+ * Returns a map of filename -> content.
+ */
+declare function generateClawHubPackage(source: string): BridgeResult<Map<string, string>>;
+/**
+ * Generate a CLI command string for publishing to ClawHub.
+ * Does NOT execute the command -- returns the string for the caller to execute.
+ *
+ * @param skillName - The skill name (kebab-case)
+ * @param registry - The registry URL (default: https://registry.clawhub.com)
+ */
+declare function getPublishCommand(skillName: string, registry?: string): string;
+/**
+ * Generate a CLI command string for installing a skill from ClawHub.
+ *
+ * @param skillName - The skill name (kebab-case)
+ * @param targetDir - Target directory (default: compositions/skills)
+ * @param registry - The registry URL (default: https://registry.clawhub.com)
+ */
+declare function getInstallCommand(skillName: string, targetDir?: string, registry?: string): string;
+/**
+ * Generate a CLI command string for installing via the HoloScript CLI.
+ *
+ * @param skillName - The skill name (kebab-case)
+ */
+declare function getHsInstallCommand(skillName: string): string;
+/**
+ * HoloClaw Skill interface — mirrors SkillRegistryTrait.Skill without the
+ * execute function (which cannot be serialized). This is the shape used for
+ * registry listing and interchange.
+ */
+interface HoloClawSkill {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    author: string;
+    inputs: HoloClawSkillInput[];
+    outputs: HoloClawSkillOutput[];
+    sandbox: boolean;
+}
+interface HoloClawSkillInput {
+    name: string;
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    required: boolean;
+    description: string;
+    default?: unknown;
+}
+interface HoloClawSkillOutput {
+    name: string;
+    type: string;
+    description: string;
+}
+/**
+ * Convert a ParsedSkill (bridge intermediate) to a HoloClaw Skill object.
+ * This enables skills parsed from SKILL.md to be registered in the HoloClaw
+ * SkillRegistry runtime (minus the execute function, which must be provided
+ * separately or wired via a BT executor).
+ */
+declare function toHoloClawSkill(parsed: ParsedSkill): HoloClawSkill;
+/**
+ * Convert a HoloClaw Skill object to a ParsedSkill (bridge intermediate).
+ * This enables HoloClaw runtime skills to be serialized as SKILL.md or .hsplus
+ * for distribution via ClawHub.
+ */
+declare function fromHoloClawSkill(skill: HoloClawSkill): ParsedSkill;
+
+export { type BridgeResult, type ClawHubManifest, type HoloClawSkill, type HoloClawSkillInput, type HoloClawSkillOutput, type ParsedSkill, type SchemaField, type SkillActionStep, type SkillMetadata, type SkillStateVar, type SkillTest, type SkillTraitDecl, fromHoloClawSkill, generateClawHubManifest, generateClawHubPackage, getHsInstallCommand, getInstallCommand, getPublishCommand, hsplusToSkillMd, parseHsplus, parseSkillMd, skillMdToHsplus, toHoloClawSkill, toHsplus, toSkillMd };