@denizokcu/haze 0.0.1

package/dist/skills/installer/SkillInstaller.js

@@ -0,0 +1,48 @@
+import fs from 'fs-extra';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { confirm } from '@inquirer/prompts';
+import { GLOBAL_SKILLS_DIR } from '../../config/paths.js';
+import { loadSkill } from '../SkillLoader.js';
+import { listFilesRecursive } from '../../utils/fs.js';
+function repoUrl(spec) {
+    if (spec.startsWith('http'))
+        return spec;
+    if (spec.startsWith('github:'))
+        return `https://github.com/${spec.slice(7)}.git`;
+    if (/^[\w.-]+\/[\w.-]+$/.test(spec))
+        return `https://github.com/${spec}.git`;
+    return spec;
+}
+export async function installSkill(spec) {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'haze-skill-'));
+    const url = repoUrl(spec);
+    const clone = spawnSync('git', ['clone', '--depth=1', url, tmp], { stdio: 'inherit' });
+    if (clone.status !== 0)
+        throw new Error('git clone failed');
+    const skill = await loadSkill(tmp, 'global');
+    if (!skill)
+        throw new Error('Repository does not contain a root skill.yaml');
+    console.log(`\nSkill: ${skill.manifest.name} ${skill.manifest.version}`);
+    console.log(skill.manifest.description);
+    console.log('\nFiles:');
+    for (const f of await listFilesRecursive(tmp))
+        console.log(`  ${f}`);
+    const deps = skill.manifest.dependencies;
+    if (deps?.cli?.length)
+        console.log(`\nCLI dependencies: ${deps.cli.map(d => d.name).join(', ')}`);
+    if (deps?.env?.length)
+        console.log(`Env dependencies: ${deps.env.map(d => d.name).join(', ')}`);
+    const dest = path.join(GLOBAL_SKILLS_DIR, skill.manifest.name);
+    if (await fs.pathExists(dest))
+        console.log(`\nExisting skill will be replaced: ${dest}`);
+    const ok = await confirm({ message: 'Approve and activate this skill? It is code from the internet, regrettably.', default: false });
+    if (!ok)
+        return;
+    await fs.remove(dest);
+    await fs.ensureDir(path.dirname(dest));
+    await fs.copy(tmp, dest, { filter: src => !src.includes(`${path.sep}.git${path.sep}`) });
+    await fs.remove(path.join(dest, '.git'));
+    console.log(`Installed ${skill.manifest.name} to ${dest}`);
+}

package/dist/skills/manifestSchema.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+export declare const skillManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodString;
+    author: z.ZodOptional<z.ZodString>;
+    homepage: z.ZodOptional<z.ZodString>;
+    dependencies: z.ZodOptional<z.ZodObject<{
+        cli: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            required: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+        env: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            required: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        path: z.ZodString;
+        input: z.ZodOptional<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+    }, z.core.$strip>>>;
+    prompts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        path: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;

package/dist/skills/manifestSchema.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+const jsonSchema = z.lazy(() => z.object({
+    type: z.string().optional(),
+    required: z.array(z.string()).optional(),
+    properties: z.record(z.string(), jsonSchema).optional(),
+    items: jsonSchema.optional(),
+    description: z.string().optional(),
+    enum: z.array(z.unknown()).optional(),
+    additionalProperties: z.union([z.boolean(), jsonSchema]).optional()
+}).passthrough());
+export const skillManifestSchema = z.object({
+    name: z.string().min(1).regex(/^[a-zA-Z0-9_-]+$/),
+    version: z.string().min(1),
+    description: z.string().min(1),
+    author: z.string().optional(),
+    homepage: z.string().url().optional(),
+    dependencies: z.object({
+        cli: z.array(z.object({ name: z.string(), description: z.string().optional(), required: z.boolean().optional() })).optional(),
+        env: z.array(z.object({ name: z.string(), description: z.string().optional(), required: z.boolean().optional() })).optional()
+    }).optional(),
+    tools: z.array(z.object({ name: z.string().min(1), description: z.string().min(1), path: z.string().min(1), input: jsonSchema.optional() })).optional(),
+    prompts: z.array(z.object({ name: z.string().min(1), description: z.string().optional(), path: z.string().min(1) })).optional(),
+});

package/dist/skills/types.d.ts

@@ -0,0 +1,60 @@
+export interface JsonSchema {
+    type?: string;
+    required?: string[];
+    properties?: Record<string, JsonSchema & {
+        description?: string;
+    }>;
+    items?: JsonSchema;
+    description?: string;
+    enum?: unknown[];
+    additionalProperties?: boolean | JsonSchema;
+}
+export interface SkillManifest {
+    name: string;
+    version: string;
+    description: string;
+    author?: string;
+    homepage?: string;
+    dependencies?: {
+        cli?: {
+            name: string;
+            description?: string;
+            required?: boolean;
+        }[];
+        env?: {
+            name: string;
+            description?: string;
+            required?: boolean;
+        }[];
+    };
+    tools?: SkillToolManifest[];
+    prompts?: SkillPromptManifest[];
+}
+export interface SkillToolManifest {
+    name: string;
+    description: string;
+    path: string;
+    input?: JsonSchema;
+}
+export interface SkillPromptManifest {
+    name: string;
+    description?: string;
+    path: string;
+}
+export interface LoadedSkill {
+    dir: string;
+    manifestPath: string;
+    manifest: SkillManifest;
+    prompts: LoadedPrompt[];
+    tools: LoadedTool[];
+    source: 'global' | 'local';
+}
+export interface LoadedPrompt extends SkillPromptManifest {
+    content: string;
+    absolutePath: string;
+}
+export interface LoadedTool extends SkillToolManifest {
+    id: string;
+    skillName: string;
+    absolutePath: string;
+}

package/dist/skills/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/ToolExecutor.d.ts

@@ -0,0 +1,3 @@
+import type { LoadedSkill, LoadedTool } from '../skills/types.js';
+import type { ToolResult } from './types.js';
+export declare function executeTool(tool: LoadedTool, skill: LoadedSkill, input: Record<string, unknown>): Promise<ToolResult>;

package/dist/tools/ToolExecutor.js

@@ -0,0 +1,15 @@
+import { pathToFileURL } from 'node:url';
+export async function executeTool(tool, skill, input) {
+    try {
+        const context = { cwd: process.cwd(), skillDir: skill.dir };
+        const mod = await import(`${pathToFileURL(tool.absolutePath).href}?t=${Date.now()}`);
+        if (typeof mod.execute !== 'function') {
+            return { ok: false, message: 'Tool must export execute(input, context)' };
+        }
+        const result = await mod.execute(input ?? {}, context);
+        return result ?? { ok: true };
+    }
+    catch (error) {
+        return { ok: false, message: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/tools/types.d.ts

@@ -0,0 +1,9 @@
+export interface ToolContext {
+    cwd: string;
+    skillDir: string;
+}
+export interface ToolResult {
+    ok: boolean;
+    message?: string;
+    data?: unknown;
+}

package/dist/tools/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ui/components/ErrorView.d.ts

@@ -0,0 +1,3 @@
+export declare function ErrorView({ error }: {
+    error: unknown;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/ui/components/ErrorView.js

@@ -0,0 +1,7 @@
+import { jsxs as _jsxs } from "react/jsx-runtime";
+import { Text } from 'ink';
+import { theme } from '../theme.js';
+export function ErrorView({ error }) {
+    const message = error instanceof Error ? error.message : String(error);
+    return _jsxs(Text, { color: theme.danger, children: ["Error: ", message] });
+}

package/dist/ui/components/Header.d.ts

@@ -0,0 +1,3 @@
+export declare function Header({ subtitle }: {
+    subtitle?: string;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/ui/components/Header.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { theme } from '../theme.js';
+export function Header({ subtitle }) {
+    return _jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsx(Text, { color: theme.purple, bold: true, children: "Haze" }), subtitle ? _jsx(Text, { color: theme.muted, children: subtitle }) : _jsx(Text, { color: theme.muted, children: "A small agent, because apparently that is allowed." })] });
+}

package/dist/ui/components/MarkdownText.d.ts

@@ -0,0 +1,3 @@
+export declare function MarkdownText({ content }: {
+    content: string;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/ui/components/MarkdownText.js

@@ -0,0 +1,108 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text, useStdout } from 'ink';
+import { marked } from 'marked';
+import { highlight } from 'cli-highlight';
+import stripAnsi from 'strip-ansi';
+import { theme } from '../theme.js';
+export function MarkdownText({ content }) {
+    const tokens = marked.lexer(content, { gfm: true, breaks: true });
+    const { stdout } = useStdout();
+    const width = Math.max(20, (stdout.columns ?? process.stdout.columns ?? 100) - 2);
+    return _jsx(Box, { flexDirection: "column", children: tokens.map((token, index) => _jsx(MarkdownBlock, { token: token, width: width }, index)) });
+}
+function MarkdownBlock({ token, width }) {
+    switch (token.type) {
+        case 'heading': {
+            const heading = token;
+            return _jsx(Box, { marginTop: heading.depth <= 2 ? 1 : 0, children: _jsxs(Text, { color: theme.purple, bold: true, children: ['#'.repeat(heading.depth), " ", _jsx(InlineMarkdown, { text: heading.text })] }) });
+        }
+        case 'paragraph': {
+            const paragraph = token;
+            return _jsx(Box, { marginBottom: 1, children: _jsx(InlineMarkdown, { text: paragraph.text }) });
+        }
+        case 'text': {
+            const text = token;
+            return _jsx(InlineMarkdown, { text: text.text });
+        }
+        case 'space':
+            return _jsx(Text, { children: " " });
+        case 'hr':
+            return _jsx(Text, { color: theme.deepPurple, children: "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500" });
+        case 'blockquote': {
+            const quote = token;
+            return _jsx(Box, { flexDirection: "column", marginY: 1, children: quote.text.split('\n').map((line, index) => _jsx(Text, { backgroundColor: theme.quoteBg, children: padAnsi(line || ' ', width) }, index)) });
+        }
+        case 'list': {
+            const list = token;
+            return _jsx(Box, { flexDirection: "column", marginBottom: 1, children: list.items.map((item, index) => _jsxs(Box, { children: [_jsx(Text, { color: theme.purple, children: list.ordered ? `${index + 1}. ` : '• ' }), _jsx(InlineMarkdown, { text: item.text.replace(/\n/g, ' ') })] }, index)) });
+        }
+        case 'code': {
+            const code = token;
+            return _jsx(CodeBlock, { code: code.text, language: code.lang, width: width });
+        }
+        case 'table': {
+            const table = token;
+            return _jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsx(Text, { color: theme.violet, children: table.header.map(cell => stripInline(cell.text)).join(' | ') }), _jsx(Text, { color: theme.deepPurple, children: table.header.map(() => '---').join(' | ') }), table.rows.map((row, index) => _jsx(Text, { children: row.map(cell => stripInline(cell.text)).join(' | ') }, index))] });
+        }
+        default:
+            return _jsx(Text, { children: 'raw' in token ? String(token.raw) : '' });
+    }
+}
+function CodeBlock({ code, language, width }) {
+    let rendered;
+    try {
+        rendered = highlight(code, { language: language || undefined, ignoreIllegals: true });
+    }
+    catch {
+        rendered = code;
+    }
+    const lines = rendered.replace(/\n$/, '').split('\n');
+    return _jsxs(Box, { flexDirection: "column", marginY: 1, children: [language ? _jsx(Text, { color: theme.muted, backgroundColor: theme.codeBg, children: padAnsi(language, width) }) : null, lines.map((line, index) => _jsx(Text, { backgroundColor: theme.codeBg, children: padAnsi(line || ' ', width) }, index))] });
+}
+function InlineMarkdown({ text }) {
+    const parts = tokenizeInline(text);
+    return _jsx(Text, { children: parts.map((part, index) => {
+            if (part.kind === 'code')
+                return _jsx(Text, { color: theme.warning, children: part.text }, index);
+            if (part.kind === 'strong')
+                return _jsx(Text, { bold: true, children: part.text }, index);
+            if (part.kind === 'em')
+                return _jsx(Text, { italic: true, children: part.text }, index);
+            if (part.kind === 'link')
+                return _jsx(Text, { color: theme.violet, children: part.text }, index);
+            return _jsx(Text, { children: part.text }, index);
+        }) });
+}
+function tokenizeInline(text) {
+    const out = [];
+    const regex = /`([^`]+)`|\*\*([^*]+)\*\*|\*([^*]+)\*|\[([^\]]+)\]\(([^)]+)\)/g;
+    let last = 0;
+    for (const match of text.matchAll(regex)) {
+        if (match.index > last)
+            out.push({ kind: 'text', text: text.slice(last, match.index) });
+        if (match[1])
+            out.push({ kind: 'code', text: match[1] });
+        else if (match[2])
+            out.push({ kind: 'strong', text: match[2] });
+        else if (match[3])
+            out.push({ kind: 'em', text: match[3] });
+        else if (match[4])
+            out.push({ kind: 'link', text: `${match[4]} (${match[5]})` });
+        last = match.index + match[0].length;
+    }
+    if (last < text.length)
+        out.push({ kind: 'text', text: text.slice(last) });
+    return out;
+}
+function stripInline(text) {
+    return text
+        .replace(/`([^`]+)`/g, '$1')
+        .replace(/\*\*([^*]+)\*\*/g, '$1')
+        .replace(/\*([^*]+)\*/g, '$1')
+        .replace(/~~([^~]+)~~/g, '$1')
+        .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');
+}
+function padAnsi(value, width) {
+    const visible = stripAnsi(value).length;
+    return visible >= width ? value : value + ' '.repeat(width - visible);
+}

package/dist/ui/components/TextInput.d.ts

@@ -0,0 +1,9 @@
+export declare function TextInput({ placeholder, disabled, mask, historyItems, recordHistory, onHistoryAdd, onSubmit }: {
+    placeholder?: string;
+    disabled?: boolean;
+    mask?: boolean;
+    historyItems?: string[];
+    recordHistory?: boolean;
+    onHistoryAdd?: (value: string) => void;
+    onSubmit: (value: string) => void;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/ui/components/TextInput.js

@@ -0,0 +1,120 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { Text, useInput } from 'ink';
+import { theme } from '../theme.js';
+export function TextInput({ placeholder, disabled, mask, historyItems = [], recordHistory = true, onHistoryAdd, onSubmit }) {
+    const [value, setValue] = useState('');
+    const [cursor, setCursor] = useState(0);
+    const history = useRef(historyItems);
+    const historyIndex = useRef(null);
+    const draft = useRef('');
+    useEffect(() => {
+        history.current = historyItems;
+    }, [historyItems]);
+    useEffect(() => {
+        if (!disabled) {
+            setValue('');
+            setCursor(0);
+            historyIndex.current = null;
+            draft.current = '';
+        }
+    }, [disabled]);
+    function setInput(next, nextCursor = next.length) {
+        setValue(next);
+        setCursor(Math.max(0, Math.min(nextCursor, next.length)));
+    }
+    function showHistory(index) {
+        historyIndex.current = index;
+        setInput(history.current[index] ?? '');
+    }
+    useInput((input, key) => {
+        if (disabled)
+            return;
+        if (key.escape) {
+            setInput('');
+            historyIndex.current = null;
+            draft.current = '';
+            return;
+        }
+        if (key.return) {
+            const submitted = value.trim();
+            setInput('');
+            historyIndex.current = null;
+            draft.current = '';
+            if (submitted) {
+                if (recordHistory) {
+                    if (history.current[history.current.length - 1] !== submitted)
+                        history.current = [...history.current, submitted];
+                    onHistoryAdd?.(submitted);
+                }
+                onSubmit(submitted);
+            }
+            return;
+        }
+        if (key.leftArrow) {
+            setCursor(current => Math.max(0, current - 1));
+            return;
+        }
+        if (key.rightArrow) {
+            setCursor(current => Math.min(value.length, current + 1));
+            return;
+        }
+        if (key.upArrow) {
+            if (history.current.length === 0)
+                return;
+            if (historyIndex.current === null) {
+                draft.current = value;
+                showHistory(history.current.length - 1);
+            }
+            else {
+                showHistory(Math.max(0, historyIndex.current - 1));
+            }
+            return;
+        }
+        if (key.downArrow) {
+            if (historyIndex.current === null)
+                return;
+            if (historyIndex.current < history.current.length - 1) {
+                showHistory(historyIndex.current + 1);
+            }
+            else {
+                historyIndex.current = null;
+                setInput(draft.current);
+            }
+            return;
+        }
+        if (key.backspace) {
+            if (cursor === 0)
+                return;
+            setInput(value.slice(0, cursor - 1) + value.slice(cursor), cursor - 1);
+            historyIndex.current = null;
+            return;
+        }
+        if (key.delete) {
+            if (cursor >= value.length)
+                return;
+            setInput(value.slice(0, cursor) + value.slice(cursor + 1), cursor);
+            historyIndex.current = null;
+            return;
+        }
+        if (key.ctrl && input === 'a') {
+            setCursor(0);
+            return;
+        }
+        if (key.ctrl && input === 'e') {
+            setCursor(value.length);
+            return;
+        }
+        if (key.ctrl && input === 'c')
+            return;
+        if (input) {
+            setInput(value.slice(0, cursor) + input + value.slice(cursor), cursor + input.length);
+            historyIndex.current = null;
+        }
+    });
+    const displayValue = mask ? '•'.repeat(value.length) : value;
+    const beforeCursor = displayValue.slice(0, cursor);
+    const cursorChar = displayValue[cursor] ?? ' ';
+    const afterCursor = displayValue.slice(cursor + 1);
+    return _jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { color: theme.purple, children: "\u203A " }), value.length === 0 ? _jsxs(_Fragment, { children: [_jsx(Text, { inverse: true, children: " " }), _jsxs(Text, { color: theme.muted, children: [" ", placeholder ?? 'Type a message...'] })] }) : _jsxs(_Fragment, { children: [beforeCursor, _jsx(Text, { inverse: true, children: cursorChar }), afterCursor] })] });
+}

package/dist/ui/theme.d.ts

@@ -0,0 +1,11 @@
+export declare const theme: {
+    purple: string;
+    deepPurple: string;
+    violet: string;
+    muted: string;
+    danger: string;
+    success: string;
+    warning: string;
+    codeBg: string;
+    quoteBg: string;
+};

package/dist/ui/theme.js

@@ -0,0 +1,11 @@
+export const theme = {
+    purple: '#a78bfa',
+    deepPurple: '#6d28d9',
+    violet: '#8b5cf6',
+    muted: '#9ca3af',
+    danger: '#fb7185',
+    success: '#34d399',
+    warning: '#fbbf24',
+    codeBg: '#1f1633',
+    quoteBg: '#171127'
+};

package/dist/utils/fs.d.ts

@@ -0,0 +1,14 @@
+export interface WalkEntry {
+    path: string;
+    absolutePath: string;
+    name: string;
+    isDirectory: boolean;
+    isFile: boolean;
+}
+export interface WalkOptions {
+    recursive?: boolean;
+    maxEntries?: number;
+    filter?: (entry: WalkEntry) => boolean | Promise<boolean>;
+}
+export declare function walkDir(root: string, options?: WalkOptions): Promise<WalkEntry[]>;
+export declare function listFilesRecursive(root: string): Promise<string[]>;

package/dist/utils/fs.js

@@ -0,0 +1,36 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+const SKIP_ENTRIES = new Set(['node_modules', '.git']);
+export async function walkDir(root, options = {}) {
+    const { recursive = false, maxEntries = Infinity, filter } = options;
+    const result = [];
+    async function walk(dir) {
+        for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+            if (result.length >= maxEntries)
+                return;
+            if (SKIP_ENTRIES.has(entry.name))
+                continue;
+            const absolutePath = path.join(dir, entry.name);
+            const relativePath = path.relative(root, absolutePath);
+            const walkEntry = {
+                path: relativePath,
+                absolutePath,
+                name: entry.name,
+                isDirectory: entry.isDirectory(),
+                isFile: entry.isFile(),
+            };
+            if (filter && !await filter(walkEntry))
+                continue;
+            result.push(walkEntry);
+            if (entry.isDirectory() && recursive)
+                await walk(absolutePath);
+        }
+    }
+    if (await fs.pathExists(root))
+        await walk(root);
+    return result;
+}
+export async function listFilesRecursive(root) {
+    const entries = await walkDir(root, { recursive: true });
+    return entries.filter(e => e.isFile).map(e => e.path).sort();
+}

package/dist/utils/path.d.ts

@@ -0,0 +1,3 @@
+export declare function workspaceRoot(): string;
+export declare function resolveWorkspacePath(inputPath: string): string;
+export declare function workspaceRelativePath(absolutePath: string): string;

package/dist/utils/path.js

@@ -0,0 +1,16 @@
+import path from 'node:path';
+export function workspaceRoot() {
+    return process.cwd();
+}
+export function resolveWorkspacePath(inputPath) {
+    const root = workspaceRoot();
+    const resolved = path.resolve(root, inputPath);
+    const relative = path.relative(root, resolved);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error(`Path is outside the workspace: ${inputPath}`);
+    }
+    return resolved;
+}
+export function workspaceRelativePath(absolutePath) {
+    return path.relative(workspaceRoot(), absolutePath) || '.';
+}

package/dist/utils/yaml.d.ts

@@ -0,0 +1,2 @@
+export declare function readYaml<T>(file: string): Promise<T>;
+export declare function writeYaml(file: string, value: unknown): Promise<void>;

package/dist/utils/yaml.js

@@ -0,0 +1,8 @@
+import fs from 'fs-extra';
+import YAML from 'yaml';
+export async function readYaml(file) {
+    return YAML.parse(await fs.readFile(file, 'utf8'));
+}
+export async function writeYaml(file, value) {
+    await fs.writeFile(file, YAML.stringify(value));
+}

package/examples/skills/files/prompts/file_tasks.md

@@ -0,0 +1 @@
+For file tasks, prefer listing files before reading unknown paths. Never ask to read secrets unless the user explicitly requests it.

package/examples/skills/files/skill.yaml

@@ -0,0 +1,28 @@
+name: files
+version: 0.1.0
+description: Safe-ish file inspection tools for the current project.
+dependencies: {}
+tools:
+  - name: list_files
+    description: List files under a directory in the current project. Skips .git and node_modules.
+    path: tools/list_files.ts
+    input:
+      type: object
+      properties:
+        dir:
+          type: string
+          description: Directory to list, relative to the current working directory.
+  - name: read_file
+    description: Read a UTF-8 text file from the current project.
+    path: tools/read_file.ts
+    input:
+      type: object
+      required: [path]
+      properties:
+        path:
+          type: string
+          description: File path relative to the current working directory.
+prompts:
+  - name: file_tasks
+    description: Guidance for file inspection tasks.
+    path: prompts/file_tasks.md

package/examples/skills/files/tools/list_files.ts

@@ -0,0 +1,21 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export async function execute(input: {dir?: string}, context: {cwd: string}) {
+  const root = path.resolve(context.cwd, input.dir ?? '.');
+  if (!root.startsWith(context.cwd)) return {ok: false, message: 'Refusing to list outside the current project.'};
+  const files: string[] = [];
+  async function walk(dir: string) {
+    for (const entry of await fs.readdir(dir)) {
+      if (entry === '.git' || entry === 'node_modules' || entry === 'dist') continue;
+      const full = path.join(dir, entry);
+      const rel = path.relative(context.cwd, full);
+      const stat = await fs.stat(full);
+      if (stat.isDirectory()) await walk(full);
+      else files.push(rel);
+      if (files.length >= 500) return;
+    }
+  }
+  await walk(root);
+  return {ok: true, message: `Found ${files.length} files.`, data: files.sort()};
+}

package/examples/skills/files/tools/read_file.ts

@@ -0,0 +1,12 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export async function execute(input: {path: string}, context: {cwd: string}) {
+  if (!input.path) return {ok: false, message: 'Missing path.'};
+  const full = path.resolve(context.cwd, input.path);
+  if (!full.startsWith(context.cwd)) return {ok: false, message: 'Refusing to read outside the current project.'};
+  const stat = await fs.stat(full);
+  if (!stat.isFile()) return {ok: false, message: 'Path is not a file.'};
+  if (stat.size > 200_000) return {ok: false, message: 'File is too large for the intentionally tiny attention span.'};
+  return {ok: true, message: `Read ${input.path}.`, data: await fs.readFile(full, 'utf8')};
+}