@matimo/core 0.1.0-alpha.8 → 0.1.0

package/tools/matimo_create_skill/matimo_create_skill.ts

@@ -0,0 +1,75 @@
+import fs from 'fs';
+import path from 'path';
+import { getGlobalMatimoLogger } from '@matimo/core';
+import {
+  validateSkillName,
+  parseSkillContent,
+  validateFrontmatter,
+} from '../shared/skill-validation';
+
+interface CreateSkillParams {
+  name: string;
+  content: string;
+  target_dir?: string;
+}
+
+interface CreateSkillResult {
+  success: boolean;
+  path?: string;
+  message: string;
+}
+
+/**
+ * Create a new skill following the Agent Skills specification.
+ *
+ * Validates the name (lowercase, hyphens, max 64 chars), ensures frontmatter
+ * has required fields (name, description), and enforces that the frontmatter
+ * name matches the directory name.
+ *
+ * @see https://agentskills.io/specification
+ */
+export default async function matimoCreateSkill(
+  params: CreateSkillParams,
+): Promise<CreateSkillResult> {
+  const logger = getGlobalMatimoLogger();
+  const targetDir = params.target_dir || './matimo-tools/skills';
+
+  // Step 1: Validate the skill name against Agent Skills spec
+  const nameResult = validateSkillName(params.name);
+  if (!nameResult.valid) {
+    return { success: false, message: nameResult.error! };
+  }
+
+  // Step 2: Parse and validate frontmatter
+  const parseResult = parseSkillContent(params.content);
+  if (!parseResult.success) {
+    return { success: false, message: parseResult.error! };
+  }
+
+  const { frontmatter } = parseResult.parsed!;
+
+  // Step 3: Validate frontmatter fields + name must match directory
+  const fmResult = validateFrontmatter(frontmatter, params.name);
+  if (!fmResult.valid) {
+    const firstError = fmResult.issues.find(i => i.severity === 'error');
+    return { success: false, message: firstError!.message };
+  }
+
+  // Step 4: Write to disk
+  const skillDirPath = path.resolve(targetDir, params.name);
+  fs.mkdirSync(skillDirPath, { recursive: true });
+
+  const filePath = path.join(skillDirPath, 'SKILL.md');
+  fs.writeFileSync(filePath, params.content, 'utf-8');
+
+  logger.info('matimo_create_skill: skill created', {
+    name: params.name,
+    path: filePath,
+  });
+
+  return {
+    success: true,
+    path: filePath,
+    message: `Skill "${params.name}" created successfully.`,
+  };
+}

package/tools/matimo_create_tool/definition.yaml

@@ -0,0 +1,48 @@
+name: matimo_create_tool
+version: '1.0.0'
+description: Create a new tool definition on disk. Validates the YAML, forces draft status and requires_approval, and writes the tool to the target directory.
+requires_approval: true
+tags:
+  - matimo
+  - meta
+  - creation
+
+parameters:
+  name:
+    type: string
+    required: true
+    description: Name for the new tool (snake_case, no path traversal)
+  yaml_content:
+    type: string
+    required: true
+    description: The YAML content of the tool definition
+  target_dir:
+    type: string
+    required: false
+    description: Directory to create the tool in (default ./matimo-tools)
+  proposed_by:
+    type: string
+    required: false
+    description: Identifier of who proposed this tool
+  justification:
+    type: string
+    required: false
+    description: Reason for creating this tool
+
+execution:
+  type: function
+  code: './matimo_create_tool.ts'
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    path:
+      type: string
+    riskLevel:
+      type: string
+    status:
+      type: string
+    message:
+      type: string

package/tools/matimo_create_tool/matimo_create_tool.ts

@@ -0,0 +1,137 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import {
+  validateToolDefinition,
+  validateToolContent,
+  classifyRisk,
+  getTierForTool,
+  getGlobalMatimoLogger,
+} from '@matimo/core';
+import type { Violation } from '@matimo/core';
+
+interface CreateParams {
+  name: string;
+  yaml_content: string;
+  target_dir?: string;
+  proposed_by?: string;
+  justification?: string;
+}
+
+interface CreateResult {
+  success: boolean;
+  path?: string;
+  riskLevel?: string;
+  status?: string;
+  /** Signals what approval state the tool is in after creation.
+   * - `pending`: requires human approval before execution (untrusted source, non-trivial risk)
+   * - `auto-approved`: low-risk read-only GET tool, can be used immediately
+   * - `approved`: manually approved (set externally by matimo_approve_tool)
+   * - `rejected`: policy blocked the tool
+   */
+  approvalState?: 'pending' | 'auto-approved' | 'approved' | 'rejected';
+  message: string;
+  errors?: string[];
+}
+
+const UNSAFE_NAME_PATTERN = /[/\\]|\.\.|[\x00-\x1f]/;
+
+export default async function matimoCreateTool(
+  params: CreateParams,
+): Promise<CreateResult> {
+  const logger = getGlobalMatimoLogger();
+  const targetDir = params.target_dir || './matimo-tools';
+
+  // Step 1: Sanitize name
+  if (!params.name || params.name.trim().length === 0) {
+    return { success: false, message: 'Tool name is required' };
+  }
+  if (UNSAFE_NAME_PATTERN.test(params.name)) {
+    return { success: false, message: 'Tool name contains invalid characters (path traversal, backslash, or control characters)' };
+  }
+  if (params.name.startsWith('matimo_')) {
+    return { success: false, message: 'Tool name cannot start with reserved namespace "matimo_"' };
+  }
+
+  // Step 2: Parse YAML
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = yaml.load(params.yaml_content) as Record<string, unknown>;
+    if (!parsed || typeof parsed !== 'object') {
+      return { success: false, message: 'YAML must parse to an object' };
+    }
+  } catch (err) {
+    return { success: false, message: `YAML parse error: ${(err as Error).message}` };
+  }
+
+  // Step 3: Force safety fields
+  parsed.name = params.name;
+  parsed.requires_approval = true;
+  parsed.status = 'draft';
+
+  // Step 4: Validate against schema
+  const yamlStr = yaml.dump(parsed);
+  try {
+    validateToolDefinition(yaml.load(yamlStr));
+  } catch (err) {
+    return { success: false, message: `Schema validation failed: ${(err as Error).message}` };
+  }
+
+  // Step 5: Run content validator
+  const tool = validateToolDefinition(yaml.load(yamlStr));
+  const validation = validateToolContent(tool, { source: 'untrusted' });
+  const criticalOrHigh = validation.violations.filter(
+    (v: Violation) => v.severity === 'critical' || v.severity === 'high',
+  );
+  if (criticalOrHigh.length > 0) {
+    return {
+      success: false,
+      message: 'Tool failed policy validation',
+      errors: criticalOrHigh.map((v: Violation) => `[${v.severity}] ${v.rule}: ${v.message}`),
+    };
+  }
+
+  // Step 6: Classify risk + tier
+  const riskLevel = classifyRisk(tool);
+  const tier = getTierForTool(tool);
+  const approvalState: CreateResult['approvalState'] = tier === 'auto' ? 'auto-approved' : 'pending';
+
+  // Step 7: Write to disk
+  const toolDirPath = path.resolve(targetDir, params.name);
+  fs.mkdirSync(toolDirPath, { recursive: true });
+
+  let header = '';
+  if (params.proposed_by) {
+    header += `# Proposed by: ${params.proposed_by}\n`;
+  }
+  if (params.justification) {
+    header += `# Justification: ${params.justification}\n`;
+  }
+  if (header) {
+    header += '\n';
+  }
+
+  const filePath = path.join(toolDirPath, 'definition.yaml');
+  fs.writeFileSync(filePath, header + yamlStr, 'utf-8');
+
+  logger.info('matimo_create_tool: tool created', {
+    name: params.name,
+    path: filePath,
+    riskLevel,
+    approvalState,
+  });
+
+  const message =
+    approvalState === 'auto-approved'
+      ? 'Tool created and auto-approved (low-risk read-only). Ready for use.'
+      : 'Tool created as draft. Requires approval before execution. Use matimo_approve_tool to promote.';
+
+  return {
+    success: true,
+    path: filePath,
+    riskLevel,
+    status: 'draft',
+    approvalState,
+    message,
+  };
+}

package/tools/matimo_get_skill/definition.yaml

@@ -0,0 +1,60 @@
+name: matimo_get_skill
+version: '1.0.0'
+description: >-
+  Level 2 activation / Level 3 resource access — read a skill's SKILL.md
+  content and metadata, or read a specific bundled resource file (scripts,
+  references, assets). Returns frontmatter fields, markdown instructions, and
+  a listing of bundled resources per the Agent Skills specification.
+requires_approval: false
+tags:
+  - matimo
+  - meta
+  - skill
+parameters:
+  name:
+    type: string
+    required: true
+    description: Name of the skill to retrieve (must match the skill's directory name)
+  skills_dir:
+    type: string
+    required: false
+    description: Directory containing skills (default ./matimo-tools/skills)
+  file:
+    type: string
+    required: false
+    description: >-
+      Optional path to a bundled resource file within the skill directory
+      (e.g. "scripts/extract.py" or "references/FORMS.md"). If provided,
+      returns that file's content instead of SKILL.md (Level 3 access).
+
+execution:
+  type: function
+  code: './matimo_get_skill.ts'
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    name:
+      type: string
+    description:
+      type: string
+    content:
+      type: string
+      description: Full content of SKILL.md or the requested resource file
+    path:
+      type: string
+    license:
+      type: string
+    compatibility:
+      type: string
+    metadata:
+      type: object
+    resources:
+      type: object
+      description: >-
+        Bundled resources listing (scripts, references, assets, other) —
+        only included when reading SKILL.md, not when reading a specific file
+    message:
+      type: string

package/tools/matimo_get_skill/matimo_get_skill.ts

@@ -0,0 +1,182 @@
+import fs from 'fs';
+import path from 'path';
+import { getGlobalMatimoLogger, getGlobalMatimoInstance, ToolLoader, SkillSummary } from '@matimo/core';
+import { parseSkillContent, listBundledResources, type BundledResources } from '../shared/skill-validation';
+
+interface GetSkillParams {
+  name: string;
+  skills_dir?: string;
+  file?: string;
+}
+
+interface GetSkillResult {
+  success: boolean;
+  name?: string;
+  description?: string;
+  content?: string;
+  path?: string;
+  message: string;
+  license?: string;
+  compatibility?: string;
+  metadata?: Record<string, string>;
+  resources?: BundledResources;
+}
+
+/** Path traversal detection — defense-in-depth. */
+const UNSAFE_NAME_PATTERN = /[/\\]|\.\.|[\x00-\x1f]/;
+
+/**
+ * Helper: Find skill directory using auto-discovery (like matimo_list_skills)
+ */
+function findSkillDir(skillName: string, explicitSkillsDir?: string): string | null {
+  // Try explicit skills_dir first
+  if (explicitSkillsDir) {
+    const skillPath = path.join(explicitSkillsDir, skillName, 'SKILL.md');
+    if (fs.existsSync(skillPath)) {
+      return path.join(explicitSkillsDir, skillName);
+    }
+  }
+
+  // Try MatimoInstance
+  try {
+    const matimo = getGlobalMatimoInstance();
+    if (matimo) {
+      const skills = matimo.listSkills();
+      const found = skills?.find((s) => s.name === skillName);
+      if (found) {
+        const skillPath = (found as SkillSummary & { _path?: string })._path;
+        if (skillPath && fs.existsSync(path.join(skillPath, 'SKILL.md'))) {
+          return skillPath;
+        }
+      }
+    }
+  } catch {
+    // Fall through
+  }
+
+  // Auto-discover from @matimo/* packages
+  try {
+    const toolLoader = new ToolLoader();
+    const discoveredPaths = toolLoader.autoDiscoverPackages();
+    for (const toolPath of discoveredPaths) {
+      const pkgDir = path.dirname(toolPath);
+      const skillPath = path.join(pkgDir, 'skills', skillName, 'SKILL.md');
+      if (fs.existsSync(skillPath)) {
+        return path.join(pkgDir, 'skills', skillName);
+      }
+    }
+  } catch {
+    // Fall through
+  }
+
+  return null;
+}
+
+/**
+ * Read a skill's content by name — Level 2 activation (SKILL.md) or
+ * Level 3 resource access (bundled file).
+ *
+ * When called without `file`, returns SKILL.md content + metadata + resource listing.
+ * When called with `file`, returns the contents of that bundled resource file.
+ *
+ * Skills are discovered in this order (priority):
+ * 1. Explicit skills_dir if provided
+ * 2. Global MatimoInstance (if initialized)
+ * 3. Auto-discovered @matimo/* packages
+ *
+ * @see https://agentskills.io/specification
+ */
+export default async function matimoGetSkill(
+  params: GetSkillParams,
+): Promise<GetSkillResult> {
+  const logger = getGlobalMatimoLogger();
+
+  if (!params.name || params.name.trim().length === 0) {
+    return { success: false, message: 'Skill name is required' };
+  }
+
+  if (UNSAFE_NAME_PATTERN.test(params.name)) {
+    return { success: false, message: 'Skill name contains invalid characters' };
+  }
+
+  // Find skill directory using auto-discovery
+  const skillDir = findSkillDir(params.name, params.skills_dir);
+  if (!skillDir) {
+    return { success: false, message: `Skill "${params.name}" not found` };
+  }
+
+  const skillPath = path.join(skillDir, 'SKILL.md');
+
+  // Level 3: Read a specific bundled resource file
+  if (params.file) {
+    // For file paths, allow forward slashes but reject path traversal
+    if (/\.\.|\\/u.test(params.file) || /[\x00-\x1f]/.test(params.file)) {
+      return { success: false, message: 'File path contains invalid characters' };
+    }
+
+    const resourcePath = path.join(skillDir, params.file);
+    // Verify the resolved path stays within the skill directory
+    const resolvedPath = path.resolve(resourcePath);
+    const resolvedSkillDir = path.resolve(skillDir);
+    if (!resolvedPath.startsWith(resolvedSkillDir + path.sep) && resolvedPath !== resolvedSkillDir) {
+      return { success: false, message: 'File path escapes the skill directory' };
+    }
+
+    if (!fs.existsSync(resourcePath)) {
+      return { success: false, message: `Resource file "${params.file}" not found in skill "${params.name}"` };
+    }
+
+    try {
+      const fileContent = fs.readFileSync(resourcePath, 'utf-8');
+      return {
+        success: true,
+        name: params.name,
+        content: fileContent,
+        path: resourcePath,
+        message: `Resource file "${params.file}" retrieved successfully.`,
+      };
+    } catch (err) {
+      return { success: false, message: `Failed to read resource file: ${(err as Error).message}` };
+    }
+  }
+
+  // Level 2: Read SKILL.md + metadata + resource listing
+  try {
+    const rawContent = fs.readFileSync(skillPath, 'utf-8');
+    const parseResult = parseSkillContent(rawContent);
+
+    const result: GetSkillResult = {
+      success: true,
+      name: params.name,
+      content: rawContent,
+      path: skillPath,
+      message: 'Skill retrieved successfully.',
+    };
+
+    if (parseResult.success && parseResult.parsed) {
+      const { frontmatter } = parseResult.parsed;
+      result.name = frontmatter.name || params.name;
+      result.description = frontmatter.description || '';
+      if (frontmatter.license) result.license = frontmatter.license;
+      if (frontmatter.compatibility) result.compatibility = frontmatter.compatibility;
+      if (frontmatter.metadata) result.metadata = frontmatter.metadata;
+    }
+
+    // List bundled resources (Level 3 discovery)
+    result.resources = listBundledResources(skillDir);
+
+    logger.info('matimo_get_skill: skill retrieved', {
+      name: params.name,
+      path: skillPath,
+    });
+
+    return result;
+  } catch (err) {
+    const errorMsg = (err as Error).message;
+    logger.error('matimo_get_skill: failed to read skill', {
+      name: params.name,
+      error: errorMsg,
+    });
+    return { success: false, message: `Failed to read skill: ${errorMsg}` };
+  }
+}

package/tools/matimo_get_tool/definition.yaml

@@ -0,0 +1,36 @@
+name: matimo_get_tool
+version: '1.0.0'
+description: Retrieve the full definition of a tool — raw YAML content and parsed fields. Use before editing or cloning a tool.
+requires_approval: false
+tags:
+  - matimo
+  - meta
+  - discovery
+
+parameters:
+  name:
+    type: string
+    required: true
+    description: Name of the tool to retrieve
+  tool_dir:
+    type: string
+    required: false
+    description: Directory containing the tool (default ./matimo-tools)
+
+execution:
+  type: function
+  code: './matimo_get_tool.ts'
+
+output_schema:
+  type: object
+  properties:
+    found:
+      type: boolean
+    name:
+      type: string
+    yaml_content:
+      type: string
+    definition:
+      type: object
+    message:
+      type: string

package/tools/matimo_get_tool/matimo_get_tool.ts

@@ -0,0 +1,56 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { validateToolDefinition, getGlobalMatimoLogger } from '@matimo/core';
+
+interface GetToolParams {
+  name: string;
+  tool_dir?: string;
+}
+
+interface GetToolResult {
+  found: boolean;
+  name?: string;
+  yaml_content?: string;
+  definition?: Record<string, unknown>;
+  message: string;
+}
+
+export default async function matimoGetTool(params: GetToolParams): Promise<GetToolResult> {
+  const logger = getGlobalMatimoLogger();
+  const toolDir = params.tool_dir ?? './matimo-tools';
+
+  const defPath = path.join(toolDir, params.name, 'definition.yaml');
+  if (!fs.existsSync(defPath)) {
+    logger.warn('matimo_get_tool: tool not found', { name: params.name, path: defPath });
+    return { found: false, message: `Tool "${params.name}" not found at ${defPath}` };
+  }
+
+  const yamlContent = fs.readFileSync(defPath, 'utf-8');
+
+  let definition: Record<string, unknown>;
+  try {
+    const parsed = yaml.load(yamlContent);
+    const validated = validateToolDefinition(parsed);
+    // Omit internal _definitionPath from the returned object
+    const { _definitionPath: _, ...rest } = validated as Record<string, unknown>;
+    definition = rest;
+  } catch (err) {
+    return {
+      found: true,
+      name: params.name,
+      yaml_content: yamlContent,
+      message: `Tool YAML is invalid: ${(err as Error).message}`,
+    };
+  }
+
+  logger.debug('matimo_get_tool: retrieved', { name: params.name });
+
+  return {
+    found: true,
+    name: params.name,
+    yaml_content: yamlContent,
+    definition,
+    message: `Tool "${params.name}" retrieved successfully`,
+  };
+}

package/tools/matimo_get_tool_status/definition.yaml

@@ -0,0 +1,42 @@
+name: matimo_get_tool_status
+version: '1.0.0'
+description: Get the current status, risk level, and approval state of a tool. Works for both pending (agent-created) and approved tools.
+requires_approval: true
+tags:
+  - matimo
+  - meta
+  - approval
+
+parameters:
+  name:
+    type: string
+    required: true
+    description: Name of the tool to check
+  tool_dir:
+    type: string
+    required: false
+    description: Directory containing the tool (default ./matimo-tools)
+
+execution:
+  type: function
+  code: './matimo_get_tool_status.ts'
+
+output_schema:
+  type: object
+  properties:
+    found:
+      type: boolean
+    name:
+      type: string
+    status:
+      type: string
+    riskLevel:
+      type: string
+    approvalState:
+      type: string
+    approvedAt:
+      type: string
+    approvedBy:
+      type: string
+    message:
+      type: string