@webship.co/workspace 0.0.0-stage → 1.0.0-beta1

package/ai-items.js

@@ -0,0 +1,202 @@
+/**
+ * The AI-items domain: agents, skills and prompts, in their three places —
+ * this workspace's folders (drafts), ~/.claude (what a session loads) and the
+ * shared repo (what the team has) — plus the git-blob comparison that says
+ * when the repo's copy differs from the folder's. The handlers live in
+ * actions/ai-items.js; the rendering in server.js imports the same primitives,
+ * so the buttons and the CLI can never disagree about where things are.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { loadWorkspaces, workspaceDir, sourceOf } = require('./workspaces');
+const { repoTree, invalidateRepoTree, gitBlobSha } = require('./repo-blobs');
+
+/* ---------------- file-item workspaces (agents, skills, prompts, docs) --- */
+
+// Where each editable kind installs into the live Claude Code CLI setup.
+const INSTALL_TARGETS = {
+  'ai-agents': path.join(process.env.HOME, '.claude', 'agents'),
+  'ai-skills': path.join(process.env.HOME, '.claude', 'skills'),
+  // Commands and prompts are two kinds that share one destination: a command is a
+  // $ARGUMENTS spec typed mid-session, a prompt is a whole `claude …` launch command
+  // for a new session. Installing one writes over the other where names collide.
+  'ai-commands': path.join(process.env.HOME, '.claude', 'commands'),
+  'ai-prompts': path.join(process.env.HOME, '.claude', 'commands'),
+};
+
+// Agents, skills and prompts exist in three places: this workspace folder
+// (drafts), ~/.claude (what a session loads) and webship/ai-agents (what
+// the team has). The item lists show all three, merged by name, so it is
+// obvious what is only local, only installed, or only in the repo.
+const AI_ITEMS_REPO = () => process.env.AI_ITEMS_REPO || sourceOf('ai_items', 'repo', 'webship/ai-agents');
+const AI_ITEMS_REF = () => process.env.AI_ITEMS_REF || sourceOf('ai_items', 'ref', 'main');
+// A prompt is the whole `claude …` launch command for a NEW session, so the only way
+// to use one is to start a session with it — the dashboard's New screen form, or the
+// CLI by hand. It is not a slash command, so nothing of a prompt's syncs into ~/.claude
+// or a project's .claude/. It keeps its INSTALL_TARGETS entry only so listClaudeItems
+// can still SHOW what a machine already has there.
+// AI Commands is the kind that DOES install: same destination, different shape.
+const NO_CLAUDE_SYNC = new Set(['ai-prompts']);
+
+// Where each kind sits IN THE REPO. Prompts are the one kind whose directory name
+// differs from the CLI's: webship/ai-agents keeps them at the top level, in
+// prompts/, beside the agents and skills they invoke.
+const AI_ITEMS_REPO_PATHS = { 'ai-agents': '.claude/agents', 'ai-skills': '.claude/skills',
+  'ai-commands': '.claude/commands', 'ai-prompts': 'prompts' };
+// Where each kind installs INSIDE A PROJECT — always the project's own .claude/,
+// which is what Claude Code reads there. Not the same map as above: a project's
+// prompts go to .claude/commands, never to a prompts/ directory of its own.
+const AI_ITEMS_PROJECT_PATHS = { 'ai-agents': '.claude/agents', 'ai-skills': '.claude/skills',
+  'ai-commands': '.claude/commands', 'ai-prompts': '.claude/commands' };
+
+// What ~/.claude currently has, by kind.
+function listClaudeItems(key) {
+  const dir = INSTALL_TARGETS[key];
+  if (!dir) return new Set();
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    if (key === 'ai-skills') {
+      return new Set(entries.filter((e) => e.isDirectory()
+        && fs.existsSync(path.join(dir, e.name, 'SKILL.md'))).map((e) => e.name));
+    }
+    return new Set(entries.filter((e) => e.isFile() && e.name.endsWith('.md')
+      && !['README.md', 'AGENTS.md', 'CLAUDE.md'].includes(e.name))
+      .map((e) => e.name.replace(/\.md$/, '')));
+  } catch (_) { return new Set(); }
+}
+
+// Blob shas for every shared item, grouped by name, from the ONE cached recursive
+// Trees call repo-blobs makes per repo@ref — the same identity git itself uses, so
+// comparing them against locally computed blob shas answers "does the repo's copy
+// differ from this folder's?" without fetching a single file body. `null` means
+// the repo was unreachable (an unauthenticated container), which the UI states
+// rather than implying the repo has nothing.
+async function repoItemBlobs(key) {
+  if (!AI_ITEMS_REPO_PATHS[key]) return null;
+  const tree = await repoTree(AI_ITEMS_REPO(), AI_ITEMS_REF());
+  if (!tree) return null;
+  const prefix = `${AI_ITEMS_REPO_PATHS[key]}/`;
+  const map = new Map(); // item name -> Map<path-inside-item, blob sha>
+  for (const [p, sha] of tree) {
+    if (!p.startsWith(prefix)) continue;
+    const rest = p.slice(prefix.length);
+    let name; let inner;
+    if (key === 'ai-skills') {
+      const slash = rest.indexOf('/');
+      if (slash < 1) continue;
+      name = rest.slice(0, slash);
+      inner = rest.slice(slash + 1);
+    } else {
+      if (!rest.endsWith('.md') || rest.includes('/')) continue;
+      name = rest.slice(0, -3);
+      inner = '';
+    }
+    if (['README', 'AGENTS', 'CLAUDE', 'RULES'].includes(name)) continue;
+    if (!map.has(name)) map.set(name, new Map());
+    map.get(name).set(inner, sha);
+  }
+  return map;
+}
+
+// The names alone — the same tree, so a page listing names AND comparing blobs
+// still costs one network call, not two.
+async function listRepoItems(key) {
+  const blobs = await repoItemBlobs(key);
+  return blobs === null ? null : new Set(blobs.keys());
+}
+
+// Does the repo's copy of one item differ from this folder's? null = not comparable
+// (not in the repo, or the tree was unreachable).
+function repoDiffers(key, name, repoBlobs) {
+  if (!repoBlobs || !repoBlobs.has(name)) return null;
+  const theirs = repoBlobs.get(name);
+  const dir = workspaceDir(key);
+  try {
+    if (key !== 'ai-skills') {
+      return theirs.get('') !== gitBlobSha(path.join(dir, `${name}.md`));
+    }
+    // A skill is a directory: same files with the same blob shas, or it differs.
+    const base = path.join(dir, name);
+    const mine = new Map();
+    const walk = (d, rel) => {
+      for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+        if (e.name === '.git') continue;
+        const full = path.join(d, e.name);
+        const r = rel ? `${rel}/${e.name}` : e.name;
+        if (e.isDirectory()) walk(full, r);
+        else if (e.isFile()) mine.set(r, gitBlobSha(full));
+      }
+    };
+    walk(base, '');
+    if (mine.size !== theirs.size) return true;
+    for (const [rel, sha] of theirs) if (mine.get(rel) !== sha) return true;
+    return false;
+  } catch (_) {
+    return null;
+  }
+}
+
+const ITEM_TEMPLATES = {
+  agents: (name) => `---
+name: ${name}
+description: Use this agent to <when to invoke it>.
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+---
+
+# ${name}
+
+You are the specialist agent for <what this agent does>.
+
+## Instructions
+
+- <how to work>
+`,
+  skills: (name) => `---
+name: ${name}
+description: <what this skill does and when to use it>
+---
+
+# ${name}
+
+## Instructions
+
+- <steps the skill follows>
+`,
+  prompts: (name) => `<Write the reusable prompt here — installing it makes it available in Claude Code as /${name}>
+`,
+  docs: (name) => `# ${name}
+
+<Write the document here — Markdown; use "Make PDF" to render a PDF next to it.>
+`,
+};
+
+// The file that holds an item's content, given its display name.
+function itemFile(key, name) {
+  const dir = workspaceDir(key);
+  if (key === 'ai-skills') return path.join(dir, name, 'SKILL.md');
+  return path.join(dir, `${name}.md`);
+}
+
+// Where an install can land besides the global ~/.claude: any real project, so a session started
+// under it (and only there) sees the item. Site workspaces only — a "project" in `docs/` or
+// `agents/` itself would be another item, not something Claude Code scopes to.
+function installTargetWorkspaces() {
+  return Object.values(loadWorkspaces()).filter((w) => w.kind !== 'files');
+}
+
+// Every write toward the repo or the folders makes the cached tree stale.
+function invalidateRepoCaches() {
+  invalidateRepoTree(AI_ITEMS_REPO());
+}
+
+module.exports = {
+  INSTALL_TARGETS, NO_CLAUDE_SYNC, AI_ITEMS_REPO, AI_ITEMS_REF, AI_ITEMS_REPO_PATHS, AI_ITEMS_PROJECT_PATHS,
+  listClaudeItems, listRepoItems, repoItemBlobs, gitBlobSha, repoDiffers,
+  ITEM_TEMPLATES, itemFile, installTargetWorkspaces, invalidateRepoCaches,
+};

package/assistant-cast.js

@@ -0,0 +1,176 @@
+/**
+ * Who the assistant's avatar can be, and which voices it can speak in.
+ *
+ * Avatars. Only the ones named in settings.yml `assistant.avatars:` are offered, so a machine shows
+ * what its owner chose and nothing else. `druplicon` ships with the dashboard; any other name is looked
+ * up in the avatars workspace (`<root>/avatars/<project>/`): a character file there
+ * (`characters/<name>.json` or `characters/osa-<name>.json`) gives its model, display name and credit,
+ * and a bare model (`public/models/<name>.vrm`) is enough on its own. The models stay where they are and
+ * are served from there, never copied into this repository: their licences are their own, and some
+ * (fan-made ones) are for personal use only.
+ *
+ * Voices. Besides the browser's own voices, the ElevenLabs voices of the account in settings.yml
+ * `elevenlabs:`, once a real key is there. Listing them is free; speaking with one spends credits, which
+ * is why it happens only when someone picks an ElevenLabs voice. The key never leaves this server: the
+ * page posts the words and gets the audio back. What was spoken is kept in `.voice-cache/`, so a
+ * sentence heard again costs nothing.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_MODEL = 'eleven_multilingual_v2';
+const CACHE_DIR = path.join(__dirname, '.voice-cache');
+const CACHE_MAX = 400;
+const MAX_TEXT = 600;
+const BASES = {
+  us: 'https://api.us.elevenlabs.io',
+  eu: 'https://api.eu.residency.elevenlabs.io',
+  in: 'https://api.in.residency.elevenlabs.io',
+  sg: 'https://api.sg.residency.elevenlabs.io',
+};
+
+const NAME_RE = /^[a-z0-9][a-z0-9_-]{0,62}$/;
+// The avatars that ship with the dashboard, in public/avatar/.
+const BUILT_IN = {
+  druplicon: { name: 'Druplicon', model: '/avatar/druplicon.vrm',
+    credit: 'Druplicon, the Drupal drop, built in code. Druplicon is licensed under the GPL; Drupal is a registered trademark of Dries Buytaert.' },
+};
+const titleOf = (id) => id.replace(/^osa-/, '').split(/[-_]/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join(' ');
+
+/** The set of moves an avatar does beyond the shared ones (public/assistant-avatar-moves.js), or ''. */
+const moveSetOf = (id) => (/^labiba/.test(String(id || '')) ? 'labiba' : '');
+
+/** The hair colour an avatar starts with (settings.yml assistant.avatar_hair.<id>), as #rrggbb, or ''. */
+function hairOf(settings, id) {
+  const v = String(((settings.assistant || {}).avatar_hair || {})[id] || '').trim().replace(/^['"]|['"]$/g, '');
+  return /^#[0-9a-f]{6}$/i.test(v) ? v.toLowerCase() : '';
+}
+
+/**
+ * The Claude Code agent an avatar brings (settings.yml assistant.avatar_agents.<id>), when it is
+ * installed for this user; '' keeps the assistant's own agent.
+ */
+function agentOf(settings, id, home = process.env.HOME || '') {
+  const name = String(((settings.assistant || {}).avatar_agents || {})[id] || '').trim();
+  return /^[a-z0-9][a-z0-9-]{0,62}$/.test(name) && fs.existsSync(path.join(home, '.claude', 'agents', `${name}.md`)) ? name : '';
+}
+
+/** The avatars settings.yml names, with what the page needs to show each one. Unknown names are left out. */
+function avatarCast(settings = {}, root = '') {
+  const a = settings.assistant || {};
+  const named = Array.isArray(a.avatars) && a.avatars.length ? a.avatars : ['druplicon'];
+  const out = [];
+  for (const raw of named) {
+    const id = String(raw || '').trim().toLowerCase();
+    if (!NAME_RE.test(id) || id === 'none' || out.some((x) => x.id === id)) continue;
+    const more = { moves: moveSetOf(id), hair: hairOf(settings, id) };
+    // The model's link carries its file's time, so a rebuilt model is fetched at once rather than after
+    // the hour a browser may keep it.
+    if (BUILT_IN[id]) { out.push({ id, ...BUILT_IN[id], model: `${BUILT_IN[id].model}?v=${stamp(path.join(__dirname, 'public', BUILT_IN[id].model))}`, ...more }); continue; }
+    const found = findAvatar(id, root);
+    if (found) out.push({ id, name: found.name, model: `/avatar/model/${id}.vrm?v=${stamp(found.file)}`, credit: found.credit, ...more });
+  }
+  return out;
+}
+
+const stamp = (file) => { try { return Math.round(fs.statSync(file).mtimeMs).toString(36); } catch (_) { return '0'; } };
+
+/** The model file of an avatar, inside `<root>/avatars`, or null. */
+function findAvatar(id, root) {
+  if (!NAME_RE.test(id) || !root) return null;
+  const base = path.join(root, 'avatars');
+  let projects = [];
+  try { projects = fs.readdirSync(base, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith('.')).map((e) => e.name).sort(); } catch (_) { return null; }
+  const inside = (file) => {
+    try {
+      const real = fs.realpathSync(file);
+      return real.startsWith(fs.realpathSync(base) + path.sep) && /\.vrm$/i.test(real) && fs.statSync(real).isFile() ? real : null;
+    } catch (_) { return null; }
+  };
+  for (const p of projects) {
+    for (const stem of [id, `osa-${id}`]) {
+      let c = null;
+      try { c = JSON.parse(fs.readFileSync(path.join(base, p, 'characters', `${stem}.json`), 'utf8')); } catch (_) { continue; }
+      const rel = String((c && c.model) || '').replace(/^\/+/, '');
+      if (!/^models\/[\w.-]+\.vrm$/i.test(rel)) continue;
+      const file = inside(path.join(base, p, 'public', rel));
+      if (file) return { file, name: String(c.name || titleOf(id)).slice(0, 40), credit: String(c.credit || '').slice(0, 400) };
+    }
+  }
+  for (const p of projects) {
+    for (const stem of [id, `osa-${id}`]) {
+      const file = inside(path.join(base, p, 'public', 'models', `${stem}.vrm`));
+      if (file) return { file, name: titleOf(id), credit: `From the ${p} avatar project; its README states the model's licence.` };
+    }
+  }
+  return null;
+}
+
+/** GET /avatar/model/<id>.vrm: only a model of an avatar settings.yml names. */
+function serveAvatarModel(res, id, settings, root) {
+  const listed = avatarCast(settings, root).some((a) => a.id === id && !BUILT_IN[a.id]);
+  const found = listed ? findAvatar(id, root) : null;
+  if (!found) { res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' }); return res.end('No such avatar.'); }
+  res.writeHead(200, { 'Content-Type': 'model/gltf-binary', 'Cache-Control': 'private, max-age=3600', 'X-Content-Type-Options': 'nosniff' });
+  fs.createReadStream(found.file).pipe(res);
+}
+
+// ---- ElevenLabs ----------------------------------------------------------------------------------
+
+/** The account's key from settings.yml, or '' while it is a placeholder or missing. */
+function elevenKey(settings = {}) {
+  const k = String((settings.elevenlabs && settings.elevenlabs.api_key) || '').trim();
+  return /^[A-Za-z0-9_.-]{20,}$/.test(k) && !/change/i.test(k) ? k : '';
+}
+const elevenBase = (settings = {}) => process.env.ELEVENLABS_API_BASE
+  || BASES[String((settings.elevenlabs && settings.elevenlabs.region) || '').toLowerCase()] || 'https://api.elevenlabs.io';
+
+let voicesMemo = { at: 0, sig: '', list: null };
+
+/** The account's voices, `{ id, name, label }`, kept ten minutes. Free: it lists, it does not speak. */
+async function elevenVoices(settings = {}, { fetchImpl = fetch } = {}) {
+  const key = elevenKey(settings);
+  if (!key) return { connected: false, voices: [] };
+  const sig = crypto.createHash('sha256').update(key + elevenBase(settings)).digest('hex');
+  if (voicesMemo.sig === sig && voicesMemo.list && Date.now() - voicesMemo.at < 600000) return { connected: true, voices: voicesMemo.list };
+  const r = await fetchImpl(`${elevenBase(settings)}/v2/voices?page_size=100`, { headers: { 'xi-api-key': key }, signal: AbortSignal.timeout(10000) });
+  if (!r.ok) return { connected: true, voices: [], error: r.status === 401 ? 'ElevenLabs rejected the key.' : `ElevenLabs answered ${r.status}.` };
+  const body = await r.json();
+  const list = (body.voices || []).filter((v) => /^[A-Za-z0-9]{16,32}$/.test(String(v.voice_id || ''))).map((v) => {
+    const l = v.labels || {};
+    return { id: v.voice_id, name: String(v.name || v.voice_id).slice(0, 60), label: [l.accent, l.gender, l.age].filter(Boolean).join(', ').slice(0, 60) };
+  });
+  voicesMemo = { at: Date.now(), sig, list };
+  return { connected: true, voices: list };
+}
+
+/** The audio of `text` in an ElevenLabs voice, as an mp3 Buffer; from the cache when it was spoken before. */
+async function elevenSpeak(settings = {}, { voice, text }, { fetchImpl = fetch, cacheDir = CACHE_DIR } = {}) {
+  const key = elevenKey(settings);
+  if (!key) throw Object.assign(new Error('ElevenLabs is not connected.'), { status: 409 });
+  const id = String(voice || '');
+  const words = String(text || '').replace(/\s+/g, ' ').trim().slice(0, MAX_TEXT);
+  if (!/^[A-Za-z0-9]{16,32}$/.test(id) || !words) throw Object.assign(new Error('A voice and some words, please.'), { status: 400 });
+  const model = String((settings.elevenlabs && (settings.elevenlabs.model_id || settings.elevenlabs.model)) || DEFAULT_MODEL).replace(/[^\w.-]/g, '') || DEFAULT_MODEL;
+  const file = path.join(cacheDir, `${crypto.createHash('sha256').update(`${id}\n${model}\n${words}`).digest('hex')}.mp3`);
+  try { return fs.readFileSync(file); } catch (_) { /* not spoken yet */ }
+  const r = await fetchImpl(`${elevenBase(settings)}/v1/text-to-speech/${id}?output_format=mp3_44100_128`, {
+    method: 'POST', signal: AbortSignal.timeout(30000),
+    headers: { 'xi-api-key': key, 'Content-Type': 'application/json', Accept: 'audio/mpeg' },
+    body: JSON.stringify({ text: words, model_id: model }),
+  });
+  if (!r.ok) throw Object.assign(new Error(r.status === 401 ? 'ElevenLabs rejected the key.' : `ElevenLabs answered ${r.status}.`), { status: 502 });
+  const audio = Buffer.from(await r.arrayBuffer());
+  try {
+    fs.mkdirSync(cacheDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, audio, { mode: 0o600 });
+    const kept = fs.readdirSync(cacheDir).filter((f) => f.endsWith('.mp3'))
+      .map((f) => ({ f, t: fs.statSync(path.join(cacheDir, f)).mtimeMs })).sort((a, b) => b.t - a.t);
+    for (const old of kept.slice(CACHE_MAX)) fs.unlinkSync(path.join(cacheDir, old.f));
+  } catch (_) { /* spoken, just not kept */ }
+  return audio;
+}
+
+module.exports = { BUILT_IN, avatarCast, moveSetOf, hairOf, agentOf, findAvatar, serveAvatarModel, elevenKey, elevenVoices, elevenSpeak };

package/assistant-suggestions.js

@@ -0,0 +1,91 @@
+// Suggested prompts for an empty assistant conversation, made from each workspace's own noun and
+// actions. A workspace can replace them with `assistant: suggestions:`; an empty list turns them off.
+
+const MAX_SUGGESTIONS = 5;
+const MAX_LENGTH = 120;
+
+const an = (noun) => (/^[aeiou]/i.test(noun) ? 'an' : 'a');
+
+// null = not given (use the defaults), [] = none.
+function cleanSuggestions(list) {
+  if (!Array.isArray(list)) return null;
+  const seen = new Set();
+  const out = [];
+  for (const item of list) {
+    if (typeof item !== 'string') continue;
+    const text = item.replace(/\s+/g, ' ').trim().slice(0, MAX_LENGTH);
+    if (!text || seen.has(text.toLowerCase())) continue;
+    seen.add(text.toLowerCase());
+    out.push(text);
+    if (out.length >= MAX_SUGGESTIONS) break;
+  }
+  return out;
+}
+
+const HOME = [
+  'What can this dashboard do?',
+  'Which workspaces have something running right now?',
+  'Where do I start on a new machine?',
+  'How do I build a new project?',
+];
+
+const SETTINGS = [
+  'What can I change on this page?',
+  'What does each setting here control?',
+  'Which of these settings matter most on a new machine?',
+];
+
+const COMMANDS = [
+  'What can I run from here?',
+  'How do I add a command of my own?',
+  'Which commands act on a project, and which on a whole workspace?',
+];
+
+function defaultSuggestions(context, meta) {
+  const ctx = String(context || 'home');
+  if (ctx === 'settings') return SETTINGS;
+  if (ctx === 'commands') return COMMANDS;
+  if (!meta) return HOME;
+
+  const noun = meta.noun || 'item';
+  const plural = meta.nounPlural || `${noun}s`;
+  const can = (action) => !!(meta.typeActions && meta.typeActions.has && meta.typeActions.has(action));
+
+  if (/^backups:/.test(ctx)) {
+    return [
+      `What backups are there for these ${plural}?`,
+      `How do I restore ${an(noun)} ${noun} from a backup?`,
+      `Which ${plural} have no backup yet?`,
+      `How do I back up ${an(noun)} ${noun} before I change it?`,
+    ];
+  }
+
+  if (meta.kind === 'files') {
+    return [
+      `What ${plural} are here?`,
+      `Which ${plural} changed most recently?`,
+      `How do I add ${an(noun)} ${noun}?`,
+      `How do I edit ${an(noun)} ${noun}?`,
+    ];
+  }
+
+  // Only DDEV workspaces have anything "running"; a folder of git clones does not.
+  const out = can('ddev')
+    ? [`What ${plural} are here, and which are running?`]
+    : [`What ${plural} are here?`];
+  out.push(`Which ${plural} have a screen or an agent running?`);
+  if (can('build')) out.push(`How do I build a new ${noun} here?`);
+  if (can('backup') && can('ddev')) out.push(`How do I back up and restore ${an(noun)} ${noun}?`);
+  if (!can('ddev')) out.push(`Which ${plural} have changes that are not committed yet?`);
+  if (can('tests')) out.push(`How do I run the tests on ${an(noun)} ${noun}?`);
+  else if (can('clone')) out.push(`How do I clone ${an(noun)} ${noun}?`);
+  return out;
+}
+
+// The workspace's own list, else settings.yml's, else the defaults.
+function suggestionsFor({ context, meta, own, global }) {
+  const chosen = cleanSuggestions(own) || cleanSuggestions(global);
+  return (chosen || defaultSuggestions(context, meta)).slice(0, MAX_SUGGESTIONS);
+}
+
+module.exports = { suggestionsFor, defaultSuggestions, cleanSuggestions, MAX_SUGGESTIONS, MAX_LENGTH };