@kodax-ai/kodax-cli 0.7.38

package/dist/builtin/skill-creator/scripts/init-skill.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ensureDirectory, getDefaultSkillsDir, pathExists } from './utils.js';
+
+function titleFromSlug(name) {
+  return name
+    .split('-')
+    .filter(Boolean)
+    .map((part) => part[0]?.toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+export function renderSkillTemplate(name, description) {
+  const title = titleFromSlug(name);
+  return `---
+name: ${name}
+description: ${description}
+user-invocable: true
+allowed-tools: "Read, Grep, Glob"
+compatibility: "Optimized for KodaX and Agent Skills style directories."
+---
+
+# ${title}
+
+Describe the task this skill handles, the trigger boundary, and the expected outcome.
+
+## When to use
+
+- Use this skill when the user asks for ${title.toLowerCase()}.
+- Do not use this skill when the request only needs a short explanation or is out of scope.
+
+## Workflow
+
+1. Restate the task boundary in one sentence.
+2. Gather the minimum context needed to do the work well.
+3. Execute the task, preferring small, verifiable steps.
+4. Summarize what changed, what was validated, and any remaining risks.
+
+## References
+
+- Put deeper guidance in \`references/\`.
+- Put reusable templates or static files in \`assets/\`.
+- Put repeatable helper scripts in \`scripts/\`.
+`;
+}
+
+export function renderEvalTemplate(name) {
+  return JSON.stringify({
+    skill_name: name,
+    evals: [
+      {
+        id: 1,
+        prompt: 'TODO: Add a realistic user request to evaluate this skill.',
+        expected_output: 'Describe what a successful result should accomplish.',
+        files: [],
+        assertions: [],
+      },
+    ],
+  }, null, 2);
+}
+
+export async function initSkill(options) {
+  const baseDir = path.resolve(options.baseDir ?? getDefaultSkillsDir());
+  const skillDir = path.join(baseDir, options.name);
+  const description = options.description
+    ?? `Describe what ${options.name} does and when it should be used.`;
+
+  if (await pathExists(skillDir)) {
+    if (!options.force) {
+      throw new Error(`Skill directory already exists: ${skillDir}`);
+    }
+  }
+
+  await ensureDirectory(skillDir);
+  await ensureDirectory(path.join(skillDir, 'references'));
+  await ensureDirectory(path.join(skillDir, 'assets'));
+  await ensureDirectory(path.join(skillDir, 'scripts'));
+
+  await writeFile(
+    path.join(skillDir, 'SKILL.md'),
+    renderSkillTemplate(options.name, description),
+    'utf8'
+  );
+
+  if (options.includeEvals !== false) {
+    await ensureDirectory(path.join(skillDir, 'evals'));
+    await writeFile(
+      path.join(skillDir, 'evals', 'evals.json'),
+      `${renderEvalTemplate(options.name)}\n`,
+      'utf8'
+    );
+  }
+
+  return {
+    skillDir,
+    created: [
+      'SKILL.md',
+      ...(options.includeEvals !== false ? ['evals/evals.json'] : []),
+      'references/',
+      'assets/',
+      'scripts/',
+    ],
+  };
+}
+
+function parseArgs(argv) {
+  const args = {
+    name: argv[2],
+    baseDir: undefined,
+    description: undefined,
+    force: false,
+    includeEvals: true,
+  };
+
+  for (let index = 3; index < argv.length; index += 1) {
+    const token = argv[index];
+    if ((token === '--path' || token === '--dest') && argv[index + 1]) {
+      args.baseDir = argv[++index];
+    } else if (token === '--description' && argv[index + 1]) {
+      args.description = argv[++index];
+    } else if (token === '--force') {
+      args.force = true;
+    } else if (token === '--no-evals') {
+      args.includeEvals = false;
+    }
+  }
+
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  if (!args.name) {
+    console.error('Usage: node scripts/init-skill.js <skill-name> [--path <skills-dir>] [--description <text>] [--force] [--no-evals]');
+    process.exit(1);
+  }
+
+  const result = await initSkill(args);
+  console.log(`Initialized ${result.skillDir}`);
+}
+
+const isDirectRun = process.argv[1]
+  && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+
+if (isDirectRun) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

package/dist/builtin/skill-creator/scripts/install-skill.d.ts

@@ -0,0 +1,29 @@
+import type { SkillPackageManifest } from './package-skill.js';
+
+export interface InstalledSkillResult {
+  skillName: string;
+  installedTo: string;
+  source: string;
+  manifest: SkillPackageManifest | null;
+}
+
+export function readSkillPackageBuffer(buffer: Uint8Array): {
+  skillName: string;
+  manifest: SkillPackageManifest | null;
+  entries: Array<{ relativePath: string; bytes: Uint8Array }>;
+};
+
+export function installSkillArchive(
+  archivePath: string,
+  options?: { skillsDir?: string; force?: boolean }
+): Promise<InstalledSkillResult>;
+
+export function installSkillDirectory(
+  skillDir: string,
+  options?: { skillsDir?: string; force?: boolean }
+): Promise<InstalledSkillResult>;
+
+export function installSkill(
+  inputPath: string,
+  options?: { skillsDir?: string; force?: boolean }
+): Promise<InstalledSkillResult>;

package/dist/builtin/skill-creator/scripts/install-skill.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+
+import { cp, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { strFromU8, unzipSync } from 'fflate';
+import { validateSkillDirectory } from './quick-validate.js';
+import { getDefaultSkillsDir, parseSkillMarkdown, pathExists } from './utils.js';
+
+const PACKAGE_MANIFEST_PATH = '.kodax-package.json';
+
+function normalizeArchivePath(relativePath) {
+  return relativePath.replace(/\\/g, '/').replace(/^\.?\//, '');
+}
+
+function assertSafeArchivePath(relativePath) {
+  const normalized = normalizeArchivePath(relativePath);
+  if (!normalized || normalized.startsWith('/') || normalized.includes('../')) {
+    throw new Error(`Unsafe archive entry path: ${relativePath}`);
+  }
+  return normalized;
+}
+
+function isZipLike(filePath) {
+  return /\.(skill|zip)$/i.test(filePath);
+}
+
+export function readSkillPackageBuffer(buffer) {
+  const archive = unzipSync(buffer);
+  const entries = Object.entries(archive).map(([relativePath, bytes]) => ({
+    relativePath: assertSafeArchivePath(relativePath),
+    bytes,
+  }));
+
+  const skillEntry = entries.find((entry) => entry.relativePath === 'SKILL.md');
+  if (!skillEntry) {
+    throw new Error('Archive is missing SKILL.md');
+  }
+
+  const parsedSkill = parseSkillMarkdown(strFromU8(skillEntry.bytes));
+  const skillName = typeof parsedSkill.frontmatter.name === 'string'
+    ? parsedSkill.frontmatter.name.trim()
+    : '';
+  const description = typeof parsedSkill.frontmatter.description === 'string'
+    ? parsedSkill.frontmatter.description.trim()
+    : '';
+  if (!skillName || !description) {
+    throw new Error('Archive SKILL.md is missing required frontmatter fields.');
+  }
+
+  const manifestEntry = entries.find((entry) => entry.relativePath === PACKAGE_MANIFEST_PATH);
+  const manifest = manifestEntry
+    ? JSON.parse(strFromU8(manifestEntry.bytes))
+    : null;
+
+  return {
+    skillName,
+    manifest,
+    entries: entries.filter((entry) => entry.relativePath !== PACKAGE_MANIFEST_PATH),
+  };
+}
+
+async function ensureInstallTarget(targetDir, force) {
+  if (await pathExists(targetDir)) {
+    if (!force) {
+      throw new Error(`Target skill already exists: ${targetDir}`);
+    }
+    await rm(targetDir, { recursive: true, force: true });
+  }
+  await mkdir(targetDir, { recursive: true });
+}
+
+export async function installSkillArchive(archivePath, options = {}) {
+  const skillsDir = path.resolve(options.skillsDir ?? getDefaultSkillsDir());
+  const archive = readSkillPackageBuffer(await readFile(archivePath));
+  const targetDir = path.join(skillsDir, archive.skillName);
+  await ensureInstallTarget(targetDir, options.force === true);
+
+  for (const entry of archive.entries) {
+    const destination = path.join(targetDir, entry.relativePath);
+    await mkdir(path.dirname(destination), { recursive: true });
+    await writeFile(destination, entry.bytes);
+  }
+
+  return {
+    skillName: archive.skillName,
+    installedTo: targetDir,
+    source: path.resolve(archivePath),
+    manifest: archive.manifest,
+  };
+}
+
+export async function installSkillDirectory(skillDir, options = {}) {
+  const validation = await validateSkillDirectory(skillDir);
+  if (!validation.valid) {
+    throw new Error(`Cannot install invalid skill:\n- ${validation.errors.join('\n- ')}`);
+  }
+
+  const skillFilePath = path.join(skillDir, 'SKILL.md');
+  const skill = parseSkillMarkdown(await readFile(skillFilePath, 'utf8'));
+  const skillsDir = path.resolve(options.skillsDir ?? getDefaultSkillsDir());
+  const targetDir = path.join(skillsDir, skill.frontmatter.name);
+  if (await pathExists(targetDir)) {
+    if (!options.force) {
+      throw new Error(`Target skill already exists: ${targetDir}`);
+    }
+    await rm(targetDir, { recursive: true, force: true });
+  }
+  await mkdir(skillsDir, { recursive: true });
+  await cp(skillDir, targetDir, { recursive: true });
+
+  return {
+    skillName: skill.frontmatter.name,
+    installedTo: targetDir,
+    source: path.resolve(skillDir),
+    manifest: null,
+  };
+}
+
+export async function installSkill(inputPath, options = {}) {
+  const resolvedInput = path.resolve(inputPath);
+  const inputStat = await stat(resolvedInput).catch(() => null);
+  if (!inputStat) {
+    throw new Error(`Input not found: ${resolvedInput}`);
+  }
+
+  if (inputStat.isDirectory()) {
+    return installSkillDirectory(resolvedInput, options);
+  }
+
+  if (inputStat.isFile() && isZipLike(resolvedInput)) {
+    return installSkillArchive(resolvedInput, options);
+  }
+
+  throw new Error('Input must be a skill directory or a .skill/.zip archive.');
+}
+
+function parseArgs(argv) {
+  const args = {
+    input: argv[2],
+    skillsDir: undefined,
+    force: false,
+  };
+
+  for (let index = 3; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--dest' && argv[index + 1]) {
+      args.skillsDir = argv[++index];
+    } else if (token === '--force') {
+      args.force = true;
+    }
+  }
+
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  if (!args.input) {
+    console.error('Usage: node scripts/install-skill.js <skill-dir-or-archive> [--dest <skills-dir>] [--force]');
+    process.exit(1);
+  }
+
+  const result = await installSkill(args.input, args);
+  console.log(`Installed ${result.skillName} to ${result.installedTo}`);
+}
+
+const isDirectRun = process.argv[1]
+  && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+
+if (isDirectRun) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

package/dist/builtin/skill-creator/scripts/package-skill.d.ts

@@ -0,0 +1,38 @@
+export interface PackagedSkillFile {
+  path: string;
+  size: number;
+  sha256: string;
+}
+
+export interface SkillPackageManifest {
+  format: 'kodax-skill-package';
+  version: 1;
+  created_at: string;
+  entrypoint: 'SKILL.md';
+  skill: {
+    name: string;
+    description: string;
+    compatibility: string | null;
+    user_invocable: boolean;
+    disable_model_invocation: boolean;
+  };
+  files: PackagedSkillFile[];
+  note: string;
+}
+
+export function createPackageManifest(
+  skill: { frontmatter: Record<string, unknown> },
+  files: Array<{ relativePath: string; bytes: Uint8Array; sha256: string }>,
+  options?: { createdAt?: string }
+): SkillPackageManifest;
+
+export function buildSkillPackage(
+  skillDir: string,
+  options?: { createdAt?: string }
+): Promise<{ manifest: SkillPackageManifest; bytes: Uint8Array }>;
+
+export function writeSkillPackage(
+  skillDir: string,
+  outputPath: string,
+  options?: { createdAt?: string }
+): Promise<{ manifest: SkillPackageManifest; bytes: Uint8Array; outputPath: string }>;

package/dist/builtin/skill-creator/scripts/package-skill.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { zipSync, strToU8 } from 'fflate';
+import { validateSkillDirectory } from './quick-validate.js';
+import { collectFiles, loadSkill } from './utils.js';
+
+const PACKAGE_MANIFEST_PATH = '.kodax-package.json';
+
+function toUint8Array(value) {
+  return value instanceof Uint8Array ? value : new Uint8Array(value);
+}
+
+function sha256(buffer) {
+  return createHash('sha256').update(buffer).digest('hex');
+}
+
+export function createPackageManifest(skill, files, options = {}) {
+  return {
+    format: 'kodax-skill-package',
+    version: 1,
+    created_at: options.createdAt ?? new Date().toISOString(),
+    entrypoint: 'SKILL.md',
+    skill: {
+      name: skill.frontmatter.name,
+      description: skill.frontmatter.description,
+      compatibility: skill.frontmatter.compatibility ?? null,
+      user_invocable: skill.frontmatter['user-invocable'] ?? true,
+      disable_model_invocation: skill.frontmatter['disable-model-invocation'] ?? false,
+    },
+    files: files.map((file) => ({
+      path: file.relativePath,
+      size: file.bytes.length,
+      sha256: file.sha256,
+    })),
+    note: 'This archive is a zip file with a .skill extension. Compatible agents can extract and install the included skill directory.',
+  };
+}
+
+export async function buildSkillPackage(skillDir, options = {}) {
+  const validation = await validateSkillDirectory(skillDir);
+  if (!validation.valid) {
+    throw new Error(`Cannot package invalid skill:\n- ${validation.errors.join('\n- ')}`);
+  }
+
+  const skill = await loadSkill(skillDir);
+  const discoveredFiles = await collectFiles(skillDir);
+  const files = [];
+  for (const file of discoveredFiles) {
+    if (file.relativePath.endsWith('.skill')) {
+      continue;
+    }
+    const bytes = toUint8Array(await readFile(file.absolutePath));
+    files.push({
+      ...file,
+      bytes,
+      sha256: sha256(bytes),
+    });
+  }
+
+  const manifest = createPackageManifest(skill, files, options);
+  const archiveEntries = {
+    [PACKAGE_MANIFEST_PATH]: strToU8(JSON.stringify(manifest, null, 2)),
+  };
+  for (const file of files) {
+    archiveEntries[file.relativePath] = file.bytes;
+  }
+
+  return {
+    manifest,
+    bytes: zipSync(archiveEntries, { level: 6 }),
+  };
+}
+
+export async function writeSkillPackage(skillDir, outputPath, options = {}) {
+  const result = await buildSkillPackage(skillDir, options);
+  await writeFile(outputPath, result.bytes);
+  return {
+    ...result,
+    outputPath: path.resolve(outputPath),
+  };
+}
+
+function parseArgs(argv) {
+  const args = {
+    skillDir: argv[2],
+    output: undefined,
+  };
+
+  for (let index = 3; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--output' && argv[index + 1]) {
+      args.output = argv[++index];
+    }
+  }
+
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  if (!args.skillDir) {
+    console.error('Usage: node scripts/package-skill.js <skill-dir> [--output <file.skill>]');
+    process.exit(1);
+  }
+
+  const skill = await loadSkill(args.skillDir);
+  const outputPath = args.output ?? path.join(path.dirname(args.skillDir), `${skill.frontmatter.name}.skill`);
+  const result = await writeSkillPackage(args.skillDir, outputPath);
+  console.log(`Wrote ${result.outputPath}`);
+}
+
+const isDirectRun = process.argv[1]
+  && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+
+if (isDirectRun) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

package/dist/builtin/skill-creator/scripts/quick-validate.d.ts

@@ -0,0 +1,8 @@
+export interface SkillValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+  frontmatter: Record<string, unknown> | null;
+}
+
+export function validateSkillDirectory(skillDir: string): Promise<SkillValidationResult>;

package/dist/builtin/skill-creator/scripts/quick-validate.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadSkill } from './utils.js';
+
+const ALLOWED_FRONTMATTER_KEYS = new Set([
+  'name',
+  'description',
+  'license',
+  'compatibility',
+  'metadata',
+  'allowed-tools',
+  'disable-model-invocation',
+  'user-invocable',
+  'argument-hint',
+  'context',
+  'agent',
+  'model',
+  'hooks',
+]);
+
+export async function validateSkillDirectory(skillDir) {
+  const result = {
+    valid: false,
+    errors: [],
+    warnings: [],
+    frontmatter: null,
+  };
+
+  let skill;
+  try {
+    skill = await loadSkill(skillDir);
+  } catch (error) {
+    result.errors.push(error instanceof Error ? error.message : String(error));
+    return result;
+  }
+
+  const { frontmatter, body } = skill;
+  result.frontmatter = frontmatter;
+
+  const unexpectedKeys = Object.keys(frontmatter).filter((key) => !ALLOWED_FRONTMATTER_KEYS.has(key));
+  if (unexpectedKeys.length > 0) {
+    result.errors.push(
+      `Unexpected frontmatter keys: ${unexpectedKeys.sort().join(', ')}`
+    );
+  }
+
+  const name = typeof frontmatter.name === 'string' ? frontmatter.name.trim() : '';
+  const description = typeof frontmatter.description === 'string'
+    ? frontmatter.description.trim()
+    : '';
+
+  if (!name) {
+    result.errors.push('Missing required frontmatter field: name');
+  } else {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
+      result.errors.push(
+        `Invalid skill name "${name}". Use lowercase kebab-case and avoid consecutive hyphens.`
+      );
+    }
+    if (name.length > 64) {
+      result.errors.push(`Skill name is too long (${name.length}/64).`);
+    }
+
+    const dirName = path.basename(path.resolve(skillDir));
+    if (dirName !== name) {
+      result.warnings.push(
+        `Skill directory name "${dirName}" does not match frontmatter name "${name}".`
+      );
+    }
+  }
+
+  if (!description) {
+    result.errors.push('Missing required frontmatter field: description');
+  } else {
+    if (description.length > 1024) {
+      result.errors.push(`Description is too long (${description.length}/1024).`);
+    }
+    if (/[<>]/.test(description)) {
+      result.errors.push('Description cannot contain angle brackets.');
+    }
+    if (!/[。.!?]/.test(description)) {
+      result.warnings.push('Description may be too terse; consider making the trigger conditions clearer.');
+    }
+  }
+
+  if (!body.trim()) {
+    result.errors.push('SKILL.md body is empty.');
+  }
+
+  if (frontmatter.compatibility != null) {
+    if (typeof frontmatter.compatibility !== 'string') {
+      result.errors.push('compatibility must be a string if provided.');
+    } else if (frontmatter.compatibility.length > 500) {
+      result.errors.push(`compatibility is too long (${frontmatter.compatibility.length}/500).`);
+    }
+  }
+
+  if (frontmatter['allowed-tools'] != null) {
+    const allowedTools = frontmatter['allowed-tools'];
+    const validAllowedTools = typeof allowedTools === 'string'
+      || (Array.isArray(allowedTools) && allowedTools.every((item) => typeof item === 'string'));
+    if (!validAllowedTools) {
+      result.errors.push('allowed-tools must be a string or string array.');
+    }
+  }
+
+  if (frontmatter['disable-model-invocation'] != null
+      && typeof frontmatter['disable-model-invocation'] !== 'boolean') {
+    result.errors.push('disable-model-invocation must be a boolean.');
+  }
+
+  if (frontmatter['user-invocable'] != null && typeof frontmatter['user-invocable'] !== 'boolean') {
+    result.errors.push('user-invocable must be a boolean.');
+  }
+
+  if (frontmatter.context != null && frontmatter.context !== 'fork') {
+    result.errors.push('context must be "fork" when provided.');
+  }
+
+  if (frontmatter.hooks != null && (typeof frontmatter.hooks !== 'object' || Array.isArray(frontmatter.hooks))) {
+    result.errors.push('hooks must be an object when provided.');
+  }
+
+  result.valid = result.errors.length === 0;
+  return result;
+}
+
+async function main() {
+  const skillDir = process.argv[2];
+  if (!skillDir) {
+    console.error('Usage: node scripts/quick-validate.js <skill-directory>');
+    process.exit(1);
+  }
+
+  const result = await validateSkillDirectory(skillDir);
+
+  if (result.errors.length === 0) {
+    console.log('Skill is valid.');
+  } else {
+    console.error('Skill validation failed:');
+    for (const error of result.errors) {
+      console.error(`- ${error}`);
+    }
+  }
+
+  if (result.warnings.length > 0) {
+    console.log('Warnings:');
+    for (const warning of result.warnings) {
+      console.log(`- ${warning}`);
+    }
+  }
+
+  process.exit(result.valid ? 0 : 1);
+}
+
+const isDirectRun = process.argv[1]
+  && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+
+if (isDirectRun) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}