@mumbrane/arrakis 0.8.2 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/skills.js ADDED
@@ -0,0 +1,122 @@
1
+ // Skills: folders of instructions (and optional scripts/templates) the model
2
+ // loads when a task calls for them. Each skill is a directory with a SKILL.md:
3
+ //
4
+ // ---
5
+ // name: release
6
+ // description: Cut a release: bump the version, update the changelog, tag and publish.
7
+ // ---
8
+ // Step-by-step instructions…
9
+ //
10
+ // Only the name and description go into the system prompt; the model reads
11
+ // the full instructions with the `skill` tool. Skills are found in:
12
+ // ~/.arrakis/skills, ~/.claude/skills (yours, everywhere)
13
+ // <project>/.arrakis/skills, <project>/.claude/skills (this project; trusted folders only)
14
+ import fs from 'node:fs';
15
+ import os from 'node:os';
16
+ import path from 'node:path';
17
+ import { HOME_DIR } from './config.js';
18
+
19
+ export function skillDirs(cwd) {
20
+ return {
21
+ user: [path.join(HOME_DIR, 'skills'), path.join(os.homedir(), '.claude', 'skills')],
22
+ project: [path.join(cwd, '.arrakis', 'skills'), path.join(cwd, '.claude', 'skills')],
23
+ };
24
+ }
25
+
26
+ export function parseSkill(text) {
27
+ const m = text.match(/^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/);
28
+ const meta = {};
29
+ let body = text;
30
+ if (m) {
31
+ body = m[2];
32
+ for (const line of m[1].split('\n')) {
33
+ const kv = line.match(/^([\w-]+):\s*(.*)$/);
34
+ if (kv) meta[kv[1].toLowerCase()] = kv[2].trim().replace(/^["']|["']$/g, '');
35
+ }
36
+ }
37
+ return { meta, body: body.trim() };
38
+ }
39
+
40
+ export function projectHasSkills(cwd) {
41
+ return skillDirs(cwd).project.some((d) => {
42
+ try {
43
+ return fs.readdirSync(d).some((n) => fs.existsSync(path.join(d, n, 'SKILL.md')));
44
+ } catch {
45
+ return false;
46
+ }
47
+ });
48
+ }
49
+
50
+ // Later sources override earlier ones with the same name (project beats user).
51
+ export function loadSkills(cwd, { includeProject = true } = {}) {
52
+ const { user, project } = skillDirs(cwd);
53
+ const skills = new Map();
54
+ for (const [dirs, source] of [[user, 'user'], [includeProject ? project : [], 'project']]) {
55
+ for (const dir of dirs) {
56
+ let names = [];
57
+ try {
58
+ names = fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory() || e.isSymbolicLink()).map((e) => e.name);
59
+ } catch {
60
+ continue;
61
+ }
62
+ for (const n of names) {
63
+ const file = path.join(dir, n, 'SKILL.md');
64
+ if (!fs.existsSync(file)) continue;
65
+ try {
66
+ const { meta } = parseSkill(fs.readFileSync(file, 'utf8'));
67
+ const name = (meta.name || n).toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
68
+ skills.set(name, { name, description: meta.description || '(no description)', dir: path.dirname(file), file, source });
69
+ } catch {}
70
+ }
71
+ }
72
+ }
73
+ return [...skills.values()].sort((a, b) => a.name.localeCompare(b.name));
74
+ }
75
+
76
+ // What the model gets when it loads a skill: the instructions plus the
77
+ // skill's other files, which it can read or run.
78
+ export function readSkill(skill) {
79
+ const { body } = parseSkill(fs.readFileSync(skill.file, 'utf8'));
80
+ const files = [];
81
+ const walk = (dir, rel) => {
82
+ for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
83
+ if (e.name.startsWith('.')) continue;
84
+ const r = rel ? `${rel}/${e.name}` : e.name;
85
+ if (e.isDirectory()) walk(path.join(dir, e.name), r);
86
+ else if (r !== 'SKILL.md') files.push(r);
87
+ if (files.length > 100) return;
88
+ }
89
+ };
90
+ walk(skill.dir, '');
91
+ return `# Skill: ${skill.name}\nFolder: ${skill.dir}\n${files.length ? `Files in this skill (read or run them by path):\n${files.map((f) => `- ${path.join(skill.dir, f)}`).join('\n')}\n` : ''}\n${body}`;
92
+ }
93
+
94
+ export function createSkill({ name, description, where = 'user', cwd }) {
95
+ const slug = name.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-|-$/g, '');
96
+ if (!slug) throw new Error('A skill needs a name.');
97
+ const base = where === 'project' ? path.join(cwd, '.arrakis', 'skills') : path.join(HOME_DIR, 'skills');
98
+ const dir = path.join(base, slug);
99
+ if (fs.existsSync(path.join(dir, 'SKILL.md'))) throw new Error(`A skill named "${slug}" already exists at ${dir}.`);
100
+ fs.mkdirSync(dir, { recursive: true });
101
+ fs.writeFileSync(
102
+ path.join(dir, 'SKILL.md'),
103
+ `---\nname: ${slug}\ndescription: ${description || 'Describe when this skill should be used.'}\n---\n\n# ${name}\n\nWrite the steps arrakis should follow when this skill is used.\n\n1. …\n2. …\n\nPut any scripts or templates next to this file and mention them here by name.\n`,
104
+ );
105
+ return path.join(dir, 'SKILL.md');
106
+ }
107
+
108
+ export function skillTool(getSkills) {
109
+ return {
110
+ name: 'skill',
111
+ description:
112
+ 'Load one of the available skills (listed in the system prompt under "Skills") to get its full instructions. Load a skill whenever the task matches its description, before starting the work, then follow its instructions.',
113
+ parameters: { type: 'object', properties: { name: { type: 'string', description: 'The skill name' } }, required: ['name'] },
114
+ summary: (a) => a.name,
115
+ run(a) {
116
+ const skills = getSkills();
117
+ const s = skills.find((x) => x.name === String(a.name).toLowerCase());
118
+ if (!s) throw new Error(`No skill "${a.name}". Available: ${skills.map((x) => x.name).join(', ') || 'none'}`);
119
+ return { content: readSkill(s), display: `loaded ${s.name}` };
120
+ },
121
+ };
122
+ }
package/src/theme.js CHANGED
@@ -1,29 +1,31 @@
1
- // "Dusk": arrakis's design language.
1
+ // "Spice": arrakis's design language.
2
2
  //
3
- // A twilight palette: lavender as the primary, deep iris and orchid as
4
- // accents, lilac for soft text, plum panels behind code. Mint, amber and rose
5
- // carry meaning (success, caution, error) and are used sparingly.
3
+ // A desert palette: spice gold as the primary, burnt orange and ember as
4
+ // accents, sand for soft text, dark umber panels behind code. Sage, saffron
5
+ // and rose carry meaning (success, caution, error) and are used sparingly.
6
+ // (The keys below name roles, kept from earlier themes: `violet` is the
7
+ // primary color, `orchid` the hot accent, `lilac` the soft text, and so on.)
6
8
  //
7
9
  // Colors render in 24-bit where the terminal supports it and fall back to the
8
10
  // nearest 256-color value elsewhere (e.g. macOS Terminal.app). NO_COLOR turns
9
11
  // everything off.
10
12
 
11
13
  export const PALETTE = {
12
- violet: [167, 139, 250], // primary
13
- iris: [124, 92, 246], // deep accent
14
- orchid: [226, 125, 245], // hot accent
15
- lilac: [221, 214, 254], // soft text
16
- mist: [140, 132, 166], // muted text
17
- dusk: [84, 76, 110], // faint lines
18
- mint: [110, 231, 183],
19
- amber: [246, 196, 92],
20
- rose: [251, 113, 150],
21
- sky: [134, 200, 252],
22
- ink: [20, 17, 31], // text on light chips
23
- panel: [32, 27, 48], // code panels
24
- raise: [46, 38, 70], // selected rows, user messages
25
- addBg: [22, 52, 44],
26
- delBg: [62, 26, 44],
14
+ violet: [232, 166, 64], // primary: spice gold
15
+ iris: [196, 104, 38], // deep accent: burnt orange
16
+ orchid: [244, 128, 52], // hot accent: ember
17
+ lilac: [240, 226, 196], // soft text: sand
18
+ mist: [156, 144, 124], // muted text: dune
19
+ dusk: [96, 86, 70], // faint lines
20
+ mint: [150, 208, 130], // success: sage
21
+ amber: [242, 206, 108], // caution / numbers: saffron
22
+ rose: [238, 110, 110],
23
+ sky: [124, 196, 210], // functions, links: oasis teal
24
+ ink: [26, 19, 11], // text on gold chips
25
+ panel: [40, 32, 22], // code panels: umber
26
+ raise: [58, 45, 28], // selected rows, your messages
27
+ addBg: [28, 50, 30],
28
+ delBg: [64, 28, 26],
27
29
  };
28
30
 
29
31
  const env = process.env;
package/src/tools.js CHANGED
@@ -1,8 +1,10 @@
1
1
  import fs from 'node:fs';
2
2
  import path from 'node:path';
3
3
  import { spawn, spawnSync } from 'node:child_process';
4
+ import { browserTool } from './browser.js';
4
5
 
5
6
  const MAX_OUTPUT = 30000;
7
+ const IMAGE_MIME = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp' };
6
8
  const SKIP_DIRS = new Set(['.git', 'node_modules', '.hg', '.svn', '__pycache__', '.venv', 'venv', '.DS_Store']);
7
9
 
8
10
  export function truncate(text, max = MAX_OUTPUT) {
@@ -132,7 +134,7 @@ function diffPreview(oldStr, newStr, maxLines = 24) {
132
134
  export const TOOLS = [
133
135
  {
134
136
  name: 'read_file',
135
- description: 'Read a text file. Returns lines prefixed with line numbers. Use offset/limit for large files. Reading a directory lists its entries.',
137
+ description: 'Read a file. Text comes back with line numbers (use offset/limit for large files); images (png, jpg, gif, webp) come back as the image itself so you can look at them. Reading a directory lists its entries.',
136
138
  parameters: {
137
139
  type: 'object',
138
140
  properties: {
@@ -150,6 +152,12 @@ export const TOOLS = [
150
152
  const entries = fs.readdirSync(p, { withFileTypes: true }).map((e) => (e.isDirectory() ? `${e.name}/` : e.name));
151
153
  return entries.sort().join('\n') || '(empty directory)';
152
154
  }
155
+ const mime = IMAGE_MIME[path.extname(p).toLowerCase()];
156
+ if (mime) {
157
+ if (stat.size > 5 * 1024 * 1024) return `${rel(ctx, p)} is an image larger than 5 MB; it can't be shown.`;
158
+ const kb = Math.round(stat.size / 1024);
159
+ return { content: `Image ${rel(ctx, p)} (${kb} KB). It is attached so you can look at it.`, display: `image · ${kb} KB`, images: [`data:${mime};base64,${fs.readFileSync(p).toString('base64')}`] };
160
+ }
153
161
  const buf = fs.readFileSync(p);
154
162
  if (isBinary(buf)) return `${rel(ctx, p)} is a binary file (${stat.size} bytes).`;
155
163
  const lines = buf.toString('utf8').split('\n');
@@ -360,6 +368,26 @@ export const TOOLS = [
360
368
  ];
361
369
 
362
370
  TOOLS.push(
371
+ {
372
+ name: 'web_search',
373
+ description: 'Search the web. Returns titles, links and snippets for the top results. Follow up with web_fetch (or the browser) to read the pages that matter. Use specific queries; run several searches for different angles.',
374
+ parameters: {
375
+ type: 'object',
376
+ properties: {
377
+ query: { type: 'string', description: 'What to search for' },
378
+ count: { type: 'integer', description: 'How many results (default 8, max 20)' },
379
+ },
380
+ required: ['query'],
381
+ },
382
+ summary: (a) => a.query,
383
+ async run(a, ctx) {
384
+ const results = await webSearch(String(a.query), Math.min(20, Math.max(1, a.count || 8)), ctx.signal);
385
+ if (!results.length) return { content: `No results for "${a.query}".`, display: 'no results' };
386
+ const body = results.map((r, i) => `${i + 1}. ${r.title}\n ${r.url}${r.snippet ? `\n ${r.snippet}` : ''}`).join('\n\n');
387
+ return { content: `Results for "${a.query}":\n\n${body}`, display: `${results.length} results` };
388
+ },
389
+ },
390
+ browserTool,
363
391
  {
364
392
  name: 'web_fetch',
365
393
  description: 'Fetch a URL and return its content as text (HTML is converted to readable text). Use it for documentation, issues, API references and other pages the task needs.',
@@ -419,7 +447,10 @@ TOOLS.push(
419
447
  run(a, ctx) {
420
448
  if (!Array.isArray(a.todos)) throw new Error('todos must be an array');
421
449
  const todos = a.todos.map((t) => ({ content: String(t.content ?? ''), status: ['pending', 'in_progress', 'completed'].includes(t.status) ? t.status : 'pending' }));
422
- if (ctx.agent) ctx.agent.todos = todos;
450
+ if (ctx.agent) {
451
+ ctx.agent.todos = todos;
452
+ ctx.agent.session.append?.({ type: 'todos', todos }); // so the list survives a resume
453
+ }
423
454
  ctx.ui.todos(todos);
424
455
  return { content: 'Todo list updated. Keep it current as you work.', display: null };
425
456
  },
@@ -445,8 +476,57 @@ TOOLS.push(
445
476
  },
446
477
  );
447
478
 
448
- export const READ_ONLY_TOOLS = new Set(['read_file', 'grep', 'list_files', 'web_fetch']);
449
- export const PARALLEL_SAFE = new Set(['read_file', 'grep', 'list_files', 'web_fetch', 'task']);
479
+ export const READ_ONLY_TOOLS = new Set(['read_file', 'grep', 'list_files', 'web_fetch', 'web_search', 'skill']);
480
+ export const PARALLEL_SAFE = new Set(['read_file', 'grep', 'list_files', 'web_fetch', 'web_search', 'skill', 'task']);
481
+
482
+ // Web search: Tavily or Brave when you have an API key for them, otherwise
483
+ // DuckDuckGo's plain-HTML results page (no key needed).
484
+ async function webSearch(query, count, signal) {
485
+ const timeout = anySignal([signal, AbortSignal.timeout(20000)]);
486
+ if (process.env.TAVILY_API_KEY) {
487
+ const res = await fetch('https://api.tavily.com/search', {
488
+ method: 'POST',
489
+ signal: timeout,
490
+ headers: { 'content-type': 'application/json', authorization: `Bearer ${process.env.TAVILY_API_KEY}` },
491
+ body: JSON.stringify({ query, max_results: count }),
492
+ });
493
+ if (!res.ok) throw new Error(`Tavily search failed: HTTP ${res.status}`);
494
+ return ((await res.json()).results ?? []).map((r) => ({ title: r.title, url: r.url, snippet: (r.content ?? '').slice(0, 300) }));
495
+ }
496
+ if (process.env.BRAVE_SEARCH_API_KEY) {
497
+ const res = await fetch(`https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=${count}`, {
498
+ signal: timeout,
499
+ headers: { accept: 'application/json', 'x-subscription-token': process.env.BRAVE_SEARCH_API_KEY },
500
+ });
501
+ if (!res.ok) throw new Error(`Brave search failed: HTTP ${res.status}`);
502
+ return ((await res.json()).web?.results ?? []).map((r) => ({ title: r.title, url: r.url, snippet: htmlToText(r.description ?? '') }));
503
+ }
504
+ const res = await fetch(process.env.ARRAKIS_SEARCH_URL || 'https://html.duckduckgo.com/html/', {
505
+ method: 'POST',
506
+ signal: timeout,
507
+ headers: { 'content-type': 'application/x-www-form-urlencoded', 'user-agent': 'Mozilla/5.0 (compatible; arrakis-cli)' },
508
+ body: `q=${encodeURIComponent(query)}`,
509
+ });
510
+ if (!res.ok) throw new Error(`Search failed: HTTP ${res.status}. Set TAVILY_API_KEY or BRAVE_SEARCH_API_KEY for a dedicated search API.`);
511
+ return parseDuckDuckGo(await res.text()).slice(0, count);
512
+ }
513
+
514
+ export function parseDuckDuckGo(html) {
515
+ const out = [];
516
+ const blocks = html.split(/<div[^>]+class="[^"]*\bresult\b[^"]*"/).slice(1);
517
+ for (const b of blocks) {
518
+ const a = b.match(/<a[^>]+class="[^"]*result__a[^"]*"[^>]+href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/);
519
+ if (!a) continue;
520
+ let url = a[1].replace(/&amp;/g, '&');
521
+ const uddg = url.match(/[?&]uddg=([^&]+)/);
522
+ if (uddg) url = decodeURIComponent(uddg[1]);
523
+ if (url.startsWith('//')) url = `https:${url}`;
524
+ if (/duckduckgo\.com\/y\.js|\/\/duckduckgo\.com\/\?/.test(url)) continue; // ads
525
+ const snippet = b.match(/class="[^"]*result__snippet[^"]*"[^>]*>([\s\S]*?)<\/(a|div)>/);
526
+ out.push({ title: htmlToText(a[2]).replace(/^# /, ''), url, snippet: snippet ? htmlToText(snippet[1]).slice(0, 300) : '' });
527
+ }
528
+ return out;
529
+ }
450
530
 
451
531
  function anySignal(signals) {
452
532
  const list = signals.filter(Boolean);
@@ -521,7 +601,8 @@ export async function executeToolCall(call, ctx) {
521
601
  ctx.ui.toolStart(tool.label ?? tool.name, safe(() => tool.summary?.(args)) ?? '', { prefix: sub ? `${ctx.label}` : '' });
522
602
  try {
523
603
  if (tool.validate) tool.validate(args, ctx);
524
- if (tool.writes && ctx.permissions.planMode) {
604
+ const writes = tool.writes || tool.writesFor?.(args);
605
+ if (writes && ctx.permissions.planMode) {
525
606
  if (!sub) ctx.ui.toolResult('Blocked: plan mode is on', true);
526
607
  return 'Blocked: plan mode is on, so files cannot be changed and commands cannot run. Finish investigating with the read-only tools, then present your plan. The user turns plan mode off with /plan when they approve.';
527
608
  }
@@ -533,7 +614,7 @@ export async function executeToolCall(call, ctx) {
533
614
  }
534
615
  }
535
616
  let preview = null;
536
- if (tool.needsPermission) {
617
+ if (tool.needsPermission || tool.needsPermissionFor?.(args)) {
537
618
  preview = safe(() => tool.preview?.(args, ctx));
538
619
  if (preview && sub) preview.title = `[${ctx.label}] ${preview.title}`;
539
620
  const allowed = await ctx.permissions.check(tool.name, preview);
@@ -548,6 +629,7 @@ export async function executeToolCall(call, ctx) {
548
629
  if (ctx.hooks) await ctx.hooks.run('PostToolUse', { tool: tool.name, input: args, result: truncate(String(content), 10000), sessionId: ctx.sessionId });
549
630
  // Skip the diff when the user just saw it in the approval prompt.
550
631
  if (!sub && display !== null) ctx.ui.toolResult(display ?? content, false, { lines: preview?.shown ? null : lines });
632
+ if (raw?.images?.length) return { text: truncate(String(content)), images: raw.images };
551
633
  return truncate(String(content));
552
634
  } catch (err) {
553
635
  const msg = `Error: ${err.name === 'AbortError' || err.name === 'TimeoutError' ? (ctx.signal?.aborted ? 'interrupted by the user' : 'timed out') : err.message}`;
package/src/tui.js CHANGED
@@ -189,7 +189,7 @@ export class FancyUI extends UI {
189
189
  }
190
190
  }
191
191
 
192
- // Your message: a raised violet panel across the full width, so it stands
192
+ // Your message: a raised gold-edged panel across the full width, so it stands
193
193
  // apart from both the terminal and arrakis's replies.
194
194
  echoUser(text) {
195
195
  const c = this.c;
@@ -892,7 +892,7 @@ export class FancyUI extends UI {
892
892
 
893
893
  // ---- welcome -----------------------------------------------------------
894
894
 
895
- banner({ version, model, provider, cwd, instructions = [], resumed, mcp = [], hooks = 0, update }) {
895
+ banner({ version, model, provider, cwd, instructions = [], resumed, mcp = [], hooks = 0, skills = 0, update }) {
896
896
  const c = this.c;
897
897
  const home = process.env.HOME ?? '';
898
898
  const tild = (p) => (home && p.startsWith(home) ? '~' + p.slice(home.length) : p);
@@ -907,6 +907,7 @@ export class FancyUI extends UI {
907
907
  if (instructions.length) facts.push(['notes', c.lilac(instructions.map((f) => tild(f).split('/').pop()).join(', '))]);
908
908
  if (mcp.length) facts.push(['mcp', mcp.map((s) => (s.status === 'connected' ? `${c.lilac(s.name)} ${c.faint(`${s.tools.length} tools`)}` : c.rose(`${s.name} failed`))).join(c.faint(' · '))]);
909
909
  if (hooks) facts.push(['hooks', c.lilac(`${hooks} active`)]);
910
+ if (skills) facts.push(['skills', c.lilac(`${skills} available`)]);
910
911
  if (resumed) facts.push(['session', c.lilac(resumed)]);
911
912
  for (const [k, v] of facts) out += ` ${c.iris(GLYPH.tool)} ${c.mist(k.padEnd(8))} ${v}\n`;
912
913
  if (update) out += `\n ${c.orchid('↑')} ${c.lilac(`arrakis ${update} is out`)} ${c.faint('·')} ${c.mist('npm install -g @mumbrane/arrakis')}\n`;