junecoder 1.0.0

package/session.mjs

@@ -0,0 +1,114 @@
+/**
+ * Session persistence — save/restore/archive conversation history.
+ *
+ * Saves display lines (rendered conversation) plus agent history to disk,
+ * allowing sessions to survive restarts.
+ */
+import { join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, renameSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+
+/** Directory under ~/.junecode/ for session storage. */
+function sessionsDir(cwd) {
+  const dir = join(homedir(), '.junecode', 'sessions');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** Encode a path for use as a filename (replace / with _). */
+function pathSlug(cwd) {
+  return cwd.replace(/[^a-zA-Z0-9]/g, '_').replace(/^_+/, '') || 'default';
+}
+
+/** Path to the session file for a given project directory. */
+export function sessionPath(cwd) {
+  return join(sessionsDir(), pathSlug(cwd) + '.json');
+}
+
+/** Save current agent history and display lines. */
+export function saveSession(agent, displayLines) {
+  try {
+    const data = {
+      cwd: agent.cwd,
+      history: agent.history,
+      displayLines: displayLines || [],
+      planMode: agent.planMode,
+      tasks: agent.tasks,
+      goal: agent.goal,
+      savedAt: Date.now(),
+    };
+    writeFileSync(sessionPath(agent.cwd), JSON.stringify(data, null, 2), 'utf-8');
+  } catch {
+    // Non-fatal: session save fails silently
+  }
+}
+
+/** Load the last session for a project directory. Returns null if none found. */
+export function loadSession(cwd) {
+  const path = sessionPath(cwd);
+  if (!existsSync(path)) return null;
+  try {
+    const raw = readFileSync(path, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/** Clear session data for a project directory. */
+export function clearSession(cwd) {
+  try {
+    const path = sessionPath(cwd);
+    if (existsSync(path)) unlinkSync(path);
+  } catch { /* ignore */ }
+}
+
+/** Archive the current session with timestamp. */
+export function archiveCurrent(cwd) {
+  try {
+    const src = sessionPath(cwd);
+    if (!existsSync(src)) return;
+    const ts = Date.now();
+    const dst = join(sessionsDir(), pathSlug(cwd) + '_' + ts + '.json');
+    renameSync(src, dst);
+  } catch { /* ignore */ }
+}
+
+/** List available session slots for a given project directory. */
+export function listSlots(cwd) {
+  try {
+    const dir = sessionsDir();
+    const prefix = pathSlug(cwd);
+    const files = readdirSync(dir).filter(f => f.startsWith(prefix) && f.endsWith('.json'));
+    return files.map(f => {
+      const match = f.match(/_(\d+)\.json$/);
+      return {
+        file: f,
+        timestamp: match ? parseInt(match[1]) : 0,
+        label: match ? new Date(parseInt(match[1])).toLocaleString() : f,
+      };
+    }).sort((a, b) => b.timestamp - a.timestamp);
+  } catch {
+    return [];
+  }
+}
+
+/** Switch to a different session slot. Returns the restored data or null. */
+export function switchToSlot(cwd, slot) {
+  try {
+    const dir = sessionsDir();
+    const src = join(dir, slot);
+    if (!existsSync(src)) return null;
+    const raw = readFileSync(src, 'utf-8');
+    // Save current session first
+    const curPath = sessionPath(cwd);
+    if (existsSync(curPath)) {
+      archiveCurrent(cwd);
+    }
+    // Copy slot to current session path
+    writeFileSync(curPath, raw, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}

package/skills.mjs

@@ -0,0 +1,147 @@
+/**
+ * Skills module — loads and formats project skills from .junecode/skills/.
+ *
+ * Skill files are markdown (.md) with optional YAML-like frontmatter.
+ * Frontmatter keys: name (string), description (string).
+ * Without frontmatter, name derives from filename and description from first line.
+ */
+import { join, basename, extname } from 'node:path';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+
+/**
+ * Load skills from cwd/.junecode/skills/.
+ * @param {string} cwd
+ * @returns {{ name: string, description: string, path: string }[]}
+ */
+export function loadSkills(cwd) {
+  const skillsDir = join(cwd, '.junecode', 'skills');
+  if (!existsSync(skillsDir)) return [];
+
+  let entries;
+  try {
+    entries = readdirSync(skillsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const skills = [];
+  for (const ent of entries) {
+    if (!ent.isFile()) continue;
+    const ext = extname(ent.name).toLowerCase();
+    if (ext !== '.md') continue;
+
+    const filePath = join(skillsDir, ent.name);
+    let content;
+    try {
+      content = readFileSync(filePath, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    const { name, description } = parseFrontmatter(content, ent.name);
+    skills.push({ name, description, path: filePath });
+  }
+  return skills;
+}
+
+/**
+ * Format a skill listing for inclusion in the system prompt.
+ * @param {object[]} skills
+ * @returns {string}
+ */
+export function formatSkillListing(skills) {
+  if (!skills || skills.length === 0) return 'No skills loaded.';
+  return skills.map((s) => `- ${s.name}: ${s.description}`).join('\n');
+}
+
+/**
+ * Read a specific skill file by name.
+ * @param {string} cwd
+ * @param {string} name
+ * @returns {string|null} skill content or null if not found
+ */
+export function readSkill(cwd, name) {
+  const skillsDir = join(cwd, '.junecode', 'skills');
+  if (!existsSync(skillsDir)) return null;
+
+  // Try exact name match (with/without .md extension)
+  const candidates = [
+    join(skillsDir, name),
+    join(skillsDir, name + '.md'),
+  ];
+
+  for (const cand of candidates) {
+    if (existsSync(cand)) {
+      try {
+        return readFileSync(cand, 'utf-8');
+      } catch {
+        return null;
+      }
+    }
+  }
+
+  // Fallback: scan directory for a match by frontmatter name
+  let entries;
+  try {
+    entries = readdirSync(skillsDir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  for (const ent of entries) {
+    if (!ent.isFile() || extname(ent.name).toLowerCase() !== '.md') continue;
+    const filePath = join(skillsDir, ent.name);
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      const fm = parseFrontmatter(content, ent.name);
+      if (fm.name === name) return content;
+    } catch {
+      continue;
+    }
+  }
+
+  return null;
+}
+
+// ─── Internal helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Parse optional YAML-like frontmatter from markdown content.
+ * Frontmatter is delimited by --- lines at the top of the file.
+ * Returns { name, description } — falls back to filename/first-line if absent.
+ */
+function parseFrontmatter(content, filename) {
+  const noExt = basename(filename, extname(filename));
+  let name = noExt;
+  let description = '';
+
+  // Try to parse frontmatter
+  const lines = content.split('\n');
+  if (lines[0]?.trim() === '---') {
+    const endIdx = lines.indexOf('---', 1);
+    if (endIdx > 0) {
+      const fmLines = lines.slice(1, endIdx);
+      for (const line of fmLines) {
+        const colonIdx = line.indexOf(':');
+        if (colonIdx > 0) {
+          const key = line.slice(0, colonIdx).trim();
+          const value = line.slice(colonIdx + 1).trim();
+          if (key === 'name') name = value;
+          else if (key === 'description') description = value;
+        }
+      }
+    }
+  }
+
+  // Fallback: use first non-empty non-heading line as description
+  if (!description) {
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('---') || trimmed.startsWith('#')) continue;
+      description = trimmed.slice(0, 100);
+      break;
+    }
+  }
+
+  return { name, description };
+}

package/tools/bash.mjs

@@ -0,0 +1,41 @@
+/**
+ * bash tool — execute a shell command and return stdout+stderr.
+ */
+import { execSync } from 'node:child_process';
+
+export const bashTool = {
+  name: 'bash',
+  description:
+    'Execute a shell command and return stdout+stderr. Use for running commands, builds, tests.',
+  parameters: {
+    type: 'object',
+    properties: {
+      command: { type: 'string', description: 'Shell command to execute' },
+      timeout: { type: 'number', description: 'Timeout in ms (default 120000)' },
+    },
+    required: ['command'],
+  },
+  readonly: false,
+  parallel: false,
+
+  async execute(args, agent) {
+    const cwd = agent?.cwd || process.cwd();
+    const timeout = args.timeout || 120_000;
+
+    try {
+      const output = execSync(args.command, {
+        cwd,
+        encoding: 'utf-8',
+        timeout,
+        maxBuffer: 10 * 1024 * 1024, // 10 MB
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      return output || '(command completed with no output)';
+    } catch (err) {
+      const stdout = err.stdout || '';
+      const stderr = err.stderr || '';
+      const msg = err.message || String(err);
+      return `Command failed (exit code ${err.status || '?'}): ${msg}\n${stdout}${stderr}`;
+    }
+  },
+};

package/tools/delete.mjs

@@ -0,0 +1,57 @@
+/**
+ * delete tool — delete a file.
+ */
+import { unlinkSync, existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export const deleteTool = {
+  name: 'delete',
+  description:
+    'Delete a file. Refuses to delete git-tracked files as a safety measure.',
+  parameters: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'File path, relative to cwd or absolute' },
+      force: { type: 'boolean', description: 'Allow deleting git-tracked files (default false)' },
+    },
+    required: ['path'],
+  },
+  readonly: false,
+  parallel: false,
+
+  async execute(args, agent) {
+    const cwd = agent?.cwd || process.cwd();
+    const abs = resolve(cwd, args.path);
+
+    if (!existsSync(abs)) {
+      return `Error: file not found: ${args.path}`;
+    }
+
+    const st = statSync(abs);
+    if (st.isDirectory()) {
+      return `Error: "${args.path}" is a directory. Use bash to remove directories.`;
+    }
+
+    try {
+      // Check if git-tracked
+      if (!args.force) {
+        const { execSync } = await import('node:child_process');
+        try {
+          execSync(`git ls-files --error-unmatch "${abs}"`, {
+            cwd,
+            stdio: 'ignore',
+            timeout: 3000,
+          });
+          return `Error: "${args.path}" is tracked by git. Use force=true to delete, or remove via bash with explicit user confirmation.`;
+        } catch {
+          // Not git-tracked — OK to delete
+        }
+      }
+
+      unlinkSync(abs);
+      return `Deleted: ${args.path}`;
+    } catch (err) {
+      return `Error deleting file: ${err.message}`;
+    }
+  },
+};

package/tools/edit.mjs

@@ -0,0 +1,71 @@
+/**
+ * edit tool — replace exact text in a file.
+ *
+ * Uses execSync (cat > file) for disk writes to avoid virtual-filesystem isolation
+ * that can cause writes to be lost when the agent session ends.
+ */
+import { readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { execSync } from 'node:child_process';
+
+/** Escape a path for safe use in a single-quoted shell string. */
+function shellEscape(str) {
+  return "'" + str.replace(/'/g, "'\\''") + "'";
+}
+
+export const editTool = {
+  name: 'edit',
+  description:
+    'Edit a file by exact string replacement. old_string must match exactly once unless replace_all is set.',
+  parameters: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'File path' },
+      old_string: { type: 'string', description: 'Exact text to find and replace' },
+      new_string: { type: 'string', description: 'Replacement text' },
+      replace_all: { type: 'boolean', description: 'Replace all occurrences instead of just one (default false)' },
+    },
+    required: ['path', 'old_string', 'new_string'],
+  },
+  readonly: false,
+  parallel: false,
+
+  async execute(args, agent) {
+    const cwd = agent?.cwd || process.cwd();
+    const abs = resolve(cwd, args.path);
+
+    if (!existsSync(abs)) {
+      return `Error: file not found: ${args.path}`;
+    }
+
+    try {
+      const original = readFileSync(abs, 'utf-8');
+      const count = original.split(args.old_string).length - 1;
+
+      if (count === 0) {
+        return `Error: old_string not found in ${args.path}. Make sure the text matches exactly (whitespace, indentation).`;
+      }
+
+      if (count > 1 && !args.replace_all) {
+        return `Error: old_string matches ${count} times in ${args.path}. Use replace_all=true or add more surrounding context to make it unique.`;
+      }
+
+      const updated = args.replace_all
+        ? original.split(args.old_string).join(args.new_string)
+        : original.replace(args.old_string, args.new_string);
+
+      mkdirSync(dirname(abs), { recursive: true });
+      execSync(`cat > ${shellEscape(abs)}`, {
+        cwd,
+        input: updated,
+        encoding: 'utf-8',
+        timeout: 10_000,
+        maxBuffer: 20 * 1024 * 1024,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      return `Replaced ${args.replace_all ? count : 1} occurrence(s) in ${args.path}`;
+    } catch (err) {
+      return `Error editing file: ${err.message}`;
+    }
+  },
+};

package/tools/fetch.mjs

@@ -0,0 +1,55 @@
+/**
+ * fetch tool — fetch a URL and return its content as text.
+ */
+export const fetchTool = {
+  name: 'fetch',
+  description:
+    'Fetch a URL and return its content as text. HTML pages are stripped to readable text.',
+  parameters: {
+    type: 'object',
+    properties: {
+      url: { type: 'string', description: 'http/https URL' },
+    },
+    required: ['url'],
+  },
+  readonly: true,
+  parallel: true,
+
+  async execute(args, _agent) {
+    try {
+      const response = await fetch(args.url, {
+        signal: AbortSignal.timeout(20_000),
+      });
+
+      if (!response.ok) {
+        return `Error: HTTP ${response.status} ${response.statusText}`;
+      }
+
+      const contentType = response.headers.get('content-type') || '';
+      const text = await response.text();
+
+      // If HTML, strip tags for readability
+      if (contentType.includes('html') || text.trim().startsWith('<!') || text.trim().startsWith('<html')) {
+        const stripped = text
+          .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+          .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
+          .replace(/<[^>]+>/g, ' ')
+          .replace(/&amp;/g, '&')
+          .replace(/&lt;/g, '<')
+          .replace(/&gt;/g, '>')
+          .replace(/&quot;/g, '"')
+          .replace(/&#39;/g, "'")
+          .replace(/\s+/g, ' ')
+          .trim();
+
+        return stripped.slice(0, 50_000) +
+          (stripped.length > 50_000 ? '\n\n[truncated]' : '');
+      }
+
+      return text.slice(0, 50_000) +
+        (text.length > 50_000 ? '\n\n[truncated]' : '');
+    } catch (err) {
+      return `Error fetching URL: ${err.message}`;
+    }
+  },
+};

package/tools/glob.mjs

@@ -0,0 +1,83 @@
+/**
+ * glob tool — find files by glob pattern.
+ */
+import { readdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+const IGNORED_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', '.turbo', 'coverage',
+]);
+
+export const globTool = {
+  name: 'glob',
+  description:
+    'Find files by glob pattern. Returns matching paths. Supports ** for recursive matching.',
+  parameters: {
+    type: 'object',
+    properties: {
+      pattern: { type: 'string', description: 'Glob pattern — supports **, *, ?, and character classes' },
+      path: { type: 'string', description: 'Directory to search in (default cwd)' },
+    },
+    required: ['pattern'],
+  },
+  readonly: true,
+  parallel: true,
+
+  async execute(args, agent) {
+    const cwd = agent?.cwd || process.cwd();
+    const base = args.path ? resolve(cwd, args.path) : cwd;
+    const regex = globToRegex(args.pattern);
+    const results = [];
+
+    try {
+      for (const relPath of walkFilesSync(base)) {
+        if (regex.test(relPath)) {
+          results.push(relPath);
+          if (results.length >= 1000) break;
+        }
+      }
+    } catch {
+      return '(no matches or glob failed)';
+    }
+
+    if (results.length === 0) return '(no matches)';
+
+    results.sort();
+    return results.slice(0, 200).join('\n') +
+      (results.length > 200 ? `\n... and ${results.length - 200} more` : '');
+  },
+};
+
+/** Recursively walk files, yielding relative paths (skips IGNORED_DIRS). */
+function* walkFilesSync(dir, rel = '') {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (e.isDirectory() && IGNORED_DIRS.has(e.name)) continue;
+    const relPath = rel ? `${rel}/${e.name}` : e.name;
+    if (e.isDirectory()) {
+      yield* walkFilesSync(join(dir, e.name), relPath);
+    } else {
+      yield relPath;
+    }
+  }
+}
+
+/** Convert a glob pattern to a RegExp: **\/ matches zero-or-more dirs, ** matches across dirs, * matches within a segment, ? matches a single char. */
+function globToRegex(pattern) {
+  const DS = '\u0001'; // placeholder for **/
+  const DP = '\u0002'; // placeholder for **
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*\//g, DS)
+    .replace(/\*\*/g, DP)
+    .replace(/\*/g, '[^/]*')
+    .replace(/\?/g, '[^/]')
+    .replaceAll(DS, '(?:.*/)?')
+    .replaceAll(DP, '.*');
+  return new RegExp('^' + escaped + '$');
+}

package/tools/grep.mjs

@@ -0,0 +1,58 @@
+/**
+ * grep tool — search file contents with a regex.
+ */
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { resolve, relative, extname } from 'node:path';
+import { execSync } from 'node:child_process';
+
+const TEXT_EXTS = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
+  '.json', '.md', '.txt', '.yml', '.yaml', '.toml',
+  '.css', '.html', '.xml', '.svg', '.py', '.rb', '.go',
+  '.rs', '.java', '.c', '.h', '.cpp', '.hpp', '.sh',
+  '.mjs', '.env', '.gitignore', '.dockerignore',
+]);
+
+export const grepTool = {
+  name: 'grep',
+  description:
+    'Search file contents with a regex. Returns matching lines as path:line: content.',
+  parameters: {
+    type: 'object',
+    properties: {
+      pattern: { type: 'string', description: 'JavaScript regular expression' },
+      path: { type: 'string', description: 'Directory or file to search (default cwd)' },
+      glob: { type: 'string', description: "Only search files matching this glob (e.g. '*.mjs')" },
+    },
+    required: ['pattern'],
+  },
+  readonly: true,
+  parallel: true,
+
+  async execute(args, agent) {
+    const cwd = agent?.cwd || process.cwd();
+    const base = args.path ? resolve(cwd, args.path) : cwd;
+
+    try {
+      let cmd = `grep -rn --include='*.${args.glob || '*'}' `;
+      // Escape the pattern for shell
+      const escaped = args.pattern.replace(/'/g, "'\\''");
+      cmd += `'${escaped}' "${base}" 2>/dev/null | head -200`;
+
+      const output = execSync(cmd, {
+        encoding: 'utf-8',
+        timeout: 10000,
+        maxBuffer: 5 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+
+      if (!output) return '(no matches)';
+
+      const lines = output.split('\n').filter(Boolean);
+      return lines.slice(0, 200).join('\n') +
+        (lines.length > 200 ? `\n... and ${lines.length - 200} more` : '');
+    } catch {
+      return '(no matches or grep failed)';
+    }
+  },
+};

package/tools/index.mjs

@@ -0,0 +1,41 @@
+/**
+ * Tools index — toOpenAISchema converter and baseTools array.
+ */
+import { readTool } from './read.mjs';
+import { writeTool } from './write.mjs';
+import { editTool } from './edit.mjs';
+import { bashTool } from './bash.mjs';
+import { globTool } from './glob.mjs';
+import { grepTool } from './grep.mjs';
+import { lsTool } from './ls.mjs';
+import { fetchTool } from './fetch.mjs';
+import { websearchTool } from './websearch.mjs';
+import { deleteTool } from './delete.mjs';
+
+/**
+ * Convert an internal tool definition to OpenAI function-calling schema.
+ */
+export function toOpenAISchema(tool) {
+  return {
+    type: 'function',
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters,
+    },
+  };
+}
+
+/** All base external tools as an array. */
+export const baseTools = [
+  readTool,
+  writeTool,
+  editTool,
+  bashTool,
+  globTool,
+  grepTool,
+  lsTool,
+  fetchTool,
+  websearchTool,
+  deleteTool,
+];